Home

First of all

Ask yourself the following question:

Do I really need to use Java Serialization with user-supplied data?

As illustrated in this presentation, SerialKiller (and all other alternatives) are suboptimal mitigations. If you do need to deserialize untrusted data, keep reading.

Getting Started

Deploying SerialKiller is easy:

1. Download the latest version of the SerialKiller's Jar. Alternatively, it is also available on Maven Central

2. Import SerialKiller's Jar in your project

3. Replace all initializations of ObjectInputStream with SerialKiller

Before

ObjectInputStream ois = new ObjectInputStream(is);

After

ObjectInputStream ois = new SerialKiller(is, "/etc/serialkiller.conf");

4. Tune the configuration file, based on your application requirements

A step-by-step tutorial on how to whitelist classes

Whitelisting is the safest approach to protect your application. In this configuration, SerialKiller will allow approved classes only. While look-ahead whitelisting provides a robust protection to modern applications, it requires complete enumeration of all Java classes exchanged by the application.

The following step-by-step tutorial illustrates how to setup SerialKiller for profiling and whitelisting in blocking mode. This tutorial assumes that you've already configured your application to use SerialKiller.

1. Enable profiling with logging support using the following configuration in serialikiller.conf

  <mode>
    <profiling>true</profiling>
  </mode>
  <logging>
    <enabled>true</enabled>
    <logfile>/tmp/serialkiller.log</logfile>
  </logging>

If you've already started your application, you don't need to reboot to change the profiling mode. However, you do need to restart whenever you change the location of the logfile.

2. Use the application as you would normally do, making sure to exercise all possible functionalities. In this 'learning' phase, it is crucial to have client-server exchange all required Java classes. Since SerialKiller is not yet protecting your application, do not expose the service to untrusted environments.

3. When you're confident that you've collected enough data, run the following command line in your terminal

$ cat /tmp/serialkiller.log | grep "Whitelist match:" | cut -d"'" -f2 | sort -u

which should lead to a list of classes.

Eg.

deserializerserver.MyCustomPayload

java.lang.Integer

java.lang.String

4. Go back to SerialKiller's configuration file, and customize the following settings:

Enforce blocking mode by setting profile mode to false. Optionally, you can also turn off logging to avoid performance overhead.

  <mode>
    <profiling>false</profiling>
  </mode>
  <logging>
    <enabled>false</enabled>
  </logging>

In the whitelist section, define the classes observed during the learning phase.

For the example above, you would need to change your configuration from

  <whitelist>
    <regexp>.*</regexp>
  </whitelist>

to

  <whitelist>
    <regexp>deserializerserver\.MyCustomPayload$</regexp>
    <regexp>java\.lang\.Integer$</regexp>
    <regexp>java\.lang\.String$</regexp>
  </whitelist>

5. Once again, no need to restart (unless you've changed a logging option). Your application is now protected using SerialKiller in whitelisting mode. Please note that the user-defined whitelist is always applied after the built-in blacklist thus blacklisting takes precedence over whitelisting.