Installation

Installation requirements

Before starting the installation, please check that your server meets the supported server versions requirements.

In addition to those requirements, the PHP module called posix needs to be installed in your PHP installation.

Installation

There are three different ways of installing the Hdiv PHP agent:

• Installing from binary package(preferred)
• Installing from a python wheel package
• Manual installation

Before starting with any of those methods, unzip the package provided by Hdiv.

unzip Hdiv.zip

Installing from binary package

This method is very straight forward. The self-contained binary will install everything for you. However, if you are interested in knowing more about what is installed behind the scenes, please refer to the manual installation.

The installer will first attempt to identify your current setup but if it can´t, it will ask you for some information regarding your setup.

In order to run the binary, you have to give execution permissions

chmod +x hdiv_php_installer_vX.X.X-63-g0f90b8e-glibc

And then, just run it

./hdiv_php_installer_vX.X.X-63-g0f90b8e-glibc

Once the installation is finished, it is safe to delete the binary.

Installing from a python wheel package

This method is also very straight forward. This approach requires Python 3.6+ with pip installed. If you are interested in knowing more about what is installed behind the scenes, please refer to the manual installation.

First add the hdiv_php_intaller package to your python with:

pip install -i hdiv_php_installer-vX.X.X_161_g4640f099-py3-none-any.whl

Then run the installer with:

hdiv_php_installer

The installer will first attempt to identify your current setup but if it can´t, it will ask you for some information regarding your setup.

Once the installation is finished, it is safe to uninstall the package:

pip uninstall hdiv_php_installer

Manual installation

This is the slowest option but probably the one that most sysadmins/devops will choose since it gives them more control and knowledge about the changes done to the system. Even if you choose any of the more automatic options, reading this section will help you understand better the installation procedure.

Uncompress the installation files:

From the folder called Hdiv created when unzipping on the first step, type the following:

cd Hdiv/agent/php/
tar -zxvf hdiv-php-agent-vX.X.X-161-g4640f099.tar.gz

This will create a tree with these directories under the hdiv-php-agent-vX.X.X-161-g4640f099 directory:

agent/
binary-core/
extension/
php/

• agent: PHP source code of the agent
• binary-core: contains the binaries (either Java and native) of the agent core.
• extension: Compiled Hdiv extension
• php: has the hdiv.ini config file.

Install the native extension

On this step we will install the Hdiv PHP extension needed for the agent. The procedure is the standard one for any PHP extension.

First, we have to identify where our system is looking for PHP extensions. In order to do so, type the following command:

php -i | grep "extension_dir"

You should see an output similar to

[root@d6603c980a4b extension]# php -i | grep "extension_dir"
extension_dir => /usr/lib64/php/modules => /usr/lib64/php/modules

From that output, in our case, we now know the folder we were looking for is /usr/lib64/php/modules

Once we know the extensior dir, we have to move the file hdiv.so which is in the extension folder to that path. In our case:

cp extension/hdiv.so /usr/lib64/php/modules/

Install the agent PHP files

Copy or move the contents of agent/ directory to any path of your choosing (suggestion for Unix: /opt/hdiv/php_agent). Using the suggested as example, we would move the content with the following command:

