Installation

Installation for Windows

The Basics

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

  • Log in to the Contrast interface.
  • 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 Installer

The downloaded zip archive contains a file called DotnetAgentSettings.ini, which is used to bootstrap your installation by pre-setting the application config file with your authentication credentials and proxy settings. The following settings can also be added to the ini file.

These additional settings allow you to pre-populate your configuration with commonly changed settings.

Example: To disable automatic updates of the .NET agent, update the ini file, add AutoUpdateEnabled=false on a new line, and then continue the installation as normal.

Parameter Description Version
AutoUpdateEnabled Sets the AutoUpdateBehavior setting in the config file. Setting this to true sets update behavior to Daily; setting it to false sets it to Disabled. 4.6+
EncryptProtectedSettings Sets the corresponding EncryptProtectedSettings setting in the config file, and controls whether ProxyUser and ProxyPass settings are encrypted. See Proxy Credentials for more information. 4.2.0+
ProfilerChainingEnabled Sets the corresponding ProfilerChainingEnabled setting in the config file. If enabled, Contrast will start and work alongside other agents installed that are using the .NET Porfiler API like NewRelic, AppDynamics or Dynatrace. The default setting is false; Contrast will fail to start if it detects another program using the .NET Profiler API, which allows the other program/agent to continue working. If set to true, Contrast will start and chain the pre-existing agent and both agents will work side-by-side. 18.10.35+
RestartIISOnConfigChange Sets the corresponding RestartIISOnConfigChange setting in the config file. If enabled, Contrast will automatically restart IIS in the background if any of the configuration settings that require IIS restart are changed. Changes that require restart are those that enable or disable Assess or Defend mode, add security controls, or change process whitelist or blacklist. These changes can come from changing the application config file or from Contrast website. The default value is true. If set to false, you must restart IIS for changes to the stated configuration settings to take effect. 18.4.69+
ServerEnvironment Controls the environment value sent to Contrast. Valid ServerEnvironment values are DEVELOPMENT, QA or PRODUCTION. The default value is QA. 3.4.2+

Silent Installation

The .NET agent installer supports the command line options below. 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

  • 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 what 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:\ProgramFiles\Contrast\dotnet). This includes several dynamic link library (DLLs) and executables, such as the background Windows service that drives agent behavior.
  • Creates the specified data directory for the agent that is primarily used to store agent log files (e.g., C:\ProgramData\Contrast\dotnet).
  • Registers the agent’s background Window service with the operating system.
  • Reads the DotnetAgentSettings.ini file to customize the agent’s configuration file with details necessary to communicate with the Contrast application (e.g., API key).
  • Registers several agent assemblies with the .NET global assembly cache so they can be loaded by instrumented applications.
  • 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 interface.
    • Communication with Profiler and Sensor components through local named pipes.

Next Steps

Express Installation for Azure App Service

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.

Key Value
CONTRAST_TeamServerUserName Replace with your agent username.
CONTRAST_TeamServerServiceKey Replace with your agent service key.
CONTRAST_TeamServerApiKey Replace with your agent API key.
CONTRAST_TeamServerUrl Defaults to https://app.contrastsecurity.com. Replace with another URL, if you're using a Contrast application that's hosted elsewhere. (Optional)

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.

Manual Installation for Azure App Service

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

Step One: Create an application hosted on Azure App Service

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_TeamServerUrl [IF USING ANOTHER SERVER THAN THE DEFAULT: https://app.contrastsecurity.com]
 CONTRAST_TeamServerUserName [REPLACE WITH YOUR AGENT USERNAME]
 CONTRAST_TeamServerServiceKey [REPLACE WITH YOUR AGENT SERVICE KEY]
 CONTRAST_TeamServerApiKey [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.