Configuration

YAML Properties

Contrast supports YAML-based configuration for the .NET Core agent. This allows you to store configuration on disk that you can override with environment variables or command line arguments. Go to the .NET Core 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.

Load Path

Configuration values use the following order of precedence (where 1 is the highest):

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

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 at the default path: %ProgramData%\Contrast\dotnet-core\contrast_security.yaml (Windows) or /etc/contrast/dotnet-core/contrast_security.yaml (Linux).

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.

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 Core 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: The .NET Core agent default behavior is (SecurityProtocolType.Tls | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls12).
      Example: tls1|tls2|tls3

    • certificate:

      • enable: If set to false, the certificate configuration in this section will be ignored.
    • 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
      • 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 Core 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.

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:

    • 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 Core agent-wide configurations.

  • dotnet:
    • application_blacklist: Set a list of application names that the agent does not analyze. Names must be formatted as a comma-separated list.
    • application_whitelist: Set a list of application names that the agent analyzes. If set, other applications are ignored. Whitelist takes precedence over blacklist. Names must be formatted as a comma-separated list.
    • 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.
    • 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.

Inventory properties

Use the properties in this section to control inventory features in the .NET Core 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 Core 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: Include the following properties to override the sampling settings from Contrast UI.

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

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

Contrast Protect properties

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

  • protect:

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

    • rules:

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

      • bot-blocker:

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

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

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

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

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

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

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

Application properties

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

  • application:
    • name: Override the application name.
    • code: Apply a code label to the application. The label is displayed next to application name in the Contrast UI.
    • 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

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

    # Set a list of application names that the agent does not
    # analyze. (The applications are still instrumented).
    # Names must be formatted as a comma-separated list.
    # application_blacklist: NEEDS_TO_BE_SET

    # Set a list of application names that the agent analyzes.
    # If set, other applications are not analyzed, but are still
    # instrumented. Whitelist takes precedence over blacklist.
    # Names must be formatted as a comma-separated list.
    # application_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

Configuration Settings for Azure App Service

Configuration Methods

Configure the .NET Core 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 Core 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 define any configuration setting in the web.config file as an environment variable. Place your overrides using the environment variable convention in the <environmentVariables> section of <aspNetCore> element. See the Microsoft documentation for more details.

YAML file

Instead of setting individual options in the Azure Portal, you may use a YAML configuration file containing Contrast settings.

To begin, upload the file to your Azure web application by including it in your application deployment or using the Kudu console. Then, within the Configuration\Application Settings blade, add a new application setting called CONTRAST_CONFIG_PATH with a value that points to this file.

Example: To use the contrast_security.yaml file in the root of your application, add a new application setting with the key CONTRAST_CONFIG_PATH and value of D:\Home\site\wwwroot\contrast_security.yaml within Configuration\Application Settings. 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 the Configuration\Application Settings blade 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.code Apply a code label to the application. The label is displayed next to application name in the Contrast UI.
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.