Setting up and Configuring the CxIAST C# Agent in the AUT Environment

This section explains how to set up and configure the C# (.NET) agent in the application testing environment (AUT).

Pre-Requisites

Application servers running on C# require .NET Framework or .NET Core as as listed under Supported Environments for Applications Under Testing.

Note

There is no other .NET/.NET Core Profiler installed on the host.

Installing and Removing .NET Agent

Extract the .NET Agent.zip archive to a folder of your choice on the host where the AUT (application under test) is going to run.

To install the CxIAST Agent, run the 'CxIAST.bat' file...

CxIAST.bat -a -app=<app_name_1> -app=<app_name_2>, …

To monitor IIS, enter...

CxIAST.bat -a -app=w3wp

Note

w3wp is the process name of the IIS application.
APP_NAME can be part of an application name, like w3, meaning that all processes that contain w3 as part of their name are monitored by CxIAST.
Use the -app parameter for every application to be monitored.

To monitor both IIS and IIS Express, enter...

CxIAST.bat -a -app=w3wp -app=iisexpress

To monitor an unsafe-only application pool, enter...

CxIAST.bat -a –app=w3wp:appPool

To monitor two application pools, enter...

CxIAST.bat -a –app=w3wp:appPool1 –app=w3wp:appPool2

After the process name, you can add `:` and partial strings from the process command line.

Note

There is currently no support for monitoring a single application within an application pool.
To start monitoring, restart the application.
In case of IIS, the application restarts automatically.

Installing .NET Core

Download the agent zip archive to a folder of your choice on your PC.
Extract the agent zip archive to Azure and place its contents under D:/home/site/cx-agent. The CxHome folder from the zip archive resides then under D:/home/site/cx-agent.
Verify that the IAST Manager is accessible from inside the Azure application service. To test it, go to the Azure web portal, and under Development Tools, go to Console and run curl <MANAGER_ORIGIN>/ 2>&1.
In the Azure web portal, select your application service and navigate to Configuration.

Add the application settings below, which also serve as environment variables:Add the application settings below, which also serve as environment variables:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={FBCC3F30-6581-4C64-B7C7-03B777F29D27}
CORECLR_PROFILER_PATH_32=D:/home/site/cx-agent/CxHome/engine_bin/DotNetProfilerEngine_x86d.dll
CORECLR_PROFILER_PATH_64=D:/home/site/cx-agent/CxHome/engine_bin/DotNetProfilerEngine_x64d.dll
Cx_IAST_NET_CORE_HOME=D:/home/site/cx-agent/CxHome

Add the application setting Cx_IAST_CORE_PROCESS_TO_MONITOR with the value dotnet:MyApp;MyApp. MyApp is the full or partial name of the application executable, which means that in order to run the application locally, you use dotnet MyApp.dll or MyApp.exe.
Save your settings. Your application restarts

Note

Due to the application service structure, the project name in the IAST Manager defaults to wwwroot. To assign a different name to the project, set the ProjectName key in D:/home/site/cx-agent/CxHome/Profiler.dll.config to the desired project name.
You are not able to download the currently running agent logs via FTP while the application is running. You can download them once the application has stopped.

Download the agent zip archive to a folder of your choice on your PC.
Extract the agent zip archive to Azure and place its contents under /home/site/cx-agent. The CxHome folder in the zip archive resides then under /home/site/cx-agent.
Verify that the IAST Manager is accessible from inside the Azure application service. To test it, go to the Azure web portal, and under Development Tools, go to SSH and run curl <MANAGER_ORIGIN>/.
In the Azure web portal, select your application service and navigate to Configuration.

Add the followAdd the following application settings, which also serve as environment variables:ing application settings, which also serve as environment variables:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={FBCC3F30-6581-4C64-B7C7-03B777F29D27}
CORECLR_PROFILER_PATH_64=/home/site/cx-agent/CxHome/engine_bin/DotNetProfilerEngine_x64d.so
Cx_IAST_NET_CORE_HOME=/home/site/cx-agent/CxHome

Save your settings. Your application restarts.

Note

Due to the application service structure, the project name in the IAST Manager defaults to 'wwwroot'. To assign the desired project name, set the ProjectName key to the desired project name. The ProjectName key is located in /home/site/cx-agent/CxHome/Profiler.dll.config.
You are not able to download the currently running agent logs via FTP while the application is running. You can download them once the application has stopped.

The following optional parameters can be added to the end of the CxIAST.bat/sh command:

-projectTag
-scanTag
-team

Example:

CxIAST.bat -a –app=w3wp -projectTag=my_projectTag -scanTag=my_scanTag -team=my_team

Note

If the installation requires scan metadata tags, the parameters listed above become mandatory and you get an error if one of them is missing.

Running the Application under Testing on .NET Core

To run the CxIAST agent, run the CxIAST_CORE.bat file as outlined below.

Execute

To execute standalone, kestrel or self-hosted web applications, open a command line interface instance (CMD) and enter the following:

CxIAST_CORE.bat -e -app=<app_name_1> -app=<app_name_2>, …

This applies the required environment variables and you can now start the application from the same command line interface as usual, for example, if you run your application using dotnet My.App.dll, enter...

CxIAST_CORE.bat -e –app=dotnet

When done, run dotnet My.App.dll from the same command line.

Add

To install the agent on the host, enter the following:

