> 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 ## Module Enabled A boolean flag to enable/disable the HUMAN Enforcer. **Default:** `false` ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_enabled: true ... ``` ## Monitor Mode/Block Mode By default, the PerimeterX plugin is set to Monitor Only mode. To active blocking mode, set the `px_block_enabled` property to `true`. **Default:** `false` ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_block_enabled: true ... ``` ## 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` ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_blocking_score: 100 ... ``` ## Debug Mode A boolean flag to enable/disable the debug log messages. **Default:** `false` ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_debug: true ... ``` ## Sensitive Routes An array of route prefixes/suffixes that trigger a server call to PerimeterX servers every time the route is called, regardless of viewing history. **Default:** Empty array ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_sensitive_routes_prefix: ["/login", "/user/profile"] px_sensitive_routes_suffix: ["/download"] ... ``` ## 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 array ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: # 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"] ... ``` ## 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 array (all routes are active) ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: # The plugin will be active only on `/search` and `/products` route prefixes. px_enabled_routes: ["/search" "/products"] ... ``` ## Sensitive Headers An array of headers that are not sent to HUMAN servers on server-to-server API calls. **Default:** \["cookie", "cookies"] ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_sensitive_headers: ["x-px-auth", "x-px-key"] ... ``` ## IP Headers An array of trusted headers that specify an IP to be extracted. **Default:** Empty array ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_ip_headers: ["X-Forwarded-For"] ... ``` ## Enrich Custom Parameters An array 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 array ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_custom_parameters: ["x-user-id", "x-vid"] ... ``` ## Score Header A set of properties configuring sending the PerimeterX score on upstream and/or downstream headers. **Default:** `false` / empty string ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: # 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" ... ``` ## API Timeout Controls the timeout property for HUMAN requests. Times are in MS. **Default:** `1000` ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_s2s_timeout: 750 ... ``` ## Allowed Cookies An array of cookie names that are allowed to be sent to HUMAN servers on server-to-server calls. **Default:** Empty array ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_allowed_cookies: ["SID", "NID"] ... ``` ## Advanced Blocking Response Flag Enables/disables the Advanced Blocking Response functionality. **Default:** `false` ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_enable_json_response: true ... ``` ## CSS Ref Modifies a custom CSS by adding the `px_css_ref` property and providing a valid URL to the CSS. **Default:** Empty ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_css_ref: "http://www.example.com/style.css" ... ``` ## 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 ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_js_ref: "https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" ... ``` ## Custom Logo The logo is displayed at the top of the the block page.\ Max-height = 150px, Width = auto. **Default:** Empty ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_custom_logo: "http://www.example.com/logo.png" ... ``` ## Test Block Flow on Monitoring Mode Allows you to test an enforcer’s blocking flow while you are still in Monitor Mode. When the header name is set (eg. `x-px-block`) and the value is set to `1`, when there is a block response (for example from using a User-Agent header with the value of `PhantomJS/1.0`) the Monitor Mode is bypassed and full block mode is applied. If one of the conditions is missing you will stay in Monitor Mode. This is done per request.\ To stay in Monitor Mode, set the header value to `0`. **Default:** Empty ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_bypass_monitor_header: "x-px-block" ... ``` ## 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 ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_active_header_name: "x-px-active" ... ``` ## 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**: `""` ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: 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**: `""` ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: 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**: `[]` ```yaml http_filters: ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: 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**: `""` ```yaml ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: 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**: `""` ```yaml ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: 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**: `[]` ```yaml ... - name: perimeterx typed_config: "@type": type.googleapis.com/udpa.type.v1.TypedStruct type_url: type.googleapis.com/perimeterx.Enforcer value: px_jwt_header_additional_field_names: ['exp', 'iss'] ```