> 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. # Fastly VCL v12 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. You define and update Fastly VCL Enforcer configuration in the `PX_CONFIGS` VCL file (`table px_configs`) and, for custom logic, in the `PX_CUSTOM` VCL file. Some Remote Configuration values also require entries in Fastly dictionaries such as `px_private` and `px_enforcer_config_rdata`. > **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. ## 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. For rotation, also set [`px_cookie_secret_old`](#px_cookie_secret). | | [Backend domain](#px_backend_url) | `px_backend_url` | String | `sapi-.perimeterx.net` | Domain to which HUMAN requests are sent | | [S2S timeout](#px_s2s_timeout) | `px_s2s_timeout` | Integer (ms) | `1000` | Risk API backend timeout. Set on the `PX_API` backend in `PX_CONFIGS`, not as a table key. | #### Basic features | Feature name | Key | Type | Default | Description | | :------------------------------------------------------ | :------------------------------- | :------- | :----------- | :-------------------------------------------------------------------------------------------- | | [Logger](#px_logger_severity) | `px_logger_severity` | String | `"error"` | The threshold above which logs on a particular event are received. | | [Client IP extraction](#px_custom_client_ip_extraction) | `px_custom_client_ip_extraction` | Function | Returns `""` | Custom subroutine that returns the true client IP. Defaults to `Fastly-Client-IP` when empty. | | [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 | | :------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- | :------- | :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | | [Activity headers](#activity-headers) | [`px_custom_activity_headers`](#px_custom_activity_headers) | Function | Returns `""` | Returns additional request headers to include on async activities. | | [Additional activity handler](#additional-activity-handler) | [`px_additional_activity_handler_enabled`](#px_additional_activity_handler_enabled) | Boolean | `false` | Whether to invoke [`px_custom_additional_activity_handler`](#px_custom_additional_activity_handler). | | [Additional activity handler](#additional-activity-handler) | [`px_custom_additional_activity_handler`](#px_custom_additional_activity_handler) | Function | Empty | Invoked after `page_requested` or `block` activity is prepared. | | [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. | | [Block oversized Risk requests](#block-oversized-risk-requests) | [`px_block_size_exceeded_15k_headers_size`](#px_block_size_exceeded_15k_headers_size) | Boolean | `false` | Whether to block when a Risk API request returns HTTP 413. | | [Block result header](#block-result-header) | [`px_add_block_result_header`](#px_add_block_result_header) | Boolean | `false` | Whether to include `px-ctx:block-result` on origin requests. | | [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). | | [CORS support](#cors-support) | [`px_cors_support_enabled`](#px_cors_support_enabled) | Boolean | `false` | Whether to enable CORS support. | | [CORS support](#cors-support) | [`px_cors_create_custom_block_response_headers_enabled`](#px_cors_create_custom_block_response_headers_enabled) | Boolean | `false` | Whether to invoke [`px_custom_cors_set_custom_block_response_headers`](#px_custom_cors_set_custom_block_response_headers). | | [CORS support](#cors-support) | [`px_custom_cors_set_custom_block_response_headers`](#px_custom_cors_set_custom_block_response_headers) | Function | Empty | Adds custom CORS headers to block responses. | | [CORS support](#cors-support) | [`px_cors_preflight_request_filter_enabled`](#px_cors_preflight_request_filter_enabled) | Boolean | `false` | Whether to filter preflight requests that pass the custom preflight handler from the Enforcer. | | [CORS support](#cors-support) | [`px_cors_preflight_handler_enabled`](#px_cors_preflight_handler_enabled) | Boolean | `false` | Whether to invoke [`px_custom_cors_preflight_handler`](#px_custom_cors_preflight_handler). | | [CORS support](#cors-support) | [`px_custom_cors_preflight_handler`](#px_custom_cors_preflight_handler) | Function | Empty | Handles CORS preflight requests before enforcement. | | [Credentials Intelligence](#credentials-intelligence) | [`px_login_credentials_extraction_enabled`](#px_login_credentials_extraction_enabled) | Boolean | `false` | Whether to enable Credentials Intelligence. | | [Credentials Intelligence](#credentials-intelligence) | [`px_login_credentials_extraction`](#px_login_credentials_extraction) | Table | Empty | Credential endpoint extraction settings in the `px_login_credentials_extraction` table. | | [Credentials Intelligence](#credentials-intelligence) | [`px_custom_is_login_request`](#px_custom_is_login_request) | Function | Empty | Returns the credential endpoint suffix for the request path. | | [Credentials Intelligence](#credentials-intelligence) | [`px_custom_login_extraction_callback`](#px_custom_login_extraction_callback) | Function | Empty | Extracts credentials when `sent_through` is `custom`. | | [Credentials Intelligence](#credentials-intelligence) | [`px_login_successful_reporting_method`](#px_login_successful_reporting_method) | String | `"status"` | How the Enforcer detects a successful login (`status`, `header`, or `custom`). | | [Credentials Intelligence](#credentials-intelligence) | [`px_login_successful_status`](#px_login_successful_status) | String | `"200"` | Single HTTP status code that indicates a successful login when using `status`. | | [Credentials Intelligence](#credentials-intelligence) | [`px_custom_set_login_successful_response_header`](#px_custom_set_login_successful_response_header) | Function | Empty | Returns `"1"` or `"0"` for login success when reporting method is `custom`. | | [Credentials Intelligence](#credentials-intelligence) | [`px_send_raw_username_on_additional_s2s_activity`](#px_send_raw_username_on_additional_s2s_activity) | Boolean | `false` | Whether to send the raw username on the `additional_s2s` activity. | | [Credentials Intelligence](#credentials-intelligence) | [`px_additional_s2s_activity_header_enabled`](#px_additional_s2s_activity_header_enabled) | Boolean | `false` | Whether to attach the `additional_s2s` payload and URL as headers instead of sending automatically. | | [Credentials Intelligence](#credentials-intelligence) | [`px_credentials_intelligence_query_string`](#px_credentials_intelligence_query_string) | Boolean | `false` | Whether to add `compromised_credentials=true` to the origin URL when credentials are compromised. | | [Credentials Intelligence](#credentials-intelligence) | [`px_compromised_credentials_returned_status_response`](#px_compromised_credentials_returned_status_response) | String | `""` | Response status code to return when compromised credentials are detected with query-string mode enabled. | | [Credentials Intelligence](#credentials-intelligence) | [`px_credentials_intelligence_version`](#px_credentials_intelligence_version) | String | `"both"` | **Deprecated.** Prefer per-endpoint `protocol` in [`px_login_credentials_extraction`](#px_login_credentials_extraction). | | [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 first party resources. | | [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_custom_first_party_response_modifier`](#px_custom_first_party_response_modifier) | Function | Empty | Modifies first party responses in `vcl_deliver`. | | [Custom parameters](#custom-parameters) | [`px_custom_add_custom_parameters`](#px_custom_add_custom_parameters) | Function | Empty | Sets `px-custom-param:1`–`10` on the request for HUMAN activities. | | [Enforced routes](#enforced-routes) | [`px_custom_enforced_routes`](#px_custom_enforced_routes) | Function | Returns `false` | Custom subroutine that returns whether the request should be enforced even in [monitor mode](#px_module_mode). | | [Extracted cookies](#extracted-cookies) | [`px_custom_extracted_cookies`](#px_custom_extracted_cookies) | Function | Empty | Custom subroutine that extracts cookie values and adds them to HUMAN requests. | | [Filters](#filters) | [`px_custom_filter_by_extension`](#px_custom_filter_by_extension) | Function | Common static extensions | Custom subroutine that filters requests by file extension. | | [Filters](#filters) | [`px_custom_filter_by_http_method`](#px_custom_filter_by_http_method) | Function | Returns `false` | Custom subroutine that filters requests by HTTP method. | | [Filters](#filters) | [`px_custom_filter_by_ip`](#px_custom_filter_by_ip) | Function | Returns `false` | Custom subroutine that filters requests by IP or CIDR. | | [Filters](#filters) | [`px_custom_filter_by_route`](#px_custom_filter_by_route) | Function | Returns `false` | Custom subroutine that filters requests by route. | | [Filters](#filters) | [`px_custom_filter_by_user_agent`](#px_custom_filter_by_user_agent) | Function | Returns `false` | Custom subroutine that filters requests by user agent. | | [GraphQL support](#graphql-support) | [`px_graphql_enabled`](#px_graphql_enabled) | Boolean | `true` | Whether to extract GraphQL operation data from matching routes. | | [GraphQL support](#graphql-support) | [`px_custom_is_graphql_route`](#px_custom_is_graphql_route) | Function | Matches `/graphql` | Custom subroutine that returns whether the request is a GraphQL endpoint. | | [GraphQL support](#graphql-support) | [`px_sensitive_graphql_operation_names`](#px_sensitive_graphql_operation_names) | String | `""` | Space-separated operation names that always trigger a Risk API call. | | [GraphQL support](#graphql-support) | [`px_sensitive_graphql_operation_types`](#px_sensitive_graphql_operation_types) | String | `""` | Space-separated operation types that always trigger a Risk API call. | | [GraphQL support](#graphql-support) | [`px_custom_check_sensitive_graphql_operation`](#px_custom_check_sensitive_graphql_operation) | Function | Returns `false` | Returns whether extracted GraphQL data should be treated as sensitive. | | [Header data enrichment](#header-data-enrichment) | [`px_data_enrichment_header_name`](#px_data_enrichment_header_name) | String | `""` | The header name used to send [data classification enrichment](/applications/data-classification-enrichment) values on the request. | | [HUMAN Challenge customization](#human-challenge-customization) | [`px_css_ref`](#px_css_ref) | String | `""` | A URL to a custom CSS file for 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. | | [HUMAN Challenge customization](#human-challenge-customization) | [`px_custom_block_on_error_message`](#px_custom_block_on_error_message) | String | `""` | A custom message to display on the block page when an error occurs. | | [HUMAN Challenge customization](#human-challenge-customization) | [`px_custom_block_page_content`](#px_custom_block_page_content) | Function | Empty | Returns custom HTML for the block page. | | [HUMAN Challenge customization](#human-challenge-customization) | [`px_custom_web_block_page_response`](#px_custom_web_block_page_response) | Function | Empty | Overrides the default web block response. | | [HUMAN Challenge customization](#human-challenge-customization) | [`px_custom_rate_limit_block_page`](#px_custom_rate_limit_block_page) | Function | Empty | Overrides the default rate-limit block response. | | [HUMAN Challenge customization](#human-challenge-customization) | [`px_custom_create_advanced_blocking_response`](#px_custom_create_advanced_blocking_response) | Function | Empty | Overrides the default ABR JSON block response. | | [Logging](#logging) | [`px_async_activities_logger`](#px_async_activities_logger) | String | `"PX-Async-Activities"` | Name of the Fastly logging endpoint for async activities. | | [Logging](#logging) | [`px_telemetry_activity_logger`](#px_telemetry_activity_logger) | String | `"PX-Telemetry"` | Name of the Fastly logging endpoint for telemetry activities. | | [Logging](#logging) | [`px_debug_syslog_name`](#px_debug_syslog_name) | String | `"PX-Debug"` | Name of the Fastly logging endpoint for debug logs. | | [Logging](#logging) | [`px_error_syslog_name`](#px_error_syslog_name) | String | `"PX-Error"` | Name of the Fastly logging endpoint for error logs. | | [Logging](#logging) | [`px_debug_probability`](#px_debug_probability) | String | `"1"` | One out of every *N* requests generates debug logs when severity is `debug`. | | [MCP protection](#mcp-protection) | [`px_agentic_trust_enabled`](#px_agentic_trust_enabled) | Boolean | `false` | Whether MCP protection is enabled. | | [MCP protection](#mcp-protection) | [`px_agentic_trust_mcp_endpoint_path`](#px_agentic_trust_mcp_endpoint_path) | String | `"/mcp"` | The path of the MCP endpoint. | | [Monitored routes](#monitored-routes) | [`px_custom_monitored_routes`](#px_custom_monitored_routes) | Function | Returns `false` | Custom subroutine that returns whether the request should be treated as monitored. | | [Override configs](#override-configs) | [`px_override_configs`](#px_override_configs) | Function | Empty | Adjusts `req.http.px-cfg` values at runtime. | | [Pre-clean](#pre-clean) | [`px_enable_pre_clean`](#px_enable_pre_clean) | Boolean | `false` | Whether to invoke [`px_custom_pre_clean`](#px_custom_pre_clean) before HUMAN headers are removed. | | [Pre-clean](#pre-clean) | [`px_custom_pre_clean`](#px_custom_pre_clean) | Function | Empty | Runs before HUMAN metadata headers are removed from the origin request. | | [PXHD cookie](#pxhd-cookie) | [`px_secured_pxhd_enabled`](#px_secured_pxhd_enabled) | Boolean | `false` | Whether the [`_pxhd` cookie](/applications/use-of-cookies-web-storage) should include the `Secure` attribute. | | [Remote Configuration](#remote-configuration) | [`px_logger_auth_token`](#px_logger_auth_token) | String | `""` | Authentication token for HUMAN's logger service and header-based logger. | | [Remote Configuration](#remote-configuration) | [`px_remote_config_auth_token`](#px_remote_config_auth_token) | String | `""` | Token that authenticates Remote Configuration update requests. | | [Remote Configuration](#remote-configuration) | [`px_remote_config_id`](#px_remote_config_id) | String | `""` | The Remote Configuration ID. | | [Remote Configuration](#remote-configuration) | [`px_fastly_api_token`](#px_fastly_api_token) | String | `""` | Fastly API token stored in the `px_private` dictionary. Required for Remote Configuration. | | [Remote Configuration](#remote-configuration) | [`px_enforcer_config_rdata_id`](#px_enforcer_config_rdata_id) | String | `""` | Dictionary ID for `px_enforcer_config_rdata`. Required for Remote Configuration. | | [Response custom parameters](#response-custom-parameters) | [`px_custom_add_response_custom_parameters`](#px_custom_add_response_custom_parameters) | Function | Empty | Sets `px-custom-param:11`–`20` from the origin response. | | [Risk backend overwrite](#risk-backend-overwrite) | [`px_set_custom_risk_backend_overwrite`](#px_set_custom_risk_backend_overwrite) | Function | Empty | Changes the backend used for Risk API requests. | | [Sensitive headers removal](#sensitive-headers-removal) | [`px_custom_unset_sensitive_headers`](#px_custom_unset_sensitive_headers) | Function | Unsets `cookie` / `cookies` | Custom subroutine that unsets sensitive headers from Enforcer backend requests. | | [Sensitive routes](#sensitive-routes) | [`px_custom_check_sensitive_route`](#px_custom_check_sensitive_route) | Function | Returns `false` | Custom subroutine that returns whether the request should always trigger a Risk API call. | | [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 | `""` | JWT cookie field that contains the user ID. | | [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 | `""` | JWT header field that contains the user ID. | | [Users identifiers](#users-identifiers) | [`px_custom_extract_jwt_additional_fields`](#px_custom_extract_jwt_additional_fields) | Function | Empty | Returns additional JWT fields as `"name":"value"` pairs. | ## 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`** ```php Example # PX_CONFIGS table px_configs { "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`** ```php Example # PX_CONFIGS table px_configs { # ... "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.** If you need to rotate secrets, then adjust this configuration to be the new generated cookie secret, then add an additional field name, `px_cookie_secret_old`, that holds the previous cookie secret value. **`Basic example`** ```php Basic example # PX_CONFIGS table px_configs { # ... "px_cookie_secret": "", # ... } ``` **`Cookie rotation example`** ```php Cookie rotation example # PX_CONFIGS table px_configs { # ... "px_cookie_secret": "", "px_cookie_secret_old": "", # ... } ``` --- **`px_backend_url`** `string` — required, default: sapi-\.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**. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_backend_url": "sapi-.perimeterx.net", # ... } ``` --- **`px_s2s_timeout`** `integer` — required, default: 1000 > **Warning** > > Adding this value in the `px_configs` table has no effect. Set `connect_timeout`, `first_byte_timeout`, and `between_bytes_timeout` on the `PX_API` backend in the `PX_CONFIGS` VCL file. 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`** ```php Example # PX_CONFIGS backend PX_API { # ... .connect_timeout = 2000ms; .first_byte_timeout = 2000ms; .between_bytes_timeout = 2000ms; # ... } ``` --- ### 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. When set to `error`, logs are sent to the endpoint named by [`px_error_syslog_name`](#px_error_syslog_name). When set to `debug`, logs are sent to the endpoint named by [`px_debug_syslog_name`](#px_debug_syslog_name). **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_logger_severity": "debug", # ... } ``` --- **`px_custom_client_ip_extraction`** `function` — required, default: Returns "" By default, the Enforcer reports the value from the [Fastly-Client-IP](https://www.fastly.com/documentation/reference/http/http-headers/Fastly-Client-IP/) header. If that value is inaccurate, implement this subroutine to return the true client IP from a trusted custom header. Returning an empty string falls back to `Fastly-Client-IP`. **`Example`** ```php Example # PX_CUSTOM sub px_custom_client_ip_extraction STRING { if (req.http.true-client-ip) { return req.http.true-client-ip; } return ""; } ``` --- **`px_module_enabled`** `boolean` — required, default: true Whether the Enforcer module is enabled. * `true`: Enable the module * `false`: Disable the module **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_module_enabled": "false", # ... } ``` --- **`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`** ```php Example # PX_CONFIGS table px_configs { # ... "px_module_mode": "active_blocking", # ... } ``` --- ## Optional configurations These configurations aren't required, but you can use them to further customize the Enforcer's behavior. ### Activity headers **`px_custom_activity_headers`** `function` — default: Returns "" Fastly VCL cannot automatically report all request headers on async activities. Return a string of additional headers to include. Each header must use the form `",{%22name%22: %22
%22, %22value%22: " if(req.http.
, "%22" json.escape(req.http.
) "%22", "null") "}"`. > **Warning** > > Be sure to include the leading comma (`,`). **`Example`** ```php Example # PX_CUSTOM sub px_custom_activity_headers STRING { declare local var.ret STRING; set var.ret = ",{%22name%22: %22my-header%22, %22value%22: " if(req.http.my-header, "%22" json.escape(req.http.my-header) "%22", "null") "}" ",{%22name%22: %22my-header-1%22, %22value%22: " if(req.http.my-header-1, "%22" json.escape(req.http.my-header-1) "%22", "null") "}"; return var.ret; } ``` --- ### Additional activity handler **`px_additional_activity_handler_enabled`** `boolean` — default: false Whether to invoke the [`px_custom_additional_activity_handler`](#px_custom_additional_activity_handler) subroutine. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_additional_activity_handler_enabled": "true", # ... } ``` --- **`px_custom_additional_activity_handler`** `function` — default: Empty A custom subroutine that runs after the Enforcer prepares the `page_requested` or `block` activity and before forwarding the request to the next step in the pipeline. A common use case is to set the score as a variable or header so the application can read it and apply its own logic. HUMAN metadata is available on `req.http.px-ctx`. This subroutine is called in `vcl_recv`. **`Example`** ```php Example # PX_CUSTOM sub px_custom_additional_activity_handler { declare local var.score STRING; set var.score = if(req.http.px-ctx:pass-reason, "0", "100"); log "syslog " req.service_id " CustomLoggingEndpoint :: Score: " var.score ", Data Enrichment: " req.http.px-ctx:data-enrichment; } ``` --- ### 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 **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_advanced_blocking_response_enabled": "false", # ... } ``` --- ### Block oversized Risk requests **`px_block_size_exceeded_15k_headers_size`** `boolean` — default: false Due to Fastly size limits, large **Risk API** requests may return [HTTP 413](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413). By default, the Enforcer fails open. When enabled, those requests are blocked instead. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_block_size_exceeded_15k_headers_size": "true", # ... } ``` --- ### Block result header **`px_add_block_result_header`** `boolean` — default: false Whether to include `px-ctx:block-result` with value `"0"` (pass) or `"1"` (block) on origin requests. Useful while testing in [monitor mode](#px_module_mode). **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_add_block_result_header": "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`** ```php Example # PX_CONFIGS table px_configs { # ... "px_bypass_monitor_header": "x-bypass-monitor-mode", # ... } ``` --- ### CORS support You can configure the Enforcer to support Cross-Origin Resource Sharing (CORS) requests. CORS is a mechanism that lets the server indicate if a request contains cross-origin resources by adding special HTTP headers to the request. These headers let the browser load these resources. Without them, the browser may block requests to these resources for security reasons instead. In most cases, CORS employs a two-stage procedure with a preliminary “preflight” request followed by the actual request. The preflight request checks if the actual request will be responded to. To learn more about different request types, see these [examples](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#examples_of_access_control_scenarios). You must configure the Enforcer to address both simple requests (without preflight) and more complex ones (with preflight) to support CORS requests. **`px_cors_support_enabled`** `boolean` — default: false Whether to enable CORS support. * `true`: Enable CORS support * `false`: Disable CORS support After setting this configuration to `true`, the Enforcer: * Automatically adds the following default CORS response headers to block responses resulting from CORS requests. ``` Access-Control-Allow-Origin: Access-Control-Allow-Credentials: true ``` * Activates the [`px_custom_cors_set_custom_block_response_headers`](#px_custom_cors_set_custom_block_response_headers) configuration, which lets you customize the block response headers via a custom function. * Activates the [`px_cors_preflight_request_filter_enabled`](#px_cors_preflight_request_filter_enabled) and [`px_custom_cors_preflight_handler`](#px_custom_cors_preflight_handler) configurations, which lets you filter and custom handle preflight requests. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_cors_support_enabled": "true", # ... } ``` --- **`px_cors_create_custom_block_response_headers_enabled`** `boolean` — default: false Whether to invoke [`px_custom_cors_set_custom_block_response_headers`](#px_custom_cors_set_custom_block_response_headers). **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_cors_create_custom_block_response_headers_enabled": "true", # ... } ``` --- **`px_custom_cors_set_custom_block_response_headers`** `function` — default: Empty If the default CORS response headers are not sufficient, use this subroutine to customize the headers added to block responses resulting from CORS requests. If this subroutine is defined, the default CORS block headers are **not** added. Only the headers you set on `obj` are included. **`Example`** ```php Example # PX_CUSTOM sub px_custom_cors_set_custom_block_response_headers { set obj.http.Access-Control-Allow-Origin = req.http.Origin; set obj.http.Access-Control-Allow-Credentials = "true"; set obj.http.Access-Control-Allow-Methods = "GET, POST, OPTIONS"; set obj.http.Access-Control-Allow-Headers = "Content-Type, Authorization"; } ``` --- **`px_cors_preflight_request_filter_enabled`** `boolean` — default: false Disables enforcement for CORS preflight requests. When set to `true`, CORS preflight requests will be pass through the Enforcer flow without triggering detection or block responses. * `true`: Filter out preflight requests * `false`: Don't filter out preflight requests **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_cors_preflight_request_filter_enabled": "true", # ... } ``` --- **`px_cors_preflight_handler_enabled`** `boolean` — default: false Whether to invoke [`px_custom_cors_preflight_handler`](#px_custom_cors_preflight_handler). **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_cors_preflight_handler_enabled": "true", # ... } ``` --- **`px_custom_cors_preflight_handler`** `function` — default: Empty A custom subroutine for handling CORS preflight requests. Use it to return a customized preflight response before enforcement. [`px_custom_cors_preflight_handler`](#px_custom_cors_preflight_handler) is invoked **prior** to determining whether to filter the request based on [`px_cors_preflight_request_filter_enabled`](#px_cors_preflight_request_filter_enabled). This lets you return customized responses for preflight requests that meet certain conditions and filter those that do not. **`Example`** ```php Example # PX_CUSTOM sub px_custom_cors_preflight_handler { set obj.status = 204; set obj.http.Access-Control-Allow-Origin = req.http.Origin; set obj.http.Access-Control-Allow-Methods = req.method; set obj.http.Access-Control-Allow-Headers = req.http.Access-Control-Request-Headers; set obj.http.Access-Control-Allow-Credentials = "true"; set obj.http.Access-Control-Max-Age = "86400"; } ``` --- ### 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: * [`px_login_credentials_extraction_enabled`](#px_login_credentials_extraction_enabled) is set to `true` * [`px_login_credentials_extraction`](#px_login_credentials_extraction) is configured with at least one credential endpoint **`px_login_credentials_extraction_enabled`** `boolean` — default: false > **Note** > > Be sure to define a suffix for each endpoint (for example `_0`, `_1`) and append that suffix to each key. Pair this table with [`px_custom_is_login_request`](#px_custom_is_login_request). The table is declared in `PX_CUSTOM`, or you can replace it with a [Fastly dictionary](https://www.fastly.com/documentation/reference/api/dictionaries/dictionary/) of the same name. Whether to enable the extraction and reporting of credentials from the Enforcer for Credential Intelligence. * `true`: Enable Credential Intelligence * `false`: Disable Credential Intelligence **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_login_credentials_extraction_enabled": "true", # ... } ``` --- **`px_login_credentials_extraction`** `table` An array of configuration objects for each credential endpoint. Each element in the array is an object representing a distinct endpoint to which credentials are sent and includes: * How to identify these credential-bearing requests * How to extract the credentials from the request * How to determine if the request operation (login, signup, etc.) was successful based on the returned HTTP response Click to expand the full properties list. **`Example`** ```php Example # PX_CUSTOM table px_login_credentials_extraction { "path_0": "/login", "protocol_0": "v2", "method_0": "post", "sent_through_0": "body", "pass_field_0": "password", "user_field_0": "username", "path_1": "/sign-up", "protocol_1": "multistep_sso", "method_1": "post", "sent_through_1": "custom", } ``` #### Properties **`path`** `string` — required The path of the request that contains the credentials. Store an exact path in the [`px_login_credentials_extraction`](#px_login_credentials_extraction) table. For regex matching, implement the logic in [`px_custom_is_login_request`](#px_custom_is_login_request). **`Example`** ```php Example # PX_CUSTOM table px_login_credentials_extraction { # ... "path_0": "/sign-up", # ... } ``` --- **`method`** `"post" | "put"` — required The HTTP method of the request that contains the credentials. Supports `"post"` and `"put"`. **`Example`** ```php Example # PX_CUSTOM table px_login_credentials_extraction { # ... "method_0": "post", # ... } ``` --- **`sent_through`** `"body" | "custom"` — required Whether the credentials should be extracted from the request body or via a defined custom callback. * `"body"`: The credentials will be extracted according to the configured [`user_field`](#user_field) and [`pass_field`](#pass_field) values from the request body. Body size is limited to 8K per [Fastly limits](https://docs.fastly.com/products/network-services-resource-limits#request-and-response-limits). The Enforcer parses the request body based on the following `Content-Type` request header: * `application/json` * `application/x-www-form-urlencoded` * `"custom"`: The credentials will be extracted by invoking [`px_custom_login_extraction_callback`](#px_custom_login_extraction_callback). **`Example`** ```php Example # PX_CUSTOM table px_login_credentials_extraction { # ... "sent_through_0": "body", # ... } ``` --- **`user_field`** `string` **Required** if [`sent_through`](#sent_through) is set to `"body"`. The name of the field containing the username in the request body. On Fastly VCL, nested JSON fields are matched by leaf field name (period-separated paths are not required). For example, a body with `{ "user_info": { "username": "user123" } }` can use `user_field` set to `"username"`. **`Example`** ```php Example # PX_CUSTOM table px_login_credentials_extraction { # ... "sent_through_0": "body", "user_field_0": "username", # ... } ``` --- **`pass_field`** `string` **Required** if [`sent_through`](#sent_through) is set to `"body"`. The name of the field containing the password in the request body. On Fastly VCL, nested JSON fields are matched by leaf field name (period-separated paths are not required). For example, a body with `{ "authentication": { "password": "P@s$w0rD!" } }` can use `pass_field` set to `"password"`. **`Example`** ```php Example # PX_CUSTOM table px_login_credentials_extraction { # ... "sent_through_0": "body", "pass_field_0": "password", # ... } ``` --- **`protocol`** `"v2" | "multistep_sso" | "both"` — default: "both" Whether to process credentials as part of single or multiple HTTP requests. By default, the module tries to process requests depending on which credential fields were extracted. If omitted, the Enforcer uses [`px_credentials_intelligence_version`](#px_credentials_intelligence_version). * `"v2"`: Both username and password are present on the same HTTP request and must be extracted successfully to trigger Credential Intelligence. * `"multistep_sso"`: The username and password are delivered on different HTTP requests. Either the username or password, but not both, must be extracted successfully to trigger Credential Intelligence. * `"both"`: The username and password may be present on the same HTTP request or on different HTTP requests. If either username or password is successfully extracted, the Enforcer will send the credentials according to the multistep_sso protocol. If both username and password are successfully extracted, the Enforcer will send the credentials according to the v2 protocol. **`Example`** ```php Example # PX_CUSTOM table px_login_credentials_extraction { # ... "protocol_0": "v2", # ... } ``` --- --- **`px_custom_is_login_request`** `function` Returns the credential endpoint suffix (for example `_0` or `_1`) that matches the request path for [`px_login_credentials_extraction`](#px_login_credentials_extraction). Use this subroutine for exact or regex path matching. **`Example`** ```php Example # PX_CUSTOM sub px_custom_is_login_request STRING { if (req.url.path == table.lookup(px_login_credentials_extraction, "path_0")) { return "_0"; } else if (req.url.path ~ "^/sign-up") { return "_1"; } } ``` --- **`px_custom_login_extraction_callback`** `function` **Required** if [`sent_through`](#sent_through) is set to `"custom"`. A custom credential extraction subroutine that returns the raw credentials from the request. Use `req.http.px-creds:endpoint-index` to distinguish endpoints. Set `req.http.px-creds:raw-username` and `req.http.px-creds:raw-password`. If neither the username nor the password can be extracted, leave both unset. **`Example`** ```php Example # PX_CUSTOM sub px_custom_login_extraction_callback { declare local var.username STRING; declare local var.password STRING; if (req.http.px-creds:endpoint-index == "_1") { # set var.username and var.password from the request } if (var.username) { set req.http.px-creds:raw-username = var.username; } if (var.password) { set req.http.px-creds:raw-password = var.password; } } ``` --- **`px_login_successful_reporting_method`** `"status" | "header" | "custom"` — default: status The method by which the Enforcer will determine whether the login request was successful. * `"status"`: The Enforcer will determine if the login request was successful by evaluating the response status code against [`px_login_successful_status`](#px_login_successful_status). * `"header"`: The Enforcer will determine if the login request was successful when `resp.http.x-px-login-successful` is `"1"`. * `"custom"`: The Enforcer will determine if the login request was successful by invoking [`px_custom_set_login_successful_response_header`](#px_custom_set_login_successful_response_header). **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_login_successful_reporting_method": "custom", # ... } ``` --- **`px_login_successful_status`** `string` — default: 200 The default HTTP status codes that indicate a successful login. This takes effect when the [`px_login_successful_reporting_method`](#px_login_successful_reporting_method) is set to `status`. Fastly VCL supports a single status code. For multiple status codes, use `custom` reporting with [`px_custom_set_login_successful_response_header`](#px_custom_set_login_successful_response_header). **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_login_successful_status": "202", # ... } ``` --- **`px_custom_set_login_successful_response_header`** `function` **Required** if [`px_login_successful_reporting_method`](#px_login_successful_reporting_method) is set to `"custom"`. A custom subroutine that inspects the HTTP response and indicates whether the login attempt was successful. Return `"1"` if the login succeeded or `"0"` otherwise. Invoked during `vcl_deliver`. **`Example`** ```php Example # PX_CUSTOM sub px_custom_set_login_successful_response_header STRING { if (resp.http.custom-login-header == "login_successful") { return "1"; } return "0"; } ``` --- **`px_send_raw_username_on_additional_s2s_activity`** `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`** ```php Example # PX_CONFIGS table px_configs { # ... "px_send_raw_username_on_additional_s2s_activity": "true", # ... } ``` --- **`px_additional_s2s_activity_header_enabled`** `boolean` — default: false Whether to attach the `additional_s2s` payload and URL as headers to the original request. This is done so that the `additional_s2s` activity can be enriched with the proper `login_successful` value and sent to the provided URL at a later stage. Enabling this configuration disables automatic sending of `additional_s2s` activity. 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. The `login_successful` and `http_status_code` fields should be set prior to sending the activity. * `px-additional-activity-url`: The URL to which the `additional_s2s` payload should be sent as an HTTP POST request. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_additional_s2s_activity_header_enabled": "true", # ... } ``` --- **`px_credentials_intelligence_query_string`** `boolean` — default: false Whether to append `compromised_credentials=true` to the origin request URL when compromised credentials are identified. Unlike header-based signaling on other Enforcers, Fastly VCL can surface compromised credentials through the request query string. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_credentials_intelligence_query_string": "true", # ... } ``` --- **`px_compromised_credentials_returned_status_response`** `string` — default: "" When [`px_credentials_intelligence_query_string`](#px_credentials_intelligence_query_string) is enabled and a successful login used compromised credentials, set the client response status to this value. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_compromised_credentials_returned_status_response": "401", # ... } ``` --- **`px_credentials_intelligence_version`** `"v2" | "multistep_sso" | "both"` — deprecated, default: both The default credential hashing protocol applied to endpoints that do not specify a [`protocol`](#protocol) field. * `"v2"`: Both username and password are present on the same HTTP request and must be extracted successfully to trigger Credential Intelligence. * `"multistep_sso"`: The username and password are delivered on different HTTP requests. Either the username or password, but not both, must be extracted successfully to trigger Credential Intelligence. * `"both"`: The username and password may be present on the same HTTP request or on different HTTP requests. If either username or password is successfully extracted, the Enforcer will send the credentials according to the multistep_sso protocol. If both username and password are successfully extracted, the Enforcer will send the credentials according to the v2 protocol. Prefer configuring `protocol` per endpoint in [`px_login_credentials_extraction`](#px_login_credentials_extraction). **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_credentials_intelligence_version": "v2", # ... } ``` --- ### 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`** ```php Example # PX_CONFIGS table px_configs { # ... "px_custom_cookie_header": "custom-human-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`** ```php Example # PX_CONFIGS table px_configs { # ... "px_first_party_enabled": "false", # ... } ``` --- **`px_custom_first_party_prefix`** `string` — default: "" 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`** ```php Example # PX_CONFIGS table px_configs { # ... "px_custom_first_party_prefix": "/custom-prefix", # ... } ``` --- **`px_custom_first_party_sensor_endpoint`** `string` — default: "" 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`** ```php Example # PX_CONFIGS table px_configs { # ... "px_custom_first_party_sensor_endpoint": "/human_sensor", # ... } ``` --- **`px_custom_first_party_xhr_endpoint`** `string` — default: "" 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`** ```php Example # PX_CONFIGS table px_configs { # ... "px_custom_first_party_xhr_endpoint": "/human_xhr", # ... } ``` --- **`px_custom_first_party_captcha_endpoint`** `string` — default: "" 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`** ```php Example # PX_CONFIGS table px_configs { # ... "px_custom_first_party_captcha_endpoint": "/human_captcha", # ... } ``` --- **`px_custom_first_party_response_modifier`** `function` — default: Empty Modifies first party responses in `vcl_deliver` using the [client response](https://www.fastly.com/documentation/reference/vcl/variables/client-response/) object. **`Example`** ```php Example # PX_CUSTOM sub px_custom_first_party_response_modifier { unset resp.http.Access-Control-Allow-Origin; set resp.http.Strict-Transport-Security = "max-age=86400"; } ``` --- ### Custom parameters These configurations are related to [custom parameters](/applications/set-custom-parameters). **`px_custom_add_custom_parameters`** `function` — default: Empty 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 (`1`–`10`). Set them on request headers named `px-custom-param:`. Custom parameters must also be configured in the HUMAN Portal. **`Example`** ```php Example # PX_CUSTOM sub px_custom_add_custom_parameters { set req.http.px-custom-param:1 = "test1"; set req.http.px-custom-param:2 = "test2"; set req.http.px-custom-param:3 = "3"; } ``` --- ### 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_custom_enforced_routes`** `function` A custom subroutine that lets you define which requests should be enforced based on custom logic, even when the Enforcer is in [monitor mode](#px_module_mode). * Returns `true`: The request should be enforced. * Returns `false` (default): The request should proceed with the usual enforcement flow. **`Example`** ```php Example # PX_CUSTOM sub px_custom_enforced_routes BOOL { if (req.url.path ~ {"^/enforced|^/checkout"}) { return true; } return false; } ``` --- ### Extracted cookies **`px_custom_extracted_cookies`** `function` — default: Empty For each cookie name, the Enforcer will extract the cookie's key-value pair and add it as a new field in the **Risk API**. This lets you include additional information to HUMAN's detection mechanism if you'd like to. Extract cookie values onto `bereq.http.X-PX-` headers for HUMAN backend requests. **`Example`** ```php Example # PX_CUSTOM sub px_custom_extracted_cookies { if (req.http.cookie:session_id && req.http.cookie:session_id != "") { set bereq.http.X-PX-session_id = req.http.cookie:session_id; } } ``` --- ### 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. Implement filter logic in `PX_CUSTOM`. A return value of `true` means the request is filtered from enforcement. A return value of `false` means the request should proceed with the usual enforcement flow. **`px_custom_filter_by_extension`** `function` 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. **`Default`** ```php Default # PX_CUSTOM sub px_custom_filter_by_extension BOOL { if ((req.request == "GET" || req.request == "HEAD") && req.url.ext ~ "^(css|bmp|tif|ttf|docx|woff2|js|pict|tiff|eot|xlsx|csv|eps|woff|xls|jpeg|jpg|doc|ejs|otf|pptx|gif|pdf|swf|svg|ps|ico|pls|midi|svgz|class|png|ppt|mid|webp|jar)$") { return true; } return false; } ``` --- **`px_custom_filter_by_http_method`** `function` — default: Returns false Filters out requests with the specified HTTP method to avoid unnecessary traffic in the Enforcer verification flow. **`Example`** ```php Example # PX_CUSTOM sub px_custom_filter_by_http_method BOOL { if (req.request ~ "(?i)^(OPTIONS|TRACE)$") { return true; } return false; } ``` --- **`px_custom_filter_by_ip`** `function` — default: Returns false Filters out requests with the specified IP address to avoid unnecessary traffic in the Enforcer verification flow. > **Note** > > The easiest way to implement this subroutine is to declare and use a [Fastly Access Control List (ACL)](https://www.fastly.com/documentation/reference/vcl/declarations/acl/) as shown in the example below. **`Example`** ```php Example # PX_CUSTOM acl Filtered_IPs { "123.123.123.123"; "12.12.12.0"/24; } sub px_custom_filter_by_ip BOOL { if (req.http.Fastly-Client-IP ~ Filtered_IPs) { return true; } return false; } ``` --- **`px_custom_filter_by_route`** `function` — default: Returns false 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`** ```php Example # PX_CUSTOM sub px_custom_filter_by_route BOOL { if (req.url.path ~ {"^/health|^/static/"}) { return true; } return false; } ``` --- **`px_custom_filter_by_user_agent`** `function` — default: Returns false 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`** ```php Example # PX_CUSTOM sub px_custom_filter_by_user_agent BOOL { if (req.http.User-Agent ~ {"Filtered_UA"}) { return true; } return false; } ``` --- ### GraphQL support These configurations let the Enforcer extract [GraphQL](https://graphql.org/learn/) data from requests so that it can enforce these requests in the same way as other types of traffic. **`px_graphql_enabled`** `boolean` — default: true Whether to parse and report information about GraphQL operations on incoming requests. When `true`, all POST requests with routes that match the prefixes configured in [`px_custom_is_graphql_route`](#px_custom_is_graphql_route) will have their bodies parsed for GraphQL operations. * `true`: Enable GraphQL support * `false`: Disable GraphQL support **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_graphql_enabled": "false", # ... } ``` --- **`px_custom_is_graphql_route`** `function` A custom subroutine that returns whether the request should be considered a GraphQL route. * Returns `true`: HUMAN checks for sensitive GraphQL operations as specified in [`px_sensitive_graphql_operation_names`](#px_sensitive_graphql_operation_names) and [`px_sensitive_graphql_operation_types`](#px_sensitive_graphql_operation_types). * Returns `false` (default): The Enforcer won't attempt to extract GraphQL data. **`Default`** ```php Default # PX_CUSTOM sub px_custom_is_graphql_route BOOL { if (req.url.path ~ {"/graphql"}) { return true; } return false; } ``` --- **`px_sensitive_graphql_operation_names`** `string` — default: "" A space-separated list of operation names that should be considered sensitive. Some routes may be more prone to bot attacks than others, such as routes that execute payments or handle personal information. You can configure these names as sensitive to ensure more stringent protection. If one or more GraphQL operations has a name matching this list, the Enforcer will trigger a **Risk API** call even if the request contains a valid, unexpired cookie. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_sensitive_graphql_operation_names": "SensitiveOperation1 SensitiveOperation2", # ... } ``` --- **`px_sensitive_graphql_operation_types`** `'query' | 'mutation' | 'subscription'` — default: "" A space-separated list of operation types that should be considered sensitive. Some routes may be more prone to bot attacks than others, such as routes that execute payments or handle personal information. You can configure these routes as sensitive to ensure a more stringent protection. If one or more GraphQL operations on an HTTP request has a type matching this list, the Enforcer will trigger a **Risk API** call even if the request contains a valid, unexpired cookie. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_sensitive_graphql_operation_types": "mutation subscription", # ... } ``` --- **`px_custom_check_sensitive_graphql_operation`** `function` > **Warning** > > This configuration is meant for cases that require more complex logic. We recommended you use [`px_sensitive_graphql_operation_types`](#px_sensitive_graphql_operation_types) and [`px_sensitive_graphql_operation_names`](#px_sensitive_graphql_operation_names) for most cases. A custom subroutine that returns a boolean indicating whether the request should be treated as sensitive given the GraphQL data that was extracted by the enforcer. If it returns `true`, the Enforcer will trigger a **Risk API** call even if the request contains a valid, unexpired cookie. Extracted values are available on: * `req.http.px-graphql:operation-type`: The GraphQL operation type (`query`, `mutation`, `subscription`) on the request. See [`px_sensitive_graphql_operation_types`](#px_sensitive_graphql_operation_types) for more information. * `req.http.px-graphql:operation-name`: The GraphQL operation name on the request. See [`px_sensitive_graphql_operation_names`](#px_sensitive_graphql_operation_names) for more information. **`Example`** ```php Example # PX_CUSTOM sub px_custom_check_sensitive_graphql_operation BOOL { if (req.http.px-graphql:operation-type ~ "mutation" || req.http.px-graphql:operation-name ~ "SensitiveOperation") { return true; } return false; } ``` --- ### Header data enrichment These configurations let you add headers to incoming requests with additional data. **`px_data_enrichment_header_name`** `string` — default: "" Adds a header to the incoming request with the configured header name and the JSON-stringified data enrichment object as the value. If empty or if data enrichment has not been enabled for your policy, no header will be set. To view available data and enable this feature, see [Data classification enrichment](/applications/data-classification-enrichment). **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_data_enrichment_header_name": "x-px-data-enrichment", # ... } ``` --- ### HUMAN Challenge customization These configurations let you customize the [HUMAN Challenge block page](/applications/create-a-human-challenge). **`px_css_ref`** `string` — default: "" A way to include a custom CSS file to the block page. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_css_ref": "https://example.com/custom.css", # ... } ``` --- **`px_js_ref`** `string` — default: "" A way to include custom JavaScript to the block page. This script will run after the default JavaScript scripts. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_js_ref": "https://example.com/custom.js", # ... } ``` --- **`px_custom_logo`** `string` — default: "" Adds a custom logo to the [HUMAN Challenge](/applications/create-a-human-challenge) block page via URL. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_custom_logo": "https://example.com/logo.png", # ... } ``` --- **`px_custom_block_on_error_message`** `string` — default: "" A custom message to display on the HUMAN Challenge block page when an error occurs (for example, if the Challenge script fails to load). When unset, a default message is shown. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_custom_block_on_error_message": "Please check your connection and try again.", # ... } ``` --- **`px_custom_block_page_content`** `function` — default: Empty Returns a string containing custom HTML for the [HUMAN Challenge](/applications/customize-challenge-look-feel) block page. Block page template values are available on `req.http.X-PX-template:*`. **`Example`** ```php Example # PX_CUSTOM sub px_custom_block_page_content STRING { declare local var.block-page-content STRING; set var.block-page-content = {"Access denied"}; return var.block-page-content; } ``` --- **`px_custom_web_block_page_response`** `function` — default: Empty Overrides the default web block response status and headers. **`Example`** ```php Example # PX_CUSTOM sub px_custom_web_block_page_response { set obj.status = 403; set obj.response = "Forbidden"; set obj.http.Content-Type = "text/html"; } ``` --- **`px_custom_rate_limit_block_page`** `function` — default: Empty Overrides the default rate-limit block response. **`Example`** ```php Example # PX_CUSTOM sub px_custom_rate_limit_block_page { set obj.status = 429; set obj.response = "Too Many Requests"; set obj.http.Content-Type = "text/html"; } ``` --- **`px_custom_create_advanced_blocking_response`** `function` — default: Empty Overrides the default Advanced Blocking Response (ABR) JSON block response status and headers. **`Example`** ```php Example # PX_CUSTOM sub px_custom_create_advanced_blocking_response { set obj.status = 403; set obj.response = "Forbidden"; set obj.http.Content-Type = "application/json"; } ``` --- ### Logging The [default installation method](/applications/fastly-vcl/v12/installation) adds Fastly logging endpoints automatically, but if you are manually installing the Enforcer instead, see our [logging endpoint setup instructions](/applications/fastly-vcl/v12/manual-installation#logging-endpoint-setup) for more information. **`px_async_activities_logger`** `string` — default: PX-Async-Activities Name of the logging endpoint used to send asynchronous activities. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_async_activities_logger": "Human-Async-Activities", # ... } ``` --- **`px_telemetry_activity_logger`** `string` — default: PX-Telemetry Name of the logging endpoint used to send telemetry activities. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_telemetry_activity_logger": "Human-Telemetry", # ... } ``` --- **`px_debug_syslog_name`** `string` — default: PX-Debug Name of the logging endpoint for debug logs when [`px_logger_severity`](#px_logger_severity) is `debug`. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_debug_syslog_name": "Human-Debug", # ... } ``` --- **`px_error_syslog_name`** `string` — default: PX-Error Name of the logging endpoint for error logs when [`px_logger_severity`](#px_logger_severity) is `error`. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_error_syslog_name": "Human-Error", # ... } ``` --- **`px_debug_probability`** `string` — default: 1 When logger severity is `debug`, one out of every **N** requests generates logs, where **N** is this value. `"1"` logs every request (1/1), while `"100"` logs about 1% of requests (1/100). **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_debug_probability": "100", # ... } ``` --- ### MCP protection These configurations let the Enforcer recognize and verify Model Context Protocol (MCP) requests. When enabled, the Enforcer extracts MCP JSON-RPC metadata such as the method, tool name, tool argument keys, and session id, then sends these to the **Risk API** for assessment. You can use these configurations in combination with other [AgenticTrust-related features](/applications/getting-started-with-agentictrust) to enforce Agentic traffic. The Enforcer treats a request as MCP traffic when its path matches [`px_agentic_trust_mcp_endpoint_path`](#px_agentic_trust_mcp_endpoint_path) after trailing slashes are removed. **`px_agentic_trust_enabled`** `boolean` — default: false Whether to enable AgenticTrust verification for MCP requests. * `true:` Enable MCP verification * `false:` Disable MCP verification **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_agentic_trust_enabled": "true", # ... } ``` --- **`px_agentic_trust_mcp_endpoint_path`** `string` — default: /mcp The MCP endpoint path used for AgenticTrust verification. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_agentic_trust_mcp_endpoint_path": "/mcp", # ... } ``` --- ### Monitored routes **`px_custom_monitored_routes`** `function` A set of endpoints to be monitored rather than blocked by the Enforcer, even when the Enforcer is in [`active_blocking`](#px_module_mode) mode. * Returns `true`: The request should behave as if the Enforcer is in [monitor mode](#px_module_mode), even when the module mode is `active_blocking`. * Returns `false` (default): The request should proceed with the usual enforcement flow. **`Example`** ```php Example # PX_CUSTOM sub px_custom_monitored_routes BOOL { if (req.url.path ~ {"^/monitored|^/experiments/"}) { return true; } return false; } ``` --- ### Override configs **`px_override_configs`** `function` — default: Empty > **Warning** > > Whenever possible, set configuration values in the `px_configs` table rather than adjusting them at runtime. Adjusts HUMAN configuration based on runtime values by modifying `req.http.px-cfg` header fields. See the `PX` VCL file for available `px-cfg` keys. **`Example`** ```php Example # PX_CUSTOM sub px_override_configs { if (client.geo.country_code == "GB") { set req.http.px-cfg:css-ref = "https://example.co.uk/style.css"; } } ``` --- ### Pre-clean The Enforcer stores configuration and metadata on request headers during the Fastly request lifecycle. Before origin requests in `vcl_miss` / `vcl_pass`, those headers are cleaned. Use pre-clean to copy values you still need. **`px_enable_pre_clean`** `boolean` — default: false Whether to invoke [`px_custom_pre_clean`](#px_custom_pre_clean). **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_enable_pre_clean": "true", # ... } ``` --- **`px_custom_pre_clean`** `function` — default: Empty Runs immediately before HUMAN metadata headers are removed from the backend request. **`Example`** ```php Example # PX_CUSTOM sub px_custom_pre_clean { set bereq.http.X-Human-Score = if(req.http.px-ctx:pass-reason, "0", "100"); set bereq.http.X-Human-Uuid = req.http.px-ctx:uuid; } ``` --- ### PXHD cookie **`px_secured_pxhd_enabled`** `boolean` — default: false The PX Hashed Data (PXHD or `_pxhd`) cookie links the first risk request with the browser activities as detected by the **Sensor** for better user tracking. It can also add more information that's shared between the HUMAN Collector, Enforcer, and Sensor. This configuration determines whether the [`Secure` cookie attribute](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies#block_access_to_your_cookies) is added when setting the PXHD cookie. See [Use of cookies & web storage](/applications/use-of-cookies-web-storage) for more information. * `true`: Adds the `Secure` attribute to the PXHD cookie * `false`: Does not add the `Secure` attribute to the PXHD cookie **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_secured_pxhd_enabled": "true", # ... } ``` --- ### Remote Configuration Remote Configuration lets you update your Enforcer's configuration from the HUMAN portal rather than interacting with the Enforcer package directly. > **Note** > > Remote Configuration requires access to the Fastly API and Fastly Dictionaries. These are included by default in the [default installation method](/applications/fastly-vcl/v12/installation). If you are manually installing the Enforcer instead, see our [manual installation instructions](/applications/fastly-vcl/v12/manual-installation#remote-configuration) for more information. **`px_logger_auth_token`** `string` — required, 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`** ```php Example # PX_CONFIGS table px_configs { # ... "px_logger_auth_token": "", # ... } ``` --- **`px_remote_config_auth_token`** `string` — required, default: "" The token used to authenticate the Enforcer with the HUMAN Remote Configuration service. [Contact HUMAN](/applications/human-customer-support) to receive your token. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_remote_config_auth_token": "", # ... } ``` --- **`px_remote_config_id`** `string` — required, default: "" The ID associated with the Remote Configuration. [Contact HUMAN](/applications/human-customer-support) to receive your ID. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_remote_config_id": "", # ... } ``` --- **`px_fastly_api_token`** `string` — required, default: "" > **Warning** > > Store this value in the `px_private` private dictionary, not in the `px_configs` table. Fastly API key with permission to update the Fastly service (global scope for that service). Create a token via the [Fastly Console](https://docs.fastly.com/en/guides/using-api-tokens#creating-api-tokens), [CLI](https://www.fastly.com/documentation/reference/cli/auth-token/create/), or [API](https://www.fastly.com/documentation/reference/api/auth-tokens/#create-token). **`Example`** ```shell Example # must belong to the dictionary named px_private curl https://api.fastly.com/service//dictionary//item \ -H 'Fastly-Key: ' \ -d 'item_key=px_fastly_api_token&item_value=' ``` --- **`px_enforcer_config_rdata_id`** `string` — required, default: "" Dictionary ID for the `px_enforcer_config_rdata` dictionary. Look it up via [CLI](https://www.fastly.com/documentation/reference/cli/dictionary/describe/) or [API](https://www.fastly.com/documentation/reference/api/dictionaries/dictionary/#get-dictionary). **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "px_enforcer_config_rdata_id": "", # ... } ``` --- ### Response custom parameters These configurations enrich async activities with values derived from the origin response. **`px_custom_add_response_custom_parameters`** `function` — default: Empty A subroutine that uses the origin response to set up to ten fields: custom parameters `11` through `20`. These are merged into `page_requested`, `additional_s2s`, and simulated block activities. There is a limit of ten response custom parameters. Invoked in `vcl_deliver` after the backend response is available on `resp`. On Fastly VCL, set them on request headers named `px-custom-param:`. **`Example`** ```php Example # PX_CUSTOM sub px_custom_add_response_custom_parameters { set req.http.px-custom-param:11 = resp.http.X-Response-Id; set req.http.px-custom-param:12 = std.itoa(resp.status); } ``` --- ### Risk backend overwrite **`px_set_custom_risk_backend_overwrite`** `function` — default: Empty Changes the backend used for **Risk API** requests (for example, to adjust timeouts by region). Define any backends other than `PX_API` yourself. Called during `vcl_pass` when a Risk API request is needed. **`Example`** ```php Example # PX_CUSTOM backend PX_RISK_API_LOW_TIMEOUT { # ... } sub px_set_custom_risk_backend_overwrite { if (server.region !~ {"US"}) { set req.backend = PX_RISK_API_LOW_TIMEOUT; } } ``` --- ### Sensitive headers removal **`px_custom_unset_sensitive_headers`** `function` 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. Called before Enforcer backend requests. Unset headers from `bereq`. If you do not customize this subroutine, `Cookie` and `Cookies` are removed by default. **`Example`** ```php Example # PX_CUSTOM sub px_custom_unset_sensitive_headers { unset bereq.http.Cookie; unset bereq.http.Cookies; unset bereq.http.X-Sensitive-Token; } ``` --- ### Sensitive routes **`px_custom_check_sensitive_route`** `function` A set of prefixes for all routes that should be considered sensitive. * Returns `true`: The request should always trigger a Risk API call, even with a valid cookie. * Returns `false` (default): The request should proceed with the usual enforcement flow. **`Example`** ```php Example # PX_CUSTOM sub px_custom_check_sensitive_route BOOL { if (req.url.path ~ {"^/login|^/checkout"}) { return true; } return false; } ``` --- ### 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`** ```php Example # PX_CONFIGS table px_configs { # ... "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`** ```php Example # PX_CONFIGS table px_configs { # ... "px_jwt_cookie_user_id_field_name": "nameID", # ... } ``` --- **`px_jwt_header_name`** `string` — default: "" The name of the header that contains the JWT token that HUMAN should extract user identifiers from. **`Example`** ```php Example # PX_CONFIGS table px_configs { # ... "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`** ```php Example # PX_CONFIGS table px_configs { # ... "px_jwt_header_user_id_field_name": "sub", # ... } ``` --- **`px_custom_extract_jwt_additional_fields`** `function` — default: Empty The field names in the JWT object that should be extracted and reported in addition to the user ID. On Fastly VCL, implement this as a subroutine that returns additional JWT fields as a string of `"fieldName":"fieldValue"` pairs. The decoded JWT is available on `req.http.px-jwt:Token-Decoded`. **`Example`** ```php Example # PX_CUSTOM sub px_custom_extract_jwt_additional_fields STRING { declare local var.px-additional-key-value-pairs STRING; if (req.http.px-jwt:Token-Decoded ~ {"("exp":"[^"]*")"}) { set var.px-additional-key-value-pairs = re.group.1; } if (req.http.px-jwt:Token-Decoded ~ {"("iss":"[^"]*")"}) { set var.px-additional-key-value-pairs = if (var.px-additional-key-value-pairs, var.px-additional-key-value-pairs ",", "") re.group.1; } return var.px-additional-key-value-pairs; } ``` ---