Installation

Installation requirements

The first step is to check the supported server versions, technologies and installation requirements.

Working modes

Hdiv .NET agent supports two working modes:

  • Dev Agent/Standalone: The agent works offline presenting all the vulnerabilities using the Hdiv Toolbar
  • EE Agent/Connected: The agent sends the vulnerabilities to the web console.

Windows Installation

Using msi file

We can install the .NET Agent by using a msi or a zip file.

In order to install .NET Agent with the msi HdivAgentSetup.msi just execute the file provided by the Hdiv support team. This setup will install the required files in the server system for the Hdiv .NET Agent to work. Execute the file with elevated permissions and continue through the wizard to complete the installation.

Video

There is a video with the installation process using the msi here

Remark

Hdiv makes use of CLR Profiling. Only one profiler can be attached, so the Profiler Chaining feature is provided to allow more than one profiler at the same time and support most APM tools.

In most scenarios, the typical installation will be enough to install the Hdiv agent, however, there might be complex scenarios where a custom installation may be required. Some examples are those servers that are short of resources, or those where many AppPools are running simultaneously.

Typical Installation

Unzip the package provided by Hdiv and execute the installer. The wizard will guide you through the installation process.

Usage

Usage

Usage

Usage

Usage

After Installation

After Hdiv .NET Agent installation, following updates will be made on the server machine

  • All Hdiv files will be placed in C:\Hdiv\Agent by default
  • This folder will also contain the default agent configuration file env.properties
  • Some assemblies will be added into GAC

Do not miss out

One last step is needed for the agent to connect with the console and get the license connected Configuration

Custom Installation

Custom installation allows you to install and configure all the necessary software without restarting the IIS. Also, enable you to select beforehand the AppPools monitored by the Hdiv profiler. For that, make sure "Enable Agent" is unchecked.

Usage

Usage

Once the wizard is finished, we will run the diagnostic tool to get a complete overview of the current configuration.

cd c:\hdiv\agent
HdivAgentConfig /d

In IIS Apps section, apps and AppPools are listed down.

Usage

Once you have a clear view on what are the AppPools that must be monitored, it is necessary to edit c:\hdiv\agent\env.properties file. Exclude all AppPools by default and specify those that must be monitored by adding the following lines

hdiv.net.ast.apppools.excluded=*
hdiv.net.ast.apppools.included=TestbedWeb.Core.2.2.Rest AppPool;SampleWebCore AppPool 2

Finally, it is time to enable the agent by executing the following commands. This will reset the IIS

cd c:\hdiv\agent
HdivAgentConfig /ip

Recomendation

If there are applications running in 32bits app pools it is recommended to launch the Agent Service with this command (Start Service)

HdivAgentConfig /ss

Do not miss out

One last step is needed for the agent to connect with the console and get the license connected Configuration

Using zip file

In order to install .NET Agent with the zip file HdivAgentSetup.zip provided by the Hdiv support team, just extract its contents in the server hard drive. The recommended path to do this is c:\hdiv\agent

Next step should be copying provided license file license.hdiv to c:\hdiv and editing c:\hdiv\agent\env.properties file to match desired configuration.

Important

Although agent extraction path is free we strongly recommend it to be c:\hdiv\agent, and if not possible, to be in c: drive, because of permissions issues seen when extraction has taken place in other drives.

IIS Support

Default installation with the msi enables support for IIS hosted applications by default. Nothing else is needed in order to enable it.

If the installation was made with the zip file, and assuming extration path was c:\hdiv\agent, execute this lines in a command prompt with elevated permissions

cd c:\hdiv\agent
HdivAgentConfig /ip

IIS Express and Kestrel exe Support

In order to enable support for IIS Express and Kestrel exe web apps we need to setup Profiler variables either user level (recommended) or globally.

Per user

To set the agent Profiler variables for current user only execute the following in a command prompt (no elevated permissions needed):

cd %HDIV_AGENT_HOME%
HdivAgentConfig /ipu
To revoke this execute:
HdivAgentConfig /upu
If we want to enable the agent in another user we will need to e the following in a command prompt with elevated permissions:
cd %HDIV_AGENT_HOME%
HdivAgentConfig /ipu:userName
To disable it execute:
HdivAgentConfig /upu:userName

