Windows Installation

Installation requirements

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

Installation with msi 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.

Msi setup types

The msi has three setup types, typical, complete and custom:

Usage

Typical Installation

  • Agent files will be copied to c:\hdiv\agent
  • Data folder will be c:\hdiv and license (if present) will be copied there
  • IIS Agent will not be activated by default.
  • Hdiv Service will not be activated by default.
  • The config wizzard will open automatically before finishing.

Remark

Typical installation will be de best suited mode for most scenarios, because it lets the user select the apps to survey.

Complete Installation

  • Agent files will be copied to c:\hdiv\agent
  • Data folder will be c:\hdiv and license (if present) will be copied there
  • IIS Agent will be activated for all web apps in the IIS Server
  • Hdiv Service will be activated if Agent detects it is needed.
  • The config wizzard will open automatically before finishing.

Remark

Complete installation is the best mode if the user knows all the apps in the IIS will be surveyed.

Custom Installation

  • User can choose the folder where agent files will be copied to (c:\hdiv\agent by default)
  • Data folder will be c:\hdiv and license (if present) will be copied there
  • Iis Agent will be activated for all web apps in the server
  • The config wizzard will open automatically before finishing.

Remark

Custom installation is for advanced users and not recommended, because it allows to change the default install path.

Important

Hdiv does not warantee the proper operation outside system drive because of security restrictions that the server might have applied.

Msi Uninstallation

  • Open the Windows control panel and go to Programs/Uninstall a program.
  • In the program list, choose "Hdiv Security Agent" and click uninstall.
  • Follow the uninstall wizzard.

Remark

The file env.properties.backup with the environment variables used by the agent will be kept for backup purposes. If the agent is installed again, this file will be used to retrieve the previous agent configuration. All data in ConfigDir (license, logs and app data) will be kept.

Installation with 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 (SystemDrive), because of permissions issues seen when extraction has taken place in other drives.

Zip file Uninstallation

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

cd %HDIV_AGENT_HOME%
HdivAgentConfig /u

User then will have to manually delete all Agent and Config files.

Configuration

Hdiv .Net Agent reads its configuration from the env.properties file present on Agent install folder (set on HDIV_AGENT_HOME environment variable)

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 its logs. So the application must have write permissions on the hdiv.config.dir folder. If not set it points to the parent folder of the Agent installation folder.

Hdiv .Net Agent can be operated by the HdivAgentConfig.exe file present on Agent install folder.

HdivAgentConfig.exe arguments

These are the command line arguments which can be passed to HdivAgentConfig.exe

Command
Requires Admin Privileges
Description
HdivAgetnConfig.exe Yes Opens Agent Config Wizzard
HdivAgetnConfig.exe /u Yes Disables every feature of the agent
HdivAgetnConfig.exe /d No Shows Agent Diagnostics
HdivAgetnConfig.exe /ip Yes Enables Iis Agent
HdivAgetnConfig.exe /up Yes Disables Iis Agent
HdivAgetnConfig.exe /ipu No Enables Iis Express and Kestrel Agent for current user
HdivAgetnConfig.exe /upu No Disables Iis Express and Kestrel Agent for current user
HdivAgetnConfig.exe /ipu:User Yes Enables Iis Express and Kestrel Agent for specified user
HdivAgetnConfig.exe /upu:User Yes Disables Iis Express and Kestrel Agent for specified user
HdivAgetnConfig.exe /upu:* Yes Disables Iis Express and Kestrel Agent for all users
HdivAgetnConfig.exe /ss Yes Starts Agent Service
HdivAgetnConfig.exe /us Yes Stops Agent Service

