Skip to content

Commit 040230d

Browse files
author
Johnny Tordgeman
authored
Merge pull request #156 from PerimeterX/dev
Version 5.2.0
2 parents 26dffd2 + f16a5a3 commit 040230d

File tree

8 files changed

+219
-64
lines changed

8 files changed

+219
-64
lines changed

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](http://keepachangelog.com/)
66
and this project adheres to [Semantic Versioning](http://semver.org/).
77

8+
## [5.2.0] - 2018-10-14
9+
### Added
10+
- Enrich Custom Parameters support
11+
- Refreshed documentation for NGINX plus and RHEL 7.5
12+
813
## [5.1.0] - 2018-09-26
914
### Added
1015
- Support for Advanced Blocking Response

‎NGINXPLUS.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
###### 1. Install the <a href="https://docs.nginx.com/nginx/admin-guide/dynamic-modules/lua/" onclick="window.open(this.href); return false;">Lua modules provided by NGINX</a>
2+
3+
* For Amazon Linux, CentOS, and RHEL:
4+
```sh
5+
yum install nginx-plus-module-lua
6+
```
7+
8+
* For Ubuntu:
9+
```sh
10+
apt-get install nginx-plus-module-lua
11+
```
12+
13+
###### 2. Remove Pre-installed Nettle
14+
```sh
15+
sudo yum -y remove nettle
16+
```
17+
18+
###### 3. Install Nettle from Source
19+
Download and compile nettle using the version appropriate for your environment:
20+
21+
For Amazon Linux, CentOS, and RHEL:
22+
```sh
23+
yum -y install m4 # prerequisite for nettle
24+
cd /tmp/
25+
wget https://ftp.gnu.org/gnu/nettle/nettle-3.3.tar.gz
26+
tar -xzf nettle-3.3.tar.gz
27+
cd nettle-3.3
28+
./configure
29+
make install
30+
```
31+
32+
###### 4. Install Luarocks and Dependencies
33+
```sh
34+
sudo yum install luarocks
35+
sudo luarocks install lua-cjson
36+
sudo luarocks install lustache
37+
sudo luarocks install lua-resty-nettle
38+
sudo luarocks install luasocket
39+
sudo luarocks install lua-resty-http
40+
```
41+
42+
###### 5. Install PerimeterX NGINX Plugin
43+
```sh
44+
sudo luarocks install perimeterx-nginx-plugin
45+
```
46+
47+
###### 6. Modify Selinux (Consult with your internal System Administrator)
48+
On CentOS 7 and other Linux operating systems you may need to modify or disable Selinux. If you get the following error:
49+
50+
`nginx: lua atpanic: Lua VM crashed, reason: runtime code generation failed, restricted kernel?`
51+
52+
You will need to make one of the following changes:
53+
* To disable SELinux: `RUN setenforcer 0`
54+
* To enable execmem for httpd_t: `RUN setsebool httpd_execmem 1 -P`

‎NGINXPLUS_RHEL7.4.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
## <a name="installation_nginxplus_px_rhel"></a>Installing PerimeterX on NGINX+ With RHEL 7.4 And Above
2+
3+
The PerimeterX NGINX plugin can be installed on **NGINX+ up to version R15**. <br/>
4+
There is currently a known bug in R16 which crashes NGINX when calling `init_worker_by_lua_block` (required by the PerimeterX plugin). Until this bug is fixed, PerimeterX will not support installations using R16.
5+
6+
### Installation
7+
8+
1. Install the NGINX+ lua module according to the version of NGINX+ installed. (The example shows R15):
9+
10+
```sh
11+
sudo yum install -y nginx-plus-module-lua-r15
12+
```
13+
14+
2. Make sure Nettle is removed:
15+
16+
```sh
17+
sudo yum -y remove nettle
18+
```
19+
20+
3. Install the development tools:
21+
22+
```sh
23+
sudo yum groupinstall -y "Development Tools"
24+
```
25+
26+
4. Compile and install Nettle from source:
27+
28+
```sh
29+
mkdir /tmp
30+
cd /tmp/
31+
wget https://ftp.gnu.org/gnu/nettle/nettle-3.3.tar.gz
32+
tar -xzf nettle-3.3.tar.gz
33+
cd nettle-3.3
34+
./configure
35+
make
36+
sudo make install
37+
```
38+
39+
5. Install Luarocks and the PerimeterX Lua plugin dependencies:
40+
41+
```sh
42+
sudo yum install -y luarocks lua-devel
43+
sudo luarocks install lua-cjson
44+
sudo luarocks install lustache
45+
sudo luarocks install lua-resty-nettle
46+
sudo luarocks install luasocket
47+
sudo luarocks install lua-resty-http
48+
```
49+
50+
6. Install the PerimeterX Module:
51+
52+
```sh
53+
sudo luarocks install perimeterx-nginx-plugin
54+
```
55+
56+
### Configuration
57+
58+
1. Add the modules loading declaration at the top of the `nginx.conf` file:
59+
60+
```lua
61+
load_module modules/ndk_http_module.so;
62+
load_module modules/ngx_http_lua_module.so;
63+
```
64+
65+
2. Add the `lua_package_path` and `lua_package_cpath` declarations inside the `http` scope:
66+
67+
```lua
68+
lua_package_path "/usr/local/lib/lua/?.lua;;";
69+
lua_package_cpath "/usr/lib64/lua/5.1/?.so;;";
70+
```
71+
72+
3. Add the Resolver directive:
73+
74+
The Resolver directive must be configured in the HTTP section of your NGINX configuration. <br/>
75+
76+
* Set the Resolver, `resolver A.B.C.D;`, to an external DNS resolver, such as Google (`resolver 8.8.8.8;`),
77+
78+
_or_
79+
80+
* Set the resolver, `resolver A.B.C.D;`, to the internal IP address of your DNS resolver (`resolver 10.1.1.1;`).
81+
82+
This is required for NGINX to resolve the PerimeterX API.
83+
84+
4. Add the Lua CA Certificates:
85+
86+
For TLS to support PerimeterX servers, configure Lua to point to the trusted certificate location.
87+
88+
```lua
89+
lua_ssl_trusted_certificate "/etc/pki/tls/certs/ca-bundle.crt";
90+
lua_ssl_verify_depth 3;
91+
```
92+
93+
5. Add the Lua Timer Initialization:
94+
95+
Add the init with a Lua script. The init is used by PerimeterX to hold and send metrics at regular intervals.
96+
This section also defines the runtime path to the 'nettle' library.
97+
98+
```lua
99+
init_worker_by_lua_block {
100+
_NETTLE_LIB_PATH = "/usr/local/lib64"
101+
local pxconfig = require("px.pxconfig")
102+
require ("px.utils.pxtimer").application(pxconfig)
103+
}
104+
```
105+
106+
6. Apply PerimeterX Enforcement:
107+
108+
Add the following line to your `location` block
109+
110+
```
111+
#----- PerimeterX protect location -----#
112+
access_by_lua_block {
113+
local pxconfig = require("px.pxconfig")
114+
require ("px.pxnginx").application(pxconfig)
115+
}
116+
#----- PerimeterX Module End -----#
117+
```
118+
119+
7. Continue with the [PerimeterX Plugin Configuration](https://github.com/PerimeterX/perimeterx-nginx-plugin#perimeterx-plugin-configuration) section.

‎README.md‎

Lines changed: 21 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
# [PerimeterX](http://www.perimeterx.com) NGINX Lua Plugin
66

7-
> Latest stable version: [v5.1.0](https://luarocks.org/modules/bendpx/perimeterx-nginx-plugin/5.1-0)
7+
> Latest stable version: [v5.2.0](https://luarocks.org/modules/bendpx/perimeterx-nginx-plugin/5.2-0)
88
99

1010
## [Introduction](#introduction)
@@ -16,8 +16,8 @@
1616
* [Supported Operating Systems](#supported_os)
1717
* [Supported NGINX Versions](#supported_versions)
1818
* [Installing with Ubuntu](#ubuntu)
19-
* [Installing with CentOS7](centos7)
20-
* [Installing the PerimeterX NGINX Plugin for NGINX+](#nstallation_nginxplus_px)
19+
* [Installing with CentOS7](#centos7)
20+
* [Installing the PerimeterX NGINX Plugin for NGINX+](#installation_nginxplus_px)
2121
* [Required NGINX Configuration](#nginx_configuration)
2222
* [Resolver](#nginx_resolver)
2323
* [Lua Package Path](#nginx_lua_package_path)
@@ -34,7 +34,6 @@
3434
* [Optional Configuration](#advanced_configuration)
3535
* [Monitor / Block Mode](#monitoring_mode)
3636
* [Debug Mode](#debug-mode)
37-
* [Extracting Real IP Address](#real-ip)
3837
* [Whitelisting](#whitelisting)
3938
* [Filter Sensitive Headers](#sensitive-headers)
4039
* [Remote Configurations](#remote-configurations)
@@ -45,6 +44,7 @@
4544
* [Redirect to a Custom Block Page URL](#redirect_to_custom_blockpage)
4645
* [Redirect on Custom URL](#redirect_on_custom_url)
4746
* [Additional Activity Handler](#add-activity-handler)
47+
* [Enrich Custom Parameters](#custom-parameters)
4848
* [Blocking Score](#blocking-score)
4949

5050
## [Enrichment](#enrichment)
@@ -339,65 +339,11 @@ sudo luarocks install perimeterx-nginx-plugin
339339
```
340340

341341
### <a name="installation_nginxplus_px"></a>Installing the PerimeterX NGINX Plugin for NGINX+
342-
If you are already using NGINX+ the following steps cover how to install the NGINX+ Lua Module & the PermimeterX NGINX Plugin.
343342

344-
###### 1. Install the <a href="https://docs.nginx.com/nginx/admin-guide/dynamic-modules/lua/" onclick="window.open(this.href); return false;">Lua modules provided by NGINX</a>
343+
If you are already using NGINX+, the following steps cover installing the NGINX+ Lua Module and the PermimeterX NGINX Plugin.
345344

346-
* For Amazon Linux, CentOS, and RHEL:
347-
```sh
348-
yum install nginx-plus-module-lua
349-
```
350-
351-
* For Ubuntu:
352-
```sh
353-
apt-get install nginx-plus-module-lua
354-
```
355-
356-
###### 2. Remove Pre-installed Nettle
357-
```sh
358-
sudo yum -y remove nettle
359-
```
360-
361-
###### 3. Install Nettle from Source
362-
Download and compile nettle using the version appropriate for your environment:
363-
364-
For Amazon Linux, CentOS, and RHEL:
365-
```sh
366-
yum -y install m4 # prerequisite for nettle
367-
cd /tmp/
368-
wget https://ftp.gnu.org/gnu/nettle/nettle-3.3.tar.gz
369-
tar -xzf nettle-3.3.tar.gz
370-
cd nettle-3.3
371-
./configure
372-
make clean && make install
373-
cd /usr/lib64 && ln -s /usr/local/lib64/libnettle.so.
374-
```
375-
376-
###### 4. Install Luarocks and Dependencies
377-
```sh
378-
sudo yum install luarocks
379-
sudo luarocks install lua-cjson
380-
sudo luarocks install lustache
381-
sudo luarocks install lua-resty-nettle
382-
sudo luarocks install luasocket
383-
sudo luarocks install lua-resty-http
384-
385-
sudo ln -s /usr/lib64/lua /usr/lib/lua
386-
```
387-
388-
###### 5. Install PerimeterX NGINX Plugin
389-
```sh
390-
sudo luarocks install perimeterx-nginx-plugin
391-
```
392-
393-
###### 6. Modify Selinux (Consult with your internal System Administrator)
394-
On CentOS 7 and other Linux operating systems you may need to modify or disable Selinux. If you get the following error:
395-
396-
`nginx: lua atpanic: Lua VM crashed, reason: runtime code generation failed, restricted kernel?`
397-
398-
You will need to make one of the following changes:
399-
* To disable SELinux: `RUN setenforcer 0`
400-
* To enable execmem for httpd_t: `RUN setsebool httpd_execmem 1 -P`
345+
* [RHEL 7.4 and higher](NGINXPLUS_RHEL7.4.md)
346+
* [Amazon Linux, CentOS and RHEL 7.3 and lower](NGINXPLUS.md)
401347

402348
## <a name="configuration"></a>Configuration
403349

@@ -784,6 +730,20 @@ Controls the timeouts for PerimeterX requests. The API is called when a Risk Coo
784730
end
785731
```
786732

733+
### <a name="custom-parameters"> Enrich Custom Parameters
734+
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).
735+
You must return the `px_cusom_params` object at the end of the function.
736+
737+
**Default:** nil
738+
739+
Example:
740+
```lua
741+
_M.enrich_custom_parameters = function(px_custom_params)
742+
px_custom_params["custom_param1"] = "user_id"
743+
return px_custom_params
744+
end
745+
```
746+
787747
### <a name="blocking-score"></a> Changing the Minimum Score for Blocking
788748

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

‎lib/px/utils/config_builder.lua‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ PX_DEFAULT_CONFIGURATIONS["score_header_enabled"] = { false, "boolean"}
1515
PX_DEFAULT_CONFIGURATIONS["sensitive_routes_prefix"] = { {}, "table"}
1616
PX_DEFAULT_CONFIGURATIONS["sensitive_routes_suffix"] = { {}, "table"}
1717
PX_DEFAULT_CONFIGURATIONS["additional_activity_handler"] = { nil, "function" }
18+
PX_DEFAULT_CONFIGURATIONS["enrich_custom_parameters"] = { nil, "function" }
1819
PX_DEFAULT_CONFIGURATIONS["enabled_routes"] = { {}, "table"}
1920
PX_DEFAULT_CONFIGURATIONS["first_party_enabled"] = { true, "boolean"}
2021
PX_DEFAULT_CONFIGURATIONS["reverse_xhr_enabled"] = { true, "boolean"}

‎lib/px/utils/pxapi.lua‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@ function M.load(px_config)
1616
local px_debug = px_config.px_debug
1717
local ngx_req_get_method = ngx.req.get_method
1818
local ngx_req_http_version = ngx.req.http_version
19+
local px_custom_params = {}
20+
21+
-- initialize the px_custom_params table
22+
for i = 1, 10 do
23+
px_custom_params["custom_param" .. i] = ""
24+
end
1925

2026
-- new_request_object --
2127
-- takes no arguments
@@ -69,6 +75,16 @@ function M.load(px_config)
6975
risk.additional.px_cookie_hmac = ngx.ctx.px_cookie_hmac
7076
end
7177

78+
if px_config.enrich_custom_parameters ~= nil then
79+
px_logger.debug("enrich_custom_parameters was triggered");
80+
local px_risk_custom_params = px_config.enrich_custom_parameters(px_custom_params)
81+
for key, value in pairs(px_risk_custom_params) do
82+
if string.match(key,"^custom_param%d+$") and value ~= "" then
83+
risk.additional[key] = value
84+
end
85+
end
86+
end
87+
7288
risk.additional.http_version = ngx_req_http_version()
7389
risk.additional.http_method = ngx_req_get_method()
7490
risk.additional.module_version = px_constants.MODULE_VERSION

‎lib/px/utils/pxconstants.lua‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
----------------------------------------------
44

55
local _M = {
6-
MODULE_VERSION = "NGINX Module v5.1.0",
6+
MODULE_VERSION = "NGINX Module v5.2.0",
77
RISK_PATH = "/api/v3/risk",
88
CAPTCHA_PATH = "/api/v2/risk/captcha",
99
ACTIVITIES_PATH = "/api/v1/collector/s2s",

perimeterx-nginx-plugin-5.1-0.rockspec renamed to perimeterx-nginx-plugin-5.2-0.rockspec

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
package = "perimeterx-nginx-plugin"
2-
version = "5.1-0"
2+
version = "5.2-0"
33
source = {
44
url = "git://github.com/PerimeterX/perimeterx-nginx-plugin.git",
5-
tag = "v5.1.0",
5+
tag = "v5.2.0",
66
}
77
description = {
88
summary = "PerimeterX NGINX Lua Middleware.",

0 commit comments

Comments
 (0)