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.

The PerimeterX Worker is configured using a set of properties specified in thecustom/pxConfig.json file. A minimal valid configuration file looks as follows:

//pxConfig.json
{
    px_app_id: 'APP_ID',
    px_auth_token: 'AUTH_TOKEN',
    px_cookie_secret: 'COOKIE_SECRET',
};

In addition, the following set of properties are available:

Is Bot Enforcer

A boolean flag to configure the enforcer as Bot Defender enforcer

Default: true

const pxConfig = {
 ...
 px_bot_enforcer: true
 ...
};

Is Code Enforcer

A boolean flag to configure the enforcer as Code Defender enforcer

Default: false

const pxConfig = {
 ...
 px_code_enforcer: false
 ...
};

Module Enabled

A boolean flag to enable/disable the Perimeterx worker.

Default: true

const pxConfig = {
 ...
 px_module_enabled: true
 ...
};

Module Mode

Sets the working mode of the worker.

Possible values:

  • monitor - Monitor Mode
  • active_blocking - Blocking Mode

Default: monitor

const pxConfig = {
 ...
 px_module_mode: 'monitor'
 ...
};

Blocking Score

Sets the minimum blocking score of a request.

Possible values:

  • Any integer between 0 and 100.

Default: 100

const pxConfig = {
 ...
 px_blocking_score: 100
 ...
};

Debug Mode

Sets the logging mode of the worker.

Possible values:

  • none - PerimeterX logger will not output any logs
  • error - PerimeterX logger will log errors only and fatal events (e.g., exceptions)
  • debug - PerimeterX logger will output detailed logs for debugging purposes

Be aware that log messages are present in your worker's logs tab in Cloudflare's dashboard

Default: error

const pxConfig = {
 ...
 px_logger_severity: `error`
 ...
};

Send Async Activities

A boolean flag to enable or disable sending of activities and metrics to PerimeterX on each request. Enabling this feature will provide data that populates the PerimeterX portal with valuable information, such as the amount of requests blocked and additional API usage statistics.

Default: true

const pxConfig = {
 ...
 px_send_async_activities_enabled: true
 ...
};

Sensitive Routes

An array of route prefixes that trigger the server call to PerimeterX servers every time the page is viewed, regardless of viewing history.

Default: Empty array

const pxConfig = {
 ...
 px_sensitive_routes: ['/login', '/user/checkout']
 ...
};

Sensitive Headers

An array of headers that are not sent to PerimeterX servers on API calls.

Default: ['cookie', 'cookies']

const pxConfig = {
 ...
 px_sensitive_headers: ['cookie', 'cookies', 'x-sensitive-header']
 ...
};

IP Headers

An array of trusted headers that specify an IP to be extracted. If the array is empty, the default IP header cf-connecting-ip is used.

Default: Empty

const pxConfig = {
 ...
 px_ip_headers: ['x-user-real-ip']
 ...
};

First Party Enabled

A boolean flag to enable or disable first party mode.

Default: true

const pxConfig = {
 ...
 px_first_party_enabled: false
 ...
};

Whitelist URIs

An array of route prefixes and/or regular expressions that are always whitelisted and not validated by the PerimeterX Worker. A regular expression can be defined using new RegExp or directly as an expression, and will be treated as is. A string value of a path will be treated as a prefix.

Default: Empty

const pxConfig = {
  ...
  px_whitelist_uri_full: ['/contant-us', /\/user\/.*\/show/]
  ...
};

Enforced Specific Routes

An array of route prefixes and/or regular expressions that are always validated by the PerimeterX Worker (as opposed to whitelisted routes). A regular expression can be defined using new RegExp or directly as an expression, and will be treated as is. A string value of a path will be treated as a prefix.

Default: Empty

const pxConfig = {
  ...
  px_enforced_routes: ['/home',/^\/$/]
  ...
};

Monitored Specific Routes

An array of route prefixes and/or regular expressions that are always set to be in monitor mode. This only takes effect when the module is enabled and in blocking mode. A regular expression can be defined using new RegExp or directly as an expression, and will be treated as is. A string value of a path will be treated as a prefix.

Default: Empty

const pxConfig = {
  ...
  px_monitored_routes: ['/home', new RegExp(/^\/$/)]
  ...
};

Custom Verification Handler

A JavaScript function that adds a custom response handler to the request.

Default: null

module.exports = {
  ...
    px_custom_verification_handler: (pxCtx, request) => { 
      ...
      return {body: result, status: 200, statusDescription: "OK", header: {key: 'Content-Type', value:'application/json'}};
    },
  ...
};

Additional Activity Handler

A JavaScript function that allows interaction with the request data collected by PerimeterX before the data is returned to the PerimeterX servers. This function must be set in the custom/pxCustomFunctionsConfig.js file.

