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:

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

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

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

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 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:

x64

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

# 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/ContrastProfiler.so \
    CORECLR_ENABLE_PROFILING=1 \
    CORECLR_PROFILER={8B2CE134-0948-48CA-A4B2-80DDAD9F5791}

ARM64

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

# 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/ContrastProfiler.so \
    CORECLR_ENABLE_PROFILING=1 \
    CORECLR_PROFILER={8B2CE134-0948-48CA-A4B2-80DDAD9F5791}

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

CONTRAST__API__URL=https://app.contrastsecurity.com/Contrast
CONTRAST__API__API_KEY={Your API KEY here}
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.

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.

In this section: