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. 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 keys as Gradle properties to the gradle.properties file in your Gradle user home directory. If this file does not exist, create it.

    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__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: