Maven Plugin reference🔗

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

Compatibility🔗

The Maven Plugin requires Java 8 or higher.

Usage🔗

Maven Plugin Getting started explains how to use the Maven Plugin.

Configuration🔗

• agentOutputDirectory: A directory to store the generated trace files. Note: Unless deleteTraceDirectoryBeforeTests is set to false, this directory will be removed at the start of each test run. When using the aggregate-report goal in a multi-module project, this MUST be left as the default value: "${project.build.directory}/cs-tracer"
• agentOutputPrefix: Common prefix used when generating trace files. This is used as the report name in AQtive Guard. Default: ${project.artifactId} (see Create an AQtive Guard build profile to set artifactId).
• agentPath: Path to the SandboxAQ Java Tracer agent.
• apiUrl: URL for the AQtive Guard platform. Default: "https://analyzer.cryptosense.com"
• deleteTraceDirectoryBeforeTests: If true, remove an existing trace directory (and all contents) when the plugin is run. Default: true.
• ensureTracesPresent: If true, ensures that the trace directory exists and is not empty. Default: false.
• failBuildOnInstanceSeverity: The minimum instance severity that will fail the build. Default: "low".
  • Possible values are:
    • passed: Fail the build if there are any instances passed or higher.
    • low: Fail the build if there are any instances low or higher.
    • medium: Fail the build if there are any instances medium or higher.
    • high: Fail the build if there are any high instances.
    • ignore: Do not fail the build for any instances.
• profileId: (required) Set the ID of the profile used for analysis.
• uploadPort: Use a custom port for trace streaming.
• uploadUseTls: Use a TLS socket when streaming the application trace. Default: false.

For instructions on providing the API Key value to your test runners when using Jenkins, refer to the section on 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 Maven Plugin passes the following arguments to the Java Virtual Machine (JVM) running the application:

• -javaagent:$agentPath
• -Dcryptosense.agent.prefix=$agentOutputPrefix
• -Dcryptosense.agent.out=$agentOutputDirectory

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.

If streaming is enabled, the following arguments are added:

• -Dcryptosense.agent.domain=$uploadDomain
• -Dcryptosense.agent.projectId=$projectId
• -Dcryptosense.agent.apiKey=$apiKey
• -Dcryptosense.agent.port=$uploadPort (if uploadPort is specified)
• -Dcryptosense.agent.tls=true (if uploadUseTls is specified)

Traces are streamed directly to AQtive Guard without first caching on the local disk. However, no analysis is triggered after the upload.

Trusted certificate limitation🔗

Currently, there’s no 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:

"$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.