Cloudflare configuration options

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_app_id: '<APP_ID>',
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_auth_token: '<AUTH_TOKEN>',
4
    // ...
5
}

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

If you need to rotate secrets, then adjust this configuration to be an array of strings (string[]) and include the new secret and old secret. The new secret value should be the first value in the array. This prevents decryption failures.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_cookie_secret: '<COOKIE_SECRET>',
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_s2s_timeout: 2000,
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_blocking_score: 20,
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_user_agent_max_length: 2048,
4
    // ...
5
}

Base URL for HUMAN SAPI (Risk API and related calls). If empty, the Enforcer uses the default host for your application ID. Set this only when directed by HUMAN (for example, custom routing or non-standard environments).

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_backend_url: 'https://custom-sapi.example.com',
4
    // ...
5
}

The severity at which the logger will output logs.

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

See px_logger_auth_token for a header-based alternative.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_logger_severity: 'debug',
4
    // ...
5
}

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

Taken from CF-Connecting-IP by default.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_ip_headers: ['true-ip', 'true-client-ip'],
4
    // ...
5
}

Whether the Enforcer module is enabled.

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_module_enabled: false,
4
    // ...
5
}

The Enforcer’s operation mode.

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_module_mode: 'active_blocking',
4
    // ...
5
}

A custom function passed to the Enforcer that runs after sending page_requested or block activity to the Collector 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. Then the application can read the score and do what is defined within the application’s logic.

Parameters:

• config: HumanSecurityConfiguration
• context: IContext
• request: Request

Returns: void or a Promise resolving to void

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_additional_activity_handler: (
4
        config: HumanSecurityConfiguration,
5
        context: IContext,
6
        request: Request
7
    ): void => {
8
        request.headers.set('x-px-score', `${context.score}`);
9
        request.headers.set('x-px-rtt', `${context.riskApiData.riskRtt}`);
10
    },
11
    // ...
12
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_advanced_blocking_response_enabled: false,
4
    // ...
5
}

Activates the full blocking flow to verify the flow works as expected if a particular header is present on the request. Often used during monitor mode, where the Enforcer collects data without blocking user requests, before switching to active_blocking.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_bypass_monitor_header: 'human-block',
4
    // ...
5
}

Whether to enable the extraction and reporting of credentials from the Enforcer for Credential Intelligence.

• true: Enable Credential Intelligence
• false: Disable Credential Intelligence

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_login_credentials_extraction_enabled: true,
4
    // ...
5
}

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.

1
{
2
    // ...
3
    path: '/sign-up',
4
    // ...
5
}

1
{
2
    // ...
3
    path: '/auth/[A-Za-z0-9]{12}/login',
4
    path_type: 'regex',
5
    // ...
6
}

1
{
2
    // ...
3
    method: 'POST',
4
    // ...
5
}

1
{
2
    // ...
3
    sent_through: 'body',
4
    // ...
5
}

1
{
2
    // ...
3
    sent_through: 'body',
4
    user_field: 'username',
5
    // ...
6
}

1
{
2
    // ...
3
    sent_through: 'body',
4
    user_field: 'username',
5
    // ...
6
}

1
type Credentials = {
2
    user?: string;  // the raw username
3
    pass?: string;  // the raw password
4
};

1
{
2
    // ...
3
    sent_through: 'custom',
4
    extract_credentials_callback: async (request: Request): Promise<Credentials> => {
5
        if (!request.body) return null;
6
        // ...
7
        // custom extraction resulting in username and password
8
        // ...
9
        if (!username || !password) {
10
            // unsuccessful extraction
11
            return null;
12
        }
13
        // successfully extracted credentials
14
        return { user: username, pass: password };
15
    },
16
    // ...
17
}

1
{
2
    // ...
3
    protocol: 'v2',
4
    // ...
5
}

1
{
2
    // ...
3
    login_successful_reporting_method: 'status',
4
    // ...
5
}

1
{
2
    // ...
3
    login_successful_reporting_method: 'status',
4
    login_successful_statuses: [200, 202],
5
    // ...
6
}

1
{
2
    // ...
3
    login_successful_reporting_method: 'body',
4
    login_successful_body_regex: 'Welcome, [A-Za-z0-9_]+!'
5
    // ...
6
}

1
{
2
    // ...
3
    login_successful_reporting_method: 'header',
4
    login_successful_header_name: 'x-login-successful'
5
    // ...
6
}

1
{
2
    // ...
3
    login_successful_reporting_method: 'header',
4
    login_successful_header_name: 'x-user-status',
5
    login_successful_header_value: 'logged-in'
6
    // ...
7
}

1
{
2
    // ...
3
    login_successful_reporting_method: 'custom',
4
    login_successful_callback: (response: Response): boolean => {
5
        return response.status === 200 && response.headers.get('set-cookie')?.includes('session_token=');
6
    },
7
    // ...
8
}

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_login_credentials_extraction: [
4
        {
5
            path: '/auth/[A-Za-z0-9]{12}/login',
6
            path_type: 'regex',
7
            method: 'POST',
8
            sent_through: 'body',
9
            user_field: 'username',
10
            pass_field: 'password',
11
            login_successful_reporting_method: 'status',
12
            login_successful_statuses: [200, 202]
13
        },
14
        {
15
            path: '/sign-up',
16
            method: 'POST',
17
            sent_through: 'custom',
18
            extract_credentials_callback: (request: Request): Credentials => {
19
                if (!request.body || request.headers.get('x-reject-signup')) {
20
                    return null;
21
                }
22
                return {
23
                    user: request.body['new_username'],
24
                    pass: request.body['password']
25
                };
26
            },
27
            login_successful_reporting_method: 'custom',
28
            login_successful_callback: (response: Response): boolean => {
29
                return response.headers.get('set-cookie')?.includes('session_token=');
30
            }
31
        },
32
        // ...
33
    ],
34
    // ...
35
}

The header name to be set on the incoming request if the credentials are compromised. If this header is added, its value will always be 1. If credentials have not been identified as compromised, the header will not be added to the request.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_compromised_credentials_header: 'x-ci-compromised',
4
    // ...
5
}

Whether to send the additional_s2s activity, which reports on whether the login was successful, automatically in the postEnforce function. This should only be set to false if it is not possible to determine whether the login was successful based on the HTTP response. However, if that’s the case, then the additional_s2s activity must be sent with px_additional_s2s_activity_header_enabled.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_automatic_additional_s2s_activity_enabled: false,
4
    // ...
5
}

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. This should only be enabled if the px_automatic_additional_s2s_activity_enabled is set to false.

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.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_additional_s2s_activity_header_enabled: true,
4
    // ...
5
}

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.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_send_raw_username_on_additional_s2s_activity: true,
4
    // ...
5
}

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: <ORIGIN_REQUEST_HEADER_VALUE>  
  Access-Control-Allow-Credentials: true
• Activates the px_cors_create_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 and px_cors_custom_preflight_handler configurations, which lets you filter and custom handle preflight requests.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_cors_support_enabled: true,
4
    // ...
5
}

If the default CORS response headers are not sufficient, you can use this configuration tocustomize 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. Only those headers specified in the returned object will be added to the block response.

Parameters:

• request: Request

Returns: An object of the type Record<string, string[]> or a Promise resolving to this type

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_cors_create_custom_block_response_headers: (
4
        request: Request,
5
    ): Record<string, string[]> => {
6
        return {
7
            'Access-Control-Allow-Origin': [request.headers.get('origin')],
8
            'Access-Control-Allow-Credentials': ['false'],
9
            'Access-Control-Allow-Methods': ['GET', 'POST', 'PUT'],
10
            'X-Custom-Header': ['1']
11
        };
12
    },
13
    // ...
14
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_cors_preflight_request_filter_enabled: true,
4
    // ...
5
}

A custom function to define desired behavior for handling CORS preflight requests, if needed. The custom function should receive the original HTTP request and return an object representing the HTTP response to be returned. If null or any other falsy value is returned from the function, the Enforcer will continue processing the preflight request.

The px_cors_custom_preflight_handler will be invoked prior to determining whether to filter the request based on the px_cors_preflight_request_filter_enabled configuration. This allows for returning customized responses for preflight requests that meet certain conditions and filtering those that don’t meet these conditions.

Parameters:

• request: Request

Returns: An object of the type IMinimalResponse or a Promise resolving to this type

1
interface IMinimalResponse {
2
    status: number;
3
    headers: Record<string, string[]>;
4
    body: any;
5
};

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_cors_custom_preflight_handler: (request: Request): ``IMinimalResponse`` | ``Promise<``IMinimalResponse``>`` => {
4
        const headers = {
5
            'Access-Control-Allow-Origin': [request.headers.get('origin')],
6
            'Access-Control-Allow-Methods': [request.headers.get('access-control-request-method')],
7
            'Access-Control-Allow-Headers': [request.headers.get('access-control-request-headers')],
8
            'Access-Control-Allow-Credentials': ['true'],
9
            'Access-Control-Max-Age': ['86400']
10
        };  
11
        return {
12
            status: 204,
13
            headers,
14
            body: null,
15
        };
16
    },
