Install the Java agent in an existing Maven project

The Contrast agent requires some configuration to communicate with Contrast. Obtain the agent keys:

Create a Contrast configuration file and open it in your preferred text editor. The Contrast configuration file is a YAML file. Since it contains API credentials, create it in a location that only you have access to, like your home directory. Choose a file name that will make sense to you (for example, .contrast.yml).

Create the file and open it in your preferred text editor.

Paste in the following contents:

api:
  url: <contrast_url>
  api_key: <your_api_key>
  user_name: <agent_user_name>
  service_key: <agent_user_service_key>

Replace <contrast_url>, <your_api_key>, <agent_user_name> and <agent_user_service_key> with the Contrast URL, API key, username and service key, and save the file.

Open a command prompt, and run the following command to clone the examples repository:

$ git clone https://github.com/Contrast-Security-OSS/contrast-java-examples.git
Cloning into 'contrast-java-examples'...
remote: Enumerating objects: 12, done.
remote: Counting objects: 100% (12/12), done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 12 (delta 1), reused 9 (delta 1), pack-reused 0
Unpacking objects: 100% (12/12), done.

Make your working directory the root of the maven-cargo example:

cd contrast-java-examples/maven-cargo

Check to make sure everything starts off in a working state by running the integration test. The maven-cargo-plugin starts a Jetty server on port 8080, and the EchoServletIT integration test verifies the behavior of the EchoServlet by sending an HTTP request to the Jetty server. Finally, the maven-cargo-plugin shuts down the Jetty server.

$ ./mvnw clean verify
[INFO] Scanning for projects...
[INFO]
[INFO] ---------< com.contrastsecurity.examples:contrast-maven-cargo >---------
[INFO] Building Contrast Maven Cargo Example 1.0
[INFO] --------------------------------[ war ]---------------------------------
[INFO]
    ... omitting some output ...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.467 s
[INFO] Finished at: 2019-03-21T22:57:22-04:00
[INFO] ------------------------------------------------------------------------

If this doesn't work, check to make sure you have Java 8 correctly installed.

$ java -version
java version "1.8.0_131"
Java(TM) SE Runtime Environment (build 1.8.0_131-b11)
Java HotSpot(TM) 64-Bit Server VM (build 25.131-b11, mixed mode)

If you had to correct something about your Java installation, try running the tests again. If it still doesn't work, open an issue that explains the problem.

Use the Maven Dependency Plugin to download the agent into the project build directory.

Add the following to the properties element of the project POM (pom.xml):

<contrast.version>3.6.3.8220</contrast.version>

You can replace the version and build numbers with those from any Contrast Java agent released to Maven Central.

Then add the following to the build.plugins element of the project POM (pom.xml):

<plugin>
  <artifactId>maven-dependency-plugin</artifactId>
  <version>3.1.1</version>
  <executions>
    <execution>
      <phase>prepare-package</phase>
      <goals>
        <goal>copy</goal>
      </goals>
      <configuration>
        <artifactItems>
          <artifactItem>
            <groupId>com.contrastsecurity</groupId>
            <artifactId>contrast-agent</artifactId>
            <version>${contrast.version}</version>
          </artifactItem>
        </artifactItems>
        <stripVersion>true</stripVersion>
      </configuration>
    </execution>
  </executions>
</plugin>

Configure the existing Maven Cargo Plugin to include Contrast when starting Jetty. Copy the following configuration element to the start-app-before-IT execution:

<configuration>
  <configuration>
    <properties>
      <cargo.jvmargs>
        -javaagent:${project.build.directory}/dependency/contrast-agent.jar
        -Dcontrast.config.path=${user.home}/.contrast.yml
        -Dcontrast.agent.java.standalone_app_name=maven-cargo-how-to
       </cargo.jvmargs>
    </properties>
   </configuration>
</configuration>

Change the value of -Dcontrast.config.path to match the path to the configuration file you created in Step 2.

Now re-run the tests. When the application container initializes, you'll see output indicating that Contrast has started.

$ ./mvnw clean verify
[INFO] Scanning for projects...
[INFO]
[INFO] ---------< com.contrastsecurity.examples:contrast-maven-cargo >---------
[INFO] Building Contrast Maven Cargo Example 1.0
[INFO] --------------------------------[ war ]---------------------------------
[INFO]
    ... omitting some output ...
[INFO] [talledLocalContainer] [Contrast] Thu Mar 21 23:20:40 EDT 2019 Starting Contrast (build 3.6.2.BACKGROUND) Pat. 8,458,789 B2
    ... omitting more output...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  16.644 s
[INFO] Finished at: 2019-03-21T22:57:22-04:00
[INFO] ------------------------------------------------------------------------

During the integration test, the agent detects and reports the vulnerable servlet to Contrast. To see the vulnerability report, go to the Vulnerabilities grid in Contrast, and filter your view by the application name maven-cargo-how-to.