PerimeterX Plugin Configuration


The PerimeterX Lua Module configuration is in the following location:

-- ## Required Parameters ##
  _M.px_appId = 'PX_APP_ID'
  _M.auth_token = 'PX_AUTH_TOKEN'
  _M.cookie_secret = 'COOKIE_ENCRYPTION_KEY'
  1. The PerimeterX Application ID / AppId and PerimeterX Token / Auth Token / Authorization Token can be found in the Portal, under Applications.
  1. PerimeterX Cookie Encryption Key / Risk Cookie can be found in the portal, under Policies.

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

Optional Configurations


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; communication is based on header 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 will be stored as 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.

Monitor / Block Mode Configuration

By default, the PerimeterX plugin is set to monitor mode.

_M.block_enabled = false

Adding the _ M.block_enabled flag and setting it to true in the pxconfig.lua file activates the module to enforce blocking. This means the PerimeterX Module blocks requests that exceed the block score threshold. If a request receives a risk score that is equal to or greater than the block score, a block page is displayed.

Debug Mode

Enables debug logging mode.

Default: false (disabled)

_M.px_debug = true

When Enabled, PerimeterX debug messages should be in the following template:

  • For debug messages - [PerimeterX - DEBUG] [APP_ID] - MESSAGE

  • For error messages - [PerimeterX - ERROR] [APP_ID] - MESSAGE

    Valid request flow example:

2017/12/04 12:04:18 [error] 7#0: *9 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - Cookie V3 found - Evaluating, client:, server: , request: "GET / HTTP/1.1", host: "localhost:8888"
  2017/12/04 12:04:18 [error] 7#0: *9 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - cookie is encyrpted, client:, server: , request: "GET / HTTP/1.1", host: "localhost:8888"
  2017/12/04 12:04:18 [error] 7#0: *9 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - Cookie evaluation ended successfully, risk score: 0, client:, server: , request: "GET / HTTP/1.1", host: "localhost:8888"
  2017/12/04 12:04:18 [error] 7#0: *9 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - Sent page requested acitvity, client:, server: , request: "GET / HTTP/1.1", host: "localhost:8888"
  2017/12/04 12:04:18 [error] 7#0: *9 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - Request is internal. PerimeterX processing skipped., client:, server: , request: "GET / HTTP/1.1", host: "localhost:8888"
  2017/12/04 12:04:19 [error] 7#0: *63 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - POST response status: 200, context: ngx.timer
  2017/12/04 12:04:19 [error] 7#0: *63 [lua] pxlogger.lua:29: debug(): [PerimeterX - DEBUG] [ APP_ID ] - Reused conn times: 3, context: ngx.timer


Allowing (bypassing enforcement) is configured in the pxconfig.lua file.

Several filters can be configured:

_M.whitelist_uri_full = { _M.custom_block_url },
_M.whitelist_uri_prefixes = {},
_M.whitelist_uri_suffixes = {'.css', '.bmp', '.tif', '.ttf', '.docx', '.woff2', '.js', '.pict', '.tiff', '.eot', '.xlsx', '.jpg', '.csv', '.eps', '.woff', '.xls', '.jpeg', '.doc', '.ejs', '.otf', '.pptx', '.gif', '.pdf', '.swf', '.svg', '.ps', '.ico', '.pls', '.midi', '.svgz', '.class', '.png', '.ppt', '.mid', 'webp', '.jar'},
_M.whitelist_ip_addresses = {},
_M.whitelist_ua_full = {},
_M.whitelist_ua_sub = {}
Filter NameValueFilters Request To
but not to
but not to
but not to
whitelist_ip_addresses{''}Filters requests coming from any of the listed IPs.
whitelist_ua_full{'Mozilla/5.0 (compatible; pingbot/2.0;'}Filters all requests matching this exact UA.
whitelist_ua_sub{'GoogleCloudMonitoring'}Filters requests containing the provided string in their UA.

Filter Sensitive Headers

A list of sensitive headers configured to prevent specific headers from being sent to PerimeterX servers (headers in lowercase). Filtering cookie headers for privacy is set by default, and can be overridden on the pxConfig variable.

Default: cookie, cookies


_M.sensitive_headers = {'cookie', 'cookies', 'secret-header'}

Remote Configurations

Allows the module to periodically pull configurations from PerimeterX services. When enabled, the configuration can be changed dynamically via PerimeterX Portal

Default: false

File: pxconfig.lua


   _M.dynamic_configurations = false
   _M.load_interval = 5

Enabled Routes

Allows you to define a set of routes on which the plugin will be active. An empty list sets all routes in the application as active.

Default: Empty list (all routes are active)


 _M.enabled_routes = {'/blockhere'}

Sensitive Routes

A list of route prefixes and suffixes. The PerimeterX module always matches the request URI with the prefixes list and suffixes list. When there is a match, the PerimeterX module creates a server-to-server call, even when the cookie is valid and the risk score is low.

Default: Empty list


_M.sensitive_routes_prefix = {'/login', '/user/profile'}
_M.sensitive_routes_suffix = {'/download'}

API Timeout Milliseconds

API Timeout in milliseconds (float) to wait for the PerimeterX server API response. The API is called when a risk cookie does not exist, is expired, or is invalid. If the timeout is reached before a response is received, the module will pass the client request.

Default: 1000


 _M.s2s_timeout = 250

Customize Default Block Page

The PerimeterX default block page can be modified by injecting custom CSS, JavaScript and a custom logo to the block page.

Default: nil


_M.custom_logo = ""
_M.css_ref = ""
_M.js_ref = ""

Redirect to a Custom Block Page URL

Customizes the block page to meet branding and message requirements by specifying the URL of the block page HTML file. The page can also implement CAPTCHA.

Default: nil


_M.custom_block_url = '/block.html'

Note: This URI is allowed automatically under _M.Whitelist['uri_full'] to avoid infinite redirects.

Redirect on Custom URL

The _M.redirect_on_custom_url boolean flag to redirect users to a block page.

Default: false


  _M.redirect_on_custom_url = false

By default, when a user exceeds the blocking threshold and blocking is enabled, the user is redirected to the block page defined by the _M.custom_block_url variable. The defined block page displays a 307 (Temporary Redirect) HTTP Response Code.

When the flag is set to false, a 403 (Unauthorized) HTTP Response Code is displayed on the blocked page URL.

Setting the flag to true (enabling redirects) results in the following URL upon blocking:

Setting the flag to false does not require the block page to include any of the examples below, as they are injected into the blocking page via the PerimeterX NGINX Module.

NOTE: The URL variable should be built with the URL-encoded query parameters (of the original request) with both the original path and variables base64-encoded (to avoid collisions with block page query params).

Custom Block Pages Requirements

As of version 4.0, Captcha logic is handled through the JavaScript snippet and not through the enforcer.

Users who have Custom Block Pages must include the new script tag and a new div in the .html block page. For implementation instructions refer to the appropriate links below:

Redirect to Referer

Indicates whether the user is redirected from the challenge page to the referrer page after successfully solving the challenge.

Default: false


_M.redirect_to_referer = true

Additional Activity Handler

An additional activity handler is added by setting _M.additional_activity_handler with a user defined function in the 'pxconfig.lua' file.

Default: Activity is sent to PerimeterX as controlled by 'pxconfig.lua'.


_M.additional_activity_handler = function(event_type, ctx, details)
 local cjson = require "cjson"
 if (event_type == 'block') then
   logger.warning("PerimeterX " + event_type + " blocked with score: " + ctx.blocking_score + "details " + cjson.encode(details))
 else"PerimeterX " + event_type + " details " +  cjson.encode(details))

Enrich Custom Parameters

With the enrich_custom_params 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). You must return the px_cusom_params object at the end of the function.

Default: nil


_M.enrich_custom_parameters = function(px_custom_params)
  px_custom_params["custom_param1"] = "user_id"
  return px_custom_params

Changing the Minimum Score for Blocking

This value should not be changed from the default of 100 unless advised by PerimeterX.

Default blocking value: 100


  _M.blocking_score = 100

First-Party Prefix

Allows you to define a custom prefix for First-Party routes.

Default: nil


_M.first_party_prefix = 'resources'

To define the First-Party Prefix:

  1. In your pxconfig.lua file, set the _M.first_party_prefix property to the desired prefix value. For example:
_M.first_party_prefix = 'resources'
  1. Open the PerimeterX Console.

  2. Go to Admin -> Applications.

  3. Open the Snippet section. Activate First-Party (if not in First-Party already), and click Edit next to the Copy Snippet button.

  4. In the pop-up that opens there are two routes beginning with /<appId without PX>. Copy both routes to a side document to use in the next steps.

  5. Click Advanced Configuration.

  6. Under Sensor, copy the first route from step 5 and add the prefix you added in step 1 to the beginning of of the route.
    For example: /resources/<appId without PX>/init.js

  7. Under Server copy the second route from step 5 and the prefix you added in step 1 to the beginning of the route.
    For example: /resources/<appId without PX>/xhr

  8. Click Save Changes.

  9. Click Copy Snippet and update the JS Sensor snippet of your site with the updated one.

Advanced Blocking Response Support

Enables/disables support for Advanced Blocking Response.

Default: true (enabled)


_M.advanced_blocking_response = false

Proxy Support

Sets a proxy server for all the enforcer's outgoing calls.

Requires lua-resty-http version 0.12 and up.

Default: nil


_M.proxy_url = 'http://localhost:8008'

Proxy Authorization

If proxy support is enabled, allows you to set a proxy authorization header.

Requires lua-resty-http version 0.12 and up.

Default: nil


_M.proxy_authorization = 'top-secret-header-value'

Custom Cookie Header

When set, this property specifies a header name that will be used to extract the PerimeterX cookie from, instead of the Cookie header.

NOTE: Using a custom cookie header requires client-side integration to be done as well. Please refer to the relevant docs for details.

Default: nil


_M.custom_cookie_header = 'x-px-cookies'

Bypass Monitor Mode Header

When set, allows you to test the blocking flow of an enforcer, while in monitoring mode. When the enforcer receives a request that has this configured header name with the value of 1, it will behave as though it is in active blocking mode. For instance, requests with this header and bad user-agents (e.g., PhantomJS/1.0) will return with a block page.

Default: nil

_M.bypass_monitor_header = 'x-px-block'

Did this page help you?