Skip to main content

Install the .NET Framework agent using a container

Before you begin

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

Step 1: Install the agent

In this example, the latest .NET Framework agent is copied. Check DockerHub for available tags.

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

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 you can share a common configuration between multiple applications.

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

YAML file configuration:

When you use a YAML file to configure the agent, you can use the environment variable CONTRAST_CONFIG_PATH 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:

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:

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 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. This table contains 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

Create application access groups in Contrast before using this variable.

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 COR_CLR variables load the agent and the CONTRAST_ variables are for agent authentication to the server.

Using the Dockerfile example in this topic:

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

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

  • set CONTRAST__API__TOKEN=<token-value

  • Legacy settings: If you are using an agent version earlier than 51.0.40, set these variables:

    CONTRAST__API__URL=https://app.contrastsecurity.com/Contrast
CONTRAST__API__API_KEY={Your API KEY here}
CONTRAST__API__SERVICE_KEY={Your Service key here}

Get the API values (agent keys) from the Contrast web interface or by downloading a YAML file for the .NET Framework agent.

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

Contrast Support Portal Kubernetes and Contrast

Contrast Support Portal AWS Fargate and Contrast agents

In this section: