Merge pull request #31 from PerimeterX/release/v2.0.0

Release/v2.0.0 to master

Author: chen-zimmer-px

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: ci
+on: pull_request
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+      - name: Setup Python
+        uses: actions/setup-python@v4
+      - name: Install dependencies
+        run: pip install -r dev-requirements.txt && pip install -r requirements.txt
+      - name: Run linter
+        run: pylint -E perimeterx/
+  unit-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: [ "3.6", "3.8", "3.x" ]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install dependencies
+        run: pip install -r dev-requirements.txt && pip install -r requirements.txt
+      - name: Run unit tests
+        run: python -m unittest discover -s ./test -p 'test*'

.travis.yml

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [2.0.0] - 2022-10-25
+### Changed
+- Configuration fields' names align with the spec
+- Async activities fields align with the spec
+- Risk activity fields align with the spec
+- Monitored and enforced routes functionality aligned with the spec
+- `px_custom_verification_handler` function return `Response` object instead of data, headers and status
+- `px_sensitive_routes_regex`, `px_sensitive_routes`, `px_whitelist_routes_regex` and `px_whitelist_routes` configuration fields should contain the exact path
+- Changed `debug_mode` configuration field to `px_logger_severity` and change the expected values to `error` and `debug` 
+
+### Fixed
+- Remove unnecessary risk api activity fields which might cause a bad request response from the collector
+
+### Added
+- Added `request_id` field to the context
+- Added implementation for handling s2s_error and enforcer_error.
+
 ## [1.2.0] - 2022-04-11
 ### Added
 - New block page implementation

CHANGELOG.md

