Installation

Installation requirements

The first step is to check the Server versions supported and the installation requirements.

Working modes

Hdiv Node.js 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. Hdiv toolbar can be activated if requested.

Default working mode

If console connection configuration is provided (hdiv.console.xxx) the agent will run in EE Mode

Installation

First of all, unzip the Hdiv.zip file provided by the Hdiv support team. It contains two folders: license and agent. The license folder's path is the one that you will need to put in a param called hdiv.config.dir later. The agent folder has a nodejs folder which contains a tar.gz file. This also needs to be decompressed. In order to use the Hdiv's Node.js Agent, use the file hdiv-nodejs-agent.js to run your application.

The application will also need some config parameters defined as environment variables to run properly. Read more about config parameters.

Run your application as follows:

$ env "hdiv.config.dir={path-to-hdiv-folder}/license/" \
      "hdiv.console.url=http://${console-host}:8089/hdiv-console-services" \
      "hdiv.server.name={server-name}" \
      "hdiv.console.token={console-token}" \
node {path-to-hdiv-folder}/nodejs/hdiv-nodejs-agent.js your-app.js

Process managers

A Node.js process manager is a useful tool to ensure that a Node.js process or script runs continuously (forever) and can enable it to auto-start at system boot. Here you can see how to run the hdiv agent with some of these different process managers:

Forever

If you are using Forever, you can run the agent in two ways:

a) Use a relative path to locate the agent. Example:

$ forever start ../hdiv-nodejs-agent.js index.js

b) Use an absolute path to locate the agent but also use the --workingDir param to set the working directory for your application. This is necessary to avoid losing the current working directory. Example:

$ forever start --workingDir /absolute/app /absolute/agent/hdiv-nodejs-agent.js index.js

PM2

If you are using PM2 you need to add --node-args with agent path require (-r) and define environment variables. Example:

$ env "hdiv.config.dir={path-to-hdiv-folder}/license/" \
      "hdiv.console.url=http://${console-host}:8089/hdiv-console-services" \
      "hdiv.server.name={server-name}" \
      "hdiv.console.token={console-token}" \
pm2 start --node-args="-r {path-to-hdiv-folder}/nodejs/hdiv-nodejs-agent.js" your-app.js

If you are using a configuration javascript file to start the application, you can define required parameters there. Example:

module.exports = {
    apps: [
        {
            script: 'your-app.js',
            ...
            'node_args': '-r {path-to-hdiv-folder}/nodejs/hdiv-nodejs-agent.js',
            env: {
                ...,
                'hdiv.config.dir': '{path-to-hdiv-folder}/license/',
                'hdiv.console.url': 'http://${console-host}:8089/hdiv-console-services',
                'hdiv.server.name': '{server-name}',
                'hdiv.console.token': '{console-token}',
            }
        }
    ]
}

SystemD

When using a SystemD service, the environment variables cannot contain dots. In this case, it is necessary to change the variable names to upper case and replace the dots with underscores. Example:

[Service]
Environment=HDIV_CONFIG_DIR={path-to-hdiv-folder}/license/
Environment=HDIV_CONSOLE_URL=http://${console-host}:8089/hdiv-console-services
Environment=HDIV_SERVER_NAME={server-name}
Environment=HDIV_CONSOLE_TOKEN={console-token}

ExecStart=node {path-to-hdiv-folder}/nodejs/hdiv-nodejs-agent.js your-app.js

Remember to perform systemctl daemon-reload after changing the service file to reload its content. And now you should be able to start, stop, restart and check the service status.

Nodemon

Nodemon is commonly used in development. You can run your app with the Hdiv agent by just changing the node binary to nodemon. It does not matter if you use absolute or relative paths. Example:

$ nodemon ../path/to/hdiv-nodejs-agent.js index.js

Configuration

Configuration options for Node.js Agent. They are modifiable using Hdiv Toolbar configuration page or more generally using environment variables.

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.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.always.excluded.files	List	Colon separated list of filenames to exclude from scanning

The app's name and version are taken from the app's package.json file but the name could be overwritten if desired with hdiv.root.app.name

License

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

hdiv.config.dir={path-to-hdiv-folder}/license/

When running Node.js 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: YYYY-MM-DD hh:mm:ss

#############################################################

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 Node.js Agent is attached to your application, you can try the Hdiv Enterprise vulnerability detection feature. You just need to browse the application and all detected vulnerabilities will be submitted to the Console Application and/or shown in the Developer toolbar.

Logging

Our agent writes two log files which could be useful for debugging purposes. If you want to debug the agent while using it with your application, add the environment variable hdiv.file.level=FINE. Do not use this setting in production because it could cause overheads.

The log files are hdivAgentLog.hlg and hdivNativeAgentLog.hlg. They are located under the hdiv.config.dir directory and the server's name (sometimes defined with hdiv.server.name).