17
    // ...
18
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_custom_cookie_header: 'x-custom-cookies',
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_first_party_enabled: false,
4
    // ...
5
}

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

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

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

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_custom_first_party_prefix: "/custom-prefix",
4
    // ...
5
}

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

In addition to responding to requests that match this configured route, the Enforcer will also proxy first party requests that match the default pattern (/12345678/init.js) and patterns according to the custom prefix (/<px_custom_first_party_prefix>/init.js) if one is configured.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_custom_first_party_sensor_endpoint: "/human_sensor",
4
    // ...
5
}

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

In addition to responding to requests that match this configured route, the Enforcer will also proxy first party requests that match the default pattern (/12345678/xhr/*) and patterns according to the custom prefix (/<px_custom_first_party_prefix>/xhr/*) if one is configured.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_custom_first_party_xhr_endpoint: "/human_xhr",
4
    // ...
5
}

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

In addition to responding to requests that match this configured route, the Enforcer will also proxy first party requests that match the default pattern (/12345678/captcha/*) and patterns according to the custom prefix (/<px_custom_first_party_prefix>/captcha/*) if one is configured.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_custom_first_party_captcha_endpoint: "/human_captcha",
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_first_party_timeout_ms: 10000,
4
    // ...
5
}

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. These custom parameters are defined by a configurable function that must return an object that contains these custom parameters. There is a limit of 10 custom parameters.

Parameters:

• config: HumanSecurityConfiguration
• request: Request

Returns: Promise<CustomParameters>

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_enrich_custom_parameters: async (
4
        config: HumanSecurityConfiguration,
5
        request: Request,
6
    ): `CustomParameters` | `Promise<`CustomParameters`>` => {
7
        const body = request.method === 'POST' && 
8
            request.headers.get('content-type')?.includes('application/json') ? 
9
            await request.clone().json() : null;
10
        return {
11
            custom_param1: 'hardcoded value',
12
            custom_param2: request.headers.get('header-name'),
13
            custom_param3: body?.['body_property']
14
        };
15
    },
16
    // ...
17
}

An array of routes or prefixes that should be enforced by HUMAN even when the Enforcer is in monitor mode.

Supports strings or regular expressions, including regex-formatted strings (i.e. "/^/regex/formatted/string/i").

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_enforced_routes: ['/enforced_route', /.*\/enforced\/regex$/],
4
    // ...
5
}

A custom function that lets you define which requests should be enforced based on custom logic. It accepts the incoming request as an argument and returns a boolean indicating whether the request should be enforced.

Parameters:

• request: Request

Returns: A boolean or a Promise resolving to a boolean.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_custom_is_enforced_request: (request: Request): boolean | Promise<boolean> => {
4
        return request.method === 'POST' && request.url.includes('/enforced_route');
5
    },
6
    // ...
7
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_filter_by_extension: ['.css', '.js', '.png'],
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_filter_by_http_method: ['OPTIONS', 'DELETE'],
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_filter_by_ip: ['1.1.1.1', '2.2.2.2/8'],
4
    // ...
5
}

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.

Supports strings or regular expressions, including regex-formatted strings (i.e. "/^/regex/formatted/string/i").

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_filter_by_route: ['/filtered_route', /.*\/filtered\/regex$/],
4
    // ...
5
}

Filters out requests with the specified user agent to avoid unnecessary traffic in the Enforcer verification flow.

Supports strings or regular expressions, including regex-formatted strings (i.e. "/^/regex/formatted/string/i").

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_filter_by_user_agent: ['filtered_UA', /.*\/filtered\/regex$/],
4
    // ...
5
}

A custom function that lets you define which requests should be filtered based on custom logic. It accepts the incoming request as an argument and returns a boolean indicating whether the request should be filtered.

Parameters:

• request: Request Returns: A boolean or a Promise resolving to a boolean.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_custom_is_filtered_request: (request: Request): boolean | Promise<boolean> => {
4
        return request.method === 'GET' && request.url.includes('/static/');
5
    },
6
    // ...
7
}

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_graphql_routes will have their bodies parsed for GraphQL operations.

• true: Enable GraphQL support
• false: Disable GraphQL support

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_graphql_enabled: true,
4
    // ...
5
}

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

Supports strings or regular expressions, including regex-formatted strings (i.e. "/^/regex/formatted/string/i").

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_graphql_routes: ['/graphql', /^\/\w+\/graphql/],
4
    // ...
5
}

A list of operation names or keywords that should be considered sensitive. If one or more GraphQL operations has a name or keyword matching this list, the Enforcer will trigger a Risk API call even if the request contains a valid, unexpired cookie. Matches against extracted GraphQL words from:

• px_graphql_keywords configuration
• px_extract_graphql_keywords configuration

Supports strings or regular expressions, including regex-formatted strings (i.e. "/^RegexFormattedString$/i").

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_sensitive_graphql_operation_names: ['LoginOperation', /sensitiveKeyword/],
4
    // ...
5
}

A list of operation types that should be considered sensitive. 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.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_sensitive_graphql_operation_types: ['query', 'mutation'],
4
    // ...
5
}

A list of keywords to identify important terms from GraphQL operation queries. These keywords are used to determine the purpose of the operation (such as login, checkout, or search) and can also be used to specify which operations should be considered sensitive. Any matching patterns will be extracted and reported to HUMAN. See px_sensitive_graphql_operation_names for more information. See px_extract_graphql_keywords for an alternative using a custom function.

Supports strings or regular expressions, including regex-formatted strings (i.e. "/^RegexFormattedString$/i").

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_graphql_keywords: ['performLogin', 'addToCart', /keyword\d+/],
4
    // ...
5
}

A custom function that identifies key terms from GraphQL operation queries. An alternative to the px_graphql_keywords configuration.

This function accepts the GraphQL query string and must return an array of strings representing all keywords found in the query. These keywords are used to determine the purpose of the operation (such as login, checkout, search) and can also be used to specify which GraphQL operations should be considered sensitive. See px_sensitive_graphql_operation_names for more information.

If this function is defined and returns an array (even an empty array), then the returned array will be used as the GraphQL keywords. If this function is defined and returns null, then the query will continue to be evaluated using px_graphql_keywords.

Parameters:

• graphqlQuery: string

Returns string[] or a Promise resolving to string[].

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_extract_graphql_keywords: (graphqlQuery: string): string[] | Promise<string[]> => {
4
        if (/userId\d+/.test(graphqlQuery)) {
5
            // report no keywords for this query
6
            return [];
7
        } else if (/perform(Login|Signin)/.test(graphqlQuery)) {
8
            // always report 'login' as the only keyword for this query
9
            return ['login'];
10
        } else {
11
            // process query according to px_graphql_keywords configuration
12
            return null;
13
        }
14
    },
15
    // ...
16
}

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.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_data_enrichment_header_name: 'x-human-data-enrichment',
4
    // ...
5
}

Adds a header to the incoming request with the configured header name and the score (0-100) as the value. If empty, no header will be set.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_score_header_name: 'x-human-score',
4
    // ...
5
}

Adds a header to the incoming request with the configured header name and the client UUID as the value. If empty, no header will be set.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_client_uuid_header_name: 'x-human-uuid',
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_css_ref: 'https://www.example.com/custom_style.css',
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_js_ref: 'https://www.example.com/custom_script.js',
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_custom_logo: 'https://www.example.com/custom_logo.png',
4
    // ...
5
}

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

Supports strings or regular expressions, including regex-formatted strings (i.e. "/^/regex/formatted/string/i").

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_monitored_routes: ['/monitored_route', /.*\/monitored\/regex$/],
4
    // ...
5
}

A custom function that lets you define which endpoints should be monitored based on custom logic. It accepts the incoming request as an argument and returns a boolean indicating whether the request should be monitored.

Parameters:

• request: Request

Returns: A boolean or a Promise resolving to a boolean.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_custom_is_monitored_request: (request: Request): boolean | Promise<boolean> => {
4
        return request.method === 'GET' && request.url.includes('/monitored');
5
    },
6
    // ...
7
}

The PX Hashed Data (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 is added when setting the PXHD cookie.

See Use of cookies & web storage for more information.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_secured_pxhd_enabled: true,
4
    // ...
5
}

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

Contact HUMAN to recieve your token.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_logger_auth_token: '<LOGGER_AUTH_TOKEN>',
4
    // ...
5
}

The token used to authenticate the Enforcer with the HUMAN Remote Configuration service.

Contact HUMAN to receive your token.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_remote_config_auth_token: '<REMOTE_CONFIG_AUTH_TOKEN>',
4
    // ...
5
}

The ID associated with the Remote Configuration.

Contact HUMAN to receive your ID.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_remote_config_id: '00000000-0000-0000-0000-000000000000',
4
    // ...
5
}

When using the PXKV namespace for Remote Configuration, this static configuration determines the KV key name whose value will contain the Enforcer configuration.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_remote_config_kv_key_name: 'human_config',
4
    // ...
5
}

The maximum number of time to attempt to fetch the Remote Configuration. If the Enforcer fails to fetch the Remote Configuration after the specified maximum, it will use the last known configuration.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_remote_config_max_fetch_attempts: 10,
4
    // ...
5
}

The interval time in milliseconds to wait between attempts to fetch the Remote Configuration.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_remote_config_timeout: 10000,
4
    // ...
5
}

A function that receives the configuration and the Response from the origin and returns up to ten fields: custom_param11 through custom_param20. These are merged into page_requested, additional_s2s, and simulated block activities. There is a limit of ten response custom parameters.

Parameters:

• config: HumanSecurityConfiguration
• response: Response

Returns: An object with custom_param11–custom_param20 keys, or a Promise resolving to that object.

1
const config: HumanSecurityConfiguration = {
2
  // ...
3
  px_enrich_response_custom_parameters: async (
4
          config: HumanSecurityConfiguration,
5
          response: Response,
6
  ): Promise<CustomParameters> => {
7
    // Clone the response if you need to read the body
8
    const clonedResponse = response.clone();
9
    const text = await clonedResponse.text();
10
    return {
11
      custom_param11: 'hardcoded value',
12
      custom_param12: response.headers.get('header-name'),
13
      custom_param13: text, // e.g., response body
14
      // ... up to custom_param20
15
    };
16
  },
17
  // ...
18
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_sensitive_headers: ['x-sensitive-token'],
4
    // ...
5
}

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

Supports strings or regular expressions, including regex-formatted strings (i.e. "/^/regex/formatted/string/i").

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_sensitive_routes: ['/login', /.*\/sensitive\/regex$/],
4
    // ...
5
}

A custom function that lets you define which requests should be considered sensitive based on custom logic. It accepts the incoming request as an argument and returns a boolean indicating whether the request should be considered sensitive.

Parameters:

• request: Request

Returns: A boolean or a Promise resolving to a boolean.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_custom_is_sensitive_request: (request: Request): boolean | Promise<boolean> => {
4
        return request.method === 'POST' || request.method === 'PUT';
5
    },
6
    // ...
7
}

When true, the Enforcer will decode reserved characters such as %3F and %2F in the request URL path prior to processing. In other words, the Enforcer will treat the URIs /login%3F.ico and /login?.ico as equivalent. By default, the Enforcer doesn’t decode reserved characters and treats these URIs separately.

• true: Decode reserved characters in the request URL.
• false: Do not decode reserved characters in the request URL.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_url_decode_reserved_characters: true,
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_jwt_cookie_name: 'auth',
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_jwt_cookie_user_id_field_name: 'nameID',
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_jwt_cookie_additional_field_names: ['exp', 'iss'],
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_jwt_header_name: 'x-jwt-authorization',
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_jwt_header_user_id_field_name: 'sub',
4
    // ...
5
}

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

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_jwt_header_additional_field_names: ['exp', 'iss'],
4
    // ...
5
}

If true, the Enforcer will inject the default Sensor snippet, shown below, into the head element of HTML responses. Any HTTP response with a Content-Type containing text/htmlis considered an HTML response.

1
<script type="text/javascript">
2
    (function(){
3
        window._pxAppId = '<APP_ID>'; // Your Application ID
4
        var p = document.getElementsByTagName('script')[0], s = document.createElement('script');
5
        s.async = 1;
6
        s.src = '<SENSOR_SRC>'; // Your Sensor source URI. Depends on your Application ID and first party configurations.
7
        p.parentNode.insertBefore(s,p);
8
    }());
9
</script>

See px_create_custom_snippet to inject customized JavaScript snippets.

• true: Snippet injection enabled.
• false: Snippet injection disabled.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_snippet_injection_enabled: true,
4
    // ...
5
}

A custom function that lets you create or retrieve a customized snippet to be injected into HTML responses. If an empty or non-string value is returned from the custom function, then the default snippet will be injected instead.

Parameters:

• config: HumanSecurityConfiguration
• request: Request
• response: Response

Returns: A string or a Promise resolving to a string.

1
const config: HumanSecurityConfiguration = {
2
    // ...
3
    px_create_custom_snippet: (
4
        config: HumanSecurityConfiguration,
5
        request: Request,
6
        response: Response,
7
    ): string | Promise<string> => {
8
        return `<script type="text/javascript">console.log("custom snippet!");</script>`;
9
    },
10
    // ...
11
}