Skip to main content

Install the .NET agent in a container

Before you begin

  • This topic provides general guidance for installing the Contrast .NET 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:

.NET Core

FROM mcr.microsoft.com/dotnet/aspnet:6.0

# Hidden for brevity...

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

 

.NET Framework

FROM mcr.microsoft.com/dotnet/framework/sdk:4.8

# Hidden for brevity...

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

In these examples, the latest .NET 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.

agent:
  logger:
    path: /var/tmp
    level: WARN

You can use the CONTRAST_CONFIG_PATH environment variable to add the agent YAML file to the container image as follows:

.NET Core

FROM mcr.microsoft.com/dotnet/aspnet:6.0

# 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

.NET Framework

FROM mcr.microsoft.com/dotnet/framework/sdk:4.8

# Hidden for brevity...

# Add the Contrast agent to the image.
COPY --from=contrast/agent-dotnet-framework:latest C:\Contrast C:\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.

Title

Usage

Environment variable

Application name

Specify the application name reported to Contrast.

CONTRAST__APPLICATION__NAME

Application group

Specify the application access group for this application during onboarding.

Note

Application access groups have to be created first in Contrast.

CONTRAST__APPLICATION__GROUP

Application tags

Add labels to an application.

CONTRAST__APPLICATION__TAGS

Server name

Specify the server name reported to Contrast.

CONTRAST__SERVER__NAME

Server environment

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

CONTRAST__SERVER__ENVIRONMENT

Server tag

Add labels to the server.

CONTRAST__SERVER__TAG

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:

.NET Core x64

FROM mcr.microsoft.com/dotnet/aspnet:6.0

# Hidden for brevity...

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

# Required variables to load the agent.
ENV CORECLR_PROFILER_PATH_64=/contrast/runtimes/linux-x64/native/ContrastProfiler.so \
    CORECLR_ENABLE_PROFILING=1 \
    CORECLR_PROFILER={8B2CE134-0948-48CA-A4B2-80DDAD9F5791}

.NET Core ARM64

FROM mcr.microsoft.com/dotnet/aspnet:6.0

# Hidden for brevity...

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

# Required variables to load the agent.
ENV CORECLR_PROFILER_PATH_64=/contrast/runtimes/linux-arm64                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             /native/ContrastProfiler.so \
    CORECLR_ENABLE_PROFILING=1 \
    CORECLR_PROFILER={8B2CE134-0948-48CA-A4B2-80DDAD9F5791}

.NET Framework

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

FROM mcr.microsoft.com/dotnet/framework/sdk:4.8

COPY --from=contrast/agent-dotnet-framework:latest C:\Contrast C:\Contrast

ENV COR_ENABLE_PROFILING=1 \
    COR_PROFILER={EFEB8EE0-6D39-4347-A5FE-4D0C88BC5BC1} \
    COR_PROFILER_PATH_32=C:\Contrast\runtimes\win-x86\native\ContrastProfiler.dll \
    COR_PROFILER_PATH_64=C:\Contrast\runtimes\win-x64\native\ContrastProfiler.dll

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

Important

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.

Examples

You can see examples of finished code in this GitHub repository. In particular, these ASP.NET application use cases might be helpful:

See also

icon-external-link.svg Kubernetes and Contrast

icon-external-link.svg AWS Fargate and Contrast agents

In this section: