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
- Configure the agent
- Add authentication credentials
- Add the Contrast .NET Core or Framework agent to Azure App Service
- 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.
- Corporate rule (e.g., expired license overrides assess.enable)
- System property value
- Environment variable value
- YAML configuration file value
- Contrast UI value
- 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 |
.NET Core agent
CORECLR_ENABLE_PROFILING: 1 |
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 |
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:
- Navigate to “Advanced Tools” for the app service in the Azure portal
- Select Go.
- In the resulting “Kudu Services” window, click on the “Debug console” menu at the top and choose “CMD”.
- Select the LogFiles directory.
- Select the Contrast directory.
- Select the “dotnet” directory of the “dotnetcore” directory
- You will see an agent log named Module_ROOT_<appservice_name>_<timestamp>.log
- Select the pencil icon for the most recent log to view its contents.
- 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)... |