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 and Custom Installations

The .NET agent installer can be customized using command line options. See the installer command line options for more information.

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. This is the extension for .NET Framework applications.

• 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: You can also install the agent 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's 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., ContrastProfiler-64.dll) are in a new contrastsecurity folder that's created in application's root directory.

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:

------------------------------------------------------------
---- Contrast .NET Framework Agent for Azure App Service ---
------------------------------------------------------------

This package includes files required to run the Contrast .NET Core agent.  These files have been installed in your "<application directory>/contrastsecurity" folder
To use the Contrast agent, you must set following settings on your Azure App Service Web App.

1. Publish your app to Azure App Service.

2. Go to portal.azure.com, log in, go to App Services and navigate to your Web App.

3. Navigate to the Configuration section and then set the following in the 'Application Settings' area.

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
CONTRAST_INSTALL_DIRECTORY:        D:\Home\site\wwwroot\contrastsecurity\

If using a configuration yaml file, include it in the application and set this setting.
CONTRAST_CONFIG_PATH:           D:\Home\site\wwwroot\[path to contrast_security.yaml within the application]

Alternately the agent can be configured with environment variables.  At minimum set these settings for authentication:

CONTRAST__API__URL:             [Optional, if using another server than the default: https://app.contrastsecurity.com]
CONTRAST__API__USER_NAME:       [Replace with agent user name]
CONTRAST__API__SERVICE_KEY:     [Replace with agent service key]
CONTRAST__API__API_KEY:         [Replace with agent api key]

4. Save changes to the Configuration section.


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

Go to the Application Settings area of your application in the Azure Portal. Set the Contrast authentication keys 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-64.dll or ConrastProfiler-32.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

Use the command line to access additional options supported by the .NET agent installer.

Command Line Operations

The .NET agent can be installed using the Windows UI, and uninstalled or repaired using standard Windows features including the Programs and Features Control Panel, Powershell, etc. However, you may want to use the .NET agent installer to perform these actions instead for certain scenarios such as automated scripting.

Attended

• Install: ContrastSetup.exe
• Uninstall: ContrastSetup.exe -uninstall
• Repair: ContrastSetup.exe -repair

Unattended or silent

• Install: ContrastSetup.exe -s -norestart
• Uninstall: ContrastSetup.exe -uninstall -s -norestart
• Repair: ContrastSetup.exe -repair -s -norestart

Custom Installation

The .NET agent installer supports several additional options that are accessible when you use the command line for installation. Supported options are shown in the following table.

Example

To install the .NET agent using scripts, the following command is commonly used:

ContrastSetup.exe -s -norestart StartTray=0 PathToYaml=C:\Temp\custom.yaml

This command installs the .NET agent in silent and unattended mode, suppresses the start of the Tray application and use a custom path to the YAML configuration file.