Skip to content

Gradle Plugin reference↑

The SandboxAQ Gradle Plugin automates testing using the Java Tracer and uploads the resulting traces to AQtive Guard to generate a report.

Compatibility↑

The Gradle Plugin requires Java 8 or higher, and Gradle 5.6.3 or higher.

Usage↑

Gradle Plugin getting started explains how to use the Gradle Plugin.

Configuration↑

  • apiKey: (required) API Key used to authenticate with AQtive Guard.
  • apiUrl: (required) URL of the AQtive Guard platform. Should follow the form https://<hostname>.
  • appname: Set the appname value in the trace header. This is used in AQtive Guard to identify the application that was traced.
  • compress: Passed to the Java tracer. See Java Tracer Reference.
  • ignoreUpdate: Passed to the Java tracer. See Java Tracer Reference.
  • out: Passed to the Java tracer. See Java Tracer Reference.
  • profileId: (required) ID of the profile to apply to the analysis. See Find the profile ID.
  • projectId: (required) ID of the project where trace should be included. See Find the project ID.
  • trace: Passed to the Java tracer. See Java Tracer Reference.

Note

The API Key provided by AQtive Guard is unique to each user and should be treated as sensitive information. We recommend not checking this value into your codebase and securely storing it using your CI server.

For instructions on providing the API Key value to your test runners when using Jenkins, refer to Using environment variables in the Jenkins User Handbook. Consult the corresponding user guides for documentation on GitLab CI/CD variables and Travis CI Environment Variables.

How it works↑

The Gradle Plugin passes the following arguments to the Java Virtual Machine (JVM) running the application:

  • -javaagent:$agentJarPath: where $agentJarPath points to the SandboxAQ Java Tracer agent.
  • -Xbootclasspath/a:$bootClassPathDep: where $bootClassPathDep points to dependencies of the plugin and agent.
  • -Dcryptosense.agent.$config=$value: where $config and $value are the configuration keys specific to the Java Tracer.

These arguments initiate the Java Tracer, which generates a trace for the application. When complete, the Gradle Plugin uploads the trace file to AQtive Guard using the GraphQL API, which in turn triggers an analysis.

Output↑

Results of the tracer will be temporarily stored in $outDirPath/test-$num, with an increasing $num value for each time the application is run, before being uploaded to AQtive Guard.

Warning

The traces being written are not deleted automatically.

Trusted certificate limitation↑

There isn’t a method to designate a trusted certificate using a parameter.

If the server presents a self-signed certificate or a certificate signed by a custom CA, you must manually add the required certificate to the Java Runtime Environment (JRE) to establish trust to upload a trace.

Add the certificate using the following command:

Bash
"$JAVA_HOME"/bin/keytool \
    -import -noprompt \
    -keystore "$JAVA_HOME"/lib/security/cacerts \
    -storepass changeit \
    -alias custom-alias-foo \
    -file /path/to/cert_or_ca.pem

In this example:

  • $JAVA_HOME is the home path to your Java Development Kit (JDK).
  • keystore indicates the path to the keystore file.
  • storepass is the password for the keystore.
  • alias is the custom certificate name.
  • file is the path to the certificate file.

Note

Replace /lib with /jre/lib. for older JREs.