Configuration

Configuration Properties

The Python agent and Contrast Service use a YAML file to alter the agent behavior. Go to the Python YAML Template for fully formatted properties that you can copy and use in your own configuration files.

Order of Precedence

The configuration file is named contrast_security.yaml or contrast_security.yml no matter where it's located. The Python agent loads the configuration YAML from the following paths in order of precedence (where 1 is the highest):

  1. Any path saved in the environment variable CONTRAST_CONFIG_PATH
  2. The settings directory within the current directory (e.g., ./settings/contrast_security.yaml)
  3. The current working directory (e.g., ./contrast_security.yaml)
  4. Within the server's etc/contrast/python directory (e.g., /etc/contrast/python/contrast_security.yaml)
  5. Within the server's etc/contrast directory (e.g., /etc/contrast/contrast_security.yaml)

The agent and service may share a common configuration file, but only some options and sections are applicable to each process.

Configuration Options

Enable the agent

  • 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.

Contrast UI properties

Use the properties in this section to connect the agent to the Contrast UI.

  • api:
    • url: Set the URL for the Contrast UI. Required.
      Example: https://app.contrastsecurity.com/Contrast
    • 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.
    • last_config_path: Set the path to which the agent should store the currently used configuration from the Contrast UI.
      Example: ./tmp/config

Certificate

Use the following properties for communication with the Contrast UI using certificates.

  • certificate:
    • enable: If set to false, the agent ignores the certificate configuration in this section.
    • ca_file: Set the absolute or relative path to a CA for communication with the Contrast UI using a self-signed certificate.
    • cert_file: PSet the absolute or relative path to the Certificate PEM file for communication with the Contrast UI.
    • key_file: Set the absolute or relative path to the Key PEM file for communication with the Contrast UI.

Contrast agent properties

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

Logger

Define the following properties to set logging values. If these properties aren't defined, the agent uses the logging values from the Contrast UI.

  • agent: Options for communicating between the agent and the service
    • 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 the log output level. Value options are ERROR, WARN, INFO, and DEBUG.
      • progname: Set the name the agent uses to identify the process within the log file
        Example: Contrast Agent

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:
    • 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 level for security logging. Valid options are ERROR, WARN, INFO, DEBUG, and TRACE.
    • 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
Syslog

Define the following properties to set Syslog values. If the properties aren't defined, the agent uses the Syslog values from the Contrast UI.

  • 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.

Service

The following properties are used by the Contrast Service.

  • service:
    • enable: Set to false to disallow the service to be started, and effectively disable the agent, if read by the service. If the agent reads this property, it disallows service auto-start.
    • socket: If this property is defined, the service is listening on a Unix socket at the defined path.
      Example: /tmp/service.sock
    • host: Set the the hostname or IP address of the Contrast service to which the Contrast agent should report. Required.
      Example: localhost
    • port: Set the the port of the Contrast service to which the Contrast agent should report. Required.
      Example: 30555
Logger

The following properties are used by the logger in the Contrast service. If the properties are not defined, the service uses the logging values from the Contrast UI.

  • logger:
    • path: Set the location to which the Contrast service saves log output. If no log file exists at this location, the service creates one.
      Example: /opt/Contrast/contrast_service.log will create a log in the /opt/Contrast directory.
    • level: Set the the log output level. Value options are ERROR, WARN, INFO, and DEBUG.
    • progname: Set the name the agent uses to identify the process within the service log file
      Example: Contrast Agent

Inventory properties

Use the properties in this section to override the inventory features.

  • inventory:
    • enable: 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 Protect properties

Use the properties in this section to override Protect features.

  • 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.

Contrast Assess properties

Use the properties in this section to override Assess features (beta).

  • assess:
    • enable: Set to true to enable or false to disable. Default behavior is delegated to Contrast UI. Note that protect and assess cannot be enabled at the same time.

Application properties

Use the properties in this section for the application(s) hosting each agent.

  • application:
    • name: Override the reported application name.
      Note: On Java systems where multiple, distinct applications may be served by a single process, this configuration causes the agent to report all discovered applications as one application with the given name.
    • 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"
    • session_id: Provide the ID of a session which already exists in the Contrast UI. Vulnerabilities discovered by the agent are associated with this session. If an invalid ID is supplied, the agent will be disabled. This option and application.session_metadata are mutually exclusive; if both are set, the agent will be disabled.
    • session_metadata: Provide metadata which is used to create a new session ID in the Contrast UI. Vulnerabilities discovered by the agent are associated with this new session. This value should be formatted as key=value pairs (conforming to RFC 2253). Available key names for this configuration are branchName, buildNumber, commitHash, committer, gitTag, repository, testRun, and version. This option and application.session_id are mutually exclusive; if both are set the agent will be disabled.

Server properties

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

  • server:
    • name: Override the reported server name.
      Example: test-server-1
    • path: Override the reported server path.
    • type: Override the reported server type.
    • 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

YAML Template

Go to the Python Configuration 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.
# ==============================================================================


# 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

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

  # ********************** 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

  # Set the path to which the agent should store the
  # currently used configuration from the Contrast UI.
  # last_config_path: ./tmp/config

  # ============================================================================
  # api.certificate
  # Use the following properties for communication
  # with the Contrast UI using certificates.
  # ============================================================================
  # certificate:

    # If set to `false`, the agent will ignore the
    # certificate configuration in this section.
    # enable: true

    # Set the absolute or relative path to a CA for communication
    # with the Contrast UI using a self-signed certificate.
    # ca_file: NEEDS_TO_BE_SET

    # Set the absolute or relative path to the Certificate
    # PEM file for communication with the Contrast UI.
    # cert_file: NEEDS_TO_BE_SET

    # Set the absolute or relative path to the Key PEM
    # file for communication with the Contrast UI.
    # key_file: 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:

  # ============================================================================
  # agent.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

    # Override the name of the process the agents uses in logs.
    # progname: Contrast Agent

  # ============================================================================
  # agent.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. Valid options
    # are `ERROR`, `WARN`, `INFO`, `DEBUG`, and `TRACE`.
    # level: ERROR

    # 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

    # ==========================================================================
    # agent.security_logger.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

  # ============================================================================
  # agent.service
  # The following properties are used by the Contrast Service.
  # ============================================================================
  service:

    # Set to `false` to disallow the service to be started, and
    # effectively disable the agent, if read by the service. If the
    # agent reads this property, it disallows service auto-start.
    # enable: true

    # If this property is defined, the service is
    # listening on a Unix socket at the defined path.
    # socket: /tmp/service.sock

    # ********************** REQUIRED **********************
    # Set the the hostname or IP address of the Contrast
    # service to which the Contrast agent should report.
    host: localhost

    # ********************** REQUIRED **********************
    # Set the the port of the Contrast service
    # to which the Contrast agent should report.
    port: 30555

    # ==========================================================================
    # agent.service.logger
    # The following properties are used by the logger in the
    # Contrast service. If the properties are not defined, the
    # service uses the logging values from the Contrast UI.
    # ==========================================================================
    # logger:

      # Set the location to which the Contrast service saves log output.
      # If no log file exists at this location, the service creates one.
      #  
      # Example - */opt/Contrast/contrast_service.log* will
      # create a log in the */opt/Contrast* directory.
      # path: ./contrast_service.log

      # Set the the log output level. Options are `OFF`, `FATAL`,
      # `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, and `ALL`.
      # level: ERROR

  # ============================================================================
  # agent.python
  # The following properties apply to any Python agent-wide configurations.
  # ============================================================================
  # python: {}

# ==============================================================================
# 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

  # 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

# ==============================================================================
# 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

  # ============================================================================
  # protect.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

    # ==========================================================================
    # protect.rules.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

    # ==========================================================================
    # protect.rules.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

      # Tell the agent to detect when semantic analysis of the query
      # reveals tautologies used in exfiltration attacks (e.g., \"or
      # 1=1\" or \"or 2<>3\"). The agent blocks if blocking is enabled.
      # detect_tautologies: true

      # Tell the agent to detect when semantic analysis of the query
      # reveals the invocation of dangerous functions typically used in
      # weaponized exploits. The agent blocks if blocking is enabled.
      # detect_dangerous_functions: true

      # Tell the agent to detect when semantic analysis of the query
      # reveals chained queries, which is uncommon in normal usage but
      # common in exploit. The agent blocks if blocking is enabled.
      # detect_chained_queries: true

      # Tell the agent to detect when semantic analysis of the query
      # reveals database queries are being made for system tables and
      # sensitive information. The agent blocks if blocking is enabled.
      # detect_suspicious_unions: true

    # ==========================================================================
    # protect.rules.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

    # ==========================================================================
    # protect.rules.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

      # Detect when custom code attempts to access sensitive
      # system files. The agent blocks if blocking is enabled.
      # detect_custom_code_accessing_system_files: true

      # Detect when users attempt to bypass filters by
      # using \"::$DATA\" channels or null bytes in file
      # names. The agent blocks if blocking is enabled.
      # detect_common_file_exploits: true

    # ==========================================================================
    # protect.rules.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

    # ==========================================================================
    # protect.rules.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

    # ==========================================================================
    # protect.rules.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

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

  # Override the reported application name.
  #  
  # Note - On Java systems where multiple, distinct applications may be
  # served by a single process, this configuration causes the agent to report
  # all discovered applications as one application with the given 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 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