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.


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
  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
    4 actionable tasks: 3 executed, 1 up-to-date


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

  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__APPLICATION__NAME: "${}-how-to"
  10. Run the build again:

    ./gradlew clean build


    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.