cp -r agent/* /opt/hdiv/php_agent/

Please note that the path must be readable and traversable (g+rX permissions) for the system user and/or group that the PHP runtime uses (e.g: chown -R apache:apache /opt/hdiv/php_agent if you are using apache). Depending on the websever you use, the user is usually one of the following: www-data, apache or nginx.

Install the core binary

The binary-core directory contains several sub-directories for different architectures:

• java (multiplatform).
• linux.
• macos.

Choose the one that matches your architecture (the Java version is multiplatform. You can choose the JAVA over any other if you prefer so.)

Choose an installation path (suggestion: /opt/hdiv/bin/[CHOSEN_ARCH]). Move the contents of the architecture chosen ARCH folder to the path chosen. (e.g: mv binary-core/linux/hdiv-ee-portable-core /opt/hdiv/bin/linux/)

Make sure the PHP runtime can have read and execute permissions(g+rx) on the chosen path. (e.g: chown -R apache:apache /opt/hdiv/bin if you are using apache)

Install the PHP config file

On this step we will tell PHP to load Hdiv extension. In order to do so the Hdiv INI file(php/hdiv.ini) must the moved to your PHP's installation directory. If you're unsure about its path, you can find it using one the following approaches:

• Using the command php -i to get a text version of phpinfo() on the cli. You can then pipe its result to grep and search for addional ini files: php -i | grep "Additional .ini files parsed"
• Using php-config --ini-dir command. PHP-config is a tool provided by PHP.
• Serve a PHP page where the following command is used: phpinfo(). Usually it´s displayed under the section: "Scan this dir for additional .ini files:".

Most likely the path will be a conf.d or php.d directory in the same path as the main php.ini file, something like /etc/php/version/conf.d or /usr/local/etc/php/version/conf.d.

Once you have this folder located, move the file php/hdiv.ini there.

Now, when running PHP, it should have the Hdiv extension loaded. In order to verify so, run the following command which shows a list of all PHP extension installed:

php -m

You should see hdiv among all the modules installed under [PHP Modules]. You could run the following command to find it faster php -m | grep hdiv.

If the Hdiv extension is not there, that usually means the folder found on this step was not the correct one. Double check it and make sure the file hdiv.ini is properly moved there.

Configure extension

Edit the file moved to PHP ini folder on the previous step called hdiv.ini.

Change AGENT_PATH_CHANGEME with the path which you chose on step Install the agent PHP files. Then append to that path /src. (E.g: We chose /opt/hdiv/php_agent so we should replace AGENT_PATH_CHANGEME with /opt/hdiv/php_agent/src)

Edit the core-settings.ini config file

Now we have everything on a path on the server, we have to tell the agent about those chosen paths. Go to the folder chosen under step Install the agent PHP files(suggested: /opt/hdiv/php_agent). Now edit the file settings/core-settings.ini path and change the following values:

• php.run.dir: set this to any existing directory that can be read, written and traversed (g+rwX). It will be used by the agent and core to store runtime files. It can be a relative path. (suggested: config). Make sure the path chosen exists and it has the right permissions.
• hdiv.config.dir: same as above. It'll be used for the core. It can be the same as php.run.dir. (suggested: config/portable-core). Make sure the path chosen exists and it has the right permissions.
• hdiv.mandatory.app.name: The name of your app.

In addition to those changes, we have to tell the agent where the binary core is. We chose this path on the step Install the core binary. On the example we suggested to move the file hdiv-ee-portable-core to /opt/hdiv/bin/linux/. Once you have this located, point the following config entry to that path:

php.core.[ARCH].bin = PATH_TO_PORTABLE_CORE

In the example case, since we are using linux, we would modify the linux entry leaving it like:

php.core.linux.bin = /opt/hdiv/bin/linux/hdiv-ee-portable-core

Install HDIV license

Find the license.hdiv file included in the Hdiv zip you got provide with(Hdiv/license/license.hdiv). Copy license.hdiv to the directory you configured as hdiv.config.dir (suggested: /opt/hdiv/php_agent/config/portable-core). Alternatively, you can copy it to the core installation directory that you chose on under Install the core binary step (suggested: /opt/hdiv/bin).

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.

Checking installation

At this stage, Hdiv agent is installed. The only remaining thing is next step which consists on restarting your webserver.

Before doing so, we can verify the installation is ok. In order to do so, go to the folder where the php agent was installed(suggested /opt/hdiv/php_agent) and run the following script:

php tools/setup-check.php --console

If everything is properly configured, the output should be similar to the following:

Hdiv extension file loaded: yes
Extension is loaded: yes
Php is prepending agent: yes
Php is appending agent: yes
Binary is properly configured on settings/core-settings.ini: yes
License is configured on settings/core-settings.ini: yes
Check binary-core runs: yes
Console is configured on settings/core-settings.ini: yes

If there is something wrong with the installation, the output will point you out where the problem is and it will help you amending it.

For example, the following output shows the file settings/core-settings.ini is missing the key php.core.linux.bin:

Hdiv extension file loaded: yes
Extension is loaded: yes
Php is prepending agent: yes
Php is appending agent: yes
Binary is properly configured on settings/core-settings.ini: no
    Point the key php.core.linux.bin to the path where you put the binary-core file

Restart

Restart your webserver. You may need to restart your PHP runtime, such as php-fpm. The Hdiv agent should start working now.

Note that on the first request after each restart the core will be initialized. This first request may be a fraction of a second slower than others.