> This page is for Applications Protection. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.humansecurity.com/llms.txt. # HUMAN Plugin Configuration ## Configuration The HUMAN Lua Module configuration is in the following location:\ `/usr/local/lib/lua/px/pxconfig.lua` ```lua -- ## Required Parameters ## _M.px_appId = 'PX_APP_ID' _M.auth_token = 'PX_AUTH_TOKEN' _M.cookie_secret = 'COOKIE_ENCRYPTION_KEY' ``` 1. The **HUMAN** **Application ID / AppId** **and HUMAN** **Token / Auth Token / Authorization Token** can be found in the Portal, under [**Applications**](https://console.humansecurity.com/botDefender/admin).\ ![](/_fern-img/9bd6c8743e575fd6fa77cede04a8c409a58d1a67b9594691984aefb97161f63d.webp) 2. HUMAN **Cookie Encryption Key / Risk Cookie** can be found in the portal, under [**Policies**](https://console.humansecurity.com/botDefender/admin).\ ![](/_fern-img/c6b3ac85f3226a12d036b580919dfb62e40ff3f89e84fdec3c76323f57f44e26.webp) \_\_NOTE: The Policy from where the **Cookie Encryption Key** is taken must correspond with the Application from where the **Application ID / AppId** and HUMAN **Token / Auth Token** \_\_ ## Optional Configurations ## 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 `pxconfig.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` Valid request flow example: ```text 2017/12/04 12:04:18 [error] 7#0: *9 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - Cookie V3 found - Evaluating, client: 172.17.0.1, server: , request: "GET / HTTP/1.1", host: "localhost:8888" 2017/12/04 12:04:18 [error] 7#0: *9 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - cookie is encyrpted, client: 172.17.0.1, server: , request: "GET / HTTP/1.1", host: "localhost:8888" 2017/12/04 12:04:18 [error] 7#0: *9 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - Cookie evaluation ended successfully, risk score: 0, client: 172.17.0.1, server: , request: "GET / HTTP/1.1", host: "localhost:8888" 2017/12/04 12:04:18 [error] 7#0: *9 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - Sent page requested activity, client: 172.17.0.1, server: , request: "GET / HTTP/1.1", host: "localhost:8888" 2017/12/04 12:04:18 [error] 7#0: *9 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - Request is internal. PerimeterX processing skipped., client: 172.17.0.1, server: , request: "GET / HTTP/1.1", host: "localhost:8888" 2017/12/04 12:04:19 [error] 7#0: *63 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - POST response status: 200, context: ngx.timer 2017/12/04 12:04:19 [error] 7#0: *63 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - Reused conn times: 3, context: ngx.timer ``` ## Allowlist Allowing (bypassing enforcement) is configured in the `pxconfig.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 = {}, _M.whitelist_hosts = {} ``` | **Filter Name** | **Value** | **Filters Request To** | | ---------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`whitelist_uri_full`** | `{'/api_server_full'}` | Matches exactly `/api_server_full?data=1`, but does not match `/api_server?data=1`. | | **`whitelist_uri_prefixes`** | `{'/api_server'}` | Matches any URI starting with `/api_server`, such as `/api_server_full?data=1`, but does not match URIs like `/full_api_server?data=1`. | | **`whitelist_uri_suffixes`** | `{'.css'}` | Matches URIs ending with `.css`, like `/style.css`, but does not match other file types, such as `/style.js`. | | **`whitelist_ip_addresses`** | `{'192.168.99.1'}` | Filters requests originating from the specified IP addresses, for example, `192.168.99.1`. | | **`whitelist_ua_full`** | `{'Mozilla/5.0 (compatible; pingbot/2.0; http://www.pingdom.com/)'}` | Filters requests with the exact User-Agent (UA) string provided. Only requests with the exact UA `Mozilla/5.0 (compatible; pingbot/2.0; http://www.pingdom.com/)` will match. | | **`whitelist_ua_sub`** | `{'GoogleCloudMonitoring'}` | Filters requests containing the specified substring within the User-Agent. Any UA that includes `GoogleCloudMonitoring`, like `Mozilla/5.0 (compatible; GoogleCloudMonitoring/1.0)`, will match. | | **`whitelist_hosts`** | `{'example.com'}` | Filters requests based on the host header. Requests with the host header set to `example.com` will match, while requests with other hosts will not. | ## 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, and can be overridden on the `pxConfig` variable. **Default:** cookie, cookies Example: ```lua _M.sensitive_headers = {'cookie', 'cookies', 'secret-header'} ``` ## Remote Configurations Allows the module to periodically pull configurations from HUMAN services. When enabled, the configuration can be changed dynamically via HUMAN Portal **Default:** false **File:** `pxconfig.lua` Example: ```lua ... _M.dynamic_configurations = false _M.load_interval = 5 ... ``` ## 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'} ``` ## API Timeout Milliseconds API Timeout in milliseconds (float) to wait for the HUMAN  server API response. The API is called when a risk cookie does not exist, is expired, or is invalid. If the timeout is reached before a response is received, the module will pass the client request. **Default:** 1000 Example: ```none _M.s2s_timeout = 250 ``` ## 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: ```none _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' ``` > **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: ```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: ```none 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**](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 ``` ## Additional Activity Handler An additional activity handler is added by setting `_M.additional_activity_handler` with a user defined function in the 'pxconfig.lua' file. **Default:** Activity is sent to HUMAN as controlled by 'pxconfig.lua'. Example: ```lua _M.additional_activity_handler = function(event_type, ctx, details) local cjson = require "cjson" if (event_type == 'block') then logger.warning("PerimeterX " + event_type + " blocked with score: " + ctx.blocking_score + "details " + cjson.encode(details)) else logger.info("PerimeterX " + event_type + " details " + cjson.encode(details)) end end ``` ## Enrich Custom Parameters With the `enrich_custom_params` function you can add up to 10 custom parameters to be sent back to HUMAN servers. When set, the function is called before setting the payload on every request to HUMAN servers. The parameters should be passed according to the correct order (1-10). You must return the `px_cusom_params` object at the end of the function. **Default:** nil Example: ```lua _M.enrich_custom_parameters = function(px_custom_params) px_custom_params["custom_param1"] = "user_id" return px_custom_params end ``` ## 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 `pxconfig.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](#advancedBlockingResponse). **Default:** true (enabled) Example: ```lua _M.advanced_blocking_response = false ``` ## Proxy Support Sets a proxy server for all the enforcer's outgoing calls. > Requires `lua-resty-http` version 0.12 and up. **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. > Requires `lua-resty-http` version 0.12 and up. **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. > **Note** > > 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' ```