@@ -5,7 +5,7 @@
 
 [PerimeterX](http://www.perimeterx.com) Python 3 Middleware
 =============================================================
-> Latest stable version: [v1.2.0](https://pypi.org/project/perimeterx-python-3-wsgi/)
+> Latest stable version: [v2.0.0](https://pypi.org/project/perimeterx-python-3-wsgi/)
 
 Table of Contents
 -----------------
@@ -30,7 +30,7 @@ Table of Contents
     * [Sensitive Headers](#sensitive_headers)
     * [IP Headers](#ip_headers)
     * [First-Party Enabled](#first_party_enabled)
-    * [Custom Request Handler](#custom_request_handler)
+    * [Custom Request Handler](#custom_verification_handler)
     * [Additional Activity Handler](#additional_activity_handler)
     * [Px Disable Request](#px_disable_request)
     * [Test Block Flow on Monitoring Mode](#bypass_monitor_header)
@@ -58,9 +58,9 @@ To use PerimeterX middleware on a specific route follow this example:
 from perimeterx.middleware import PerimeterX
 
 px_config = {
-    'app_id': 'APP_ID',
-    'cookie_key': 'COOKIE_KEY',
-    'auth_token': 'AUTH_TOKEN',
+    'px_app_id': 'APP_ID',
+    'px_cookie_secret': 'COOKIE_SECRET',
+    'px_auth_token': 'AUTH_TOKEN',
 }
 application = get_wsgi_application()
 application = PerimeterX(application, px_config)
@@ -81,7 +81,7 @@ A boolean flag to enable/disable the PerimeterX Enforcer.
 ```python
 config = {
   ...
-  module_enabled: False
+  px_module_enabled: False
   ...
 }
 ```
@@ -98,7 +98,7 @@ Possible values:
 ```python
 config = {
   ...
-  module_mode: 'active_blocking'
+  px_module_mode: 'active_blocking'
   ...
 }
 ```
@@ -113,7 +113,7 @@ Possible values:
 ```python
 config = {
   ...
-  blocking_score: 100
+  px_blocking_score: 100
   ...
 }
 ```
@@ -132,16 +132,18 @@ config = {
 }
 ```
 
-#### <a name="debug_mode"></a>Debug Mode
+#### <a name="logger_severity"></a>Logger Severity
 
-Enable/disable the debug log messages.
+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:** False
+**Default:** 'error'
 
 ```python
 config = {
   ...
-  debug_mode: True
+  px_logger_severity: 'debug'
   ...
 }
 ```
@@ -154,7 +156,7 @@ An array of route prefixes that trigger a server call to PerimeterX servers ever
 ```python
 config = {
   ...
-  sensitive_routes: ['/login', '/user/checkout']
+  px_sensitive_routes: ['/login', '/user/checkout']
   ...
 }
 ```
@@ -168,12 +170,12 @@ An array of regex patterns that trigger a server call to PerimeterX servers ever
 ```python
 config = {
   ...
-  sensitive_routes_regex: [r'^/login$', r'^/user']
+  px_sensitive_routes_regex: [r'^/login$', r'^/user']
   ...
 }
 ```
 
-#### <a name="whitelist_routes"></a> Whitelist Routes
+#### <a name="filtered_routes"></a> Filter By Routes
 
 An array of route prefixes which will bypass enforcement (will never get scored).
 
@@ -182,7 +184,7 @@ An array of route prefixes which will bypass enforcement (will never get scored)
 ```python
 config = {
   ...
-  whitelist_routes: ['/about-us', '/careers']
+  px_filter_by_route: ['/about-us', '/careers']
   ...
 }
 ```
@@ -211,7 +213,7 @@ When this property is set, any route which is not added - will be whitelisted.
 ```python
 config = {
   ...
-  enforced_specific_routes: ['/profile']
+  px_enforced_routes: ['/profile']
   ...
 };
 ```
@@ -226,7 +228,7 @@ When this property is set, any route which is not added - will be whitelisted.
 ```python
 config = {
   ...
-  enforced_specific_routes_regex: [r'^/profile$']
+  px_enforced_routes_regex: [r'^/profile$']
   ...
 };
 ```
@@ -240,7 +242,7 @@ An array of route prefixes that are always set to be in [monitor mode](#module_m
 ```python
 config = {
   ...
-  monitored_specific_routes: ['/profile']
+  px_monitored_routes: ['/profile']
   ...
 };
 ```
@@ -254,7 +256,7 @@ An array of regex patterns that are always set to be in [monitor mode](#module_m
 ```python
 config = {
   ...
-  monitored_specific_routes_regex: [r'^/profile/me$']
+  px_monitored_routes_regex: [r'^/profile/me$']
   ...
 };
 ```
@@ -268,7 +270,7 @@ An array of headers that are not sent to PerimeterX servers on API calls.
 ```python
 config = {
   ...
-  sensitive_headers: ['cookie', 'cookies', 'x-sensitive-header']
+  px_sensitive_headers: ['cookie', 'cookies', 'x-sensitive-header']
   ...
 }
 ```
@@ -282,7 +284,7 @@ An array of trusted headers that specify an IP to be extracted.
 ```python
 config = {
   ...
-  ip_headers: ['x-user-real-ip']
+  px_ip_headers: ['x-user-real-ip']
   ...
 }
 ```
@@ -296,12 +298,12 @@ Enable/disable First-Party mode.
 ```python
 config = {
   ...
-  first_party: False
+  px_first_party_enabled: False
   ...
 }
 ```
 
-#### <a name="custom_request_handler"></a>Custom Request Handler
+#### <a name="custom_verification_handler"></a>Custom Verification Handler
 
 A Python function that adds a custom response handler to the request.</br>
 You must declare the function before using it in the config.</br>
@@ -313,7 +315,7 @@ The custom function should handle the response (most likely it will create a new
 ```python
 config = {
   ...
-  custom_request_handler: custom_request_handler_function,
+  px_custom_verification_handler: custom_verification_handler_function,
   ...
 }
 ```
@@ -326,7 +328,7 @@ A Python function that allows interaction with the request data collected by Per
 ```python
 config = {
   ...
-  additional_activity_handler: additional_activity_handler_function,
+  px_additional_activity_handler: additional_activity_handler_function,
   ...
 }
 ```
@@ -362,14 +364,14 @@ Allows you to test an enforcer’s blocking flow while you are still in Monitor
 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 `bypass_monitor_header` property.
+The Header Name is configurable using the `px_bypass_monitor_header` property.
 
 **Default:** Empty
 
 ```python
 config = {
   ...
-  bypass_monitor_header: 'x-px-block',
+  px_bypass_monitor_header: 'x-px-block',
   ...
 }
 ```

README.md

@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class PassReason(Enum):
+    COOKIE = 'cookie'
+    S2S = 's2s'
+    S2S_TIMEOUT = 's2s_timeout'
+    S2S_ERROR = 's2s_error'
+    ENFORCER_ERROR = 'enforcer_error'
+
+    def __str__(self):
+        return str(self.value)

perimeterx/enums/pass_reason.py

@@ -0,0 +1,13 @@
+from enum import Enum
+
+
+class S2SErrorReason(Enum):
+    NO_ERROR = ''
+    BAD_REQUEST = 'bad_request'
+    SERVER_ERROR = 'server_error'
+    INVALID_RESPONSE = 'invalid_response'
+    REQUEST_FAILED_ON_SERVER = 'request_failed_on_server'
+    UNKNOWN_ERROR = 'unknown_error'
+
+    def __str__(self):
+        return str(self.value)

perimeterx/enums/s2s_error_reason.py

@@ -1,9 +1,12 @@
+import sys
 import time
 
 from werkzeug.wrappers import Request
 
 from perimeterx import px_activities_client
 from perimeterx import px_utils
+from perimeterx.enums.pass_reason import PassReason
+from perimeterx.enums.s2s_error_reason import S2SErrorReason
 from perimeterx.px_config import PxConfig
 from perimeterx.px_context import PxContext
 from perimeterx.px_request_verifier import PxRequestVerifier
@@ -24,7 +27,7 @@ def __init__(self, app, config=None):
             logger.error('Unable to initialize module, missing mandatory configuration: auth_token')
             raise ValueError('PX Auth Token is missing')
 
-        if not px_config.cookie_key:
+        if not px_config.cookie_secret:
             logger.error('Unable to initialize module, missing mandatory configuration: px_cookie')
             raise ValueError('PX Cookie Key is missing')
 
@@ -52,6 +55,7 @@ def __call__(self, environ, start_response):
             return verified_response(environ, pxhd_callback)
 
         except Exception as err:
+            self._config.logger.error(generate_exception())
             self._config.logger.error("Caught exception, passing request. Exception: {}".format(err))
             if context:
                 self.report_pass_traffic(context)
@@ -65,14 +69,18 @@ def verify(self, request):
         logger.debug("Starting request verification {}".format(request.path))
         ctx = None
         try:
-            if not config._module_enabled:
+            if not config.module_enabled:
                 logger.debug('Request will not be verified, module is disabled')
                 return ctx, True
             ctx = PxContext(request, config)
             return ctx, self._request_verifier.verify_request(ctx, request)
         except Exception as err:
             logger.error("Caught exception in verify, passing request. Exception: {}".format(err))
             if ctx:
+                if ctx.s2s_error_reason == str(S2SErrorReason.NO_ERROR):
+                    ctx.pass_reason = str(PassReason.ENFORCER_ERROR)
+                    ctx.error_message = generate_exception()
+
                 self.report_pass_traffic(ctx)
             else:
                 self.report_pass_traffic(PxContext(Request({}), config))
@@ -97,3 +105,11 @@ def custom_start_response(status, headers, exc_info=None):
         return start_response(status, headers, exc_info)
 
     return custom_start_response
+
+
+def generate_exception():
+    exc_type, exc_obj, tb = sys.exc_info()
+    f = tb.tb_frame
+    lineno = tb.tb_lineno
+    filename = f.f_code.co_filename
+    return 'EXCEPTION IN ({}, LINE {}): {}'.format(filename, lineno, exc_obj)