Agent installation guide
This guide offers examples for using Contrast Security’s Java agent with Docker. We encourage you to take this guide, make it your own, and distribute it to teams who both need to instrument Java applications and manage them through Docker.
The main portion of the guide details the most popular methods customers use to instrument Java applications contained in Docker and see security data in Contrast.
There is also a lab section that describes how to instrument a sample Java application called PetClinic. It’s a good way to learn before proceeding with your own applications. You can instrument PetClinic with Docker and see security data for this application in Contrast using the source code samples section at the end of this guide.
Update the application’s Dockerfile
Instrument your application
Before you begin, please be sure Contrast supports your preferred tools and environments for Java:
This guide assumes you have:
- Some familiarity with DevOps practices and how Docker works
- The information needed to connect the Contrast Java agent to the Contrast dashboard: https://docs.contrastsecurity.com/en/install-java-using-contrast.html
- Downloaded and started the Contrast Java agent before running your applications
Begin by updating the Dockerfile for your application.
1. Add the Contrast Java agent
Here are two options to add the Contrast agent and basic configuration to a Docker image. Choose the one that works best for you.
Option 1: Add to a base image
In this approach, agent updates will depend on the base image update. To do this:
- Add the Contrast agent and basic configuration to a Docker base image without enabling it
- Make one image change and Contrast is available to all applications using that base image
- Enable Contrast in the application’s Docker image or container
Base image Dockerfile configuration example:
COPY --from=contrast/agent-java:4 /contrast/contrast-agent.jar /opt/contrast/contrast.jar
This approach requires support for multi-stage builds, introduced in Docker Engine version 17.05
If you are using an older version, this alternative is available:
Base image Dockerfile configuration example:
ADD https://repo1.maven.org/maven2/com/contrastsecurity/contrast-agent/$CONTRAST_AGENT_VERSION/contrast-agent-$CONTRAST_AGENT_VERSION.jar /opt/contrast/contrast.jar
Change $CONTRAST_AGENT_VERSION to the Java agent version to download, i.e.:
/opt/contrast location is recommended for Contrast agents and it can be modified. You can also change the URL to download agents from an internal repository, if you prefer.
You can pass the specific agent version of your choice during build time and download it from the Maven repository.
docker build --build-arg CONTRAST_AGENT_VERSION=<addVersionHere> -t image_with_contrast:tag .
LATEST may be used to always download the newest available version (recommended only if you are a Contrast SaaS user; if you are Enterprise on-premise (EOP), it's best to pin the agent version to match the latest available from your TeamServer)
Option 2: Add to an application image
This option gives your teams more flexibility to use any version of the Contrast agent and avoid automatic updates. To do this:
- Add the above ADD instruction directly to an application’s Docker image.
2. Configure the agent
There are different values you can use to configure Contrast agents. This is the order of precedence, and each level overrides the next: 1 is highest.
- Corporate rule (e.g., expired license overrides assess.enable)
- System property value
- Environment variable value
- YAML configuration file value
- Contrast UI value
- Default value
Order of precedence is explained more here:
We recommend a mixed approach:
- Keep the common configuration in the YAML file so it can be placed in the base image
- Use the Java system properties for application-specific configuration values
This approach keeps a core set of configurations in the YAML file. Here are a few examples of common configurations. You can modify these, as desired.
- Redirect logging to console output
- Proxy configuration, if any
- Performance tuning options to limit agent activity
To do this:
- Add a logging configuration
- Next, you create and copy the YAML file into the base image.
- Copy the edited YAML file into the base image Dockerfile
COPY WORKSPACE/contrast_security.yaml /opt/contrast/contrast_security.yaml
This allows additional options, per application. To set an application-specific configuration, use the Java system properties:
Application metadata: Specify application-specific metadata
Application name: Specify the application name reported to Contrast
Application session metadata: Send application details like build number, version, GIT hash, etc.
For more, see Contrast documentation: https://docs.contrastsecurity.com/en/session-metadata.html
Application group: Specify the application access group for this application during onboarding. NOTE: application access groups have to be created first in Contrast.
Server environment: specify in which environments the application is running. Valid values for this configuration are: Development, QA and Production.
3. Update JVM parameters to attach the agent
To attach any profiler to a Java application, you need to pass a -javaagent flag to the application. You do this by setting
JAVA_TOOL_OPTIONS environment variables.
You can pre-populate the Contrast common JVM parameters in a separate environment variable in the base image, so the application team can use it in
Base image Dockerfile
ENV CONTRAST_OPTS "-javaagent:/opt/contrast/contrast.jar \
Application image Dockerfile
ENV JAVA_TOOL_OPTIONS $CONTRAST_OPTS \
4. Instrument your application
For the agent to send data to Contrast, it needs an API URL and the agent credentials. To protect the agent credentials, you can utilize the Docker secret and pass them as environment variables during deployment time. Here is an example of the Docker run command:
docker run -e CONTRAST__API__URL=https://app.contrastsecurity.com -e CONTRAST__API__API_KEY=<value> -e CONTRAST__API__SERVICE_KEY=<value>
You can verify that Contrast is running by checking the container log. You should see messages like these:
2020-05-28 22:36:29,910 [main STDOUT] INFO - Copyright: 2019 Contrast Security, Inc
Source code example: PetClinic
Use the following GitHub repository to learn how first. It contains a lab that walks you through different ways to instrument Java applications delivered with Docker for security monitoring with Contrast.
- How much will the Contrast Java agent affect performance for my applications?
- Is there any impact on application startup when running with Java?
- How do I fix SSL connection errors I see in the Contrast log?
- Will a new version of an agent work with an older version of Contrast? Or vice-versa?
It may work, but it is not recommended. Always update both.