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, the entire communication is based on headers 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.

📘

Manual Installation Note

As part of VCL installation there are All <appid> instances must be replaced with Application Id value.
All <appid-suffix> instances must be replaced with the Application Id without _px prefix.
Pay attention to the instructions in each instance on px_configs.vcl and px.vcl custom VCL files.

All configurations are available on px_configs.vcl configuration file.

Basic Configurations

From v8.0.0

📘

Basic configurations values

Application ID / AppId and PerimeterX Token / Auth Token can be found in the Portal, under Applications section.
Cookie Encryption Key can be found in the portal, under Policies section.

Note: The Policy from where the Cookie Encryption Key is taken must correspond with the Application from where the Application ID / AppId and PerimeterX Token / Auth Token.

Advanced Configurations

From v8.0.0

Basic and advanced configuration up to v7.2.0

px_configs {
  "APP_ID": "",
  "COOKIE_SECRET_KEY": "",
  "AUTH_TOKEN": "",
  "ENABLE_MODULE": "1",
  "MODULE_MODE": "1",
  "ENABLE_CAPTCHA": "1",
  "CUSTOM_LOGO": "",
  "CSS_REF": "",
  "JS_REF": "",
  "FIRST_PARTY_MODE": "1",
  "REDIRECT_XHR": "1",
  "ENABLE_WHITELISTED_ROUTES": "0",
  "ENABLE_SPECIFIC_ROUTES": "0",
  "ENABLE_BLOCK_SPECIFIC_ROUTES": "0",
  "ENABLE_SENSITIVE_ROUTES": "0",
  "ENABLE_COOKIE_FROM_HEADER": "0",
  "SEND_PAGE_ACTIVITIES": "1",
  "ADD_BLOCK_RESULT_HEADER": "0",
  "ENABLE_DEBUG": "0",
  "ENABLE_ERROR": "0",
  "BLOCK_ALL_SIZE_EXCEEDED_POST_REQUESTS": "0",
  "BLOCK_SIZE_EXCEEDED_POST_REQUESTS_SPECIFIC_ROUTES": "0",
  "BLOCK_SIZE_EXCEEDED_POST_REQUESTS_BY_SIZE": "0",
  "PX_SYSLOG_NAME": "PX-Syslog",
  "DEBUG_SYSLOG_NAME": "PX-Debug",
  "ENABLE_PRE_CLEAN": "0",
  "ENABLE_ACCESS_CONTROL_HEADER": "0",
  "USE_SINGLE_BACKEND" : "1",
  "PXHD_SECURE": "0",
  "REMOTE_DATA": "0",  
  "CSP_ENABLE": "0",
  "REMOTE_BLOCK_ENABLE": "0",
  "REMOTE_BLOCK_MAX_SIZE": "1000",
  "PX_ENABLE_LOGIN_CREDS_EXTRACTION": "0",
  "PX_CREDENTIALS_INTELLIGENCE_VERSION": "v1",
  "PX_ENABLE_ADDITIONAL_ACTIVITY_HEADER": "0",
  "PX_ENABLE_SENDING_RAW_USERNAME": "0",
  "PX_LOGIN_SUCCESSFUL_REPORTING_METHOD": "status",
  "PX_LOGIN_SUCCESSFUL_STATUS": "200"
}

Customized Subroutines

In order to complete the configuration of some of the additional features,
it is required to modify a customized subroutines that are called as part of the feature flow.
All customized subroutines are available on px_custom.vcl file, with instructions for how to use them.

For each feature the corresponding custom function name is under Custom function name column for each config. Example:

# Description: Set custom cookie header to extract PX cookies from
# Input Headers:
# req.http.<custom_cookie_header>: Custom header contains the PX cookies values
# Output Headers:
# req.http.cookie: PX cookies values
# Instructions: 1. Uncomment the sample code inside px_custom_cookie_header subroutine below.
#               2. Replace <custom_cookie_header> with the desired header name that stores PX cookies.
sub px_custom_cookie_header {
#   set req.http.cookie = req.http.<custom_cookie_header>;
#   unset req.http.<custom_cookie_header>;
#   set req.http.X-PX-ADD-cookie-origin = "header";
}

Module Enabled

Enables/disables the Enforcer.

v8.0.0 and up
Name: px_module_enabled
Values:

• true - Enabled (default)
• false - Disabled

v7.2.0 and below
Name: ENABLE_MODULE
Values:

• 1 - Enabled (default)
• 0 - Disabled

table px_configs {
  "px_module_enabled": "false",
}

table px_configs {
  "ENABLE_MODULE": "0",
}

Module Mode

Sets the working mode of the Enforcer.

