Configuration

🚧

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.

All configurations are set on the px_configs.vcl configuration file.

📘

Note

In the px_configs.vcl and in the px_custom.vcl the AppID must be changed according to the requirements of each VCL subroutine. In some subroutines the full AppID is required. In some subroutines the AppID without the _px prefix is required. Pay attention to the instructions in each subroutine in the px_configs.vcl and the px_custom.vcl

Required Configuration

The PerimeterX Application ID / AppId and PerimeterX Token / Auth Token can be found in the Portal, under Applications section.

The PerimeterX Cookie Encryption Key can be found in the portal, under Policies section.

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.

APP_ID


PerimeterX Custom Application ID (appID) in the format of PX__. The appId must also be added to configurations in px_custom.vcl to enable the First-Party Sensor on block pages.

📘

Note

In the px_custom.vcl, the appID is sometimes added in full, and sometimes added without the px_.

Subroutine px_configs.vcl

COOKIE_SECRET_KEY

The key used for cookie signing.

Subroutine px_configs.vcl

AUTH_TOKEN

JWT token used for REST API.

Subroutine px_configs.vcl

First-Party Configuration

As the Fastly Enforcer is an Edge Enforcer, the served JS Sensor sends the XHR requests in a first-party fashion by default. In case of a failure, the XHR will be sent directly to PX in third-party fashion as a fallback.

FIRST_PARTY_MODE

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

0 - Disabled
1 - Enabled

Subroutine px_configs.vcl

Default 1 - Enabled

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.

Optional Configuration

ENABLE_MODULE

Enable/disable PerimeterX protection

0 - Disabled
1 - Enabled

Subroutine px_configs.vcl

Default 1 - Enabled

MODULE_MODE

Configure the Module Mode.

0 - Monitor mode async Server-to-server requests are sent asynchronously.
1 - Monitor mode sync Module may not block users. Server-to-server requests are sent synchronously.
2 - Active mode Module may block users. Server-to-server requests are sent synchronously.
3 - Monitor mode with rate limiting Module will only block users that exceeded rate limit. Server-to-server requests are being sent synchronously.

Subroutine px_configs.vcl

Default 1 - Monitor Mode

ENABLE_CAPTCHA

Enable/disable the PerimeterX Captcha on block pages.

0 - Disabled
1 - Enabled (Relevant only when block is enabled)

Subroutine px_configs.vcl

Default 1 - Enabled

CUSTOM_LOGO

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

Subroutine px_configs.vcl

Default N/A

CSS_REF

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

Subroutine px_configs.vcl

Default N/A

JS_REF

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

Subroutine px_configs.vcl
Default N/A

REDIRECT_XHR

Enable/disable redirecting First-Party implementation for XHR requests.

0 - Disabled
1 - Enabled

Subroutine px_configs.vcl

Default 1 - Enabled

ENABLE_WHITELISTED_ROUTES

Enable/disable filtering out allowed routes logic

(This should not be used with specific routes config. Allowed routes config priority is stronger than specific routes).
See Modifying Allowed Routes

0 - Disabled
1 - Enabled

Subroutine Flag - config tableRoutes - check_enabled _route

Default 0 - Disabled

ENABLE_SPECIFIC_ROUTES

Enable/disable filtering specific routes logic (This should not be used with allowed routes config, Allowed routes config priority is stronger than specific routes).
See Modifying Specific Routes

0 - Disabled
1 - Enabled

Subroutine Flag - config tableRoutes - check_enabled_route

Default 0 - Disabled

ENABLE_BLOCK_SPECIFIC_ROUTES

Enable/disable marking routes for blocking regardless of Module Mode configuration.
See Defining Block Specific Routes

0 - Disabled
1 - Enabled

Subroutine Flag - config tableRoutes - check_block_specific_route

Default 0 - Disabled

ENABLE_SENSITIVE_ROUTES

Enable/disable marking routes prefixes as sensitive.
The PerimeterX module will always match the request URI with this list. If a match is found, a server-to-server call will be made.
See Defining Sensitive Routes

0 - Disabled
1 - Enabled

Subroutine Flag - config tableRoutes - check_specific _route

Default 0 - Disabled

