Linux Installation
Installation requirements¶
The first step is to check the supported server versions, technologies and installation requirements.
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.
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.
Configuration¶
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 |
hdiv.file.level | Custom | Define the logging level the following options are available |
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) |
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: 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.