开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

PerimeterX NGINX Lua Plugin

Latest stable version: v7.1.3

Introduction

Upgrading

• From any Version Lower than 4.x
• From any Version Above 4.x

Installation

• Supported Operating Systems
• Supported NGINX Versions
• Installing with Ubuntu
• Installing with CentOS7
• Installing the PerimeterX NGINX Plugin for NGINX+
• Required NGINX Configuration
  • Resolver
  • Lua Package Path
  • Lua CA Certificates
  • Lua Timer Initialization
  • PerimeterX enforcement
  • NGINX.conf Example

Configuration

• Required Configuration
• First-Party Configuration
  • First-Party Mode
  • PerimeterX First-Party JS Snippet
• Optional Configuration
  • Monitor / Block Mode
  • Debug Mode
  • Whitelisting
  • Filter Sensitive Headers
  • Remote Configurations
  • Enabled Routes
  • Monitored Routes
  • Sensitive Routes
  • Sensitive Routes Regex List
  • 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

• Data Enrichment
• Log Enrichment

Advanced Blocking Response

Login Credentials Extraction

• Login Credentials Extraction Configuration
• Enable Login Credentials Extraction
• Credentials JSON file
• Credentials Intelligence Version
• Additional s2s Activity Header
• Send Raw Username On Additional s2s Activity
• Compromised Credentials Header Name
• Login Successful Reporting Method
• Login Successful Header Name
• Login Successful Header Value
• Login Successful Status
• Login Successful Custom Function

HypeSale

• HypeSale host

Sensitive GraphQL Operations

• Sensitive GraphQL Operation Types
• Sensitive GraphQL Operation Names

Appendix

• HTTP v2 Support
• NGINX Plus
• NGINX Dynamic Modules
• Multiple App Support
• Setting Up A First Party Prefix
• URI Delimiters

Test Environment

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 implicitly 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:

1. Modify init_worker_by_lua_block

    init_worker_by_lua_block {
        local pxconfig = require("px.pxconfig")
        require ("px.utils.pxtimer").application(pxconfig)
    }

2. Modify access_by_lua_block

    access_by_lua_block {
        local config = require('px.pxconfig')
        require("px.pxnginx").application(config)
    }

3. Modify header_filter_by_lua_block

    header_filter_by_lua_block {
        require("px.pxnginx").finalize()
    }

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:

Recommended that you use the newest version of NGINX from the Official NGINX repo.

• NGINX 1.7 or later
  • Lua NGINX Module V0.9.11 or later
• NGINX Plus
  • Lua NGINX Plus Module
• OpenResty

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 official 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 Nettle 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

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 official 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 dependencies

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 luasocket
luarocks install lua-resty-http
luarocks install lua-cjson
luarocks install perimeterx-nginx-plugin

10. Optionally, 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.

• RHEL 7.4 and higher
• Amazon Linux, CentOS and RHEL 7.3 and lower

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.

• 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(pxconfi