Maven Plugin Installation Instructions

Before you begin

Please make sure that you have the following information available:

  • Your Cryptosense API Key
  • Your Cryptosense AWS Credentials
    • These should have been provided to you with these instructions
  • Your target project ID
    • 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
    • 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 7 builds from Java 7u111 and above 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.

If you want to do this, you should use a blank value instead of API KEY in the POM.xml snippets below, and then set it at runtime using the Maven command-line option -Dcryptosense.apiKey=API KEY.

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.

Method of Procedure

Install the Maven S3 Wagon

Install the Maven S3 wagon plugin using the instructions documented at https://github.com/seahen/maven-s3-wagon. A shortened version of them is below:

  1. Add the following to the build section of your POM.xml to install the wagon extension:

     <build>
       ...
       <extensions>
         ...
         <extension>
           <groupId>com.github.seahen</groupId>
           <artifactId>maven-s3-wagon</artifactId>
           <version>1.3.0</version>
         </extension>
         ...
       </extensions>
       ...
     </build>
    
  2. 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-maven-repo</id>
           <url>s3://cryptosense-maven/repository</url>
         </pluginRepository>
         ...
       </pluginRepositories>
       ...
     </project>
    
  3. Give the extension access to the provided AWS Credentials using one of the methods described in https://github.com/seahen/maven-s3-wagon#authentication (in a CI environment, it is likely to be easiest to use environment variables rather than modifying ~/.m2/settings)

Apply the Cryptosense Maven Plugin to your build

There are two options to apply the Cryptosense Maven plugin to your build:

  1. Create a new Maven build profile to apply the plugin on a selective basis
  2. Apply the plugin to the root build

We recommend option 1 for configurability, but if you know that you will want to apply the plugin on every build (including local builds), then option 2 may be simpler.

Option 1: Create a new Maven build profile

  1. Add the following to the profiles section of the project in your POM.xml:

     <project>
       ...
       <profiles>
         ...
         <profile>
           <id>cryptosense</id>
           <properties>
             <cryptosense.apiKey>API KEY</cryptosense.apiKey>
             <cryptosense.projectId>PROJECT ID</cryptosense.projectId>
             <cryptosense.profileId>PROFILE ID</cryptosense.profileId>
           </properties>
           <build>
             <plugins>
               <plugin>
                 <groupId>com.cryptosense</groupId>
                 <artifactId>cryptosense-maven-plugin</artifactId>
                 <version>0.2.0</version>
                 <configuration>
                   <apiKey>${cryptosense.apiKey}</apiKey>
                   <projectId>${cryptosense.projectId}</projectId>
                   <profileId>${cryptosense.profileId}</profileId>
                 </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>
    
  2. 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
    

Option 2: Apply the plugin to the root build

  1. Add the following to the properties and build sections of your POM.xml:

     <properties>
       ...
       <cryptosense.apiKey>API KEY</cryptosense.apiKey>
       <cryptosense.projectId>PROJECT ID</cryptosense.projectId>
       <cryptosense.profileId>PROFILE ID</cryptosense.profileId>
       ...
     </properties>
     ...
     <build>
       ...
       <plugins>
         ...
         <plugin>
           <groupId>com.cryptosense</groupId>
           <artifactId>cryptosense-maven-plugin</artifactId>
           <version>0.2.0</version>
           <configuration>
             <apiKey>${cryptosense.apiKey}</apiKey>
             <projectId>${cryptosense.projectId}</projectId>
             <profileId>${cryptosense.profileId}</profileId>
           </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>
    

Test the Plugin

To test the plugin, take the following steps:

  1. If you selected option 1 in the section above run mvn clean install -P cryptosense from the root of your codebase

    If you selected option 2 in the section above, run mvn clean install from the root of your codebase

  2. 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>
  <apiKey>${cryptosense.apiKey}</apiKey>
  <projectId>${cryptosense.projectId}</projectId>
  <profileId>${cryptosense.profileId}</profileId>
</configuration>

Try a Free 14-day Trial

Cryptosense Analyzer audits your applications and infrastructure to find vulnerabilities and understand your crypto landscape. Use it to optimise bug-fix resources and demonstrate compliance.