*** title: Configuration slug: configuration hidden: false createdAt: Thu Nov 07 2024 17:33:44 GMT+0000 (Coordinated Universal Time) updatedAt: Mon Mar 10 2025 15:12:57 GMT+0000 (Coordinated Universal Time) --------------------- For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.humansecurity.com/applications/llms.txt. For full documentation content, see https://docs.humansecurity.com/applications/llms-full.txt. All HAProxy Enforcer configuration are placed in `px_config.lua` file, which is located in `/usr/local/etc/` directory. ## Required HUMAN Module Configuration The following parameters are mandatory: * **px\_enabled** * **px\_appId** * **px\_cookie\_secret** * **px\_auth\_token** ```lua -- ## Required Parameters ## _M.px_enabled = true _M.px_appId = "" _M.auth_token = "" _M.cookie_secret = "" ``` ## **px\_app\_id** The application ID. Required to initialize the HAProxy Enforcer. ```lua _M.px_appId = "" ``` ## **px\_auth\_token** The token used for authorization with the HUMAN backend. Required to initialize the HAProxy Enforcer. ```lua _M.auth_token = "" ``` ## **px\_cookie\_secret** The secret used to encrypt and decrypt the risk cookie. Required to initialize the HAProxy Enforcer. ```lua _M.cookie_secret = "" ``` ## **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. ```lua _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_config.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_config.lua` file. Several filters can be configured: ```lua _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: ```lua _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: ```lua _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: ```lua _M.sensitive_routes_prefix = {'/login', '/user/profile'} _M.sensitive_routes_suffix = {'/download'} ``` ## Enrich Custom Parameters A list of up to 10 header keys that allows you to send up to 10 custom parameters back to HUMAN servers. The parameters should be passed according to the correct order (1-10). Skipping is possible using an empty string (i.e "header1", "header2", "", "header4"). **Default:** Empty list ```lua _M.custom_parameters = {"", "x-user-id", "", "x-vid"} ``` ## **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: ```lua _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: ```lua _M.custom_block_url = '/block.html' ``` 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: ```lua _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 ```plaintext 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. 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**](https://github.com/PerimeterX/perimeterx-nginx-plugin/tree/master/examples/Custom%20Block%20Page%20%2B%20CAPTCHA) * [**Custom Block Page**](https://github.com/PerimeterX/perimeterx-nginx-plugin/tree/master/examples/Custom%20Block%20Page) ## **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: ```lua _M.redirect_to_referer = true ``` ## Disable Original Redirect URL Query Encoding When a request is blocked and redirected to a custom block page, the original request URL is passed as a query parameter (`url`) to the destination. This parameter allows the block page to identify the specific resource the user was attempting to access. To ensure compatibility and prevent issues with special characters during the redirect process, the entire original URL string is `Base64 encoded`. `px_redirect_on_custom_url_raw_query` setting controls whether the query string within the original URL is URL-encoded (percent-encoded) prior to the final Base64 encoding. URL encoding follows the standards defined in [W3C HTML 4.01 Specification](http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1). When `false` (Default): The original URL's query parameters are URL-encoded. This ensures maximum compatibility with web servers and prevents misinterpreted characters. When `true`: The system disables URL encoding for the query portion. The query parameters are kept in their raw state before the entire URL is Base64 encoded. Use this if your block page logic requires literal characters (e.g., specific delimiters) that URL encoding might obscure. **Default:** false ```lua http { ... server { ... _M.custom_block_url = '/block.html' _M.redirect_on_custom_url = true _M.redirect_on_custom_url_raw_query = 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: ```lua _M.blocking_score = 100 ``` ## **First-Party Prefix** Allows you to define a custom prefix for First-Party routes. **Default:** nil Example: ```lua _M.first_party_prefix = 'resources' ``` #### **To define the First-Party Prefix:** 1. In your `px_config.lua` file, set the `_M.first_party_prefix`property to the desired prefix value. For example: ```lua _M.first_party_prefix = 'resources' ``` 2. Open the [HUMAN Console](https://console.humansecurity.com/user/login?nextUrl=/). 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 `/`. 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//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//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](https://portal.document360.io/#advancedBlockingResponse). **Default:** true (enabled) Example: ```lua _M.advanced_blocking_response = false ``` ## **Proxy Support** Sets a proxy server for all the enforcer's outgoing calls. **Default:** nil Example: ```lua _M.proxy_url = 'http://localhost:8008' ``` ## **Proxy Authorization** If proxy support is enabled, allows you to set a proxy authorization header. **Default:** nil Example: ```lua _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. Using a custom cookie header requires client-side integration to be done as well. Please refer to the relevant [docs](https://console.perimeterx.com/docs/advanced_client_integration.html#custom-cookie-header) for details. **Default:** nil Example: ```lua _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 ```lua _M.bypass_monitor_header = 'x-px-block' ``` ## Credential Intelligence The following configurations are used to enable HUMAN [Credential Intelligence](/applications/credential-intelligence-overview) 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) ```lua _M.px_enable_login_creds_extraction = true ``` ### Credentials JSON file Sets a full path to credentials JSON file Default: nil (none) ```lua _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: ```json { "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' ```lua _M.px_credentials_intelligence_version = 'v2'; ``` ## IP Headers A list of trusted headers that specify an IP to be extracted. **Default:** Empty list ```lua _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 ```lua _M.bypass_monitor_header = 'x-px-block' ```