.NET Core configuration options

Your HUMAN Application ID in the form of PX12AB34CD. You can copy this value from the HUMAN Console in Platform Settings > Applications Overview. If you have multiple applications, make sure to copy the ID of the application you want the Enforcer on.

1
{
2
    "px_app_id": "<APP_ID>"
3
}

The application’s server token needed to authorize with HUMAN’s backend. You can copy this value from the HUMAN Console in Platform Settings > Applications Overview > Click the appropriate application > Server token tab.

1
{
2
    "px_auth_token": "<AUTH_TOKEN>"
3
}

The secret used to encrypt and decrypt the risk cookie sent from the HUMAN Sensor. You can copy this value from the HUMAN Console in Sightline Cyberfraud Defense > Traffic Policy Overview > Click the appropriate application > Click the key > Copy value.

1
{
2
    "px_cookie_secret": "<COOKIE_SECRET>"
3
}

The base URL for the HUMAN SAPI (Risk API and related calls). If empty, the Enforcer uses the default host for your Application ID.

The default value uses {0} as a placeholder for your application ID.

1
{
2
    "px_backend_url": "https://sapi-{0}.perimeterx.net"
3
}

The total time in milliseconds that the Enforcer will wait for the Risk API request to return before timing out and passing the request.

1
{
2
    "px_s2s_timeout": 2000
3
}

The minimum risk score that the Enforcer will block. Ranges from 0 (lowest risk) to 100 (highest risk).

1
{
2
    "px_blocking_score": 100
3
}

The maximum length of the User-Agent header. If the user agent header value exceeds this length, it will be truncated to this length prior to processing.

1
{
2
    "px_user_agent_max_length": 8528
3
}

The maximum length of the risk cookie. If the value exceeds this length, then validation will fail automatically.

1
{
2
    "px_risk_cookie_max_length": 2048
3
}

The minimum accepted number of iterations for the Risk Cookie V3.

1
{
2
    "px_risk_cookie_min_iterations": 500
3
}

The maximum accepted number of iterations for the Risk Cookie V3.

1
{
2
    "px_risk_cookie_max_iterations": 5000
3
}

The severity at which the logger will output logs.

• none: The logger will not generate any logs.
• error: The logger will only generate logs on fatal errors.
• debug: The logger will generate detailed logs for debugging purposes. Not recommended for production environments.

See px_logger_auth_token for a header-based alternative.

1
{
2
    "px_logger_severity": "debug"
3
}

An alternative to the basic logger configuration. This sends Enforcer logs to HUMAN’s logging service if a specific header is present on the request. This is particularly useful for expedited debugging, diagnosis, and resolution of any integration or Enforcer-related issues.

Contact HUMAN to recieve your token.

1
{
2
    "px_logger_auth_token": "<LOGGER_AUTH_TOKEN>"
3
}

An array of header names that are trusted to contain the true client IP. Headers are traversed in the order they’re listed, and the first header value will always be used as the client IP.

Taken from HttpContext.Connection.RemoteIpAddress by default.

If px_ip_extraction_handler returns a value, that value is used instead of these headers.

1
{
2
    "px_ip_headers": ["true-ip", "true-client-ip"]
3
}

A custom class that extracts the client IP. Set this value to the class name of an ICustomIpExtraction implementation. When the handler returns a non-null value, that value is used as the client IP. Otherwise, the Enforcer falls back to px_ip_headers, then to HttpContext.Connection.RemoteIpAddress.

The custom logic resides in the Handle method:

• httpRequest: The current ASP.NET Core HttpRequest

Returns: The client IP string, or null to fall back to header and connection-based extraction.

1
{
2
    "px_ip_extraction_handler": "CustomIpExtractionImpl"
3
}

Whether the Enforcer module is enabled.

• true: Enable the module
• false: Disable the module

1
{
2
    "px_module_enabled": true
3
}

The Enforcer’s operation mode.

• monitor: The Enforcer performs all functions without returning block responses. Useful for analyzing and adjusting Enforcer behavior without serving block pages to end users. If you have routes that must have enforcement at all times, see Enforced routes.
• active_blocking: The Enforcer will return block responses as needed.

1
{
2
    "px_module_mode": "active_blocking"
3
}

A custom class the Enforcer invokes after the Risk API call and before it sends page_requested or block activity. A common use case is to set the score as a request header so the application can read it.

Set this value to the class name of an IAdditionalActivityHandler implementation. The class must provide a public parameterless constructor. The Enforcer calls Handle with:

