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

Config nameDescription
px_app_idPerimeterX Custom Application ID (appID) in the format of PX__. The appId must also be added to configurations in px.vcl to enable the First-Party Sensor on block pages
px_cookie_secretSecret key used for cookie signing
px_auth_tokenJWT token used for REST API

📘

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

Config name

Description

Values

Default value

Custom function name

Feature Name

px_module_enabled

Enable/disable PerimeterX module protection

"false" - Disabled
"true" - Enabled

"true" - Enabled

N/A

module_enable

px_module_mode

Configure the Module Mode.

monitor - Monitor mode sync Module may not block users. Server-to-server requests are sent synchronously.
active_blocking - Active mode Module may block users. Server-to-server requests are sent synchronously.

monitor

N/A

module_mode

N/A

Enable specific endpoints to be monitored rather than enforced by PerimeterX

N/A

N/A

px_custom_monitored_routes

monitored_routes

N/A

Enable specific endpoints to be enforced rather than monitored by PerimeterX

N/A

N/A

px_custom_enforced_routes

enforced_routes

N/A

Activates active blocking in monitor mode when a custom header is set custom value.

N/A

N/A

px_custom_check_bypass_monitor_header

bypass_monitor_header

px_custom_logo

Enables the user to set a custom logo on the block page.

Logo url

""

N/A

custom_logo

px_css_ref

Enables the user to set a custom CSS on the block page.

CSS url

""

N/A

custom_css

px_js_ref

Enables the user to set a custom Javascript for the block page.

JS Script url

""

N/A

custom_js

px_first_party_enabled

Enable/disable serving the JS Sensor and XHR requests from the enforcer as First-Party.

"false" - Disabled
"true" - Enabled

"true"

N/A

first_party

px_backend_url

Set custom backend url

Backend url

""

N/A

N/A

px_filter_by_extension_enabled

Enable filter by extension
(Request will skip Enforcer validation process immediately)

"false" - Disabled
"true" - Enabled

"false"

px_custom_filter_by_extension

filter_by_extension

px_filter_by_http_method_enabled

Enable filter by HTTP method
(Request will skip Enforcer validation process immediately)

"false" - Disabled
"true" - Enabled

"false"

px_custom_filter_by_http_method

filter_by_http_method

px_filter_by_route_enabled

Enable filter by route
(Request will skip Enforcer validation process immediately)

"false" - Disabled
"true" - Enabled

"false"

px_custom_filter_by_route

filter_by_route

px_filter_by_user_agent_enabled

Enable filter by user agent
(Request will skip Enforcer validation process immediately)

"false" - Disabled
"true" - Enabled

"false"

px_custom_filter_by_user_agent

filter_by_user_agent

px_filter_by_ip_enabled

Enable filter by ip
(Request will skip Enforcer validation process immediately)

"false" - Disabled
"true" - Enabled

"false"

px_custom_filter_by_ip

filter_by_ip

px_sensitive_routes_enabled

Enable sensitive routes

"false" - Disabled
"true" - Enabled

"false"

px_custom_check_sensitive_route

sensitive_routes

px_sensitive_headers_enabled

Enable sensitive headers removal

"false" - Disabled
"true" - Enabled

"false"

px_custom_unset_sensitive_headers

sensitive_headers

px_enable_captcha

Enable captcha page on block

"false" - Disabled
"true" - Enabled

"false"

N/A

block_page_captcha

N/A

Custom block page

N/A

Default block page

px_custom_create_block_page,
px_custom_block_handler,
px_custom_post_block_handler

block_page_captcha

N/A

Advanced blocking response

N/A

Default Advanced block response

px_custom_create_advanced_blocking_response

advanced_blocking_response

px_enable_redirect_xhr

Enable redirect sensor requests via first party

"false" - Disabled
"true" - Enabled

"true"

N/A

first_party

px_custom_cookie_header_enabled

Enable receive cookie from custom header

"false" - Disabled
"true" - Enabled

"false"

px_custom_cookie_header

custom_cookie_header

px_additional_activity_handler_enabled

Enable additional activity handler to run after sending async activity

"false" - Disabled
"true" - Enabled

"false"

px_custom_additional_activity_handler

additional_activity_handler

px_send_page_activities

Enable sending page_requested and block async activities

"false" - Disabled
"true" - Enabled

"true"

N/A

