Agent installation guide
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.
Create an .ebextensions configuration file
- Download the Contrast Java agent
- Create an agent configuration file
- Update JVM parameters to attach the agent
Instrument your application
- Deploy your application with the .ebextensions configuration file
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 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.
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:
Change $CONTRAST_AGENT_VERSION to the version of the Java agent to download, i.e.:
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.
- Corporate rule (e.g., expired license overrides assess.enable)
- System property value
- Environment variable value
- YAML configuration file value
- Contrast UI value
- 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
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.
This allows additional options, per application. To set an application-specific configuration, use the environment variables:
- 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.
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.
For this folder structure, use the following command to deploy your application with the Contrast Java agent:
eb deploy < environment name >
- 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.