Parameters:

• httpRequest: The current ASP.NET Core HttpRequest
• configuration: The current EnforcerConfig
• context: The Enforcer Context, including fields such as score, uuid, blockAction, and riskApiData

Returns: void

1
{
2
    "px_additional_activity_handler": "CustomAdditionalActivityImpl"
3
}

In specific cases such as XHR post requests, a full CAPTCHA page render might not be an option. In such cases, the Advanced Blocking Response (ABR) returns a JSON object containing all the information needed to render a customized CAPTCHA challenge implementation such as a popup modal, a section on the page, etc. This provides more flexibility and customizability in displaying the CAPTCHA challenge.

• true: Enable ABR
• false: Disable ABR

ABR is used when this configuration is true and the request Accept header includes application/json. The Enforcer then returns a JSON block payload instead of an HTML challenge page. A sample JSON response appears as follows:

1
{
2
    "px_advanced_blocking_response_enabled": true
3
}

Activates the full blocking flow to verify the flow works as expected if the specified header is present on the request with a value of 1. Often used to test the Enforcer block workflow during monitor mode, where the Enforcer usually collects data without blocking user requests, before switching to active_blocking. Requests with this header will go through the entire blocking workflow despite being in monitor mode.

To disable blocking behavior on the specified header, set the value to 0.

1
{
2
    "px_bypass_monitor_header": "x-px-block"
3
}

By default, the Enforcer extracts HUMAN cookies from the Cookie header. However, if these cookies are transferred on a different header, then that header’s name must be provided with this configuration.

1
{
2
    "px_custom_cookie_header": "x-px-cookies"
3
}

Whether to enable first party mode for Bot Defender or Sightline Cyberfraud Defense.

1
{
2
    "px_first_party_enabled": true
3
}

