Standard installation for the .NET Core agent

To install the .NET Core agent:

  1. Download the .NET Core agent from the Contrast web interface.

    Note

    You might need to specify proxy authentication information, if required by your network, before downloading 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 following table to find the correct CORECLR_PROFILER_PATH setting for the given architecture:

    Environment variable

    Platform

    Value

    CORECLR_PROFILER_PATH_64

    Windows (64-bit)

    runtimes\win-x64\native\ContrastProfiler.dll

    CORECLR_PROFILER_PATH_32

    Windows (32-bit)

    runtimes\win-x86\native\ContrastProfiler.dll

    CORECLR_PROFILER_PATH_64

    Linux (64-bit)

    runtimes/linux-x64/native/ContrastProfiler.so

    CORECLR_PROFILER

    All

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

    CORECLR_ENABLE_PROFILING

    All

    1

    CONTRAST_CONFIG_PATH

    All

    \contrast_security.yaml Learn more about load path.

    Note

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

    Tip

    See environment variable examples for Powershell (Windows), Bash (Linux), IIS and IIS Express or dotnet.exe launch profile.

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

    Path

    Usage

    Customizable

    Permissions

    The path to contrast_security.yaml

    Configures the agent

    Yes; set the environment variable CONTRAST_CONFIG_PATH

    Read

    {{ Unzipped Directory Root }}

    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. Use the .NET Core agent contrast_security_yaml file to configure 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.

Tip

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".

Here are some environment variable examples for installing the .NET Core agent in different environments:

Powershell

You can use Powershell or Powershell Core (Windows) to set the environment variables for standard installation of the .NET Core agent.

$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

Bash (Linux)

You can use the dotnet.exe launch profile to set the environment variables for the standard installation process.

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 

Then run the application:

dotnet ./MyAppWithContrastAgent.dll

IIS and IIS Express

You can use IIS and IIS Express to set the environment variables for the standard installation process using either of these methods.

  • Use the environmentVariables section in the application web.config using ASP.NET Module Configuration.

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

Launch profile (dotnet.exe)

You can use the dotnet.exe launch profile to set the environment variables for the standard installation process.

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