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 detected, 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 not occur 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 in 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 the Readme.txt file
Attach Hdiv .NET Agent to an 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
In this case we will run:
HdivAgentConfig /sa:SampleWeb
After running the instruction for the SampleWeb site, the console application will show something similar to:
In this way, the SampleWeb application and related assemblies are now attached to Hdiv .NET Agent monitor actions. All new requests to the SampleWeb application will be analyzed by Agent inspectors
Detach Agent (Unscan) for an 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:
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 the installation guide, it is possible to define website exclusion lists by using the ExcludedSites attribute in the system.properties file to omit those sites from the attachment 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 monitored, we provide a Watcher Service, which 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. For 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 in 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 the 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 the 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 predictable naming with some suffix (such as [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 the 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