Monitor mode - Use this mode to fine-tune and test your system. When in the Monitor mode, the Enforcer will pass through requests that would otherwise be blocked.
Active Blocking mode - Switch to this mode after making sure the Enforcer is operating properly in the Monitor mode. The Enforcer will block requests when necessary.

v8.0.0 and up
Name: px_module_mode
Values:

• monitor - Monitor mode (default)
• active_blocking - Active Blocking mode

v7.2.0 and below
Name: MODULE_MODE
Values:

• 0 - Monitor mode (default)
• 1 - Active Blocking mode

table px_configs {
  px_module_mode: 'monitor',
}

table px_configs {
  MODULE_MODE: 0,
}

Filter by Route

You may want certain routes to be accessible regardless of PerimeterX's detection. These routes will not be blocked, regardless of the score they receive. A client request to a filtered route will not generate any risk or async activities.

TO define filtered routes:

1. Open the PX_CUSTOM.vcl fie.
2. Modify the custom subroutine px_custom_filter_by_route. The subroutine evaluates the request path and sets the header X-PX-filter-by:route to "1" to indicate that the request should be filtered, if needed.

For example:

sub px_custom_filter_by_route {
   if (req.url.path ~ {"^/prefix|^/exact/match$"}) {
      set req.http.X-PX-filter-by:route = "1";
   }
}

To learn more about custom subroutines, see Customized subroutines.

TO enable the feature:

v8.0.0 and up

1. Open the PX_CONFIG.vcl file.
2. Set the px_filter_by_route_enabled value to "true" (enabled). The default is "false" (disabled).

table px_configs {
  "px_filter_by_route_enabled": "true",
}

v7.2.0 and below

1. Open the PX_CONFIG.vcl file.
2. Set the ENABLE_WHITELISTED_ROUTES value to "1" (enabled). The default is "0" (disabled).

table px_configs {
  "ENABLE_WHITELISTED_ROUTES": "1",
}

Enforced Routes

You may want certain requests to be enforced by PerimeterX, even when the Enforcer is in the Monitor mode. These are enforced routes. Enforced routes will go through the full Enforcer workflow, including blocking requests when necessary. That is, even when the Enforcer is in the Monitor mode, these routes will behave as if in the Blocking mode.

TO define enforced routes:

1. Open the PX_CUSTOM.vcl file.
2. Modify the custom subroutine px_custom_enforced_routes. The subroutine evaluates the request path and sets the header X-PX-enforced-route to “1” to indicate that the request should be enforced, if needed.

For example:

sub px_custom_enforced_routes {
  if (req.url.path ~ {"^/prefix|^/exact/match$"}) {
    set req.http.X-PX-enforced-route = "1";
  }
}

To learn more about custom subroutines, see Customized subroutines.

Only for v7.2.0 and below:

After defining the enforced routes, as explained above:

1. Open the PX_CONFIG.vcl file.
2. Set the ENABLE_BLOCK_SPECIFIC_ROUTES value to “1” (enabled). The default is “0” (disabled).

table px_configs {
  "ENABLE_BLOCK_SPECIFIC_ROUTES": "1",
}

First Party

To prevent suspicious or unwanted behavior on the client side, some browsers or extensions (such as an Adblock extension) may deny the frontend JavaScript code from making requests to other domains. This prevents the PerimeterX Sensor from making requests to the PerimeterX servers, which greatly limits PerimeterX's detection capabilities. To avoid this problem, the First Party feature enables the Enforcer to be used as a proxy for PerimeterX servers, and to serve content to the browser from a first party endpoint (i.e., an endpoint on the customer’s domain).

We recommend to keep the First Party enabled at all times.
However, if for some reason you need to disable the First Party feature, follow the steps below:

v8.0.0 and up

1. Open the PX_CONFIG.vcl file.
2. Change the px_first_party_enabled value to "false" (disabled). The default value is “true” (enabled).

table px_configs {
  "px_first_party_enabled": "false",
}

v7.2.0 and below

1. Open the PX_CONFIG.vcl file.
2. Change the FIRST_PARTY_MODE value to “0” (disabled). The default value is “1” (enabled).

table px_configs {
  "FIRST_PARTY_MODE": "0",
}

Additional Activity Handler

The Additional Activity Handler is a callback function passed to the Enforcer. The Enforcer runs this callback after sending the page_requested or block activity to the Collector, and before forwarding the request to the next step in the pipeline. A common use case of the Additional Activity Handler is to set the score as a variable or header. Then the application can read the score and implement the application logic.

TO define the feature:

1. Open the PX_CUSTOM.vcl file.
2. Modify px_custom_additional_activity_handler to perform the required logic.

Example

sub px_custom_additional_activity_handler {
  set req.http.x-px-score = if(req.http.x-px-validated-request == "1", "0", "100");
}

