Configuration

All HAProxy Enforcer configuration are placed in px_haproxy.lua file, which is located in /usr/local/lib/ directory.

Required HUMAN Module Configuration

The following parameters are mandatory:

• px_enabled
• px_appId
• px_cookie_secret
• px_auth_token

-- ## Required Parameters ##
_M.px_enabled = true
_M.px_appId = "<PX_APP_ID>"
_M.auth_token = "<PX_AUTH_TOKEN>"
_M.cookie_secret = "<COOKIE_ENCRYPTION_KEY>"

px_app_id

The application ID. Required to initialize the HAProxy Enforcer.

_M.px_appId = "<PX_APP_ID>"

px_auth_token

The token used for authorization with the HUMAN backend. Required to initialize the HAProxy Enforcer.

_M.auth_token = "<PX_AUTH_TOKEN>"

px_cookie_secret

The secret used to encrypt and decrypt the risk cookie. Required to initialize the HAProxy Enforcer.

_M.cookie_secret = "<COOKIE_ENCRYPTION_KEY>"

px_enabled

This boolean serves as an on/off switch for the entire module, providing a way to enable and disable all Enforcer capabilities quickly and easily.

_M.px_enabled = true

Monitor / Block Mode Configuration

By default, the HUMAN plugin is set to monitor mode.

_M.block_enabled = false

Adding the _ M.block_enabled flag and setting it to true in the px_haproxy.lua file activates the module to enforce blocking. This means the HUMAN Module blocks requests that exceed the block score threshold. If a request receives a risk score that is equal to or greater than the block score, a block page is displayed.

Debug Mode

Enables debug logging mode.

Default: false (disabled)

_M.px_debug = true

When Enabled, HUMAN debug messages should be in the following template:

• For debug messages - [PerimeterX - DEBUG] [APP_ID] - MESSAGE
• For error messages - [PerimeterX - ERROR] [APP_ID] - MESSAGE

Allowlist

Allowing (bypassing enforcement) is configured in the px_haproxy.lua file.

Several filters can be configured:

_M.whitelist_uri_full = { _M.custom_block_url },
_M.whitelist_uri_prefixes = {},
_M.whitelist_uri_suffixes = {'.css', '.bmp', '.tif', '.ttf', '.docx', '.woff2', '.js', '.pict', '.tiff', '.eot', '.xlsx', '.jpg', '.csv', '.eps', '.woff', '.xls', '.jpeg', '.doc', '.ejs', '.otf', '.pptx', '.gif', '.pdf', '.swf', '.svg', '.ps', '.ico', '.pls', '.midi', '.svgz', '.class', '.png', '.ppt', '.mid', '.webp', '.jar'},
_M.whitelist_ip_addresses = {},
_M.whitelist_ua_full = {},
_M.whitelist_ua_sub = {}

Filter Sensitive Headers

A list of sensitive headers configured to prevent specific headers from being sent to HUMAN servers (headers in lowercase). Filtering cookie headers for privacy is set by default.

Default: cookie, cookies

Example:

_M.sensitive_headers = {'cookie', 'cookies', 'secret-header'}

Enabled Routes

Allows you to define a set of routes on which the plugin will be active. An empty list sets all routes in the application as active.

Default: Empty list (all routes are active)

Example:

_M.enabled_routes = {'/blockhere'}

Sensitive Routes

A list of route prefixes and suffixes. The HUMAN module always matches the request URI with the prefixes list and suffixes list. When there is a match, the HUMAN  module creates a server-to-server call, even when the cookie is valid and the risk score is low.

Default: Empty list

Example:

_M.sensitive_routes_prefix = {'/login', '/user/profile'}
_M.sensitive_routes_suffix = {'/download'}

Customize Default Block Page

The HUMAN  default block page can be modified by injecting custom CSS, JavaScript and a custom logo to the block page.

Default: nil

Example:

_M.custom_logo = "http://www.example.com/logo.png"
_M.css_ref = "http://www.example.com/style.css"
_M.js_ref = "http://www.example.com/script.js"

Redirect to a Custom Block Page URL

Customizes the block page to meet branding and message requirements by specifying the URL of the block page HTML file. The page can also implement CAPTCHA.

Default: nil

Example:

_M.custom_block_url = '/block.html'

📘

Note

This URI is allowed automatically under _M.Whitelist['uri_full'] to avoid infinite redirects.

Redirect on Custom URL

The _M.redirect_on_custom_url boolean flag to redirect users to a block page.

Default: false

Example:

_M.redirect_on_custom_url = false

By default, when a user exceeds the blocking threshold and blocking is enabled, the user is redirected to the block page defined by the _M.custom_block_url variable. The defined block page displays a 307 (Temporary Redirect) HTTP Response Code.

When the flag is set to false, a 403 (Unauthorized) HTTP Response Code is displayed on the blocked page URL.

Setting the flag to true (enabling redirects) results in the following URL upon blocking:

Text

http://www.example.com/block.html?url=L3NvbWVwYWdlP2ZvbyUzRGJhcg==&uuid=e8e6efb0-8a59-11e6-815c-3bdad80c1d39&vid=08320300-6516-11e6-9308-b9c827550d47

Setting the flag to false does not require the block page to include any of the examples below, as they are injected into the blocking page via the HUMAN NGINX Module.

📘

Note

