The Basics

To install the .NET agent, complete the following steps.

• Log in to the Contrast UI.
• Click the button in the top navigation bar to Add Agent.
• Select the .NET Agent in the dropdown menu, and click the button to Download Agent. You might need to specify proxy authentication information required by your network before downloading the agent.
• Extract the downloaded zip archive (e.g., ContrastSetup_18.4.56.zip) on the web server, and run ContrastSetup.exe. This installs the .NET agent.

Customize Your Installation

The downloaded zip archive contains a file called contrast_security.yaml which is used by the agent for configuration. This includes the authentication credentials and proxy settings the agent needs to connect to Contrast.

You can fully configure the agent using the contrast_security.yaml file. See the agent configuration instructions for more information.

Example: To disable automatic updates of the .NET agent, update the contrast_security.yaml file, add a new line and the code below, and then continue the installation as normal.

 agent:
  auto_update:
    enable: false

Note: The contrast_security.yaml file is copied to the agent's data directory by the installer (C:\ProgramData\Contrast\dotnet\contrast_security.yaml by default). The installer does not copy the YAML file if it already exists at the destination.

Silent Installation

The .NET agent installer supports following the command line options. These options are silent, which means that they don't require your interaction and don't present the installer's UI.

• Install: ContrastSetup.exe -s -norestart

• Install and do not start the Contrast .NET Tray Application: ContrastSetup.exe -s -norestart StartTray=0

• Install using the YAML file specified: ContrastSetup.exe -s PathToYaml=c:\contrast_security.yaml

• Uninstall: ContrastSetup.exe -uninstall -s -norestart

• Repair: ContrastSetup.exe -s -repair

Changes Made by the Agent Installer

Many users are curious about the changes made by the .NET agent and the impacts these changes may have. In all respects, the Contrast .NET agent installer is a normal Windows application installer built using standard MSI technology. The .NET agent installer validates that the target server satisfies several requirements (e.g., the operating system is Windows Server 2008 R2 or greater). If all requirements are met, the installer registers the .NET agent as a standard Windows program and makes the following changes.

• Places the agent’s files on a disk in the specified install location (e.g., C:\Program Files\Contrast\dotnet). This includes several dynamic link libraries (DLLs) and executables, such as the background Windows service that drives agent behavior.
• Creates the specified data directory for the agent that's primarily used to store agent log files and configuration (e.g., C:\ProgramData\Contrast\dotnet).
• Registers the agent’s background Window service with the operating system.
• Starts the agent’s background Windows service and Tray (UI) application. This service has a number of responsibilities:
  • Preparing the environment for instrumentation by registering the agent’s profiler component with IIS through environment variables, and restarting IIS. This causes the CLR to load the agent’s profiler, which is responsible for instrumenting analyzed applications.
  • Communication with the Contrast UI.
  • Communication with profiler and sensor components through local named pipes.

Next Steps

• Use the Contrast .NET agent
• Customize .NET agent configuration

Complete the following steps for express installation of the .NET agent via Azure Portal Extensions.

Step One: Create an application hosted on Azure App Service

• Create an Azure account, if you don't have one already.
• Follow the instructions to create an ASP.NET web application, and deploy it to Azure App Service.
• Publish your application to Azure, and confirm that it works as expected without Contrast.

Step Two: Add application settings for Contrast

The following values are the Application Settings that the agent needs to connect to Contrast. You can get your authentication keys from your Profile in the Contrast UI.

Step Three: Add the site extension to the hosted application

• In the Azure Portal, select your hosted application.
• Select Extensions.

• Click + Add.
• Select the Contrast.NET Site Extension.

• Click OK, and agree to the terms and conditions.
• Wait a few seconds and confirm the site extension installed correctly.

• Go back to the application overview and Restart the application.
• Navigate to the application, and confirm the application is reporting to Contrast.

Note: The agent can also be installed from the Site Extensions area of your application management SCM (Kudu) site.

Update Your Installation

If a new version of the agent is available, it will be indicated in the Azure Portal or Kudu dashboard. You must stop the site before starting the update; otherwise, the update may fail.

Complete the following steps to manually install the .NET agent via Nuget.

Step One: Create an application hosted on Azure App Service

• Create an Azure account, if you don't have one already.
• Follow the instructions to create an ASP.NET web application, and deploy it to Azure App Service.
• Publish your application to Azure, and confirm that it works as expected without Contrast.

Step Two: Add the Contrast NuGet Package to your application

In Visual Studio:

• Under the application project in the Solution Explorer, right click on References and select Manage NuGet Packages.

• Search for Contrast.Net.Azure.AppService package, select it and add it to your project.

• Build your application. Confirm that Contrast assemblies (e.g., Contrast.Sensors.dll and ContrastProfiler-32.dll) are in your application's bin directory.

  • You can easily navigate to the bin directory by right clicking on the project in Visual Studio, selecting Open Folder in File Explorer and going to the directory from there.

Step Three: Add application authentication settings for Contrast

There are two primary ways to add the authentication settings that Contrast needs:

• The App Service Settings dialog in Visual Studio's Publish to Azure App Service
• The Azure App Service Portal

You might notice that the following text appears when you installed the Contrast .NET NuGet package:

 Added package 'Contrast.NET.Azure.WebSites.18.X.X' to 'packages.config'
 Executing script file 'C:\yourprojectpath\packages\Contrast.NET.Azure.WebSites.18.4.14\tools\net451\install.ps1'...
 ***Package install is complete***

 Please make sure to add the following configurations to your Azure Web App prior to deploying.
 1. Go to portal.azure.com, log in, go to App Services and navigate to your Web App.
 2. Navigate to the 'Application Settings' section and set the following settings:
 Key Value
 ---------------------------------------
 CONTRAST__API__URL [IF USING A SERVER OTHER THAN THE DEFAULT: https://app.contrastsecurity.com]
 CONTRAST__API__USER_NAME [REPLACE WITH YOUR AGENT USERNAME]
 CONTRAST__API__SERVICE_KEY [REPLACE WITH YOUR AGENT SERVICE KEY]
 CONTRAST__API__API_KEY [REPLACE WITH YOUR AGENT API KEY]
 CONTRAST_INSTALL_DIRECTORY D:\Home\site\wwwroot\contrastsecurity\
 COR_ENABLE_PROFILING 1
 COR_PROFILER {EFEB8EE0-6D39-4347-A5FE-4D0C88BC5BC1}
 COR_PROFILER_PATH_32 D:\Home\site\wwwroot\contrastsecurity\ContrastProfiler-32.dll
 COR_PROFILER_PATH_64 D:\Home\site\wwwroot\contrastsecurity\ContrastProfiler-64.dll

 Go to https://docs.contrastsecurity.com/installation-netazureappservice.html for more configuration options.

Go to the Application Settings area of your application in the Azure Portal. Set the Contrast applications that the agent needs to connect to Contrast, and click Save. (You can get your authentication keys from your Profile in the Contrast UI.)

Step Four: Publish the application to Azure

• Using Visual Studio, publish your application to Azure App Service once more (after you've installed the Contrast NuGet package and specified the Application Settings).

• Once the application has loaded, use the application and then go to the Contrast UI. Verify that the server and application are active, and that any expected vulnerabilities appear.

Update Your Installation

When redeploying a web application that has Contrast agent running, you may run into an error that says "Files in use" on ContrastProfiler-32.dll or ConrastProfiler-64.dll.

This happens because the agent dll files are locked by .NET, and can't be overwritten while the application is still running. The dll files need to be unloaded before publishing. To unload them, stop the site, publish and then start the site back up. Alternately, you can change the COR_ENABLE_PROFILING setting to 0 in the portal, publish and then change the setting back to 1.

The following instructions show you how install and configure the Contrast .NET agent in Docker for Windows using the NuGet package. Examples of the finished code exist in a GitHub repository.

Install the Agent

Complete the following steps to install and configure the agent.

• To begin, use an image based on Microsoft ASP.NET.

• You can download Contrast agent assemblies from the Contrast.NET.Azure.AppService NuGet package.

• Extract the NuGet package, and set the following environment variables on the application process.

• Use the YAML configuration file or environment variables to set Contrast authentication and other settings for the agent.

Examples

Examples of the following use cases are provided in the contrast-dotnet-examples GitHub repository.

ASP.NET application in the default AppPool

• Dockerfile
• Entrypoint script

ASP.NET application in a custom AppPool

• Dockerfile
• Entrypoint script