Skip to main content

Install the .NET Core agent in a container

Before you begin

  • This topic provides general guidance for installing the Contrast .NET Core agent in a containerized application, with Docker as an example.

  • You should have a basic understanding of how containers and related software work. You may need to adjust the instructions to meet your specific circumstances.

  • If you are using Kubernetes, consider using the Agent Operator to configure the agent.

Step 1: Install the agent

Contrast can be added either before or after the application is added to the container image. The recommended approach is with the use of named multi-stage builds. For example:


# Hidden for brevity...

# Copy the required agent files from the official Contrast agent image.
COPY --from=contrast/agent-dotnet-core:latest /contrast /contrast

Where in this example, the latest .NET Core agent is used (check DockerHub for available tags).

Step 2: Configure the agent

Contrast agents accept configuration from multiple sources, with order of precedence documented in the order of precedence section.

A mixed approach is recommended:

  • Use a YAML file so that common configuration may be shared between many applications.

  • Use environment variables for application-specific configuration values, to override values provided by a YAML file, or for sensitive keys that are injected during runtime.

YAML file configuration:

When using a YAML file to configure the agent, the environment variable CONTRAST_CONFIG_PATH can also be used to indicate where the YAML file is located inside the container.

For example, given a YAML file called contrast_security.yaml that exists in the Docker build context:

The environment variable CONTRAST_CONFIG_PATH can also be used to indicate where the YAML file is located.

    path: /var/tmp
    level: WARN

The YAML file can be added to the container image as follows:


# Hidden for brevity...

# Add the Contrast agent to the image.
COPY --from=contrast/agent-dotnet-core:latest /contrast /contrast

# Copy the contrast_security.yaml file from Docker build context.
COPY ./contrast_security.yaml /contrast_security.yaml

# Finally configure configure the agent to use the YAML file previously copied.
ENV CONTRAST_CONFIG_PATH=/contrast_security.yaml

Environment variable configuration:

To set an application-specific configuration, use environment variables. Below are some common configuration options.



Environment variable

Application name

Specify the application name reported to Contrast.


Application group

Specify the application access group for this application during onboarding.


Application access groups have to be created first in Contrast.


Application tags

Add labels to an application.


Server name

Specify the server name reported to Contrast.


Server environment

Specify in which environment the application is running. Valid values for this configuration are: Development, QA and Production


Server tag

Add labels to the server.


Step 3: Add profiler variables and authentication credentials

To enable instrumentation of your application, the .NET agent requires additional environment variables. The CORECLR_ variables load the agent and the CONTRAST_ variables are for agent authentication to the server.

Using the Dockerfile example from before:



# Hidden for brevity...

COPY --from=contrast/agent-dotnet-core:latest /contrast /contrast

# Required variables to load the agent.
ENV CORECLR_PROFILER_PATH_64=/contrast/runtimes/linux-x64/native/ \



# Hidden for brevity...

COPY --from=contrast/agent-dotnet-core:latest /contrast /contrast

# Required variables to load the agent.
ENV CORECLR_PROFILER_PATH_64=/contrast/runtimes/linux-arm64                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             /native/ \

Additionally, the following environment variables are required for agent authentication to the server.

CONTRAST__API__SERVICE_KEY={Your Service key here}
CONTRAST__API__USER_NAME={Your agent username here}

You can get API values (agent keys) from Contrast or by downloading a YAML file for the .NET Core agent.


The API_KEY, SERVICE_KEY and USER_NAME keys should be considered sensitive data and handled accordingly. Contrast recommends injecting these during runtime from your secrets store (e.g. Kubernetes Secrets).

Step 4: Instrument your application

You can now run the application image with Contrast enabled. Contrast will instrument your application during startup and begin reporting security vulnerabilities to Contrast. You can verify that Contrast is running by checking the container.