Enforcer Configuration

Suggest Edits

🚧
PII (Personally Identifiable Information) Anonymization
Personally Identifiable Information (PII) is information that can be used on its own or with other information to identify a single person, or to identify an individual in context.
It is important for us to keep personal private information out of our servers. Therefore, by default, we do not send the request body and cookies to HUMAN backend servers; communication is based on header data.
PII is not a recommended setting. If PII is essential for your organization, contact HUMAN Support.
When PII is enabled, HUMAN does not store a client’s full IP information (client IP, HTTP headers). In IPv4, this is done by zeroing 4th IP octet (for example, the IP 1.2.3.4 will be stored as 1.2.3.0). In IPv6 this is done by zeroing the last four (4) octets (for example, the IP 1:2:3:4:1:2:3:4 will be stored as 1:2:3:4:1:2:3:0).
Removing the IP's last octet can result small reduction of detection capability, usually for the models and signatures that are based on IPs.

Active Header Name

Allows you to pass a specific header (e.g. x-px-active) when px_enabled is off. When the header has a value of 1, the module is enabled for the specific request. When the header has a value of 0, the module is not enabled.

This feature can be used for a/b testing.

Default: Empty

"px_active_header_name": "x-px-active"

Advanced Blocking Response Flag

Enables/disables the Advanced Blocking Response functionality.

Default: false

"px_enable_json_response": true

Allowed Cookies

A list of cookie names that are allowed to be sent to HUMAN servers on server-to-server calls.

Default: Empty list

"px_allowed_cookies": ["SID" "NID"]

Allowlist Routes

Allowing (bypassing enforcement) can be configured on different aspects of the request, ranging from URI to IP addresses and user agents. The rules are OR based.

Default: Empty list

"px_whitelist_uri_full": ["/api_server_full?data=1"],
"px_whitelist_uri_prefixes": ["/api_server"],
"px_whitelist_uri_suffixes": [".json"],
"px_whitelist_ip_addresses": ["10.0.0.15", "192.168.0.0/16"],
"px_whitelist_ua_full": ["Mozilla/5.0 (compatible; pingbot/2.0; http://www.pingdom.com/)"],
"px_whitelist_ua_sub": ["GoogleCloudMonitoring"]

Filter Traffic by pairs of regular expressions and HTTP methods

An array of pairs of of regular expressions and HTTP methods that are always filtered out and not validated by the Enforcer. Requests with paths matching these configured patterns will always be allowed to pass the Enforcer.

px_whitelist_uri_regex takes one or multiple pairs of a route RegEx and a HTTP method.

"px_whitelist_uri_regex": ["\/images|\/docs", "GET"]

Filter By Domain

An array of regular that are always filtered out and not validated by the Enforcer. Requests with Domains matching these configured patterns will always be allowed to pass the Enforcer.

px_filter_by_domain takes one or multiple Domain route RegEx.

"px_filter_by_domain": ["img\.example\.com|docs\.example\.com"]

API Timeout

Controls the timeout property for HUMAN requests. Times are in milliseconds.

Default: 1000

"px_s2s_timeout": 750

Blocking Score

Sets the minimum blocking score of a request. Do not change this value without consulting with a HUMAN support engineer.

Possible values:

Any integer between 0 and 100.

Default: 100

"px_blocking_score": 100

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)

"px_enable_login_creds_extraction": false

Credentials JSON file

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

"px_login_creds_settings_filename": "/etc/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'

"px_credentials_intelligence_version": "v2"

Login successful header name

Default: 'x-px-login-successful'

"px_login_successful_header_name": "x-px-login-successful"

Login successful header value

Default: '1'

"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'
Default: 'none'

"px_login_successful_reporting_method": "none"

Login successful status

Sets a list of login successful status.
Default: 200

"px_login_successful_status": [200, 201]

Custom Logo

The logo is displayed at the top of the the block page.
Max-height = 150px, Width = auto.

Default: Empty

"px_custom_logo": "http://www.example.com/logo.png"

Debug Mode

A boolean flag to enable/disable the debug log messages.

Default: false

"px_debug": true

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)

"px_enabled_routes": ["/search", "/products"]

Enforced Routes

Allows to define a set of routes that will be handled by the Enforcer (px_block_enabled must be set to true). All other routes, that do not match regex(-s), will be ignored by the Enforcer. Values added in this configuration will match routes as regex (e.g. “^/path” will match with route “/path/example”). Use whitespace separation to add multiple values.

Default: Empty list

"px_enforced_routes": "^/path"

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

"px_custom_parameters": ["x-user-id", "x-vid"]

It is also possible to extract custom parameters from cookies. Just as with the headers, the cookie keys should be passed according to the correct order (1-10). Parameters extracted from cookies will be base64 decoded.

Default: Empty list

"px_cookie_custom_parameters": ["_someCookie", "_someOtherCookie"]

First Party URL Override

In some specific cases (as instructed by HUMAN) you can override the default domains for first-party calls by adding the px_client_host and px_captcha_script_host properties and providing alternate URLs.

Default: Empty

"px_client_host": "https://client.px-cloud.net",
"px_captcha_script_host": "//captcha.px-cloud.net"