Sets a custom prefix for first party routes to use in addition to the default prefix. By default, first party endpoints always begin with the Application ID without the initial “PX”. For example, if the ID is PX12345678, then all first party routes will take the form /12345678/*.

When configured, the Enforcer will respond to first party requests with endpoints matching the following patterns:

• /<px_custom_first_party_prefix>/init.js
• /<px_custom_first_party_prefix>/xhr/*
• /<px_custom_first_party_prefix>/captcha/*

If empty, the configuration will use the default as described above.

1
{
2
    "px_custom_first_party_prefix": "/custom-prefix"
3
}

Customizes the entire first party Sensor script endpoint. By default, for an Application ID PX12345678, the first party endpoint is /12345678/init.js.

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.

1
{
2
    "px_custom_first_party_sensor_endpoint": "/human_sensor/init.js"
3
}

Customizes the first party XHR endpoint. By default, for an Application ID PX12345678, the first party XHR endpoint is /12345678/xhr.

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.

1
{
2
    "px_custom_first_party_xhr_endpoint": "/human_xhr"
3
}

Customizes the first party CAPTCHA endpoint. By default, for an Application ID PX12345678, the first party CAPTCHA endpoint is /12345678/captcha.

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.

1
{
2
    "px_custom_first_party_captcha_endpoint": "/human_captcha/captcha.js"
3
}

The maximum time in milliseconds to wait for first party requests.

1
{
2
    "px_first_party_timeout": 4000
3
}

Enriches activities sent from the Enforcer to HUMAN with additional custom parameters. This data can include user information, session IDs, or other data that HUMAN should have access to. There is a limit of 10 custom parameters (custom_param1 through custom_param10).

Set this value to the class name of an ICustomParameters implementation. The class must provide a public parameterless constructor.

Parameters:

• httpRequest: The current ASP.NET Core HttpRequest

Returns: A CustomParameters object.

1
{
2
    "px_enrich_custom_params": "CustomParametersImpl"
3
}

Routes or prefixes that should be enforced by HUMAN even when the Enforcer is in monitor mode.

1
{
2
    "px_enforced_routes": ["/login", "/checkout"]
3
}

Regular expressions for routes that should be ignored by the Enforcer.

1
{
2
    "px_enforced_routes_regex": ["^/home$", "^/user.*"]
3
}

Filters out requests with the specified file extension. By default, HUMAN doesn’t enforce static assets such as images and documents to minimize unncessary API calls and computation, but you can configure this list at any time.

1
{
2
    "px_filter_by_extension": [".css", ".js", ".png"]
3
}

Filters out requests with the specified HTTP method to avoid unnecessary traffic in the Enforcer verification flow.

1
{
2
    "px_filter_by_http_method": ["OPTIONS", "DELETE"]
3
}

Filters out requests with the specified IP address to avoid unnecessary traffic in the Enforcer verification flow.

1
{
2
    "px_filter_by_ip": ["1.1.1.1", "2.2.2.2/8"]
3
}

Filters out requests with the specified route to avoid unnecessary traffic in the Enforcer verification flow. Requests to these specified routes will never be blocked regardless of their risk score and will never generate risk or async activities. Primitive string values are treated as path prefixes. For example, /login also matches /login/callback.

1
{
2
    "px_filter_by_route": ["/contact-us", "/static"]
3
}

Regular expressions for routes that should be filtered to avoid unnecessary traffic in the Enforcer verification flow. Requests to these specified routes will never be blocked regardless of their risk score and will never generate risk or async activities.

1
{
2
    "px_filter_by_route_regex": ["^/contact-us.*", "^/user/.*"]
3
}

Filters out requests with the specified user agent to avoid unnecessary traffic in the Enforcer verification flow. Primitive string values are case-sensitive and require an exact user-agent string.

1
{
2
    "px_filter_by_user_agent": ["testUserAgent/v1.0", "ExampleBot"]
3
}

A custom class that lets you define which requests should be filtered. Set this value to the class name of an ICustomFilter implementation. Return true to filter the request (Bot Defender detection is not applied). Return false to continue enforcement.

Register the implementation in the ASP.NET Core service container so the Enforcer can resolve it with dependency injection. If the type is not registered, the Enforcer falls back to a public parameterless constructor.

Parameters:

• httpRequest: The current ASP.NET Core HttpRequest

Returns: bool

1
{
2
    "px_filter_by_custom_function": "CustomFilterImpl"
3
}

A way to include a custom CSS file to the block page.

1
{
2
    "px_css_ref": "https://www.example.com/custom_style.css"
3
}

A way to include custom JavaScript to the block page. This script will run after the default JavaScript scripts.

1
{
2
    "px_js_ref": "https://www.example.com/custom_script.js"
3
}

Adds a custom logo to the HUMAN Challenge block page via URL.

1
{
2
    "px_custom_logo": "https://www.example.com/custom_logo.png"
3
}

A list of endpoints to be monitored rather than blocked by the Enforcer, even when the Enforcer is in active_blocking mode.

1
{
2
    "px_monitored_routes": ["/home", "/preview"]
3
}

Regular expressions for routes that should be treated as monitored even when the Enforcer is in active_blocking mode.

1
{
2
    "px_monitored_routes_regex": ["^/home$", "^/user.*"]
3
}

Specifies certain headers that should not be forwarded to any other destination, including the HUMAN Detector. While HUMAN’s detection system will continue to use these headers to determine whether to block or not, the specified headers won’t be forwarded from the Enforcer, won’t appear in Enforcer activities, and won’t be sent to any other IP if the Enforcer acts as a proxy.

1
{
2
    "px_sensitive_headers": ["cookie", "cookies", "x-sensitive-token"]
3
}

A list of prefixes for all routes that should be considered sensitive.

1
{
2
    "px_sensitive_routes": ["/login", "/checkout"]
3
}

A list of regular expressions for all routes that should be considered sensitive.

1
{
2
    "px_sensitive_routes_regex": ["^/login$", "^/api/.*/checkout$"]
3
}

The name of the cookie that contains the JWT token that HUMAN should extract user identifiers from.

1
{
2
    "px_jwt_cookie_name": "auth"
3
}

The field name in the JWT object, extracted from the JWT cookie, that contains the user ID to be extracted and reported.

1
{
2
    "px_jwt_cookie_user_id_field_name": "nameID"
3
}

The field names in the JWT object, extracted from the JWT cookie, that should be extracted and reported in addition to the user ID.

1
{
2
    "px_jwt_cookie_additional_field_names": ["exp", "iss"]
3
}

The name of the header that contains the JWT token that HUMAN should extract user identifiers from.

1
{
2
    "px_jwt_header_name": "x-jwt-authorization"
3
}

The field name in the JWT object, extracted from the JWT header, that contains the user ID to be extracted and reported.

1
{
2
    "px_jwt_header_user_id_field_name": "sub"
3
}

The field names in the JWT object, extracted from the JWT header, that should be extracted and reported in addition to the user ID.

1
{
2
    "px_jwt_header_additional_field_names": ["exp", "iss"]
3
}