TO enable the feature:

v.8.0.0 and up

1. Open the PX_CONFIG.vcl file.
2. Set the px_additional_activity_handler_enabled value to "true" (enabled). The default is "false" (disabled).

table px_configs {
  "px_additional_activity_handler_enabled": "true",
}

v7.2.0 and below

1. Open the PX_CONFIG.vcl file.
2. Set the PX_ENABLE_ADDITIONAL_ACTIVITY_HEADER value to "1" (enabled). The default is "0" (disabled).

table px_configs {
  "PX_ENABLE_ADDITIONAL_ACTIVITY_HEADER": "1",
}

Custom Logo

Adds a custom logo to the block page that will be shown to users. The configuration directs to an URL with the logo file.
Use a .png file with a max height of 150px.

Default: empty

Example:

table px_configs {
  px_custom_logo: 'https://s.perimeterx.net/logo.png',
}

table px_configs {
  CUSTOM_LOGO: 'https://s.perimeterx.net/logo.png',
}

Custom CSS

Allows you to set a custom CSS on the Block page. The function directs to an URL with the CSS file.

Default: empty

Example:

table px_configs {
  px_css_ref: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css',
}

table px_configs {
  CSS_REF: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css',
}

Custom JS script

Allows you to add a custom JS script to the Block page. This script will run after the default JS scripts.

Default: empty

Example:

table px_configs {
  px_js_ref: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js',
}

table px_configs {
  JS_REF: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js',
}

Filter By Extension

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

Default: Disabled

TO define which extensions to filter:

1. Open the PX_CUSTOM.vcl file.
2. Enter extensions under px_custom_filter_by_extension as shown in the example below.

Example

sub px_custom_filter_by_extension {
if ((req.request == "GET" || req.request == "HEAD") && req.url.ext ~ "(?i)
(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)$")
}

TO enable the feature:

1. Open the PX_CONFIG.vcl file.
2. Change the value as shown below:

table px_configs {
  "px_filter_by_extension_enabled": "true",
}

PerimeterX First-Party JS Snippet

To deploy the PerimeterX First-Party JS Snippet:

1. Generate the First-Party Snippet

• Go to Applications >> Snippet.
• Select First-Party.
• Select Use Default Routes.
• Click Copy Snippet to generate the JS Snippet.

2. Deploy the First-Party Snippet

Copy the JS Snippet and deploy using a tag manager, or by embedding it globally into your web template for which websites you want PerimeterX to run.

Module Context Object

• X-PX-risk-rtt - The time (in ms) it took to make server-to-server call (if one occurred).
• X-PX-uuid - The unique identifier of the request.
• X-PX-data-enrichment - The PerimeterX data enrichment object see the data enrichment documentation for more information.
• X-PX-data-enrichment-validated - A boolean flag indicating whether the data enrichment is signed correctly and was not modified.

To use these headers (or any other PerimeterX header), it is recommended to use the px_custom_pre_clean subroutine. This subroutine is called just before the PerimeterX headers are removed from the request. A user who wants to keep the data from one of these headers, can do so by saving the value on a different, user-defined header.

Data Enrichment

The PerimeterX Fastly Enforcer provides a hook function where processing is performed on the data enrichment payload

px_custom.vcl contains the custom hook function px_custom_data_enrichment_handler.

The function receives the following headers:

• X-PX-data-enrichment: A JSON string with data enrichment.
• X-PX-data-enrichment-validated: A boolean flag indicating when data enrichment is trusted and has not been tampered with (possible values: 0 or 1)

To extract values from the JSON object, set: req.http.X-PX-de-value = if (req.http.X-PX-data-enrichment ~ {“”VALUE_HERE”:”([^”]*)”}, re.group.1, “”);

When it is determined that the request should be passed to the backend server, set the X-PX-de-pass-request = “1”

Example:

  set req.http.X-PX-de-f-type = if (req.http.X-PX-data-enrichment ~ {“”f_type”:”([^”]*)”}, 
re.group.1, “”); 

  if (req.http.X-PX-de-f-type == “w”) {
    set req.http.X-PX-de-pass-request = “1”;
  }
}

Test Block Flow on Monitoring Mode - Bypass Monitor Header

Allow you to test an enforcer’s blocking flow while you are still in Monitor Mode.

When the px_custom_check_bypass_monitor_header subroutine is implemented and the configured request header (my-custom-header in the example) has the value set to 1, then 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.

Implementation Example:

# px_custom.vcl:
sub px_custom_check_bypass_monitor_header {
  if (req.http.my-custom-header-name == "1") {
    set req.http.X-PX-config:enable-bypass-monitor-header = "1";
  }
}

CSP

Creating and Configuring the Edge-Dictionary

