To install the .NET agent, complete the following steps.
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.
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
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.
Complete the following steps for express installation of the .NET agent via Azure Portal Extensions.
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) |
Note: The agent can also be installed from the Site Extensions area of your application management SCM (Kudu) site.
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.
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.
There are two primary ways to add the authentication settings that Contrast needs:
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.)
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.
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
.