Configuration

YAML Properties

Contrast supports YAML-based configuration for the .NET agent. This allows you to store configuration on disk that you can override with environment variables or command line arguments. Go to the .NET YAML Template for fully formatted properties that you can copy and use in your own configuration files.

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

Order of Precedence

Configuration values use the following order of precedence:

  1. Corporate rule (e.g., expired license overrides assess.enable)
  2. Specific environmental variable
  3. Generic environment variable value
  4. Application-specific configuration file value (i.e. web.config)
  5. User configuration file value (i.e. contrast_security.yaml)
  6. Contrast UI value
  7. Default value

Load Path

The contrast_security.yaml file should be placed on the file system using one of the following methods:

  • Specify the path to the YAML file with the environment variable CONTRAST_CONFIG_PATH.
  • Place the contrast_security.yaml file in the data directory specified during agent install. (The default location is %ProgramData%\Contrast\dotnet\. As a result, the default file path would be %ProgramData%\Contrast\dotnet\contrast_security.yaml.)

Environment Variables

You can use environment variables to specify every configuration option supported by the contrast_security.yaml file. Environment variable names are derived from the YAML path by replacing path segment delimiters (.) with double underscores (__) and prefixing the result with CONTRAST__. For example, server.name becomes CONTRAST__SERVER__NAME while api.api_key becomes CONTRAST__API__API_KEY.

Use web.config

You can also specify the application configuration options in an application's web.config file. For the agent to pick up customized application settings, you must place these settings in the application web.config file's root configuration appSettings section.

Configuration option names in web.config files are derived from the YAML path prefixed with contrast.. For example, application.name becomes contrast.application.name.

You can specify the following application-specific configuration options in each application's web.config file:

  • contrast.application.name
  • contrast.application.version
  • contrast.application.group
  • contrast.application.metadata
  • contrast.application.tags
  • contrast.inventory.tags
  • contrast.assess.tags

If contrast.application.name is not specified, the .NET agent will use the application's virtual path as an application name. If the application is hosted in the root of a site (i.e., the virtual path is /), the .NET agent will use the site's name as the application name.

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 .NET agent to the Contrast UI. The proxy settings allow the agent to communicate with the Contrast UI over a proxy.

  • api:
    • 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.
    • tls_versions: Set the version of the TLS protocol the agent uses to communicate with the Contrast UI. The .NET agent default behavior is (SecurityProtocolType.Tls | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls12).
      Examples: (tls|tls11|tls12),tls12,(tls11|tls12)

Certificate

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

  • certificate:
    • enable: If set to false, the agent will ignore the certificate configuration in this section.
    • certificate_location: Determine the location from which the agent loads a client certificate. Value options include File or Store.
    • cer_file: Set the absolute path to the client certificate's .CER file for communication with Contrast UI. The certificate_location property must be set to File.
    • store_name: Specify the name of certificate store to open. The certificate_location property must be set to Store. Value options include AuthRoot, CertificateAuthority, My, Root, TrustedPeople, or TrustedPublisher.
    • store_location: Specify the location of the certificate store. The certificate_location property must be set to Store. Value options include CurrentUser or LocalMachine.
    • find_type: Specify the type of value the agent uses to find the certificate in the collection of certificates from the certificate store. The certificate_location property must be set to Store. Value options include FindByIssuerDistinguishedName, FindByIssuerName, FindBySerialNumber, FindBySubjectDistinguishedName, FindBySubjectKeyIdentifier, FindBySubjectName, or FindByThumbprint.
    • find_value: Specify the value the agent uses in combination with find_type to find a certification in the certificate store.
      Note: The agent will use the first certificate from the certificate store that matches this search criteria.

Proxy

Use the following properties for communication with the Contrast UI over a proxy.

  • 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
    • url: Set the URL of the proxy server.
    • 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 the way and frequency with which the .NET agent 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:

Auto-update

Use the following properties to control auto-update behavior of the .NET agent.

Note: These settings don't apply to the .NET Core agent, which doesn't have the capability to auto-update.

  • auto_update:
    • enable: Set to true for the agent to automatically upgrade to newer versions.
    • checks: Set the frequency with which the agent checks for updates. Valid values are daily for every 24 hours and on startup, or startup for only when service starts up.

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.

  • logger:
    • level: Set the the log output level. Value options are OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, and ALL.

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:
    • level: Set the log level for security logging. Value options are ERROR, WARN, INFO, DEBUG, and TRACE.
    • connection_type: Specify if a connection should be encrypted or plain text. Value options are ENCRYPTED or UNENCRYPTED.
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:
    • 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