CxIAST_CORE.bat -a -app=<app_name_1> -app=<app_name_2>, …>]

Restart your application. The application now runs with the agent.

Note

You have to use the same syntax as you do for executing, just instead of using `-e` for executing, you use `-a` for adding.
When running as a service, you might have to restart the host for the changes to take effect.

For example, to monitor dotnet under IIS, enter...

CxIAST_CORE.bat -a –app=dotnet

Remove

If you installed the agent using -a, you can remove it by entering the following:

CxIAST_CORE.bat -r

Restart the application to stop monitoring the application.

Note

When running as a service, you might have to restart the host for the changes to take effect.

Docker File Example

To run a test application with the .NET Core agent using Docker, follow the instructions below.

Note

These instructions apply to using a Docker file or Docker Compose.

Obtain the agent by downloading the agent zip archive and extracting it. Use one of the following options:
- Option 1: Copy the folder into the Docker image.
- Option 2: Use a volume to map the extracted folder into the image.
Run the test application with the .NET Core agent by using one of the following options:
- Option 1: Start the application by running CxIAST_CORE.sh.
  - Change `dotnet MyApp.dll` to /cx-agent/CxIAST_CORE.sh 'dotnet MyApp.dll' in the command line interface.
- Option 2: Add environment variables manually:
  - Add the variables below to the Dockerfile. You may use -e when running the container.

ENV CORECLR_ENABLE_PROFILING=1\
          CORECLR_PROFILER="{FBCC3F30-6581-4C64-B7C7-03B777F29D27}"\
          CORECLR_PROFILER_PATH_64="/cx-agent/CxHome/engine_bin/DotNetProfilerEngine_x64d.so"\
          Cx_IAST_CORE_PROCESS_TO_MONITOR=*\
          Cx_IAST_NET_CORE_DEBUG=0\
          Cx_IAST_NET_CORE_HOME="/cx-agent/CxHome"

Docker Compose Example

Assuming you have the following YML file:

webapp:
        image: mcr.microsoft.com/dotnet/core/aspnet:2.1
        ports:
                - 8080:8080
db: ...

To run it with the agent, add an environment variable and a volume as follows:

webapp:
image: mcr.microsoft.com/dotnet/core/aspnet:2.1
ports:
        - 8080:8080
environment:
        - CORECLR_ENABLE_PROFILING=1
        - CORECLR_PROFILER="{FBCC3F30-6581-4C64-B7C7-03B777F29D27}"
        - CORECLR_PROFILER_PATH_64="/cx-agent/CxHome/engine_bin/DotNetProfilerEngine_x64d.so"
        - Cx_IAST_CORE_PROCESS_TO_MONITOR=*
        - Cx_IAST_NET_CORE_DEBUG=0
        - Cx_IAST_NET_CORE_HOME="/cx-agent/CxHome"
volumes:
        - /agent/folder:/cx-agent
db: ...

Installing and Running the Application under Testing on .NET Framework

Download the agent zip archive to a folder of your choice on your PC.
Extract the agent zip archive to Azure and place its content under D:/home/site/cx-agent. The CxHome folder from the zip archive resides then under D:/home/site/cx-agent.
Verify that the IAST Manager is accessible from inside the Azure application service. To test it, go to the Azure web portal, and under Development Tools, go to Console and run curl <MANAGER_ORIGIN>/ 2>&1.
In the Azure web portal, select your application service and navigate to Configuration.

Add the following application settings, which also serve as environment variables.

COR_ENABLE_PROFILING=1
COR_PROFILER={FBCC3F30-6581-4C64-B7C7-03B777F29D27}
COR_PROFILER_PATH_32=D:/home/site/cx-agent/CxHome/engine_bin/DotNetProfilerEngine_x86d.dll
COR_PROFILER_PATH_64=D:/home/site/cx-agent/CxHome/engine_bin/DotNetProfilerEngine_x64d.dll
COMPLUS_LoaderOptimization=1
Cx_IAST_NET_HOME=D:/home/site/cx-agent/CxHome
Cx_IAST_PROCESS_TO_MONITOR=w3wp
Cx_IAST_NET_AZURE=1

Copy the files "Profiler.dll", "Newtonsoft.Json.Net20.dll" and "websocket-sharp.dll" from D:/home/site/cx-agent/CxHome/other_bin/ to D:/home/site/wwwroot/bin. If the bin folder does not exist, you have to create it.
Save your settings. Your application restarts.

Note

Azure supports .NET Framework v4.7 and v3.5. The .NET Agent is only supported with v4.7.
Due to the application service structure, the project name in the IAST Manager defaults to 'wwwroot'.
The project name can be customized by modifying the ProjectName key to the desired name.
The project name key is located in D:/home/site/cx-agent/CxHome/Profiler.dll.config.
Agent auto-upgrade is currently not supported on Azure app services.
In case of any error, check for messages in D:/home/LogFiles/eventlog.xml in addition to the regular agent logs.
You are not able to download the currently running agent logs via FTP as long as the application is running. You can download them once the application has stopped.

In this section:

Setting up and Configuring the CxIAST C# Agent in the AUT Environment

Pre-Requisites

Note

Installing and Removing .NET Agent

Note

Note

Note

Installing .NET Core

Note

Note

Note

Running the Application under Testing on .NET Core

Note

Note

Note

Note

Installing and Running the Application under Testing on .NET Framework

Note

Search results