.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. Add the Contrast .NET Core or Framework Agent Site Extension
2. Add Configuration options
3. 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 of how to instrument your applications that can be automated.

Instructions

1. Add the Contrast .NET Core or Framework Agent Site Extension

To add the Contrast Agent as a Site Extension via the Azure Portal:

• Navigate to the App Service in the Azure portal
• Open the “Extensions” blade 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

To add the Contrast .NET Framework Site Extension to an App Service named "myAppService" in Resource Group "myResourceGroup" using the Azure CLI:

az resource create --resource-group 'myResourceGroup' --resource-type Microsoft.Web/sites/siteextensions --name myAppService/siteextensions/Contrast.NET.Azure.SiteExtension --properties "{}"

or as follows for the Contrast .NET Core Site Extension:

az resource create --resource-group 'myResourceGroup' --resource-type Microsoft.Web/sites/siteextensions --name myAppService/siteextensions/Contrast.NetCore.Azure.SiteExtension --properties "{}"

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

2. Add Configuration options

At a minimum, the following Application Settings are required to allow the Contrast Agent to communicate activity to the Contrast UI:

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}

To add the Application Settings to an App Service via the Azure Portal:

• Navigate to the App Service in the Azure portal
• Open the “Configurations” blade 
• Add App Settings indicated above as name/value pairs.

To add the Application Settings to an App Service named "myAppService" in Resource Group "myResourceGroup" using the Azure CLI:

az webapp config appsettings set --resource-group 'myResourceGroup' --name 'myAppService' --settings CONTRAST__API__URL=https://app.contrastsecurity.com 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 the Contrast UI 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. Instrument your application

You can now run the application with Contrast enabled. 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 “Kudu 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