📘
Note
Both values should not have a trailing /.
The px_captcha_script_host value should not have a protocol. It should always begin with //.

CSS Ref

Modifies a custom CSS by adding the px_css_ref property and providing a valid URL to the CSS.

Default: Empty

"px_css_ref": "http://www.example.com/style.css"

IP Headers

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

Default: Empty list

"px_ip_headers": "X-Forwarded-For"

JS Ref

Adds a custom JS file by adding the px_js_ref property and providing the JS file that is loaded with the block page.

Default: Empty

"px_js_ref": "https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"

Monitor Mode/Block Mode

By default, the HUMAN plugin is set to monitor mode. To active blocking mode, set the px_block_enabled property to true.

Default: false

"px_block_enabled": true

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 regex (e.g. “^/path” will match with route “/path/example”). Use whitespace separation to add multiple values.

Default: Empty list

"px_monitored_routes": ["^/path"]

Redirect to a Custom Block Page URL

Customizes the block page to meet branding and message requirements by specifying the URL of a custom block page HTML file.

Default: Empty / false

"px_custom_block_url": "/pages/block.html",
"px_redirect_on_custom_url": true

Score Header

A set of properties configuring sending the HUMAN score on upstream and/or downstream headers.

Default: false / empty string

"px_score_header_enabled": true,
"px_upstream_score_header_name": "x-px-upstream-score",
"px_score_header_name": "x-px-score"

Sensitive Headers

A list of headers that are not sent to HUMAN servers on server-to-server API calls.

Default: "cookie" "cookies"

"px_sensitive_headers": ["x-px-auth", "x-px-key"]

Sensitive Routes

A list of route prefixes/suffixes that trigger a server call to HUMAN servers every time the route is called, regardless of viewing history.

Default: Empty list

"px_sensitive_routes_prefix": ["/login", "/user/profile"]
"px_sensitive_routes_suffix": ["/download"]

Sensitive Routes Regex

A list of route regexs that trigger a server call to HUMAN servers every time the route is called, regardless of viewing history.

Default: Empty list

"px_sensitive_routes_regex": ["/.*\/enforced\/regex$/"]

Outgoing Enforcer traffic compression

By default, the HUMAN Enforcer sends uncompressed traffic to HUMAN Collector. To activate outgoing Enforcer traffic compression (for "offline" activities), set px_compression_enabled property to true.

Default: false

"px_compression_enabled": true

Outgoing Enforcer traffic compression level

By default, HUMAN Enforcer uses gzip compression with the compression level 6.

Default: 6

"px_compression_level": 6

Filter By Extension

An array of extensions that are always filtered and not validated by the HUMAN Enforcer. Requests with path extensions matching these configured patterns will always be allowed to pass the HUMAN Enforcer.

Default: '.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' '.json' '.xml'

"px_filter_by_extension": [".jpeg", ".gif", ".png"]

Filter By HTTP Method

An array of strings that represent HTTP methods that are always filtered and not validated by the HUMAN Enforcer. Requests with HTTP methods matching these will always be allowed to pass the HUMAN Enforcer.

Default: Empty list

"px_filter_by_http_method": ["post"]

Custom First Party Sensor Endpoint

The default first party endpoint to retrieve the HUMAN sensor is /<app_id_without_PX>/init.js. In certain cases (adblockers, etc.) it may be beneficial to change this endpoint name to a different value. You can do this by configuring a custom endpoint name using this configuration.

"px_custom_first_party_sensor_endpoint": "/botdefense"

You should also modify the snippet on the HTML pages served to refer to this custom endpoint.

// JS snippet code

(function(){
    // Custom parameters
    // window._pxParam1 = "";
    var p = document.getElementsByTagName('script')[0],
        s = document.createElement('script');
    s.async = 1;
    s.src = '/botdefense'; // custom endpoint
    p.parentNode.insertBefore(s,p);
}());

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

"px_bypass_monitor_header": "x-px-block"

URL Decode Reserved Characters

When set, the enforcer decodes reserved characters (such as %3F → ? and %2F → /).

Default: false

"px_url_decode_reserved_characters": true

Updated 12 days ago

🚧PII (Personally Identifiable Information) Anonymization

Active Header Name

Advanced Blocking Response Flag

Allowed Cookies

Allowlist Routes

Filter Traffic by pairs of regular expressions and HTTP methods

Filter By Domain

API Timeout

Blocking Score

Credential Intelligence

Login Credentials Extraction

Enable Login Credentials Extraction

Credentials JSON file

Credentials Intelligence Version

Login successful header name

Login successful header value

Login successful reporting method

Login successful status

Custom Logo

Debug Mode

Enabled Routes

Enforced Routes

Enrich Custom Parameters

First Party URL Override

📘Note

CSS Ref

IP Headers

JS Ref

Monitor Mode/Block Mode

Monitored Routes

Redirect to a Custom Block Page URL

Score Header

Sensitive Headers

Sensitive Routes

Sensitive Routes Regex

Outgoing Enforcer traffic compression

Outgoing Enforcer traffic compression level

Filter By Extension

Filter By HTTP Method

Custom First Party Sensor Endpoint

Test Block Flow on Monitoring Mode

URL Decode Reserved Characters

🚧
PII (Personally Identifiable Information) Anonymization

📘
Note