Configuration

📘

PX_CONFIGS and PX_CUSTOM

Enabling and configuring Enforcer features may require changes to the PX_CONFIGS VCL file, the PX_CUSTOM VCL file, or both. Each code sample below includes the name of the relevant VCL file where the changes should be made. See the instructions for each configuration below for more details.

Required Configurations

px_app_id

The application ID. Required to initialize the Enforcer.

# PX_CONFIGS
table px_configs {
    "px_app_id": "<APP_ID>",
    # ...
}

px_auth_token

The token used for authorization with the Human Security backend. Required to initialize the Enforcer.

# PX_CONFIGS
table px_configs {
    # ...
    "px_auth_token": "<AUTH_TOKEN>",
    # ...
}

px_cookie_secret

The secret used to decrypt the risk cookie. Required to initialize the Enforcer.

# PX_CONFIGS
table px_configs {
    # ...
    "px_cookie_secret": "<COOKIE_SECRET>",
    # ...
}

Cookie secret rotation:

In case you would like to generate and use a new cookie secret, the enforcer will have to support both, old and new cookie secrets to avoid multiple 'cookie decryption failed' errors.
In your px_configs table, adjust the px_cookie_secret value to be the new generated cookie secret, and add an additional field name px_cookie_secret_old the holds the previous cookie secret value.

# PX_CONFIGS
table px_configs {
    # ...
    "px_cookie_secret": "<NEW_COOKIE_SECRET>",
    "px_cookie_secret_old": "<OLD_COOKIE_SECRET>"
    # ...
}

px_fastly_api_token

🚧

This configuration should be added to the px_private private dictionary, and NOT the px_configs table in the PX_CONFIGS VCL file.

📘

This configuration is required when enabling the Remote Configuration feature. This allows HUMAN to periodically update the Remote Config values in the px_remote_config_rdata dictionary.

The Fastly API key with permissions to make changes to the Fastly service. (The scope must be global, but it only needs permissions for the specific Fastly service.) You can create an API token via the Fastly Console, CLI, or API.

# note that the <dictionary_id> must be the ID belonging to the dictionary named px_private
curl https://api.fastly.com/service/<service_id>/dictionary/<dictionary_id>/item  \
    -H 'Fastly-Key: <fastly_api_token>' \
    -d 'item_key=px_fastly_api_token&item_value=<fastly_api_token>'

px_remote_config_id

📘

This configuration is required when enabling the Remote Configuration feature.

The ID of the Remote Config associated with your Fastly Service.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_remote_config_id": "<REMOTE_CONFIG_ID>",
    # ...
}

px_remote_config_auth_token

📘

This configuration is required when enabling the Remote Configuration feature.

A secret token to use in the authentication of incoming Remote Config update requests.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_remote_config_auth_token": "<REMOTE_CONFIG_AUTH_TOKEN>",
    # ...
}

px_enforcer_config_rdata_id

📘

This configuration is required when enabling the Remote Configuration feature.

The dictionary ID associated with the px_enforcer_config_rdata dictionary. You can determine the dictionary ID via CLI or API.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_enforcer_config_rdata_id": "<DICTIONARY_ID>",
    # ...
}

Generic Enforcer Configurations

px_module_enabled

This boolean serves as an on/off switch for the entire module, providing a way to enable and disable all Enforcer capabilities quickly and easily.

Default: "true"

# PX_CONFIGS
table px_configs {
    # ...
    "px_module_enabled": "false",
    # ...
}

px_module_mode

This feature controls the behavior of the enforcer by changing how it executes certain parts of the workflow. Most notably, different modes allow for analysis and fine-tuning of the enforcer behavior without serving block pages that affect end users.

Possible values:

• "monitor" - the enforcer will perform all functions without returning block responses
• "active_blocking" - the enforcer will return block responses when needed

Default: "monitor"

# PX_CONFIGS
table px_configs {
    # ...
    "px_module_mode": "active_blocking",
    # ...
}

px_s2s_timeout

🚧

Note

Adding this value in the px_configs table will not have any effect. Instead, this value can be set in the PX_CONFIGS VCL file under the PX_API backend definition. The connect_timeout, first_byte_timeout, and between_bytes_timeout can all be set to this same value.

The maximum time in milliseconds to wait for the risk API request. If this timeout is reached, the original request will be allowed to pass (fail open).

Default: 1000ms

# PX_CONFIGS
backend PX_API {
    # ...
    .connect_timeout = 2000ms;
    .first_byte_timeout = 2000ms;
    .between_bytes_timeout = 2000ms;
    # ...
}

px_custom_client_ip_extraction

By default, the value from the Fastly-Client-IP header is reported as the IP. However, if this value is inaccurate, the enforcer can extract the IP from the request using the logic defined in this subroutine. Returning an empty string from the subroutine means the enforcer will use the default Fastly-Client-IP header.

Default: Returns ""

Example:

# PX_CUSTOM
sub px_custom_client_ip_extraction STRING {
    if (req.http.client-ip-header) {
        return req.http.client-ip-header;
    }
    return "";
}

px_custom_cookie_header

🚧

