Skip to main content

Install the Java agent using a container

Before you begin

This topic provides general guidance for installing the Contrast Java agent in a containerized application, with Docker as an example.

You should have a basic understanding of how containers and related software work. You may need to adjust the instructions to meet your specific circumstances.

ECS support

Using this procedure, you can install the Contrast Java agent using a Docker container in an Amazon Elastic Container Service (ECS) environment.

Step 1: Add the agent to base application image

If you add the agent to a base image, you can make a single image change and Contrast will be available to all applications using that base image. Also, this way, updates will depend on the base image update. To do this:

  1. Add the Contrast agent and basic configuration to a Docker base image, but don't enable it. The preferred location is /opt/contrast. For example:

    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

    Optionally, you can change the URL to download agents from an internal repository

    You can pass a specific agent version at build time by replacing <YourAgentVersion> with the version number you want to download, as shown in this example:

    docker build --build-arg CONTRAST_AGENT_VERSION=<YourAgentVersion> -t image_with_contrast:tag .

    Tip

    If you want more flexibility to use any version of the Java agent, and to avoid automatic updates, apply the ADD instruction directly to an application's Docker image.

  2. To enable Contrast in the application’s Docker image or container, use JVM parameters.

Step 2: Configure the agent

Configuration of the Java agent follows this order of precedence. When installing into a container:

  • Use a YAML configuration file for common configuration so it can be placed in the base image. For example, common configuration might include redirecting logging to console output, proxy configuration, or performance tuning.

    Here is a sample YAML configuration file:

    agent:
      java:
        scan_all_classes: false
        scan_all_code_sources: false
      logger:
        stdout: true

    Create and copy the YAML file into the base image, then copy the file into the base image Dockerfile using:

    COPY WORKSPACE/contrast_security.yaml /opt/contrast/contrast_security.yaml
  • Use Java system properties or environment variables for application-specific configuration values so you can uniquely configure options for each application.

    Contrast configuration

    Function

    Java system property

    Environment variable

    Application metadata

    Specify application-specific metadata

    -Dcontrast.application.metadata

    CONTRAST__APPLICATION__METADATA

    Application session metadata

    Send application details like build number, version, GIT hash, and other session metadata.

    -Dcontrast.application.session_metadata

    CONTRAST__APPLICATION__SESSION_METADATA

    Application group

    Specify the application access group for this application during onboarding. Create these groups in Contrast first.

    -Dcontrast.application.group

    CONTRAST__APPLICATION__GROUP

    Server environment

    Specify in which environments the application is running: Development, QA and Production.

    -Dcontrast.server.environment

    CONTRAST__SERVER__ENVIRONMENT

Step 3: Update JVM parameters

To attach any profiler to a Java application, you need to pass a -javaagent flag to the application by setting JAVA_TOOL_OPTIONS environment variables.

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. For example:

  • For the base image Dockerfile:

    ENV CONTRAST_OPTS "-javaagent:/opt/contrast/contrast.jar \
    -Dcontrast.config.path=/opt/contrast/contrast_security.yaml"
  • For the application image Dockerfile:

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

Step 4: Run the application image

After you add and configure the agent in a base image, run the image.

For the agent to send data to Contrast, it needs agent authentication keys. To protect the agent credentials, you can use 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]

See also

Agent Operator (Kubernetes operator)

Contrast Support Portal AWS Fargate and Contrast agents and Java agent with Docker