Search

Java agent with Docker

  • Updated

Agent installation guide 

Overview

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.

 

Main steps

Update the application’s Dockerfile

  1. Add Contrast Java agent
  2. Configure the agent
  3. Update JVM parameters to attach the agent

Instrument your application

  1. Build the application image with Contrast enabled

Supported technologies

Before you begin, please be sure Contrast supports your preferred tools and environments for Java:
https://docs.contrastsecurity.com/en/java-supported-technologies.html 

 

This guide assumes you have:

 

Instructions

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:

FROM BASE_IMAGE
COPY --from=contrast/agent-java:latest /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 of Docker, this alternative is available:

Base image Dockerfile configuration example to download the latest:

FROM BASE_IMAGE
ADD https://download.java.contrastsecurity.com/latest /opt/contrast/contrast.jar

Base image Dockerfile configuration example to download the latest 5.x version:

FROM BASE_IMAGE
ADD https://download.java.contrastsecurity.com/5 /opt/contrast/contrast.jar

Or to download a specific version of the Java agent (you can see the available versions here on Docker Hub or on Quay.io):  

FROM BASE_IMAGE
ARG CONTRAST_AGENT_VERSION
ADD https://repo1.maven.org/maven2/com/contrastsecurity/contrast-agent/$CONTRAST_AGENT_VERSION/contrast-agent-$CONTRAST_AGENT_VERSION.jar /opt/contrast/contrast.jar


The target location of /opt/contrast is recommended for Contrast agents but it can be modified. You can also change the URL to download agents from an internal repository if you prefer.

To 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 advised 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 COPY (or 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.

      1. Corporate rule (e.g., expired license overrides assess.enable)
      2. System property value
      3. Environment variable value
      4. YAML configuration file value
      5. Contrast UI value
      6. Default value

Order of precedence is explained more here:
https://docs.contrastsecurity.com/en/order-of-precedence.html

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

Common configuration

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:

  1. Add a logging configuration
api:
  proxy:
    url: http:://host:port
agent:
  logger:
    stdout: true
assess:
  cache:
    hierarchy_enable: false
  1. Next, you create and copy the YAML file into the base image. 
  2. Copy the edited YAML file into the base image Dockerfile
COPY WORKSPACE/contrast_security.yaml /opt/contrast/contrast_security.yaml

Application-specific configuration

This allows additional options, per application. To set an application-specific configuration, use the Java system properties:

  • Application metadata: Specify application-specific metadata
    -Dcontrast.application.metadata
  • Application name: Specify the application name reported to Contrast
    -Dcontrast.agent.java.standalone_app_name
  • Application session metadata: Send application details like build number, version, GIT hash, etc.
    -Dcontrast.application.session_metadata

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.
    -Dcontrast.application.group
  • Server environment: specify in which environments the application is running. Valid values for this configuration are: Development, QA and Production. -Dcontrast.server.environment

 

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 JAVA_TOOL_OPTIONS. 

Base image Dockerfile

ENV CONTRAST_OPTS "-javaagent:/opt/contrast/contrast.jar \
-Dcontrast.config.path=/opt/contrast/contrast_security.yaml"

Application image Dockerfile

ENV JAVA_TOOL_OPTIONS $CONTRAST_OPTS \
-Dcontrast.application.metadata=bU=<value>,contactEmail=<value>,contactName=<value> \
-Dcontrast.agent.java.standalone_app_name=APP \
-Dcontrast.application.group=APP_GROUP

 

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> 
-e CONTRAST__API__USER_NAME=<value> -e CONTRAST__SERVER__NAME=<value> -e CONTRAST__SERVER__ENVIRONMENT=<value> image_with_contrast

 

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
2020-05-28 22:36:29,910 [main STDOUT] INFO - Contact: support@contrastsecurity.com
2020-05-28 22:36:29,910 [main STDOUT] INFO - License: Commercial
2020-05-28 22:36:29,910 [main STDOUT] INFO - NOTICE: This Software and the patented inventions embodied within may only be used as part of
2020-05-28 22:36:29,910 [main STDOUT] INFO - Contrast Security's commercial offerings. Even though it is made available through public
2020-05-28 22:36:29,910 [main STDOUT] INFO - repositories, use of this Software is subject to the applicable End User Licensing Agreement
2020-05-28 22:36:29,910 [main STDOUT] INFO - found at https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed between
2020-05-28 22:36:29,910 [main STDOUT] INFO - Contrast Security and the End User. The Software may not be reverse engineered, modified,
2020-05-28 22:36:29,910 [main STDOUT] INFO - repackaged, sold, redistributed or otherwise used in a way not consistent with the End User
2020-05-28 22:36:29,910 [main STDOUT] INFO - License Agreement.
[Contrast] Thu May 28 22:36:30 EDT 2020 Effective instructions: Assess=false, Protect=true
[Contrast] Thu May 28 22:36:30 EDT 2020 String Supporter has been disabled
[Contrast] Thu May 28 22:36:30 EDT 2020 Logging security messages to /Users/usernamehere/.contrast/security.log
[Contrast] Thu May 28 22:36:31 EDT 2020 Starting JVM [1862ms]

 

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.

https://github.com/Contrast-Security-OSS/demo-petclinic

 

FAQ

  1. How much will the Contrast Java agent affect performance for my applications?

https://support.contrastsecurity.com/hc/en-us/articles/360000500286-Java-Agent-Effects-on-Application-Performance-Assess-

  1. Is there any impact on application startup when running with Java?

https://support.contrastsecurity.com/hc/en-us/articles/360000460066-Java-Agent-Effects-on-Startup-Performance

  1. How do I fix SSL connection errors I see in the Contrast log?

https://support.contrastsecurity.com/hc/en-us/articles/360026878252-Java-Agent-Fails-to-Connect-to-Contrast-UI-javax-net-ssl-SSLHandshakeException

  1. 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.

https://docs.contrastsecurity.com/en/install-an-agent.html

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request