The following properties apply to any .NET agent-wide configurations.

  • dotnet:

    • app_pool_blacklist: Set a list of application pool names that the agent does not instrument or analyze. Names must be formatted as a comma-separated list.
    • app_pool_whitelist: Set a list of application pool names that the agent instruments or analyzes. If set, other application pools are ignored. Whitelist takes precedence over blacklist. Names must be formatted as a comma-separated list.
    • enable_clr2_analysis: Enable instrumentation and analysis of application pools targeting CLR2.
    • enable_chaining: Enable the profiler chaining feature to allow Contrast to work alongside other tools that use the CLR Profiling API.
    • enable_dvnr: Indicate that the agent should produce a report that summarizes application hosting on the server (e.g., CLR versions, bitness or pipeline modes).
    • enable_instrumentation_optimizations: Indicate that the agent should allow CLR optimizations of JIT-compiled methods.
    • enable_jit_inlining: Indicate that the agent should allow the CLR to inline methods that are not instrumented by Contrast.
    • enable_transparency_checks: Indicate that the agent should allow the CLR to perform transparency checks under full trust.
    • restart_iis_on_config_change: Indicate that the agent should automatically restart IIS to apply certain configuration changes (e.g., app_pool_blacklist).
    • skip_profiler_check: Indicate that the agent should not check for other profilers before starting.
    • thread_analysis: Valid values are full or web. Full indicates instrumenting all threading operations to fully follow dataflow. Web indicates following dataflow only through built-in sync and async web operations, but not user-managed threads/tasks. Using web can improve agent performance.
    • web_module_whitelist: Responses for request paths (e.g., HttpRequest.Path) that match this regex are not analyzed. See the troubleshooting article for more information.
      Example: WebResource.axd

Inventory properties

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

  • 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 Assess properties

Use the properties in this section to control Assess in the .NET 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
    • event_detail: Control the values captured by Assess vulnerability events. Full captures most values by calling ToString on objects, which can provide more info but causes increased memory usage. Minimal has better performance as it only captures String type objects as strings and uses type name for other object type values.
    • tags: Apply a list of labels to vulnerabilities and preflight messages. Labels must be formatted as a comma-delimited list. Example: label1, label2, label3
    • stacktraces: Value options are ALL, SOME, or NONE.

    • sampling:

      • enable: Set to false to disable sampling.
      • baseline: This property indicates the number of 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 this property to determine if the Protect feature should be enabled. If this property is not present, the decision is delegated to the Contrast UI.

    • analysis_cache: Use this property to control the behavior of the cache used to store the results of analysis for duplicate inputs. Set to false to disable the use of the analysis cache.

    • 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.
      • untrusted-deserialization:

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

Application properties

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

  • application:
    • group: Add the name of the application group with which this application should be associated 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
    • 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

Example Configurations

You can add the following examples to an existing contrast_security.yaml file to achieve the desired behavior.

Enable profiler chaining

The following configuration enables profiler chaining. This allows the .NET agent to work alongside other tools that use the CLR Profiling API, such as performance APMs.

agent:
  dotnet:
    enable_chaining: true

Whitelist an application pool for instrumentation

The following configuration excludes all application pools except ExampleAppPool and Fabrikam from instrumentation by the .NET agent. This can help improve performance on applications you don't want to analyze.

agent:
  dotnet:
    app_pool_whitelist: ExampleAppPool,Fabrikam

Disable auto-update

The following configuration disables the auto-update feature that automatically downloads and installs new versions of the .NET agent from Contrast.

agent:
  auto_update:
    enable: false

Combined example

The following configuration enables profiler chaining, specifies an application pool whitelist, disables auto-update and sets the server name to "MyServer".

agent:
  auto_update:
    enable: false
  dotnet:
    enable_chaining: true
    app_pool_whitelist: ExampleAppPool
server:
  name: MyServer

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


# 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 version of the TLS protocol the agent uses to communicate with the
  # Contrast UI. The .NET agent default behavior is (SecurityProtocolType.Tls
  # | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls12).
  # tls_versions: tls1|tls2|tls3

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

    # Determine the location from which the agent loads a client
    # certificate. Value options include `File` or `Store`.
    # certificate_location: NEEDS_TO_BE_SET

    # Set the absolute path to the client certificate's
    # .CER file for communication with Contrast UI. The
    # `certificate_location` property must be set to `File`.
    # cer_file: NEEDS_TO_BE_SET

    # Specify the name of certificate store to open. The
    # `certificate_location` property must be set to `Store`.
    # Value options include `AuthRoot`, `CertificateAuthority`,
    # `My`, `Root`, `TrustedPeople`, or `TrustedPublisher`.
    # store_name: NEEDS_TO_BE_SET

    # Specify the location of the certificate store. The
    # `certificate_location` property must be set to `Store`.
    # Value options include `CurrentUser` or `LocalMachine`.
    # store_location: NEEDS_TO_BE_SET

    # Specify the type of value the agent uses to find the certificate
    # in the collection of certificates from the certificate store.
    # The `certificate_location` property must be set to `Store`.
    # Value options include `FindByIssuerDistinguishedName`,
    # `FindByIssuerName`, `FindBySerialNumber`,
    # `FindBySubjectDistinguishedName`, `FindBySubjectKeyIdentifier`,
    # `FindBySubjectName`, or `FindByThumbprint`.
    # find_type: NEEDS_TO_BE_SET

    # Specify the value the agent uses in combination with
    # `find_type` to find a certification in the certificate store.
    #  
    # Note - The agent will use the first certificate from
    # the certificate store that matches this search criteria.
    # find_value: NEEDS_TO_BE_SET

  # ============================================================================
  # api.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 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:

  # ============================================================================
  # agent.auto_update
  # TODO
  # ============================================================================
  # auto_update:

    # Set to `true` for the agent to automatically upgrade to newer versions.
    # enable: true

    # Set the frequency with which the agent checks for updates.
    # Valid values are `daily` for every 24 hours and on
    # startup, or `startup` for *only* when service starts up.
    # checks: daily

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

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

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

    # Specify if connection should be encrypted or plaintext.
    # Value options are `ENCRYPTED` or `UNENCRYPTED`.
    # connection_type: 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.dotnet
  # The following properties apply to any .NET agent-wide configurations.
  # ============================================================================
  # dotnet:

    # Set a list of application pool names that the agent does not instrument
    # or analyze. Names must be formatted as a comma-separated list.
    # app_pool_blacklist: NEEDS_TO_BE_SET

    # Set a list of application pool names that the agent
    # instruments or analyzes. If set, other application pools
    # are ignored. Whitelist takes precedence over blacklist.
    # Names must be formatted as a comma-separated list.
    # app_pool_whitelist: NEEDS_TO_BE_SET

    # Enable instrumentation and analysis of application pools targeting CLR2.
    # enable_clr2_analysis: true

    # Enable an experimental profiler chaining feature to allow Contrast
    # to work alongside other tools that use the CLR Profiling API.
    # enable_chaining: false

    # Indicate that the agent should produce a report
    # that summarizes application hosting on the server
    # (e.g., CLR versions, bitness or pipeline modes).
    # enable_dvnr: true

    # Indicate that the agent should allow CLR
    # optimizations of JIT-compiled methods.
    # enable_instrumentation_optimizations: true

    # Indicate that the agent should allow the CLR to
    # inline methods that are not instrumented by Contrast.
    # enable_jit_inlining: true

    # Indicate that the agent should automatically restart IIS to
    # apply certain configuration changes (e.g., app_pool_blacklist).
    # restart_iis_on_config_change: true

    # Indicate that the agent should not check
    # for other profilers before starting.
    # skip_profiler_check: false

    # Valid values are `full` or `web`. `Full` indicates instrumenting all
    # threading operations to fully follow dataflow. `Web` indicates following
    # dataflow only through built-in sync and async web operations, but not
    # user-managed threads/tasks. Using `web` can improve agent performance.
    # thread_analysis: full

    # Responses for request paths (e.g., HttpRequest.Path)
    # that match this regex are not analyzed. See
    # https://docs.contrastsecurity.com/troubleshooting-netissues.html#zero
    # for more information.
    # web_module_whitelist: WebResource.axd

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

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

  # Control the values captured by Assess vulnerability events. `Full`
  # captures most values by calling ToString on objects, which can
  # provide more info but causes increased memory usage. `Minimal`
  # has better performance as it only captures String type objects
  # as strings and uses type name for other object type values.
  # event_detail: minimal

  # 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

  # Value options are `ALL`, `SOME`, or `NONE`.
  # stacktraces: ALL

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

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

    # This property indicates the number of 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

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

  # ============================================================================
  # protect.analysis_cache
  # Use the properties in this section to control the behavior of the
  # cache used to store the results of analysis for duplicate inputs.
  # ============================================================================
  # analysis_cache:

    # Set to `false` to disable the use of the analysis cache.
    # 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

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

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

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

General Settings for Windows

The Contrast configuration file DotnetAgentService.exe.config contains several settings that you can modify to change the behavior of the .NET agent for Windows. In all cases, configuration values in the agent configuration file will override any configuration values that have the same name specified in the Contrast UI (e.g., logging level, sampling and stack trace configuration).

Note: These configuration values are considered legacy configuration options. New configuration values will only be supported via YAML-based configuration. All users are encouraged to migrate to YAML configuration properties.

General

Parameter Description Version
AutoUpdateBehavior Determines if the agent automatically updates to a newer version when a newer version is available on Contrast. The default value is Daily.
  • Daily: The agent checks for a new version on service start and every 24 hours afterwards.
  • Startup: The agent only checks for and installs updates on service start
  • Disabled: The agent checks for, but doesn't install, any updates.
  • 4.6+
    OverrideExistingProfiler Due to .NET Profiling API technology limitations, only one program can use it at a time. This API is commonly used by APM agents like NewRelic, AppDynamics or DynaTrace. By default, this is set to "false"; the Contrast agent will fail to start if it detects another program using the .NET Profiling API so that the other program can continue working. If set to "true", Contrast will attempt to force itself to start, which will break the other agent. 18.3.4+
    RestartIISOnConfigChange Contrast will automatically restart IIS in the background when any configuration settings that require IIS restart are changed. Changes that enable or disable Assess or Defend mode, add security controls, or change process whitelist or blacklist require restart. These changes can come from changing the application config file or from the Contrast website. The default value is "true". If set to "false", you must restart IIS for changes to the given configuration settings to take effect. 3.2.7+
    RouteDiscoveryEnabled Turn on and off the route coverage collection feature. The default is "true". If set to "false", routes will not be collected for supported .NET frameworks. 18.8.23

    Communication

    Parameter Description Version
    TeamServerUrl Overrides the Contrast URL that's packaged with the agent. This can be useful for networks that proxy the information. All
    ProxyAuth, ProxyAddress Controls the proxy used by the agent (if any) to connect to the Contrast interface. Proxy credentials (if applicable) are stored in a separate DotnetAgent.Protected section as described below. All
    EncryptProtectedSettings Controls whether ProxyUser and ProxyPass settings are encrypted. See the Proxy Credentials section below. 4.2.0+
    TlsVersion Controls the version of TLS that the agent uses to communicate with the Contrast interface. Valid TlsVersion values include Tls, Tls11 and Tls12. Agent default behavior is SecurityProtocolType.Tls | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls12. 3.3.6+

    Proxy credentials

    To avoid storing sensitive proxy credentials in plain text, the agent stores them in the DotnetAgent.Protected section which is encrypted on startup. To change existing credentials, delete the contents of the section and manually add the keys. They will be re-encrypted on the next agent service startup. To turn off this encryption, use the set EncryptProtectedSettings setting given in the previous section.

    Parameter Description Version
    ProxyUser Username for the proxy All
    ProxyPass Password for the proxy All

    Display Customization and Tagging

    Parameter Description Version
    ServerName Customizes the display name used by the Contrast interface for the server running the .NET agent. If the ServerName configuration setting is not present, the .NET agent will use the computer name for the server's display name. You can view the computer name by viewing the System properties in the Windows Control Panel. 3.1.4+
    Contrast.AppVersion Controls the application version tag sent to Contrast. 3.3.6+
    Contrast.AppGroup Specifies the group to which this application will be added in the Contrast UI, if this application is not already a member of a group. 3.4.5+
    ServerEnvironment Controls the environment value sent to Contrast when servers are created. Valid ServerEnvironment values are DEVELOPMENT, QA or PRODUCTION (case insensitive). The default value is QA. This does not affect servers that already exist in Contrast. 3.4.2+
    ServerTags Controls free-form tags sent to Contrast for servers; you can use tags to search for servers in the Contrast interface. See the article on Application-Specific Settings for details on tagging applications, libraries and vulnerabilities. 4.8.20+

    Note: Setting any of the Contrast.* (e.g., Contrast.AppVersion) parameters in the agent's configuration file will cause the agent to use the same parameter value for all applications that do not have that parameter set in their web.config file. See the article on Application-Specific Settings for more details.

    Diagnostics

    More detailed levels of logging degrade performance, but can generate useful information for debugging Contrast. The logging level is configured in Server Settings in the Contrast interface by default; however, you can also configure it at the agent level.

    LogLevel Controls
    Error Only log error conditions, such as unhandled exceptions
    Warn Error messages and unexpected conditions that don't impact the agent
    Info Error and Warn messages as well as general information about the agent's sensors (startup, shutdown, start and end of requests, etc.)
    Debug Info messages and some high-level debugging information (e.g., number of vulnerabilities detected for a request)
    Trace Debug messages as well as logging every trace event (e.g., String.Concat); this logging level greatly degrades performance


    Parameter Description Version
    ShouldLogMethodSignatures Controls logging of method signatures during CLR JIT compilation. The default value is "false". Set to "true" to enable method signature logging. This setting has a noticeable impact on startup time but can help troubleshoot issues during application startup. All

    Performance

    Parameter Description
    SamplingBaseline, SamplingFrequency, SamplingWindow Enable and configure sampling mode. Configured in Server Settings in the Contrast interface by default. See the article on Sampling for more information.
    StackTraceConfig Limits stack traces captured by the agent. Configured in Server Settings in the Contrast interface by default. The default is Full.
  • Full: Captures all stack traces with file and line number information. Deployments must include .PDB files for line number information.
  • Limited: Better performance; captures all stack traces but without file and line number information. Best used for builds without debugging symbols (.PDB files).
  • Minimal: Best performance; doesn't capture intermediate propagator stack traces, no file and line information. Best used for Release builds and Production environments.
  • ThreadAnalysis Web (default) or Full. Web follows data flow through normal web operations. Full instruments all threading operations which adds overhead. It can be used for more thorough analysis if your application manually creates background threads.
    DetectPotentialSecurityControls Set to "true" or "false" (default). All code signatures will be checked if they are a potential security validator or sanitizer, when their code is JIT compiled. Detected signatures are reported to Contrast website and can be set as validators or sanitizers there. Set it to "false" to slightly improve start-up performance or bypass issues with this feature.

    Analysis

    Parameter Description
    ResponseUrlWhiteListRegex Controls the .NET agent's collection and analysis of response headers and bodies. Responses aren't captured and are analyzed for request paths (HttpRequest.Path) that match this regex. This setting is required to work around a known Microsoft bug in the .NET framework (HttpModules) with filters can cause resources such as WebResource.axd to return 0 bytes. (This can result in 500 status responses for embedded resources, such as images.) The default value is WebResource.axd.
    ProcessBlacklist Controls the .NET agent's monitoring of application pools. Set the value of this setting to a comma-separated list of application pool names that the agent shouldn't analyze. The agent should have no performance impact on applications that aren't analyzed due to this setting. This list accepts * as a wildcard.
    ProcessWhitelist Controls the .NET agent's monitoring of application pools. You should set the value of this setting to a comma-separated list of application pool names that the agent should analyze. The agent doesn't monitory any other applications. The agent should have no performance impact on applications that aren't analyzed due to this setting. This list accepts * as a wildcard.

    See the Application Pool Filter article for more information on using ProcessBlacklist and ProcessWhitelist against IIS application pools.

    Application-Specific Settings for Windows

    Users can customize several pieces of information that are specific to each application by adding entries to the application's web.config file. In order for the agent to pick up customized application settings, you must place these settings in the application web.config file's root configuration appSettings section.

    Note: The "Contrast.CamelCase"-style configuration options are considered legacy options. New configuration values will follow the YAML-style naming convention. All users are encouraged to migrate to YAML-based property names in their applications' web.config files.

    Option Legacy Option Description Version
    contrast.application.name Contrast.AppName Controls the application name sent to the Contrast UI for this application. The contrast.application.name setting should be present on each server where the application is to be analyzed. If it isn't present, the applications could have different display names and be considered as different applications by the Contrast application. See the Absent Configuration Setting section below for more details. 3.1.3+
    contrast.application.version Contrast.AppVersion Controls the application version tag sent to Contrast. 3.3.6+
    contrast.application.group Contrast.AppGroup Specifies the group to which this application will be added in the Contrast UI, if this application isn't already a member of a group. 3.4.5+
    contrast.application.tags Contrast.AppTags Controls free-form tags sent to Contrast for the application. You can use tags to search for specific applications in the Contrast UI. 4.8.20+
    contrast.inventory.tags Contrast.LibraryTags Controls free-form tags sent to Contrast for the application's libraries. You can use tags to search for specific libraries in the Contrast UI. 4.8.20+
    contrast.assess.tags Contrast.FindingTags Controls free-form tags sent to Contrast for the application's vulnerabilities. You can use tags to search for specific vulnerabilities in the Contrast UI. 4.8.20+

    Example:

     <configuration>
       <appSettings>
         <add key="contrast.application.name" value="MyWebAppName" />
         <add key="contrast.application.version" value="1.2.3" />
       </appSettings>
       <system.web>
         ...
    

    Absent Configuration Setting

    If the Contrast.AppName configuration setting isn't present, the .NET agent will use the application's virtual path as an application name. If the application is hosted in the root of a site (i.e., the virtual path is /), then the .NET agent will use the site's name as the application name.

    Configuration Settings for Azure App Service

    The .NET agent for Azure App Service can be configured using the environment variable convention of agent configuration. See YAML configuration properties for more information and a full list of supported configuration options.

    Example: To change the agent's logging level, add CONTRAST__AGENT__LOGGER__LEVEL in the Azure portal.

    You can also specify specific application configuration options in an application's web.config file. For the agent to pick up customized application settings, you must place these settings in the application web.config file's root configuration appSettings section. See application-specific settings for more details.

    Legacy Configuration Options

    The following configuration values for Azure App Service are considered legacy configuration options. New configuration values are only supported as YAML-based configuration. All users are encouraged to migrate to YAML configuration properties.

    You can override these configurations using Application Settings in the Azure portal, or in your application's web.config file. You can also modify the following configurations.

    Example: To change a the default log level, change the configuration setting LogLevel by either adding CONTRAST_LogLevel in the Azure portal or adding a Contrast.LogLevel application setting in the web.config file.

    Identification and tagging

    Parameter Description
    ServerName Customizes the display name used by the Contrast UI for the server running the .NET agent. If the ServerName configuration setting isn't present, the server name is the Resource Group - Region of your application (e.g.,MyResourceGroup - US East).
    ServerEnvironment Set the environment value sent to Contrast when servers are created. Valid ServerEnvironment values are DEVELOPMENT, QA or PRODUCTION (case insensitive). The default value is QA. This does not affect servers that already exist in Contrast.
    ServerTags Controls free-form tags sent to Contrast for servers; you can use tags to search for servers in the Contrast interface. See the article on Application-Specific Settings for details on tagging applications, libraries and vulnerabilities.
    AppName Change the application name sent to the Contrast interface for this application. The default is your Azure App Service application name as set on Azure Portal.
    AppVersion Controls the application version tag sent to Contrast.
    AppGroup Specifies the to which group this application will be added in the Contrast interface, if this application isn't already a member of a group.
    AppTags Controls free-form tags sent to Contrast for the application; you can use tags to search for specific applications in the Contrast UI.
    LibraryTags Controls free-form tags sent to Contrast for the application's libraries; you can use tags to search for specific libraries in the Contrast UI.
    FindingTags Controls free-form tags sent to Contrast for the application's vulnerabilities; you can use tags to search for specific vulnerabilities in the Contrast UI.

    Diagnostics

    Parameter Description
    LogLevel More detailed levels of logging degrade performance, but can generate useful information for debugging Contrast. The logging level is configured in Server Settings in the Contrast UI by default; however, you can also configure it at the agent level. Options are Error, Warn, Info, Debug and Trace.

    Performance tweaks

    Parameter Description
    StackTraceConfig Limits stack traces captured by the agent. This is configured in Server Settings in the Contrast UI by default. The default is Full.
  • Full: Captures all stack traces with file and line number information. Deployments must include .PDB files for line number information.
  • Limited: Better performance; captures all stack traces but no file and line number information. Best used for builds without debugging symbols (.PDB files).
  • Minimal: Best performance; doesn't capture intermediate propagator stack traces, or file and line information. Best used for Release builds and Production environments.
  • ThreadAnalysis Useful for more thorough analysis if your application manually creates background threads. Choose Web (default) or Full. Web follows data flow through normal web operations. Full instruments all threading operations which adds overhead.