The URL variable should be built with the URL-encoded query parameters (of the original request) with both the original path and variables base64-encoded (to avoid collisions with block page query params).

Custom Block Pages Requirements

As of version 4.0, Captcha logic is handled through the JavaScript snippet and not through the enforcer.

Users who have Custom Block Pages must include the new script tag and a new div in the .html block page. For implementation instructions refer to the appropriate links below:

• reCaptcha
• Custom Block Page

Redirect to Referer

Indicates whether the user is redirected from the challenge page to the referrer page after successfully solving the challenge.

Default: false

Example:

_M.redirect_to_referer = true

Changing the Minimum Score for Blocking

This value should not be changed from the default of 100 unless advised by HUMAN.

Default blocking value: 100

Example:

_M.blocking_score = 100

First-Party Prefix

Allows you to define a custom prefix for First-Party routes.

Default: nil

Example:

_M.first_party_prefix = 'resources'

To define the First-Party Prefix:

1. In your px_haproxy.lua file, set the _M.first_party_prefixproperty to the desired prefix value. For example:

   Lua

   _M.first_party_prefix = 'resources'
   

2. Open the HUMAN Console.

3. Go to Admin -> Applications.

4. Open the Snippet section. Activate First-Party (if not in First-Party already), and click Edit next to the Copy Snippet button.

5. In the pop-up that opens there are two routes beginning with /<appId without PX>. Copy both routes to a side document to use in the next steps.

6. Click Advanced Configuration.

7. Under Sensor, copy the first route from step 5 and add the prefix you added in step 1 to the beginning of of the route.

   For example: /resources/<appId without PX>/init.js

8. Under Server copy the second route from step 5 and the prefix you added in step 1 to the beginning of the route.

   For example: /resources/<appId without PX>/xhr

9. Click Save Changes.

10. Click Copy Snippet and update the JS Sensor snippet of your site with the updated one.

Advanced Blocking Response Support

Enables/disables support for Advanced Blocking Response.

Default: true (enabled)

Example:

_M.advanced_blocking_response = false

Proxy Support

Sets a proxy server for all the enforcer's outgoing calls.

Default: nil

Example:

_M.proxy_url = 'http://localhost:8008'

Proxy Authorization

If proxy support is enabled, allows you to set a proxy authorization header.

Default: nil

Example:

_M.proxy_authorization = 'top-secret-header-value'

Custom Cookie Header

When set, this property specifies a header name that will be used to extract the HUMAN cookie from, instead of the Cookie header.

📘

Note

Using a custom cookie header requires client-side integration to be done as well. Please refer to the relevant docs for details.

Default: nil

Example:

_M.custom_cookie_header = 'x-px-cookies'

Bypass Monitor Mode Header

When set, allows you to test the blocking flow of an enforcer, while in monitoring mode. When the enforcer receives a request that has this configured header name with the value of 1, it will behave as though it is in active blocking mode. For instance, requests with this header and bad user-agents (e.g., PhantomJS/1.0) will return with a block page.

Default: nil

_M.bypass_monitor_header = 'x-px-block'

Credential Intelligence

The following configurations are used to enable HUMAN Credential Intelligence offering:

Login Credentials Extraction

This feature extracts credentials (hashed username and password) from requests and sends them to HUMAN as additional info in risk / activity api calls. The feature can be toggled on and off. The settings are adjusted by modifying a credentials JSON file.

Enable Login Credentials Extraction

Default: false (disabled)

_M.px_enable_login_creds_extraction = true

Credentials JSON file

Sets a full path to credentials JSON file
Default: nil (none)

_M.px_login_creds_settings_filename = "/etc/haproxy/creds.json"

Credentials JSON file contains an array of CI items. Each item must contain the following fields:

• id : unique number
• method : string contains a method, supported methods: "post", "put"
• sent_through : contains one of the following strings: "body", "header", "query-param"
• path : string with URL path, must start with "/"
• user_field : string with username field name
• pass_field : string with password field name

This is an example of `/etc/creds.json` file. It includes an array of JSON objects containing the following properties:

{
    "features": {
        "credentials": {
            "items": [
                {
                    "id": 0,
                    "method": "post",
                    "path": "/login",
                    "sent_through": "body",
                    "pass_field": "password",
                    "user_field": "username"
                  }, {
                    "id": 1,
                    "method": "post",
                    "path": "/login-header",
                    "sent_through": "header",
                    "pass_field": "password",
                    "user_field": "username"
                  }, {
                    "id": 2,
                    "method": "put",
                    "path": "/login-params",
                    "sent_through": "query-param",
                    "pass_field": "password",
                    "user_field": "username"
                  }
            ]
        }
    }
}

Credentials Intelligence Version

Sets Credentials Intelligence protocol version
Default: 'v2'

_M.px_credentials_intelligence_version = 'v2';

IP Headers

A list of trusted headers that specify an IP to be extracted.

Default: Empty list

_M.ip_headers = {"X-Forwarded-For"}

Test Block Flow on Monitoring Mode

When set, allows you to test the blocking flow of an enforcer, while in monitoring mode. When the enforcer receives a request that has this configured header name with the value of 1, it will behave as though it is in active blocking mode. For instance, requests with this header and bad user-agents (e.g., PhantomJS/1.0) will return with a block page.

Default: Empty

_M.bypass_monitor_header = 'x-px-block'