Java Agent Configuration

  • Updated


Learn how to configure the Contrast Java agent.


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

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: # Required
api_key: h7...3R # Required
service_key: DS...FP # Required
user_name: agent_ae..87@MyOrg # Required
  name: MyApp
  name: MyAppServer
  enable: true
  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, 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.



Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request