/captcha/*`
- If the PerimeterX Kong module is enabled on `location /`, the routes are already open and no action is necessary.
> NOTE: The PerimeterX Kong Plugin Configuration Requirements must be completed before proceeding to the next stage of installation.
##### First-Party JS Snippet
Ensure the PerimeterX Kong 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.
#### Changing the Minimum Score for Blocking
**Default blocking value:** 100
```bash
--data 'config.blocking_score=60'
```
#### Blocking Mode
**Default:** false
```bash
--data 'config.block_enabled=true'
```
The PerimeterX plugin is enabled in monitor only mode by default.
Setting the block_enabled flag to *true* will activate the module to enforce the blocking score. The PerimeterX module will block users crossing the block score threshold that you define. If a user crosses the minimum block score then the user will receive the block page.
#### Enabled Routes
The enabled routes variable allows you to implicitly define a set of routes which the plugin will be active on. Supplying an empty list will set all application routes as active.
**Default: Empty list (all routes)**
```bash
--data 'config.enabled_routes=/blockhere'
```
#### Sensitive Routes
Lists of route prefixes and suffixes. The PerimeterX module will always match the request URI with these lists, and if a match is found will create a server-to-server call, even if the cookie is valid and its score is low.
**Default: Empty list**
```bash
--data 'config.sensitive_routes_prefix=/login,/user/profile'
--data 'config.sensitive_routes_suffix=/download'
```
#### Filter sensitive headers
A list of sensitive headers can be configured to prevent specific headers from being sent to PerimeterX servers (lower case header names). Filtering cookie headers for privacy is set by default, and can be overridden on the `pxConfig` variable.
**Default: cookie, cookies**
```bash
--data 'config.sensitive_headers=cookie,cookies,secret-header'
```
#### API Timeout Milliseconds
> Note: Controls the timeouts for PerimeterX requests. The API is called when a Risk Cookie does not exist, or is expired or invalid.
API Timeout in milliseconds (float) to wait for the PerimeterX server API response.
**Default:** 1000
```bash
--data 'config.s2s_timeout=250'
```
#### Send Page Activities
A boolean flag to determine whether or not to send activities and metrics to PerimeterX, on each page request. Disabling this feature will prevent PerimeterX from receiving data populating the PerimeterX portal, containing valuable information such as the amount of requests blocked and other API usage statistics.
**Default:** true
```bash
--data 'config.send_page_requested_activity=false'
```
#### Debug Mode
Enables debug logging mode.
**Default:** false
```bash
--data 'config.px_debug=true'
```
#### Extracting the real IP address from a request
> Note: It is important that the real connection IP is properly extracted when your NGINX server sits behind a load balancer or CDN. The PerimeterX module requires the user's real IP address.
For the PerimeterX NGINX module to see the real user's IP address, you need to set `ip_headers`, a list of headers to extract the real IP from, ordered by priority.
**Default with no predefined header: `ngx.var.remote_addr`**
Example:
```bash
--data 'config.ip_headers=X-TRUE-IP,X-Forwarded-For'
```
#### Custom Block Page
Customizing block page can be done by 2 methods:
##### Modifying default block pages
PerimeterX default block page can be modified by injecting custom css, javascript and logo to page
**default values:** nil
Example:
```bash
--data 'config.custom_logo= http://www.example.com/logo.png'
--data 'config.css_ref=http://www.example.com/style.css'
--data 'config.js_ref=http://www.example.com/script.js'
```
##### Redirect to a custom block page url
Users can customize the blocking page to meet their branding and message requirements by specifying the URL to a blocking page HTML file. The page can also implement reCaptcha. See [NGINX plugin docs](https://github.com/PerimeterX/perimeterx-nginx-plugin/tree/master/examples) for examples of a customized Captcha page.
**default:** nil
```bash
--data 'config.custom_block_url=http://www.example.com/block.html'
```
> Note: This URI **MUST** be whitelisted under `config.whitelist.uri_full` to avoid infinite redirects to the block page.
#### API Protection Mode
For the case where kong is used for API calls and not serving HTML pages, users can set the plugin into API protection mode.
In this mode, when the system decides to block a request, instead of rendering an HTML block/captcha page, it will return a JSON object
that contains a URL for optional redirect on the user's client side.
The end user can be redirected this way to a custom captcha page, and after solving the captcha challenge, will be redirected back to the page they came from or to a default location.
##### Note
When setting the configuration of `api_protection_mode` to `true`, users must also set `api_protection_block_url` which is the address of the custom block page,
and api_protection_default_redirect_url which is the default location for redirect after solving captcha.
Example:
```bash
--data 'config.api_protection_mode=true'
--data 'config.api_protection_block_url=http://www.example.com/block.html'
--data 'config.api_protection_default_redirect_url=http://www.example.com/home.html'
```
Response may look like:
```json
{
"reason": "blocked",
"redirect_to": "http://www.example.com/block.html?url=aHR0cDovL2xvY2FsaG9zdDo4MDAwLz9nZmQ9ZmdkZmc=&uuid=11a12b80-b40c-11e7-8050-eb8403f523e5&vid=ef77a690-9bc8-11e7-9c31-970ffdcc0e6d"
}
```
#### Redirect on Custom URL
The `_M.redirect_on_custom_url` flag provides 2 options for redirecting users to a block page.
**default:** false
```bash
--data 'config.redirect_on_custom_url=false'
```
By default, when a user crosses the blocking threshold and blocking is enabled, the user will be redirected to the block page defined by the `_M.custom_block_url` variable, responding with a 307 (Temporary Redirect) HTTP Response Code.
Setting the flag to flase will *consume* the page and serve it under the current URL, responding with a 403 (Unauthorized) HTTP Response Code.
>_Setting the flag to **false** does not require the block page to include any of the coming examples, as they are injected into the blocking page via the PerimeterX Nginx Enforcer._
Setting the flag to **true** (enabling redirects) will result with 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
```
>Note: the **url** variable is comprised of URL Encoded query parameters (of the originating request) and then both the original path and variables are Base64 Encoded (to avoid collisions with block page query params).
###### Custom blockpage requirements:
When captcha is enabled, and `_M.redirect_on_custom_url` is set to **true**, the block page **must** include the following:
* The `` section **must** include:
```html
#### Configuration example:
```bash
--data 'config.custom_block_url=/block.html'
--data 'config.redirect_on_custom_url=true'
```
#### Block page implementation full example:
```html
You are Blocked
Try and solve the captcha
```
#### Multiple App Support
The PerimeterX Enforcer allows for multiple configurations for different apps.
If your PerimeterX account contains several Applications (as defined via the portal), follow these steps to create different configurations for each Application.
Since Kong supports multiple APIs, you can also use the same PerimeterX Application with different configuration for different APIs, but for best results in our detection,
it is best to use different Applications and policies for different APIs.
#### Additional Activity Handler
Adding an additional activity handler is done by setting 'additional_activity_handler' with a user defined function on the 'pxconfig.lua' file. The 'additional_activity_handler' function will be executed before sending the data to the PerimeterX portal.
Because of technical limitations of the Kong platform, you can't set this function using the admin API. Instead, you need to edit the PerimeterX plugin's `handler.lua`
file, and add the function directly to the configuration.
Default: Only send activity to PerimeterX.
```lua
function additional_activity_handler(event_type, ctx, details)
local cjson = require "cjson"
if (event_type == 'block') then
logger.warning("PerimeterX " + event_type + " blocked with score: " + ctx.score + "details " + cjson.encode(details))
else
logger.info("PerimeterX " + event_type + " details " + cjson.encode(details))
end
end
function PXHandler:init_worker(config)
PXHandler.super.init_worker(self)
...
--add function to pxconfig here
config.additional_activity_handler = additional_activity_handler
end
```
Whitelisting
-----------------------------------------------
Whitelisting (bypassing enforcement) is configured under in the `whitelist` table.
There are several different types of filters that can be configured.
```
whitelist_uri_full = { _M.custom_block_url },
whitelist_uri_prefixes = {},
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'},
whitelist_ip_addresses = {},
whitelist_ua_full = {},
whitelist_ua_sub = {}
```
- **whitelist_uri_full** : for value `{'/api_server_full'}` - will filter requests to `/api_server_full?data=1` but not to `/api_server?data=1`
- **whitelist_uri_prefixes** : for value `{'/api_server'}` - will filter requests to `/api_server_full?data=1` but not to `/full_api_server?data=1`
- **whitelist_uri_suffixes** : for value `{'.css'}` - will filter requests to `/style.css` but not to `/style.js`
- **whitelist_ip_addresses** : for value `{'192.168.99.1'}` - will filter requests coming from any of the listed ips.
- **whitelist_ua_full** : for value `{'Mozilla/5.0 (compatible; pingbot/2.0; http://www.pingdom.com/)'}` - will filter all requests matching this exact UA.
- **whitelist_ua_sub** : for value `{'GoogleCloudMonitoring'}` - will filter requests containing the provided string in their UA.
Contributing
----------------------------------------
The following steps are welcome when contributing to our project.
### Fork/Clone
[Create a fork](https://guides.github.com/activities/forking/) of the repository, and clone it locally.
Create a branch on your fork, preferably using a descriptive branch name.
### Pull Request
After you have completed the process, create a pull request. Please provide a complete and thorough description explaining the changes. Remember, this code has to be read by our maintainers, so keep it simple, smart and accurate.
### Thanks
After all, you are helping us by contributing to this project, and we want to thank you for it.
We highly appreciate your time invested in contributing to our project, and are glad to have people like you - kind helpers.