Product guides

Configuration Options

Suggest Edits

ASP Configuration options

The HUMAN Enforcer is configured using a set of properties specified below the HumanConfiguration section in the appsettings.json file.

Required parameters

  • px_app_id
  • px_cookie_key
  • px_api_token
"px_app_id": "APP_ID",
"px_auth_token": "AUTH_TOKEN",
"px_cookie_secret": "COOKIE_SECRET",

Module Enabled

A boolean flag to enable/disable the HUMAN Enforcer.

Default: true

"px_module_enabled": true

Module Mode

Sets the working mode of the enforcer.

Possible values:

  • monitor - Monitor Mode
  • active_blocking - Blocking Mode

Default: monitor

"px_module_mode": "active_blocking"

Blocking Score

Sets the minimum blocking score of a request.

Possible values:

  • Any integer between 0 and 100.

Default: 100

"px_blocking_score": 100

Debug Mode

Sets the logging mode of the worker.

Possible values:

  • error - HUMAN logger will log errors only and fatal events (e.g., exceptions)
  • debug - HUMAN logger will output detailed logs for debugging purposes

Default: error

"px_logger_severity": "debug"

S2S Timeout

The maximum amount of time, in milliseconds, to wait when performing a Risk API request. If this timeout is reached before a score is obtained, the request will pass with pass_reason: s2s_timeout.

Default: 1000

"px_s2s_timeout": 2000

Sensitive Routes

Some routes may be more prone to bot attacks than others. For example, routes that execute payments or handle personal information. By using regular expressions, you can configure these routes as sensitive to ensure more stringent protection. The Enforcer will make Risk API calls on such sensitive routes, even if the request contains a valid cookie.

Default: Empty array

"px_sensitive_routes": ["/login","/home"]
"px_sensitive_routes_regex": ["^/home$", "^/login.*"]

your title goes here

📘

Note:

Generally, ^ and $ anchors are a good way of ensuring that a regex matches an entire string.

IP Headers

An array of trusted headers that specify an IP to be extracted.

Default: Empty array

"px_ip_headers": ["x-user-real-ip"]

Custom Ip Extraction

This function allows you to customize the logic for extracting the user IP.

"px_ip_extraction_handler":"CustomIpExtractionImpl"

The custom logic will reside in the Handle method, making use of the following argument:

  • HttpRequest httpRequest - The currently running .NET Core application request , contains the HTTP values sent by a client during a Web request.
using human_module;

namespace MyApp
{
    public class CustomIpExtractionImpl : ICustomIpExtraction
    {
        public string? Handle(HttpRequest httpRequest)
        {
            if (httpRequest.Headers.ContainsKey("x-forwarded-for"))
            {
                httpRequest.Headers.TryGetValue("x-forwarded-for", out var value);
                return value.ToString().Split(",")[0];
            }

            return null;
        }
    }
}

First Party Enabled

A boolean flag to enable/disable first party mode.

Default: true

"px_first_party_enabled": true

Sensitive Headers

An array of headers that are not sent to HUMAN servers on API calls.

Default: ['cookie', 'cookies']

"px_sensitive_headers": ["cookie", "cookies", "x-sensitive-header"]

Filter Traffic 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: []

"px_filter_http_methods": ["DELETE"],

Filter Traffic By Route

You may want certain routes to be accessible regardless of HUMAN's detection (filtered routes). Such allowed routes will not be blocked, regardless of the score they receive. A client request to a filtered route will not generate any risk or async activities.

Default: []

px_filter_by_route: ["/contant-us", "/user"]
px_filter_by_route_regex: ["^/contant-us.*", "^\/user\/.*"]

your title goes here

📘

Note

Generally, ^ and $ anchors are a good way of ensuring that a regex matches an entire string.

Filter Traffic By Extension

HUMAN does not enforce static assets such as images and documents. To prevent unnecessary API calls to HUMAN servers and needless computation, the enforcer filters all requests with a valid static file extension. Filtering by extension only applies to HTTP requests with methods GET and HEAD.

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": [".css", ".js", ".png"],

Filter Traffic by User Agent

An array of user agents that are always filtered and not validated by the HUMAN Enforcer.

Default: Empty

"px_filter_by_user_agent": ['testUserAgent/v1.0']

Filter Traffic by IP

An array of IP ranges / IP addresses that are always filtered and not validated by the HUMAN Enforcer.

Default: []

"px_filter_by_ip": ['192.168.10.0/24', '192.168.2.2']

Enforced Routes

Use this feature to define an array of regular expressions to be enforced in the Monitor mode.

You may want certain requests to be enforced by HUMAN, even when the Enforcer is in the Monitor mode. Requests for predefined regular expressions. will go through the full enforcement workflow, and may be blocked based on their score.

Default: []

px_enforced_routes: ["/login", "/user"],
px_enforced_routes_regex: ["^/home$", "^/user.*"],

📘

Note

Generally, ^ and $ anchors are a good way of ensuring that a regex matches an entire string.

Monitored Routes

When in the Active Blocking mode, use this feature to define trusted routes to be monitored only. Such routes will be treated, as if the Enforcer were in the Monitor mode.