ENABLE_COOKIE_FROM_HEADER

When set to true, the enforcer will Extract the px cookie from a header. Additional changes are required in subroutine px_custom.vcl extract_cookie from header.

Subroutine px_configs.vcl

Default 0 - Disabled

SEND_PAGE_ACTIVITIES

Enable/disable sending activities and metrics to PerimeterX on each page request.
Enabling this feature provides data that populates the PerimeterX Portal with valuable information.

0 - Disabled
1 - Enabled

Subroutine px_configs.vcl

Default 1 - Enabled

ADD_BLOCK_RESULT_HEADER

Enable/disable adding the block result header to the backend request.

0 - Disabled
1 - Enabled

Subroutine px_configs.vcl

Default 1 - Enabled

ENABLE_DEBUG

Enable/disable PerimeterX debug logs.

0 - Disabled
1 - Enabled

Subroutine px_configs.vcl

Default 0 - Disabled

ENABLE_ERROR

Enable/disable PerimeterX error logs.

0 - Disabled
1 - Enabled

Subroutine px_configs.vcl

Default 0 - Disabled

BLOCK_ALL_SIZE_EXCEEDED_POST_REQUESTS

When a POST request is over 8k, the POST request is blocked or process on monitor mode.

Subroutine px_configs.vcl

Default 0 - Disabled

BLOCK_SIZE_EXCEEDED_POST_REQUESTS_SPECIFIC_ROUTES

When a specific route POST request is over 8k, the POST request is blocked or process on monitor mode. The specific routes are defined in the px.vcl.

Subroutine px_configs.vcl

Default 0 - Disabled

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

Subroutine px_configs.vcl

Default 0 - Disabled

PX_SYSLOG_NAME

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

Subroutine px_configs.vcl

Default PX-Syslog

DEBUG_SYSLOG_NAME

The name of the predefined Debug Syslog for sending debug messages.
Syntax example: [PX-DEBUG] ReqId: 61fc2b55ccd7b5 8cb830c635a8b6 9443290079aa...

Subroutine px_configs.vcl

Default PX-Debug

ENABLE_PRE_CLEAN

Enable/disable pre-headers cleanup logic.

Subroutine px_configs.vcl

Default 0 - Disabled

ENABLE_ACCESS_CONTROL_HEADER

Enable/disable appending access control header to support CORS

Subroutine px_configs.vcl

Default 0 - Disabled

Modifying Allowed Routes

When the Enable Allowed Routes flag (in the config table) is set to “1”, the allowed routes can be modified at check_enabled_route subroutine.

For example, to allow all requests to /dontblockhere1 and /dontblockhere2 add the following regex to check_enabled_route as follows:

if (req.url.path ~ {"^/exact/dontblockhere$|^/prefix/dontblockhere"})

Modifying Specific Routes

When the Enable Specific Routes flag (in the config table) is set to “1”, the specific routes can be modified in the check_enabled_route subroutine.

For example, to enable only the following routes: /blockhere” and /blockhere2 add the following regex to check_enabled_route as follows:

if (req.url.path ~ {"^/exact/blockhere$|^/prefix/blockhere"})

For an exact match, use ^XXX$, and for a prefix match, use ^XXX.

Defining Sensitive Routes

When Enable Sensitive Routes flag (in the config table) is set to “1”, the sensitive routes can be modified in the check_sensitive_route subroutine.

For example, to set the following routes: /prefix* and /exact/match add the following regex to check_sensitive_route as follows:

if (req.url.path ~ {"^/prefix|^/exact/match$"})

Defining Specific Blocking Routes

When the Enable Block Specific Routes flag (in the config table) is set to “1”, the block specific routes can be modified in the check_block_specific_route subroutine.

For example, to set the following routes: /prefix* and /exact/match add the following regex to check_block_specific_route as follows:

if (req.url.path ~ {"^/prefix|^/exact/match$"})

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 Data Enrichment 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:

sub px_custom_data_enrichment_handler {
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

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

When the px_custom_check_bypass_monitor 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 {
   if (req.http.my-custom-header == "1") {
     set req.http.X-PX-config:enable-bypass-monitor-header = "1";
   }
 }

Did this page help you?