Configuration Options

Required NGINX Configurations

The following NGINX Configurations are required to support the HUMAN NGINX Lua enforcer:

Apply HUMAN Enforcement

Add the following lines to your location block:

#----- PerimeterX protect location -----#
access_by_lua_block {
  local pxconfig = require("px.pxconfig")
  require ("px.pxnginx").application(pxconfig)
}
header_filter_by_lua_block {
  require("px.pxnginx").finalize()
}
#----- PerimeterX Module End  -----#

Lua CA Certificates

For TLS support to HUMAN servers, configure Lua to point to the trusted certificate location.

lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt";
lua_ssl_verify_depth 3;

📘

Please Note

The certificate location may differ between Linux distributions. In CentOS/RHEL systems, the CA bundle location may be located at /etc/pki/tls/certs/ca-bundle.crt.

Lua Package Path

Your Lua package path location in the HTTP section of your configuration reflects the location of the installed HUMAN modules.

lua_package_path "/usr/local/lib/lua/?.lua;;";

Lua Timer Initialization

Add the init within a Lua script. The init is used by HUMAN to hold and send metrics at regular intervals.

init_worker_by_lua_block {
    local pxconfig = require("px.pxconfig")
    require ("px.utils.pxtimer").application(pxconfig)
}

nginx.conf Example

The following nginx.conf example contains the required directives with enforcement applied to the location block.

worker_processes  1;
error_log /var/log/nginx/error.log;
events {
    worker_connections 1024;
}
http {
    lua_package_path "/usr/local/lib/lua/?.lua;;";
    # -- initializing the perimeterx module -- #
    init_worker_by_lua_block {
        local pxconfig = require("px.pxconfig")
        require ("px.utils.pxtimer").application(pxconfig)
    }
    lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt";
    lua_ssl_verify_depth 3;
    resolver 8.8.8.8;
    server {
        listen 80;
        location / {
            #----- PerimeterX protect location -----#
            access_by_lua_block {
              local pxconfig = require("px.pxconfig")
              require("px.pxnginx").application(pxconfig)
            }
            header_filter_by_lua_block {
              require("px.pxnginx").finalize()
            }
            #----- PerimeterX Module End  -----#
            root   /nginx/www;
            index  index.html;
        }
    }
}

Resolver

The Resolver directive must be configured in the HTTP section of your NGINX configuration.

• Set the resolver, resolver A.B.C.D;, to an external DNS resolver, such as Google (resolver 8.8.8.8;)
  or
• Set the resolver, resolver A.B.C.D;, to the internal IP address of your DNS resolver (resolver 10.1.1.1;).
  This is required for NGINX to resolve the HUMAN API.

Required Enforcer Configurations

The following configurations are set in:

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

• The HUMAN Application ID / AppId and HUMAN Token / Auth Token can be found in the portal in the following link
• The HUMAN Cookie Encryption Key can be found in the portal in the following link.

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

First-Party Configuration

First-Party Mode

First-Party Mode enables the module to send/receive data to/from the sensor, acting as a reverse-proxy for client requests and sensor activities.

First-Party Mode may require additional changes on the JS sensor snippet as mentioned here.

...
_M.first_party_enabled = true

