Usage

Introduction

Hdiv .NET Agent is an Interactive Application Security Testing (IAST) tool which monitors activities from .NET Web applications deployed under IIS Server. In order to do so, Hdiv .NET agent must be attached to .NET sites. This can be done by using the HdivAgentConfig.exe tool or by activating HdivAgentService after the configuration phase.

Client Deployment

In order to allow Hdiv .NET Agent to rescue specific lines of code in which vulnerabilities are raised, web applications must be deployed with their synchronized .pdb files. By default, Debug builds include these files, but this is not the case for Release ones. However, it is possible to include .pdb files for Release compilations by defining a specific Project property feature. Follow these steps in order to include .pdb files for a Release build

• Under Visual Studio IDE, select the applications project and click on the Properties option
• Go to Package/Publish Web
• In the Configuration dropdownlist select Release
• Uncheck the Exclude generated debug symbols option and save the settings
• Rebuild the web application project

All .pdb files should match their corresponding assemblies

Security Considerations

From a security point of view the inclusion of pdb files does't incur in the security risks related to deployments under Debug compilations

Environment Considerations

Take a look at the Environment Considerations section when using Hdiv .NET Agent at DEV environment for additional deployment recommendations

Starting

Once configuration settings has been defined, users can run the HdivAgentConfig.exe in a command line or powershell window with elevated permissions. By using this tool users can attach / detach Hdiv .NET Agent to each website individually or in a global-filter fashion. At this point, the following requirements should be met:

• Run cmd / powershell in administration mode
• IIS resets should be allowed on the server machine

Navigate to root of HdivAgentConfig.exe application %Program Files%\Hdiv Security\Agent, and open a command window. Issuing the command

    HdivAgentConfig /d

will show a diagnostics report like this:

HdivAgentConfig.exe options

From here you can inspect all Hdiv agent tool options by typing HdivAgentConfig.exe /? or inspecting Readme.txt file

Attach Hdiv .NET Agent to individual website

In order to attach (Scan) Hdiv .NET Agent to an Application run the following syntax:

    HdivAgentConfig /sa:[appName]

Filter activated

[appName] accepts wildcard filters to allow the scanning of multiple applications at once

For instance, let us suppose we have an ASP.NET MVC app called SampleWeb

If this is the case we will run:

    HdivAgentConfig /sa:SampleWeb

After running the instruction for SampleWeb site, the console application will show something similar to:

This way, SampleWeb the application and related assemblies are now attached to Hdiv .NET Agent monitor actions. All new requests to SampleWeb application will be analyzed by Agent inspectors

Detach Agent (Unscan) for individual application

In order to detach Hdiv .NET Agent from an application, run the following syntax:

    HdivAgentConfig /ua:[appName]

Filter deactivated

[appName] accepts wildcard filters to allow the unscanning of multiple applications at once

If we continue with the previous example, ASP.NET MVC website SampleWeb:

If this is the case, we will run:

    HdivAgentConfig /ua:SampleWeb

After running the instruction we will get something similar to:

Attach Hdiv .NET Agent globally

Users can also make use of Hdiv .NET Agent in global filter mode. This means that the attaching process will be performed over all .NET Websites (MVC, WebForms, WebAPI, WS) configured in IIS or those which match filter criteria.

As mentioned in installation guide, it is possible to define website exclusion lists by using the ExcludedSites attribute in system.properties file for skipping those sites from the attaching process.

    HdivAgentConfig /s:*

Filter activated

After running the above command, a new global IIS filter will be configured for all web applications

Detach Hdiv .NET Agent globally

At the same time, users can run the global detaching process for restoring all sites to normal behaviour. This can be done by running:

    HdivAgentConfig /u

Filter deactivated

After running the command above and in addition to global Agent detaching, the global filter will be deleted from the server machine

App Monitoring Service

In order to ensure new deployed versions of the applications are properly watched we provide a Watcher Service that is stopped by default, but can be started by using the command

    HdivAgentConfig /ss

The Watcher Service can be stopped with the command

    HdivAgentConfig /sts

Order

HdivAgentService should be started only after HdivAgentConfig action has been run

Environment Considerations

Hdiv .NET Agent can be used in DEV, UAT/PRE and PRO environments depending on client strategy. The recommended actions for UAT/PRE and PRO follow the guidelines described above, in summary :

• Standard client deployment with pdbs files
• .NET Agent configuration (define server name, console settings, and specific params if needed)
• Open console with elevated permissions
• Run HdivAgentConfig.exe tool in discriminated or global filter mode
• Activate HdivAgentService monitoring service

Alternatively, for those users interested in using .NET Agent in DEV environment, some additional recommendations are provided for integrating Hdiv .NET Agent actions in their DEV ecosystems

.NET Agent at DEV Environment

Some extra considerations regarding client deployment have to be taken into account for using Hdiv .NET Agent in DEV environment. Hdiv recommends using Visual Studio Publish option for those web applications that are going to scan with Hdiv .NET Agent. Standard steps are as follows:

• Make sure you have IIS installed in DEV machine
• Create a common folder for all web applications to be published for .NET Agent. It can be created in C:\Inetpub for instance

• Use Visual Studio Publish option for client deployment with pdbs files (Debug mode or Release with pdb files)

• Create Site or Application in IIS with predictable naming convention

Predictable Naming

Using a predictable naming with some sufix (like [Hdiv + AppName] in sample below) makes wildcard filter definitions easier for HdivAgentConfig actions. For the given example, we can run HdivAgentConfig /s:Hdiv* for scanning all web applications from the publish folder

Port consideration

Make sure you assign a valid local port for running your site or application

• Run HdivAgentConfig.exe tool in discriminated or general filter mode.

    HdivAgentConfig /sa:[appName]

    HdivAgentConfig /s:Hdiv*

• As a final step you can choose to activate HdivAgentService for monitoring updates in publish folders