Skip to main content

Install the Java agent in an existing Gradle project with Docker

This example uses a sample Gradle project, which includes the Application Plugin and the Docker Plugin to build a Java web application. It also runs JUnit 5 integration tests that verify the web application's behavior. As part of the process, you will include Contrast in the Docker image used for testing so that Contrast Assess analyzes your code during integration testing. See an example of a Gradle project in our Github repo.

Note

Any part of the following procedures that refer to any form of packaging or distribution are meant for your organization's internal use. Do not distribute Contrast with your application or Docker container outside of your organization. See Contrast's Terms of Service agreement for more information.

To add the Contrast Java agent to an existing Gradle project with Docker:

  1. Open a command prompt, and run the following command to clone Contrast's examples repository:

    $ git clone https://github.com/Contrast-Security-OSS/contrast-java-examples.git

  2. Enter the gradle-docker directory:

    $ cd contrast-java-examples/gradle-docker

  3. Run a test build to make sure everything is working:

    $ ./gradlew build

BUILD SUCCESSFUL in 3s
4 actionable tasks: 3 executed, 1 up-to-date

    Note

    On Windows, run gradlew.bat build instead.

  4. If the test build doesn't work, check to make sure you have Java 11 correctly installed (Java 11 or later is required to build the sample application. Java supported technologies lists the versions of Java supported that the Contrast Java agent supports):

    $ java -version
openjdk version "11.0.18" 2023-01-17
OpenJDK Runtime Environment Temurin-11.0.18+10 (build 11.0.18+10)
OpenJDK 64-Bit Server VM Temurin-11.0.18+10 (build 11.0.18+10, mixed mode)

  5. If you've made changes, run the build again. If it still doesn't work, open an issue that explains the problem.

  6. Use the agent keys to configure the agent's communication with Contrast. In most cases, you'll use this key:

    • Agent Token: This variable is a base64 encoded JSON object containing the url, api_key, service_key, and user_name configuration settings, allowing you to set them set in a single variable.

      Legacy settings: For older agents, you'll need these keys:

      • Contrast URL: This URL, https://app.contrastsecurity.com/Contrast or the URL of your on-premises or private cloud instance.

      • Organization API key

      • Agent username

      • Agent service key

  7. Add the key as Gradle properties to the gradle.properties file in your Gradle user home directory. If this file does not exist, create it.

    contrastToken=<contrast_api_token>

    Legacy settings: If you are using an older agent version, add these keys to the gradle.properties file.

    Be sure to replace <contrast_url>, <your_api_key>, <agent_user_name> and <agent_user_service_key> with the Contrast URL, API key, username and service key values you obtained from the Contrast:

    contrastUrl=<contrast_url>
contrastAgentUserName=<agent_user_name>
contrastAgentServiceKey=<agent_user_service_key>
contrastApiKey=<your_api_key>

  8. Add the Contrast agent and configure the application to use it by modifying the createDockerfile task in build.gradle:

    task createDockerfile(type: Dockerfile) {
  // ... rest of block omitted

  copyFile(new Dockerfile.CopyFile("/contrast/contrast-agent.jar", "/contrast.jar").withStage("contrast/agent-java:latest"))
  environmentVariable("JAVA_TOOL_OPTIONS", "-javaagent:/contrast.jar")
}

  9. Pass the configuration variables into the container by adding the following commands to the createContainer task in build.gradle:

    task createContainer(type: DockerCreateContainer) {
    // ... rest of the config omitted

    envVars = [
        CONTRAST__API__TOKEN: project.property("contrastToken"),
        CONTRAST__APPLICATION__NAME: "${project.name}-how-to"
    ]
}

    If your agent configuration refers to both the legacy settings and the agent token, (in environment variables or the YAML file), the legacy settings take precedence. To use just the agent token value, make sure you remove references to the legacy settings

    Legacy settings: If you are using an older agent version, add the following commands:

    task createContainer(type: DockerCreateContainer) {
    // ... rest of the config omitted

    envVars = [
        CONTRAST__API__URL: project.property("contrastUrl"),
        CONTRAST__API__USER_NAME: project.property("contrastAgentUserName"),
        CONTRAST__API__SERVICE_KEY: project.property("contrastAgentServiceKey"),
        CONTRAST__API__API_KEY: project.property("contrastApiKey"),
        CONTRAST__APPLICATION__NAME: "${project.name}-how-to"
    ]
}

  10. Run the build again:

    ./gradlew clean build

    Note

    On Windows, run gradlew.bat clean build instead.

    The Docker container now runs the application with Contrast enabled. When the integration test runs, it detects the vulnerable endpoint and reports it to Contrast. To see the vulnerability report, log in to the Contrast web interface, navigate to the Vulnerabilities list and filter your view by the application name gradle-application-how-to.

In this section: