Onweer Java Instrumentation Agent

This repository contains the source code for the Onweer Java Instrumentation Agent. Its purpose is collecting coverage data, tracing requests and injecting faults, and communicating this information over a HTTP interface to an Onweer fuzzer.

Building

The agent JAR may be built locally using Maven:

$ mvn clean install

This will place a JAR file named onweer-agent-$VERSION.jar under onweer-agent/target, which may be used as a Java Agent.

For use with docker, it may be easier to build this project’s docker container, using either the build-and-tag.sh script or the following command:

$ docker build -t onweer-agent .

This will build the agent in a docker container and create an image called onweer-agent containing the JAR file at /jars/onweer-agent.jar, which may be imported into other Docker images with the following Docker command:

COPY --from=onweer-agent:latest /jars/onweer-agent.jar /onweer-agent.jar

Using

The agent may be added to a JVM by using the -javaagent command-line option:

$ java -javaagent:onweer-agent-0-SNAPSHOT.jar -jar aesma.jar

The agent will start a HTTP REST interface on port 43546. We recommend using Docker or similar to redirect the port if needed.

The agent’s REST API has the following endpoints:

/trace

Get the trace of all fault injection points as a list of fault injection point identifiers. Fetching the trace clears it.

/faults

• GET: Get the current list of faults which are still pending
• POST: Install a list of faults as a JSON object mapping fault injection point identifiers to a list of "BEFORE" and "AFTER". Replaces any currently pending faults.

/coverage

Return an integer representing this service’s current coverage level.

/coveragemax

Return the maximum possible value of the service’s coverage level.

/coverageclass

Return a JSON object mapping class names to their coverage level.

/reset

Reset the coverage data to 0.

/report

Download a JaCoCo coverage report.

Supported frameworks

These are the frameworks for which the agent supports fault injection and tracing. Coverage information should work for any Java application.

Framework	Class	Tracepoints	Faults
Spring Boot	SpringRestAdvice	All calls to Spring REST methods	Throw a SpringResourceAccessException before or after sending the request
Jakarta/TeaStore	JakartaTeaStoreAdvice	All calls into TeaStore’s communication middleware.	Throw a TeastoreLoadBalancerTimeoutException before or after sending the request
Jakarta/TeaStore	JakartaTeaStoreCoarseAdvice	All calls into TeaStore’s communication middleware, identified by target service instead of source code location.	Throw a TeastoreLoadBalancerTimeoutException on all requests to the specified service.

The JakartaTeastoreCoarseAdvice is disabled by default. If you wish to configure which advices are applied, you will have to comment or uncomment them in the source code and rebuild the agent.

Implementation notes

We vendor JaCoCo in our source tree in order to easily use private features of JaCoCo’s implementation for more effective coverage instrumentation.

Contact

Onweer was developed at the Vrije Universiteit Brussel as part of a research grant by the Research Foundation - Flanders (FWO), grant number 1SHFL24N. .

If you wish to contribute or collaborate, please contact Gilles Coremans <[email protected]> or Coen De Roover <[email protected]>