Skip to main content

Configure the .NET agent

The standard configuration for all agents uses this order of precedence.

Depending on your situation, you can configure the .NET agent with:

Tip

Use the Contrast agent configuration editor to create or upload a YAML configuration file, validate YAML and get setting recommendations.

.NET profiling and diagnostics variables

For .NET 8 and later, setting the DOTNET_EnableDiagnostics environment variable to 0 disables all diagnostics for the process, including profiling. This setting prevents the Contrast agent from working with your applications. Setting the DOTNET_EnableDiagnostics_Profiler environment variable to 0 disables profiling only, however, it also prevents the Contrast agent from working with your .NET 8 applications.

This behavior is different from the behavior in .NET 7 and earlier applications.

Note

COMPlus_EnableDiagnostics is an alias of DOTNET_EnableDiagnostics, so setting this variable to 0 has the same effect on the Contrast agent.

To turn off diagnostics only and keep profiling on, set these environment variables:

DOTNET_EnableDiagnostics=1

DOTNET_EnableDiagnostics_IPC=0

Configure the .NET Core agent for Azure App Service

When using Azure App Service, you can configure the .NET Core agent with:

  • The Azure Portal: Configure the .NET Core agent using environment variables.

    Add all settings to the Application Settings section of the Configuration blade using environment variable syntax.

  • Environment variables in a web.config file: Place your overrides using the environment variable convention in the <environmentVariables> section of <aspNetCore> element.

  • A YAML configuration file: Upload the file to your Azure web application by including it in your application deployment or using the Kudu console.

    In the Configuration\Application Settings blade, add a new application setting called CONTRAST_CONFIG_PATH with a value that points to this file.

    For 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 in Configuration\Application Settings. Application files in Azure App Service are deployed to D:\home\site\wwwroot.

See also

Configure .NET Core agent with environment variables

You can configure environment variables in several ways:

Tip

You can convert any of the properties in the .NET Core YAML template to environment variables.

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

Here are some of the most common settings:

Environment variable

Purpose

CONTRAST__APPLICATION__NAME

Specify the application name reported to Contrast.

CONTRAST__APPLICATION__GROUP

Specify the access group for this application. (You must have already created access groups.)

CONTRAST__APPLICATION__SESSION_METADATA

Provide metadata which is used to create a new session ID in the Contrast web interface. Vulnerabilities discovered by the agent are associated with this new session.

CONTRAST__SERVER__NAME

Specify the server name reported to Contrast.

CONTRAST__SERVER__ENVIRONMENT

Specify in which environment the application is running (Development, QA and Production).

See the .NET Core YAML template for a description of other available properties.

Configure .NET Framework with web.config file

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

For example, two applications hosted in the same application pool will report as different servers if you configure the contrast.server.name property in the appSettings in each application's web.config file. Or, you could use web.config to configure the contrast.application.name, like this:

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

See the .NET Framework YAML template for a description of other available properties.

If your agent version is earlier than 21.1.4, only some properties can be configured with web.config as listed here.

Properties

Introduced with this .NET Framework agent version

contrast.application.code

19.6.3

contrast.application.group

19.1.3

contrast.application.metadata

19.1.3

contrast.application.name

19.1.3

contrast.application.session_id

20.6.6

contrast.application.session_metadata

20.6.6

contrast.application.tags

19.1.3

contrast.application.version

19.1.3

contrast.assess.tags

19.1.3

contrast.inventory.tags

19.1.3

Note

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

Important

Starting with agent version 21.1.4, users can set most agent configuration settings either with the application's web.config file or with a contrast_security.yaml file in the same directory as the application. For example, two applications hosted in the same application pool can now report as different servers by setting contrast.server.name in the appSettings in each application's web.config file.

The following configuration settings are applied at the process level and cannot be customized separately for each application. You cannot set these properties using web.config and must set these configurations another way (like with YAML).

  • agent.dotnet.app_pool_denylist

  • agent.dotnet.app_pool_allowlist

  • agent.dotnet.enable_instrumentation_optimizations

  • agent.dotnet.enable_jit_inlining

  • agent.dotnet.enable_transparency_checks

  • agent.dotnet.enable_struct_dataflow

  • assess.enable_control_detection

Additionally, the agent's profiler component uses the process-level settings for the following keys, while the agent's sensor component will use the application-specific settings (if specified):

  • agent.logger.level

  • agent.logger.stdout

.NET Core YAML configuration template

Use this template to configure the .NET Core agent using a YAML configuration file. (Learn more about YAML configuration.)

Place your YAML file in the default location:

  • Windows: C:/ProgramData/contrast/dotnet-core/contrast_security.yaml

  • Unix: /etc/contrast/dotnet-core/contrast_security.yaml

https://docs.contrastsecurity.com/common-agent-config/dotnetcore_contrast_security.yaml

.NET Framework YAML template

Configure the .NET Framework agent using a YAML configuration file.

The contrast_security.yaml file is copied to the agent's data directory by the installer (C:\ProgramData\Contrast\dotnet\contrast_security.yaml by default). The installer does not copy the YAML file if it already exists at the destination.

The template below contains all valid YAML options for this agent. For example, you can use the file to set the server name reported by the .NET Framework agent. To do this, update the contrast_security.yaml file, add a new line and the code below, and then continue the installation as normal.

server:
  name: MyServerName
https://docs.contrastsecurity.com/common-agent-config/dotnet_contrast_security.yaml

Certificate exceptions

If you see certificate exception messages and feel that it's safe to ignore them, add this setting to the YAML configuration file:

api:
  certificate:
    ignore_cert_errors: true

icon-external-link.svgLearn more about managing certificate issues.

In this section: