Skip to main content

Install the .NET Core agent manually

Use this method to install the .NET Core agent if you are using a web application hosted on IIS, or running a self-hosted application on Windows, Linux or Docker.

Note

Installing within containers can be complex, and these steps might not work for your situation. Read more about installing with Docker.

Before you begin

Check the system requirements and supported technologies to be sure installation will work and ensure best performance.

Steps

  1. Download the agent:

    1. At the top right of the Contrast web interface, select Add new.

    2. Select the Application card.

    3. Select the operating system you are using.

    4. Select a method to install the agent.

    5. Download the agent configuration file.

      Tip

      Use the Contrast agent configuration editor to make the agent configuration easier.

    6. Download the agent.

  2. On the web server, extract the downloaded ZIP archive (for example, Contrast.NET.Core_1.0.1.zip) to a directory that your applications have sufficient permissions to access. 

  3. Set the following environment variables on your application's process. Use the appropriate CORECLR_PROFILER_PATH settings for your operating system. Replace <UnzippedDirectoryRoot> with your archive directory.

    • Windows

      Environment variable

      Value

      CORECLR_PROFILER_PATH_64

      <UnzippedDirectoryRoot>\runtimes\win-x64\native\ContrastProfiler.dll

      CORECLR_PROFILER_PATH_32

      <UnzippedDirectoryRoot>\runtimes\win-x86\native\ContrastProfiler.dll

      CORECLR_PROFILER

      {8B2CE134-0948-48CA-A4B2-80DDAD9F5791}

      CORECLR_ENABLE_PROFILING

      1

      CONTRAST_CONFIG_PATH

      <path_to_contrast_security.yaml>

      Important

      If you are running the .NET Core agent and the .NET Framework agent on the same server, the CONTRAST_CONFIG_PATH option applies to the load path for both agents. To apply distinct paths for each agent, use these options to set the data directory:

      • CONTRAST_CORECLR_DATA_DIRECTORY

      • CONTRAST_DATA_DIRECTORY

    • Linux x64

      Environment variable

      Value

      CORECLR_PROFILER_PATH_64

      <UnzippedDirectoryRoot>/runtimes/linux-x64/native/ContrastProfiler.so

      CORECLR_PROFILER

      {8B2CE134-0948-48CA-A4B2-80DDAD9F5791}

      CORECLR_ENABLE_PROFILING

      1

      CONTRAST_CONFIG_PATH

      <path_to_contrast_security.yaml>

    • Linux ARM64

      Environment variable

      Value

      CORECLR_PROFILER_PATH_64

      <UnzippedDirectoryRoot>/runtimes/linux-arm64/native/ContrastProfiler.so

      CORECLR_PROFILER

      {8B2CE134-0948-48CA-A4B2-80DDAD9F5791}

      CORECLR_ENABLE_PROFILING

      1

      CONTRAST_CONFIG_PATH

      <path_to_contrast_security.yaml>

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

    Path

    Usage

    Customizable

    Permissions

    The path to .NET Core YAML

    Configures the agent

    Yes; set the environment variable CONTRAST_CONFIG_PATH

    Read

    <UnzippedDirectoryRoot>

    The root "installation" directory; stores the agent binaries

    No

    Read

    • Windows:%ProgramData%\Contrast\dotnet-core\logs

    • Linux: /var/tmp/contrast/dotnet-core/logs

    Directory for Contrast agent logs. If missing, the directory will be created

    Yes; set the environment variable CONTRAST_CORECLR_LOGS_DIRECTORY

    Read/Write(or inherited from a parent directory)

    Note

    When running in IIS, make sure that the application pool can access these paths.

    For example, given an application pool called Default Web Site using the default identity ApplicationPoolIdentity, ensure that the user IIS AppPool\Default Web Site has effective permissions to read the unzipped directory root.

  5. Configure the agent with authentication credentials and proxy settings to connect to Contrast.

  6. Once the application has loaded, use the application and then verify that the server and application are active in Contrast, and that any expected vulnerabilities appear.

    Tip

    To update the agent, replace the agent files in the agent directory and restart your application. As the agent is running alongside your application, it can't update itself.

    The agent automatically starts with your application as long as the environment is properly set up.

    To stop the agent, stop the application and remove agent from its environment. Alternatively, you may change the CORECLR_ENABLE_PROFILING setting to 0.

    Follow any of these examples to set environment variables using:

IIS and IIS Express

Set the environment variables with either:

  • The environmentVariables section in the application web.config 

    <?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

Bash (Linux)

Linux x64:

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

Linux ARM64:

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

Then run the application:

dotnet ./MyAppWithContrastAgent.dll

Powershell or Powershell Core (Windows)

$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' 

Then run the application:

dotnet .\MyAppWithContrastAgent.dll

Launch profile (dotnet.exe)

{
    "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"
        }
    }
}

Then run the application:

dotnet run --launch-profile MyAppWithContrastAgent
In this section: