> This page is for Applications Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# Configuration Options

## Active Header Name

Allows you to pass a specific header (e.g. x-px-active) when px_enabled is off. When the header has a value of 1, the module is enabled for the specific request. When the header has a value of 0, the module is not enabled.

This feature can be used for a/b testing.

**Default:** Empty

```nginx
http {
    ...
    server {
       ...
         px_active_header_name "x-px-active";
    ...
```

## Advanced Blocking Response Flag

Enables/disables the Advanced Blocking Response functionality.

**Default:** `false`

```nginx
http {
    ...
    server {
       ...
         px_enable_json_response true;
    ...
```

## Allowed Cookies

A list of cookie names that are allowed to be sent to HUMAN servers on server-to-server calls.

**Default:** Empty list

```nginx
http {
    ...
    server {
       ...
         px_allowed_cookies "SID" "NID";
    ...
```

## Allowlist Routes

Allowing (bypassing enforcement) can be configured on different aspects of the request, ranging from URI to IP addresses and user agents. The rules are OR based.

**Default:** Empty list

```nginx
http {
    ...
    server {
       ...
        # Filters requests to `/api_server_full?data=1`, but not to `/api_server?data=1`
        px_whitelist_uri_full "/api_server_full?data=1";

        # Filters requests to `/api_server_full?data=1` but not to `/full_api_server?data=1`
        px_whitelist_uri_prefixes "/api_server";

        # Filters request to `/result.json` but not to `/result.js`
        px_whitelist_uri_suffixes ".json";

        # Filters requests coming from any of the IPs listed. Accepts either a full IPV4 address or a CIDR (192.168.0.0/16):
        px_whitelist_ip_addresses "10.0.0.15" "192.168.0.0/16";

        # Filters all requests matching this exact UA.
        px_whitelist_ua_full "Mozilla/5.0 (compatible; pingbot/2.0; http://www.pingdom.com/)";

        # Filters requests containing the provided string in their UA
        px_whitelist_ua_sub "GoogleCloudMonitoring";
    ...
```

## Filter Traffic by pairs of regular expressions and HTTP methods

An array of pairs of of regular expressions and HTTP methods that are always filtered out and not validated by the Enforcer. Requests with paths matching these configured patterns will always be allowed to pass the Enforcer.

**px_whitelist_uri_regex** takes one or multiple pairs of a route RegEx and a HTTP method.

(Remember that '$' character must be escaped: [Escaping  '$' character]\([https://docs.perimeterx.com/v1/docs/nginx-config#using-character-in-nginx-configuration](https://docs.perimeterx.com/v1/docs/nginx-config#using-character-in-nginx-configuration)) )

```nginx
http {
    ...
    server {
       ...
       px_whitelist_uri_regex "\/images|\/docs" "GET";
       ...
```

## Filter By Domain

An array of regular that are always filtered out and not validated by the Enforcer. Requests with Domains matching these configured patterns will always be allowed to pass the Enforcer.

**px_filter_by_domain** takes one or multiple Domain route RegEx.

(Remember that '$' character must be escaped: [Escaping '$' character]\([https://docs.perimeterx.com/v1/docs/nginx-config#using-character-in-nginx-configuration](https://docs.perimeterx.com/v1/docs/nginx-config#using-character-in-nginx-configuration)) )

```nginx
http {
    ...
    server {
       ...
       px_filter_by_domain "img\.example\.com|docs\.example\.com";
       ...
```

## API Timeout

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:** `1000`

```nginx
http {
    ...
    server {
       ...
         px_s2s_timeout 2000;
    ...
```

## Blocking Score

Sets the minimum blocking score of a request. Do not change this value without consulting with a HUMAN support engineer.

Possible values:

* Any integer between 0 and 100.

**Default:** `100`

```nginx
http {
    ...
    server {
       ...
        px_blocking_score 100;
    ...
```

## Credential Intelligence

The following configurations are used to enable HUMAN [Credential Intelligence](/applications/credential-intelligence-overview) offering:

#### Login Credentials Extraction

This feature extracts credentials (hashed username and password) from requests and sends them to HUMAN as additional info in risk / activity api calls. The feature can be toggled on and off. The settings are adjusted by modifying a credentials JSON file.

### Enable Login Credentials Extraction

Default: false (disabled)

```nginx
px_enable_login_creds_extraction false;
```

### Credentials JSON file

Sets a full path to credentials JSON file
Default: nil (none)

```nginx
px_login_creds_settings_filename '/etc/creds.json';
```

Credentials JSON file contains an array of CI items. Each item must contain the following fields:

* **id** : unique number
* **method** : string contains a method, supported methods: "post", "put"
* **sent_through** : contains one of the following strings: "body", "header", "query-param"
* **path** : string with URL path, must start with "/"
* **user_field** : string with username field name
* **pass_field** : string with password field name

This is an example of \`/etc/creds.json\` file. It includes an array of JSON objects containing the following properties:

```json
{
    "features": {
        "credentials": {
            "items": [
                {
                    "id": 0,
                    "method": "post",
                    "path": "/login",
                    "sent_through": "body",
                    "pass_field": "password",
                    "user_field": "username"
                  }, {
                    "id": 1,
                    "method": "post",
                    "path": "/login-header",
                    "sent_through": "header",
                    "pass_field": "password",
                    "user_field": "username"
                  }, {
                    "id": 2,
                    "method": "put",
                    "path": "/login-params",
                    "sent_through": "query-param",
                    "pass_field": "password",
                    "user_field": "username"
                  }
            ]
        }
    }
}
```

### Credentials Intelligence Version

Sets Credentials Intelligence protocol version
Default: 'v2'

```nginx
px_credentials_intelligence_version  'v2';
```

### Login successful header name

Default: 'x-px-login-successful'

```nginx
px_login_successful_header_name  "x-px-login-successful";
```

### Login successful header value

Default: '1'

```nginx
px_login_successful_header_value  "1";
```

### Login successful header regex value

Default: '1'

```nginx
px_login_successful_header_value_regex  "^secret$";
```

### Login successful reporting method

Sets login successful reporting method, could be one of the following values: 'none', 'header', 'status'
Default: 'none'

```nginx
px_login_successful_reporting_method  'none';
```

\


### Login successful status

Sets a list of login successful status.
Default: 200

```nginx
px_login_successful_status 200 201;
```

## Custom Logo

The logo is displayed at the top of the the block page.
Max-height = 150px, Width = auto.

**Default:** Empty

```nginx
http {
    ...
    server {
       ...
         px_custom_logo "http://www.example.com/logo.png";
    ...
```

## Debug Mode

A boolean flag to enable/disable the debug log messages.

**Default:** `false`

```nginx
http {
    ...
    server {
       ...
        px_debug true;
    ...
```

## Enabled Routes

Allows you to define a set of routes on which the plugin will be active. An empty list sets all routes in the application as active.

**Default:** Empty list (all routes are active)

```nginx
http {
    ...
    server {
       ...
         # The plugin will be active only on `/search` and `/products` route prefixes.
         px_enabled_routes "/search" "/products";
    ...
```

## Enforced Routes

Allows to define a set of routes that will be handled by the Enforcer (`px_block_enabled` must be set to `true`). All other routes, that do not match regex(-s), will be ignored by the Enforcer. Values added in this configuration will match routes as regex (e.g. “^/path” will match with route “/path/example”). Use whitespace separation to add multiple values.

**Default:** Empty list

```nginx
px_enforced_routes "^/path";
```

## Enrich Custom Parameters

A list of up to 10 header keys that allows you to send up to 10 custom parameters back to HUMAN servers. The parameters should be passed according to the correct order (1-10). Skipping is possible using an empty string (i.e "header1" "header2" "" "header4").

**Default:** Empty list

```nginx
http {
    ...
    server {
       ...
         px_custom_parameters "x-user-id" "x-vid";
    ...
```

It is also possible to extract custom parameters from cookies. Just as with the headers, the cookie keys should be passed according to the correct order (1-10). Parameters extracted from cookies will be base64 decoded.

**Default:** Empty list

```nginx
http {
    ...
    server {
       ...
         px_cookie_custom_parameters "_someCookie" "_someOtherCookie";
    ...
```

## First Party URL Override

In some specific cases (as instructed by HUMAN) you can override the default domains for first-party calls by adding the `px_client_host` and `px_captcha_script_host` properties and providing alternate URLs.

**Default:** Empty

```nginx
http {
    ...
    server {
       ...
         px_client_host "https://client.px-cloud.net";
         px_captcha_script_host "//captcha.px-cloud.net";
    ...
```

> **Note**
>
> Both values should not have a trailing `/`.
> The `px_captcha_script_host` value should not have a protocol. It should always begin with `//`.

## CSS Ref

Modifies a custom CSS by adding the `px_css_ref` property and providing a valid URL to the CSS.

**Default:** Empty

```nginx
http {
    ...
    server {
       ...
         px_css_ref "http://www.example.com/style.css";
    ...
```

## IP Headers

A list of trusted headers that specify an IP to be extracted.

**Default:** Empty list

```nginx
http {
    ...
    server {
       ...
         px_ip_headers "X-Forwarded-For";
    ...
```

## JS Ref

Adds a custom JS file by adding the `px_js_ref` property and providing the JS file that is loaded with the block page.

**Default:** Empty

```nginx
http {
    ...
    server {
       ...
         px_js_ref "https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js";
    ...
```

## Log Enrichment Variables

A boolean flag to enable/disable log enrichment variables

**Default:** `false`

```nginx
http {
    ...
    server {
       ...
        px_variables_enabled true;
    ...
```

## Module Enabled

A boolean flag to enable/disable the HUMAN Enforcer.

**Default:** `false`

```nginx
http {
    ...
    server {
       ...
        px_enabled true;
    ...
```

## Monitor Mode/Block Mode

By default, the HUMAN plugin is set to monitor mode. To active blocking mode, set the `px_block_enabled` property to `true`.

**Default:** `false`

```nginx
http {
    ...
    server {
       ...
        px_block_enabled true;
    ...
```

## Monitored Routes

Allows you to define a set of routes that will be handled as if in monitor mode, even if `block_enabled` is set to `true`. Values added in this configuration will match routes as regex (e.g. “^/path” will match with route “/path/example”). Use whitespace separation to add multiple values.

**Default:** Empty list

```nginx
px_monitored_routes "^/path";
```

## Redirect to a Custom Block Page URL

Customizes the block page to meet branding and message requirements by specifying the URL of a custom block page HTML file.

(Note: Nginx must have more than 1 worker, as HUMAN Nginx Enforcer performs a sub-request to fetch the block page)

**Default:** Empty / false

```nginx
http {
    ...
    server {
       ...
         px_custom_block_url "/pages/block.html";
         px_redirect_on_custom_url: true;
    ...
```

## Disable Original Redirect URL Query Encoding

When a request is blocked and redirected to a custom block page, the original request URL is passed as a query parameter (`url`) to the destination. This parameter allows the block page to identify the specific resource the user was attempting to access.

To ensure compatibility and prevent issues with special characters during the redirect process, the entire original URL string is `Base64 encoded`.

`px_redirect_on_custom_url_raw_query` setting controls whether the query string within the original URL is URL-encoded (percent-encoded) prior to the final Base64 encoding. URL encoding follows the standards defined in [W3C HTML 4.01 Specification](http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1).

When `false` (Default): The original URL's query parameters are URL-encoded. This ensures maximum compatibility with web servers and prevents misinterpreted characters.

When `true`: The system disables URL encoding for the query portion. The query parameters are kept in their raw state before the entire URL is Base64 encoded. Use this if your block page logic requires literal characters (e.g., specific delimiters) that URL encoding might obscure.

**Default:** false

```nginx
http {
    ...
    server {
       ...
         px_custom_block_url "/pages/block.html";
         px_redirect_on_custom_url: true;
         px_redirect_on_custom_url_raw_query true;
    ...
```

## Score Header

A set of properties configuring sending the HUMAN score on upstream and/or downstream headers.

**Default:** `false` / empty string

```nginx
http {
    ...
    server {
       ...
         # enables/disables sending score on a header
         px_score_header_enabled true;

         # sets a header name to send the score upstream
         px_upstream_score_header_name "x-px-upstream-score";

         # sets a header name to send the score on the response
         px_score_header_name "x-px-score";
    ...
```

## Sensitive Headers

A list of headers that are not sent to HUMAN servers on server-to-server API calls.

**Default:** "cookie" "cookies"

```nginx
http {
    ...
    server {
       ...
          px_sensitive_headers "x-px-auth" "x-px-key";
    ...
```

\


## Sensitive Routes

A list of route prefixes/suffixes that trigger a server call to HUMAN servers every time the route is called, regardless of viewing history.

**Default:** Empty list

```nginx
http {
    ...
    server {
       ...
        px_sensitive_routes_prefix "/login" "/user/profile";
        px_sensitive_routes_suffix "/download";
    ...
```

## Sensitive Routes Regex

A list of route regexs that trigger a server call to HUMAN servers every time the route is called, regardless of viewing history.

**Default:** Empty list

```nginx
http {
    ...
    server {
       ...
        px_sensitive_routes_regex "/.*\/enforced\/regex$/";
    ...
```

## Outgoing Enforcer traffic compression

By default, the HUMAN Enforcer sends uncompressed traffic to HUMAN Collector. To activate outgoing Enforcer traffic compression (for "offline" activities), set `px_compression_enabled` property to `true`.

**Default:** false

```nginx
http {
    ...
    server {
       ...
         px_compression_enabled true;
    ...
```

\


## Outgoing Enforcer traffic compression level

By default, HUMAN Enforcer uses gzip compression with the compression level 6.

**Default:** 6

```nginx
http {
    ...
    server {
       ...
         px_compression_level 6;
    ...
```

## Filter By Extension

An array of extensions that are always filtered and not validated by the HUMAN Enforcer. Requests with path extensions matching these configured patterns will always be allowed to pass the HUMAN Enforcer.

**Default**: '.css' '.bmp' '.tif' '.ttf' '.docx' '.woff2' '.js' '.pict' '.tiff' '.eot' '.xlsx' '.jpg' '.csv' '.eps' '.woff' '.xls' '.jpeg' '.doc' '.ejs' '.otf' '.pptx' '.gif' '.pdf' '.swf' '.svg' '.ps' '.ico' '.pls' '.midi' '.svgz' '.class' '.png' '.ppt' '.mid' '.webp' '.jar' '.json' '.xml'

```nginx
http {
    ...
    server {
       ...
         px_filter_by_extension ".jpeg" ".gif" ".png";
    ...
```

## Filter By HTTP Method

An array of strings that represent HTTP methods that are always filtered and not validated by the HUMAN Enforcer. Requests with HTTP methods matching these will always be allowed to pass the HUMAN Enforcer.

Default: Empty list

```nginx
http {
    ...
    server {
       ...
       px_filter_by_http_method "post";
    ...
```

## **Custom First Party Sensor Endpoint**

The default first party endpoint to retrieve the HUMAN sensor is `/<app_id_without_PX>/init.js`. In certain cases (adblockers, etc.) it may be beneficial to change this endpoint name to a different value. You can do this by configuring a custom endpoint name using this configuration.

```nginx
http {
    ...
    server {
       ...
    px_custom_first_party_sensor_endpoint "/botdefense"
    ...
```

You should also modify the snippet on the HTML pages served to refer to this custom endpoint.

```javascript
// JS snippet code

(function(){
    // Custom parameters
    // window._pxParam1 = "";
    var p = document.getElementsByTagName('script')[0],
        s = document.createElement('script');
    s.async = 1;
    s.src = '/botdefense'; // custom endpoint
    p.parentNode.insertBefore(s,p);
}());
```

## Test Block Flow on Monitoring Mode

When set, allows you to test the blocking flow of an enforcer, while in monitoring mode. When the enforcer receives a request that has this configured header name with the value of 1, it will behave as though it is in active blocking mode. For instance, requests with this header and bad user-agents (e.g., PhantomJS/1.0) will return with a block page.

**Default:** Empty

```nginx
http {
    ...
    server {
       ...
         px_bypass_monitor_header "x-px-block";
    ...
```

## URL Decode Reserved Characters

When set, the enforcer decodes reserved characters (such as `%3F` → `?` and `%2F` → `/`).

**Default:** false

```nginx
http {
    ...
    server {
       ...
       px_url_decode_reserved_characters true;
       ...
```

## **CORS support**

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](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#examples_of_access_control_scenarios).

In the Enforcer, CORS behavior must be configured to address both simple requests (without preflight) and more complex ones (with preflight). 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.

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

* It will activate the `px_cors_preflight_request_filter_enabled` configuration, which allows for filtering and custom handling of preflight requests.

**Default**: false

```nginx
http {
    ...
    server {
       ...
       px_cors_support_enabled true;
       ...
```

### **px_cors_preflight_request_filter_enabled**

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

```nginx
http {
    ...
    server {
       ...
       px_cors_preflight_request_filter_enabled true;
       ...
```

### **px_abr_accept_header_regex**

This configuration allows to specify a regular expression patterns for the `Accept` header in incoming requests. When set, the enforcer will check if the `Accept` header in the request matches the specified regex patterns. If it does, the request will be treated as an ABR (Adaptive Bitrate Streaming) request.

**Default**: Empty

```nginx
http {
    ...
    server {
       ...
       px_enable_json_response true;
       px_abr_accept_header_regex '^application/[^+]*\+json';
       ...
```

## 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**: `""`

```nginx
http {
    ...
    server {
       ...
       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**: `""`

```nginx
http {
    ...
    server {
       ...
       px_jwt_cookie_user_id_field_name 'nameID';
       ...
```

### px_jwt_cookie_additional_field_names

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

**Default**: `[]`

```nginx
http {
    ...
    server {
       ...
       px_jwt_cookie_additional_field_names 'exp' 'iss';
       ...
```

### px_jwt_header_name

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

**Default**: `""`

```nginx
http {
    ...
    server {
       ...
       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**: `""`

```nginx
http {
    ...
    server {
       ...
       px_jwt_header_user_id_field_name 'sub';
       ...
```

### px_jwt_header_additional_field_names

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

**Default**: `[]`

```nginx
http {
    ...
    server {
       ...
       px_jwt_header_additional_field_names 'exp' 'iss';
       ...
```

## Sensitive GraphQL Operations

For those using GraphQL endpoints, it is possible to trigger server-to-server risk calls on particular operation types or names. Like the sensitive routes feature, a request that contains an operation of the configured type or name will trigger a server call to HUMAN servers every time that operation is performed.

If an operation type (e.g., `query`, `mutation`) is configured in `px_sensitive_graphql_operation_types`, all GraphQL operations of that type will be treated as sensitive. If an operation name is configured in `px_sensitive_graphql_operation_names`, all GraphQL operations with that name will be treated as sensitive.

This feature only applies to request’s route that match the regex route configured in `px_graphql_routes` (Default is `^/graphql/?$`).

### px_graphql_routes

A list of route regexes that will be checked for sensitive GraphQL operations. If a request’s route matches any of the regexes in this list, it will be checked for sensitive GraphQL operations as configured in `px_sensitive_graphql_operation_types` and `px_sensitive_graphql_operation_names`. If the request contains a sensitive operation, it will trigger a server call to HUMAN servers every time that operation is performed, regardless of cookie state.

**Default:**: `^/graphql/?$`

```nginx
http {
    ...
    server {
       ...
       px_graphql_routes "regex1" "regex2";
       ...
```

### px_sensitive_graphql_operation_types

A 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**: Empty list

```nginx
http {
    ...
    server {
       ...
       px_sensitive_graphql_operation_types "query" "mutation" "subscription";
       ...
```

### px_sensitive_graphql_operation_names

A 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**: Empty list

```nginx
http {
    ...
    server {
       ...
       px_sensitive_graphql_operation_names "SensitiveOperation1" "SensitiveOperation2";
       ...
```