Previously, this was done via the px_custom_cookie_header_enabled configuration and px_custom_cookie_header subroutine. Both have since been deprecated.

The Enforcer attempts to extract the HUMAN cookies from the Cookie header. If the HUMAN cookies are transferred on a header other than Cookie, the header name should be configured here.

Default: "x-px-cookies"

# PX_CONFIGS
table px_configs {
    # ...
    "px_custom_cookie_header": "custom-human-cookies",
    # ...
}

px_secured_pxhd_enabled

Whether the PXHD cookie set on the HTTP response should include the Secure attribute.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_secured_pxhd_enabled": "true",
    # ...
}

px_block_size_exceeded_15k_headers_size

Due to Fastly size limitations, large requests may sometimes result in 413 HTTP errors. If this error is received during a Risk API request, the default Enforcer behavior is to allow the request to pass to the origin. However, if this configuration is enabled, Risk API requests resulting in a 413 response will be blocked instead.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_block_size_exceeded_15k_headers_size": "true",
    # ...
}

px_add_block_result_header

Whether to include the px-ctx:block-result header with value "0" or "1" to origin requests. A header value of "0" means that HUMAN determined the request should pass, while "1" means HUMAN determined the request should be blocked.

Note: This configuration is typically used while in monitor mode for testing and validation.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_add_block_result_header": "true",
    # ...
}

px_additional_activity_handler

px_additional_activity_handler_enabled

Whether to invoke the px_custom_additional_activity_handler subroutine.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_additional_activity_handler_enabled": "true",
    # ...
}

px_custom_additional_activity_handler

A subroutine where custom logic can be performed after sending the page_requested or block activity at the end of the request flow. HUMAN metadata about the request can be found on the req.http.px-ctx header. This subroutine is called in vcl_deliver.

Default: Empty

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");

    declare local var.data_enrichment_validated STRING;
    set var.data_enrichment_validated = if(req.http.px-ctx:de-validated == "1", "true", "false");

    log "syslog " req.service_id " CustomLoggingEndpoint :: Score: " var.score ", Data Enrichment: " req.http.px-ctx:data-enrichment ", Data Enrichment Validated: " var.data_enrichment_validated;
}

px_pre_clean

The HUMAN Enforcer stores configurations and metadata on the client request HTTP headers to maintain access to them throughout the Fastly request lifecycle. During invocations of vcl_pass and vcl_miss that happen after the HUMAN enforcement flow, the px_miss and px_pass subroutines invoke logic to clean these HUMAN metadata headers from the backend request to your origin. If desired, you can configure a custom subroutine to run immediately before these HUMAN metadata headers are removed.

px_enable_pre_clean

Whether to invoke the px_custom_pre_clean subroutine.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_enable_pre_clean": "true",
    # ...
}

px_custom_pre_clean

This custom subroutine runs immediately before the HUMAN metadata headers are removed from the backend request. This subroutine is called in vcl_miss and vcl_pass.

Default: Empty

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;
}

px_set_custom_risk_backend_overwrite

A custom subroutine that is called during the Risk API flow to change the backend used for the Risk API request. (This is most often done to adjust the backend timeouts in different regions.) Any HUMAN backends other than PX_API must be defined. If left empty, the default PX_API backend is used. The subroutine is called during vcl_pass only when a Risk API request is necessary.

Default: Empty

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;
    }
}

px_custom_add_custom_parameters

This subroutine defines custom parameters that are sent to HUMAN on the Risk API and asynchronous activities. The custom parameters must be set in the HUMAN Portal before implementing this subroutine.

Custom parameters can be added by setting a client request header with the name px-custom-param:<NUMBER>, where <NUMBER> corresponds to the custom parameter number between 1-10.

Default: Empty

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";
    set req.http.px-custom-param:4 = "4";
    set req.http.px-custom-param:5 = "5";
    set req.http.px-custom-param:6 = "6";
}

px_custom_activity_headers

Fastly VCL limitations prevent the HUMAN Enforcer from reporting all request headers on the async activities. If there are additional headers that should be reported, they can be added to the async activities by implementing this custom subroutine.

The subroutine should return a string representing all headers that should be added to the async activities. Every header should be added in the following form, replacing <header_name> with the desired header. Note: The leading comma is very important!

",{%22name%22: %22<header name>%22, %22value%22: " if(req.http.<header name>, "%22" json.escape(req.http.<header name>) "%22", "null") "}"

Default: Returns ""

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") "}"
        ",{%22name%22: %22my-header-2%22, %22value%22: " if(req.http.my-header-2, "%22" json.escape(req.http.my-header-2) "%22", "null") "}"
        ",{%22name%22: %22my-header-3%22, %22value%22: " if(req.http.my-header-3, "%22" json.escape(req.http.my-header-3) "%22", "null") "}";
    return var.ret;
}

px_override_configs

🚧

Whenever possible, configuration values should be set in the px_configs table rather than adjust them during runtime.

A custom subroutine that allows for adjusting the HUMAN configuration based on runtime values. See the PX VCL file for the list of req.http.px-cfg configuration header values that can be modified.

Default: Empty

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";
    }
}

First Party Configurations

px_first_party_enabled

To prevent suspicious or unwanted behavior on the client side, some browsers or extensions (e.g., adblockers) may deny the frontend JavaScript code from making requests to other domains. This prevents the Human Security sensor from making requests to the Human Security backends, which greatly limits Human Security's detection capabilities. To avoid this problem, first party enables the enforcer to be used as a proxy for Human Security servers, and to serve content to the browser from a first party endpoint (i.e., an endpoint on the customer’s domain).

Default: "true"

# PX_CONFIGS
table px_configs {
    # ...
    "px_first_party_enabled": "false",
    # ...
}

px_custom_first_party_prefix

To enable first party mode, you will first need to follow the installation steps here, below the Installing the HumanFirstParty Lambda section.

By default, first party endpoints always begin with the application ID without the initial "PX". For example, if the application ID is PX12345678, then all first party routes will take the form /12345678/*. This configuration sets a custom prefix for first party routes to use in addition to the default prefix. When configured, the enforcer will respond to first party requests with endpoints matching the patterns /<px_custom_first_party_prefix>/init.js, /<px_custom_first_party_prefix>/xhr/*, and /<px_custom_first_party_prefix>/captcha/*.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
     "px_custom_first_party_prefix": "/custom-prefix",
    # ...
}

px_custom_first_party_sensor_endpoint

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

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_custom_first_party_sensor_endpoint": "/human_sensor",
    # ...
}

px_custom_first_party_xhr_endpoint

To enable first party mode, you will first need to follow the installation steps here, below the Installing the HumanFirstParty Lambda section.

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

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_custom_first_party_xhr_endpoint": "/human_xhr",
    # ...
}

px_custom_first_party_captcha_endpoint

To enable first party mode, you will first need to follow the installation steps here, below the Installing the HumanFirstParty Lambda section.

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

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_custom_first_party_captcha_endpoint": "/human_captcha",
    # ...
}

px_custom_first_party_response_modifier

A custom subroutine for modifications to first party responses. This subroutine is called in vcl_deliver, so changes to the response should be made with the client response object.

Default: Empty

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";
}

Logging Configurations

px_async_activities_logger

📘

See the instructions on adding the required logging endpoints to your Fastly service here.

The name of the logging endpoint used to send asynchronous activities.

Default: "PX-Async-Activities"

# PX_CONFIGS
table px_configs {
    # ...
    "px_async_activities_logger": "Human-Async-Activities",
    # ...
}

px_telemetry_activity_logger

📘

See the instructions on adding the required logging endpoints to your Fastly service here.

The name of the logging endpoint used to send telemetry activities.

Default: "PX-Telemetry"

# PX_CONFIGS
table px_configs {
    # ...
    "px_telemetry_activity_logger": "Human-Telemetry",
    # ...
}

px_logger_severity

📘

See the instructions on adding the required logging endpoints to your Fastly service here.

The verbosity of the logs generated by the enforcer.

Possible values:

• "none" - No logs will be generated
• "error" - Sparse logs will be sent to the logging endpoint name set by the px_error_syslog_name configuration only when errors occur
• "debug" - Detailed logs will be sent to the logging endpoint name set by the px_debug_syslog_name configuration (not advisable for production environments)

Default: "error"

# PX_CONFIGS
table px_configs {
    # ...
    "px_logger_severity": "debug",
    # ...
}

px_debug_syslog_name

📘

See the instructions on adding the required logging endpoints to your Fastly service here.

The name of the logging endpoint to which debug logs will be sent.

Default: "PX-Debug"

# PX_CONFIGS
table px_configs {
    # ...
    "px_debug_syslog_name": "Human-Debug",
    # ...
}

px_error_syslog_name

📘

See the instructions on adding the required logging endpoints to your Fastly service here.

The name of the logging endpoint to which error logs will be sent.

Default: "PX-Error"

# PX_CONFIGS
table px_configs {
    # ...
    "px_error_syslog_name": "Human-Error",
    # ...
}

px_debug_probability

📘

See the instructions on adding the required logging endpoints to your Fastly service here.

Sometimes, logging every request to the service is impractical, and a random sample of logs is preferable. This configuration can be used to specify the likelihood of a log being generated for an incoming request. One out of every X requests will result in logs, where X is the number configured here. That is, setting this value to "2" means 1 out of every 2 requests, or a 50% chance; setting "100" means 1 out of every 100 requests, or a 1% chance.

Default: "1"

# PX_CONFIGS
table px_configs {
    # ...
    "px_debug_probability": "100",
    # ...
}

Filtering Configurations

px_custom_filter_by_extension

Human Security does not enforce static assets such as images and documents. To prevent unnecessary API calls to Human Security servers and needless computation, the enforcer filters all requests with a valid static file extension.

A custom subroutine that returns a boolean value. A return value of true means the request should be filtered from the enforcement flow due to the file extension in its URL. A return value of false means the request should proceed with the usual enforcement flow.

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

Filters out requests according to their HTTP method, avoiding unnecessary traffic in the enforcer verification flow and reducing operating costs.

A custom subroutine that returns a boolean value. A return value of true means the request should be filtered from the enforcement flow due to its HTTP method. A return value of false means the request should proceed with the usual enforcement flow.

Default: Returns false.

Example:

# PX_CUSTOM
sub px_custom_filter_by_http_method BOOL {
    if (req.request ~ "(?i)(GET|POST|HEAD)$") {
        return true;
    }
    return false;
}

px_custom_filter_by_ip

Filters out requests according to their IP address, avoiding unnecessary traffic in the enforcer verification flow and reducing operation costs.

A custom subroutine that returns a boolean value. A return value of true means the request should be filtered from the enforcement flow due to its IP. A return value of false means the request should proceed with the usual enforcement flow.

📘

Using Fastly ACLs

The easiest way to implement this subroutine is to declare and use a Fastly Access Control List (ACL) as shown in the example below. For more information, see here.

Default: Returns false.

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

A custom subroutine that returns a boolean value. A return value of true means the request should be filtered from the enforcement flow due to its route. A return value of false means the request should proceed with the usual enforcement flow.

Default: Returns false.

Example:

# PX_CUSTOM
sub px_custom_filter_by_route BOOL {
     if (req.url.path ~ {"^/prefix|^/exact/match$"}) {
        return true;
    }
    return false;
}

px_custom_filter_by_user_agent

A custom subroutine that returns a boolean value. A return value of true means the request should be filtered from the enforcement flow due to its user agent. A return value of false means the request should proceed with the usual enforcement flow.

Default: Returns false.

Example:

# PX_CUSTOM
sub px_custom_filter_by_user_agent BOOL {
    if (req.http.User-Agent ~ {"Filtered_UA"}) {
        return true;
    }
    return false;
}

px_filter_on_cache_hit_enabled

Filters out requests if the requested resource results in a cache HIT at the edge POP. If shielding is enabled, a request that results in a cache MISS at the edge POP will undergo enforcement even if it results in a cache HIT at the shield POP. For more information about Fastly Shielding, see here.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_filter_on_cache_hit_enabled": "true",
    # ...
}

Special Routes Configurations

px_custom_enforced_routes

Customers may want certain, but not all, endpoints to be enforced by HUMAN, even when the Enforcer is in monitor mode. This custom subroutine returns a boolean value indicating whether the request is an enforced route.

A return value of true means the request should go through the full enforcer workflow, including blocking when necessary. That is, even when the enforcer is in monitor mode, these requests will behave as if in active blocking mode. A return value of false means the request should proceed with the usual flow based on the module mode.

Default: Returns false.

Example:

# PX_CUSTOM
sub px_custom_enforced_routes BOOL {
    if (req.url.path ~ {"^/enforced|^/non/monitored/route$"}) {
        return true;
    }
    return false;
}

px_custom_monitored_routes

Enables certain endpoints to be monitored rather than enforced by HUMAN, even when the enforcer is in active blocking mode.

A return value of true means the request should go through the enforcement flow in monitor mode. That is, even when the enforcer is in active_blocking mode, these requests will behave as if in monitor mode. A return value of false means the request should proceed with the usual flow based on the module mode.

Default: Returns false.

Example:

# PX_CUSTOM
sub px_custom_monitored_routes BOOL {
    if (req.url.path ~ {"^/monitored|^/non/enforced/route$"}) {
        return true;
    }
    return false;
}

px_bypass_monitor_header

When enabling the enforcer for the first time, it is recommended to do so in monitor mode to collect data before actually starting to block user requests. Prior to switching the module mode to active_blocking entirely, it's also crucial to verify that the full blocking flow works as expected. This feature activates the full blocking flow even while in monitor mode if a particular header is present on the request.

Default: "x-px-block"

# PX_CONFIGS
table px_configs {
    # ...
    "px_bypass_monitor_header": "x-bypass-monitor-mode",
    # ...
}

px_custom_check_sensitive_route

Certain endpoints may require more stringent protection from bot attacks (e.g., endpoints that execute payments or handle personal information). In these cases, this subroutine can be implemented. If the subroutine returns true, a Risk API call will be made even if the request contains a valid, unexpired cookie. If the subroutine returns false, the enforcer will use the value found in the valid, unexpired cookie.

Default: Returns false.

Example:

# PX_CUSTOM
sub px_custom_check_sensitive_route BOOL {
    if (req.url.path ~ {"^/login"}) {
        return true;
    }
    return false;
}

px_sensitive_headers

The HUMAN detector requires information about the HTTP request as part of its bot detections. Certain headers may contain information that should not be forwarded to other servers, including the HUMAN backend. Setting these configurations will remove the headers from requests sent to HUMAN.

Note: The Cookie header is always removed from backend requests to HUMAN whether this feature is enabled or not.

px_sensitive_headers_enabled

Whether to invoke the px_custom_unset_sensitive_headers function to unset sensitive headers prior to requests to the HUMAN backend.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_sensitive_headers_enabled": "true",
    # ...
}

px_custom_unset_sensitive_headers

A custom subroutine that is invoked prior to requests to the HUMAN backend to remove sensitive headers. This subroutine is called in vcl_pass, so headers should be unset from the bereq object.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_unset_sensitive_headers {
    unset bereq.http.X-Sensitive-Token;
}

Custom Blocking Configurations

px_css_ref

Provides a way to include an additional custom .css file to add to the captcha page.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_css_ref": "https://www.example.com/custom_style.css",
    # ...
}

px_js_ref

Provides a way to include a custom JS script to add to the captcha page. This script will run after the default JS scripts.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_js_ref": "https://www.example.com/custom_script.js",
    # ...
}

px_custom_logo

Adds a custom logo to the captcha page that will be shown to users. This aligns the captcha page with the customer's brand.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_custom_logo": "https://www.example.com/custom_logo.png",
    # ...
}

px_custom_block_page_content

A custom subroutine that returns a string representing the HTML response body to be returned on the block response. Returning an empty string will result in the default HTML block page.

Default: Returns ""

Example:

# PX_CUSTOM
sub px_custom_create_block_page STRING {
    return "<!DOCTYPE html><html><head><title>Access Denied</title></head><body><h1>You have been blocked.</h1></body></html>";
}

px_custom_create_synthetic_web_response

A subroutine that allows for customization of the HTML browser captcha response. This is applicable to the HTML captcha response only! This subroutine is called in vcl_error, so changes to the response should be made with the cache object type and the synthetic statement.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_web_block_page_response {
    set obj.http.Is-Web-Block = "1";
}

px_custom_rate_limit_block_page

A subroutine that allows for customizing the rate limit block response. This will be invoked only if HUMAN has decided to return a 429 Too Many Requests response. This subroutine is called in vcl_error, so changes to the response should be made with the cache object type and the synthetic statement.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_rate_limit_block_page {
    set obj.http.Response-Header = "Value";
}

px_advanced_blocking_response_enabled

In specific cases (e.g., XHR post requests), a full captcha page render might not be an option. In such cases the advanced blocking response returns a JSON object containing all the information needed to render a customized captcha challenge implementation - be it a popup modal, a section on the page, etc. This allows for flexibility and customizability in terms of how the captcha pages are displayed.

Default: "true"

# PX_CONFIGS
table px_configs {
  # ...
  "px_advanced_blocking_response_enabled": "false",
  # ...
}

px_custom_create_advanced_blocking_response

A subroutine that allows for customization of the JSON captcha response. This is applicable to the JSON captcha response only! This subroutine is called in vcl_error, so changes to the response should be made with the cache object type and the synthetic statement.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_create_advanced_blocking_response {
    set obj.status = 401;
    set obj.response = "Unauthorized";
    set obj.http.Response-Header = "Value";
}

px_custom_web_block_page_response

A subroutine that allows for customization of the HTML browser captcha response. This is applicable to the HTML captcha response only! This subroutine is called in vcl_error, so changes to the response should be made with the cache object type and the synthetic statement.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_web_block_page_response {
    set obj.http.Is-Web-Block = "1";
}

CORS Configurations

CORS (Cross-Origin Resource Sharing) is a mechanism that enables the server to indicate when a request contains cross-origin resources. It does so by adding special HTTP headers to the request, which permits the browser to load these resources. Without these headers, the browser may block requests to these resources for security reasons.

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.

In the HUMAN Enforcer, CORS behavior must be configured to address both simple requests (without preflight) and more complex ones (with preflight).

px_cors_support_enabled

Enabling CORS support via this configuration will have the following effects:

• It will automatically add the following default CORS response headers to block responses resulting from CORS requests.

Access-Control-Allow-Origin: <ORIGIN_REQUEST_HEADER_VALUE>
Access-Control-Allow-Credentials: true

• It will permit enabling the px_cors_create_custom_block_response_headers configuration, which will allow for customizing the block response headers via a custom function.
• It will permit enabling the px_cors_preflight_request_filter_enabled and px_cors_custom_preflight_handler configurations, which allow for filtering and custom handling of preflight requests.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_cors_support_enabled": "true",
    # ...
}

px_cors_preflight_request_filter_enabled

🚧

Note

If both the px_cors_preflight_request_filter_enabled and px_cors_preflight_handler_enabled are set to true, the custom preflight handler will take priority and invoke the px_custom_cors_preflight_handler from the VCL error stage.

This configuration disables enforcement for CORS preflight requests. When this configuration is set to true, CORS preflight requests will be filtered from the enforcer flow. That is, they will pass through the enforcer flow without triggering detection or block responses.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_cors_preflight_request_filter_enabled": "true",
    # ...
}

px_cors_preflight_handler

If a more customized approach is needed for handling CORS preflight requests, these configurations can be set to define the desired behavior.

px_cors_preflight_handler_enabled

🚧

Note

If both the px_cors_preflight_request_filter_enabled and px_cors_preflight_handler_enabled are set to true, the custom preflight handler will take priority and invoke the px_custom_cors_preflight_handler from the VCL error stage.

Whether to invoke the px_custom_cors_preflight_handler subroutine. This is done by triggering a specific error with an error statement.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_cors_preflight_handler_enabled": "true",
    # ...
}

px_custom_cors_preflight_handler

A custom subroutine for defining the desired CORS preflight response. This subroutine is called in vcl_error, so changes to the response should be made with the cache object type and the synthetic statement.

Default: Empty

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";
}

px_cors_create_custom_block_response_headers

If the default CORS response headers are not sufficient, these configurations can be used to completely customize the headers that should be added to all block responses resulting from CORS requests. If this function is defined, the default headers will not be added; instead, the custom subroutine will be invoked.

px_cors_create_custom_block_response_headers_enabled

Whether to invoke the px_custom_cors_set_custom_block_response_headers subroutine. If set to "true", the px_custom_cors_set_custom_block_response_headers subroutine will be invoked on block responses to CORS requests. If set to "false", then the default CORS response headers (Access-Control-Allow-Origin: req.http.Origin and Access-Control-Allow-Credentials: true) will be added to block responses.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_cors_create_custom_block_response_headers_enabled": "true",
    # ...
}

px_custom_cors_set_custom_block_response_headers

A custom subroutine for adding any desired headers to block responses to CORS requests. This subroutine is called in vcl_error, so changes to the response should be made with the cache object type.

Default: Empty

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";
}

GraphQL Configurations

px_graphql_enabled

Whether the enforcer should attempt to parse and report information about GraphQL operations on incoming requests.

Default: "true"

# PX_CONFIGS
table px_configs {
    # ...
    "px_graphql_enabled": "false",
    # ...
}

px_custom_is_graphql_route

A custom subroutine that returns a boolean indicating whether the request should be parsed as a GraphQL request. If px_graphql_enabled is "true" and this subroutine returns true, the enforcer will attempt to parse the request body for GraphQL data. If this subroutine returns false, the enforcer will not attempt to extract GraphQL data.

Default:

# PX_CUSTOM
sub px_custom_is_graphql_route BOOL {
    if (req.url.path ~ {"/graphql"}) {
        return true;
    }
    return false;
}

px_sensitive_graphql_operation_types

A space-separated list of operation types (query, mutation, or subscription) that should be considered sensitive. If one or more GraphQL operations on an HTTP request is found to have a type matching the list configured here, it will trigger a Risk API call even if the request contains a valid, unexpired cookie.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_sensitive_graphql_operation_types": "mutation subscription",
    # ...
}

px_sensitive_graphql_operation_names

A space-separated list of operation names that should be considered sensitive. If one or more GraphQL operations on an HTTP request is found to have a name matching the list configured here, it will trigger a Risk API call even if the request contains a valid, unexpired cookie.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_sensitive_graphql_operation_names": "SensitiveOperation1 SensitiveOperation2",
    # ...
}

px_custom_check_sensitive_graphql_operation

📘

Note

This configuration should be used in cases that require more complex logic than allowed by the px_sensitive_graphql_operation_types and px_sensitive_graphql_operation_names configurations.

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.

Extracted data:

• req.http.px-graphql:operation-type - The GraphQL operation type (query, mutation, subscription) on the request
• req.http.px-graphql:operation-name - The GraphQL operation name on the request

Default: Returns false

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;
}

px_custom_extract_graphql_keywords

📘

A custom subroutine for extracting keywords from request body or GraphQL query and returning them as a string, the returned value would be sent to the Human Security servers for detection.

In order to extract GraphQL keywords, implement the px_custom_extract_graphql_keywords custom subroutine in PX_CUSTOM.vcl
The returned value should be a STRING containing the extracted keywords separated by commas (with no spaces in between)

🚧

Due to preformance reasons, we are highly recommend to use regex comparison to extract the keywords

Example:
Default: return ""

# PX_CUSTOM.vcl
sub px_custom_extract_graphql_keywords STRING {

    #Extract graphQL query using the snippet below:
    declare local var.graphql_query STRING;
    set var.graphql_query = "";

    if (std.strstr(req.body, "%22" "query" "%22") ~ {"(?U).*:[\s]*"((\s)|(\\n))*?(.*)[^a-zA-Z\d](.*)[^a-zA-Z\d](.*)""}) {
        if (re.group.4 == "query") {
          set var.graphql_query = re.group.6;
        }
    }
    # Example:
    #Extracting two keywords, keyword1 and keyword2 from graphql query
    # The query:
    # query GetID {
    #   keyword1344keyword2 {
    #        id
    #       }
    #  }
     if (var.graphql_query ~ {"^keyword1\d{2,4}keyword2"}) {
        return "keyword1,keyword2";
        }
   return ""

Account Defender Configurations

px_jwt_cookie_name

The name of the cookie that contains the JWT token from which user identifiers should be extracted.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_jwt_cookie_name": "auth",
    # ...
}

px_jwt_cookie_user_id_field_name

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

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_jwt_cookie_user_id_field_name": "nameID",
    # ...
}

px_jwt_header_name

The name of the header that contains the JWT token from which user identifiers should be extracted.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_jwt_header_name": "x-jwt-authorization",
    # ...
}

px_jwt_header_user_id_field_name

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

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_jwt_header_user_id_field_name": "sub",
    # ...
}

px_custom_extract_jwt_additional_fields

A custom subroutine that extracts any additional desired field names and values in the JWT object. The subroutine should set the client request header px-jwt:additional-fields to a valid JSON string in the format of {"<field_name_1>": "<field_value_1>", "field_name_2": "field_value_2"}. The values can be extracted from the decoded JWT token available on the header req.http.px-jwt:token-decoded.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_extract_jwt_additional_fields {
    declare local var.fieldValue1 STRING;
    if (req.http.px-jwt:token-decoded ~ {"("fieldName1":"[^"]*")"}) {
        set var.fieldValue1 = if(re.group.1, re.group.1, "");
    }
    set req.http.px-jwt:additional-fields = "{\"fieldName1\":\"" var.fieldValue1 "\"}";
}

Credential Intelligence Configurations

The Credential Intelligence product allows customers to safeguard their users' login information by leveraging HUMAN's database of compromised credentials.

The enforcer plays a major role in the Credential Intelligence process as it is in charge of extracting and sending to Credential Intelligence an anonymized, hashed, and salted version of the credentials in real-time and provides a real-time response whether the credentials are compromised or not. (This requires enablement of the Data Enrichment feature.)

px_login_credentials_extraction_enabled

This enables the extraction and reporting of credentials from the Enforcer. This must be set to "true" to enable the Credential Intelligence product.

Default: false

# PX_CONFIGS
table px_configs {
    # ...
    "px_login_credentials_extraction_enabled": "true",
    # ...
}

px_login_credentials_extraction

A table detailing the settings for each credential endpoint. Each element in the array is an object representing a distinct endpoint to which credentials are sent, and includes information about how to identify these credential-bearing requests and how to extract the credentials from the request.

For each endpoint, define a credential entpoint suffix (e.g., _0, _1) and add this suffix to the keys corresponding to that endpoint (e.g., path_0, method_0, path_1, method_1). For more information, see the px_custom_is_login_request subroutine.

This table exists in the PX_CUSTOM VCL file. This table can be filled in or it may be removed in favor of a Fastly dictionary with the same name.

Default: Empty

# PX_CUSTOM
table px_login_credentials_extraction {
    # endpoint _0
    "path_0": "/login",
    "protocol_0": "v2",
    "method_0": "post",
    "sent_through_0": "body",
    "pass_field_0": "password",
    "user_field_0": "username",

    # endpoint _1
    "path_1": "/sign-up",
    "protocol_1": "multistep_sso",
    "method_1": "post",
    "sent_through_1": "custom",
}

Each credential endpoint configuration object contains the following fields:

path

Required. The path of the request that contains the credentials. (If you need to use a regular expression instead of an exact path, you can do so in the px_custom_is_login_request subroutine.)

# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "path_0": "/login",
    # ...
}

method

Required. The HTTP method of the request that contains the credentials. Supported methods are "post" and "put".

# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "method_0": "post",
    # ...
}

sent_through

Required. Whether the credentials should be extracted from the request body or by invoking the custom subroutine.

Possible values:

• "body" - The credentials will be extracted according to the configured user_field and pass_field values from the request body. Please notice that body limit is 8K (see Fastly docs).
• "custom" - The credentials will be extracted by invoking the px_custom_login_extraction_callback subroutine. This may be used for multiple credential endpoints, and all credential endpoints with this value will invoke the same subroutine.

# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "sent_through_0": "body",
    # ...
    "sent_through_1": "custom",
    # ...
}

📘

Note

The Enforcer parses the request body based on the Content-Type request header. Supported Content-Type values are:

• application/json
• application/x-www-form-urlencoded

To support other content types, set the sent_through key to custom and define a px_custom_login_extraction_callback to extract the credentials from the request as desired.

user_field

Required only if sent_through is set to "body".

The name of the field, header name, or query parameter where the username can be found.

# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "sent_through_0": "body",
    "user_field_0": "username",
    # ...
}

pass_field

Required only if sent_through is set to "body".

The name of the field, header name, or query parameter where the password can be found.

# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "sent_through_0": "body",
    "pass_field_0": "password",
    # ...
}

📘

Nested Objects in a JSON Body

The user_field and pass_field configurations support Content-Type: application/json bodies with nested objects. The configurations need only include the specific key names associated with the desired values. Any higher-level keys can be ignored.

For example, the table can include a user_field with the value "username" and a pass_field with the value "password" to support extracting the credentials from the following JSON body. There is no need to include the higher-level fields (i.e., "user_info" or "authentication") in the configurations.

{
    "user_info": {
        "username": "user123"
    },
    "authentication": {
        "password": "P@s$w0rD!"
    }
}

protocol

Optional. 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.

Possible values:

• "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.

Default: "both"

# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "protocol_0": "v2",
    # ...
}

px_custom_is_login_request

A custom subroutine that returns the correct credential endpoint suffix according to the the request URL. That is, this subroutine should return the credential endpoint suffix (e.g., _0, _1) that corresponds with the request's path.

You may use the path values in the px_login_credentials_extraction table if an exact match is needed, or you may use a regular expression as desired.

Default:

# 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

A custom subroutine to extract the raw username and password from the request. All login extraction endpoints will use this same subroutine if their sent_through value is set to "custom". Use the req.http.px-creds:endpoint-index header, which has the value of the credential endpoint suffix (e.g., _0, _1), to differentiate between the endpoints.

Set the req.http.px-creds:raw-username header value to the raw username and the req.http.px-creds:raw-password header value to the raw password extracted from the request.

Default: Empty

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") {
        # extract from req and set to local variables
        # set var.username = ...;
        # set var.password = ...;
    }

    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_credentials_intelligence_version

❗️

Deprecated

This configuration is deprecated. Set the Credential Intelligence protocol on a per-endpoint basis by adding the protocol field in the px_login_credentials_extraction table.

px_login_successful_reporting_method

The method by which the Enforcer will determine whether the login request was successful.

Possible values:

• "status" - The Enforcer will determine if the login request was successful by evaluating the response status code against the px_login_successful_status configuration. (Supports only one status code. For multiple status codes, use the "custom" setting.)
• "header" - The Enforcer will determine if the login request was successful by evaluating whether the x-px-login-successful header is set to "1".
• "custom" - The Enforcer will determine if the login request was successful by invoking the px_custom_set_login_successful_response_header subroutine.

This setting will apply to all configured Credential Intelligence endpoints. If you need to differentiate between endpoints, set this value to "custom" and use the px_custom_set_login_successful_response_header to implement your desired logic on a per-endpoint basis.

Default: "status"

# PX_CONFIGS
table px_configs {
    # ...
    "px_login_successful_reporting_method": "custom",
    # ...
}

px_login_successful_status

An HTTP status signifying a successful login. All other status codes will be treated as unsuccessful login attempts. This configuration takes effect only when the px_login_successful_reporting_method is set to "status".

🚧

Note

This configuration supports defining only one status code. For multiple status codes, set px_login_successful_reporting_method to "custom" and implement your desired logic in the px_custom_set_login_successful_response_header subroutine instead.

Default: "200"

# PX_CONFIGS
table px_configs {
    # ...
    "px_login_successful_status": "202",
    # ...
}

px_custom_set_login_successful_response_header

A custom subroutine to indicate if the login attempt was successful. This configuration takes effect only when the px_login_successful_reporting_method is set to "custom". This subroutine is invoked during the vcl_deliver stage.

The subroutine should set the resp.http.x-px-login-successful header to "1" if the login request resulted in a successful login, or to "0" if the login attempt was unsuccessful.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_set_login_successful_response_header {
    if (resp.http.custom-login-header == "login_successful") {
        set resp.http.x-px-login-successful = "1";
    } else {
        set resp.http.x-px-login-successful = "0";
    }
}

px_send_raw_username_on_additional_s2s_activity

Whether to report the raw username on the additional_s2s activity. When set to "false", the raw username will never be reported. When set to "true", the raw username will only be reported if (1) the credentials are compromised, and (2) the login request was successful.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_send_raw_username_on_additional_s2s_activity": "true",
    # ...
}

px_credentials_intelligence_query_string

Whether to add the URL query parameter compromised_credentials=true to the origin request URL if compromised credentials have been identified on the request.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_credentials_intelligence_query_string": "true",
    # ...
}

px_compromised_credentials_returned_status_response

This configuration modifies the returned client response status code if px_credentials_intelligence_query_string is enabled, and if the login request contained compromised credentials and resulted in a successful login.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_compromised_credentials_returned_status_response": "401",
    # ...
}

px_additional_s2s_activity_header_enabled

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.

When set to "true", the additional_s2s activity will no longer be sent automatically by the Enforcer. Instead, the following headers will be 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.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_additional_s2s_activity_header_enabled": "true",
    # ...
}

Below is an example of JavaScript code at the origin server to handle parsing, enrichment, and sending of the additional_s2s activities that arrive on request headers.

app.post('/login', (req, res) => {
    // handle login flow, resulting in variables
    // isLoginSuccessful (boolean) and responseStatusCode (number)

    if (
        req.headers['px-additional-activity'] &&
        req.headers['px-additional-activity-url']
    ) {
        handlePxAdditionalActivity(req, responseStatusCode, isLoginSuccessful);
    }
});

function handlePxAdditionalActivity(req, statusCode, isLoginSuccessful) {
    try {
        // extract url and activity from the request headers
        const url = req.headers['px-additional-activity-url'];
        const activity = JSON.parse(req.headers['px-additional-activity']);

        // enrich the activity details with added information
        activity.details['http_status_code'] = statusCode;
        activity.details['login_successful'] = isLoginSuccessful;

        if (activity.details['credentials_compromised'] && isLoginSuccessful) {
            // add raw username if credentials are compromised and login is successful (only if desired)
            activity.details['raw_username'] = req.body.username;
        } else {
            // remove raw username if login is not successful or credentials are not compromised
            delete activity.details['raw_username'];
        }

        // send the POST request
        axios.post(url, activity, {
            headers: {
                'Authorization': `Bearer ${env.PX_AUTH_TOKEN}`,
                'Content-Type': 'application/json'
            }
        });
    } catch (err) {
        console.error(`Error: ${err}`);
    }
}