page_requested_activity, block_activity

px_add_block_result_header

Enable add block result header

"false" - Disabled
"true" - Enabled

"false"

N/A

N/A

px_logger_severity

Logger severity types

debug, error

""

N/A

logger

px_debug_probability

Probability for printing debug logs

[1-100000]

"1"

N/A

logger

px_enable_error_logs

Enable error logs

"false" - Disabled
"true" - Enabled

"false"

N/A

logger

px_block_all_size_exceeded_post_requests

Enable blocking of post requests that exceeded max size: When a POST request is over 8k, or GET/POST request with too long (~15kb) header size, the request is blocked or process on monitor mode.

"false" - Disabled
"true" - Enabled

"false"

N/A

N/A

px_block_size_exceeded_post_requests_specific_routes

Enable blocking post requests that exceeded max size on specific routes: When a specific route POST request is over 2k, the POST request is blocked or process on monitor mode. The specific routes are defined in the px_custom.vcl

"false" - Disabled
"true" - Enabled

"false"

px_custom_check_block_post_url

N/A

px_block_size_exceeded_post_requests_by_size

Enable blocking post requests that exceeded custom size: When a POST request is over a defined size, the POST request is blocked or process on monitor mode. The specific size is defined in the px.vcl

"false" - Disabled
"true" - Enabled

"false"

px_custom_check_block_by_size

N/A

px_syslog_name

The name of the predefined PerimeterX Syslog that sends mandatory data to the PerimeterX Syslog servers.

<syslog-endpoint-name>

"PX-Syslog"

N/A

page_requested_activity, block_activity

px_debug_syslog_name

The name of the predefined Debug Syslog for sending debug messages

<syslog-endpoint-name>

"PX-Debug"

N/A

N/A

px_error_syslog_name

The name of the predefined Debug Syslog for sending error messages

<syslog-endpoint-name>

"PX-Error"

N/A

N/A

px_enable_pre_clean

Enable calling custom function before cleaning PX module headers

"false" - Disabled
"true" - Enabled

"false"

px_custom_pre_clean

N/A

px_pxhd_secure_enabled

Enables the user to set pxhd cookie with a 'Secure' flag

"false" - Disabled
"true" - Enabled

"false"

N/A

N/A

px_remote_data_enabled

Enable receiving remote data from PX (required for CSP remote update)

"false" - Disabled
"true" - Enabled

"false"

N/A

csp_support

px_csp_enabled

Enable CSP feature

"false" - Disabled
"true" - Enabled

"false"

N/A

csp_support

px_sensitive_graphql_operations_enabled

Enable sensitive GraphQL operation

"false" - Disabled
"true" - Enabled

"false"

px_custom_check_sensitive_graphql_operation

N/A

px_login_credentials_extraction_enabled

Enable credentials extraction

"false" - Disabled
"true" - Enabled

"false"

px_login_credentials_extraction

login_credentials_extraction

px_credentials_intelligence_version

Credentials extraction version

v1/multistep_sso

v1

N/A

login_credentials_extraction

px_additional_s2s_activity_header_enabled

Enables adding the additional_s2s activity payload as a header on the origin request instead of sending the activity automatically

"false" - Disabled
"true" - Enabled

N/A

login_credentials_extraction

px_send_raw_username_on_additional_s2s_activity

Enables adding the raw username to the additional_s2s activity payload if the credentials are compromised and login was successful

"false" - Disabled
"true" - Enabled

"false"

N/A

login_credentials_extraction

px_login_successful_reporting_method

The method used for determining whether a login request was successful

status - reports a successful login if the status code configured in px_login_successful_status is returned from the origin
header - reports a successful login if the header x-px-login-successful with value 1 exists on the origin response
custom - calls the px_custom_set_login_successful_response_header subroutine to determine whether login was successful

"status"

px_custom_set_login_successful_response_header

login_credentials_extraction

px_login_successful_status

The status code representing a successful login. Used if px_login_successful_reporting_method is status

N/A

"200"

N/A

login_credentials_extraction

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

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.
  1. 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.
Key NameExamplesNotes
path_0"/login"The endpoint of the request
method_0"post"Supported methods: post
sent_through_0"body"Supported sent_throughs: body
user_field_0"username"The name of the field that contains the username
pass_field_0"password"The name of the field that contains the password

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.

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

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

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>”};
}

Did this page help you?