Globally

We can also enable the agent globally by setting the Profiler variables in global environment. This will enable the Agent for Iis Express and independent Kestrel apps for everyone, but we recommend the "per user" alternative

Remark

Due to the fact that this mode changes global environment variables a machine restart is recommended in case Hdiv Agent does not get enabled on the desired web app

To set Profiler globally execute the following in a command prompt with elevated permissions:

cd %HDIV_AGENT_HOME%
HdivAgentConfig /ipg
To revoke this execute:
HdivAgentConfig /upg

Important

Setting Profiler variables globally will make the Agent launch for al processes in the machine. In order to disable certain platforms we can set the following in In env.properties:

hdiv.net.ast.platforms.iis=false
hdiv.net.ast.platforms.iisexpress=false
hdiv.net.ast.platforms.kestrel=false
hdiv.net.ast.platforms.exe=false

For Kestrel exe apps only, we need to add the exe name of the app to the env.properties file in the variable called hdiv.net.ast.apps.included (wildcards are accepted)

hdiv.net.ast.apps.included=MyKestrelApp-1.exe;MyKestrelApp-2.exe

Hint

For Kestrel exe it can be useful to set the Profiler variables on the current command prompt session only executing this:

set HDIV_AGENT_HOME=C:\Hdiv\Agent
set CORECLR_ENABLE_PROFILING=0x1
set CORECLR_PROFILER={1adbf8d7-8774-4733-aa10-4376ba3bd37a}
set CORECLR_PROFILER_PATH_64=C:\Hdiv\Agent\x64\Hdiv.AST.Clr.Profiler.dll

Uninstall

To completely uninstall the Agent execute this in a command promp with elevated permissions:

cd %HDIV_AGENT_HOME%
HdivAgentConfig /u

Linux Installation

In Linux environments we provide a zip file containing the .NET Agent. It is required to uncompress the zip file in the chosen directory, for instance /opt/hdiv/agent. The applications must have read and execution permissions on this folder.

Next, for the NetCore runtime to load the .NET Agent and instrument the application, some environment variables have to be defined. For libc distros set this variables:

export HDIV_AGENT_HOME=/opt/hdiv/agent/ \
export CORECLR_ENABLE_PROFILING=1 \
export CORECLR_PROFILER={1adbf8d7-8774-4733-aa10-4376ba3bd37a} \
export CORECLR_PROFILER_PATH_64=/opt/hdiv/agent/x64/Hdiv.AST.Clr.Profiler.so

For musl distros, like Alpine use the following:

export HDIV_AGENT_HOME=/opt/hdiv/agent/ \
export CORECLR_ENABLE_PROFILING=1 \
export CORECLR_PROFILER={1adbf8d7-8774-4733-aa10-4376ba3bd37a} \
export CORECLR_PROFILER_PATH_64=/opt/hdiv/agent/x64/Hdiv.AST.Clr.Profiler_musl.so

Whenever the application is loaded the .NET Agent will start automatically.

After Installation

It is possible to stop the .NET Agent by setting CORECLR_ENABLE_PROFILING environment variable to 0 and restarting your application.

For Kestrel exe apps

Linux limits the process exe file name to 16 chars. Take this into account when setting the hdiv.net.ast.apps.included property

Configuration

For more info about Agent usage, check Usage section

Before using the Hdiv .NET Agent, some tweaking should be performed in the env.properties file.

The first property to check is hdiv.config.dir. It points to the path where the license is present and it is where the .NET Agent will write the logs. So the application must have write permissions on the hdiv.config.dir folder.

hdiv.config.dir

Default value for this property, if not set, is the parent folder of the path stated in HDIV_AGENT_HOME environment variable.

Other properties to be taken into account are those used to configure the Hdiv Console: hdiv.console.url, hdiv.console.token and hdiv.server.name.

The following is a list of possible configuration properties:

Key Type Description
hdiv.console.level Custom Define the logging level the following options are available
  • OFF
  • SEVERE (default)
  • WARNING
  • INFO
  • FINE
  • FINER
  • hdiv.file.level Custom Define the logging level the following options are available
  • OFF
  • SEVERE
  • WARNING
  • INFO (default)
  • FINE
  • FINER
  • hdiv.log.file.location String Agent log file complete path. For example, /opt/hdiv/logs/agent.log
    hdiv.log.append Boolean Define whether agent traces should be appended during startup or not, by default false
    hdiv.log.file.size Number Log file maximum size in bytes, by default 100000000 (100MB)
    hdiv.config.dir String Path to the config dir where the license is present
    hdiv.console.url String Defines de URL of the Web Console, by default http://localhost:8089/hdiv-console-services
    hdiv.console.token String Authentication token for the environment in the Web Console
    hdiv.server.name String The name that will identify this server in the Web Console
    hdiv.console.timeout String Console communication timeout (ms) , by default 2000
    hdiv.console.validate.certificate Boolean Whether the Web Console certificate should be verified when using https or not, by default true
    hdiv.toolbar.enabled Boolean Whether Hdiv toolbar should be shown or not, when the agent is not configured to communicate with a Web Console it will be always displayed, otherwise by default is false
    hdiv.toolbar.enabled.on.demand Boolean With this parameter Hdiv toolbar could be manually activated in runtime but it is not displayed otherwise, by default false
    hdiv.toolbar.disabled.patterns List A comma separated list, including regular expressions to avoid the toolbar in URLs matching those
    hdiv.trace.queries Boolean Flag to indicate that SQL Queries will be displayed in Hdiv Toolbar, by default true
    hdiv.validation.info Boolean Flag to allow validation info to be displayed on the toolbar when using Hdiv Library Protection, by default true
    hdiv.toolbar.delete.location.change Boolean In some SPA vulnerabilities will not be emptied in the toolbar, they can be manually cleaned with the button in the toolbar or otherwise use this option (but it may have issues depending on the browser used), by default false
    hdiv.toolbar.xhr.header Boolean By default Hdiv toolbar includes (if not present) X-Requested-With header in AJAX calls to identify them, by default true
    hdiv.toolbar.only.in.html.responses Boolean If true, Hdiv toolbar will be included only in responses that have HTML Content-Type and whose content looks like actual HTML. If false, the toolbar will be included in any page with HTML Content-Type or without any Content-Type header and HTML-like content. Defaults to true.
    hdiv.throughput.rate Integer Defines the percent of the requests for which the detection will be activated, by default 100
    hdiv.artifact.detection.additional.disabled Boolean Flag to indicate if additional artifacts (OS, DB & JVM) should be disabled or not, by default false
    hdiv.default.task.time.period Number Time period for all agent communication tasks (in seconds)
    hdiv.metrics.task.time.period Number Time period for metrics task (in seconds), by default 60
    hdiv.security.threats.task.time.period Number Time period for security threads task (in seconds), by default 5
    hdiv.update.config.task.time.period Number Time period for Hdiv library configuration update (in seconds), by default 5
    hdiv.vulnerability.config.task.time.period Number Time period for Hdiv agent configuration update (in seconds), by default 60
    hdiv.rule.info.task.time.period Number Time period for rule configuration update (in seconds), by default 60
    hdiv.excluded.stacks List A comma separated list, including packages that should be avoided in vulnerability stacks
    hdiv.root.app.name String Mandatory name for application deployed on root context path
    hdiv.mandatory.app.name String Mandatory name for any application deployed on this server. If more that one application is deployed, it is possible to define a mapping like the following app_1:First;app_2:Second
    hdiv.js.cache.maxage Number Time in minutes that javascript files are cached on the client with the Cache-Control header. Default value is 30
    hdiv.main.ip.strategy String Strategy to get the main request IP. FORWARDED_IF_PRESENT (default) uses the X-Forwarded-For header if present, while REMOTE uses the remote client IP.
    hdiv.net.ast.apppools.excluded List Semicolon separated list of AppPool names to exclude from scanning (supports wildcards)
    hdiv.net.ast.assemblies.excluded List Semicolon separated list of assembly file names to exclude from scanning (supports wildcards)
    hdiv.always.excluded.classes List Semicolon separated list of type names to exclude from scanning (supports wildcards)
    hdiv.net.ast.apps.included List Semicolon separated list of exe Kestrel app names to include in scanning (supports wildcards)

    Here we can see a sample configuration:

    # Hdiv Agent config file. 
    # Comment properties by adding # to the beginning of the line
    
    hdiv.config.dir=C:\\hdiv
    hdiv.console.url=http://localhost:8089/hdiv-console-services
    hdiv.console.token=e781990ff291c0D693c45fd3
    hdiv.server.name=server
    #hdiv.toolbar.enabled=true
    

    License

    Hdiv provides a license file whose name is license.hdiv. The folder containing this file should be included in the application server as system property:

    hdiv.config.dir={path-to-hdiv-configuration-files-folder}
    

    As we commented earlier, this param defaults to C:\Hdiv directory. When running .NET Agent, you will see this banner in the server console if you have successfully referenced hdiv.config.dir to the folder where your license.hdiv is installed:

    #############################################################
    Hdiv Enterprise X.X.X
    (c) Copyright hdivsecurity.com
    
    This product is licensed to Your Company
    
    Valid until: 2019-01-15 07:28:44
    Offline mode valid until: 2017-01-15 07:28:44
    #############################################################
    

    Hdiv requires write permissions in configuration folder

    Alternative

    Alternatively the env variable HDIV_LICENSE_DATA can be set with the propper value provided by Hdiv

    Connect to the Hdiv Console

    Applications and servers using Hdiv can communicate with the Hdiv Console to send detected vulnerabilities and attacks to it and retrieve configuration options.

    It is necessary to add some properties to enable communication between the applications and the console.

    Add the following system properties (or environment variables) to the server in the same place the Hdiv Agent is configured.

    hdiv.console.url=http://${console-host}:8089/hdiv-console-services
    hdiv.server.name={server-name}
    hdiv.console.token={console-token}
    
    • hdiv.console.url: The location of the Hdiv Console REST API. Replace ${console-host} variable with the hostname or IP address where the Hdiv Console is installed
    • hdiv.server.name: Unique name that identifies the server where the agent is installed.

      Only alphanumeric, '-' and '_' characters are allowed in the server name property

    • hdiv.console.token: Authentication token used to invoke the REST API in the console. The actual value of the token for your console installation is in the System Settings / Environments section of the Hdiv console. Access the console and copy the value of the token to this property.

    No Data Loss. Connectivity Fault Recovery

    Hdiv agent is designed to allow connectivity errors without losing any data when console connection is not available. Hdiv stores pending information in the fileystem (with a maximun size limit) and it sends that information when the console is available again.

    Usage

    Once the .NET Agent is attached to every application, you can try out the Hdiv Enterprise vulnerability detection feature. You only need to browse the application and all detected vulnerabilities will be submitted to the Console Application and/or shown in the Developer toolbar.

    Remark

    If you are using an older version of the agent using a legacy approach (not CLR Profiling agent) you can find setup instructions here for up to V2.1 or here for older versions

    Windows Uninstallation

    Open the Windows control panel. Click on Programs/Uninstall a program.

    Usage

    In the program list, choose "Hdiv Security Agent" and click on uninstall.

    Usage

    A dialog will ask wether the agent should be uninstalled. Click on Yes.

    Usage

    The uninstallation process will have finished. Some files will remain in the Hdiv Agent folder.

    Usage

    The file env.properties.backup contains the environment variables used by the agent. This file is kept for backup purposes. If the agent is installed again, this file can be used to retrieve the previous agent configuration. Also, two log files will contain information regarding the installation/uninstallation processes.

    Linux Uninstallation

    Prevent the .NET Agent from instrumenting applications by setting CORECLR_ENABLE_PROFILING environment variable to 0.

    Close the already running and instrumented applications.

    At this time, you can delete the Hdiv Agent files if you do not plan to use it in the future. You can go to the installation directory and delete the files. You might consider keeping a backup of the env.properties file if you plan to install newest releases of the Hdiv Agent in the future.