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↑
Refer to Maven Plugin Getting started for information on using the Maven Plugin.
Configuration↑
agentOutputDirectory
: A directory to store the generated trace files. Note: UnlessdeleteTraceDirectoryBeforeTests
is set tofalse
, 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 setartifactId
).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.
- Possible values are:
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
.
Note
The API Key provided by AQtive Guard is unique to each user and should be treated as sensitive information. Avoid checking this value into your codebase. Instead, consider securely storing the API Key using your CI server.
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 Maven Plugin uploads the trace file to AQtive Guard using the GraphQL API, which then 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
(ifuploadPort
is specified)-Dcryptosense.agent.tls=true
(ifuploadUseTls
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↑
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:
"$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.