Maven Plugin Manual

Before you begin

Please make sure that you have the following information available:

Cryptosense API URL (optional)
- This URL should be https://analyzer.cryptosense.com if you use SaaS (this is the default), or something like https://cap-domain.example.net if you installed CAP on-premises.
Your Cryptosense API Key (required)
- This key can be found at https://analyzer.cryptosense.com/api.
Your target project ID (required)
- This can be found by navigating to the project in the analyzer GUI, and copying the ID from the URL bar.
Your target profile ID (required)
- This can be found by navigating to the profile in the analyzer GUI, and coping the ID from the URL bar.

Note: In order to securely upload traces, your Java distribution must include the IdenTrust root CA. This is available in all Java 8 builds from Java 8u101 and above. If this is not possible in your application, please contact support for guidance on manually installing the required certificates.

Note: The API Key provided by Cryptosense is unique on a per-user basis, and should be considered sensitive. Therefore you may want to avoid checking this value into your codebase, and instead make use of your CI server to securely store this variable.

For instructions of providing this value to your test runners when using Jenkins, please see these instructions. For GitLab CI, see here, and for Travis CI see here.

Installation

Extract the provided archive (e.g. cryptosense-maven-plugin-1.2.3.zip) and copy the extracted artifacts to a repository that Maven will be able access (e.g. standalone directory in the filesystem or internal Maven repository).

This archive only contains Cryptosense artifacts. Maven will need to download some external dependencies from a public, such as Maven Central, or a private repository (such as company-wide repository).

In the following section, we will assume that the Maven repository containing Cryptosense artifacts is available at /path/to/cryptosense/repository on the filesystem.

Configuration

Plugin repository

Add the following to the project section of your pom.xml to add the Cryptosense repository as a configured plugin repository:

<project>
  ...
  <pluginRepositories>
    ...
    <pluginRepository>
      <id>cryptosense-repository</id>
      <url>file://path/to/cryptosense/repository</url>
    </pluginRepository>
    ...
  </pluginRepositories>
  ...
</project>

Creating a Cryptosense build profile

The most flexible way to use the plugin consists in creating a build profile. Add the <profile> below to your pom.xml configuration:

<project>
  ...
  <profiles>
    ...
    <profile>
      <id>cryptosense</id>
      <build>
        <plugins>
          <plugin>
            <groupId>com.cryptosense</groupId>
            <artifactId>cryptosense-maven-plugin</artifactId>
            <version>MAVEN PLUGIN VERSION</version>  <!-- change this -->
            <configuration>
              <apiUrl>CAP API URL</apiUrl>  <!-- change this -->
              <apiKey>${env.CS_API_KEY}</apiKey>
              <projectId>CAP PROJECT ID</projectId>  <!-- change this -->
              <profileId>CAP PROFILE ID</profileId>  <!-- change this -->
            </configuration>
            <executions>
              <execution>
                <id>inject-agent</id>
                <goals>
                  <goal>inject-agent</goal>
                </goals>
              </execution>
              <execution>
                <id>generate-report</id>
                <goals>
                  <goal>generate-report</goal>
                </goals>
              </execution>
            </executions>
          </plugin>
        </plugins>
      </build>
    </profile>
    ...
  </profiles>
  ...
</project>

This code assumes that the API key will be provided as the CS_API_KEY environment variable.

Run tests with the plugin

When running your tests, add -P cryptosense to enable the profile. For example, a full test suite (with trace upload) can be run using the command:

mvn clean install -P cryptosense

This will run your tests with the Cryptosense Java Tracer attached and will upload the results to the project chosen in the previous section.

To make sure the plugin was used, check the output to see if the inject-agent and generate-report goals were triggered as part of the build.

Next steps

Customize the prefix used for traces and reports

In order to customize the prefix that is used by the Cryptosense java agent when generating trace files (and therefore the uploaded traces and reports), add the following to the configuration in your pom.xml:

<configuration>
  ...
  <agentOutputPrefix>myprefix</agentOutputPrefix>
</configuration>