Default: null

module.exports = {
  ...
    px_additional_activity_handler: (pxCtx, config) => { 
      const dataEnrichmentObject = pxCtx.pxde;
      const isDataEnrichmentVerified = pxCtx.pxdeVerified;
      ...
    },
  ...
};

Enrich Custom Parameters

With the px_enrich_custom_parameters function you can add up to 10 custom parameters to be sent back to PerimeterX servers. When set, the function is called before setting the payload on every request to PerimeterX servers. The parameters should be passed according to the correct order (1-10) and their format must align as following: custom_param1, custom_param2, ... , custom_param10. The parameters passed along with the px_enrich_custom_parameters function are request which is the Cloudflare request object, and pxCtx which is a PerimeterX object.

Default: Empty

module.exports = {
  ...
    px_enrich_custom_parameters: async (pxCtx, request) => { 
      let customParams = {};
      customParams["custom_param1"] = "yay, test value";
      // ...
      return customParams;
    },
  ...
};

CSS Ref

Modifies a custom CSS by adding the px_css_ref directive and providing a valid URL to the CSS.

Default: Empty

const pxConfig = {
  ...
  px_css_ref: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css'
  ...
};

JS Ref

Adds a custom JS file by adding px_js_ref directive and providing the JS file that is loaded with the block page.

Default: Empty

const pxConfig = {
 ...
 px_js_ref: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js'
 ...
};

Custom Logo

The logo is displayed at the top of the the block page.
Max-height = 150px, Width = auto.

Default: Empty

const pxConfig = {
 ...
 px_custom_logo: 'https://s.perimeterx.net/logo.png',
 ...
};

Filter Traffic by User Agent

An array of user agents that are always filtered and not validated by the PerimeterX Worker.

Default: Empty

const pxConfig = {
 ...
 px_filter_by_user_agent: ['testUserAgent/v1.0']
 ...
};

Filter Traffic by IP

An array of IP ranges / IP addresses that are always filtered and not validated by the PerimeterX Worker.

Default: Empty

const pxConfig = {
 ...
 px_filter_by_ip: ['192.168.10.0/24', '192.168.2.2']
 ...
};

Filter Traffic by header

An object consist of headerName: headerValue pairs that are always filtered and not validated by the PerimeterX Worker.

Default: Empty

const pxConfig = {
 ...
 px_filter_by_header: {
    test_header: "true",
    goodBot: "abc"    
 }
 ...
};

Custom Cookie Header

When set, instead of extracting the PerimeterX Cookie from the Cookie header, this property specifies a header name that will contain the PerimeterX Cookie.

Default: Empty

const pxConfig = {
 ...
 px_custom_cookie_header: "x-px-cookies"
 ...
};

Upstream Score Header

When set, this property specifies a header name that will contain the PerimeterX score to be sent to the origin.

Default: Empty

const pxConfig = {
 ...
 px_score_header_name: "x-px-score"
 ...
};

Upstream Identifier Header

When set, this property specifies a header name that will contain the PerimeterX unique identifier (UUID) to be sent to the origin.

Default: Empty

const pxConfig = {
 ...
     px_identifier_header_name: "x-px-uuid"
 ...
};

JavaScript Sensor Injection

A boolean flag to enable/disable injection of the JavaScript sensors snippet into site pages. The snippet will be added to the end of the <head> element.

Default: false

const pxConfig = {
  ...
  px_sensor_inject_enabled: true
  ...
};

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. The feature can be toggled on and off, and may be set for any number of unique paths. The settings are adjusted by modifying the custom/pxConfig JSON object.
If credentials are found to be compromised, the header px-compromised-credentials will be added to the origin request with the value 1. You may configure the name of this header with the px_compromised_credentials_header configuration.

Default Values

  • px_compromised_credentials_header: "px-compromised-credentials"
  • px_login_credentials_extraction_enabled: false
  • px_login_credentials_extraction: []
const pxConfig = {
  ...
  px_compromised_credentials_header: "x-px-comp-creds",
  px_login_credentials_extraction_enabled: true,
  px_login_credentials_extraction: [
    {
      pathType: "exact" or "regex" // default: exact
      path: "/login", // support regular expressions and exact path configuration
      method: "post", // supports all http methods
      sentThrough: "body", // supported sentThroughs: body, header, query-param
      passField: "password", // name (or array of names) of the password field in the request (can also be nested field using dots i.e details.password)
      userField: ["username", "email"] // name (or array of names) of the username field in the request (can also be nested field using dots i.e details.username)
    },
    ...
  ],
  ...
};

📘

Important Notice

Define regular expression "path": When using pathType "regex" the path attribute should contain regular expression as a string pattern, without slashes and without flags (i.e, instead of /ab+c/i configure "ab+c"). Regular expressions are treated as case-insensitive by the enforcer by default.

Configure userField or passField as an array when the same login endpoint can have two or more different field names as input.

CSP Support

Add CSP policy header to the response returned to the client (only if active CSP policy exists in PerimeterX for the specific appId) - px_csp_enabled.

Default: false

Invalidates active CSP policy after specified time in minutes where no updates were received from PerimeterX - px_csp_no_updates_max_interval_minutes.

Default: 60

const pxConfig = {
  ...
  px_csp_enabled: true,
  px_csp_no_updates_max_interval_minutes: 60
  ...
};

Pre Enforce Handler

preEnforcerHandler is a function supplied by the customer (supports both synchronous and asynchronous functions) which gets the original request and the request context constructed by PerimeterX (pxCtx) and returns an integer value (or a Promise resolved with an integer value) representing one of the following enum values:

  • 0 - continue with the request to the regular enforcer flow
  • 1 - drop the request and respond with block/captcha page (based on the customer’s policy)

Default: null

module.exports = {
  ...
    px_pre_enforce_handler: (pxCtx, request) => { 
      if (request.something) {
          return 1;
      } else {
          return 0;
      }
    },
  ...
};

Deferred Activities

A boolean flag to enable/disable sending PerimeterX page_requested activity after getting the response from the origin.

Default: true

const pxConfig = {
  ...
  px_deferred_activities: true
  ...
};

Test Block Flow on Monitoring Mode

Allows you to test an enforcer’s blocking flow while you are still in Monitor Mode. When the header name is set(e.g., x-px-block) and the value is set to 1, 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.

The Header Name is configurable using the px_bypass_monitor_header property.

Default: Empty

const pxConfig = {
  ...
  px_bypass_monitor_header: "x-px-block"
  ...
};

Snippet Injection

Determine whether to activate the dynamic snippet injection.

Default: false

const pxConfig = {
 ...
 px_snippet_provider_enable: true
 ...
};

px_snippet_provider_cache_ttl_seconds determines how long will the snippet retrieved from PerimeterX servers will be held in the cache. After the specified time period the enforcer will attempt to retrieve the snippet again from the PerimeterX servers.

Default: 600

const pxConfig = {
 ...
 px_snippet_provider_cache_ttl_seconds: 600
 ...
};

📘

Important Notice

When enabling the Snippet injection feature, do not forget to address the First Party Enabled configuration.

Defining the content of the snippet to be injected to the HTML response is done internally via PerimeterX operations team. To do so please get in touch with your PerimeterX contact person or contact support here.

Optional Configurations

Enforcer Timeout

By default, the Enforcer is set to timeout after 1000 ms. If you wish to change the value of the timeout, set the desired value of the ENFORCE_TIMEOUT property in your workerBundle.js file.

...
ENFORCE_TIMEOUT = 2000 // sets the timeout to 2000ms
...

Sign Cookie with IP

By default, cookies are signed with user agent only; however, it is possible to sign cookies with the socket IP as well. In order to enable cookie signing with the socket IP, ensure that the socket IP is extracted properly using the px_ip_headers configuration and reach out to your PerimeterX representative.

Hype Sale Challenge

The Hype Sale Challenge requires the use of the Custom Parameters feature.

Custom parameters allow you to add up to 10 custom parameters to be sent back to PerimeterX servers. When set, the px_enrich_custom_parameters function is called before setting the payload on every request to PerimeterX servers. This function can be found in the configuration object.

The configured custom parameters function must return an object which contains keys in the following format. custom_param<#> for example, will look as follows:

px_enrich_custom_parameters: async (pxCtx, request) => {
return { "custom_param1" : 11, "custom_param2": "test" }
}

Implementing the EnrichCustomParams Callback for Hype Sale
Custom parameters range from 1-10 (that is, custom_param1 through custom_param10). However, for requests that should trigger the Hype Sale Challenge, there should be a field called is_hype_sale with the boolean value true.

Since the original HTTP request is passed as an argument to the px_enrich_custom_parameters
callback, you can use identifiers on the original request (e.g., path, method, headers) to determine whether or not PerimeterX should respond with the Hype Sale Challenge.

Example usage:

var pxCustomFunctionsConfig = {
       //px_additional_activity_handler: (pxCtx, config) => { },
       //px_custom_verification_handler: (pxCtx, request) => { },
       px_enrich_custom_parameters: async (pxCtx, request) => {
           const { searchParams } = new URL(request.url);
           if (searchParams.has("id")){
               let id = searchParams.get('id');
               return {"is_hype_sale" : id === '111'}
           }
           return {};
        },
       //px_pre_enforce_handler: (pxCtx, request) => { }
   };

Did this page help you?