In order to support Code Defender CSP Capability in Fastly Enforcer the following configurations are required:

1. The Fastly Enforcer module should be upgraded to v6.0.0 or higher.

2. Create an edge-dictionary named px_csp_rdata to contain the CSP data with the following command.

curl -X POST -H 'Fastly-Key: FASTLY_API_TOKEN' -d 'name=px_csp_rdata' https://api.fastly.com/service/<service_id>/version/<version_number>/dictionary

See the Fastly documentation for more information on edge-dictionaries.

3a. In the px_config.vcl, create the cs_data dictionary with a Fastly API key with Engineering permission. and the px_csp_rdata dictionary ID

or

3b. Create the cs_data dictionary as an edge-dictionary with a Fastly API key with Engineering permission and the px_csp_rdata dictionary ID

table cs_data {
     "eng_key": "1234567",
     "px_csp_rdata_id": "12345678"
}

The PerimeterX team will take over the rest of the integration process once your edge-dictionary is configured.

When the our back-end work is finished, CSP is integrated on your site, and you can enable and disable the policy from your console.

Login Credentials Extraction

This feature extracts credentials (hashed username and password) from requests and sends them to PerimeterX as additional info in the risk api call. If credentials are found to be compromised, the request passed to the origin will have the header px-compromised-credentials with the value 1. The feature can be toggled on and off, and may be set for any number of unique paths.

To enable the feature, you must do the following:

1. Add a table or Fastly dictionary named px_login_credentials_extraction with the following fields, which will determine which requests will have their credentials extracted.

The request body will be parsed based on its Content-Type header. Supported content types are: application/json and application/x-www-form-urlencoded.

Notice that all fields in this example end in _<id> to allow the configuration of multiple endpoints. For example, to configure a second endpoint, add these same fields with _1 instead of _0 at the end of the key name to the table.

Note: If you use a Fastly dictionary to configure these values, remove the empty table declaration in the px_config.vcl file.

2. In the px_custom.vcl, modify the px_custom_is_login_request subroutine to set req.http.login-set to the proper ending (e.g., _0, _1, etc.) depending on the request path. See the comments in the subroutine for examples of how to do this.

3. In the px_config.vcl, change the "px_login_credentials_extraction_enabled" field from "0" to "1" to enable the feature.

Credentials Intelligence - OKTA Integration

As part of the Credentials Intelligence feature, an indication of compromised credentials should be passed to the origin.

In case of OKTA the indication will be passed on the query string compromised_credentials with the value true.

In case the credentials were compromised and the login attempt succeeded, there is an option to change the status code of the response, so that it will fail.

In order to enable the query string indication use the px_credentials_intelligence_query_string flag, set it as true.

In order to set the status code on a successful login response that has been made with compromised credentials use the px_compromised_credentials_returned_status_response field and set unauthorized HTTP status code such as 401.

Advanced Blocking Response

In special cases, (such as XHR post requests) a full Captcha page render might not be an option. In such cases, using the Advanced Blocking Response returns a JSON object containing all the information needed to render your own Captcha challenge implementation, be it a popup modal, a section on the page, etc. The Advanced Blocking Response occurs when a request contains the Accept header with the value of application/json. A sample JSON response appears as follows:

{
    "appId": String,
    "jsClientSrc": String,
    "firstPartyEnabled": Boolean,
    "vid": String,
    "uuid": String,
    "hostUrl": String,
    "blockScript": String
}

Once you have the JSON response object, you can pass it to your implementation (with query strings or any other solution) and render the Captcha challenge.

In addition, you can add the _pxOnCaptchaSuccess callback function on the window object of your Captcha page to react according to the Captcha status. For example when using a modal, you can use this callback to close the modal once the Captcha is successfully solved.
An example of using the _pxOnCaptchaSuccess callback is as follows:

window._pxOnCaptchaSuccess = function(isValid) {
    if(isValid) {
        alert("yay");
    } else {
        alert("nay");
    }
}

Returning A Custom Block Page

It is possible to return a customized block page instead of PX default one.
The block page returned by Fastly Enforcer is defined in the subroutine px_custom_create_block_page in px_custom.vcl file.
To set your own block page, set the req.http.X-PX-block-page header to a string containing the html of the desired block page.
For example:

sub px_custom_create_block_page {
  set req.http.X-PX-block-page = {“<!DOCTYPE html> <html> <body> block page </body> </html>”};
}

Custom First Party Sensor Endpoint

The default first party endpoint to retrieve the PerimeterX 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.

"px_custom_first_party_sensor_endpoint": "/botdefense"

Note: The /<app_id_without_PX>/init.js endpoint will continue to work even when a custom endpoint is configured.

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

// JS snippet code

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