Configuration Properties

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.included List Semicolon separated list of AppPool or standalone exe names to include in scanning (supports wildcards)
    hdiv.net.ast.apppools.excluded List Semicolon separated list of AppPool or standalone exe 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)

    Config Wizzard

    HdivAgentCofig location

    This wizzard can be opened by launching HdivAgentConfig.exe directly by double clicking on it. The process will ask for elevation in order to show the wizzard. Once opened we should see a dialog with several tabs in a navigation panel on the left.

    Basic Tab

    Basic tab

    This tab will show the main folders configured for the agent and allows us to access them easily :

    • Agent Install Dir : where agent files are (HDIV_AGENT_HOME env variable)
    • env.properties : file inside install folder
    • Condig Dir : where license file must be and where log files will be generated. (hdiv.config.dir property)
    • Log Level : detail of logs generated by the agent
    • Dev Toolbar : controls the presence of the Dev Toolbar in surveiyed apps.
    • License : shows status of current license.

    Remark

    License is a file called license.hdiv in hdiv.config.dir or can be set as a text blob supplied by Hdiv in HDIV_LICENSE_DATA env variable

    Remark

    If license can not be validated a big red cross sign will be shown in BASIC tab.

    Console Tab

    Console tab

    This tab will show the Hdiv console configuration :

    • Server Name : the name this server will be registered as in Hdiv Console. This name should be unique.
    • Console URL : the Url where the Hdiv console is deployed. This url should be finished by /hdiv-console-services
    • Console Token : token of the environment where this server will be registered.
    • Validate console certificate : if unchecked comms with console will ignore invalid certificate errors
    • Http Proxy Options : set if console comms should use a proxy for http connections
    • Https Proxy Options : set if console comms should use a proxy for https connections
    • Commns : shows the result of a communication test attempt with configured Hdiv console

    Remark

    If Server Name is left empty, Agent will assume there is no console configured in the system and a blue Info icon will be shown.

    Remark

    If console comms fails a big red cross will be shown in CONSOLE tab.

    IIS Tab

    IIS tab

    This tab will show the Hdiv Agent for the IIS Server configuration :

    • IIS Profiler : the status of the IIS Agent. Can be enabled or disabled with the big buttons.
      • Enable : enable the Hdiv Agent in the IIS Server
      • Disable : disable the Hdiv Agent in the IIS Server
    • Included Filter : comma separated values of AppPools included by the agent. Empty means all apps are included.
    • Excluded Filter : comma separated values of AppPools excluded by the agent. Empty means no app is excluded.
    • Web Apps : List of web apps configured in IIS Server
      • Restart IIS : restart the IIS Server
      • Include Apps : adds to the included filter the AppPools of the selected apps
      • Exclude Apps : adds to the excluded filter the AppPools of the selected apps
      • Include All Apps : adds all AppPools to the included filter
      • Include Exclusively : adds to the included filter the AppPools of the selected apps and exclude the rest of AppPools
      • Restart Apps : restart selected apps AppPools
      • Browse Apps : opens a web browser to the selected apps

    Remark

    App filters admit wildcards (*)

    Remark

    If Hdiv Agent is enabled it will a big green check will be shown in IIS tab.

    Remark

    If Hdiv Agent is disabled a big red cross will be shown in IIS tab.

    Service Tab

    Service tab

    This tab will show the Hdiv Agent Service configuration :

    • Service Status : the status of the Hdiv Agent Service.
      • Start : starts the Hdiv Agent Service
      • Stop : stops the Hdiv Agent Service
    • Native Agent : working mode of the Native Agent

    Important

    Native Agent can be inproc for 64bits apps. This mode makes the agent faster but requires more memory to work.

    Remark

    Hdiv Agent Service is a piece that is not required for the Hdiv Agent to work, although it is recommended if there is an app wich needs Outproc Native Agent

    Remark

    If there is an App in IIS wich requires outproc Native Agent the Service will be started

    Buttons

    • Reload : reloads env.properties file
    • Save : saves changes made to env.properties file
    • Uninstall : disables all agent features (equivalent to running HdivAgentConfig.exe /u)
    • Exit : closes config wizzard

    Remark

    Uninstall will only disable all Agent features, but will not remove any file from disk.

    App Types

    Hdiv Agent for Windows can monitor these type of web apps:

    Apps deployed on IIS Server

    For these apps to be monitored Hdiv Agent for IIS Server must be enabled, either with the Hdiv Agent Wizzard or by executing

    cd %HDIV_AGENT_HOME%
    HdivAgentConfig /ip
    

    This sets the Hdiv Agent Profiler env variables on the registry entry for the WAS service on HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WAS Environment key.

    Hdiv Agent for IIS Server can be disabled either by the Hdiv Agent Wizzard or by executing

    cd %HDIV_AGENT_HOME%
    HdivAgentConfig /ipu
    

    Apps deployed on IIS Server Express or Kestrel apps launched from Command Line

    For these apps to be monitored Hdiv Agent env variables must be set for the user.

    For Kestrel apps the variables must be set on the command line session.

    In order to set Hdiv Agent variables in user environment execute this :

    cd %HDIV_AGENT_HOME%
    HdivAgentConfig /ipu
    

    Executing a bat file with this content will set the variables for current session

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

    Hdiv Agent env variables can be unset by executing

    cd %HDIV_AGENT_HOME%
    HdivAgentConfig /upu
    

    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: 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.