Install the Java agent in an existing Maven project

These instructions use an existing Maven project and reuse the project's existing integration tests to find vulnerabilities. This includes guided changes to an example servlet project. A completed version of the project exists in a GitHub branch.

Before you start:

To install the Java agent in an existing Maven project:

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

    • Contrast URL

    • API key

    • Username

    • Service key

  2. 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).

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

  4. 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>
  5. 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.

    Tip

    You can configure the Contrast Java agent using a file, Java system properties or environment variables. Only put in the variables that are shared across multiple applications (for example, credentials and Contrast connection details). That way you can manage them in one place.

  6. 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.
  7. Make your working directory the root of the maven-cargo example:

    cd contrast-java-examples/maven-cargo
  8. 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] ------------------------------------------------------------------------

    Note

    On Windows, run mvnw.cmd clean verify instead.

  9. 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)
  10. 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.

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

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

    <contrast.version>3.6.3.8220</contrast.version>
  13. You can replace the version and build numbers with those from any Contrast Java agent released to Maven Central.

  14. 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>
  15. 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>
  16. Change the value of -Dcontrast.config.path to match the path to the configuration file you created in Step 2.

  17. 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] ------------------------------------------------------------------------

    Note

    On Windows, run mvnw.cmd clean verify instead.

    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.

Tip

To integrate Contrast further with your Maven build, check out the Contrast Maven Plugin. You can configure its verify goal to fail your Maven build when vulnerabilities are detected in your test run.