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 Hdiv Toolbar
  • EE Agent/Connected: The agent sends the vulnerabilities to the web console.

Installation

In order to install .NET Agent use the msi file HdivAgentSetup.msi 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 permisions and continue through the wizzard to complete the instalation.

Remark

Hdiv makes use of CLR Profiling. Only one profiler can be attached so profiler chaining feature is provided to have more than one profiler at the same time and support performance or APM tools.

Usage

Usage

Usage

Usage

Usage

After Installation

After Hdiv .NET Agent installation following updates will be made at server machine

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

Configuration

For more info about Agent usage consult use Hdiv .Net Agent

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

You may need to define some config parameters:

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.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.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.net.ast.apppools.excluded List Semicolon separated list or AppPool names to exclude from scanning (supports wildcards)
    hdiv.net.ast.assemblies.excluded List Semicolon separated list or assembly file names to exclude from scanning (supports wildcards)
    hdiv.always.excluded.classes List Semicolon separated list or type names to exclude from scanning (supports wildcards)

    Here we can see a sample configuration :

    {
      "hdiv.config.dir": "C:\\hdiv\\",
      "hdiv.console.url": "http://localhost:8089/hdiv-console-services",
      "hdiv.console.token": "[console-token]",
      "hdiv.server.name": "[server-name]",
      "hdiv.net.ast.apppools.excluded": "MusicStore*",
      "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-folder}/license/
    

    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 license folder

    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 the vulnerability detection feature of Hdiv Enterprise. 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 old version of the agent using legacy approach (not CLR Profiling agent) you can find setup instructions here