README.md

PerimeterX Python 3 Middleware

Latest stable version: v2.0.0

Table of Contents

• Installation
• Upgrading
• Required Configuration
• Advanced Blocking Response
• Optional Configuration
  • Module Enabled
  • Module Mode
  • Blocking Score
  • Send Page Activities
  • Debug Mode
  • Sensitive Routes
  • Sensitive Routes Regex
  • Whitelist Routes
  • Whitelist Routes Regex
  • Enforce Specific Routes
  • Enforce Specific Routes Regex
  • Monitor Specific Routes
  • Monitor Specific Routes Regex
  • Sensitive Headers
  • IP Headers
  • First-Party Enabled
  • Custom Request Handler
  • Additional Activity Handler
  • Px Disable Request
  • Test Block Flow on Monitoring Mode
• Additional Information

Installation

• To install the PerimeterX Python 3 middleware, use PIP as follows:

pip install perimeterx-python-3-wsgi

Upgrading

To upgrade to the latest PerimeterX Enforcer version, run:

pip install -U perimeterx-python-3-wsgi

For more information, contact PerimeterX Support.

Required Configurations

To use PerimeterX middleware on a specific route follow this example:

from perimeterx.middleware import PerimeterX

px_config = {
    'px_app_id': 'APP_ID',
    'px_cookie_secret': 'COOKIE_SECRET',
    'px_auth_token': 'AUTH_TOKEN',
}
application = get_wsgi_application()
application = PerimeterX(application, px_config)

• The PerimeterX Application ID / AppId and PerimeterX Token / Auth Token can be found in the Portal, in Applications.
• PerimeterX Risk Cookie / Cookie Key can be found in the portal, in Policies. The Policy from where the Risk Cookie / Cookie Key is taken must correspond with the Application from where the Application ID / AppId and PerimeterX Token / Auth Token. For details on how to create a custom Captcha page, refer to the documentation

Optional Configuration

In addition to the basic installation configuration above, the following configurations options are available:

Module Enabled

A boolean flag to enable/disable the PerimeterX Enforcer.

Default: true

config = {
  ...
  px_module_enabled: False
  ...
}

Module Mode

Sets the working mode of the Enforcer.

Possible values:

• active_blocking - Blocking Mode
• monitor - Monitoring Mode

Default: monitor - Monitor Mode

config = {
  ...
  px_module_mode: 'active_blocking'
  ...
}

Blocking Score

Sets the minimum blocking score of a request.

Possible values:

• Any integer between 0 and 100.

Default: 100

config = {
  ...
  px_blocking_score: 100
  ...
}

Send Page Activities

Enable/disable sending activities and metrics to PerimeterX with each request.
Enabling this feature allows data to populate the PerimeterX Portal with valuable information, such as the number of requests blocked and additional API usage statistics.

Default: true

config = {
  ...
  send_page_activities: True
  ...
}

Logger Severity

The severity level at which the logger should output logs 'error' - PerimeterX logger will log errors only on fatal events (e.g., uncaught errors) 'debug' - PerimeterX logger will output detailed logs for debugging purposes

Default: 'error'

config = {
  ...
  px_logger_severity: 'debug'
  ...
}

Sensitive Routes

An array of route prefixes that trigger a server call to PerimeterX servers every time the page is viewed, regardless of viewing history.

Default: Empty

config = {
  ...
  px_sensitive_routes: ['/login', '/user/checkout']
  ...
}

Sensitive Routes Regex

An array of regex patterns that trigger a server call to PerimeterX servers every time the page is viewed, regardless of viewing history.

Default: Empty

config = {
  ...
  px_sensitive_routes_regex: [r'^/login$', r'^/user']
  ...
}

Filter By Routes

An array of route prefixes which will bypass enforcement (will never get scored).

Default: Empty

config = {
  ...
  px_filter_by_route: ['/about-us', '/careers']
  ...
}

Whitelist Routes Regex

An array of regex patterns which will bypass enforcement (will never get scored).

Default: Empty

config = {
  ...
  whitelist_routes_regex: [r'^/about']
  ...
}

Enforce Specific Routes

An array of route prefixes that are always validated by the PerimeterX Worker (as opposed to whitelisted routes). When this property is set, any route which is not added - will be whitelisted.

Default: Empty

config = {
  ...
  px_enforced_routes: ['/profile']
  ...
};

Enforce Specific Routes Regex

An array of regex patterns that are always validated by the PerimeterX Worker (as opposed to whitelisted routes). When this property is set, any route which is not added - will be whitelisted.

Default: Empty

config = {
  ...
  px_enforced_routes_regex: [r'^/profile$']
  ...
};

Monitor Specific Routes

An array of route prefixes that are always set to be in monitor mode. This configuration is effective only when the module is enabled and in blocking mode.

Default: Empty

config = {
  ...
  px_monitored_routes: ['/profile']
  ...
};

Monitor Specific Routes Regex

An array of regex patterns that are always set to be in monitor mode. This configuration is effective only when the module is enabled and in blocking mode.

Default: Empty

config = {
  ...
  px_monitored_routes_regex: [r'^/profile/me$']
  ...
};

Sensitive Headers

An array of headers that are not sent to PerimeterX servers on API calls.

Default: ['cookie', 'cookies']

config = {
  ...
  px_sensitive_headers: ['cookie', 'cookies', 'x-sensitive-header']
  ...
}

IP Headers

An array of trusted headers that specify an IP to be extracted.

Default: Empty

config = {
  ...
  px_ip_headers: ['x-user-real-ip']
  ...
}

First-Party Enabled

Enable/disable First-Party mode.

Default: True

config = {
  ...
  px_first_party_enabled: False
  ...
}

Custom Verification Handler

A Python function that adds a custom response handler to the request.
You must declare the function before using it in the config.
The Custom Request Handler is triggered after PerimeterX's verification. The custom function should handle the response (most likely it will create a new response)

Default: Empty

config = {
  ...
  px_custom_verification_handler: custom_verification_handler_function,
  ...
}

Additional Activity Handler

A Python function that allows interaction with the request data collected by PerimeterX before the data is returned to the PerimeterX servers. Does not alter the response.

Default: Empty

config = {
  ...
  px_additional_activity_handler: additional_activity_handler_function,
  ...
}

PerimeterX Data Enrichment

This is a cookie we make available for our costumers, that can provide extra data about the request

context.pxde
context.pxde_verified

Px Disable Request

This is a property that allows the developer to disable the module for a single request. Its value should be True for disabling, and False for enabling

...
environ['px_disable_request'] = False #The request shall be passed to the enforcer.

or

environ['px_disable_request'] = True #The enforcer shall be disabled for that request.

Test Block Flow on Monitoring Mode

Allows you to test an enforcer’s blocking flow while you are still in Monitor Mode.

When the header name is set(eg. x-px-block) and the value is set to 1, when there is a block response (for example from using a User-Agent header with the value of PhantomJS/1.0) the Monitor Mode is bypassed and full block mode is applied. If one of the conditions is missing you will stay in Monitor Mode. This is done per request. To stay in Monitor Mode, set the header value to 0.

The Header Name is configurable using the px_bypass_monitor_header property.

Default: Empty

config = {
  ...
  px_bypass_monitor_header: 'x-px-block',
  ...
}

Additional Information

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.