HUMAN Plugin Configuration

Configuration

The HUMAN Lua Module configuration is in the following location:
/usr/local/lib/lua/px/pxconfig.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.
   
2. HUMAN Cookie Encryption Key / Risk Cookie can be found in the portal, under Policies.
   

_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:

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 acitvity, 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:

_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, and can be overridden on the pxConfig variable.

Default: cookie, cookies

Example:

_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:

   ...
   _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:

 _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'}

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:

 _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:

_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:

 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

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:

_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:

_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:

  _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 pxconfig.lua file, set the _M.first_party_prefixproperty to the desired prefix value. For example:

   _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.

Requires lua-resty-http version 0.12 and up.

Default: nil

Example:

_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:

_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'