Deploying a .NET IAST agent

This topic explains how to create a .NET IAST agent type on your web server.

Before you begin

If the server running IAST is behind a proxy, the IAST .NET agent supports two ways to configure an outbound HTTP proxy:

  1. System proxy settings, which are automatically detected from standard OS settings or the HTTP_PROXY, HTTPS_PROXY environment variables.
  2. IAST-specific proxy settings, defined with the application’s own environment variables. Configure them as follows:
    IAST_PROXY_HOST={proxy_ip}
                        IAST_Deploy_dot_net.html

If the application-specific variables are set, they take precedence. Otherwise, the system proxy is used. If neither is defined, the application connects directly. Proxy settings are read at startup, so changes require a restart. Check the IAST log to verify that the proxy is configured correctly.

About this task

Use the NuGet Package Manager to add the IAST agent to your application. The example below applies to Visual Studio, but the procedure is similar for other IDEs and build environments.
Important:
Install the IAST NuGet package in the application project before publishing or deploying the application. Do not install the package separately on the target production server.

Procedure

  1. Download the ASoC .NET IAST NuGet package:
    1. Follow the instructions at IAST scan documentation to download the agent.
  2. Configure a NuGet package source:
    1. Open Visual Studio.
    2. Go to Menu > Tools > Options > NuGet Package Manager > Package Source.
    3. Click + to add a new package source.
    4. Enter a name for the source.
    5. Select the folder that contains the downloaded NuGet package.
    6. Click OK.
  3. Identify web server projects:

    Install the IAST agent only in projects that host web applications, such as:

    • ASP.NET Framework applications
    • ASP.NET MVC applications
    • ASP.NET Core applications

    These projects typically contain files or folders such as Startup.cs, Program.cs, Controllers, or wwwroot.

  4. Install the IAST agent NuGet package:
    1. In Solution Explorer, right-click the web application project.
    2. Select Manage NuGet Packages.
    3. From the Package source drop-down list, select the package source that you created in Step 2.
    4. Search for com.HCL.AppScan.IAST.Agent.
    5. Select the package and click Install.
    6. Repeat this step for each web application project that should be monitored.
    Important:
    Several AppScan-related packages may be available. Make sure that you install com.HCL.AppScan.IAST.Agent from the package source configured earlier. Do not install HCL.AppScan.IAST.NetCore.Azure.SiteExtension, because it is intended for Azure App Service deployments and is not required for standard .NET Framework or .NET Core IAST deployments.
  5. Configure the application environment variable (for .NET Core only): For .NET Core applications, configure the following environment variable: 
    "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES": "SecagentCore"
  6. Verify the installation: Verify that the installation was successful.
    1. For .NET Framework, open the web.config file and make sure the following lines were added by the NuGet installation. If these lines were not added, the installation was unsuccessful. 
      Module registration:
                                <system.webServer>
                                <modules>
                                <add name="SecagentModule" type="Secagent.SecagentModule" preCondition="managedHandler" />
                                </modules>
                                </system.webServer>
                                Application settings:    
                                
                                <system.webServer>                      
                                <appSettings>
                                <add key="IASTAgentKey" value="<token to access ASoC IAST session>" />
                                <add key="IASTHost" value="URL to ASoC host, e.g. /https://cloud.appscan.com/IAST/" />
                                <add key="IASTActive" value="true" />
                                </appSettings>
                                </system.webServer>
    2. For .NET Core, make sure that an asoc-config.json file was added to the root folder of your project.

Results

The IAST agent monitors requests and reports security issues as you use or test your application, for example, when you run functional tests, run a Dynamic Scan, or explore the application manually.

Deploying to a separate server

Install the IAST NuGet package on the build or development machine, then deploy the application and all required IAST files to the target server.

About this task

Many .NET applications are developed and built on one machine and then deployed to a different server.

In this scenario, install the IAST NuGet package only in the application project on the build or development machine. Do not install the NuGet package separately on the target server.

Procedure

  1. Complete all steps in the previous procedure to install the IAST NuGet package in the application project on the build or development machine, and then follow the steps below.
  2. Verify that the NuGet installation completed successfully.

    Confirm that the following updates were made:

    • The required IAST entries were added to web.config.
    • The IAST assemblies were added to the application's output.
  3. Publish or deploy the application by using your standard deployment process.
  4. Ensure that all required IAST files are copied to the target server.

    This includes the following files:

    • The IAST agent DLLs and dependencies.
    • The modified web.config file for .NET Framework applications.
    • Asoc-config.json for .NET Core applications.

    The complete list of required agent files for each language version is provided in the NuGet package Dependencies folder.

Results

The application is deployed to the target server with the required IAST files.

What to do next

Important: The IAST agent consists of multiple assemblies. Missing files can prevent the agent from loading or operating correctly. Always verify the deployed files against the required file list after deployment.

Troubleshooting instructions

Note:
Make sure the NuGet name is not changed from the original downloaded name. For example, for version 1.17.2, the NuGet name must be com.HCL.AppScan.IAST.agent.1.17.2.nuget.

If the IAST session in ASoC does not reach the Connected status after the application starts, review the IAST agent log for additional diagnostic information.

On Windows, the log is typically created under the account running the application, for example: C:\Users\<user-name>\AppData\Local\Temp\Secagent

In some server environments, permission restrictions may prevent the agent from creating log files in this location. If no logs are present, configure a custom log directory by using one of the following methods:

  1. Create a folder in a location that is accessible to the application.
  2. Configure a custom log directory using one of the following methods:
    1. Option 1: Environment variable

      Create an environment variable named secagent.log and set its value to the full path of a folder that is accessible to the application.

    2. Option 2: Application configuration
      Specify the log directory in the application's configuration: 
      .NET Framework (web.config):
                                                <appSettings>
                                                <add key="IASTAgentKey" value="..." />
                                                <add key="IASTHost" value="..." />
                                                <add key="IASTLogLocation" value="C:\Logs\Secagent" />
                                                </appSettings>
                                                
                                                .NET Core (appsettings.json or equivalent configuration source):
                                                {
                                                "IASTAgentKey": "...", (optional)
                                                "IASTHost": "...", (optional)
                                                "IASTLogLocation": "C:\\Logs\\Secagent" (optional)
                                                }
  3. Restart the application. The agent log file is created in the specified folder.
    Note:
    Ensure that the application account has read and write permissions for the configured log directory.