PerimeterX NGINX Lua Plugin
Latest stable version: v6.7.2
Introduction
Upgrading
Installation
- Supported Operating Systems
- Supported NGINX Versions
- Installing with Ubuntu
- Installing with CentOS7
- Installing the PerimeterX NGINX Plugin for NGINX+
- Required NGINX Configuration
Configuration
- Required Configuration
- First-Party Configuration
- Optional Configuration
- Monitor / Block Mode
- Debug Mode
- Whitelisting
- Filter Sensitive Headers
- Remote Configurations
- Enabled Routes
- Monitored Routes
- Sensitive Routes
- API Timeout
- Customize Default Block Page
- Redirect to a Custom Block Page URL
- Redirect on Custom URL
- Redirect to Subdomain
- Additional Activity Handler
- Enrich Custom Parameters
- Blocking Score
- First-Party Prefix
- Advanced Blocking Response
- Proxy Support
- Proxy Authorization Header
- Custom Cookie Header
- Bypass Monitor Mode Header
- Secured PXHD Cookie
Enrichment
Advanced Blocking Response
Login Credentials Extraction
Appendix
- HTTP v2 Support
- NGINX Plus
- NGINX Dynamic Modules
- Multiple App Support
- Setting Up A First Party Prefix
- URI Delimiters
- Contributing
Introduction
The PerimeterX Nginx Lua Plugin is a Lua module that enforces whether or not a request is allowed to continue being processed. When the PerimeterX Enforcer determines that a request is coming from a non-human source the request is blocked.
Upgrading
See the full changelog for all versions.
From any Version Lower than 4.x
As of version 4.x the config builder was added. The config builder adds default values to properties that are not impicitly specified. This change requires the user to import the configuration in the init_worker_by_lua_block
and access_by_lua_block
blocks inside nginx.conf
:
- Modify
init_worker_by_lua_block
init_worker_by_lua_block {
local pxconfig = require("px.pxconfig")
require ("px.utils.pxtimer").application(pxconfig)
}
- Modify
access_by_lua_block
access_by_lua_block {
local pxconfig = require("px.pxconfig")
require("px.pxnginx").application(pxconfig)
}
From any Version above 4.x
To upgrade to the latest Enforcer version, re-install the Enforcer according to your OS.
Installation
Supported Operating Systems
- Debian
- Ubuntu 14.04 or Ubuntu 16.04+
- RHEL
- CentOS 7
- Amazon Linux (AMI)
Supported NGINX Versions:
Recomended that you use the newest version of NGINX from the Official NGINX repo.
NOTE: Using the default NGINX provide by default in various Operating Systems does not support the LUA NGINX Module.
Installing with Ubuntu
Ubuntu 14.04
1. Upgrade and update your existing dependencies for Ubuntu 16.04 or higher
sudo apt-get update
sudo apt-get upgrade
2. Add the offical NGINX repository to get the latest version of NGINX
sudo add-apt-repository ppa:nginx/stable
If an add-apt-repository: command not found
error is returned, run:
sudo apt-get -y install software-properties-common
3. Install the dependencies for Ubuntu 14.04:
sudo apt-get -y install build-essential
sudo apt-get -y install ca-certificates
sudo apt-get -y install make
sudo apt-get -y install wget
sudo apt-get -y install nginx
sudo apt-get -y install m4
sudo apt-get -y install libnginx-mod-http-lua
sudo apt-get -y install lua-cjson
4. Download and install LuaRocks from source
wget http://luarocks.github.io/luarocks/releases/luarocks-2.4.4.tar.gz
tar -xzf luarocks-2.4.4.tar.gz
cd luarocks-2.4.4
./configure
sudo make clean && sudo make build && sudo make install
cd ~
5. Download and install Netttle 3.3 from source
wget https://ftp.gnu.org/gnu/nettle/nettle-3.3.tar.gz
tar -xzf nettle-3.3.tar.gz
cd nettle-3.3
./configure
sudo make clean && sudo make install
cd ~
6. Install the remaining dependencies
sudo apt-get -y install lua-sec
sudo luarocks install lua-resty-nettle
luarocks install lua-resty-upload
7. Install the PerimeterX NGINX Plugin
sudo no_proxy=1 luarocks install perimeterx-nginx-plugin
Ubuntu 16.04 and Higher
1. Update your existing dependencies for Ubuntu 16.04 or higher
sudo apt-get update
2. Add the offical NGINX repository to get the latest version of NGINX
sudo add-apt-repository ppa:nginx/stable
If an add-apt-repository: command not found
error is returned, run:
sudo apt-get -y install software-properties-common
3. Update and upgrade your existing dependencies for Ubuntu 16.04 or higher
sudo apt-get update
sudo apt-get upgrade
4. Install the dependencies for Ubuntu 16.04 or higher
sudo apt-get -y install build-essential
sudo apt-get -y install ca-certificates
sudo apt-get -y install nginx
sudo apt-get -y install libnginx-mod-http-lua
sudo apt-get -y install lua-cjson
sudo apt-get -y install libnettle6
sudo apt-get -y install nettle-dev
sudo apt-get -y install luarocks
sudo apt-get -y install luajit
sudo apt-get -y install libluajit-5.1-dev
5. Install the PerimeterX NGINX Plugin
luarocks install perimeterx-nginx-plugin
Installing with CentOS 7
NGINX does not provide an NGINX http lua module for CentOS/RHEL via an RPM. This means that you need to compile the Module from source.
1. Update and Install dependecies
yum -y update
yum install -y epel-release
yum update -y
yum groupinstall -y "Development Tools"
yum install -y wget rpmdevtools git luajit luajit-devel openssl-devel zlib-devel pcre-devel gcc gcc-c++ make perl-ExtUtils-Embed lua-json lua-devel ca-certificates
yum remove -y nettle luarocks
2. Make a tmp directory to work in
sudo mkdir /tmp/nginx
cd /tmp/nginx
3. Download all required source files
wget http://luarocks.github.io/luarocks/releases/luarocks-3.5.0.tar.gz
wget http://nginx.org/download/nginx-1.18.0.tar.gz
wget -O luajit-2.0.tar.gz https://github.com/LuaJIT/LuaJIT/archive/refs/tags/v2.0.5.tar.gz
wget -O nginx_devel_kit.tar.gz https://github.com/simpl/ngx_devel_kit/archive/v0.3.1.tar.gz
wget -O nginx_lua_module.tar.gz https://github.com/openresty/lua-nginx-module/archive/v0.10.15.tar.gz
wget https://ftp.gnu.org/gnu/nettle/nettle-3.6.tar.gz
4. Unpackage all source files
tar -xzf luarocks-3.5.0.tar.gz
tar -xzf nettle-3.6.tar.gz
tar -xvf luajit-2.0.tar.gz
tar -xvf nginx-1.18.0.tar.gz
tar -xvf nginx_devel_kit.tar.gz
tar -xvf nginx_lua_module.tar.gz
5. Install luarocks from source
cd /tmp/nginx/luarocks-3.5.0
./configure
make
make install
6. Install Nettle from source
cd /tmp/nginx/nettle-3.6
./configure --prefix=/usr --disable-static
make
make check
make install
7. Install LuaJIT
cd /tmp/nginx/LuaJIT-2.0.5
make install
8. Build and Install NGINX with required Modules
cd /tmp/nginx/nginx-1.18.0
LUAJIT_LIB=/usr/local/lib LUAJIT_INC=/usr/local/include/luajit-2.0 \
./configure \
--user=nginx \
--group=nginx \
--prefix=/etc/nginx \
--sbin-path=/usr/sbin/nginx \
--conf-path=/etc/nginx/nginx.conf \
--pid-path=/var/run/nginx.pid \
--lock-path=/var/run/nginx.lock \
--error-log-path=/var/log/nginx/error.log \
--http-log-path=/var/log/nginx/access.log \
--with-http_gzip_static_module \
--with-http_stub_status_module \
--with-debug \
--with-http_ssl_module \
--with-pcre \
--with-http_perl_module \
--with-file-aio \
--with-http_realip_module \
--add-module=/tmp/nginx/ngx_devel_kit-0.3.1 \
--add-module=/tmp/nginx/lua-nginx-module-0.10.15
make install
9. Install PerimeterX Nginx Plugin & Dependencies
luarocks install luasec
luarocks install lustache
luarocks install lua-resty-core
luarocks install lua-resty-nettle
luarocks install lua-resty-upload
luarocks install luasocket
luarocks install lua-resty-http
luarocks install lua-cjson
luarocks install perimeterx-nginx-plugin
10. Optionalally, if you are testing in a new environment you may need to configure the following:
-
Add the user "nginx"
sudo useradd --system --home /var/cache/nginx --shell /sbin/nologin --comment "nginx user" --user-group nginx
-
Create a systemd service for NGINX
sudo vi /usr/lib/systemd/system/nginx.service
-
Paste the following in the file you just created:
[Unit] Description=nginx - high performance web server Documentation=https://nginx.org/en/docs/ After=network-online.target remote-fs.target nss-lookup.target Wants=network-online.target [Service] Type=forking PIDFile=/var/run/nginx.pid ExecStartPre=/usr/sbin/nginx -t -c /etc/nginx/nginx.conf ExecStart=/usr/sbin/nginx -c /etc/nginx/nginx.conf ExecReload=/bin/kill -s HUP $MAINPID ExecStop=/bin/kill -s TERM $MAINPID [Install] WantedBy=multi-user.target
-
Enable and Start the NGINX Service
sudo systemctl is-enabled nginx.service sudo systemctl start nginx.service sudo systemctl enable nginx.service
Installing the PerimeterX NGINX Plugin for NGINX+
If you are already using NGINX+, the following steps cover installing the NGINX+ Lua Module and the PermimeterX NGINX Plugin.
Configuration
Required NGINX Configuration
The following NGINX Configurations are required to support the PerimeterX NGINX Lua Plugin:
-
Resolver
The Resolver directive must be configured in the HTTP section of your NGINX configuration.
- Set the resolver,
resolver A.B.C.D;
, to an external DNS resolver, such as Google (resolver 8.8.8.8;
),
or
- Set the resolver,
resolver A.B.C.D;
, to the internal IP address of your DNS resolver (resolver 10.1.1.1;
).
This is required for NGINX to resolve the PerimeterX API.
- Set the resolver,
-
Lua Package Path
Ensure your Lua package path location in the HTTP section of your configuration reflects the location of the installed PerimeterX modules.
lua_package_path "/usr/local/lib/lua/?.lua;;";
-
Lua CA Certificates
For TLS support to PerimeterX servers, configure Lua to point to the trusted certificate location.
lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; lua_ssl_verify_depth 3;
NOTE: The certificate location may differ between Linux distributions. In CentOS/RHEL systems, the CA bundle location may be located at
/etc/pki/tls/certs/ca-bundle.crt
. -
Lua Timer Initialization
Add the init with a Lua script. The init is used by PerimeterX to hold and send metrics at regular intervals.
init_worker_by_lua_block { local pxconfig = require("px.pxconfig") require ("px.utils.pxtimer").application(pxconfig) }
-
Apply PerimeterX Enforcement
Add the following line to your
location
block:#----- PerimeterX protect location -----# access_by_lua_block { local pxconfig = require("px.pxconfig") require ("px.pxnginx").application(pxconfig) } #----- PerimeterX Module End -----#
-
nginx.conf Example
The following nginx.conf example contains the required directives with enforcement applied to the
location
block.worker_processes 1; error_log /var/log/nginx/error.log; events { worker_connections 1024; } http { lua_package_path "/usr/local/lib/lua/?.lua;;"; # -- initializing the perimeterx module -- # init_worker_by_lua_block { local pxconfig = require("px.pxconfig") require ("px.utils.pxtimer").application(pxconfig) } lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; lua_ssl_verify_depth 3; resolver 8.8.8.8; server { listen 80; location / { #----- PerimeterX protect location -----# access_by_lua_block { local pxconfig = require("px.pxconfig") require("px.pxnginx").application(pxconfig) } #----- PerimeterX Module End -----# root /nginx/www; index index.html; } } }
NOTE: The NGINX Configuration Requirements must be completed before proceeding to the next stage of installation.
PerimeterX Plugin Configuration
Required Configuration:
The following configurations are set in:
/usr/local/lib/lua/px/pxconfig.lua
-- ## Required Parameters ##
_M.px_appId = 'PX_APP_ID'
_M.auth_token = 'PX_AUTH_TOKEN'
_M.cookie_secret = 'COOKIE_ENCRYPTION_KEY'
-
The PerimeterX Application ID / AppId and PerimeterX Token / Auth Token can be found in the Portal, in Applications.
-
PerimeterX Cookie Encryption Key can be found in the portal, in Policies.
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
First-Party Configuration
First-Party Mode
First-Party Mode enables the module to send/receive data to/from the sensor, acting as a reverse-proxy for client requests and sensor activities.
First-Party Mode may require additional changes on the JS Sensor Snippet. For more information, refer to the PerimeterX Portal.
...
_M.first_party_enabled = true
The following routes must be enabled for First-Party Mode for the PerimeterX Lua module: - /<PX_APP_ID without PX prefix>/xhr/*
- /<PX_APP_ID without PX prefix>/init.js
-
If the PerimeterX Lua module is enabled on
location /
, the routes are already open and no action is necessary. -
If the PerimeterX Lua module is not enabled on
location /
, add to your server block for NGINX:
server {
listen 80;
location /<PX_APP_ID without PX prefix> {
#----- PerimeterX protect location -----#
access_by_lua_block {
local pxconfig = require("px.pxconfig")
require("px.pxnginx").application(pxconfig)
}
#----- PerimeterX Module End -----#
root /nginx/www;
index index.html;
}
}
NOTE: If your NGINX version supports HTTP v2, refer to the HTTP v2 section of the Appendix.
NOTE: The PerimeterX NGINX Lua Plugin Configuration Requirements must be completed before proceeding to the next stage of installation.
First-Party JS Snippet
Ensure the PerimeterX NGINX Lua Plugin is configured before deploying the PerimeterX First-Party JS Snippet across your site. (Detailed instructions for deploying the PerimeterX First-Party JS Snippet can be found here.)
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.
2. 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
Monitor / Block Mode Configuration
By default, the PerimeterX plugin is set to Monitor Only 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.
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: 172.17.0.1, 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: 172.17.0.1, 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: 172.17.0.1, 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: 172.17.0.1, 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: 172.17.0.1, 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
Whitelisting
Whitelisting (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 Name | Value | Filters Request To |
---|---|---|
whitelist_uri_full | {'/api_server_full'} |
/api_server_full?data=1 but not to /api_server?data=1 |
whitelist_uri_prefixes | {'/api_server'} |
/api_server_full?data=1 but not to /full_api_server?data=1 |
whitelist_uri_suffixes | {'.css'} |
/style.css but not to /style.js |
whitelist_ip_addresses | {'192.168.99.1'} |
Filters requests coming from any of the listed IPs. |
whitelist_ua_full | {'Mozilla/5.0 (compatible; pingbot/2.0; http://www.pingdom.com/)'} |
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 lower case). Filtering cookie headers for privacy is set by default, and can be overridden on the pxConfig
variable.
Default: cookie, cookies
Example:
_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
Example:
...
_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)
Example:
_M.enabled_routes = {'/blockhere'}
Monitored Routes
allows you to define a set of route prefixes that will be handled as if in monitor mode, even if block_enabled
is set to true
.
Default: Empty list
Example:
_M.monitored_routes = {'/profile'}
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
Example:
_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.
Controls the timeouts for PerimeterX requests. The API is called when a Risk Cookie does not exist, is expired, or is invalid.
Default: 1000
Example:
_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
Example:
_M.custom_logo = "http://www.example.com/logo.png"
_M.css_ref = "http://www.example.com/style.css"
_M.js_ref = "http://www.example.com/script.js"
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
Example:
_M.custom_block_url = '/block.html'
Note: This URI is whitelisted 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
Example:
_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:
http://www.example.com/block.html?url=L3NvbWVwYWdlP2ZvbyUzRGJhcg==&uuid=e8e6efb0-8a59-11e6-815c-3bdad80c1d39&vid=08320300-6516-11e6-9308-b9c827550d47
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 Enforcer.
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 being 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:
- [reCaptcha](examples/Custom Block Page + reCAPTCHA + Redirect/README.md)
- [Custom Block Page](examples/Custom Block Page/README.md)
Redirect to Referer
Indicates whether the user is redirected from the challenge page to the referrer page after successfully solving the challenge.
Default: false
Example:
_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'.
Example:
_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
logger.info("PerimeterX " + event_type + " details " + cjson.encode(details))
end
end
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 seting the payload on every request to PerimetrX 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
Example:
_M.enrich_custom_parameters = function(px_custom_params)
px_custom_params["custom_param1"] = "user_id"
return px_custom_params
end
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
Example:
_M.blocking_score = 100
First-Party Prefix
Allows you to deinfe a custom prefix for First-Party routes. Refer to Setting Up A First Party Prefix for complete setup instructions.
Default: nil
Example:
_M.first_party_prefix = 'resources'
Advanced Blocking Response Support
Enables/disables support for Advanced Blocking Response.
Default: true (enabled)
Example:
_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
Example:
_M.proxy_url = 'http://localhost:8008'
Proxy Authorization
If proxy support is enabled, allow you to set a proxy authorization header.
Requires
lua-resty-http
version 0.12 and up.
Default: nil
Example:
_M.proxy_authorization = 'top-secret-header-value'
Custom Cookie Header
When set, this property specifies a header name which 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
Example:
_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.
The property accept an header name which, if provided in a request with the value of 1
, in addition to a bad user agent (such as PhantomJS/1.0
) will block the request and show a challenge page.
Default: nil
_M.bypass_monitor_header = 'x-px-block'
Secured PXHD Cookie
A boolean flag to enable/disable the Secure
flag when baking a PXHD cookie.
Default: false
_M.pxhd_secure_enabled = true
Enrichment
Data Enrichment
The PerimeterX NGINX plugin stores the data enrichment payload on the request context. The data enrichment payload can also be processed with additional_activity_handler
.
Only requests that are not being block will reach the backend server, so specific logic must be applied to the processing function.
The following example includes the pre-condition checks required to process the data enrichment payload and enrich the request headers.
...
_M.additional_activity_handler = function(event_type, ctx, details)
-- verify that the request is passed to the backend
if event_type == 'page_requested' then
-- pxde - contains a parsed json of the data enrichment object
-- pxde_verified - makes sure that this payload is trusted and signed by PerimeterX
local pxde = ngx.ctx.pxde
local pxde_verified = ngx.ctx.pxde_verified
if pxde and pxde_verified then
-- apply the data enrichment logic here
-- the example below will set the f_type on the request header
local f_type = ngx.ctx.pxde.f_type
ngx.req.set_header("x-px-de-f-type", f_type)
end
end
end
...
For more information and the available fields in the JSON, refer to the PerimeterX Portal documentation.
Log Enrichment
Access logs can be enriched with the PerimeterX bot information by creating an NGINX variable with the proper name. To configure this variable use the NGINX map directive in the HTTP section of your NGINX configuration file. This should be added before additional configuration files are added.
The following variables are enabled:
- Request UUID:
pxuuid
- Request VID:
pxvid
- Risk Round Trimp:
pxrtt
- Risk Score:
pxscore
- Pass Reason:
pxpass
- Block Reason:
pxblock
- Cookie Validity:
pxcookiets
- Risk Call Reason:
pxcall
....
http {
map score $pxscore { default 'none'; }
map pass $pxpass { default 'none'; }
map uuid $pxuuid { default 'none'; }
map rtt $pxrtt { default '0'; }
map block $pxblock { default 'none'; }
map vid $pxvid { default 'none'; }
map cookiets $pxcookiets { default 'none'; }
map px_call $pxcall { default 'none'; }
log_format enriched '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'| perimeterx uuid[$pxuuid] vid[$pxvid] '
'score[$pxscore] rtt[$pxrtt] block[$pxblock] '
'pass[$pxpass] cookie_ts[$pxcookiets] risk_call[$pxcall]';
access_log /var/log/nginx/access_log enriched;
}
...
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 continaing 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 successfullt solved.
An example of using the _pxOnCaptchaSuccess
callback is as follows:
window._pxOnCaptchaSuccess = function (isValid) {
if (isValid) {
alert("yay");
} else {
alert("nay");
}
};
For details on how to create a custom Captcha page, refer to the documentation
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. The settings are adjusted by modifying the creds.json file.
pxconfig.lua
_M.px_enable_login_creds_extraction = true
_M.px_login_creds_settings_filename = ‘/path/to/creds.json’
creds.json
Example available in examples/creds.json
file. It includes an array of JSON objects containing the following properties:
{
"id": 0, // unique int
"method": "post", // supported methods: post
"sent_through": "body", // supported sent_throughs: header, url, body
"content_type": "json", // supported content_types: json, form-data, form-urlencoded
"encoding": "clear-text", // supported encodings: clear-text
"path": "/login", // login path
"pass_field": "password", // name of the password field in the request
"user_field": "username" // name of the username field in the request
}
Default Values
_M.px_enable_login_creds_extraction = false
_M.px_login_creds_settings_filename = nil
Appendix
HTTP v2 Support
The PerimeterX NGINX module supports HTTP v2 for both Third-Party and First-Party implementations. To verify that your NGINX is running with HTTP v2 support, run:
nginx -V
For NGINX modules that support HTTP v2, the flag --with-http_v2_module
will be listed. For example:
# nginx -V
nginx version: nginx/1.13.3
built by gcc 5.4.0 20160609 (Ubuntu 5.4.0-6ubuntu1~16.04.10)
built with OpenSSL 1.0.2g 1 Mar 2016
TLS SNI support enabled
configure arguments: --prefix=/nginx --with-ld-opt=-Wl,-rpath,/usr/local/lib --add-module=/ngx_devel_kit-0.3.0 --add-module=/lua-nginx-module-0.10.10 --with-http_ssl_module --with-http_stub_status_module --with-http_realip_module --with-ipv6 --with-http_v2_module
If you are running in Third-Party mode, you do not need to take any additional actions for the PerimeterX NGINX module to support HTTP v2.
If you are running in First-Party mode, add the following location to your nginx.conf
file:
location /<app id without PX prefix>/xhr/ {
proxy_buffering on;
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $server_name;
proxy_set_header X-PX-Enforcer-True-IP $remote_addr;
proxy_set_header X-PX-First-Party 1;
set $pxcookie "";
if ($cookie__pxvid != "") {
set $pxcookie pxvid=$cookie__pxvid;
}
if ($cookie_pxvid != "") {
set $pxcookie pxvid=$cookie_pxvid;
}
proxy_set_header cookie $pxcookie;
proxy_pass https://collector-<app_id>.perimeterx.net/;
}
Note: Make sure you replace the <app id without PX prefix> and <app_id> with your PerimeterX appId value.
NGINX Plus
The PerimeterX NGINX module is compatible with NGINX Plus. Users or administrators should install the NGINX Plus Lua dynamic module (LuaJIT).
NGINX Dynamic Modules
If you are using NGINX with dynamic module support you can load the Lua module with the following lines at the beginning of your NGINX configuration file.
load_module modules/ndk_http_module.so;
load_module modules/ngx_http_lua_module.so;
Multiple App Support
The PerimeterX Enforcer allows multiple configurations for different applications.
If your PerimeterX account contains several applications (as defined in the Portal), you can create different configurations for each application.
NOTE: The application initializes a timed Enforcer. The Enforcer must be initialized with one of the applications in your account. The the correct configuration file name must be passed to the
require ("px.utils.pxtimer").application("AppName"|empty)
block in the server initialization.
- Open the
nginx.conf
file, and locate therequire("px.pxnginx").application()
line inside your location block. - Pass the desired application name into the
application()
function.
For example:require("px.pxnginx").application("mySpecialApp")
- Locate the
pxconfig.lua
file, and create a copy of it.
The copy name should follow the pattern:
pxconfig-<AppName>.lua
(e.g.pxconfig-mySpecialApp.lua
)
The < AppName > placeholder must be replaced by the exact name provided to the application function in step 1. - Change the configuration in file created in step 3.
- Save the file in the location where pxnginx.lua file is located.
(Default location:
/usr/local/lib/lua/px/<yourFile>
) - For every location block of your app, replace the code mentioned in step 2 with the correct < AppName >.
Setting Up A First Party Prefix
Documentation for setting up First-Party Prefixes is found here.
URI Delimiters
PerimeterX processes URI paths with general- and sub-delimiters according to RFC 3986. General delimiters (e.g., ?
, #
) are used to separate parts of the URI. Sub-delimiters (e.g., $
, &
) are not used to split the URI as they are considered valid characters in the URI path.
Contributing
The following steps are welcome when contributing to our project.
-
Fork/Clone
Create a fork of the repository, and clone it locally. Create a branch on your fork, preferably using a descriptive branch name.
-
Test
Tests for this project are written using the
Test::Nginx
testing framework.Don't forget to test.
This project relies heavily on tests to ensure that each user has the same experience, and no new features break the code. Before you create any pull request, make sure your project has passed all tests. If any new features require it, write your own test.
To run the tests
- Build the docker container.
- Run the tests using the following command: make docker-test.
-
Pull Request
Once you have completed the process, create a pull request. Provide a complete and thorough description explaining the changes. Remember, the code has to be read by our maintainers, so keep it simple, smart and accurate.