For example, you can put newly introduced routes in the Monitor mode to fine-tune them, while continuing to actively protect the rest of your assets.

For more on the difference between the modes, see Module Mode.
Default: Empty array

"px_monitored_routes": ["/home", "/user"],
"px_monitored_routes_regex": ["^/home$", "^/user.*"]

📘

Note

Generally, ^ and $ anchors are a good way of ensuring that a regex matches an entire string.

Additional Activity Handler

A function that allows interaction with the request data collected by HUMAN before the data is returned to the HUMAN servers.
The custom handler class should implement the IAdditionalActivityHandler interface, and its name should be added to the configuration section:

"px_additional_activity_handler"="CustomAdditionalActivityImpl"

The custom logic will reside in the Handle method, making use of the following arguments:

  • HttpRequest httpRequest - The currently running .NET Core application request , contains the HTTP values sent by a client during a Web request.
  • Context context - The Human Enforcer context, containing valuable fields such as Score, UUID, BlockAction etc.
  • EnforcerConfig configuration - The current configuration used by the HumanModule, Contains fields such as BlockingScore.
using human_module;

namespace MyApp
{
    public class CustomAdditionalActivityImpl : IAdditionalActivityHandler
    {
        public void Handle(HttpRequest httpRequest, EnforcerConfig configuration, Context context)
        {
            // Custom additional activity handler logic goes here.
            // The following code is only an example of a possible implementation:
           request.Headers.TryAddWithoutValidation("x-px-score", context.score);
           request.Headers.TryAddWithoutValidation("x-px-rtt", context.riskApiData.riskRtt);
        }
    }
}

Enrich Custom Parameters

With this 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) and their format must align as following: custom_param1, custom_param2, ... , custom_param10.
The custom handler class should implement the ICustomParameters interface, and its name should be added to the configuration section:

"px_enrich_custom_params":"CustomParamsImpl"

The custom logic will reside in the Handle method, making use of the following argument:

  • HttpRequest httpRequest - The currently running .NET Core application request , contains the HTTP values sent by a client during a Web request.
using human_module;

namespace MyApp
{
    public class CustomParametersImpl : ICustomParameters
    {
       public CustomParameters Handle(HttpRequest httpRequest)
        {
            // Custom parameters handler logic goes here.
            // The following code is only an example of a possible implementation:
            CustomParameters customParams = new CustomParameters();
            customParams.custom_param1 = "example";
            customParams.custom_param2 = "example2";
            return customParams;
        }
    }
}

CSS Ref

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

Default: Empty

"px_css_ref": 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css'

JS Ref

Adds a custom JS file by adding px_js_ref directive 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'

Custom Logo

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

Default: Empty

"px_custom_logo": 'https://s.perimeterx.net/logo.png',

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 the advanced blocking response configuration sets to true and 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,
    "altBlockScript": String,
    "customLogo": String
}

Default: true

"px_advanced_blocking_response": true

Custom First Party Sensor Endpoint

For an application with ID PX12345678, the first party sensor endpoint is /12345678/init.js by default. This configuration customizes the entire first party sensor script endpoint. Note that in addition to responding to requests that match this configured route, the enforcer will also proxy first party requests that match the default pattern (/12345678/init.js) and patterns according to the custom prefix (/<px_custom_first_party_prefix>/init.js) if one is configured.

Default: ""

"px_custom_first_party_sensor_endpoint": "/human_sensor/init.js",

Custom First Party Xhr Endpoint

For an application with ID PX12345678, the first party XHR endpoint is /12345678/xhr by default. This configuration customizes the first party XHR endpoint. Note that in addition to responding to requests that match this configured route, the enforcer will also proxy first party requests that match the default pattern (/12345678/xhr/) and patterns according to the custom prefix (/<px_custom_first_party_prefix>/xhr/) if one is configured.

Default: ""

"px_custom_first_party_xhr_endpoint": "/human_xhr",

Custom First Party Captcha Endpoint

For an application with ID PX12345678, the first party captcha endpoint is /12345678/captcha by default. This configuration customizes the first party captcha endpoint. Note that in addition to responding to requests that match this configured route, the enforcer will also proxy first party requests that match the default pattern (/12345678/captcha/) and patterns according to the custom prefix (/<px_custom_first_party_prefix>/captcha/) if one is configured.

Default: ""

"px_custom_first_party_captcha_endpoint": "/human_captcha/captcha.js",

Custom Cookie Header

Allows to set a header name which is used to extract the HUMAN cookies (processed in addition to the Cookie header).

Default: "x-px-cookies"

"px_custom_cookie_header": "x-px-cookies"

px_bypass_monitor_header

Allows you to test an enforcer’s blocking flow while you are still in Monitor Mode. When the header name is set(e.g., x-px-block) and the value is set to 1, when there is a block response (for example from using a User-Agent header with the value of PhantomJS/1.0) the Monitor Mode is bypassed and full block mode is applied. If one of the conditions is missing you will stay in Monitor Mode. This is done per request. To stay in Monitor Mode, set the header value to 0.

The Header Name is configurable using the px_bypass_monitor_header property.

Default: ""

"px_bypass_monitor_header": 'x-px-block',

Updated 12 days ago