> 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. # ASP.NET 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. Set ASP.NET Enforcer configurations as XML attributes in the `pxModuleConfigurationSection` element of your application's `web.config`. > **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. Comma-delimited list attributes such as [`sensitiveRoutes`](#sensitiveroutes) or [`ipWhitelist`](#ipwhitelist) map to .NET `StringCollection` values. Custom logic options use a **class name** string: implement the corresponding HUMAN interface, put your logic in that class's `Handle` method, and set the configuration attribute to the class name so the Enforcer can load it. ## Quick reference #### Basic functionality | Feature name | Key | Type | Default | Description | | :-------------------------------- | :-------------- | :------ | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | | [Application ID](#appid) | `appId` | String | — | HUMAN Application ID | | [Authentication token](#apitoken) | `apiToken` | String | `""` | HUMAN authentication token | | [Cookie secret](#cookiekey) | `cookieKey` | String | — | HUMAN cookie secret | | [Backend domain](#baseuri) | `baseUri` | String | `https://sapi-{0}.perimeterx.net` | Domain to which HUMAN requests are sent. `{0}` is replaced with the application ID. | | [S2S timeout](#apitimeout) | `apiTimeout` | Integer | `1500` | 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](#blockingscore) | `blockingScore` | Integer | `100` | 0-100. The minimum risk score that the Enforcer blocks from. | #### Basic features | Feature name | Key | Type | Default | Description | | :-------------------------------------- | :--------------- | :------ | :------ | :------------------------------------------------------------------------------------------------------------------------- | | [Client IP extraction](#socketipheader) | `socketIpHeader` | String | `""` | Header name trusted to contain the true client IP. Required when proxies sit between the client and the Enforcer. | | [Module enable](#enabled) | `enabled` | Boolean | `true` | Whether the HUMAN Enforcer module is enabled | | [Module mode](#monitormode) | `monitorMode` | Boolean | `true` | When `true`, the Enforcer inspects traffic without blocking. When `false`, the Enforcer returns block responses as needed. | #### Optional | Feature name | Key | Type | Default | Description | | :-------------------------------------------------------------- | :---------------------------------------------------------------------------------- | :------------------------------- | :---------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | | [Bypass monitor header](#bypass-monitor-header) | [`bypassMonitorHeader`](#bypassmonitorheader) | String | `""` | Header name that triggers the Enforcer blocking workflow even in [monitor mode](#monitormode). | | [Credentials Intelligence](#credentials-intelligence) | [`loginCredentialsExtractionEnabled`](#logincredentialsextractionenabled) | Boolean | `false` | Whether to enable Credentials Intelligence. | | [Credentials Intelligence](#credentials-intelligence) | [`loginCredentialsExtraction`](#logincredentialsextraction) | String (JSON array) | `""` | JSON array of credential endpoint configurations. See [details](#logincredentialsextraction). | | [Credentials Intelligence](#credentials-intelligence) | [`ciVersion`](#civersion) | String | `"v2"` | Credentials Intelligence protocol version. | | [Credentials Intelligence](#credentials-intelligence) | [`compromisedCredentialsHeader`](#compromisedcredentialsheader) | String | `"px-compromised-credentials"` | Header name set on the incoming request when credentials are compromised. | | [Credentials Intelligence](#credentials-intelligence) | [`additionalS2SActivityHeaderEnabled`](#additionals2sactivityheaderenabled) | Boolean | `false` | Whether to attach the `additional_s2s` payload and URL as headers instead of sending the activity automatically. | | [Credentials Intelligence](#credentials-intelligence) | [`sendRawUsernameOnAdditionalS2SActivity`](#sendrawusernameonadditionals2sactivity) | Boolean | `false` | Whether to send the raw username on the `additional_s2s` activity. | | [Credentials Intelligence](#credentials-intelligence) | [`loginSuccessfulReportingMethod`](#loginsuccessfulreportingmethod) | String | `""` | How the Enforcer detects a successful login for automatic `additional_s2s` activities. | | [Credentials Intelligence](#credentials-intelligence) | [`loginSuccessfulStatus`](#loginsuccessfulstatus) | Comma-delimited list of integers | `""` | HTTP status codes that indicate a successful login when using the `status` reporting method. | | [Credentials Intelligence](#credentials-intelligence) | [`loginSuccessfulBodyRegex`](#loginsuccessfulbodyregex) | String | `""` | Body regular expression that indicates a successful login when using the `body` reporting method. | | [Credentials Intelligence](#credentials-intelligence) | [`loginSuccessfulHeaderName`](#loginsuccessfulheadername) | String | `""` | Response header name that indicates a successful login when using the `header` reporting method. | | [Credentials Intelligence](#credentials-intelligence) | [`loginSuccessfulHeaderValue`](#loginsuccessfulheadervalue) | String | `""` | Response header value that indicates a successful login when using the `header` reporting method. | | [Credentials Intelligence](#credentials-intelligence) | [`customCredentialsExtractionHandler`](#customcredentialsextractionhandler) | String | `""` | Class name of an `ICredentialsExtractionHandler` implementation. | | [Credentials Intelligence](#credentials-intelligence) | [`customLoginSuccessfulHandler`](#customloginsuccessfulhandler) | String | `""` | Class name of an `ILoginSuccessfulHandler` implementation. | | [Custom block page](#custom-block-page) | [`customBlockUrl`](#customblockurl) | String | `""` | URL of a custom block page HTML file. | | [Custom block page](#custom-block-page) | [`redirectOnCustomUrl`](#redirectoncustomurl) | Boolean | `false` | Whether to redirect to [`customBlockUrl`](#customblockurl) with a `307` response instead of returning `403` with an injected block page. | | [Custom cookie header](#custom-cookie-header) | [`customCookieHeader`](#customcookieheader) | String | `"x-px-cookies"` | Header name that may contain HUMAN cookies instead of the `Cookie` header. | | [Custom parameters](#custom-parameters) | [`customParametersHandler`](#customparametershandler) | String | `""` | Class name of an `ICustomParametersHandler` implementation that returns custom parameters for HUMAN activities. | | [Custom user agent header](#custom-user-agent-header) | [`useragentOverride`](#useragentoverride) | String | `""` | Header name from which to read the client user agent. | | [Custom verification handler](#custom-verification-handler) | [`customVerificationHandler`](#customverificationhandler) | String | `""` | Class name of an `IVerificationHandler` implementation that customizes post-risk behavior. | | [Enforced routes](#enforced-routes) | [`mitigationUrls`](#mitigationurls) | Comma-delimited list of strings | `""` | Exact request paths (without a leading `/`) that should be enforced even in [monitor mode](#monitormode). | | [Enforced routes](#enforced-routes) | [`enforceSpecificRoutes`](#enforcespecificroutes) | Comma-delimited list of strings | `""` | Path prefixes to enforce. When non-empty, all other routes are skipped. | | [Filters](#filters) | [`fileExtWhitelist`](#fileextwhitelist) | Comma-delimited list of strings | Common static extensions. See [details](#fileextwhitelist). | File extensions ignored by the Enforcer. | | [Filters](#filters) | [`ipWhitelist`](#ipwhitelist) | Comma-delimited list of strings | `""` | IP addresses or CIDR ranges ignored by the Enforcer. | | [Filters](#filters) | [`routesWhitelist`](#routeswhitelist) | Comma-delimited list of strings | `""` | Path prefixes ignored by the Enforcer. | | [Filters](#filters) | [`useragentsWhitelist`](#useragentswhitelist) | Comma-delimited list of strings | `""` | Exact user-agent strings ignored by the Enforcer. | | [First party](#first-party) | [`firstPartyEnabled`](#firstpartyenabled) | Boolean | `true` | Whether to enable first-party mode for the Sensor and CAPTCHA. | | [First party](#first-party) | [`firstPartyXhrEnabled`](#firstpartyxhrenabled) | Boolean | `true` | Whether to reverse-proxy first-party XHR activity requests. | | [HUMAN Challenge customization](#human-challenge-customization) | [`cssRef`](#cssref) | String | `""` | URL of a custom CSS file for the [HUMAN Challenge](/applications/customize-challenge-look-feel) block page. | | [HUMAN Challenge customization](#human-challenge-customization) | [`jsRef`](#jsref) | String | `""` | URL of a custom JavaScript file to load with the block page. | | [HUMAN Challenge customization](#human-challenge-customization) | [`customLogo`](#customlogo) | String | `""` | URL of a custom logo to display on the block page. | | [Monitored routes](#monitored-routes) | [`monitoredRoutes`](#monitoredroutes) | Comma-delimited list of strings | `""` | Exact request paths (without a leading `/`) treated as monitor mode even when [`monitorMode`](#monitormode) is `false`. | | [Send activities](#send-activities) | [`sendPageActivities`](#sendpageactivities) | Boolean | `true` | Whether to send asynchronous `page_requested` activities. | | [Send activities](#send-activities) | [`sendBlockActivities`](#sendblockactivities) | Boolean | `true` | Whether to send asynchronous `block` activities. | | [Sensitive headers removal](#sensitive-headers-removal) | [`sensitiveHeaders`](#sensitiveheaders) | Comma-delimited list of strings | `"cookie,cookies"` | Header names stripped from requests sent by the Enforcer. | | [Sensitive routes](#sensitive-routes) | [`sensitiveRoutes`](#sensitiveroutes) | Comma-delimited list of strings | `""` | Path prefixes that always trigger a Risk API call. | ## Required configurations These configurations are necessary for the Enforcer's basic functionality and features. ### Basic functionality configurations **`appId`** `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`** ```xml Example ... appId="" ... ``` --- **`apiToken`** `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`** ```xml Example ... apiToken="" ... ``` --- **`cookieKey`** `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`** ```xml Example ... cookieKey="" ... ``` --- **`baseUri`** `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. Change this only after discussing the change with [HUMAN Support](/applications/support). **`Example`** ```xml Example ... baseUri="https://sapi-{0}.perimeterx.net" ... ``` --- **`apiTimeout`** `integer` — required, default: 1500 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`** ```xml Example ... apiTimeout="1500" ... ``` --- **`blockingScore`** `integer` — required, default: 100 The minimum risk score that the Enforcer will block. Ranges from 0 (lowest risk) to 100 (highest risk). **`Example`** ```xml Example ... blockingScore="100" ... ``` --- ### Basic feature configurations **`socketIpHeader`** `string` — required Header name that contains the real client IP. If unset, the Enforcer uses the request's `UserHostAddress`. Configure this when a load balancer or proxy sits in front of your application so HUMAN receives the true client IP for detection. **`Example`** ```xml Example ... socketIpHeader="X-PX-TRUE-IP" ... ``` --- **`enabled`** `boolean` — required, default: true Whether the Enforcer module is enabled. * `true`: Enable the module * `false`: Disable the module **`Example`** ```xml Example ... enabled="true" ... ``` --- **`monitorMode`** `boolean` — required, default: true When `true`, 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). When `false`, the Enforcer returns block responses as needed. **`Example`** ```xml Example ... monitorMode="false" ... ``` --- ## Optional configurations These configurations aren't required, but you can use them to further customize the Enforcer's behavior. ### Bypass monitor header **`bypassMonitorHeader`** `string` 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](#monitorMode), where the Enforcer usually collects data without blocking user requests, before switching to `false`. 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`** ```xml Example ... bypassMonitorHeader="x-px-block" ... ``` --- ### Credentials Intelligence These configurations let you extract and detect compromised credentials. They're closely related to [Credentials Intelligence-related features](/applications/about-the-credentials-intelligence-dashboard) in Sightline Cyberfraud Defense. At minimum, ensure the following are configured to enable Credential Intelligence: * [`loginCredentialsExtractionEnabled`](#loginCredentialsExtractionEnabled) is set to `true` * [`loginCredentialsExtraction`](#loginCredentialsExtraction) is configured with at least one credential endpoint **`loginCredentialsExtractionEnabled`** `boolean` — default: false Whether to enable the extraction and reporting of credentials from the Enforcer for Credential Intelligence. * `true`: Enable Credential Intelligence * `false`: Disable Credential Intelligence **`Example`** ```xml Example ... loginCredentialsExtractionEnabled="true" ... ``` --- **`loginCredentialsExtraction`** `string` JSON array of credential extraction definitions, set as an XML attribute string. Each object configures one login endpoint. | Property | Type | Description | Possible values | | :------------- | :----- | :----------------------------------------------------------------- | :---------------------------------------- | | `method` | String | HTTP method of the login request | Any HTTP method | | `path_type` | String | Whether `path` is an exact match or a regular expression | `exact`, `regex` | | `path` | String | Login request path | Exact path or regex | | `sent_through` | String | Where credentials appear on the request | `body`, `header`, `query-param`, `custom` | | `user_field` | String | Username field name (not required when `sent_through` is `custom`) | — | | `pass_field` | String | Password field name (not required when `sent_through` is `custom`) | — | When `sent_through` is `custom`, configure [`customCredentialsExtractionHandler`](#customcredentialsextractionhandler). All endpoints with `sent_through: "custom"` use that handler. **`Example`** ```xml Example ... loginCredentialsExtraction='[{"method":"post","path_type":"exact","path":"/login","sent_through":"body","user_field":"username","pass_field":"password"},{"method":"post","path_type":"exact","path":"/login/custom","sent_through":"custom"}]' ... ``` --- **`ciVersion`** `"v2" | "multistep_sso"` — default: v2 Credentials Intelligence protocol to use for extracted login data. * `v2`: Single-step login * `multistep_sso`: Multi-step login **`Example`** ```xml Example ... ciVersion="v2" ... ``` --- **`compromisedCredentialsHeader`** `string` — default: px-compromised-credentials The header name to be set on the incoming request if the credentials are compromised. If this header is added, its value will always be `1`. If credentials have not been identified as compromised, the header will not be added to the request. **`Example`** ```xml Example ... compromisedCredentialsHeader="px-compromised-credentials" ... ``` --- **`additionalS2SActivityHeaderEnabled`** `boolean` — default: false Whether to attach the `additional_s2s` payload and URL as headers on the original request so your origin can enrich and send the activity later. When `true`, the Enforcer does **not** send `additional_s2s` automatically. When set to `true`, the following headers are added to the origin request: * `px-additional-activity`: A JSON object containing the payload of the `additional_s2s` activity. Set the `login_successful` and `http_status_code` fields before sending the activity. #### \`px-additional-activity\` header example ```json { "type": "additional_s2s", "timestamp": 1637000000, "socket_ip": "1.1.1.1", "px_app_id": "PX_APP_ID", "url": "https://www.example.com/the-target-url", "vid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "details": { "client_uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "request_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "ci_version": "v1", "http_status_code": null, // MODIFY, number (e.g., 200, 401, 404, etc.) "login_successful": null, // MODIFY, boolean (e.g., true, false) "raw_username": null // MODIFY, string (e.g., "test@mail.com") } } ``` * `px-additional-activity-url`: The URL to which the `additional_s2s` payload should be sent as an HTTP POST request. Send the POST with `Content-Type: application/json` and `Authorization: Bearer `. To send `additional_s2s` automatically from the Enforcer instead, leave this set to `false` and configure [`loginSuccessfulReportingMethod`](#loginsuccessfulreportingmethod). If the reporting method is left empty, login success is always reported as `false`. **`Example`** ```xml Example ... additionalS2SActivityHeaderEnabled="true" ... ``` --- **`sendRawUsernameOnAdditionalS2SActivity`** `boolean` — default: false Whether to report the raw username on the `additional_s2s` activity. * `false`: The raw username will never be reported. * `true`: The raw username will only be reported if: * The credentials are compromised, and * The login request was successful. **`Example`** ```xml Example ... sendRawUsernameOnAdditionalS2SActivity="true" ... ``` --- **`loginSuccessfulReportingMethod`** `"status" | "body" | "header" | "custom"` Method used to decide whether a login succeeded when the Enforcer sends `additional_s2s` automatically. If left empty, login success is always reported as `false`. #### status Provide status codes that represent a successful login via [`loginSuccessfulStatus`](#loginsuccessfulstatus). If the response status matches one of those values, login success is `true`; otherwise it is `false`. To define a status range, use the `custom` reporting method. ```xml ... loginSuccessfulReportingMethod="status" loginSuccessfulStatus="200,201,202" ... ``` #### header Configure [`loginSuccessfulHeaderName`](#loginsuccessfulheadername) and [`loginSuccessfulHeaderValue`](#loginsuccessfulheadervalue). If the response includes that header with the matching value, login success is `true`. ```xml ... loginSuccessfulReportingMethod="header" loginSuccessfulHeaderName="login-successful" loginSuccessfulHeaderValue="true" ... ``` #### body Configure [`loginSuccessfulBodyRegex`](#loginsuccessfulbodyregex). If the response body matches the regex, login success is `true`. ```xml ... loginSuccessfulReportingMethod="body" loginSuccessfulBodyRegex=".*You logged in successfully.*" ... ``` #### custom Configure [`customLoginSuccessfulHandler`](#customloginsuccessfulhandler). The handler's return value sets `login_successful`. **`Example`** ```xml Example ... loginSuccessfulReportingMethod="status" ... ``` --- **`loginSuccessfulStatus`** `comma-delimited list of integers` HTTP status codes treated as a successful login when [`loginSuccessfulReportingMethod`](#loginsuccessfulreportingmethod) is `status`. **`Example`** ```xml Example ... loginSuccessfulStatus="200,201" ... ``` --- **`loginSuccessfulBodyRegex`** `string` Regular expression matched against the response body when [`loginSuccessfulReportingMethod`](#loginsuccessfulreportingmethod) is `body`. **`Example`** ```xml Example ... loginSuccessfulBodyRegex=".*You logged in successfully.*" ... ``` --- **`loginSuccessfulHeaderName`** `string` Response header name checked when [`loginSuccessfulReportingMethod`](#loginsuccessfulreportingmethod) is `header`. **`Example`** ```xml Example ... loginSuccessfulHeaderName="login-successful" ... ``` --- **`loginSuccessfulHeaderValue`** `string` Expected response header value when [`loginSuccessfulReportingMethod`](#loginsuccessfulreportingmethod) is `header`. **`Example`** ```xml Example ... loginSuccessfulHeaderValue="true" ... ``` --- **`customCredentialsExtractionHandler`** `string` Class name of an `ICredentialsExtractionHandler` implementation used when a credentials extraction endpoint sets `sent_through` to `custom`. The `Handle` method receives an [`HttpRequest`](https://learn.microsoft.com/en-us/dotnet/api/system.web.httprequest) and should return an `ExtractedCredentials` object, or `null` if extraction fails. **`Example`** ```xml Example ... customCredentialsExtractionHandler="MyCredentialsExtractorHandler" ... ``` **`Handler example`** ```csharp Handler example namespace myUniqueApp { public class MyCredentialsExtractorHandler : ICredentialsExtractionHandler { public ExtractedCredentials Handle(HttpRequest httpRequest) { // Custom credentials extraction logic goes here. return new ExtractedCredentials("user", "pass"); } } } ``` --- **`customLoginSuccessfulHandler`** `string` Class name of an `ILoginSuccessfulHandler` implementation used when [`loginSuccessfulReportingMethod`](#loginsuccessfulreportingmethod) is `custom`. The `Handle` method receives an [`HttpResponse`](https://learn.microsoft.com/en-us/dotnet/api/system.web.httpresponse) and returns whether the login succeeded. **`Example`** ```xml Example ... customLoginSuccessfulHandler="MyLoginSuccessfulHandler" ... ``` **`Handler example`** ```csharp Handler example namespace myUniqueApp { public class MyLoginSuccessfulHandler : ILoginSuccessfulHandler { public bool Handle(HttpResponse httpResponse) { // Custom implementation resulting in boolean isLoginSuccessful return isLoginSuccessful; } } } ``` --- ### Custom block page Use these options to serve a custom block experience instead of the default [HUMAN Challenge](/applications/customize-challenge-look-feel) block page. To customize HUMAN's default page, see [HUMAN Challenge customization](#human-challenge-customization). **`customBlockUrl`** `string` URL of the custom block page HTML file. The Enforcer automatically allows this URI to avoid infinite redirects. As of version 2.8.0, CAPTCHA logic is handled by the JavaScript snippet rather than the Enforcer. Custom block pages must include the required script tag and div for the challenge. **`Example`** ```xml Example ... customBlockUrl="https://www.example.com/block.html" ... ``` --- **`redirectOnCustomUrl`** `boolean` — default: false When `true` and [`customBlockUrl`](#customblockurl) is set, blocked users receive a `307 Temporary Redirect` to the custom block page, with query parameters such as: ``` https://www.example.com/block.html?url=L3NvbWVwYWdlP2ZvbyUzRGJhcg==&uuid=e8e6efb0-8a59-11e6-815c-3bdad80c1d39&vid=08320300-6516-11e6-9308-b9c827550d47 ``` The `url` parameter is the original path and query, URL-encoded and then Base64-encoded, so it does not collide with block-page query parameters. When `false`, the Enforcer returns `403` on the blocked request URL and injects the block page content (or custom page content) without requiring those query parameters on your page. **`Example`** ```xml Example ... redirectOnCustomUrl="false" ... ``` --- ### Custom cookie header **`customCookieHeader`** `string` — default: x-px-cookies When set, the Enforcer reads HUMAN cookies from this header in addition to (or instead of relying solely on) the standard `Cookie` header. **`Example`** ```xml Example ... customCookieHeader="x-px-cookies" ... ``` --- ### Custom parameters These configurations are related to [custom parameters](/applications/set-custom-parameters). **`customParametersHandler`** `string` Class name of an `ICustomParametersHandler` implementation. The Enforcer calls `Handle` before building the payload on requests to HUMAN servers. You can set up to 10 custom parameters (`custom_param1` through `custom_param10`). The `Handle` method receives an [`HttpRequest`](https://learn.microsoft.com/en-us/dotnet/api/system.web.httprequest). **`Example`** ```xml Example ... customParametersHandler="CustomParamsImpl" ... ``` **`Handler example`** ```csharp Handler example namespace myUniqueApp { public class CustomParamsImpl : ICustomParametersHandler { public CustomParameters Handle(HttpRequest httpRequest) { CustomParameters customParams = new CustomParameters(); customParams.custom_param1 = "example"; customParams.custom_param2 = "example2"; return customParams; } } } ``` --- ### Custom user agent header **`useragentOverride`** `string` Header name that contains the client user agent. If unset, the Enforcer uses the incoming request's `User-Agent` header. **`Example`** ```xml Example ... useragentOverride="px-user-agent" ... ``` --- ### Custom verification handler **`customVerificationHandler`** `string` Class name of an `IVerificationHandler` implementation. When set, the Enforcer calls this handler instead of the default verification behavior so you can customize handling based on the risk score and context. The `Handle` method receives: * `HttpApplication application`: Current ASP.NET application. Calling [`CompleteRequest`](https://learn.microsoft.com/en-us/dotnet/api/system.web.httpapplication.completerequest) ends the request pipeline after the current event. * `PxContext pxContext`: HUMAN context with fields such as `Score`, `UUID`, and `BlockAction`. You can also read data enrichment from `pxContext` when `pxContext.IsPxdeVerified` is `true`. * `PxModuleConfigurationSection pxConfig`: Current Enforcer configuration. **`Example`** ```xml Example ... customVerificationHandler="UniqueVerificationHandler" ... ``` **`Handler example`** ```csharp Handler example namespace myUniqueApp { public class UniqueVerificationHandler : IVerificationHandler { public void Handle(HttpApplication application, PxContext pxContext, PxModuleConfigurationSection pxConfig) { if (pxContext.IsPxdeVerified) { dynamic pxde = pxContext.Pxde; // Use data enrichment as needed } if (pxContext.Score >= pxConfig.BlockingScore) { PxModule.BlockRequest(pxContext, pxConfig); application.CompleteRequest(); } } } } ``` --- ### Enforced routes These configurations let you define specific routes that should be enforced under certain conditions. **`mitigationUrls`** `comma-delimited list of strings` Routes or prefixes that should be enforced by HUMAN even when the Enforcer is in [monitor mode](#monitorMode). Matching routes go through the full Enforcer workflow, including blocking when necessary. Compare paths to `Request.Url.AbsolutePath` with the leading `/` removed. For example, configure `login` to match `/login`. This is an exact match, not a prefix match. **`Example`** ```xml Example ... mitigationUrls="login,checkout" ... ``` --- **`enforceSpecificRoutes`** `comma-delimited list of strings` When this list is non-empty, the Enforcer runs only on request paths that start with one of the configured prefixes. All other routes are skipped. **`Example`** ```xml Example ... enforceSpecificRoutes="/protect/route,/login,/checkout" ... ``` --- ### 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. **`fileExtWhitelist`** `comma-delimited list of strings` — default: .axd,.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,.jar 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`** ```xml Example ... fileExtWhitelist=".css,.js,.png,.jpg" ... ``` --- **`ipWhitelist`** `comma-delimited list of strings` Filters out requests with the specified IP address to avoid unnecessary traffic in the Enforcer verification flow. The request IP is resolved with the same logic as detection ([`socketIpHeader`](#socketipheader) when configured, otherwise the request socket IP). IPv4 and IPv6 are supported. **`Example`** ```xml Example ... ipWhitelist="127.0.0.1,10.0.0.0/24" ... ``` --- **`routesWhitelist`** `comma-delimited list of strings` 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`. That is, it uses exact prefix matching on the route via `StartsWith()`. Does not support regex and is case-sensitive. **`Example`** ```xml Example ... routesWhitelist="/health,/assets" ... ``` --- **`useragentsWhitelist`** `comma-delimited list of strings` 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`** ```xml Example ... useragentsWhitelist="GoogleBot,MyInternalMonitor/1.0" ... ``` --- ### First party 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. First party is enabled by default. If `firstPartyEnabled` and `firstPartyXhrEnabled` are omitted from your `pxModuleConfigurationSection`, the Enforcer handles first-party requests. When enabled, the Enforcer responds to first-party requests on routes derived from your **Application ID** without the `PX` prefix: * `//init.js` * `//xhr/*` For example, if the application ID is `PX12345678`, first-party routes take the form `/12345678/*`. After enabling first party on the Enforcer, complete the steps in [Integrate 1st-Party JS Snippet](/applications/integrate-1st-party-client) so your snippet serves the JavaScript Sensor via first party. > **Note** > > Both attributes must be set to `false` to disable first party. **`firstPartyEnabled`** `boolean` — default: true Whether to enable first party mode for Bot Defender or Sightline Cyberfraud Defense. **`Example`** ```xml Example ... firstPartyEnabled="true" ... ``` --- **`firstPartyXhrEnabled`** `boolean` — default: true Whether first-party XHR activity reverse-proxy routes are enabled. **`Example`** ```xml Example ... firstPartyXhrEnabled="true" ... ``` --- ### HUMAN Challenge customization These configurations let you customize the [HUMAN Challenge block page](/applications/create-a-human-challenge) **`cssRef`** `string` A way to include a custom CSS file to the block page. **`Example`** ```xml Example ... cssRef="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" ... ``` --- **`jsRef`** `string` A way to include custom JavaScript to the block page. This script will run after the default JavaScript scripts. **`Example`** ```xml Example ... jsRef="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" ... ``` --- **`customLogo`** `string` Adds a custom logo to the [HUMAN Challenge](/applications/create-a-human-challenge) block page via URL. **`Example`** ```xml Example ... customLogo="https://s.perimeterx.net/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 [`monitorMode`](#monitormode) is `false`. 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. **`monitoredRoutes`** `comma-delimited list of strings` Exact request paths treated as monitor mode even when the Enforcer is actively blocking elsewhere. Compare paths to `Request.Url.AbsolutePath` with the leading `/` removed. For example, configure `home` to match `/home`. This is an exact match, not a prefix match. **`Example`** ```xml Example ... monitoredRoutes="home,user" ... ``` --- ### Send activities **`sendPageActivities`** `boolean` — default: true Whether to send asynchronous `page_requested` activities. Sending these activities does not block the request. **`Example`** ```xml Example ... sendPageActivities="true" ... ``` --- **`sendBlockActivities`** `boolean` — default: true Whether to send asynchronous `block` activities. **`Example`** ```xml Example ... sendBlockActivities="true" ... ``` --- ### Sensitive headers removal **`sensitiveHeaders`** `comma-delimited list of strings` — 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`** ```xml Example ... sensitiveHeaders="cookie,cookies,x-auth-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. **`sensitiveRoutes`** `comma-delimited list of strings` A list of prefixes for all routes that should be considered sensitive. **`Example`** ```xml Example ... sensitiveRoutes="/login,/user/profile" ... ``` ---