Configuration Options

🚧

PII (Personally Identifiable Information) Anonymization

Personally Identifiable Information (PII) is information that can be used on its own or with other information to identify a single person, or to identify an individual in context.

It is important for us to keep personal private information out of our servers. Therefore, by default, we do not send the request body and cookies to PerimeterX backend servers; communication is based on header data.

PII is not a recommended setting. If PII is essential for your organization, contact PerimeterX Support.

When PII is enabled, PerimeterX does not store a client’s full IP information (client IP, HTTP headers). In IPv4, this is done by zeroing 4th IP octet (for example, the IP 1.2.3.4 will be stored as 1.2.3.0). In IPv6 this is done by zeroing the last four (4) octets (for example, the IP 1:2:3:4:1:2:3:4 will be stored as 1:2:3:4:1:2:3:0).
Removing the IP's last octet can result small reduction of detection capability, usually for the models and signatures that are based on IPs.

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

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

Advanced Blocking Response Flag

Enables/disables the Advanced Blocking Response functionality.

Default: false

http {
    ...
    server {
       ...
         px_enable_json_response true;
    ...

Allowed Cookies

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

Default: Empty list

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

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

API Timeout

Controls the timeout property for PerimeterX requests. Times are in milliseconds.

Default: 1000

http {
    ...
    server {
       ...
         px_s2s_timeout 750;
    ...

Blocking Score

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

Possible values:

  • Any integer between 0 and 100.

Default: 100

http {
    ...
    server {
       ...
        px_blocking_score 100;
    ...

Credential Intelligence

The following configurations are used to enable PerimeterX Credential Intelligence offering:

Login Credentials Extraction

This feature extracts credentials (hashed username and password) from requests and sends them to PerimeterX 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)

px_enable_login_creds_extraction false;

Credentials JSON file

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

px_login_creds_settings_filename '/etc/creds.json';

Example available in examples/creds.json file. It includes an array of JSON objects containing the following properties:

{
  "id": 0, // unique int
  "method": "post", // supported methods: post
  "sent_through": "body", // supported sent_throughs: header, url, body
  "path": "/login", // login path
  "pass_field": "password", // name of the password field in the request
  "user_field": "username" // name of the username field in the request
}

Credentials Intelligence Version

Sets Credentials Intelligence protocol version
Default: 'v2'

px_credentials_intelligence_version  'v2';

Login successful header name

Default: 'x-px-login-successful'

px_login_successful_header_name  "x-px-login-successful";

Login successful header value

Default: '1'

px_login_successful_header_value  "1";

Login successful reporting method

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

px_login_successful_reporting_method  'none';

Login successful status

Sets a list of login successful status.
Default: 200

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

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

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)

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 as if in active blocking mode, even if px_block_enabled is set to false. 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

 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 PerimeterX 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

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

Default: Empty list

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

First Party URL Override

In some specific cases (as instructed by PerimeterX) 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

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

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

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

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

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

http {
    ...
    server {
       ...
        px_variables_enabled true;
    ...

Module Enabled

A boolean flag to enable/disable the PerimeterX Enforcer.

Default: false

http {
    ...
    server {
       ...
        px_enabled true;
    ...

Monitor Mode/Block Mode

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

Default: false

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

 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.

Default: Empty / false

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

Score Header

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

Default: false / empty string

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 PerimeterX servers on server-to-server API calls.

Default: "cookie" "cookies"

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 PerimeterX servers every time the route is called, regardless of viewing history.

Default: Empty list

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

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

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

Did this page help you?