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 contrast.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 (__). For example, contrast.server.name becomes CONTRAST__SERVER__NAME while contrast.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.

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

  • contrast.application.name
  • contrast.application.code
  • 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. If you set these properties in the global configuration file, all applications on the server will automatically have the same setting. Therefore, Contrast recommends that you use Application-Specific Settings to customize individual application settings.

  • 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"
    • 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 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 allow the CLR to
    # perform transparency checks under full trust.
    # enable_transparency_checks: false

    # 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

      # Tell the agent to detect when commands come directly
      # from input. The agent blocks if blocking is enabled.
      # detect_phased_commands: true

    # ==========================================================================
    # 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.unsafe-file-upload
    # Use the following properties to configure
    # how the unsafe file upload rule works.
    # ==========================================================================
    # unsafe-file-upload:

      # 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

  # 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_id: NEEDS_TO_BE_SET

  # 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.
  # session_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. If this setting 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.code N/A Controls the application "code" displayed in the Contrast UI for this application. This string is displayed in a subheader next to the name. 19.6.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.application.name 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

    Configuration Methods

    Configure the .NET Framework agent for Azure App Service in the Azure Portal, a web.config file or a YAML configuration file.

    Azure Portal

    You can configure the .NET Framework agent using the environment variable convention of agent configuration. Add all settings to the Application Settings section of the Configuration blade in the Azure Portal using environment variable syntax.

    Examples:

    • To change the agent's logging level (agent.logger.level) to trace, add a setting with key CONTRAST__AGENT__LOGGER__LEVEL and value TRACE.
    • To change the agent's server name (server.name) to "MyServer", add a setting with key CONTRAST__SERVER__NAME and value MyServer.

    web.config file

    You can also specify 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.

    YAML file

    Instead of setting individual options in the Azure Portal, you may use a YAML configuration file containing Contrast settings. First, upload the file to your Azure web application by including it in your application deployment or using the Kudu console. Then add an application setting, CONTRAST_CONFIG_PATH, that points to this file.

    Example: To use the contrast_security.yaml file in the root of your application, add an application setting with key CONTRAST_CONFIG_PATH and value D:\Home\site\wwwroot\contrast_security.yaml. Application files in Azure App Service are deployed to D:\home\site\wwwroot.

    Common Configuration Options

    The following tables outline some common configuration settings for Azure App Service and their default values. These settings can be included in the YAML configuration file or in Application Settings using environment variable syntax. This is a subset of all configurations that are available when using YAML configuration properties.

    Identification and tagging

    Parameter Description
    server.name Customizes the display name used by the Contrast UI for the server running the .NET agent. If this configuration setting isn't present, the server name is the Resource Group - Region of your application (e.g.,MyResourceGroup - US East).
    server.environment Set the environment value sent to Contrast when servers are created. Valid values are DEVELOPMENT, QA or PRODUCTION (case insensitive). The default value is QA. This does not affect servers that already exist in Contrast.
    server.tags 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.
    application.name Change the application name sent to the Contrast interface for this application. The default is your Azure App Service name as seen in the Azure Portal.
    application.version Controls the application version tag sent to Contrast. Default is none.
    application.group 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. Default is none.
    application.tags Controls free-form tags sent to Contrast for the application; you can use tags to search for specific applications in the Contrast UI. Default is none.
    inventory.tags 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. Default is none.
    assess.tags 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. Default is none.

    Diagnostics

    Parameter Description
    agent.logger.level 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
    assess.stacktraces Limits stack traces captured by the agent. This is configured in Server Settings in the Contrast UI by default. The default is ALL.
  • ALL: Captures all stack traces with file and line number information. Deployments must include .PDB files for line number information.
  • SOME: Better performance; captures all stack traces but no file and line number information. Best used for builds without debugging symbols (.PDB files).
  • NONE: Best performance; doesn't capture intermediate propagator stack traces, or file and line information. Stack traces for sources and sinks are still captured. Best used for Release builds and Production environments.
  • assess.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 (default) has better performance as it only captures String type objects as strings and uses type name for other object type values.
    agent.dotnet.thread_analysis 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.