Warning

Matilda is a prototype. Please report any issues and be mindful when using it in production.

Matilda

Matilda provides sandboxing capabilities at runtime for the JVM. It is a lightweight alternative to the soon to be deprecated Java Security Manager. You can granuallary block modules from executing System.exit(), System.exec() and Network connections like Socket.open.

Installation

Matilda uses the Class File API which is a preview feature in JDK 23, in order to run your application with Matilda you need to enable preview.. To use Matilda download the MatildaAgent.jar and the MatildaBootstrap.jar from the repository.

Usage

Matilda can be used via the CLI or by configuring the projects build file accordingly.

CLI Quickstart

Matilda uses the ClassFile API which is a preview feature in JDK 23, in order to run your application with Matilda you need to enable preview.

--enable-preview

Hook the MatildaAgent into your application

-javaagent:/path/to/matilda-agent-<version>.jar

Add the MatildaAcceControl to the bootpath. This is needed due to the class loading hirachy. Classes manipulated by the MatildaAgent reference to the MatildaAccessControl.

-Dmatilda.bootstrap.jar=/path/to/matilda-bootstrap-<version>.jar"

Note that Matilda works with a whitelisting approach. With enabling the MatildaAgent, all calls to the above mentioned methods will be blocked by default.

For gradle examples refer to the Log4Shell example

Configuration

Matilda comes with a module-based whitelisting approach, permission can be set per module and are enforced accordingly. If your projects does not use modules consider to change it, it is not only needed to use Matilda but also recommenede by the Secure Coding Guidelines for Java SE. If you want to understand what modules are and aren't better read this Blogpost by Ron Pressler.

Configuration can also be done via the CLI or build file following the naming scheme:

-Dmatilda.runtime.exit.allow=module <insert module name here>
-Dmatilda.system.exec.allow=module <insert module name here>
-Dmatilda.network.connect.allow=module <insert module name here>

POC Log4Shell

Matilda is a tool that can be used to to reduce the impact of supply chain attacks by setting granular permissions for each module. As an example a proof of concept for Log4Shell can be found in the Log4Shell_POC.

In order to test just clone this repository and run it with gradle

To run it with the MatildaAgent use the following gradle command, the build should be successful and return " Matilda has successfully blocked log4shell"

gradle run

To test the exploitable version run the following gradle command. The build should fail and return "LogForShell was not blocked by matilda"

gradle runNoAgent

Configuration Example - tomcat

In order to run apache tomcat with Matilda just export CATALINA_OPTS with the following configuration.

export CATALINA_OPTS="--enable-preview -javaagent:./path/matilda-agent-<version>.jar -Dmatilda.bootstrap.jar=./path/matilda-bootstrap-<version>.jar"