Installation

Standard Installation

The Basics

To install the .NET agent, complete the following steps. The installation process for self-hosted applications also applies to IIS Express users.

  • Log in to the Contrast UI.
  • Click the Add Agent button in the top navigation bar.
  • Select .NET Core in the dropdown menu, and click the Download Agent button for the platform on which your application is hosted. You might need to specify proxy authentication information, if required by your network, before downloading the agent.
  • Proceed to Step 2, and click on the Download Config File button to download the agent's configurations.
  • On the web server, extract the downloaded zip archive (e.g., Contrast.NET.Core_0.20.1.zip) to a directory that your applications have sufficient permissions to access.
  • On the web server, place the downloaded configuration file in a directory that your applications have sufficient permissions to access.

Customize Your Installation

The agent uses the downloaded configuration file, contrast_security.yaml, to configure authentication credentials and proxy settings to connect to Contrast. You can fully configure the agent using the YAML file. See the agent configuration guidelines for more information.

Permissions

Ensure that the following paths are accessible by the runtime user of the application.

Path Usage Customizable Permissions
The path to YAML configuration file, such as contrast_security.yaml Used to configure the agent Yes; set the environment variable CONTRAST_CONFIG_PATH Read
{{ Unzipped Directory Root }} The root "installation" directory; stores the agent binaries No Read
%ProgramData%\Contrast\dotnet-core\logs (Windows)

/var/tmp/contrast/dotnet-core/logs (Linux)
Logs the directory; if missing, the directory will be created Yes; set the environment variable CONTRAST_CORECLR_LOGS_DIRECTORY Read/Write
(or inherited from a parent directory)

When running in IIS, make sure the application pool can access the these paths. For example, given an application pool called Default Web Site using the default identity ApplicationPoolIdentity, ensure the user IIS AppPool\Default Web Site has the effective permissions to read the unzipped directory root.

Enable the Agent

To enable the .NET Core agent on your application, you must set the following environment variables on your application's process.

  • CORECLR_PROFILER_PATH_64: Use the following table to find the correct Profiler path for 64-bit applications.
  • CORECLR_PROFILER_PATH_32: Use the following table to find the correct Profiler path for 32-bit applications. (Windows)
  • CORECLR_ENABLE_PROFILING: 1
  • CORECLR_PROFILER: {8B2CE134-0948-48CA-A4B2-80DDAD9F5791}
  • CONTRAST_CONFIG_PATH: Set the path to the YAML configuration file. It can be an absolute path (i.e., C:\contrast\contrast_security.yaml or /opt/contrast/contrast_security.yaml) or a path relative to your application process's current directory (i.e., my_custom_config.yaml). If not set, the default is C:\ProgramData\Contrast\dotnet-core\contrast_security.yaml (Windows) or /etc/contrast/dotnet-core/contrast_security.yaml (Linux). This setting is optional.
Environment Variable Platform Profiler Path
CORECLR_PROFILER_PATH_64 Windows (64-bit) {{ Unzipped Directory Root }}\runtimes\win-x64\native\ContrastProfiler.dll
CORECLR_PROFILER_PATH_32 Windows (32-bit) {{ Unzipped Directory Root }}\runtimes\win-x86\native\ContrastProfiler.dll
CORECLR_PROFILER_PATH_64 Linux (64-bit) {{ Unzipped Directory Root }}\runtimes\linux-x64\native\ContrastProfiler.so

Note: The platform's CPU architecture is based on the CoreCLR's bitness. For example, when using a 32-bit CoreCLR, you must use the 32-bit profiler, even if the OS is 64-bit.

Running from Powershell or Powershell Core (Windows)

Windows users running from Powershell or Powershell Core can set the environment variables.

Example:

$env:CORECLR_PROFILER_PATH_64 = 'C:\contrast\dotnetcore\runtimes\win-x64\native\ContrastProfiler.dll'
$env:CORECLR_PROFILER_PATH_32 = 'C:\contrast\dotnetcore\runtimes\win-x86\native\ContrastProfiler.dll'
$env:CORECLR_ENABLE_PROFILING = '1'
$env:CORECLR_PROFILER = '{8B2CE134-0948-48CA-A4B2-80DDAD9F5791}'
$env:CONTRAST_CONFIG_PATH = 'C:\contrast\dotnet-core\contrast_security.yaml'

You can then run the application:

dotnet .\MyAppWithContrastAgent.dll

Running from Bash (Linux)

Linux users running from Bash can set the environment variables.

Example:

export CORECLR_PROFILER_PATH_64=/contrast/runtimes/linux-x64/native/ContrastProfiler.so
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={8B2CE134-0948-48CA-A4B2-80DDAD9F5791}
export CONTRAST_CONFIG_PATH=/contrast/contrast_security.yaml

You can then run the application:

dotnet ./MyAppWithContrastAgent.dll

Running under IIS and IIS Express

Users running under IIS and IIS Express can set the environment variables using either of these two methods.

  • The environmentVariables section in the application web.config via ASP.NET Module Configuration, as shown below (recommended)

    <?xml version="1.0" encoding="utf-8"?>
    <configuration>
    <system.webServer>
      ...
      <aspNetCore processPath="dotnet" arguments=".\ExampleNetCoreApp.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout">
        <environmentVariables>
          <environmentVariable name="CORECLR_PROFILER_PATH_64" value="C:\contrast\dotnetcore\runtimes\win-x64\native\ContrastProfiler.dll" />
          <environmentVariable name="CORECLR_PROFILER_PATH_32" value="C:\contrast\dotnetcore\runtimes\win-x86\native\ContrastProfiler.dll" />
          <environmentVariable name="CORECLR_ENABLE_PROFILING" value="1" />
          <environmentVariable name="CORECLR_PROFILER" value="{8B2CE134-0948-48CA-A4B2-80DDAD9F5791}" />
          <environmentVariable name="CONTRAST_CONFIG_PATH" value="C:\contrast\dotnet-core\contrast_security.yaml" />
        </environmentVariables>
      </aspNetCore>
    </system.webServer>
    </configuration>
    
  • The application pool setting on the server

Running with a dotnet.exe launch profile

Users running with a dotnet.exe launch profile can set the environment variables as part of your application startup script or as an ASP.NET Core launch profile.

Example:

    "MyAppWithContrastAgent": {
      "environmentVariables": {
        "CORECLR_PROFILER_PATH_64": "C:\\contrast\\dotnetcore\\runtimes\\win-x64\\native\\ContrastProfiler.dll",
        "CORECLR_PROFILER_PATH_32": "C:\\contrast\\dotnetcore\\runtimes\\win-x86\\native\\ContrastProfiler.dll",
        "CORECLR_ENABLE_PROFILING": "1",
        "CORECLR_PROFILER": "{8B2CE134-0948-48CA-A4B2-80DDAD9F5791}",
        "CONTRAST_CONFIG_PATH": "c:\\contrast\\config\\MyApp\\contrast_security.yaml",
      }
    }

You can then run the application:

dotnet run --launch-profile MyAppWithContrastAgent

Next Steps

Profiler Chaining

About Contrast Profiler Chaining

Contrast profiler chaining allows the .NET Core agent to run alongside another .NET Core APM profiler, such as the ones provided by AppDynamics or New Relic.

To achieve profiler chaining, you should replace the CORECLR environment variables for the APM with CONTRAST_CCC_CORECLR versions. Any of the following environment variable names that exist should be transformed:

  • CORECLR_PROFILER -> CONTRAST_CCC_CORECLR_PROFILER
  • CORECLR_PROFILER_PATH -> CONTRAST_CCC_CORECLR_PROFILER_PATH
  • CORECLR_PROFILER_PATH_32 -> CONTRAST_CCC_CORECLR_PROFILER_PATH_32
  • CORECLR_PROFILER_PATH_64 -> CONTRAST_CCC_CORECLR_PROFILER_PATH_64

Use the following sets of instructions, which include the changes described above, to set up profiler chaining with New Relic or AppDynamics.

New Relic

Complete the following steps to install the .NET Core agent alongside the New Relic agent.

  • Install the New Relic agent.

  • Change the environment variable keys as follows:

    • CORECLR_PROFILER -> CONTRAST_CCC_CORECLR_PROFILER
    • CORECLR_PROFILER_PATH -> CONTRAST_CCC_CORECLR_PROFILER_PATH
    • The New Relic environment should should be similar to:

      CORECLR_ENABLE_PROFILING=1
      CONTRAST_CCC_CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
      CORECLR_NEWRELIC_HOME=PATH\TO\INSTALL
      CONTRAST_CCC_CORECLR_PROFILER_PATH=%CORECLR_NEWRELIC_HOME%\NewRelic.Profiler.dll
      NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY
      NEW_RELIC_APP_NAME=YOUR_APP_NAME
      
  • Follow the directions to install the Contrast .NET Core agent.

    • The application environment with Contrast and New Relic should look like:

      CORECLR_ENABLE_PROFILING=1
      CONTRAST_CCC_CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
      CORECLR_NEWRELIC_HOME=PATH\TO\INSTALL
      CONTRAST_CCC_CORECLR_PROFILER_PATH=%CORECLR_NEWRELIC_HOME%\NewRelic.Profiler.dll
      NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY
      NEW_RELIC_APP_NAME=YOUR_APP_NAME
      CORECLR_PROFILER_PATH_64=<CONTRAST_CORE_CLR_HOME>\runtimes\win-x64\native\ContrastProfiler.dll
      CORECLR_PROFILER_PATH_32=<CONTRAST_CORE_CLR_HOME>\runtimes\win-x86\native\ContrastProfiler.dll
      CORECLR_PROFILER={8B2CE134-0948-48CA-A4B2-80DDAD9F5791}
      CONTRAST_CONFIG_PATH=<CONTRAST_CORE_CLR_CONFIG_PATH>\contrast_security.yaml
      

AppDynamics

Complete the following steps to install the .NET Core agent alongside the AppDynamics agent.

  • Install the AppDynamics agent.

  • Change the environment variable keys as follows:

    • CORECLR_PROFILER -> CONTRAST_CCC_CORECLR_PROFILER
    • CORECLR_PROFILER_PATH_32 -> CONTRAST_CCC_CORECLR_PROFILER_PATH_32
    • CORECLR_PROFILER_PATH_64 -> CONTRAST_CCC_CORECLR_PROFILER_PATH_64
    • The AppDynamics environment should be similar to:

      CORECLR_ENABLE_PROFILING=1
      CONTRAST_CCC_CORECLR_PROFILER={39AEABC1-56A5-405F-B8E7-C3668490DB4A}
      CONTRAST_CCC_CORECLR_PROFILER_PATH_32=<actual_path>\AppDynamics.Profiler_x86.dll
      CONTRAST_CCC_CORECLR_PROFILER_PATH_64=<actual_path>\AppDynamics.Profiler_x64.dll
      
  • Follow the directions to install the Contrast .NET Core agent.

    • The application environment with Contrast and AppDynamics should look like:

      CORECLR_ENABLE_PROFILING=1
      CONTRAST_CCC_CORECLR_PROFILER={39AEABC1-56A5-405F-B8E7-C3668490DB4A}
      CONTRAST_CCC_CORECLR_PROFILER_PATH_32=<actual_path>\AppDynamics.Profiler_x86.dll
      CONTRAST_CCC_CORECLR_PROFILER_PATH_64=<actual_path>\AppDynamics.Profiler_x64.dll
      CORECLR_PROFILER_PATH_64=<CONTRAST_CORE_CLR_HOME>\runtimes\win-x64\native\ContrastProfiler.dll
      CORECLR_PROFILER_PATH_32=<CONTRAST_CORE_CLR_HOME>\runtimes\win-x86\native\ContrastProfiler.dll
      CORECLR_PROFILER={8B2CE134-0948-48CA-A4B2-80DDAD9F5791}
      CONTRAST_CONFIG_PATH=<CONTRAST_CORE_CLR_CONFIG_PATH>\contrast_security.yaml
      

Next Steps

Express Installation for Azure App Service

Complete the following steps for express installation of the .NET Core 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.
  • Ensure that your application is deployed using a Windows plan. (Linux plans are not supported when using the .NET Core site extension.)

Step Two: Add application settings for Contrast

The following values are the application settings that the agent needs to connect to Contrast. You should add these values using the Configuration\Application Settings blade for your application. You can get your authentication keys from your Profile in the Contrast UI.

Key Value
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__API__URL 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 Core Site Extension. This is the extension for .NET Core 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.

Manual Installation for Azure App Service

Complete the following steps to manually install the .NET Core 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.SensorsNetCore package, select it and add it to your project.

  • Build your application. Confirm that a contrast folder appears in your project. When the application is published, this folder appears in the build output 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 Core Agent Readme ------------------
------------------------------------------------------------

This package includes files required to run the Contrast .NET Core agent.  These files have been installed in your "<application directory>/contrast" folder
To use the Contrast agent, you must set following environment variables on your application process.

CORECLR_ENABLE_PROFILING: 1
CORECLR_PROFILER: {8B2CE134-0948-48CA-A4B2-80DDAD9F5791}
CORECLR_PROFILER_PATH_32: <application directory>\contrast\runtimes\win-x86\native\ContrastProfiler.dll
CORECLR_PROFILER_PATH_64: <application directory>\contrast\runtimes\win-x64\native\ContrastProfiler.dll

The agent requires valid authentication to the Contrast web site.  To configure the agent using the yaml configuration add this
environment variable.  More information: https://docs.contrastsecurity.com/installation-netcoreconfig.html#netcore-template

CONTRAST_CONFIG_PATH: [Path to yaml config file]

Alternately the agent can be fully configured using environment variables   At minimum the following are required:

CONTRAST__API__URL: [IF USING ANOTHER SERVER 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]

---------- Stand-alone process or Docker Containers ---------
Set the environment using your shell or Docker container.
More information: https://docs.contrastsecurity.com/installation-netcoreinstall.html#netcore-install


---------- Azure App Service --------------------------------
Set the environment variables in the your App Service web app.
1. Go to portal.azure.com, log in, go to App Services and navigate to your Web App.
2. Navigate to the 'Configuration' section.
3. Add all the settings described above in the 'Application settings' area.  They will be added as environment variables in your application process.
4. Save changes to restart the application.

---------- IIS Hosted ---------------------------------------
Add the environment variables in the <environmentVariables> section of the <system.webServer><aspnetNetCore> section in the web.config file.
More information: https://docs.contrastsecurity.com/installation-netcoreinstall.html#running-under-iis-and-iis-express
  • Go to the Configuration\Application Settings blade 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 updated the Configuration\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 ContrastProfiler-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 must be unloaded before publishing. To unload them, stop the site, publish and then start the site back up. Alternately, you can change the CORECLR_ENABLE_PROFILING setting to 0 in the portal, publish and then change the setting back to 1.