.NET Core agent with Docker

Agent installation guide

Overview

This guide offers examples for using Contrast Security’s .NET Core agent with Docker. We encourage you to take this guide, make it your own, and distribute it to teams who both need to instrument .NET Core applications and manage them through Docker. 

The main portion of the guide details the most popular methods customers use to instrument .NET Core applications contained in Docker and see security data in Contrast.

There is also a lab section that describes how to instrument a sample .NET Core application called eShopOnWeb. It’s a good way to learn before proceeding with your own applications. You can instrument eShopOnWeb with Docker and see security data for this application in Contrast using the source code samples section at the end of this guide. 

Main steps

Update the application’s Dockerfile

1. Add the Contrast .NET Core agent package into the Dockerfile
2. Create an agent configuration file
3. Add profiler variables and authentication credentials for your environment

Instrument your application

4. Build the application image with Contrast enabled

Supported technologies

Before you begin, please be sure Contrast supports your preferred tools and environments for .NET Core:
.NET Core supported technologies

This guide assumes you have:

• Some familiarity with DevOps practices and how Docker works
• The information needed to connect the Contrast .NET Core agent to the Contrast dashboard: Standard installation for the .NET Core agent
• Downloaded and started the Contrast .NET Core agent before running your applications

Instructions

Begin by updating the Dockerfile for your application.

1) Add the Contrast .NET Core agent

Here are two options to add the Contrast agent and basic configuration to a Docker image. Choose the one that works best for you.

Option one: Add to a base image

• Add the Contrast agent and basic configuration to a Docker base image without enabling it
• Make one ENV update and Contrast is available to the application using that image
• Enable Contrast in the application’s Docker image or container 

Example 1: Base image Dockerfile configuration using the downloaded Nuget package:

# START Build Stage
FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build

# Build steps for your application here
# ....
# ....

# Download Contrast Sensor package from nuget, unpack to /tmp/contrast

ADD https://www.nuget.org/api/v2/package/Contrast.SensorsNetCore /tmp/contrast.sensorsnetcore.nupkg
RUN apt-get update \
    && apt-get install -y unzip \
    && unzip /tmp/contrast.sensorsnetcore.nupkg -d /tmp/contrast \
    && rm /tmp/contrast.sensorsnetcore.nupkg
# END Build Stage

# START Final Stage
FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS final

# Copy the application over from the build stage here
# ....
# ....

# Copy the agent over from the build stage to /opt/contrast
COPY --from=build /tmp/contrast /opt/contrast

# START Build Stage
FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build

# Build steps for your application here including the agent
# ....
RUN dotnet add package Contrast.SensorsNetCore
# ....

# END Build Stage

# START Final Stage
FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS final

# Copy the application (now includes agent) over from the build stage here
# ....
# ....

# START Build Stage
FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build

# Build steps for your application here
# ....
# ....

# END Build Stage

# START Final Stage
FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS final

# Copy the application over from the build stage here
# ....
# ....

#Copy the agent over from the Contrast image to /opt/contrast
COPY --from=contrast/agent-dotnet-core /contrast /opt/contrast

This option gives your teams more flexibility to use any version of the Contrast agent and avoid automatic updates. To do this:

• Download the Contrast agent zip file from the Contrast UI. 
• See Contrast documentation for instructions: Download agent and configuration files from Contrast
• Extract the downloaded zip archive (for example, Contrast.NET.Core_2.4.2.0.zip) to a directory within your application project
• Add the Contrast agent and its configuration directly to an application’s Docker image

COPY Contrast.NET.Core_2.4.2.0 /app/Contrast.NET.Core_2.4.2.0

2) Configure the agent

There are several different ways to configure Contrast agents.

The order of precedence is explained in detail here: Order of precedence

For the .NET Core agent, all configuration options can be set via environment variables, but if it desired to use a yaml configuration file, you can specify the location of that file using the environment variable CONTRAST_CONFIG_PATH.

Some examples of commonly used application-specific configuration options are:

• Application name: Specify the application name reported to ContrastCONTRAST__APPLICATION__NAME
• Application group: Specify the application access group (must already exist in Contrast) for this application during onboarding.CONTRAST__APPLICATION__GROUP
• Application tags: Add labels to an applicationCONTRAST__APPLICATION__TAGS
• Server name: Specify the server name reported to ContrastCONTRAST__SERVER__NAME
• Server environment: specify in which environment the application is running. Valid values for this configuration are: Development, QA and ProductionCONTRAST__SERVER__ENVIRONMENT
• Server tag: Add labels to the server CONTRAST__SERVER__TAGS

3) Add profiler variables and authentication credentials for your environment

To complete the configuration of the .NET Core agent, you must pass, at a minimum, the following environment variables to the application: (The CORECLR_ variables instruct the runtime to load the agent, and the CONTRAST_ variables provide the agent with credentials for authentication to the Contrast UI server.)

CORECLR_PROFILER_PATH_64={path to the ContrastProfiler.so} 
# Examples: /app/contrast/runtimes/linux-x64/native/ContrastProfiler.so
#           /opt/contrast/contentFiles/any/netstandard2.0/contrast/runtimes/linux-x64/native/ContrastProfiler.so
#           /opt/contrast/runtimes/linux-x64/native/ContrastProfiler.so
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={8B2CE134-0948-48CA-A4B2-80DDAD9F5791}
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. For more, see Contrast documentation: Find the agent keys

Note: The API_KEY, SERVICE_KEY and USER_NAME should be considered sensitive data and handled accordingly.

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 log. You should see output similar to this:

Source code example: eShopOnWeb

Use this GitHub repository to learn how to first. It contains a lab that walks you through the different ways .NET Core applications delivered via Docker can be instrumented for security monitoring with Contrast.
https://github.com/Contrast-Security-OSS/eShopOnWeb

FAQ

• How can I add profiler chaining?
• What are.NET Core system requirements?
• How do I use sampling for better performance?
• How can I get enhanced logging and data for .NET Core agent?