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

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 with the following fields, which will determine which requests will have their credentials extracted.
Key NameExamplesNotes
login_creds::path_0"/login"The endpoint of the request
login_creds::method_0"post"Supported methods: post
login_creds::sent_through_0"body"Supported sent_throughs: body
login_creds::user_field_key_0"username"The name of the field that contains the username
login_creds::pass_field_key_0"password"The name of the field that contains the password

Note: Supported Content-Types are application/json and application/x-www-form-urlencoded.

It is also possible to use the subroutine px_custom_login_extraction_callback to extract the username and password. To do this, set the key name login_creds::use_callback_<id> to be value 1 and modify the subroutine in px_custom.vcl to extract the raw username and password from the request. When successful, the headers x-px-creds:raw-username and x-px-creds:raw-password should be set before the custom subroutine exits.

Key NameExamplesNotes
login_creds::path_0"/login"The endpoint of the request
login_creds::method_0"post"Supported methods: post
login_creds::use_callback_0"1"Supported values: 1

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. If using the px_custom_login_extraction_callback to extract the username and password, be sure it is configured properly. See the comments in the subroutines for examples of how to do this.

  2. In the px_config.vcl, change the "PX_ENABLE_LOGIN_CREDS_EXTRACTION" configuration from "0" to "1" to enable the feature.

Note: The latest version of Credentials Intelligence is enabled by default. However, if you have a multi-step SSO login process, you may change the PX_CREDENTIALS_INTELLIGENCE_VERSION configuration setting to multistep_sso.

Additional S2S Activity

To enhance detection on login credentials extraction endpoints, the following additional information is sent to PerimeterX via an additional server-to-server activity:

  • Response Code - The numerical HTTP status code of the response. This is sent automatically.
  • Login Success - A boolean indicating whether the login completed successfully. Modify the PX_LOGIN_SUCCESSFUL_REPORTING_METHOD configuration to one of status, header, or custom to configure how the login success status will be reported:
    • The value status means the module will assume that all responses with a particular status code (e.g., 200) indicate a successful login response, and all others are failures. The default value of this status code is 200, but it can be configured by setting the value for PX_LOGIN_SUCCESSFUL_STATUS.
    • The value header header means the module expects a response header named x-px-login-successful with a value of either 1 representing success or 0 representing failure.
    • The value custom means the module will call the subroutine px_custom_set_is_login_successful defined in the px_custom.vcl file. The custom subroutine can use any logic to determine if login was successful. It should indicate this by setting the response header x-px-login-successful to 1 or 0.
  • Raw Username - The original username used for the login attempt. In order to report this information, make sure the configuration PX_ENABLE_SENDING_RAW_USERNAME is set to 1. Even when enabled, the raw username will be reported to PerimeterX only if (1) the credentials were identified as compromised, and (2) the login was successful as reported via the header above.

Additional S2S Activity Header

The additional server-to-server activity may also be sent at the origin rather than automatically in the PerimeterX module. When the PX_ENABLE_ADDITIONAL_ACTIVITY_HEADER configuration is set to 1, the PerimeterX module will generate the additional_s2s activity object along with the correct URL endpoint and pass them to the origin server as headers on the original request. These values can then be extracted, added to, and sent to PerimeterX via an XHR POST request.

The two new headers added to the original request are:

  • px-additional-activity, a stringified JSON activity that should be sent.
  • px-additional-activity-url, the complete URL endpoint to which the JSON object should be sent.

Example Origin Server Code

This code provides an example of code at the origin server that handles these headers and performs the API call. The example is in JavaScript, but the process of extracting the px-additional-activity and px-additional-activity-url headers, modifying the necessary activity fields, and executing the additional_s2s XHR request to the PerimeterX servers is applicable to all servers for which this feature is enabled, regardless of language.

app.post('/login', (req, res) => {
    // complete login flow, resulting in boolean variable isLoginSuccessful
    const statusCode = isLoginSuccessful ? 200 : 401;
    res.sendStatus(statusCode);
    if (req.headers['px-additional-activity'] && req.headers['px-additional-activity-url']) {
        handlePxAdditionalActivity(req, statusCode, isLoginSuccessful);
    }
});

function handlePxAdditionalActivity(req, statusCode, isLoginSuccessful) {
    try {
        // extract url and activity from the request headers
        const url = req.headers['px-additional-activity-url'];
        const activity = JSON.parse(req.headers['px-additional-activity']);

        // change the modifiable values
        activity.details['http_status_code'] = statusCode;
        activity.details['login_successful'] = isLoginSuccessful;

        // only add in raw username is credentials are
        // compromised and the login was successful
        if (activity.details['credentials_compromised'] && isLoginSuccessful) {
            activity.details['raw_username'] = req.body.username;
        }
       
        // send the POST request
        axios.post(url, activity, {
            headers: {
                'Authorization': `Bearer ${env.PX_AUTH_TOKEN}`,
                'Content-Type': 'application/json'
            }
        });
    } catch (err) {
        console.error(`Error: ${err}`);
    }
}

Did this page help you?