Install the .NET Framework agent using a container

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.

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

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

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

A mixed approach is recommended:

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.

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.

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.

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

Contrast Support Portal Kubernetes and Contrast

Contrast Support Portal AWS Fargate and Contrast agents