Java agent with AWS Elastic Beanstalk

Agent installation guide 

Overview

This guide offers examples for using Contrast Security’s Java agent with AWS Elastic Beanstalk. We encourage you to take this guide, make it your own, and distribute it to teams who both need to instrument Java applications and deploy them to the Beanstalk environment. 

The main portion of the guide details the most popular methods customers use to instrument Java applications deployed in Beanstalk and see security data in Contrast.

There is also a lab section that describes how to instrument a sample Java application called WebGoat. It’s a good way to learn before proceeding with your own applications. You can instrument WebGoat with Contrast and see security data for this application in Contrast using the source code samples section at the end of this guide.

Main steps

Create an .ebextensions configuration file

1. Download the Contrast Java agent
2. Create an agent configuration file
3. Update JVM parameters to attach the agent

Instrument your application

1. Deploy your application with the .ebextensions configuration file

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:

• Some familiarity with DevOps practices and how Beanstalk deployment works
• The information needed to connect the 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.
• Access to the Beanstalk environment to install customized .ebextensions configuration files.

https://aws.amazon.com/premiumsupport/knowledge-center/elastic-beanstalk-configuration-files/

Instructions

To begin, create an .ebextensions configuration file for Contrast.

1. Download the Contrast Java agent

We recommend that you use an .ebextensions configuration file to download the Contrast Java agent and instrument your application. The .ebextensions configuration file has a files section that downloads the agent from a remote URL. In this example, we get the Contrast Java agent from the Maven public repository.

Here is an example that shows how to configure .ebextensions to download the latest version of the Contrast Java agent from Maven:

files:
  "/opt/contrast/contrast.jar":
    mode: "000755"
    owner: root
    group: root
    source: "https://repo1.maven.org/maven2/com/contrastsecurity/contrast-agent/$CONTRAST_AGENT_VERSION/contrast-agent-$CONTRAST_AGENT_VERSION.jar"

Change $CONTRAST_AGENT_VERSION to the version of the Java agent to download, i.e.:
https://repo1.maven.org/maven2/com/contrastsecurity/contrast-agent/5.1.0/contrast-agent-5.1.0.jar

We recommend the location /opt/contrast for Contrast agents, but you can use another location, if necessary. You can also change the URL to download agents from an internal repository, if you prefer.

At build time, you can specify the agent version of your choice and download it from the Maven repository. 

2. Create an agent configuration file

There are different values you can use to configure Contrast agents. This is the order of precedence. Each level overrides the next, and 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

Learn more about the order of precedence 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 .ebextensions configuration file
• Use environment variables 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

Here is an example of code from the .ebextensions configuration file that shows how to create and configure the agent’s YAML file at deployment time.

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 allows additional options, per application. To set an application-specific configuration, use the environment variables:

• Application metadata: Specify application-specific metadata
  CONTRAST__APPLICATION__METADATA
• Application name: Specify the application name reported to Contrast
  CONTRAST__AGENT__JAVA__STANDALONE_APP_NAME
• Application session metadata: Send application details like build number, version, GIT hash, etc.
  CONTRAST__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.
  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

You can set the environment variables as you create the environment. Here is an example:

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>

You can also set them after you create the environment. Here is an example:

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>

3. Update JVM parameters

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.

Set these the same way as application-specific environment variables. Use the paths for the agent’s JAR and YAML configuration files. Here is an example:

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

You can combine this step with previous steps that pass environment variables to the agent.

4. Deploy your application with .ebextensions configuration

AWS expects the Beanstalk customization configuration to be in the .ebextensions folder in the deployment folder root. 

Here is an example 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

For this folder structure, use the following command to deploy your application with the Contrast Java agent:

eb deploy < environment name >

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-

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

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

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