Setting Java Agent options

During the connection setup of JVM web applications with CI Fuzz the Java Agent is included into the start command of the target application to be loaded by the application. The Java Agent instruments the application during the startup to be able to collect coverage information about the the executed Java byte code during the execution of the fuzz tests. The collected coverage information is subsequently send back to the CI Fuzz daemon to steer the input generation of the Fuzz Tests and the exploration of the code base.

Although the CI Fuzz Visual Code extension is generating a Java Agent Command which already contains the required parameters, there are other optional parameters available which could be necessary depending on the application setup.

The following shows an example of the startup of a Jar application with the inclusion of the CI Fuzz Java Agent:

java -javaagent:$HOME/bin/fuzzing_agent_deploy.jar=service_name=projects/example-9070daab/web_services/example -jar ./target/example.jar   

The CI Fuzz agent supports multiple parameters which are expected to be enumerated in a comma separated list, e.g.

javaagent:<SOME_PATH>fuzzing_agent_deploy.jar=param1=value1,param2=value2 ...

The CI Fuzz Java Agent supports the following parameters:

  • service_name - A name which should be unique to be distinguishable from other services e.g. service_name=projects/example-9070daab/web_services/example
    This is the only necessary parameter of the Java Agent. Usually it is automated generated by the Visual Studio Code Extension during the web service setup.
  • instrumentation_includes - A ":" separated list of package glob patterns to include in the instrumentation e.g. instrumentation_includes=com.google.**:com.example.**
    Only the feedback that is received for the specified package patterns will affect the fuzzing input generation and path discovery of the code.
  • instrumentation_excludes - A ":" separarted list of package glob patterns to exclude from instrumentation e.g. instrumentation_excludes=com.google.**:com.example.**
    There will be no feedback received for the specified classes during fuzzing.
  • fuzzing_server_host - The IP or hostname of the fuzzing server (default 127.0.0.1).
  • fuzzing_server_port - The port on which the fuzzing gRPC server is listening (default 6773)
  • tls - If the CI daemon has TLS enabled you can add enable it by setting to true (default false). This will encrypt the communication between CI daemon and fuzzing agent. The gRPC communication between fuzzer and fuzzing agent is still unencrypted.
  • cert_file -  The location of the TLS certificate of the CI Fuzz server. Only required if the cert is not signed by a public CA and the corresponding CA Root certificate is not imported on the host where the Java Agent is running.
  • api_token - A token for the authentication of the agent to the CI Daemon. This can be necessary in a CI/CD environment. You can generate token in the web interface of the CI Server for personal or organization usage.