.NET and Azure App Service

Agent installation guide

Overview

This guide offers examples for using Contrast Security’s .NET Framework or Core agents with Azure App Service. We encourage you to take this guide, make it your own, and distribute it to teams who need to instrument applications this way. 

The main portion of the guide details the most popular methods customers use to instrument .NET Framework or Core applications with Azure App Service to see security data in Contrast.

Main steps

1. Configure the agent
2. Add authentication credentials
3. Add the Contrast .NET Core or Framework agent to Azure App Service
4. Instrument your application

Supported technologies

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

This guide assumes you have:

• Some familiarity with DevOps practices and how Azure Portal works
• Some familiarity with Azure App Service
• The information and access you need to connect Contrast .NET agents to the Contrast dashboard:
  Install the .NET Framework agent
  Install the .NET Core agent

Known issues

Only Azure Portal (web UI), Policy, and REST API natively support site extensions. This guide is limited to examples for how to instrument your applications that can be automated.

Instructions

Begin by configuring the Contrast agent for your application.

1. Configure the agent

There are different values you can use to configure Contrast agents. This is the order of precedence, and each level overrides the next: 1 is highest.

1. Corporate rule (e.g., expired license overrides assess.enable)
2. System property value
3. Environment variable value
4. YAML configuration file value
5. Contrast UI value
6. Default value

Order of precedence is explained more here:
Order of precedence

We recommend setting at least the following values to configure the agent. Add these key/value pairs to the configuration file for the .NET agent you are using:

.NET Framework agent

CORECLR_ENABLE_PROFILING: 1
CORECLR_PROFILER: {EFEB8EE0-6D39-4347-A5FE-4D0C88BC5BC1}
CORECLR_PROFILER_PATH_32: D:\\home\\SiteExtensions\\Contrast.NET.Azure.SiteExtension\\ContrastAppService\\ContrastProfiler-32.dll
CORECLR_PROFILER_PATH_64: D:\\home\\SiteExtensions\\Contrast.NET.Azure.SiteExtension\\ContrastAppService\\ContrastProfiler-64.dll

.NET Core agent

CORECLR_ENABLE_PROFILING: 1
CORECLR_PROFILER: {8B2CE134-0948-48CA-A4B2-80DDAD9F5791}
CORECLR_PROFILER_PATH_32: D:\\home\\SiteExtensions\\Contrast.NetCore.Azure.SiteExtension\\ContrastNetCoreAppService\\contrast\\runtimes\\win-x86\\native\\ContrastProfiler.dll
CORECLR_PROFILER_PATH_64: D:\\home\\SiteExtensions\\Contrast.NetCore.Azure.SiteExtension\\ContrastNetCoreAppService\\\contrast\\runtimes\\win-x64\\native\\ContrastProfiler.dll

2. Add authentication credentials

To complete the configuration of the .NET Core or Framework agents, you must pass these environment variables to the application. They are for agent authentication to the server.

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

You can get API values (agent keys) from Contrast or by downloading a YAML file for the .NET Core or Framework agent. For more, see Contrast documentation: Find the agent keys

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

3. Add the Contrast .NET Core or Framework agent

To add the Contrast agent to an app service:

• Navigate to the app service in the Azure portal
• Select “Configurations” for the app service 
• Add all configuration and authentication values indicated above as name/value pairs. Be careful about the differences in required values between the .NET Framework and .NET Core agents.
  
  

4. Instrument your application

You can now run the application with Contrast enabled. To start monitoring your application, add the Contrast agent as a site extension:

• Navigate to the app service in the Azure portal
• Select “Extensions” for the app service
• Search for and choose the .NET Framework or .NET Core Contrast extension, depending on which type of application want to instrument
• Accept the licensing terms
• Click OK to add the agent as a site extension

Once the extension is added, the portal will immediately display a list of the installed agents similar to the following:

It will automatically instrument any application that is running inside of the App Service, and you should begin to see data in Contrast.

You can also verify that Contrast is running by checking the logs. To do so:

1. Navigate to “Advanced Tools” for the app service in the Azure portal
2. Select Go.
3. In the resulting “Kudzu Services” window, click on the “Debug console” menu at the top and choose “CMD”.
4. Select the LogFiles directory.
5. Select the Contrast directory.
6. Select the “dotnet” directory of the “dotnetcore” directory
7. You will see an agent log named Module_ROOT_<appservice_name>_<timestamp>.log
8. Select the pencil icon for the most recent log to view its contents.
9. You will see contents similar to the following:

2020-08-14 07:07:54.1207 INFO   10772:12            NLogManager Replaying buffered logs (0 events were discarded)...
2020-08-14 07:07:44.4929 INFO   10772:12            ConfigFileFinder No 'contrast_security.yaml' file could be located, so no configuration file will be sourced.
2020-08-14 07:07:44.9816 INFO   10772:12            Global           TLS Version not set in configuration. Using default: (Tls|Tls11|Tls12).
.
.
.
2020-08-14 07:07:46.1023 INFO   10772:12            Global           Sending server startup with environment = PRODUCTION, version = 20.8.2.0, tags = 
2020-08-14 07:07:47.5873 INFO   10772:5             Global           Received Server Config from TeamServer for Azure WebGoat.NET Production Pipeline - 'Azure Web App' 
2020-08-14 07:07:47.9932 INFO   10772:12            Global           TeamServer connected