Usage

Introduction

Hdiv .NET Agent is an Interactive Application Security Testing (IAST) 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 HdivAgentConfig.exe tool or by activating HdivAgentService after configuration phase

Client Deployment

In order to allow Hdiv .NET Agent to rescue specific lines of code at which code vulnerabilities are raised, it is required that web applications will be deployed with their synchronized .pdb files. By default, Debug builds includes these files, but this is no 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 Properties option
  • Go to Package/Publish Web
  • At Configuration dropdownlist select Release
  • Here uncheck the Exclude generated debug symbols option and save the settings
  • Rebuild the web application project

Release with pdbs

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 Environment Considerations section when using Hdiv .NET Agent at DEV environment for additional deployment recommendations

Starting

Once configuration settings have 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 following requirements should be meet.

  • Run cmd / powershell in administration mode
  • IIS resets should be allowed at 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 one

Status Report

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's suppose we have and ASP.NET MVC app called SampleWeb

Usage

If this is the case we will run:

    HdivAgentConfig /sa:SampleWeb

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

Usage

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

Detach Agent (Unscan) for individual application

In order to detach Hdiv .NET Agent to 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 previous example, ASP.NET MVC website SampleWeb:

Usage

If this is the case we will run:

    HdivAgentConfig /ua:SampleWeb

After running the instruction we will get something similar to:

Usage

Attach Hdiv .NET Agent globally

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

As it was mention at installation guide, it's possible to define website exclusion lists by using ExcludedSites attribute at system.properties file for skipping those sites from attaching process.

    HdivAgentConfig /s:*

Filter activated

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

Detach Hdiv .NET Agent globally

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

    HdivAgentConfig /u

Filter deactivated

After running above command and in addition to global Agent detaching, global filter will be deleted from 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

Service

Order

HdivAgentService should be started only after HdivAgentConfig action has been run

Environment Considerations

Hdiv .NET Agent can be used at 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 elevetated permissions
  • Run HdivAgentConfig.exe tool in discriminated or global filter mode
  • Activate HdivAgentService monitoring service

On the other hand, for those users interested in using .NET Agent at DEV environment, some additional recommendations are provided for integrating Hdiv .NET Agent actions in their DEV ecosystems

.NET Agent at DEV Environment

Some extra consideration regarding to client deployment has to be taken into account for using Hdiv .NET Agent at DEV environment. Hdiv recommends to use Visual Studio Publish option for those web applications that are going to scan with Hdiv .NET Agent. Standard steps will be the folllowing:

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

Publish

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

Publish-Wizard-Step1

Publish-Wizard-Step2

Publish-Wizard-Step3

  • Create Site or Application at IIS with predictable naming convention

Publish-IIS-Step1

Predictable Naming

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

Publish-IIS-Step2

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 at publish folders