Install the Java agent in an existing Gradle project with Docker

Use the agent keys to configure the agent's communication with Contrast. You'll need these keys:

If you're using a Unix-like operating system, create a file for exporting the agent key values as Contrast environment variables.

Open a command prompt and run the following command. 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:

$ tee -a ~/.contrastrc > /dev/null
export CONTRAST__API__URL=<contrast_url>
export CONTRAST__API__API_KEY=<your_api_key>
export CONTRAST__API__USER_NAME=<agent_user_name>
export CONTRAST__API__SERVICE_KEY=<agent_user_service_key>

Press CTRL+D when you're finished typing all four lines of input to save the values to the $HOME/.contrastrc file.

Run the .contrastrc script in the current shell to export the variables to your environment:

$ . ~/.contrastrc

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

Enter the gradle-docker directory:

$ cd contrast-java-examples/gradle-docker

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

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've made changes, run the build again. If it still doesn't work, open an issue that explains the problem.

Add a dependency configuration and include a dependency on the Contrast Java agent:

configurations {
    contrastAgent
}

def contrast_version = "3.6.3.8220"

dependencies {
    // ... other dependencies omitted
    contrastAgent "com.contrastsecurity:contrast-agent:$<contrast_version>"
}

Add a task for copying the agent into a directory of the project:

task("copyAgent", type: Copy) {
    from configurations.contrastAgent
    into "$<projectDir>/lib"
}

run.dependsOn copyAgent
assemble.dependsOn copyAgent

Add the -javaagent property to the JVM arguments passed to the application by modifying the application block of build.gradle:

application {
  // ... rest of block omitted
  def agentBuildPath = "lib/contrast-agent-$<contrast_version>.jar"
  def agentProjectPath = Paths.get(getProjectDir().toURI()).resolve(agentBuildPath)


  applicationDefaultJvmArgs = [
          "-javaagent:$<agentProjectPath.toString()>"
  ]
}

Run the application:

$ ./gradlew run

The application will now start up with Contrast. If you do any manual testing, any security related findings are reported to Contrast. You can press CTRL+C to stop the application.

Configure the Distribution Plugin to include the Contrast agent JAR in the bundles created when you run gradle build. (The Distribution Plugin was included when you included the Application Plugin.)

application {

  // ... rest of application config omitted

  distributions {
    main {
      contents {
        from("$<projectDir>/lib") {
            into "lib"
        }
      }
    }
  }
}

The -javaagent points to a JAR file in your project directory, not the JAR file in the application bundle. To point to the correct JAR file, configure the startScripts task to use the correct path in the bundle.

application {

  // ... rest of application config omitted

  startScripts {
    doLast {
      def shFile = new File(getOutputDir(), project.name)
      shFile.text = shFile.text.replace(agentProjectPath.toString(), "\$APP_HOME/$<agentBuildPath>")
      def batFile = new File(getOutputDir(), "$<project.name>.bat")
      batFile.text = batFile.text.replace(agentProjectPath.toString(), "%APP_HOME%\\lib\\contrast-agent-$<contrast_version>.jar")
    }
  }
}

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: System.getenv("CONTRAST__API__URL"),
        CONTRAST__API__USER_NAME: System.getenv("CONTRAST__API__USER_NAME"),
        CONTRAST__API__SERVICE_KEY: System.getenv("CONTRAST__API__SERVICE_KEY"),
        CONTRAST__API__API_KEY: System.getenv("CONTRAST__API__API_KEY"),
        CONTRAST__APPLICATION__NAME: "${project.name}-how-to"
    ]
}

Run the build again:

./gradlew clean build

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, navigate to the Vulnerabilities grid, and filter your view by the application name gradle-docker-how-to.