How Does the Contrast .NET Agent Work? – Contrast Security Support Portal

License Type	SaaS \| On-Premise
Agent Mode	Assess \| Protect
Main Product Category	.NET Agent \|.NET Core Agent
Sub Category

.NET Agent Analysis Techniques

The .NET Agent uses several different approaches to analyze applications to identify vulnerabilities, prevent attacks, and catalog dependencies:

Instrumentation is used to weave in method calls to sensor methods that perform Contrast’s indepth analysis. This includes Assess data flow analysis and control flow analysis as well as Protect attack analysis at sensitive method calls where an attack could cause damage.
Library Identification is used to detect libraries used by the application.
HTTP(S) Analysis is used to capture HTTP(S) requests and responses. The agent then examines the requests and responses for vulnerabilities and attacks.
File Analysis is used to identify vulnerabilities by inspecting static files (e.g. configuration files) used by the application. Each of these techniques are discussed in more depth in the following sections

Instrumentation

We need to review how .NET applications run at a high-level before we can discuss how the Contrast .NET agent works.

.NET applications are written in a high-level programming language such as C#. The language compiler (e.g. Roslyn) creates an executable or assembly that contains:

Metadata describing the application’s new types and methods
Common Intermediate Language (IL) for the instructions of each method

The Common Language Runtime (CLR)’s Just-in-Time (JIT) Compiler then creates native code that is run on the processor. The CLR also provides a number of services including garbage collection, type safety, and a robust Profiling API which a profiler can use to gain information about the runtime and application.

Contrast’s .NET agent profiler component uses several of the functions of the Profiling API to weave in calls to Contrast sensor methods. This instrumentation is very minimal and safe. Contrast instrumentation typically packages up information about a method call (e.g. parameter values) and passes this information to Contrast sensors, which are standard .NET assemblies written in C#.

Contrast agent sensors can use this method-call information to identify vulnerabilities and prevent attacks by analyzing each security-relevant method call within the context of information from previously observed method calls for the HTTP request’s thread(s). The agent instruments and analyzes hundreds of security-relevant methods across the .NET base class library (BCL) and 3rd party libraries. This broad and deep analysis allows the agent to accurately follow control and data flow through the application and reliably detect vulnerabilities and attacks with a very low false positive rate.

Instrumentation-based analysis (e.g. Assess dataflow) is performed inline as each instrumented method is called by the analyzed application or application dependencies.

Library Identification

The Profiling API provides callbacks for when the runtime loads classes, modules, and assemblies. The Contrast .NET agent uses this information to determine what libraries an application uses, as well as which classes are used from each library. Library identification is performed as each assembly is loaded by the runtime.

HTTP(S) Analysis

The Contrast .NET agent leverages the relevant BCL APIs to capture HTTP request and response information. The agent uses instrumentation to add an IHttpModule implementation under ASP.NET and middleware under OWIN or ASP.NET Core. Request analysis is performed at the beginning of each request and response analysis is performed at the end of each request

File Analysis

The .NET Framework agent analyzes static files on disk (e.g. web.config, .aspx) to identify configuration weaknesses such as exposing runtime errors or disabling ASP.NET’s built-in security protections. Configuration analysis is performed using straightforward XML parsing. File analysis is performed after Contrast sensors are initialized when the application is first loaded by the runtime.

Agent Architecture

The Contrast .NET agents consist of multiple components. All agent deployments include the profiler and sensor components. The installed .NET Framework includes additional components:

Windows Installer responsible for placing the agent files at the specified install location and registering the Windows service with the operating system. You can learn more about the agent’s installer here.
Windows Service responsible for registering the profiler with and restarting IIS. The service also receives high-level agent health information from each instance of sensors.
Tray (GUI) Application responsible for retrieving health information from the service and displaying it.
Diagnostics is a command line utility used to troubleshoot and validate agent deployment.

The diagram below shows an example of an installed .NET Framework agent deployment. In this scenario, IIS has loaded three applications. Two applications (App 1, App 2) are hosted in the same application pool/worker process. The .NET runtime provides isolation between these applications via application domains, which also means that each application has its own instance of Contrast .NET agent sensors. A third application (App 3) is hosted in a separate application pool/worker process; this process has a separate instance of the Contrast .NET agent profiler and the application also has its own instance of agent sensors. Each instance of sensors uses named pipe inter-process communication (IPC) to report high-level information about analyzed applications to the agent’s service. HTTPS is used by each instance of sensors to securely report detailed vulnerability, library, and attack information to Contrast.

FAQ

How does the Contrast .NET Agent work alongside 3rd party agents such as APM tools?

By default, “Only one profiler can profile a process at one time in a given environment.” (Microsoft docs) Contrast has worked around this limitation to allow the .NET agent to work alongside other agent tools. There are three approaches:

Under the installed .NET Framework agent, a user can enable the agent’s profiler chaining feature by setting agent.dotnet.enable_chaining to true. When enable_chaining is true, the agent’s service will add a Native Module to IIS. The native module checks the environment variables used to register profilers with the CLR and if found, moves these profiling environment variable values to placeholder environment variables. The native module then replaces the values with Contrast’s profiler values. This causes the CLR to load the Contrast .NET agent profiler. When the placeholder environment variables are found, the Contrast .NET agent profiler will use Windows APIs to load the 3rd party agent profiler. The Contrast .NET agent profiler then acts as a “pass-through” to the runtime’s Profiling API. You can learn more about .NET Framework profiler chaining feature here.
Under Azure App Service Site Extension deployments, the .NET agent site extension includes a configuration file that instructs the CLR Instrumentation Engine to load the Contrast .NET agent profiler. This allows the .NET agent to work alongside AppInsights out-of-the-box. The CLR Instrumentation Engine is a cooperation profiler produced by Microsoft.
Under .NET Core and .NET Framework deployments outside of IIS, the user can set the profiler chaining environment variables. Once set, the Contrast .NET agent profiler will use low-level Windows APIs to load the 3rd party agent profiler and will act as a “pass-through” to the runtime’s Profiling API. You can learn more about .NET Core profiler chaining feature here.

How does the .NET Agent stop attacks in Protect mode?

The agent will throw an exception of type Contrast.Sensors.Protect.AttackBlockedException when an attack is identified and the relevant Protect rule is set to block. Throwing an exception immediately stops the execution of the instrumented method until either the application or container (e.g. ASP.NET) catch the exception. The Contrast AttackBlockedException implements System.Security.SecurityException which can be caught and handled by the application if desired.

What is the difference between the .NET Framework and .NET Core agents?

The .NET Core agent shares a lot of DNA with the .NET Framework agent: both agents include a profiler and sensor components. However, each agent has significantly different business logic necessary to handle the differences between the runtime (CLR vs. Core CLR), containers (ASP.NET vs. ASP.NET Core), and the available APIs (.NET BCL vs. .NET Core BCL.) Due to these differences, the .NET Framework agent can only be used to instrument and analyze .NET Framework applications. Similarly, the .NET Core agent can only be used to instrument .NET Core applications.

What is the difference between the Site Extension and NuGet package?

The primary difference is that the Site Extension is targeted to applications deployed to Azure App Service while the Sensors Nuget packages are targeted to a broader set of deployments.

Contrast publishes four packages to Nuget:

.NET Framework and .NET Core Site Extension: includes the agent’s profiler and sensor components to support applications deployed to Azure App Service. These Site Extensions can be added using the Azure Portal. The Site Extensions automatically register the agent’s profiler with the runtime using Kudu XDT transforms. More information is available for .NET Framework and .NET Core.
.NET Framework and .NET Core Sensors: includes the agent’s profiler and sensor components. The Nuget packages can be used to add the agent to an application like any other Nuget package. The agent will then be deployed alongside the application’s binaries. The Nuget package can also be downloaded and extracted independent of an application such as in our recommended Docker deployment for .NET Framework.

Resources

Contrast Documentation

.NET Framework Agent: https://docs.contrastsecurity.com/en/-net-framework.html
.NET Core Agent: https://docs.contrastsecurity.com/en/-net-core.html

.NET Runtime and Compilation

.NET Profiling API

Example Profilers

.NET Agent articles: