Java Agent Configuration

Objective

Learn how to configure the Contrast Java agent.

Prerequisites

Download the latest Java agent from the Contrast UI or via Maven. 

To download the agent from the UI, a user's organization role has to be Edit or higher, in which case there should be an +Add new button in the upper right hand corner:

The agent can also be downloaded from the Contrast server via curl.

After selecting +Add new in the UI, a screen showing different types of instrumentation will be shown. To download the agent jar, select Live Application, and the click Next. The download link will be at the bottom of the screen:

Configuring the Agent

If the Java agent is downloaded from the Contrast server, the organization-specific agent credentials are bundled in the jar. For agents downloaded from a repo, such as Maven, the api credentials need to be supplied.

In addition to API credentials, the agent configuration can be used to control a variety of application settings and performance properties. Settings can be applied to an agent via - in order of precedence - Java system properties, Environment variables or a YAML configuration file (typically named contrast_security.yaml). For details, see https://docs.contrastsecurity.com/en/java-configuration.html.

Note: The contrast_security.yaml can also be downloaded from the server via

curl -HAuthorization:<AUTHORIZATION> -HAPI-Key:<API_KEY> -Haccept:'application/json' -Hcontent-type:'application/json' 'https://<SERVER>/Contrast/api/ng/<ORG_ID>/agents/external/default/JAVA' --data-binary '{"metadata":[]}' -OJ

A sample contrast_security.yaml file looks like

api:                                             # From User Menu->Org Settings->Agents
  url: https://app.contrastsecurity.com/Contrast # Required
  api_key: h7...3R                               # Required
  service_key: DS...FP                           # Required
  user_name: agent_ae..87@MyOrg                  # Required
application:
  name: MyApp
server:
  name: MyAppServer
assess:
  enable: true
protect:
  enable: false

Note: To indent keys, use spaces. Tabs are not allowed in YAML files.

To see available choices, you can run java -jar contrast.jar properties. For example, to get info on setting an application.name, you can execute:

java -jar contrast.jar properties | grep APPLICATION_NAME -A 8

You can use the Contrast agent configuration editor to validate and generate the configuration for Contrast agents.

To run the agent with a specific contrast_security.yaml, use the -Dcontrast.config.path  system property:

java -javaagent:/PATH/TO/contrast.jar -Dcontrast.config.path=/PATH/TO/contrast_security.yaml -jar app.jar

Note: When configuring other additional agents, it is recommended to instrument the Contrast agent first.