Skip to main content

Install the Java agent with AWS Elastic Beanstalk

Use this procedure as a guide to configuring the Java agent to work with AWS Elastic Beanstalk. It describes how to create an .ebextensions file that downloads the Contrast Java agent and instruments your application.

Depending on your environment, you might need to customize the steps in this procedure.

This procedure is designed for users who are familiar with DevOps practices and how Beanstalk deployment works.

Before you begin

Step1: Specify settings to download the Contrast Java agent

The .ebextensions configuration file has a files section that downloads the agent from a remote URL. This example shows how to specify downloading the agent from a Maven repository.

files:
  "/opt/contrast/contrast.jar":
    mode: "000755"
    owner: rootCorporate rule
    group: root
    source: "https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=com.contrastsecurity&a=contrast-agent&v=LATEST"

For Contrast agents, the recommended location is /opt/contrast, but you can use another location, if necessary. You can also change the URL to download agents from an internal repository. At build time, you can specify the agent version of your choice and download it from the Maven repository.

Step 2: Create an agent configuration file

There are different values you can use to configure Contrast agents, based on an order of precedence. Active configuration values are determined in this order:

  1. Corporate rule (for example, expired licenses)

  2. System property

  3. Environment variable

  4. YAML configuration file

  5. Contrast web interface value

  6. Contrast Security default value

The recommended approach to creating the configuration file is to use a common configuration and an application-specific configuration:

  • Common configuration: Specifies core set of configurations in the YAML. For example:

    • Redirect logging to console output

    • Proxy configuration, if any

    • Performance tuning options to limit agent activity

    This example shows how to create and configure the agent’s YAML file at deployment time in an .ebextensions configuration file.

    files:
 "/var/contrast/contrast_security.yaml" :
   mode: "000755"
   owner: root
   group: root
   content: |
     api:
       proxy:
         url: https://host:port
     agent:
       java:
         scan_all_classes: false
         scan_all_code_sources: false
       logger:
         stdout: true

  • Application-specific configuration: This configuration lets you specify additional options, for each application. Use these environment variables:

    • Application metadata: Specifies application-specific metadata

      CONTRAST__APPLICATION__METADATA

    • Application name: Specifies the application name reported to Contrast

      CONTRAST__APPLICATION_NAME

    • Application session metadata: Send application details such as, build number, version, and GIT hash,

      CONTRAST__APPLICATION__SESSION_METADATA

      Note

      Learn about additional session metadata options.

    • Application group: Specifies the application access group for this application when you add it to Contrast. You must create application access groups before you use this variable.

      CONTRAST__APPLICATION__GROUP

    • Server environment: specify in which environments the application is running. Valid values for this configuration are: Development, QA and Production.

      CONTRAST__SERVER__ENVIRONMENT

    Example 1: This example shows how to set environment variables when you create the environment:

    eb create <environment name> --envvars CONTRAST__API__URL=https://app.contrastsecurity.com/Contrast,CONTRAST__API__API_KEY=<value>,CONTRAST__API__SERVICE_KEY=<value>,CONTRAST__API__USER_NAME=<value>,CONTRAST__SERVER__NAME=<value>,CONTRAST__SERVER__ENVIRONMENT=<value>

    Example 2: This example shows how to set the environment variables after you create the environment:

    eb setenv CONTRAST__API__URL=https://app.contrastsecurity.com/Contrast CONTRAST__API__API_KEY=<value> CONTRAST__API__SERVICE_KEY=<value> CONTRAST__API__USER_NAME=<value> CONTRAST__SERVER__NAME=<value> CONTRAST__SERVER__ENVIRONMENT=<value>

Step 3: Update JVM parameters

To attach any profiler to a Java application, you must pass a -javaagent flag to the application. To do this, set the JAVA_TOOL_OPTIONS environment variable.

Set these variables in the same way as you set application-specific environment variables. Use the paths for the agent’s JAR and YAML configuration files, as shown in this example.

eb setenv JAVA_TOOL_OPTIONS="-javaagent:/opt/contrast/contrast.jar -Dcontrast.config.path=/var/contrast/contrast_security.yaml"

Step 4: Deploy the agent using the .ebextensions configuration

AWS expects the Beanstalk customization configuration to be in the .ebextensions folder in the deployment folder root. This example shows a directory structure that includes the .ebextensions folder. It shows the location of the contrast.config file that includes the agent download and YAML configuration sections.

├── .ebextensions
│   └── contrast.config
└── application.jar
In this section: