Configuration

YAML Properties

Contrast supports YAML-based configuration for the Java agent. This allows you to store configuration on disk that you can override with environment variables or command line arguments.

Note: While all Contrast agents share the same property formatting in YAML configuration files, each agent must use its specified file.

Load Path

Configuration values use the following order of precedence:

  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

You can set the path to the YAML configuration file using the environment variable CONTRAST_CONFIG_PATH or the Java system property contrast.config.path. Like the rest of the configuration values, the system property takes precedence over the environment variable, if both are set.

If the environment variable and the system property aren't set, the agent will look for the YAML configuration file in the default location.

On Windows:

%ProgramData%\Contrast\java\contrast_security.yaml

On Unix/Linux file systems:

/etc/contrast/java/contrast_security.yaml

Go to the Java YAML Template for fully formatted properties that you can copy and use in your own agent configuration files.

Set as System Properties

You can also set all of the following YAML properties as system properties. Derive the system property key from the YAML by joining every node with a "." until you reach the bottom property.

Example: If you want to override the contrast property, as given below, you can set -Dcontrast.enable=false as a system property.

  • contrast:
    • enable: true

Configuration Options

Contrast UI properties

Use the properties in this section to connect the Java agent to the Contrast UI. The proxy settings allow the agent to communicate with the Contrast UI over a proxy.

  • contrast:

    • enable: Only set this property if you want to turn off Contrast. Set to true to turn the agent on; set to false to turn the agent off.
    • url: Set the URL for the Contrast UI.
      Example: https://app.contrastsecurity.com/Contrast. Required.
    • api_key: Set the API key needed to communicate with the Contrast UI. Required.
    • service_key: Set the service key needed to communicate with the Contrast UI. It is used to calculate the Authorization header. Required.
    • user_name: Set the user name used to communicate with the Contrast UI. It is used to calculate the Authorization header. Required.

      • proxy:
        • enable: Add a property value to determine if the agent should communicate with the Contrast UI over a proxy. If a property value is not present, the presence of a valid proxy host and port determines enabled status. Value options are true or false
        • host: Set the proxy host. It must be set with port and scheme.
          Example: localhost
        • port: Set the proxy port. It must be set with host and scheme.
          Example: 1234
        • scheme: Set the proxy scheme. It must be set with host and port.
          Example: http or https
        • url: Set as an alternate for scheme://host:port. It takes precedence over the other settings, if specified; however, an error will be thrown if both the URI and individual properties are set.
        • user: Set the proxy user.
        • pass: Set the proxy password.
        • auth_type: Set the proxy authentication type. Value options are NTLM, Digest, and Basic.

Contrast agent properties

Use the properties in this section to control agent-wide behaviors. For example, you can use this section to control the way in which the agent starts up and shuts down, and the way in which it communicates to logs and to the Contrast UI. If these values are not set, the agent will use the values set in the Contrast UI.

All properties in this section must be put under the agent node, as shown in the YAML template.

  • agent:
    • shutdown_time_ms: Set how long to run the agent before shutting down itself (in milliseconds). A negative value disables scheduled shutdown.
    • deinstrument_on_shutdown: Enable to deinstrument classes on shutdown. If this is not enabled, the agent disables sensors on shutdown, but leaves instrumentation.

Diagnostic logging

Use the properties in this section to control diagnostic logging. These logs allow us to diagnose any issues you may be having with the agent.

  • agent:

    • logger:
      • path: Enable diagnostic logging by setting a path to a log file. While diagnostic logging hurts performance, it generates useful information for debugging Contrast. The value set here is the location to which the agent saves log output. If no log file exists at this location, the agent creates a file.
        Example: /opt/Contrast/contrast.log creates a log in the /opt/Contrast directory, and rotates it automatically as needed.
      • level: Set the log output level. Value options are OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, and ALL.
      • roll_daily: Change the Contrast logger from a file-sized based rolling scheme to a date-based rolling scheme. At midnight server time, the log from the previous day log is renamed to file_name.yyyy-MM-dd. You must set this flag to use the backups and size flags.
        Note: This scheme does not have a size limit; manual log pruning is required.
        Example: false
      • roll_size: Set the roll size for log files unless agent.logger.roll_daily=true.
        Example: 100M
      • backups: Set the number of backup files to keep.
        Example: 10

Security logging

Use the properties in this section to control security logging. These logs allow you to watch Protect as it monitors and blocks attacks against your application. They are written to the specified file in the Common Event Format (CEF). The Syslog settings allow you to send security logs to remote servers.

  • security_logger:

    • path: Set the file to which the agent logs security events.
      Example: /.contrast/security.log
    • level: Set the log level for security logging. Value options are OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, and ALL. Set this property to OFF to disable security logging.
    • roll_daily: Change the Contrast security logger from a file-sized based rolling scheme to a date-based rolling scheme. At midnight server time, the log from the previous day is renamed to file_name.yyyy-MM-dd. This flag must be set to use the backups and size flags. Value options are true or false.
      Note: This scheme does not have a size limit; manual log pruning will be required.
    • roll_size: Specify the file size cap (in MB) of each log file.
    • backups: Specify the number of backup logs that the agent will create before Contrast cleans up the oldest file. A value of 0 means that no backups are created, and the log is truncated when it reaches its size cap.
      Note: This property must be used with agent.security_logger.roll_daily=false; otherwise, Contrast continues to log daily and disregard this limit.

    • syslog:

      • enable: Set to true to enable Syslog logging.
      • ip: Set the IP address of the Syslog server to which the agent should send messages.
      • port: Set the port of the Syslog server to which the agent should send messages.
      • facility: Set the facility code of the messages the agent sends to Syslog.
      • severity_exploited: Set the log level of Exploited attacks. Value options are ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, and DEBUG.
      • severity_blocked: Set the log level of Blocked attacks. Value options are ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, and DEBUG.
      • severity_probed: Set the log level of Probed attacks. Value options are ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, and DEBUG.

Agent-Specific Properties

Use the properties in this section to apply any Java agent-wide configurations.

  • java:
    • standalone_app_name: Set the name of a standalone application. If this value is set, the agent assumes there is only one application in this server.

Inventory properties

Use the properties in this section to control inventory features in the Java agent.

  • inventory:
    • enable: Set to false to disable Inventory features in the agent.
    • library_dirs: Define a list of directories where libraries are stored. Directories must be formatted as a semicolon-delimited list.
      Example: path1;path2;path3
    • library_depth: Set the maximum archive unpacking depth when analyzing libraries.
      Example: 10
    • prune_package_details: Set to false to disable Inventory features in the agent.
    • tags: Apply a list of labels to libraries. Labels must be formatted as a comma-delimited list.
      Example: label1, label2, label3

Contrast Assess properties

Use the properties in this section to control Assess in the Java agent. The sampling settings allow you to control which requests the agent tracks and which it ignores. The rules setting allows you to control which Assess rules are disabled.

Note: If you need a complete list of rules, use the Support widget in OpenDocs to contact Contrast's Customer Support team.

  • assess:

    • enable: Include this property to determine if the Assess feature should be enabled. If this property is not present, the decision is delegated to the Contrast UI.
      Example: true
    • tags: Apply a list of labels to vulnerabilities and preflight messages. Labels must be formatted as a comma-delimited list. Example: label1, label2, label3

    • samplings:

      • enable: Set to false to disable sampling.
      • baseline: This property indicates how many requests to analyze in each window before sampling begins.
        Example: 5
      • request_frequency: This property indicates that every nth request after the baseline is analyzed.
        Example: 10
      • window_ms: This property indicates the duration for which a sample set is valid.
        Example: 180_000
    • rules:

      • disabled_rules: Define a list of Assess rules to disable in the agent. The rules must be formatted as a comma-delimited list.
        Example: Set "reflected-xss,sql-injection" to disable the reflected-xss rule and the sql-injection rule.

Contrast Protect properties

Use the properties in this section to control Protect features and rules.

  • protect:

    • enable: Use the properties in this section to determine if the Protect feature should be enabled. If this property is not present, the decision is delegated to the Contrast UI.

    • rules:

      • disabled_rules: Define a list of Protect rules to disable in the agent. The rules must be formatted as a comma-delimited list.

      • bot-blocker:

        • enable: Set to true for the agent to block known bots.
      • sql-injection:

        • mode: Set the mode of the rule. Value options are monitor, block, block_at_perimeter, or off.
          Note: If a setting says, "if blocking is enabled", the setting can be block or block_at_perimeter.
      • cmd-injection:

        • mode: Set the mode of the rule. Value options are monitor, block, block_at_perimeter, or off.
          Note: If a setting says, "if blocking is enabled", the setting can be block or block_at_perimeter.
      • path-traversal:

        • mode: Set the mode of the rule. Value options are monitor, block, block_at_perimeter, or off.
          Note: If a setting says, "if blocking is enabled", the setting can be block or block_at_perimeter.
      • method-tampering:

        • mode: Set the mode of the rule. Value options are monitor, block, block_at_perimeter, or off.
          Note: If a setting says, "if blocking is enabled", the setting can be block or block_at_perimeter.
      • reflected-xss:

        • mode: Set the mode of the rule. Value options are monitor, block, block_at_perimeter, or off.
          Note: If a setting says, "if blocking is enabled", the setting can be block or block_at_perimeter.
      • xxe:

        • mode: Set the mode of the rule. Value options are monitor, block, block_at_perimeter, or off.
          Note: If a setting says, "if blocking is enabled", the setting can be block or block_at_perimeter.
      • csrf:

        • mode: Set the mode of the rule. Value options are monitor, block, block_at_perimeter, or off.
          Note: If a setting says, "if blocking is enabled", the setting can be block or block_at_perimeter.

Application properties

Use the properties in this section to control the application(s) hosting this agent.

  • application:
    • name: Override the reported application name.
    • path: Override the reported application path.
    • group: Add the name of the application group with which this application should be associated in the Contrast UI.
    • code: Add the application code this application should use in the Contrast UI.
    • version: Override the reported application version.
    • tags: Apply labels to an application. Labels must be formatted as a comma-delimited list.
      Example: label1,label2,label3
    • metadata: Define a set of key=value pairs (which conforms to RFC 2253) for specifying user-defined metadata associated with the application. The set must be formatted as a comma-delimited list of key=value pairs.
      Example: "business-unit=accounting, office=Baltimore"

Server properties

Use the properties in this section to set metadata for the server hosting this agent.

  • server:

    • name: Override the reported server name.
      Example: test-server-1
    • build: Override the reported server build.
    • version: Override the reported server version.
    • environment: Override the reported server environment.
      Example: development
    • tags: Apply a list of labels to the server. Labels must be formatted as a comma-delimited list.
      Example: label1,label2,label3

System Properties

General Properties

Generate a list of general properties directly from the command line using the Contrast agent JAR by executing java -jar path/to/contrast.jar properties. You could also generate this markdown file directly from the command line by executing java -jar contrast.jar properties --generate-markdown --write-to-file=/path/to/file.md. Combine the command with tools like grep to search for commands.

Example: java -jar path/to/contrast.jar properties | grep -A5 "proxy" would yield a list of proxy-related properties.

Property Description
contrast.activity Boolean to enable/disable the Contrast activity thread
DEFAULT VALUE: true
contrast.app.activity.period Contrast application activity thread polling period in milliseconds
DEFAULT VALUE: 30000 (30 seconds, in milliseconds)
contrast.app.features JSON from disk to use for application
DEFAULT VALUE: not used; this property must be set to be active
contrast.app.update.period Contrast application update thread polling period in milliseconds
DEFAULT VALUE: 5000 (5 seconds, in milliseconds)
contrast.appupdate Boolean to enable/disable threads that sends updates about applications to Contrast
DEFAULT VALUE: true
contrast.auto.license.assessment Boolean to allow Contrast to license an application on creation
DEFAULT VALUE: false
contrast.auto.license.protection Boolean to allow Contrast to license a server on creation
DEFAULT VALUE: false
contrast.classpath.libs Determines if Contrast tracks usage of libraries listed in the environment's java.class.path property. This should only be on in J2SE/desktop situations.
DEFAULT VALUE: not used; this property must be set to be active
contrast.cloneinput Boolean to enable/disable cloning of tracked objects
DEFAULT VALUE: true
contrast.container Manually override the web app container name/ID
DEFAULT VALUE: detected by the Java agent
contrast.dbinspection Boolean to enable/disable database inspection when analyzing application architecture
DEFAULT VALUE: true
contrast.deepclone Boolean to enable/disable cloning of leaf nodes in object graphs of deserialized objects
DEFAULT VALUE: false
contrast.dir This value can override the default Contrast working directory. Creates the directory if it does not exist.
DEFAULT VALUE: ${HOME}/.contrast of the user account the application runs under.
contrast.duplicate.delay The period for which duplicate traces, based on Contrast hashing methods, will be supressed (in milliseconds)
DEFAULT VALUE: 5000
contrast.enabled Determines if Contrast monitors the JVM. You can use this feature to turn Contrast on or off quickly without removing the -javaagent flag.
DEFAULT VALUE: true
contrast.env Send the environment for a new application server to Contrast. See the Note below for more information.
Valid values: development, qa and production (case insensitive). Example: -Dcontrast.env=qa.
contrast.external.lib.dir List of directories where external libraries are stored; used during library analysis. Takes a semicolon-delimited list on Windows and a colon-delimited list on Linux.
DEFAULT VALUE: not used; this property must be set to be active
contrast.inject.browseragent Manually override name of browser agent.
DEFAULT VALUE: not used; this property must be set to be active
contrast.j2ee.context.discovery Boolean to enable/disable J2EE context discovery.
DEFAULT VALUE: true
contrast.mode assess: Data flow analysis, defend: defend features, inventory: library catalog and analysis, all: all features; When this property is enabled, the agent ignores all customizations from the Contrast interface.
DEFAULT VALUE: not used; this property must be set to be active
contrast.nested.libs.depth Maximum archive unpacking depth when analyzing libraries
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.noteamserver.enable Boolean to enable/disable Contrast to start up without access to the Contrast interface.
DEFAULT VALUE: false
contrast.override.appname Sets the application name; this name is reported to Contrast.
DEFAULT VALUE: determined by scanning web.xml
contrast.override.appversion Sets the application version; this version is reported to the Contrast interface.
DEFAULT VALUE: determined by scanning web.xml
contrast.path Contrast "working directory" override
DEFAULT VALUE: the "current" folder according to the container
contrast.poll.features Boolean to enable/disable features polling thread
DEFAULT VALUE: true
contrast.properties Location of file containing Java properties style key and value pairs.
DEFAULT VALUE: not used; this property must be set to be active
contrast.redos.characcess.limit The number of character accesses that can occur when processing a regular expression before blocking occurs.
DEFAULT VALUE: 3000000
contrast.reporting.period Polling period for spooling reports, like traces and application updates (in milliseconds)
DEFAULT VALUE: 3000 (3 seconds, in milliseconds)
contrast.rootapp This value can override - or provide, if none exist - a display name for the application running at the root context. This may be necessary for Contrast to collect analytics on the application.
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.scanresponses Boolean to enable/disable scanning of HTTP responses.
DEFAULT VALUE: true
contrast.server Overrides name of the server displayed in the Contrast interface. Includes any valid path characters, e.g. myserver-1/myapp or john_dev.
DEFAULT VALUE: not used; this property must be set to be active
contrast.server.activity.period Polling period for Contrast polling thread (in milliseconds).
DEFAULT VALUE: 30000 (30 seconds, in milliseconds)
contrast.stacks.maxdepth Maximum stack depth to include in reported findings.
DEFAULT VALUE: 75
contrast.standalone.appname Indicates the application is a standalone application with the provided name.
DEFAULT VALUE: none, must be set
contrast.supporter.jackson.interning Controls whether or not string interning is disabled in Jackson. The default value is true.
DEFAULT VALUE: true
contrast.supporter.minidevjson Boolean to enable/disable net.minidev.json support.
DEFAULT VALUE: true
contrast.teamserver.channel.pause.period The amount of time to pause agent-to-Contrast communication when a bad response code is received.
DEFAULT VALUE: 900000 (15 minutes in milliseconds)
contrast.teamserver.url This value overrides the Contrast interface URL that's packaged with the agent. This can be useful for networks that proxy the information.
DEFAULT VALUE: stored in the contrast.config file packaged in contrast.jar
contrast.telemetry.dir Location for Contrast telemetry output.
DEFAULT VALUE: not used; this property must be set to be active
contrast.timeout This value can override the default timeout (in seconds) for communicating with the Contrast interface.
DEFAULT VALUE: 10
contrast.useconfig Uses the contrast.config file packaged in another contrast.jar.
DEFAULT VALUE: not used; this property must be set to be active
contrast.user.packages A comma-separated list of packages that Contrast should deeply scan for SMAP information, vulnerabilities and other application-related analysis.
DEFAULT VALUE: none
contrast.websphere.shared.libs The location of shared library directory on WebSphere.
DEFAULT VALUE: not used; this property must be set to be active
csrf.allowed.filewrite.suffixes A comma-separated list of allowed file suffixes which CSRF won't consider as evidence of state change.
DEFAULT VALUE: not used; this property must be set to be active
csrf.allowed.urls Sets the path to a file containing line-separated URLs patterns which don't require CSRF tokens.
DEFAULT VALUE: not used; this property must be set to be active
csrf.protected.urls Sets the path to a file containing line-separated URLs patterns which require CSRF tokens.
DEFAULT VALUE: not used; this property must be set to be active
felix.bundles.path Set to override default location of Felix bundles directory.
DEFAULT VALUE: ./sling/felix

Note: To change the environment after the server has been created in Contrast, you must go to the Servers page in the Contrast UI.

Logging

By default, diagnostic logging is enabled, but set to the INFO level. It uses a rolling file appender scheme to keep up to 1 GB of logs on the File System, broken up into 10MB log files. Logging has a small performance impact, but generates useful information for debugging Contrast. To change how logging functions, you can adjust the following system properties.

Assessment mode

Property Description
contrast.level Log output level
DEFAULT VALUE: info
contrast.log Enable diagnostic logging. This hurts performance, but generates useful information for debugging Contrast. The value set here will be the location to which log output is saved. If no log file exists at this location, one will be created. For instance, /opt/Contrast/contrast.log will create a log in the /opt/Contrast directory and rotate it automatically as needed.
DEFAULT VALUE: ${HOME}/.contrast/logs/contrast.log
contrast.log.backups Specify the number of "backup" logs that will be created before Contrast will clean up the oldest file. This value has a cap of 100, meaning no more than 100 log files can be stored on the file system at one time. A value of 0 here means that no backups will be created and the log will simply be truncated when it reaches its size cap.
DEFAULT VALUE: 100
contrast.log.daily Change the Contrast logger from a file sized based rolling scheme to a date based rolling scheme. At midnight serve time, the previous day's log will be renamed to file_name.yyyy-MM-dd. Note, this scheme does not have a size limit, so manual log pruning will be required. This flag must be set to use the backups and size flags.
DEFAULT VALUE: true
contrast.log.size Specify the file size cap, in MB, of each log file. This value has a cap of 10, meaning no more than 10MB will be logged to a single file.
DEFAULT VALUE: 10

Defend mode

Property Description
contrast.security.log.backups Specify the number of "backup" logs that will be created before Contrast will clean up the oldest file. This value has a cap of 100, meaning no more than 100 log files can be stored on the file system at one time. A value of 0 here means that no backups will be created and the log will simply be truncated when it reaches its size cap.
DEFAULT VALUE: false
contrast.security.log.daily Change the Contrast security logger from a file sized based rolling scheme to a date based rolling scheme. At midnight server time, the previous day's log will be renamed to file_name.yyyy-MM-dd. Note, this scheme does not have a size limit, so manual log pruning will be required. This flag must be set to use the backups and size flags.
DEFAULT VALUE: true
contrast.security.log.file The file to which logging of security events will occur. By default, this file is located at /security.log.
DEFAULT VALUE: ${HOME}/.contrast/logs/security-events.log
contrast.security.log.level Set the log level for security logging. Values include: trace, debug, info, warn, error, fatal, off. Setting this to off will disable security logging.
DEFAULT VALUE: info
contrast.security.log.size Specify the file size cap, in MB, of each log file. This value has a cap of 10, meaning no more than 10MB will be logged to a single file. By default, this value is '10'.
DEFAULT VALUE: 10

Diagnostics

Property Description
contrast.assess.autodetect.controls boolean to enable/disable detecting security sensors
DEFAULT VALUE: true
contrast.assess.secondorder.canary A value that will be fed by attack testing tools in order to test stored XSS or other second-order injection attacks to be detected coming out of databases
DEFAULT VALUE: null (disabled)
contrast.savebytecode Save the before/after bytecode of classes where sensors have been added.
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.saveresults controls when Contrast findings are saved locally
DEFAULT VALUE: never
contrast.scoped.jarverifier controls whether the JarInputStream verifier is disabled during our scoped operations
DEFAULT VALUE: false

Proxy settings

Property Description
contrast.proxy.protocol Proxy protocol, e.g. http, https
DEFAULT VALUE: not used; this property must be set in order to be active
proxy.auth Override authentication type for Proxy
DEFAULT VALUE: configured system property
proxy.fingerprint Override Fingerprint for Proxy
DEFAULT VALUE: configured system property
proxy.host Override Host for Proxy
DEFAULT VALUE: configured system property
proxy.pass Override Password for Proxy
DEFAULT VALUE: configured system property
proxy.port Override Port for Proxy
DEFAULT VALUE: configured system property
proxy.user Override User for Proxy
DEFAULT VALUE: configured system property

Performance

Property Description
contrast.assess.threshold.entries The maximum number of vulnerabilities per rule type that can be discovered within a period defined by contrast.assess.threshold.period
DEFAULT VALUE: 100
contrast.assess.threshold.period The period, in seconds, in which a maximum number of vulnerabilities per rule type can be discovered
DEFAULT VALUE: 60 (seconds)
contrast.blacklist path to file that lists blacklisted classes
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.cache.hierarchy boolean to enable/disable hierarchy cache
DEFAULT VALUE: true
contrast.concurrent.requests average number of concurrent users logged into the application at any one time
DEFAULT VALUE: 20
contrast.hierarchy.rebuild boolean to trigger rebuilding/resetting the hierarchy cache
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.hierarchy.update boolean to trigger updating the hierarchy cache
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.http.analysis.parameters boolean to enable/disable analysis of HTTP parameters
DEFAULT VALUE: true
contrast.j2ee.classcache boolean to enable/disable caching of instrumented classes
DEFAULT VALUE: true
contrast.preflight.open Typically, the Contrast Agent uses a preflight hashing mechanism to avoid duplicate reporting, reducing load on TeamServer. Occasionally, this process can be overwhelmed, and TeamServer cannot reply quickly enough. In this case, in order to avoid losing any vulnerability data, the Agent will send any reports that are being filtered by preflight. While TeamServer can usually recover and resume preflight, it sometimes falls behind (for instance if the application being monitored is placed under a load test). To ensure that TeamServer has a chance to catch up, you can set this flag to false; however, it is worth noting that doing so may result in lost vulnerability information as all reports will be disregarded.
DEFAULT VALUE: false
contrast.sampling Enable and configure sampling mode. By default, just placing this flag will result in a baseline (how many times a request should be analyzed before it is considered sampled) and frequency (how often after the baseline has been established should new samples be taken) of 5 and a sampling window (how long the baseline is valid, in seconds) of 180 seconds. This means that after the same request has been seen five times in 180 seconds, it will only be analyzed every subsequent fifth time. You can customize this further by setting the value to "#,#,#". In this case, the baseline will be set to the first number, the frequency second, and the window third. Note that if you choose to customize any value, you must provide all three inputs.
DEFAULT VALUE: Not used if flag is not specified. If just the flag is specified (without the values): 5,5,180

Policy

Property Description
contrast.policy If you set this value to a file or URL, Contrast will use it in addition to the pre-packaged security policy. This means that rules from both the standard Contrast policy and your custom policy will be used, with conflicts being resolved in favor of the external policy, i.e. if two sources have the same ID, one in the internal policy and one in the external, the external source will be used.
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.policy.overrides Same functionality as contrast.policy, but policies listed here have a higher priority, meaning that conflicts will be resolved in favor of the overrides policy, i.e. if two sources have the same ID, one in the policy and one in the override, the override source will be used.
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.policy.standalone If you set this value to a file or URL, Contrast will use it instead of the pre-packaged security policy. For more information about rule customization, please contact your account manager.
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.rules.jar If you set this value to a .jar file or URL, Contrast will load the rules from it (Java 6+ only)
DEFAULT VALUE: not used; this property must be set in order to be active

Rules configuration

Property Description
contrast.assess.hashing.includeurl Set to "true" to factor in request URL when computing hash for reported finding
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.deadzones boolean to enable/disable loading of deadzones from policy
DEFAULT VALUE: true
contrast.disabledrules list of disabled rule ids
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.disabledsources list of disabled source ids
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.dynamicsources boolean to enable/disable loading of dynamic sources from policy
DEFAULT VALUE: true
contrast.identitytags boolean to enable/disable identity tags
DEFAULT VALUE: true
contrast.propagators boolean enable/disable loading of propagators from policy
DEFAULT VALUE: true
contrast.rules boolean to enable/disable loading of rules from policy
DEFAULT VALUE: true
contrast.sources boolean to enable/disable loading of sources from policy
DEFAULT VALUE: true
contrast.tags boolean to enable/disable loading of tags from policy
DEFAULT VALUE: true
contrast.validator.scopes boolean to enable/disable loading of validator-scopes
DEFAULT VALUE: true
contrast.validators boolean to enable/disable loading of validators from policy
DEFAULT VALUE: true
web.session.timeout Overrides the maximum "safe" value of detected in the web.xml file. The default value is 30 (minutes).
DEFAULT VALUE: 30

Defend mode configuration

Property Description
contrast.cmdinjection.keywords File path to overriding Command Injection keywords file
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.cmdinjection.patterns Location of Command Injection patterns file
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.defend.api.bodyread boolean to enable/disable whether API request bodies should be scanned for attacks if no known deserializers are in use
DEFAULT VALUE: true
contrast.defend.blocked.samples Max number of detailed reports generated for blocked attacks detected during a reporting period
DEFAULT VALUE: 25
contrast.defend.csrf.token.name the name of the CSRF token HTTP parameter
DEFAULT VALUE: cs_csrf_tkn
contrast.defend.exploited.samples Max number of detailed reports generated for exploited attacks during a reporting period
DEFAULT VALUE: 100
contrast.defend.ineffective.samples Max number of detailed reports generated for ineffective attacks detected during a
DEFAULT VALUE: 50
contrast.defend.paddingoracle.threshold Minimum number of padding errors to be observed during a reporting period in order to be classfied as malicious
DEFAULT VALUE: 25
contrast.defend.patterns File path to overriding RASP patterns file (used when Contrast is in DEFEND mode)
DEFAULT VALUE: uses patterns embedded in the agent
contrast.defend.telemetry.dir File path to RASP telemetry directory (used when Contrast is in DEFEND mode)
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.sqlinjection.keywords File path to overriding SQL Injection keywords file
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.sqlinjection.patterns Location of SQL Injection patterns file
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.xss.keywords File path to overriding XSS keywords file
DEFAULT VALUE: not used; this property must be set in order to be active
contrast.xss.patterns Location of XSS patterns file
DEFAULT VALUE: not used; this property must be set in order to be active

More Information

Configurable Properties

Parameters for certain rules are now configurable by the end user. The following are methods of applying custom parameters to these rules.

Setting In "rules.xml"

An optional top level <properties> element has been added to the rules.xml.

<?xml version="1.0" encoding="UTF-8"?>
<policies>
    <policy>
        <properties>
            <web.session.timeout>30</web.session.timeout>
            .
            .
            .
        </properties>
        <org-packages/>
        <propagators>
        .
        .
        .
        </propagators>
        .
        .
        .
    </policy>
    .
    .
    .
</policies>

Properties File

Also, users can use -Dcontrast.properties="/path/to/properties.file" to point to a standard Java properties file when launching their application container. This will override any settings in the <properties> element in the rules.xml file.

For example, in the catalina.sh:

export CONTRAST_AGENT_JAR= "..."
export JAVA_OPTS= "$JAVA_OPTS -javaagent:$CONTRAST_AGENT_JAR -Dcontrast.properties=" /path/to/properties.file "..."

And a properties file located at /path/to/properties.file would look like web.session.timeout= 30.

Direct Definition

Finally, the user could specify a property directly when launching their application container, like -Dweb.session.timeout=30. This will override any settings in rules.xml and the properties file.

export CONTRAST_AGENT_JAR= "..." 
export JAVA_OPTS= "$JAVA_OPTS -javaagent:$CONTRAST_AGENT_JAR -Dweb.session.timeout=" 30 "..."

Supported Properties

Currently, the following properties are supported by this feature:

Property Name Default Value Description
web.session.timeout 30 The security plugin will report a vulnerability if the <session-timeout> value configured in an application's web.xml exceeds this value. This value is in minutes.

PII Masking

About PII Masking

Some Contrast users have sensitive information in their applications that the Java agent captures and sends to the Contrast application. Consequently, other users in the same organization may view personally identifiable information (PII) - including passwords, security keys and other sensitive data - in the Contrast UI.

How It Works

Contrast’s PII masking feature removes the sensitive information and replaces it with a masking key in the Contrast UI, while still allowing the agent to Assess and Protect your application. Contrast handles three types of user input data: body, header and query parameter. Body masking is activated using a Boolean configuration property, and will mask all request bodies. For Protect findings and HTTP requests, header and query parameter masking will only mask the value of the header or query parameter defined in the configuration property. For Assess findings, Contrast masks all potentially sensitive information.

Properties

The following command line properties control and define masking for Protect findings and HTTP requests.

  • contrast.report.body: Masks data in the body when set to false. Provided as a Boolean. Defaults to true (no masking).

  • contrast.report.headers.mask: Masks data found in the header values. Values provided as a comma-separated string with spaces omitted. Defaults to empty (no masking).

  • contrast.report.query.parameter.mask: Masks data found in the query parameters. Values provided as a comma-separated string. Defaults to empty (no masking).

The following command line property enables masking for Assess findings.

  • -Dcontrast.report.assess.mask: If true, Contrast masks all potentially sensitive fields. Defaults to false (no masking).

Example:

 java -javaagent:contrast.jar 
 -Dcontrast.report.query.parameter.mask=menu,title -Dcontrast.report.body=false -Dcontrast.report.assess.mask=true -Dcontrast.report.headers.mask=cookie,host,referer,menu,title,screen,message,submit -jar /Users/johnsmith/Source/Test/webgoat-container-7.0.1-war-exec.jar

Masking Keys

Contrast sends the following string values to the application in place of sensitive information.

  • Body: {body-omitted-by-contrast}
  • Header: {header-value-omitted-by-contrast}
  • Parameter: {query-parameter-value-omitted-by-contrast}
  • Details: {value-omitted-by-contrast}
    Most rules have details that contain additional rule-specific information. In some cases, these details have sensitive information that requires Contrast to use the given mask.

TLS Configuration

TLS Connection

The Contrast Java agent uses a secure TLS connection to communicate with the Contrast UI. Contrast hosted systems (e.g., app.contrastsecurity.com) use strong TLSv1.2 connections and certificates signed by industry standard certificate authorities (CAs). However, users running their own Enterprise-on-Premises (EOP) Contrast services may need to configure the Java agent to use enterprise CAs, and may want the Java agent to send client certificates in the TLS handshake.

Configuring TLS

The Contrast Java agent uses the standard Java Cryptography Architecture for configuring TLS. Specifically, the Java agent uses the system's "TLS" SSContext. For most users, this means that you can adjust the certificates trusted by the agent using the standard javax.net.ssl.trustStore system properties. You can also adjust the certificate the agent sends when the TLS server requests a client certificate using the standard javax.net.ssl.keyStore system properties.

The following example configures the Java agent to use a custom key store and trust store.

java \
  -javaagent:contrast.jar \
  -Djavax.net.ssl.trustStore=/etc/pki/tls/my-enterprise-truststore.p12 \
  -Djavax.net.ssl.trustStorePassword=changeit \
  -Djavax.net.ssl.trustStoreType=PKCS12 \
  -Djavax.net.ssl.keyStore=/etc/pki/tls/server-client-certificate.p12 \
  -Djavax.net.ssl.keyStorePassword=password \
  -Djavax.net.ssl.keyStoreType=PKCS12 \
  -jar my-server.jar

Configuring the Cache

How does the cache work?

It works like this: Contrast sees a new class about to be loaded, it checks the results of the last execution. If it was a class that didn't need to be instrumented before, it doesn't need to be analyzed or instrumented now! Once the JVM is finished starting up, the cache spools. After that, it spools during quiet periods or after new classes are put in the cache.

Where is this cache stored?

It's stored (along with other metadata) in your Contrast directory. This is specified by the contrast.dir System property - i.e., -Dcontrast.dir=/tmp/contrast - and defaults to $HOME/.contrast. The cache file is relatively small, even for really big apps on heavy duty containers. For instance, the cache is only a few MB for a big application on WebSphere. A new cache is created every time new rules are enabled, a new JRE is in use, or a new agent has been downloaded.

Can I clear the cache?

Yes! Simply delete the $CONTRAST/cache directory!

Overriding Configuration

If you'd like to override configuration options in your agent, you can run with a custom configuration. To start, let's copy the configuration that's shipped with the agent. The following JAR command will copy the configuration file out of an agent that's been downloaded from the Contrast site:

user:tomcat majordomo$ jar -xf contrast.jar contrast.config

Now that you have a contrast.config file, which is just XML, you can edit it like any other file. However, to tell the agent to use this configuration file, we have to modify our -javaagent line to point to it, as shown here:

export JAVA_OPTS="$JAVAOPTS -javaagent:/tomcat6/contrast.jar=/tomcat6/contrast.config"

The following marked-up contrast.config file shows what can be controlled here:

<?xml version="1.0"?>
<contrast>
   <id/> <!-- Used to 'id' this agent, if such a need exists. -->
   <log level="error" console="false"/> <!-- The level is one of the standard log4j levels. -->
   <global-key>demo</global-key> <!-- Your organization's API Key. Needed for talking to the REST API. -->

   <user>
     <id>contrast_admin</id> <-- Your username. -->
     <key>demo</key> <!-- Your service key, which is needed for talking to the REST API. -->
   </user>

   <!-- 
   Where Contrast results are reported. You can add the following attributes to the 'url' element in order
   to ask Contrast to use a proxy:
      - proxyHost (just the hostname or IP)
      - proxyPort
      - proxyUser
      - proxyPassword
      - proxyAuthenticationType (one of NTLM, Digest or Basic)
    --> 
   <url>https://app.contrastsecurity.com/Contrast/s/</url>
   <local-results mode="never"/> <!-- Results can be captured locally with "error" or "always". -->
   <plugins>
      <!-- The contents of this area shouldn't be altered. -->
   </plugins>
   <capture-stacktraces>ALL</capture-stacktraces> <!-- Set to SOME or NONE to gain performance boosts. -->

   <!--
   Setting 'enabled' to true in the sampling section tells Contrast to skip analysis of redundant of URIs
   after some baseline samples have been collected.
   -->
   <sampling>
      <enabled>false</enabled>
      <baseline>5</baseline>
      <request-frequency>10</request-frequency>
      <response-frequency>50</response-frequency>
      <window>180</window>
    </sampling>
</contrast>

Bytecode Changes

You can ask Contrast to save all of its weavings for analysis by passing a custom system property to the server process:

-Dcontrast.savebytecode=/path/to/bytecode/

This will save the before and after copies of any class that Contrast weaved sensors into during the process, into the given directory. These will be useful for Contrast analysts hoping to understand more complex issues. After running with this feature enabled, the directory given will have a directory full of packages like this:

This feature was introduced in Contrast 2.4.1.

YAML Template

Go to the YAML Properties article for more information about this template.

#================================================================================================================================================================================
#  
#  Use the properties in this YAML file to configure a Contrast agent. Go to https://docs.contrastsecurity.com/ to determine the order of precedence for configuration values. 
#  
#================================================================================================================================================================================


#================================================================================
# Contrast
# Use the properties in this section to connect the agent to the Contrast UI.
#================================================================================
contrast:

  # Only set this property if you want to turn off Contrast. Set to `true` to turn the agent on; set to `false` to turn the agent off.
  # enable: true

  # ********************** REQUIRED **********************
  # Set the URL for the Contrast UI.
  url: https://app.contrastsecurity.com/Contrast

  # ********************** REQUIRED **********************
  # Set the API key needed to communicate with the Contrast UI.
  api_key: NEEDS_TO_BE_SET

  # ********************** REQUIRED **********************
  # Set the service key needed to communicate with the Contrast UI. It is used to calculate the Authorization header.
  service_key: NEEDS_TO_BE_SET

  # ********************** REQUIRED **********************
  # Set the user name used to communicate with the Contrast UI. It is used to calculate the Authorization header.
  user_name: NEEDS_TO_BE_SET

  #======================================================================================
  # Proxy
  # Use the following properties for communication with the Contrast UI over a proxy.
  #======================================================================================
  # proxy:

    # Add a property value to determine if the agent should communicate with the Contrast UI over a proxy. If a property value is not present, the presence of a valid proxy host and port determines enabled status.
    # enable: NEEDS_TO_BE_SET

    # Set the proxy host. It must be set with port and scheme.
    # host: localhost

    # Set the proxy port. It must be set with host and scheme.
    # port: 1234

    # Set the proxy scheme (e.g., `http` or `https`). It must be set with host and port.
    # scheme: http

    # Set this property as an alternate for `scheme://host:port`. It takes precedence over the other settings, if specified; however, an error will be thrown if both the URL and individual properties are set.
    # url: NEEDS_TO_BE_SET

    # Set the proxy user.
    # user: NEEDS_TO_BE_SET

    # Set the proxy password.
    # pass: NEEDS_TO_BE_SET

    # Set the proxy authentication type. Value options are `NTLM`, `Digest`, and `Basic`.
    # auth_type: NEEDS_TO_BE_SET

#=======================================================================================================================================
# Agent
# Use the properties in this section to control the way and frequency with which the agent communicates to logs and the Contrast UI.
#=======================================================================================================================================
# agent:

  # Set how long to run the agent before shutting down itself (in milliseconds). A negative value disables scheduled shutdown.
  # shutdown_time_ms: NEEDS_TO_BE_SET

  # Enable to deinstrumentation classes on shutdown. If this is not enabled, the agent disables sensors on shutdown, but leaves instrumentation.
  # deinstrument_on_shutdown: NEEDS_TO_BE_SET

  #================================================================================================================================================================
  # Logger
  # Define the following properties to set logging values. If the following properties are not defined, the agent uses the logging values from the Contrast UI.
  #================================================================================================================================================================
  # logger:

    # Enable diagnostic logging by setting a path to a log file. While diagnostic logging hurts performance, it generates useful information for debugging Contrast. The value set here is the location to which the agent saves log output. If no log file exists at this location, the agent creates a file. 
    #  Example - */opt/Contrast/contrast.log* creates a log in the */opt/Contrast* directory, and rotates it automatically as needed.
    # path: ./contrast_agent.log

    # Set the the log output level. Valid options are `ERROR`, `WARN`, `INFO`, `DEBUG`, and `TRACE`.
    # level: ERROR

    # Set to `true` to log to STDOUT. Set to `false` for the agent to suppress output to STDOUT.
    # stdout: NEEDS_TO_BE_SET

    # Set to `true` to log to STDERR.
    # stderr: NEEDS_TO_BE_SET

    # Change the Contrast logger from a file-sized based rolling scheme to a date-based rolling scheme. At midnight server time, the log from the previous day log is renamed to *file_name.yyyy-MM-dd*. Note - this scheme does not have a size limit; manual log pruning is required. You must set this flag to use the backups and size flags.
    # roll_daily: false

    # Set the roll size for log files unless `agent.logger.roll_daily=true`.
    # roll_size: 100M

    # Set the number of backup files to keep.
    # backups: 10

  #===========================================================================================================================================================
  # Security_logger
  # Define the following properties to set security logging values. If not defined, the agent uses the security logging (CEF) values from the Contrast UI.
  #===========================================================================================================================================================
  # security_logger:

    # Set the file to which the agent logs security events.
    # path: /.contrast/security.log

    # Set the log level for security logging. Value options are `OFF`, `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, and `ALL`. Set this property to `OFF` to disable security logging.
    # level: NEEDS_TO_BE_SET

    # Change the Contrast security logger from a file-sized based rolling scheme to a date-based rolling scheme. At midnight server time, the log from the previous day is renamed to *file_name.yyyy-MM-dd*. Note - this scheme does not have a size limit; manual log pruning will be required. This flag must be set to use the backups and size flags. Value options are `true` or `false`.
    # roll_daily: NEEDS_TO_BE_SET

    # Specify the file size cap (in MB) of each log file.
    # roll_size: NEEDS_TO_BE_SET

    # Specify the number of backup logs that the agent will create before Contrast cleans up the oldest file. A value of `0` means that no backups are created, and the log is truncated when it reaches its size cap. 
    #  Note - this property must be used with `agent.security_logger.roll_daily=false`; otherwise, Contrast continues to log daily and disregard this limit.
    # backups: NEEDS_TO_BE_SET

    #====================================================================================================================================================
    # Syslog
    # Define the following properties to set Syslog values. If the properties are not defined, the agent uses the Syslog values from the Contrast UI.
    #====================================================================================================================================================
    # syslog:

      # Set to `true` to enable Syslog logging.
      # enable: NEEDS_TO_BE_SET

      # Set the IP address of the Syslog server to which the agent should send messages.
      # ip: NEEDS_TO_BE_SET

      # Set the port of the Syslog server to which the agent should send messages.
      # port: NEEDS_TO_BE_SET

      # Set the facility code of the messages the agent sends to Syslog.
      # facility: NEEDS_TO_BE_SET

      # Set the log level of Exploited attacks. Value options are `ALERT`, `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.
      # severity_exploited: NEEDS_TO_BE_SET

      # Set the log level of Blocked attacks. Value options are `ALERT`, `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.
      # severity_blocked: NEEDS_TO_BE_SET

      # Set the log level of Probed attacks. Value options are `ALERT`, `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.
      # severity_probed: NEEDS_TO_BE_SET

  #==========================================================================
  # Java
  # The following properties apply to any Java agent-wide configurations.
  #==========================================================================
  # java:

    # Set the name of a standalone application. If this value is set, the agent assumes there is only one application in this server.
    # standalone_app_name: NEEDS_TO_BE_SET

#===========================================================================
# Inventory
# Use the properties in this section to override the inventory features.
#===========================================================================
# inventory:

  # Set to `false` to disable inventory features in the agent.
  # enable: true

  # Define a list of directories where libraries are stored. Directories must be formatted as a semicolon-delimited list. \n Example - path1;path2;path3
  # library_dirs: NEEDS_TO_BE_SET

  # Set the maximum archive unpacking depth when analyzing libraries.
  # library_depth: 10

  # Set to `false` to disable inventory features in the agent.
  # prune_package_details: true

  # Apply a list of labels to libraries. Labels must be foratted as a comma-delimited list. \n Example - label1, label2, label3
  # tags: NEEDS_TO_BE_SET

#==========================================================
# Assess
# Use the properties in this section to control Assess.
#==========================================================
# assess:

  # Include this property to determine if the Assess feature should be enabled. If this property is not present, the decision is delegated to the Contrast UI.
  # enable: true

  # Apply a list of labels to vulnerabilities and preflight messages. Labels must be formatted as a comma-delimited list. \n Example - label1, label2, label3
  # tags: NEEDS_TO_BE_SET

  #===================================================================
  # Sampling
  # Use the following properties to control sampling in the agent.
  #===================================================================
  # sampling:

    # Set to `false` to disable sampling.
    # enable: true

    # This property indicates how many requests to analyze in each window before sampling begins.
    # baseline: 5

    # This property indicates that every *nth* request after the baseline is analyzed.
    # request_frequency: 10

    # This property indicates the duration for which a sample set is valid.
    # window_ms: 180_000

  #========================================================================
  # Rules
  # Use the following properties to control simple rule configurations.
  #========================================================================
  # rules:

    # Define a list of Assess rules to disable in the agent. The rules must be formatted as a comma-delimited list. 
    #  Example - Set "reflected-xss,sql-injection" to disable the reflected-xss rule and the sql-injection rule.
    # disabled_rules: NEEDS_TO_BE_SET

#=====================================================================
# Protect
# Use the properties in this section to override Protect features.
#=====================================================================
# protect:

  # Use the properties in this section to determine if the Protect feature should be enabled. If this property is not present, the decision is delegated to the Contrast UI.
  # enable: true

  #====================================================================
  # Rules
  # Use the following properties to set simple rule configurations.
  #====================================================================
  # rules:

    # Define a list of Protect rules to disable in the agent. The rules must be formatted as a comma-delimited list.
    # disabled_rules: NEEDS_TO_BE_SET

    #================================================================================
    # Bot-blocker
    # Use the following properties to configure if and how the agent blocks bots.
    #================================================================================
    # bot-blocker:

      # Set to `true` for the agent to block known bots.
      # enable: false

    #=====================================================================================================================================================
    # Sql-injection
    # Use the following properties to override a specific Protect rule. The key is the rule ID in the Contrast UI with dashes replaced by underscores.
    #=====================================================================================================================================================
    # sql-injection:

      # Set the mode of the rule. Value options are `monitor`, `block`, `block_at_perimeter`, or off. 
      #  Note - If a setting says, "if blocking is enabled", the setting can be `block` or `block_at_perimeter`.
      # mode: monitor

    #====================================================================================
    # Cmd-injection
    # Use the following properties to configure how the command injection rule works.
    #====================================================================================
    # cmd-injection:

      # Set the mode of the rule. Value options are `monitor`, `block`, `block_at_perimeter`, or `off`. 
      #  Note - If a setting says, "if blocking is enabled", the setting can be `block` or `block_at_perimeter`.
      # mode: monitor

    #=================================================================================
    # Path-traversal
    # Use the following properties to configure how the path traversal rule works.
    #=================================================================================
    # path-traversal:

      # Set the mode of the rule. Value options are `monitor`, `block`, `block_at_perimeter`, or `off`. 
      #  Note - If a setting says, "if blocking is enabled", the setting can be `block` or `block_at_perimeter`.
      # mode: monitor

    #===================================================================================
    # Method-tampering
    # Use the following properties to configure how the method tampering rule works.
    #===================================================================================
    # method-tampering:

      # Set the mode of the rule. Value options are `monitor`, `block`, `block_at_perimeter`, or `off`. 
      #  Note - If a setting says, "if blocking is enabled", the setting can be `block` or `block_at_perimeter`.
      # mode: monitor

    #=================================================================================================
    # Reflected-xss
    # Use the following properties to configure how the reflected cross-site scripting rule works.
    #=================================================================================================
    # reflected-xss:

      # Set the mode of the rule. Value options are `monitor`, `block`, `block_at_perimeter`, or `off`. 
      #  Note - If a setting says, "if blocking is enabled", the setting can be `block` or `block_at_perimeter`.
      # mode: monitor

    #=================================================================================
    # Xxe
    # Use the following properties to configure how the XML external entity works.
    #=================================================================================
    # xxe:

      # Set the mode of the rule. Value options are `monitor`, `block`, `block_at_perimeter`, or `off`. 
      #  Note - If a setting says, "if blocking is enabled", the setting can be `block` or `block_at_perimeter`.
      # mode: monitor

    #=============================================================================================
    # Csrf
    # Use the following properties to configure how the cross-site request forgery rule works.
    #=============================================================================================
    # csrf:

      # Set the mode of the rule. Value options are `monitor`, `block`, `block_at_perimeter`, or `off`. 
      #  Note - If a setting says, "if blocking is enabled", the setting can be `block` or `block_at_perimeter`.
      # mode: monitor

#==================================================================================
# Application
# Use the properties in this section for the application(s) hosting this agent.
#==================================================================================
# application:

  # Override the reported application name.
  # name: NEEDS_TO_BE_SET

  # Override the reported application path.
  # path: NEEDS_TO_BE_SET

  # Add the name of the application group with which this application should be associated in the Contrast UI.
  # group: NEEDS_TO_BE_SET

  # Add the application code this application should use in the Contrast UI.
  # code: NEEDS_TO_BE_SET

  # Override the reported application version.
  # version: NEEDS_TO_BE_SET

  # Apply labels to an application. Labels must be formatted as a comma-delimited list. 
  #  Example - label1,label2,label3
  # tags: NEEDS_TO_BE_SET

  # Define a set of key=value pairs (which conforms to RFC 2253) for specifying user-defined metadata associated with the application. The set must be formatted as a comma-delimited list of `key=value` pairs. 
  #  Example - "business-unit=accounting, office=Baltimore"
  # metadata: NEEDS_TO_BE_SET

#==========================================================================================
# Server
# Use the properties in this section to set metadata For the server hosting this agent.
#==========================================================================================
# server:

  # Override the reported server name.
  # name: test-server-1

  # Override the reported server path.
  # path: NEEDS_TO_BE_SET

  # Override the reported server type.
  # type: NEEDS_TO_BE_SET

  # Override the reported server build.
  # build: NEEDS_TO_BE_SET

  # Override the reported server version.
  # version: NEEDS_TO_BE_SET

  # Override the reported server environment.
  # environment: development

  # Apply a list of labels to the server. Labels must be formatted as a comma-delimited list. 
  #  Example - label1,label2,label3 
  # tags: NEEDS_TO_BE_SET