The following routes must be enabled for First-Party Mode: - /<PX_APP_ID without PX prefix>/xhr/* - /<PX_APP_ID without PX prefix>/init.js

If the HUMAN Lua module is enabled on location /, the routes are already open and no action is necessary. If the HUMAN Lua module is not enabled on location /, add to your server block for NGINX:

server {
    listen 80;
    location /<PX_APP_ID without PX prefix> {
        #----- PerimeterX protect location -----#
        access_by_lua_block {
          local pxconfig = require("px.pxconfig")
          require("px.pxnginx").application(pxconfig)
        }
        header_filter_by_lua_block {
         require("px.pxnginx").finalize()
        }
        #----- PerimeterX Module End  -----#
        root   /nginx/www;
        index  index.html;
    }
}

HTTP v2 Support

The HUMAN NGINX module supports HTTP v2 for both Third-Party and First-Party implementations. To verify that your NGINX is running with HTTP v2 support, run:

nginx -V

For NGINX modules that support HTTP v2, the flag --with-http_v2_module will be listed. For example:

# nginx -V
nginx version: nginx/1.13.3
built by gcc 5.4.0 20160609 (Ubuntu 5.4.0-6ubuntu1~16.04.10)
built with OpenSSL 1.0.2g  1 Mar 2016
TLS SNI support enabled
configure arguments: --prefix=/nginx --with-ld-opt=-Wl,-rpath,/usr/local/lib --add-module=/ngx_devel_kit-0.3.0 --add-module=/lua-nginx-module-0.10.10 --with-http_ssl_module --with-http_stub_status_module --with-http_realip_module --with-ipv6 --with-http_v2_module

If you are running in Third-Party mode, you do not need to take any additional actions for the HUMAN NGINX module to support HTTP v2.

If you are running in First-Party mode, add the following location to your nginx.conf file:

location /<app id without PX prefix>/xhr/ {
    proxy_buffering on;
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host $server_name;
    proxy_set_header X-PX-Enforcer-True-IP $remote_addr;
    proxy_set_header X-PX-First-Party 1;
    set $pxcookie "";
    if ($cookie__pxvid != "") {
        set $pxcookie pxvid=$cookie__pxvid;
    }
    if ($cookie_pxvid != "") {
        set $pxcookie pxvid=$cookie_pxvid;
    }
    proxy_set_header cookie $pxcookie;
    proxy_pass https://collector-<app_id>.perimeterx.net/;
}

📘

Please Note

Make sure you replace the and <app_id> with your HUMAN appId value.

Optional Enforcer Configurations

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. Please refer to the PX context object for more information on accessible data that can be used within the additional activity handler.

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

Additional s2s Activity Header

Enables attaching additional s2s activity header ('px-additional-activity'), instead of sending Additional s2s activity to HUMAN Collector.

Default: false

_M.px_additional_s2s_activity_header_enabled = false

Advanced Blocking Response

In special cases, (such as XHR post requests) a full Captcha page render might not be an option. In such cases, using the Advanced Blocking Response returns a JSON object containing all the information needed to render your own Captcha challenge implementation, be it a popup modal, a section on the page, etc. The Advanced Blocking Response occurs when a request contains the Accept header with the value of application/json. A sample JSON response appears as follows:

{
    "appId": String,
    "jsClientSrc": String,
    "firstPartyEnabled": Boolean,
    "vid": String,
    "uuid": String,
    "hostUrl": String,
    "blockScript": String
}

Once you have the JSON response object, you can pass it to your implementation (with query strings or any other solution) and render the Captcha challenge.

In addition, you can add the _pxOnCaptchaSuccess callback function on the window object of your Captcha page to react according to the Captcha status. For example when using a modal, you can use this callback to close the modal once the Captcha is successfully solved.
An example of using the _pxOnCaptchaSuccess callback is as follows:

window._pxOnCaptchaSuccess = function (isValid) {
  if (isValid) {
    alert("yay");
  } else {
    alert("nay");
  }
};

For details on how to create a custom Captcha page, refer to the documentation

Advanced Blocking Response Support

Enables/disables support for Advanced Blocking Response.

Default: true (enabled)

Example:

_M.advanced_blocking_response = false

API Timeout Milliseconds

API Timeout in milliseconds (float) to wait for the HUMAN server API response. Controls the timeouts for HUMAN requests. The API is called when a Risk Cookie does not exist, is expired, or is invalid.

Default: 1000

Example:

_M.s2s_timeout = 250

Bypass Monitor Mode Header

When set, allows you to test the blocking flow of an enforcer, while in monitoring mode.

The property accept an header name which, if provided in a request with the value of 1, in addition to a bad user agent (such as PhantomJS/1.0) will block the request and show a challenge page.

Default: nil

_M.bypass_monitor_header = 'x-px-block'

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

Credential intelligence header name

Default: 'x-px-compromised-credentials'

_M.px_compromised_credentials_header_name = 'x-px-compromised-credentials'

Custom Block Pages Requirements

As of version 4.0, Captcha logic is being 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](examples/Custom Block Page + reCAPTCHA + Redirect/README.md)
• [Custom Block Page](examples/Custom Block Page/README.md)

Custom Cookie Header

When set, this property specifies a header name which 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: x-px-cookies

Example:

_M.custom_cookie_header = 'x-px-cookies'

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"

Data Enrichment

The HUMAN NGINX plugin stores the data enrichment payload on the request context. The data enrichment payload can also be processed with additional_activity_handler.

Only requests that are not being block will reach the backend server, so specific logic must be applied to the processing function.

The following example includes the pre-condition checks required to process the data enrichment payload and enrich the request headers.

...
_M.additional_activity_handler = function(event_type, ctx, details)
    -- verify that the request is passed to the backend
    if event_type == 'page_requested' then
      -- pxde - contains a parsed json of the data enrichment object
      -- pxde_verified - makes sure that this payload is trusted and signed by PerimeterX
      local pxde = ngx.ctx.pxde
      local pxde_verified = ngx.ctx.pxde_verified
      if pxde and pxde_verified then
          -- apply the data enrichment logic here
          -- the example below will set the f_type on the request header
          local f_type = ngx.ctx.pxde.f_type
          ngx.req.set_header("x-px-de-f-type", f_type)
      end
    end
end
...

For more information and the available fields in the JSON, refer to the HUMAN Portal documentation.

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

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. Values added in this configuration will match routes as prefix (e.g. "/path" will match with route "/path/example"). Use comma separation to add multiple values.

Default: Empty list (all routes are active)

Example:

_M.enabled_routes = {'/blockhere'}

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

Filter Sensitive Headers

A list of sensitive headers configured to prevent specific headers from being sent to HUMAN servers (headers in lower case). 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'}

First-Party Prefix

Allows you to define a custom prefix for First-Party routes. Refer to Setting Up A First Party Prefix for complete setup instructions.

Default: nil

Example:

_M.first_party_prefix = 'resources'

Setting Up A First Party Prefix

In some cases you may need to define a prefix to the Enforcer's First-Party routes. The custom prefix must be defined both in the Enforcer's config file and in the HUMAN console.

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:

   ShellShell

   Shell

   _M.first_party_prefix = 'resources'
   

2. Open the {{variable.HUMAN Security}} 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.

Hype sales challenge

To enforcer will server the hypesale page in cases where the custom_param["is_hype_sale"] set to true.
If the request contains a cookie _px3 with the cpa value so the hypesale will not be served but the enforcer will do risk_api to verify the request.

HypeSale host

Sets HypeSale host

Default: 'https://captcha.px-cdn.net'

_M.hypesale_host = 'https://captcha.px-cdn.net'

Log Enrichment

Access logs can be enriched with the HUMAN bot information by creating an NGINX variable with the proper name. To configure this variable use the NGINX map directive in the HTTP section of your NGINX configuration file. This should be added before additional configuration files are added.

The following variables are enabled:

• Request UUID: pxuuid
• Request VID: pxvid
• Risk Round Trimp: pxrtt
• Risk Score: pxscore
• Pass Reason: pxpass
• Block Reason: pxblock
• Cookie Validity: pxcookiets
• Risk Call Reason: pxcall

....
http {
    map score $pxscore  { default 'none'; }
    map pass $pxpass  { default 'none'; }
    map uuid $pxuuid  { default 'none'; }
    map rtt $pxrtt { default '0'; }
    map block $pxblock { default 'none'; }
    map vid $pxvid { default 'none'; }
    map cookiets $pxcookiets { default 'none'; }
    map px_call $pxcall { default 'none'; }
    log_format enriched '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" '
                    '| perimeterx uuid[$pxuuid] vid[$pxvid] '
                    'score[$pxscore] rtt[$pxrtt] block[$pxblock] '
                    'pass[$pxpass] cookie_ts[$pxcookiets] risk_call[$pxcall]';
    access_log /var/log/nginx/access_log enriched;
  }
  ...

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/creds.json'

Example available in examples/creds.json file. It includes an array of JSON objects containing the following properties:

{
  "id": 0, // unique int
  "method": "post", // supported methods: post
  "sent_through": "body", // supported sent_throughs: header, url, body
  "path": "/login", // login path
  "pass_field": "password", // name of the password field in the request
  "user_field": "username" // name of the username field in the request
}

Credentials Settings

Instead of using a separate JSON file for CI settings, one could specify CI configuration in pxconfig.lua file, using _M.px_login_creds_settings table.

_M.px_login_creds_settings table consists of one or more CI items. Each item must contain the following keys: "method", "sent_through", "path", "pass_field", "user_field".

Default: nil 

_M.px_login_creds_settings = {
    { ["method"] = "post", ["path"] = "/login", ["sent_through"] = "body", ["pass_field"] = "password", ["user_field"] = "username" },
    { ["method"] = "post", ["path"] = "login-header", ["sent_through"] = "header", ["pass_field"] = "password", ["user_field"] = "username" },
}

Credentials Intelligence Version

Sets Credentials Intelligence protocol version

Default: 'v2'

_M.px_credentials_intelligence_version = 'v1'

Login successful custom function

Sets an user defined function which should return true if login was successful.

Default: nil

_M.custom_login_successful = function()
    local headers, err = ngx.resp.get_headers()
    if err then
        return false
    end
    if headers['x-login'] and headers['x-login'] == "123" then
        return true
    else
        return false
    end
end

Login successful header name

Default: 'x-px-login-successful'

_M.px_login_successful_header_name = "x-px-login-successful"

Login successful header value

Default: '1'

_M.px_login_successful_header_value = "1"

Login successful reporting method

Sets login successful reporting method, could be one of the following values: 'none', 'header', 'status', 'custom'

Default: 'none'

--_M.px_login_successful_reporting_method = 'none'

Login successful status

Sets a list of login successful status(e.g. _M.px_login_successful_status = { 200, 201, 202 } ).

Default: { 200 }

_M.px_login_successful_status = { 200 }

Monitor / Block Mode Configuration

By default, the HUMAN plugin is set to Monitor Only 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.

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.

Monitored Routes

Allows you to define a set of routes that will be handled as if in monitor mode, even if block_enabled is set to true. Values added in this configuration will match routes as prefix (e.g. "/path" will match with route "/path/example"). Use comma separation to add multiple values.

Default: Empty list

Example:

_M.monitored_routes = {'/profile'}

Multiple App Support

The HUMAN Enforcer allows multiple configurations for different applications.

If your HUMAN account contains several applications (as defined in the Portal), you can create different configurations for each application.

NOTE: The application initializes a timed Enforcer. The Enforcer must be initialized with one of the applications in your account. The the correct configuration file name must be passed to the require ("px.utils.pxtimer").application("AppName"|empty) block in the server initialization.

1. Open the nginx.conf file, and locate the require("px.pxnginx").application() line inside your location block.
2. Pass the desired application name into the application() function.
   For example: require("px.pxnginx").application("mySpecialApp")
3. Locate the pxconfig.lua file, and create a copy of it.
   The copy name should follow the pattern:
   pxconfig-<AppName>.lua (e.g. pxconfig-mySpecialApp.lua)
   The < AppName > placeholder must be replaced by the exact name provided to the application function in step 1.
4. Change the configuration in file created in step 3.
5. Save the file in the location where pxnginx.lua file is located.
   (Default location: /usr/local/lib/lua/px/<yourFile>)
6. For every location block of your app, replace the code mentioned in step 2 with the correct < AppName >.

HUMAN Context Object

The HUMAN context object (ngx.ctx) is an internal object within the Enforcer, which is created per request and holds the entire state regarding the specific request. The customer who integrates the Enforcer in his environment controls the Enforcer behavior using different configuration values, a few of them are custom functions that can be implemented as necessary.

The "ngx.ctx" object could be accessed from those custom functions. "ngx.ctx" object can be used to access fields and values that the Enforcer has inferred from the request as part of its detection process, and can be used by the customer to perform his own logic based on our detections. A simple use case for example is to examine the HUMAN score that the request gets and add a header to the request to the origin with the given score. The functions that has access to the ngx.ctx are:

• Additional Activity Handler
• Custom Login Successful

"ngx.ctx" useful fields:

• ngx.ctx.block_score - the HUMAN score this request received.
• ngx.ctx.risk_rtt - risk round trip time, the time it took for the risk request from when it was sent until the response was received.
• ngx.ctx.pxde - HUMAN data enrichment, the data enrichment cookie is attached to S2S calls as a way to transfer additional data between the Enforcer and HUMAN collector. The data it contains is set by the collector according to the setting in the portal and is available on the cookie as a JSON object. While this functionality is mostly controlled by the collector, you may want access to the HUMANDE values after activities have been sent, in the additional activity handler.
• ngx.ctx.pass_reason - reason HUMAN decided to pass the request, can be one of s2s, cookie, s2s_timeout, s2s_error.
• ngx.ctx.px_is_mobile - whether this is a mobile or web request.

Proxy Authorization

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

📘

Note

Requires lua-resty-http version 0.12 and up.
Default: nil

Example:

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

Proxy Support

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

📘

Note

Requires lua-resty-http version 0.12 and up.
Default: nil

Example:

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

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

📘

Please 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).

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'

📘

Please Note

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

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

Secured HUMANHD Cookie

A boolean flag to enable/disable the Secure flag when baking a HUMANHD cookie.

Default: false

_M.pxhd_secure_enabled = true

Send Raw Username On Additional s2s Activity

Enables sending a raw username on additional s2s activity (only when activities are sent to HUMAN Collector)

Default: false

_M.px_send_raw_username_on_additional_s2s_activity = false

Sensitive GraphQL Operations

For those using GraphQL endpoints, it is possible to trigger server-to-server risk calls on particular operation types or names. Like the sensitive routes feature, a request that contains an operation of the configured type or name will trigger a server call to HUMAN servers every time that operation is performed.

If an operation type (e.g., query, mutation) is configured in px_sensitive_graphql_operation_types, all GraphQL operations of that type will be treated as sensitive. If an operation name is configured in px_sensitive_graphql_operation_names, all GraphQL operations with that name will be treated as sensitive.

Sensitive GraphQL Operation Types

Sets the list of one or more operation types (e.g., query, mutation)

Default: nil (none)

_M.px_sensitive_graphql_operation_types = {}

Sensitive GraphQL operation names

Sets the list of one or more operation names

Default: nil (none)

_M.px_sensitive_graphql_operation_names = {}

Sensitive GraphQL routes

Sets the list of one or more GraphQL routes.

Default: /graphql

_M.px_graphql_routes = { "/graphql", "/graphql/csrf" }

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

Sensitive Routes Regex List

A list of route regular expressions (regex). When HUMAN module matches the request URI with a regex from the list, the 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 = {'^/login/[0-9]*user$'}

URI Delimiters

HUMAN processes URI paths with general- and sub-delimiters according to RFC 3986. General delimiters (e.g., ?, #) are used to separate parts of the URI. Sub-delimiters (e.g., $, &) are not used to split the URI as they are considered valid characters in the URI path.

Whitelisting

Whitelisting (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_uri_pattern = {},
_M.whitelist_ip_addresses = {},
_M.whitelist_ua_full = {},
_M.whitelist_ua_sub = {}

Cross-Origin Resource Sharing (CORS) Support

For security reasons, browsers can block cross-origin requests, if they are not allowed by a third-party origin.

CORS is a mechanism that lets the server indicate if a request contains cross-origin resources. It does so by adding special HTTP headers to the request, which allows the browser to load such resources.

In most cases, CORS employs a two-stage procedure with a preliminary request, called preflight, followed by the actual request. The preflight request checks if the actual request will be responded to. To learn more about different request types, see these examples.

The CORS behavior must be configured to address both simple requests (without preflight) and more complex ones (with preflight).

Enable CORS Support

To enable CORS Support set true to px_cors_support_enabled.

_M.px_cors_support_enabled = true

Enable passing preflight requests to the origin

To enable passing preflight requests to the origin set true to px_cors_preflight_request_filter_enabled.

_M.px_cors_preflight_request_filter_enabled = true

Contributing to the project

Test

Tests for this project are written using the Test::Nginx testing framework.

Don't forget to test.

This project relies heavily on tests to ensure that each user has the same experience, and no new features break the code. Before you create any pull request, make sure your project has passed all tests. If any new features require it, write your own test.

To run the tests:

1. Build the docker container.
2. Run the tests using the following command: make docker-test.

Pull Request

Once you have completed the process, create a pull request. Provide a complete and thorough description explaining the changes. Remember, the code has to be read by our maintainers, so keep it simple, smart and accurate.