> This page is for Applications Protection. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.humansecurity.com/llms.txt. # .NET Core configuration options Each Enforcer has a set of **configuration options** that control the Enforcer's functionality and features. While some are required, many of these are optional configurations that you can use to customize the Enforcer's behavior. You can reference available configurations with this article. Define .NET Core Enforcer configuration in the `HumanConfiguration` section of `appsettings.json`, or another configuration provider bound to `EnforcerConfig`. > **Note** > > While all Enforcers come with the same set of required configurations, the optional configurations available for each may differ. We recommend updating to the latest Enforcer version to ensure you have access to the latest features and configurations. **`Example`** ```json Example ... "HumanConfiguration": { "px_app_id": "", "px_auth_token": "", "px_cookie_secret": "", // Other optional HUMAN configurations } ``` Certain custom logic options can't be set in the configuration file. Instead, implement the corresponding HUMAN interface in your ASP.NET Core project, put your logic in that class' `Handle` method, and set the configuration value to the **class name**. The Enforcer loads that class at startup. The relevant custom options have a Handler implementation example included. Handler classes other than the [custom filter](#px_filter_by_custom_function) must provide a public parameterless constructor. For custom filters, register the class in the ASP.NET Core service container so the Enforcer can resolve it with dependency injection. ## Quick reference #### Basic functionality | Feature name | Key | Type | Default | Description | | :----------------------------------------------------------- | :------------------------------ | :------ | :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Application ID](#px_app_id) | `px_app_id` | String | `""` | HUMAN Application ID | | [Authentication token](#px_auth_token) | `px_auth_token` | String | `""` | HUMAN authentication token | | [Cookie secret](#px_cookie_secret) | `px_cookie_secret` | String | `""` | HUMAN cookie secret | | [Backend domain](#px_backend_url) | `px_backend_url` | String | `https://sapi-{0}.perimeterx.net` | Domain to which HUMAN requests are sent. `{0}` is replaced with the application ID. | | [S2S timeout](#px_s2s_timeout) | `px_s2s_timeout` | Integer | `1000` | Total time, in milliseconds, that the Enforcer will wait for the Risk API request to return before timing out and passing the request | | [Blocking score](#px_blocking_score) | `px_blocking_score` | Integer | `100` | 0-100. The minimum risk score that the Enforcer blocks from. | | [Max user agent length](#px_user_agent_max_length) | `px_user_agent_max_length` | Integer | `8528` | Maximum length of a user agent. The default value is the current value used by the Collector to truncate the user agent. This configuration should only be modified if it's also modified in the Collector | | [Max risk cookie length](#px_risk_cookie_max_length) | `px_risk_cookie_max_length` | Integer | `2048` | Maximum length of a risk cookie. The default value is the current value used by the Collector to truncate the risk cookie. This configuration should only be modified if it's also modified in the Collector | | [Min risk cookie iterations](#px_risk_cookie_min_iterations) | `px_risk_cookie_min_iterations` | Integer | `500` | Minimum number of iterations for the risk cookie V3. | | [Max risk cookie iterations](#px_risk_cookie_max_iterations) | `px_risk_cookie_max_iterations` | Integer | `5000` | Maximum number of iterations for the risk cookie V3. | #### Basic features | Feature name | Key | Type | Default | Description | | :------------------------------------------------ | :------------------------- | :--------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------- | | [Basic logger](#px_logger_severity) | `px_logger_severity` | String | `"error"` | The threshold above which logs on a particular event are received. | | [Header-based logger](#px_logger_auth_token) | `px_logger_auth_token` | String | `""` | Authentication token for HUMAN's logger service for specific headers. | | [Client IP extraction](#px_ip_headers) | `px_ip_headers` | Array of strings | `[]` | Header names that are trusted to contain the true client IP. This is required when there are proxies between the Enforcer and your server. | | [Client IP extraction](#px_ip_extraction_handler) | `px_ip_extraction_handler` | String | `""` | Class name of an `ICustomIpExtraction` implementation used to extract the client IP. | | [Module enable](#px_module_enabled) | `px_module_enabled` | Boolean | `true` | Whether the HUMAN Enforcer module is enabled | | [Module mode](#px_module_mode) | `px_module_mode` | String | `"monitor"` | The HUMAN Enforcer's operation mode | #### Optional | Feature name | Key | Type | Default | Description | | :------------------------------------------------------------------ | :---------------------------------------------------------------------------------- | :--------------- | :--------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | | [Additional activity handler](#additional-activity-handler) | [`px_additional_activity_handler`](#px_additional_activity_handler) | String | `""` | Class name of an `IAdditionalActivityHandler` implementation invoked after the Risk API call and before `page_requested` or `block` activity is sent. | | [Advanced blocking response (ABR)](#advanced-blocking-response-abr) | [`px_advanced_blocking_response_enabled`](#px_advanced_blocking_response_enabled) | Boolean | `true` | Whether the ABR feature is enabled. | | [Bypass monitor header](#bypass-monitor-header) | [`px_bypass_monitor_header`](#px_bypass_monitor_header) | String | `"x-px-block"` | The header name to trigger Enforcer blocking workflow even in [monitor mode](#px_module_mode). | | [Custom cookie header](#custom-cookie-header) | [`px_custom_cookie_header`](#px_custom_cookie_header) | String | `"x-px-cookies"` | A custom name for the header that contains HUMAN's cookies | | [Custom first party endpoints](#custom-first-party-endpoints) | [`px_first_party_enabled`](#px_first_party_enabled) | Boolean | `true` | Whether to enable first party mode. | | [Custom first party endpoints](#custom-first-party-endpoints) | [`px_custom_first_party_prefix`](#px_custom_first_party_prefix) | String | `""` | A custom general prefix for each first party resource that routes the entire first party flow to a custom routing. | | [Custom first party endpoints](#custom-first-party-endpoints) | [`px_custom_first_party_sensor_endpoint`](#px_custom_first_party_sensor_endpoint) | String | `""` | A unique, customized endpoint for the first party Sensor. | | [Custom first party endpoints](#custom-first-party-endpoints) | [`px_custom_first_party_xhr_endpoint`](#px_custom_first_party_xhr_endpoint) | String | `""` | A unique, customized endpoint for first party XHR requests. | | [Custom first party endpoints](#custom-first-party-endpoints) | [`px_custom_first_party_captcha_endpoint`](#px_custom_first_party_captcha_endpoint) | String | `""` | A unique, customized endpoint for first party CAPTCHA requests. | | [Custom first party endpoints](#custom-first-party-endpoints) | [`px_first_party_timeout`](#px_first_party_timeout) | Integer | `4000` | The maximum time in milliseconds to wait for first party requests | | [Custom parameters](#custom-parameters) | [`px_enrich_custom_params`](#px_enrich_custom_params) | String | `""` | Class name of an `ICustomParameters` implementation that returns custom parameters to add to HUMAN activities. | | [Enforced routes](#enforced-routes) | [`px_enforced_routes`](#px_enforced_routes) | Array of strings | `[]` | Path prefixes that should be enforced even in [monitor mode](#px_module_mode). | | [Enforced routes](#enforced-routes) | [`px_enforced_routes_regex`](#px_enforced_routes_regex) | Array of strings | `[]` | Regular expressions for routes that should be enforced even in [monitor mode](#px_module_mode). | | [Filters](#filters) | [`px_filter_by_extension`](#px_filter_by_extension) | Array of strings | All common file extensions. See [details](#px_filter_by_extension) for more information. | An array of file extensions that should be ignored by the Enforcer. | | [Filters](#filters) | [`px_filter_by_http_method`](#px_filter_by_http_method) | Array of strings | `[]` | An array of HTTP methods that should be ignored by the Enforcer. | | [Filters](#filters) | [`px_filter_by_ip`](#px_filter_by_ip) | Array of strings | `[]` | An array of IP addresses or CIDR ranges that should be ignored by the Enforcer. | | [Filters](#filters) | [`px_filter_by_route`](#px_filter_by_route) | Array of strings | `[]` | Path prefixes that should be ignored by the Enforcer. | | [Filters](#filters) | [`px_filter_by_route_regex`](#px_filter_by_route_regex) | Array of strings | `[]` | Regular expressions for routes that should be ignored by the Enforcer. | | [Filters](#filters) | [`px_filter_by_user_agent`](#px_filter_by_user_agent) | Array of strings | `[]` | An array of user agents that should be ignored by the Enforcer. | | [Filters](#filters) | [`px_filter_by_custom_function`](#px_filter_by_custom_function) | String | `""` | Class name of an `ICustomFilter` implementation that returns whether the request should be filtered. | | [HUMAN Challenge customization](#human-challenge-customization) | [`px_css_ref`](#px_css_ref) | String | `""` | A URL to a custom CSS file to customize the [HUMAN Challenge](/applications/customize-challenge-look-feel) block page. | | [HUMAN Challenge customization](#human-challenge-customization) | [`px_js_ref`](#px_js_ref) | String | `""` | A URL to a custom JavaScript file to load with the block page. | | [HUMAN Challenge customization](#human-challenge-customization) | [`px_custom_logo`](#px_custom_logo) | String | `""` | The URL of a custom logo to display on the block page | | [Monitored routes](#monitored-routes) | [`px_monitored_routes`](#px_monitored_routes) | Array of strings | `[]` | Path prefixes that behave as if the Enforcer is in [monitor mode](#px_module_mode) even when actively blocking. | | [Monitored routes](#monitored-routes) | [`px_monitored_routes_regex`](#px_monitored_routes_regex) | Array of strings | `[]` | Regular expressions for routes that behave as if the Enforcer is in [monitor mode](#px_module_mode) even when actively blocking. | | [Sensitive headers removal](#sensitive-headers-removal) | [`px_sensitive_headers`](#px_sensitive_headers) | Array of strings | `["cookie", "cookies"]` | Requests with the specified headers will be considered sensitive and removed from requests sent by the Enforcer. | | [Sensitive routes](#sensitive-routes) | [`px_sensitive_routes`](#px_sensitive_routes) | Array of strings | `[]` | Path prefixes that the Enforcer will always trigger a Risk API call for. | | [Sensitive routes](#sensitive-routes) | [`px_sensitive_routes_regex`](#px_sensitive_routes_regex) | Array of strings | `[]` | Regular expressions for routes that should be considered sensitive. | | [Users identifiers](#users-identifiers) | [`px_jwt_cookie_name`](#px_jwt_cookie_name) | String | `""` | Name of the cookie that contains the JWT token. | | [Users identifiers](#users-identifiers) | [`px_jwt_cookie_user_id_field_name`](#px_jwt_cookie_user_id_field_name) | String | `""` | Name of the field's path that contains the user ID. | | [Users identifiers](#users-identifiers) | [`px_jwt_cookie_additional_field_names`](#px_jwt_cookie_additional_field_names) | Array of strings | `[]` | Additional field paths to extract from the JWT cookie. | | [Users identifiers](#users-identifiers) | [`px_jwt_header_name`](#px_jwt_header_name) | String | `""` | Name of the header that contains the JWT token. | | [Users identifiers](#users-identifiers) | [`px_jwt_header_user_id_field_name`](#px_jwt_header_user_id_field_name) | String | `""` | Name of the field path that contains the user ID. Extracted from the header. | | [Users identifiers](#users-identifiers) | [`px_jwt_header_additional_field_names`](#px_jwt_header_additional_field_names) | Array of strings | `[]` | Additional JWT fields to extract from the header. | ## Required configurations These configurations are necessary for the Enforcer's basic functionality and features. ### Basic functionality configurations **`px_app_id`** `string` — required Your HUMAN Application ID in the form of `PX12AB34CD`. You can copy this value from the [HUMAN Console](https://console.humansecurity.com/) in **Platform Settings > Applications Overview.** If you have multiple applications, make sure to copy the ID of the application you want the Enforcer on. **`Example`** ```json Example { "px_app_id": "" } ``` --- **`px_auth_token`** `string` — required The application's server token needed to authorize with HUMAN's backend. You can copy this value from the [HUMAN Console](https://console.humansecurity.com/) in **Platform Settings > Applications Overview > Click the appropriate application > Server token tab.** **`Example`** ```json Example { "px_auth_token": "" } ``` --- **`px_cookie_secret`** `string` — required The secret used to encrypt and decrypt the risk cookie sent from the HUMAN Sensor. You can copy this value from the [HUMAN Console](https://console.humansecurity.com/) in **Sightline Cyberfraud Defense > Traffic Policy Overview > Click the appropriate application > Click the key > Copy value.** **`Example`** ```json Example { "px_cookie_secret": "" } ``` --- **`px_backend_url`** `string` — required, default: https\://sapi-\{0}.perimeterx.net > **Warning** > > Do not set this value unless directed by your HUMAN Solutions Engineer. 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. **`Example`** ```json Example { "px_backend_url": "https://sapi-{0}.perimeterx.net" } ``` --- **`px_s2s_timeout`** `integer` — required, default: 1000 The total time in milliseconds that the Enforcer will wait for the **Risk API** request to return before timing out and passing the request. **`Example`** ```json Example { "px_s2s_timeout": 2000 } ``` --- **`px_blocking_score`** `integer` — required, default: 100 The minimum risk score that the Enforcer will block. Ranges from 0 (lowest risk) to 100 (highest risk). **`Example`** ```json Example { "px_blocking_score": 100 } ``` --- **`px_user_agent_max_length`** `integer` — required, default: 8528 > **Warning** > > Do not modify this value without consulting your HUMAN Solutions Engineer. 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. **`Example`** ```json Example { "px_user_agent_max_length": 8528 } ``` --- **`px_risk_cookie_max_length`** `integer` — required, default: 2048 The maximum length of the risk cookie. If the value exceeds this length, then validation will fail automatically. **`Example`** ```json Example { "px_risk_cookie_max_length": 2048 } ``` --- **`px_risk_cookie_min_iterations`** `integer` — required, default: 500 The minimum accepted number of iterations for the Risk Cookie V3. **`Example`** ```json Example { "px_risk_cookie_min_iterations": 500 } ``` --- **`px_risk_cookie_max_iterations`** `integer` — required, default: 5000 The maximum accepted number of iterations for the Risk Cookie V3. **`Example`** ```json Example { "px_risk_cookie_max_iterations": 5000 } ``` --- ### Basic feature configurations **`px_logger_severity`** `"none" | "error" | "debug"` — required, default: "error" 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`](#px_logger_auth_token) for a header-based alternative. **`Example`** ```json Example { "px_logger_severity": "debug" } ``` --- **`px_logger_auth_token`** `string` — default: "" An alternative to the [basic logger](#px_logger_severity) 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](/applications/human-customer-support) to receive your token. **`Example`** ```json Example { "px_logger_auth_token": "" } ``` --- **`px_ip_headers`** `string[]` — required, default: \[] 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`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.connectioninfo.remoteipaddress) by default. If [`px_ip_extraction_handler`](#px_ip_extraction_handler) returns a value, that value is used instead of these headers. **`Example`** ```json Example { "px_ip_headers": ["true-ip", "true-client-ip"] } ``` --- **`px_ip_extraction_handler`** `string` — default: "" 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`](#px_ip_headers), then to `HttpContext.Connection.RemoteIpAddress`. The custom logic resides in the `Handle` method: * `httpRequest`: The current ASP.NET Core [`HttpRequest`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.httprequest) **Returns:** The client IP string, or `null` to fall back to header and connection-based extraction. **`appsettings.json implementation`** ```json title="appsettings.json implementation" { "px_ip_extraction_handler": "CustomIpExtractionImpl" } ``` **`Handler implementation`** ```csharp Handler implementation using human_module; using Microsoft.AspNetCore.Http; 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; } } } ``` --- **`px_module_enabled`** `boolean` — required, default: true Whether the Enforcer module is enabled. * `true`: Enable the module * `false`: Disable the module **`Example`** ```json Example { "px_module_enabled": true } ``` --- **`px_module_mode`** `"monitor" | "active_blocking"` — required, default: monitor 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](#enforced-routes). * `active_blocking`: The Enforcer will return block responses as needed. **`Example`** ```json Example { "px_module_mode": "active_blocking" } ``` --- ## Optional configurations These configurations aren't required, but you can use them to further customize the Enforcer's behavior. ### Additional activity handler **`px_additional_activity_handler`** `string` — default: "" 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`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.httprequest) * `configuration`: The current `EnforcerConfig` * `context`: The Enforcer `Context`, including fields such as `score`, `uuid`, `blockAction`, and `riskApiData` **Returns:** `void` **`appsettings.json implementation`** ```json title="appsettings.json implementation" { "px_additional_activity_handler": "CustomAdditionalActivityImpl" } ``` **`Handler implementation`** ```csharp Handler implementation using human_module; using Microsoft.AspNetCore.Http; namespace MyApp { public class CustomAdditionalActivityImpl : IAdditionalActivityHandler { public void Handle(HttpRequest httpRequest, EnforcerConfig configuration, Context context) { httpRequest.Headers["x-px-score"] = context.score.ToString(); httpRequest.Headers["x-px-rtt"] = context.riskApiData.riskRtt.ToString(); } } } ``` --- ### Advanced blocking response (ABR) **`px_advanced_blocking_response_enabled`** `boolean` — default: true 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)](/applications/set-challenge-configurations#enable-challenge-configurations#custom-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: **`Example`** ```json Example { "px_advanced_blocking_response_enabled": true } ``` --- ### Bypass monitor header **`px_bypass_monitor_header`** `string` — default: x-px-block 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](#px_module_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`. **`Example`** ```json Example { "px_bypass_monitor_header": "x-px-block" } ``` --- ### Custom cookie header **`px_custom_cookie_header`** `string` — default: x-px-cookies 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. **`Example`** ```json Example { "px_custom_cookie_header": "x-px-cookies" } ``` --- ### Custom first party endpoints These configurations let you use the Enforcer as a proxy for HUMAN servers and serve content to the browser from a first party endpoint. These are particularly useful when browser or extension restrictions that block JavaScript requests to other domains, such as adblockers, prevent the HUMAN **Sensor** from making requests to HUMAN's backend. When this happens, it significantly limits HUMAN's detection capabilities, so we recommend enabling these configurations to maintain full detection capabilities. **`px_first_party_enabled`** `boolean` — default: true Whether to enable first party mode for Bot Defender or Sightline Cyberfraud Defense. **`Example`** ```json Example { "px_first_party_enabled": true } ``` --- **`px_custom_first_party_prefix`** `string` 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: * `//init.js` * `//xhr/*` * `//captcha/*` If empty, the configuration will use the default as described above. **`Example`** ```json Example { "px_custom_first_party_prefix": "/custom-prefix" } ``` --- **`px_custom_first_party_sensor_endpoint`** `string` 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. **`Example`** ```json Example { "px_custom_first_party_sensor_endpoint": "/human_sensor/init.js" } ``` --- **`px_custom_first_party_xhr_endpoint`** `string` 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. **`Example`** ```json Example { "px_custom_first_party_xhr_endpoint": "/human_xhr" } ``` --- **`px_custom_first_party_captcha_endpoint`** `string` 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. **`Example`** ```json Example { "px_custom_first_party_captcha_endpoint": "/human_captcha/captcha.js" } ``` --- **`px_first_party_timeout`** `integer` — default: 4000 The maximum time in milliseconds to wait for first party requests. **`Example`** ```json Example { "px_first_party_timeout": 4000 } ``` --- ### Custom parameters These configurations are related to [custom parameters](/applications/set-custom-parameters). **`px_enrich_custom_params`** `string` — default: "" 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`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.httprequest) **Returns:** A `CustomParameters` object. **`appsettings.json implementation`** ```json title="appsettings.json implementation" { "px_enrich_custom_params": "CustomParametersImpl" } ``` **`Handler implementation`** ```csharp Handler implementation using human_module; using Microsoft.AspNetCore.Http; namespace MyApp { public class CustomParametersImpl : ICustomParameters { public CustomParameters Handle(HttpRequest httpRequest) { CustomParameters customParams = new CustomParameters(); customParams.custom_param1 = "hardcoded value"; customParams.custom_param2 = httpRequest.Headers["header-name"].ToString(); return customParams; } } } ``` --- ### Enforced routes These configurations let you define specific routes that should be enforced by HUMAN when the Enforcer is in [monitor mode](#px_module_mode). These routes will always be subject to the full Enforcer workflow, including blocking requests if necessary. Primitive string values are treated as path prefixes. For example, `/login` also matches `/login/callback`. **`px_enforced_routes`** `array of strings` — default: \[] Routes or prefixes that should be enforced by HUMAN even when the Enforcer is in [monitor mode](#px_module_mode). **`Example`** ```json Example { "px_enforced_routes": ["/login", "/checkout"] } ``` --- **`px_enforced_routes_regex`** `array of strings` — default: \[] Regular expressions for routes that should be ignored by the Enforcer. **`Example`** ```json Example { "px_enforced_routes_regex": ["^/home$", "^/user.*"] } ``` --- ### Filters These configurations let you filter out certain requests or assets from the Enforcer. These values will be ignored by the Enforcer and will never be blocked. **`px_filter_by_extension`** `array of strings` — 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' ] 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. > **Note** > > Filtering by extension only applies to GET and HEAD HTTP methods. **`Example`** ```json Example { "px_filter_by_extension": [".css", ".js", ".png"] } ``` --- **`px_filter_by_http_method`** `array of strings` — default: \[] Filters out requests with the specified HTTP method to avoid unnecessary traffic in the Enforcer verification flow. **`Example`** ```json Example { "px_filter_by_http_method": ["OPTIONS", "DELETE"] } ``` --- **`px_filter_by_ip`** `array of strings` — default: \[] Filters out requests with the specified IP address to avoid unnecessary traffic in the Enforcer verification flow. **`Example`** ```json Example { "px_filter_by_ip": ["1.1.1.1", "2.2.2.2/8"] } ``` --- **`px_filter_by_route`** `array of strings` — default: \[] 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`. **`Example`** ```json Example { "px_filter_by_route": ["/contact-us", "/static"] } ``` --- **`px_filter_by_route_regex`** `array of strings` — default: \[] 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. **`Example`** ```json Example { "px_filter_by_route_regex": ["^/contact-us.*", "^/user/.*"] } ``` --- **`px_filter_by_user_agent`** `array of strings` — default: \[] 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. **`Example`** ```json Example { "px_filter_by_user_agent": ["testUserAgent/v1.0", "ExampleBot"] } ``` --- **`px_filter_by_custom_function`** `string` — default: "" > **Warning** > > This configuration is meant for cases that require more complex logic. We recommend you use the other default filters available for most cases. 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`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.httprequest) **Returns:** `bool` **`appsettings.json implementation`** ```json title="appsettings.json implementation" { "px_filter_by_custom_function": "CustomFilterImpl" } ``` **`Program.cs registration`** ```csharp title="Program.cs registration" builder.Services.AddTransient(); ``` **`Handler implementation`** ```csharp Handler implementation using human_module; using Microsoft.AspNetCore.Http; using Microsoft.Extensions.Logging; namespace MyApp { public class CustomFilterImpl : ICustomFilter { private readonly ILogger _logger; public CustomFilterImpl(ILogger logger) { _logger = logger; } public bool Handle(HttpRequest httpRequest) { httpRequest.Headers.TryGetValue("x-environment", out var environment); if (environment == "test") { _logger.LogInformation("Filtering test traffic for path: {Path}", httpRequest.Path); return true; } return false; } } } ``` --- ### HUMAN Challenge customization These configurations let you customize the [HUMAN Challenge block page](/applications/create-a-human-challenge). **`px_css_ref`** `string` A way to include a custom CSS file to the block page. **`Example`** ```json Example { "px_css_ref": "https://www.example.com/custom_style.css" } ``` --- **`px_js_ref`** `string` A way to include custom JavaScript to the block page. This script will run after the default JavaScript scripts. **`Example`** ```json Example { "px_js_ref": "https://www.example.com/custom_script.js" } ``` --- **`px_custom_logo`** `string` — default: "" Adds a custom logo to the [HUMAN Challenge](/applications/create-a-human-challenge) block page via URL. **`Example`** ```json Example { "px_custom_logo": "https://www.example.com/custom_logo.png" } ``` --- ### Monitored routes These configurations let you specify routes that should be monitored by the Enforcer, which means their requests will never be blocked, even when the Enforcer is in [`active_blocking`](#px_module_mode) mode. This means that these routes will go through the full Enforcer workflow and generate risk and async activities, but all block activities will only be simulated blocks on these routes. Primitive string values are treated as path prefixes. For example, `/login` also matches `/login/callback`. **`px_monitored_routes`** `array of strings` — default: \[] A list of endpoints to be monitored rather than blocked by the Enforcer, even when the Enforcer is in [`active_blocking`](#px_module_mode) mode. **`Example`** ```json Example { "px_monitored_routes": ["/home", "/preview"] } ``` --- **`px_monitored_routes_regex`** `array of strings` — default: \[] Regular expressions for routes that should be treated as monitored even when the Enforcer is in [`active_blocking`](#px_module_mode) mode. **`Example`** ```json Example { "px_monitored_routes_regex": ["^/home$", "^/user.*"] } ``` --- ### Sensitive headers removal **`px_sensitive_headers`** `string[]` — default: \["cookie", "cookies"] 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. **`Example`** ```json Example { "px_sensitive_headers": ["cookie", "cookies", "x-sensitive-token"] } ``` --- ### Sensitive routes These configurations let you specify certain routes that need particularly stringent protection from attacks, such as endpoints that execute payments or handle personal information. Sensitive routes will always trigger a **Risk API** call even if the request contains a valid, unexpired, low-score cookie. Primitive string values are treated as path prefixes. For example, `/login` also matches `/login/callback`. > **Note** > > Requests with high-score cookies won't send a Risk API call. **`px_sensitive_routes`** `array of strings` — default: \[] A list of prefixes for all routes that should be considered sensitive. **`Example`** ```json Example { "px_sensitive_routes": ["/login", "/checkout"] } ``` --- **`px_sensitive_routes_regex`** `array of strings` — default: \[] A list of regular expressions for all routes that should be considered sensitive. **`Example`** ```json Example { "px_sensitive_routes_regex": ["^/login$", "^/api/.*/checkout$"] } ``` --- ### Users identifiers These configurations let you extract user identifiers from a JWT carried on the request either in a cookie or a header. They're closely related to the [Accounts](/applications/about-the-accounts-overview-dashboard) and [Account Takeover or Fake Account](/applications/about-the-recent-attacks-dashboard) features in Sightline Cyberfraud Defense. The Enforcer reads the JWT from the configured cookie first, then from the configured header if cookie extraction does not succeed. Field names support dot notation for nested JWT claim (for example, `product.id`). **`px_jwt_cookie_name`** `string` — default: "" The name of the cookie that contains the JWT token that HUMAN should extract user identifiers from. **`Example`** ```json Example { "px_jwt_cookie_name": "auth" } ``` --- **`px_jwt_cookie_user_id_field_name`** `string` — default: "" The field name in the JWT object, extracted from the JWT cookie, that contains the user ID to be extracted and reported. **`Example`** ```json Example { "px_jwt_cookie_user_id_field_name": "nameID" } ``` --- **`px_jwt_cookie_additional_field_names`** `string[]` — default: \[] The field names in the JWT object, extracted from the JWT cookie, that should be extracted and reported in addition to the user ID. **`Example`** ```json Example { "px_jwt_cookie_additional_field_names": ["exp", "iss"] } ``` --- **`px_jwt_header_name`** `string` — default: "" The name of the header that contains the JWT token that HUMAN should extract user identifiers from. **`Example`** ```json Example { "px_jwt_header_name": "x-jwt-authorization" } ``` --- **`px_jwt_header_user_id_field_name`** `string` — default: "" The field name in the JWT object, extracted from the JWT header, that contains the user ID to be extracted and reported. **`Example`** ```json Example { "px_jwt_header_user_id_field_name": "sub" } ``` --- **`px_jwt_header_additional_field_names`** `string[]` — default: \[] The field names in the JWT object, extracted from the JWT header, that should be extracted and reported in addition to the user ID. **`Example`** ```json Example { "px_jwt_header_additional_field_names": ["exp", "iss"] } ``` ---