Skip to main content

Configure an agent

When you install an agent, you must configure it so that it recognizes your application and can communicate information back to Contrast.

Configuration follows this order of precedence.

Note

An expired license or exceeding a license quota disables all agent behavior regardless of configuration.

Steps

  1. Recommended: Use the Agent token to configure the required authentication variables (you can find this value in Contrast).

    api: 
   token: <token-value>

    Where the <token-value> is a base64 encoded JSON object containing the url, api_key, service_key, and user_name values, allowing you to set them in a single variable.

    Legacy settings: If you are using an older version of the agent, configure these authentication variables:

    api: 
  url: https://<environment>-agents.contrastsecurity.com  
  user_name: contrast_user  
  api_key: demo  
  service_key: demo

    where:

    • url: Address of the Contrast installation you would like your agent to report to. Defaults to: https://<environment>-agents.contrastsecurity.com/Contrast

    • user_name: Contrast user account

    • api_key: Your organization's API key

    • service_key: Contrast user account service key

    You can set these authentication variables with either:

    1. Environment variables.

      The simplest way to configure these values is to use an agent wizard (In the Contrast web interface, select Add New, select the Application card, and follow the instructions for your language). You can open the Contrast agent configuration editor from the agent wizard to configure these values.

    2. YAML configuration file.

      • You can download a YAML configuration file that is pre-populated with your organization keys. Select Add new in the Contrast web interface, select the Application card, and choose your application language to find a download link.

        This image shows the Add new button

      • You can also configure the file with the Contrast agent configuration editor which you can open from the agent wizard.

    3. Other methods native to the language and tools you are using, such as system properties or command line flags. Refer to the individual documentation pages for more details.

    Note

    See Contrast agent configuration editor to view a full list of options and their default values.

  2. Configure any additional variables.

    • Use session metadata to filter vulnerabilities and route information for a specific branch, build, committer, or repository.

    • Use application metadata to filter applications by custom values.

    When you add the necessary configuration settings to your agent configuration file, the agent reports this information along with the rest of your standard vulnerability data to Contrast. Look here for the full list of configuration values and what they do beyond the necessary values described above.

In this section: