Skip to main content

Configure the .NET Core agent

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

Depending on your situation, you can configure the .NET Core 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 the diagnostics port only and keep profiling on, set these environment variables:

DOTNET_EnableDiagnostics=1

DOTNET_EnableDiagnostics_IPC=0

.NET Environment variables provides additional information about these environment variables.

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.

.NET Core variables for directory and log location

Use these variables to change the location of the .NET Core working directory and log files.

Environment variable

Purpose

CONTRAST_CORECLR_DATA_DIRECTORY

Specify the working directory you want to use.

CONTRAST_CORECLR_LOGS_DIRECTORY

Specify the directory where you want to write log files.

.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
In this section: