{"id":22096032,"url":"https://github.com/HumanSecurity/perimeterx-node-express","last_synced_at":"2025-07-24T22:31:34.160Z","repository":{"id":8497815,"uuid":"55367366","full_name":"PerimeterX/perimeterx-node-express","owner":"PerimeterX","description":"PerimeterX Express.js middleware to monitor and block traffic according to PerimeterX risk score","archived":false,"fork":false,"pushed_at":"2024-03-25T22:26:50.000Z","size":515,"stargazers_count":25,"open_issues_count":8,"forks_count":11,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-04-15T11:31:58.663Z","etag":null,"topics":["enforcer","perimeterx"],"latest_commit_sha":null,"homepage":"http://www.perimeterx.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PerimeterX.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-03T20:27:25.000Z","updated_at":"2024-06-19T02:58:10.037Z","dependencies_parsed_at":"2023-02-16T06:30:44.720Z","dependency_job_id":"e75634ad-44f5-4677-b27a-e644f4b08221","html_url":"https://github.com/PerimeterX/perimeterx-node-express","commit_stats":{"total_commits":234,"total_committers":31,"mean_commits":7.548387096774194,"dds":0.7393162393162394,"last_synced_commit":"d0f9c4496464c9108ac30e6663f72f560a221b00"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerimeterX%2Fperimeterx-node-express","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerimeterX%2Fperimeterx-node-express/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerimeterX%2Fperimeterx-node-express/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PerimeterX%2Fperimeterx-node-express/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PerimeterX","download_url":"https://codeload.github.com/PerimeterX/perimeterx-node-express/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227482498,"owners_count":17779968,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["enforcer","perimeterx"],"created_at":"2024-12-01T04:09:25.705Z","updated_at":"2025-07-24T22:31:28.746Z","avatar_url":"https://github.com/PerimeterX.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/PerimeterX/perimeterx-node-express.svg?branch=master)](https://travis-ci.org/PerimeterX/perimeterx-node-express)\n[![Known Vulnerabilities](https://snyk.io/test/github/PerimeterX/perimeterx-node-express/badge.svg)](https://snyk.io/test/github/PerimeterX/perimeterx-node-express)\n\n![image](https://storage.googleapis.com/perimeterx-logos/primary_logo_red_cropped.png)\n\n# [PerimeterX](http://www.perimeterx.com) Express.js Middleware\n\n\u003e Latest stable version: [v7.9.0](https://www.npmjs.com/package/perimeterx-node-express)\n\n## Table of Contents\n\n-   [Installation](#installation)\n-   [Upgrading](#upgrading)\n-   [Configuration](#configuration)\n    -   [Required Configuration](#requiredConfiguration)\n    -   [Optional Configuration](#optionalConfiguration)\n        - [Module Enabled](#moduleEnabled)\n        - [Module Mode](#moduleMode)\n        - [Blocking Score](#blockingScore)\n        - [Send Page Activities](#sendPageActivities)\n        - [Send Block Activities](#sendBlockActivities)\n        - [Logger Severity](#loggerSeverity)\n        - [Sensitive Routes](#sensitiveRoutes)\n        - [Enforced Specific Routes](#enforcedSpecificRoutes)\n        - [Monitored Specific Routes](#monitoredSpecificRoutes)\n        - [Filter By Route](#filterByRoute)\n        - [Sensitive Headers](#sensitiveHeaders)\n        - [IP Headers](#ipHeaders)\n        - [First Party Enabled](#firstPartyEnabled)\n        - [CD First Party Enabled](#CDFirstPartyEnabled)\n        - [Custom Request Handler](#customRequestHandler)\n        - [Additional Activity Handler](#additionalActivityHandler)\n        - [Enrich Custom Parameters](#enrichCustomParams)\n        - [CSS Ref](#cssRef)\n        - [JS Ref](#jsRef)\n        - [Custom Logo](#customLogo)\n        - [Secured PXHD cookie](#securedpxhd)\n        - [Proxy Support](#proxySupport)\n        - [Custom Cookie Header](#customCookieHeader)\n        - [Filter Traffic by User Agent](#filterByUserAgent)\n        - [Filter Traffic by IP](#filterByIP)\n        - [Filter Traffic by HTTP Method](#filterByMethod)\n        - [Test Block Flow on Monitoring Mode](#bypassMonitorHeader)\n        - [CSP Enabled](#cspEnabled)\n        - [CSP Policy Refresh Interval](#cspPolicyRefreshIntervalMinutes)\n        - [CSP Invalidate Policy Interval](#cspNoUpdatesMaxIntervalMinutes)\n        - [Login Credentials Extraction](#loginCredentialsExtraction)\n        - [JWT](#JWT)\n        - [CORS support](#px_cors_support)\n-   [Code Defender Middleware - cdMiddleware](#cdMiddleware)\n-   [Advanced Blocking Response](#advancedBlockingResponse)\n-   [Multiple App Support](#multipleAppSupport)\n-   [Additional Information](#additionalInformation)\n\n## \u003ca name=\"installation\"\u003e\u003c/a\u003e Installation\n\nPerimeterX Express.js middleware is installed via NPM:\n`$ npm install --save perimeterx-node-express`\n\n\u003e Please note: As stated in [NodeJS's release schedule](https://github.com/nodejs/Release#release-schedule), NodeJS 6.x is reaching EOL. Thus, support for it will be dropped starting with version 5.0.0.\n\n## \u003ca name=\"upgrading\"\u003e\u003c/a\u003e Upgrading\n\nTo upgrade to the latest Enforcer version, run:\n\n`npm install -s perimeterx-node-express`\n\nFor more information, contact [PerimeterX Support](support@perimeterx.com).\n\n## \u003ca name=\"configuration\"\u003e\u003c/a\u003e Configuration\n\n### \u003ca name=\"requiredConfiguration\"\u003e\u003c/a\u003e Required Configuration\n\nTo use PerimeterX middleware on a specific route follow this example:\n\n```javascript\n'use strict';\n\nconst express = require('express');\nconst perimeterx = require('perimeterx-node-express');\n\nconst server = express();\n\n/* px-module and cookie parser need to be initiated before any route usage */\nconst pxConfig = {\n    px_app_id: 'PX_APP_ID',\n    px_cookie_secret: 'PX_COOKIE_ENCRYPTION_KEY',\n    px_auth_token: 'PX_TOKEN',\n};\nperimeterx.init(pxConfig);\n\n/*  block users with high bot scores using px-module for the route /helloWorld */\nserver.get('/helloWorld', perimeterx.middleware, (req, res) =\u003e {\n    res.send('Hello from PX');\n});\n\nserver.listen(8081, () =\u003e {\n    console.log('server started');\n});\n```\n\n-   The PerimeterX **Application ID / AppId** and PerimeterX **Token / Auth Token** can be found in the Portal, in \u003ca href=\"https://console.perimeterx.com/botDefender/admin?page=applicationsmgmt\" onclick=\"window.open(this.href); return false;\"\u003e**Applications**\u003c/a\u003e.\n\n-   The PerimeterX **Cookie Encryption Key** can be found in the portal, in \u003ca href=\"https://console.perimeterx.com/botDefender/admin?page=policiesmgmt\" onclick=\"window.open(this.href); return false;\"\u003e**Policies**\u003c/a\u003e.\n\n    The Policy from where the **Cookie Encryption Key** is taken must correspond with the Application from where the **Application ID / AppId** and PerimeterX **Token / Auth Token**\n\nSetting the PerimeterX middleware on all server's routes:\n\n\u003e When configuring the PerimeterX middleware on all the server's routes, you will have a\n\u003e score evaluation on each incoming request. The recommended pattern is to use\n\u003e on top of page views routes.\n\n```javascript\n'use strict';\n\nconst express = require('express');\nconst perimeterx = require('perimeterx-node-express');\n\nconst server = express();\n\n/* the px-module and parser need to be initialized before any route usage */\nconst pxConfig = {\n    px_app_id: 'PX_APP_ID',\n    px_cookie_secret: 'PX_COOKIE_ENCRYPTION_KEY',\n    px_auth_token: 'PX_TOKEN',\n};\nperimeterx.init(pxConfig);\n\n/* block high scored users using px-module for all routes */\nserver.use(perimeterx.middleware);\n\nserver.get('/helloWorld', (req, res) =\u003e {\n    res.send('Hello from PX');\n});\n\nserver.listen(8081, () =\u003e {\n    console.log('server started');\n});\n```\n\n## \u003ca name=\"upgrade\"\u003e\u003c/a\u003e Upgrading\n\nTo upgrade to the latest Enforcer version, run:\n\n`npm install -s perimeterx-node-express`\n\nYour Enforcer version is now upgraded to the latest enforcer version.\n\nFor more information,contact [PerimeterX Support](support@perimeterx.com).\n\n### \u003ca name=\"optionalConfiguration\"\u003e\u003c/a\u003eOptional Configuration\n\nIn addition to the basic installation configuration [above](#requiredConfiguration), the following configurations options are available:\n\n#### \u003ca name=\"moduleEnabled\"\u003e\u003c/a\u003eModule Enabled\n\nA boolean flag to enable/disable the PerimeterX Enforcer.\n\n**Default:** true\n\n```js\nconst pxConfig = {\n  ...\n  px_module_enabled: false\n  ...\n};\n```\n\n#### \u003ca name=\"moduleMode\"\u003e\u003c/a\u003eModule Mode\n\nSets the working mode of the Enforcer.\n\nPossible values:\n\n-   `monitor` - Monitor Mode\n-   `active_blocking` - Blocking Mode\n\n**Default:** `monitor`\n\n```js\nconst pxConfig = {\n  ...\n  px_module_mode: \"monitor\"\n  ...\n};\n```\n\n#### \u003ca name=\"blockingScore\"\u003e\u003c/a\u003eBlocking Score\n\nSets the minimum blocking score of a request.\n\nPossible values:\n\n-   Any integer between 0 and 100.\n\n**Default:** 100\n\n```js\nconst pxConfig = {\n  ...\n  px_blocking_score: 100\n  ...\n};\n```\n\n#### \u003ca name=\"sendPageActivities\"\u003e\u003c/a\u003eSend Page Activities\n\nA boolean flag to enable/disable sending activities and metrics to PerimeterX with each request. \u003cbr/\u003e\nEnabling this feature allows data to populate the PerimeterX Portal with valuable information, such as the number of requests blocked and additional API usage statistics.\n\n**Default:** true\n\n```js\nconst pxConfig = {\n  ...\n  px_send_async_activities_enabled: true\n  ...\n};\n```\n\n#### \u003ca name=\"loggerSeverity\"\u003e\u003c/a\u003eLogger Severity\n\nSets the logging verbosity level. The available options are:\n\n* `none` - no logs will be generated\n* `error` - logs only when severe errors occur, best for production environments\n* `debug` - logs more descriptive messages, helpful for analyzing and debugging the enforcer flow\n\n**Default:** error\n\n```js\nconst pxConfig = {\n  ...\n  px_logger_severity: 'debug'\n  ...\n};\n```\n\n#### \u003ca name=\"sensitiveRoutes\"\u003e\u003c/a\u003e Sensitive Routes\n\nAn array of route prefixes that trigger a server call to PerimeterX servers every time the page is viewed, regardless of viewing history.\n\n**Default:** Empty\n\n```js\nconst pxConfig = {\n  ...\n  px_sensitive_routes: ['/login', '/user/checkout']\n  ...\n};\n```\n\n#### \u003ca name=\"enforcedSpecificRoutes\"\u003e\u003c/a\u003eEnforced Specific Routes\n\nAn array of route prefixes and/or regular expressions that are always validated by the PerimeterX Worker (as opposed to filtered routes).\n\u003cbr/\u003eA regular expression can be defined using `new RegExp` or directly as an expression, and will be treated as is.\n\u003cbr/\u003eA string value of a path will be treated as a prefix.\n\n**Default:** Empty\n\n```js\nconst pxConfig = {\n  ...\n  px_enforced_routes: ['/home',/^\\/$/]\n  ...\n};\n```\n\n#### \u003ca name=\"monitoredSpecificRoutes\"\u003e\u003c/a\u003eMonitored Specific Routes\n\nAn array of route prefixes and/or regular expressions that are always set to be in [monitor mode](#moduleMode). This only takes effect when the module is enabled and in blocking mode.\n\u003cbr/\u003eA regular expression can be defined using `new RegExp` or directly as an expression, and will be treated as is.\n\u003cbr/\u003eA string value of a path will be treated as a prefix.\n\n**Default:** Empty\n\n```js\nconst pxConfig = {\n  ...\n  px_monitored_routes: ['/home', new RegExp(/^\\/$/)]\n  ...\n};\n```\n\n#### \u003ca name=\"filterByRoute\"\u003e\u003c/a\u003e Filter By Route\n\nAn array of route prefixes and/or regular expressions that are always allowed and not validated by the PerimeterX Worker.\n\u003cbr/\u003eA regular expression can be defined using `new RegExp` or directly as an expression, and will be treated as is.\n\u003cbr/\u003eA string value of a path will be treated as a prefix.\n\n**Default:** Empty\n\n```js\nconst pxConfig = {\n  ...\n  px_filter_by_route: ['/contact-us', /\\/user\\/.*\\/show/]\n  ...\n};\n```\n\n#### \u003ca name=\"sensitiveHeaders\"\u003e\u003c/a\u003eSensitive Headers\n\nAn array of headers that are not sent to PerimeterX servers on API calls.\n\n**Default:** ['cookie', 'cookies']\n\n```js\nconst pxConfig = {\n  ...\n  px_sensitive_headers: ['cookie', 'cookies', 'x-sensitive-header']\n  ...\n};\n```\n\n#### \u003ca name=\"ipHeaders\"\u003e\u003c/a\u003eIP Headers\n\nAn array of trusted headers that specify an IP to be extracted.\n\n**Default:** Empty\n\n```js\nconst pxConfig = {\n  ...\n  px_ip_headers: ['x-user-real-ip']\n  ...\n};\n```\n\n#### \u003ca name=\"firstPartyEnabled\"\u003e\u003c/a\u003eFirst Party Enabled\n\nA boolean flag to enable/disable first party mode.\n\n**Default:** true\n\n```js\nconst pxConfig = {\n  ...\n  px_first_party_enabled: false\n  ...\n};\n```\n\n#### \u003ca name=\"CDFirstPartyEnabled\"\u003e\u003c/a\u003eCD First Party Enabled\n\nA boolean flag to enable/disable Code Defender first party mode.\n\n**Default:** false\n\n```js\nconst pxConfig = {\n  ...\n  px_cd_first_party_enabled: false\n  ...\n};\n```\n\n#### \u003ca name=\"customRequestHandler\"\u003e\u003c/a\u003eCustom Request Handler\n\nA JavaScript function that adds a custom response handler to the request.\n\n**Default:** Empty\n\n```js\nconst pxConfig = {\n  ...\n  px_custom_request_handler: function(pxCtx, pxconfig, req, cb) {\n    ...\n    cb({body: result, status: 200, statusDescription: \"OK\", header: {key: 'Content-Type', value:'application/json'}})\n  }\n  ...\n};\n```\n\n#### \u003ca name=\"additionalActivityHandler\"\u003e\u003c/a\u003eAdditional Activity Handler\n\nA JavaScript 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.\n\n**Default:** Empty\n\n```javascript\nconst pxConfig = {\n  ...\n  px_additional_activity_handler: function(pxCtx, request) {\n    ...\n  }\n  ...\n};\n```\n\n#### \u003ca name=\"enrichCustomParams\"\u003e\u003c/a\u003eEnrich Custom Parameters\n\nWith the `px_enrich_custom_parameters` 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).\n\n**Default:** Empty\n\n```javascript\nconst pxConfig = {\n  ...\n  px_enrich_custom_parameters: function(customParams, originalRequest) {\n    customParams[\"custom_param1\"] = \"yay, test value\";\n    return customParams;\n  }\n  ...\n};\n```\n\n#### \u003ca name=\"cssRef\"\u003e\u003c/a\u003eCSS Ref\n\nModifies a custom CSS by adding the CSSRef directive and providing a valid URL to the CSS.\n\n**Default:** Empty\n\n```javascript\nconst pxConfig = {\n  ...\n  px_css_ref: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css'\n  ...\n};\n```\n\n#### \u003ca name=\"jsRef\"\u003e\u003c/a\u003eJS Ref\n\nAdds a custom JS file by adding JSRef directive and providing the JS file that is loaded with the block page.\n\n**Default:** Empty\n\n```js\nconst pxConfig = {\n  ...\n  px_js_ref: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js'\n  ...\n};\n```\n\n#### \u003ca name=\"customLogo\"\u003e\u003c/a\u003eCustom Logo\n\nThe logo is displayed at the top of the the block page.\nMax-height = 150px, Width = auto.\n\n**Default:** Empty\n\n```js\nconst pxConfig = {\n  ...\n  px_custom_logo: 'https://s.perimeterx.net/logo.png',\n  ...\n};\n```\n\n#### \u003ca name=\"securedpxhd\"\u003e\u003c/a\u003eSecured PXHD cookie\n\nA boolean flag to enable/disable the `Secure` flag when baking a PXHD cookie.\n\n**Default:** false\n\n```js\nconst pxConfig = {\n  ...\n  px_pxhd_secure: true\n  ...\n};\n```\n\n#### \u003ca name=\"proxySupport\"\u003e\u003c/a\u003eProxy Support\n\nAllows traffic to pass through a http proxy server.\n\n**Default:** Empty\n\n```javascript\nconst pxConfig = {\n  ...\n  px_proxy_url: 'https://localhost:8008',\n  ...\n};\n```\n\n#### \u003ca name=\"customCookieHeader\"\u003e\u003c/a\u003eCustom Cookie Header\n\nWhen set, instead of extrating the PerimeterX Cookie from the `Cookie` header, this property specifies a header name that will contain the PerimeterX Cookie.\n\n**Default:** Empty\n\n```javascript\nconst pxConfig = {\n  ...\n  px_custom_cookie_header: \"x-px-cookies\"\n  ...\n};\n```\n\n#### \u003ca name=\"filterByUserAgent\"\u003e\u003c/a\u003e Filter Traffic by User Agent\n\nAn array of user agent constants and/or regular expressions that are always filtered and not validated by the PerimeterX middleware.\n\n**Default:** Empty\n\n```js\nconst pxConfig = {\n  ...\n  px_filter_by_user_agent: ['testUserAgent/v1.0', /test/]\n  ...\n};\n```\n\n#### \u003ca name=\"filterByIP\"\u003e\u003c/a\u003e Filter Traffic by IP\n\nAn array of IP ranges / IP addresses that are always filtered and not validated by the PerimeterX middleware.\n\n**Default:** Empty\n\n```js\nconst pxConfig = {\n  ...\n  px_filter_by_ip: ['192.168.10.0/24', '192.168.2.2']\n  ...\n};\n```\n\n#### \u003ca name=\"filterByMethod\"\u003e\u003c/a\u003e Filter Traffic by HTTP Method\n\nAn array of HTTP methods that are always filtered and not validated by the PerimeterX middleware.\n\n**Default:** Empty\n\n```js\nconst pxConfig = {\n  ...\n  px_filter_by_http_method: ['options']\n  ...\n};\n```\n\n#### \u003ca name=“bypassMonitorHeader”\u003e\u003c/a\u003e Test Block Flow on Monitoring Mode\n\nAllows you to test an enforcer’s blocking flow while you are still in Monitor Mode.\n\nWhen 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.\nTo stay in Monitor Mode, set the header value to `0`.\n\nThe Header Name is configurable using the `px_bypass_monitor_header` property.\n\n**Default:** Empty\n\n```javascript\nconst pxConfig = {\n  ...\n  px_bypass_monitor_header: \"x-px-block\"\n  ...\n};\n```\n\n#### \u003ca name=“cspEnabled”\u003e\u003c/a\u003e CSP Enabled\n\nUsed in `cdMiddleware` - Code Defender's middleware. Enable enforcement of CSP header policy on responses retured to the client (only if active CSP policy exists in PerimeterX for the specific appId). \n\n**Default:** false\n\n```javascript\nconst pxConfig = {\n  ...\n  px_csp_enabled: false\n  ...\n};\n```\n\n#### \u003ca name=“cspPolicyRefreshIntervalMinutes”\u003e\u003c/a\u003e CSP Policy Refresh Interval\n\nUsed by `cdMiddleware` - Code Defender's middleware. Sets the interval, in minutes, to fetch and update the active CSP policy for the specific appId from PerimeterX. \n\n**Default:** 5\n\n```javascript\nconst pxConfig = {\n  ...\n  px_csp_policy_refresh_interval_minutes: 5\n  ...\n};\n```\n\n#### \u003ca name=“cspNoUpdatesMaxIntervalMinutes”\u003e\u003c/a\u003e CSP Invalidate Policy Interval\n\nUsed by `cdMiddleware` - Code Defender's middleware. Invalidates active CSP policy after specified number of minutes with no updates received from PerimeterX. \n\n**Default:** 60\n\n```javascript\nconst pxConfig = {\n  ...\n  px_csp_no_updates_max_interval_minutes: 60\n  ...\n};\n```\n\n#### \u003ca name=\"loginCredentialsExtraction\"\u003e\u003c/a\u003eLogin Credentials Extraction\n\nThis feature extracts credentials (hashed username and password) from requests and sends them to PerimeterX as additional info in the risk api call. The feature can be toggled on and off, and may be set for any number of unique paths.\n\nIf credentials are found to be compromised, the header `px-compromised-credentials` will be added to the request with the value `1`. You may configure the name of this header with the `px_compromised_credentials_header` configuration.\n\n\u003e Note: This feature requires access to the request body as a either an `object` or a `string` type.\n\n**Default Values**\n\npx_compromised_credentials_header: \"px-compromised-credentials\"\n\npx_login_credentials_extraction_enabled: false\n\npx_login_credentials_extraction: Empty\n\n```javascript\nconst pxConfig = {\n  ...\n  px_compromised_credentials_header: \"x-px-comp-creds\",\n  px_login_credentials_extraction_enabled: true,\n  px_login_credentials_extraction: [\n    {\n      path: \"/login\", // login path\n      method: \"post\", // supported values: post\n      sent_through: \"body\", // supported values: body, header, query-param\n      pass_field: \"password\", // name of the password field in the request\n      user_field: \"username\" // name of the username field in the request\n    },\n    ...\n  ],\n  ...\n};\n\n```\n\nIt is also possible to define a custom callback to extract the username and password. The function should accept the request object as\na parameter and return an object with the keys `user` and `pass`. If extraction is unsuccessful, the function should return `null`.\n\n```javascript\nconst pxConfig = {\n    ...\n    px_login_credentials_extraction_enabled: true,\n    px_login_credentials_extraction: [{\n        path: \"/login\", // login path, automatically added to sensitive routes\n        method: \"post\", // supported values: post\n        callback: (req) =\u003e {\n            // custom implementation resulting in variables username and password\n            if (username \u0026\u0026 password) {\n                return { \"user\": username, \"pass\": password };\n            } else {\n                return null;\n            }\n        }\n    }]\n};\n```\n\n#### \u003ca name=\"JWT\"\u003e\u003c/a\u003eJWT\n\nEnable the extraction of JWT fields from requests and adding them to the risk, page requested and block activities.\n\npx_jwt_cookie_name\n\nThe cookie name that should contain the JWT token.\n\n**Default:** \"\"\n\npx_jwt_cookie_user_id_field_name\n\nThe field name in the JWT object, extracted from the JWT cookie, that contains the user ID to be extracted\n\n**Default:** \"\"\n\npx_jwt_cookie_additional_field_names\n\nThe field names in the JWT object, extracted from the JWT cookie, that should be extracted in addition to the user ID.\n\n**Default:** []\n\npx_jwt_header_name\n\nThe header name that should contain the JWT token.\n\n**Default:** \"\"\n\npx_jwt_header_user_id_field_name\n\nThe field name in the JWT object, extracted from the JWT header, that contains the user ID to be extracted\n\n**Default:** \"\"\n\npx_jwt_header_additional_field_names\n\nThe field names in the JWT object, extracted from the JWT header, that should be extracted in addition to the user ID.\n\n**Default:** []\n\n```javascript\nconst pxConfig = {\n  ...\n    \"px_jwt_cookie_name\":  \"auth\",\n    \"px_jwt_cookie_user_id_field_name\": \"nameID\",\n    \"px_jwt_cookie_additional_field_names\": [\"exp\", \"iss\"],\n    \"px_jwt_header_name\":  \"authorization\",\n    \"px_jwt_header_user_id_field_name\": \"sub\",\n    \"px_jwt_header_additional_field_names\": [\"jti\"]\n  ...\n};\n```\n\n### \u003ca name=\"additional-s2s-activity\"\u003e\u003c/a\u003e Additional S2S Activity\n\nTo enhance detection on login credentials extraction endpoints, the following additional information is sent to PerimeterX\nvia an `additional_s2s` activity:\n\n* __Response Code__ - The numerical HTTP status code of the response. This is sent automatically.\n* __Login Success__ - A boolean indicating whether the login completed successfully. See the options listed below for how to provide this data.\n* __Raw Username__ - The original username used for the login attempt. In order to report this information, make sure the configuration `px_send_raw_username_on_additional_s2s_activity` is set to `true`.\n\nBy default, this `additional_s2s` activity is sent automatically. If it is preferable to send this activity manually,\nit's possible to disable automatic sending by configuring the value of `px_automatic_additional_s2s_activity_enabled` to `false`.\n\n**Default Value*: true\n\n```javascript\nconst pxConfig = {\n    ...\n    px_automatic_additional_s2s_activity_enabled: false\n    ...\n}\n```\n\nThe activity can then be sent manually by invoking the function `sendAdditionalS2SActivity()`. The function accepts three\narguments: the original HTTP request, the status code, and a boolean indicating the login successful status.\n\n```javascript\nconst perimeterx = require('perimeterx-node-express');\nconst pxConfig = {\n    px_app_id: '\u003cAPP_ID\u003e',\n    // ...\n};\npxInstance = perimeterx.new(pxConfig);\n\napp.use(pxInstance.middleware);\n\napp.post('/login', (req, res) =\u003e {\n   // login flow resulting in boolean isLoginSuccessful\n    res.status(200).json({ successful: isLoginSuccessful });\n    pxInstance.sendAdditionalS2SActivity(req, res.statusCode, isLoginSuccessful);\n});\n```\n\n#### Login Success Reporting\n\nThere are a number of different possible ways to report the success or failure of the login attempt. If left empty, the\nlogin successful status will always be reported as `false`.\n\n**Default**: Empty\n\n```javascript\nconst pxConfig = {\n    ...\n    px_login_successful_reporting_method: 'status' // supported values: status, header, body, custom\n    ...\n}\n```\n\n__Status__\n\nProvide a status or array of statuses that represent a successful login. If a response's status code matches the provided\nvalue or one of the values in the provided array, the login successful status is set to `true`. Otherwise, it's set to `false`.\n\n\u003e Note: To define a range of statuses, use the `custom` reporting method.\n\n**Default Values**\n\npx_login_successful_status: 200\n\n```javascript\nconst pxConfig = {\n    ...\n    px_login_successful_reporting_method: 'status',\n    px_login_successful_status: [200, 202] // number or array of numbers\n    ...\n}\n```\n\n__Header__\n\nProvide a header name and value. If the header exists on the response and matches the provided value, the login successful\nstatus is set to `true`. If the header is not found on the response, or if the header value does not match the value in the\nconfiguration, the login successful status is set to `false`.\n\n**Default Values**\n\npx_login_successful_header_name: x-px-login-successful\n\npx_login_successful_header_value: 1\n\n```javascript\nconst pxConfig = {\n    ...\n    px_login_successful_reporting_method: 'header',\n    px_login_successful_header_name: 'login-successful',\n    px_login_successful_header_value: 'true'\n    ...\n}\n```\n\n__Body__\n\nProvide a string or regular expression with which to parse the response body. If a match is found, the login successful\nstatus is set to `true`. If no match is found, the login successful status is set to `false`.\n\n**Default Values**\n\npx_login_successful_body_regex: Empty\n\n```javascript\nconst pxConfig = {\n    ...\n    px_login_successful_reporting_method: 'body',\n    px_login_successful_body_regex: 'You logged in successfully!' // string or RegExp\n    ...\n}\n```\n\n__Custom__\n\nProvide a custom callback that returns a boolean indicating if the login was successful.\n\n**Default Values**\npx_login_successful_custom_callback: null\n\n```javascript\nconst pxConfig = {\n    ...\n    px_login_successful_reporting_method: 'custom',\n    px_login_successful_custom_callback: (response) =\u003e {\n        return response \u0026\u0026 response.locals \u0026\u0026 response.locals.isLoginSuccessful;\n    }\n    ...\n}\n```\n\n#### Raw Username\n\nWhen enabled, the raw username used for logins on login credentials extraction endpoints will be reported to PerimeterX\nif (1) the credentials were identified as compromised, and (2) the login was successful as reported via the property above.\n\n**Default**: false\n\n```javascript\nconst pxConfig = {\n    ...\n    px_send_raw_username_on_additional_s2s_activity: true\n    ...\n}\n```\n\n#### \u003ca name=\"px_cors_support\"\u003e\u003c/a\u003eCORS Support\n\nEnable CORS support for the enforcer. This will allow the enforcer to filter out preflight requests and to add CORS headers to block responses.\nThis will ensure responses are not blocked by the browser.\nCORS support is enabled by default.\n\n`px_cors_support_enabled` - Enable CORS support for the enforcer.\n\n**Default:** `false`\n\n`px_cors_custom_preflight_handler` - Custom preflight handler. This function will be called for preflight requests and returns response that will return to the client.\n\n```js\n// Example\nconst pxConfig = { \n    ...\n    px_cors_custom_preflight_handler: function(request) {\n        const response = {\n            status: '204',\n        };\n    \n        response.headers = {\n            'Access-Control-Allow-Origin': request.headers['origin'] || '*',\n            'Access-Control-Allow-Methods': request.method,\n            'Access-Control-Allow-Headers': request.headers['access-control-request-headers'],\n            'Access-Control-Allow-Credentials': 'true',\n            'Access-Control-Max-Age': '86400',\n        };\n    \n        return response;\n    };\n}\n```\n\n`px_cors_preflight_request_filter_enabled` - Filter out preflight requests from validation flow.\n\n**Default:** false\n\nEnable CORS support for the enforcer:\n``` JS\nconst pxConfig = {\n  ...\n  px_cors_support_enabled: true,\n  px_cors_preflight_request_filter_enabled: true,\n  ...\n};\n```\n\nThe default CORS policy when blocking a request is as follows:\n``` JS\nAccess-Control-Allow-Origin: request origin\nAccess-Control-Allow-Credentials: true\n```\n\nThe default CORS policy can be overridden by setting the following properties:\n\n`px_cors_create_custom_block_response_headers`\n\nSynchronous function supplied by the customer which gets the original request and returns an array of custom headers to be added to the block response.\nReturn type should be an array of objects as follows:\n\n```js\n// Example\nconst pxConfig = {\n  ...\n      px_cors_create_custom_block_response_headers: function(request) { \n            return {\n                'Access-Control-Allow-Origin':  request.headers['origin'],\n                'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',\n                'Access-Control-Allow-Headers': 'Content-Type, Authorization',\n                'Access-Control-Allow-Credentials': 'true'\n            }\n        };\n  ...\n};\n```\n\n#### \u003ca name=\"px_custom_is_sensitive_request\"\u003e\u003c/a\u003eCustom Is Sensitive Request\nAllows writing your own logic to decide whether the request is sensitive.\nThe custom sensitive request function gets the request object as a parameter and should return true, otherwise, return false. Throwing an exception is equivalent to `false`.\n\n**Default**: Empty\n\n```javascript\nconst pxConfig = {\n    ...\n        px_custom_is_sensitive_request: function(req) {\n            return req.method === 'POST' \u0026\u0026 req.body \u0026\u0026 req.body.test;\n        }\n    ...\n```\n\n\n**Default:** `null`\n\n## \u003ca name=\"cdMiddleware\"\u003e\u003c/a\u003e Code Defender Middleware - cdMiddleware\n\nCode Defender's middleware to handle the enforcement of CSP headers on responses returned to the client.\nThe express module is in charge of communicating with PerimeterX to receive and maintain the latest CSP policy for the given appId.\nIt also maintains the policy state and invalidates the policy when communication with PerimeterX's Enforcer Data Provider is lost, base on the configuration values (`px_csp_no_updates_max_interval_minutes`, `px_csp_policy_refresh_interval_minutes`).\n\nIt then uses **PerimeterX Node Core** module to enforce the actual functionality adding the necessary CSP header to the response object.\n\nusage example:\n```javascript\nconst perimeterx = require('perimeterx-node-express');\n...\nconst pxInstance = perimeterx.new(pxConfig);\napp.use(pxInstance.cdMiddleware);\n...\n```\n\n### Adding Nonce value to CSP header\n\nThe PerimeterX Express module allows adding a Nonce value to the CSP header.\nTo do this, use the module's static function `addNonce`.\nAfter PerimeterX cdMiddleware has added the CSP header to the response, call the `addNonce` function,\npassing in the response object and a nonce value (string consisting of alphanumeric characters).\nIf a CSP header exists on the response object, the function will alter the header by adding the nonce value in the correct place.\nThe function does not return a value, but rather changes the original response.\n```javascript\nconst perimeterx = require('perimeterx-node-express');\n...\nperimeterx.addNonce(response, 'rAnd0mNon6e');\n...\n```\n\u003e Please note: the nonce value must be unique for each HTTP response.\n\u003e For further explanation, refer to the official documentation of [CSP nonce](https://content-security-policy.com/nonce/).\n\n\n## \u003ca name=\"advancedBlockingResponse\"\u003e\u003c/a\u003e Advanced Blocking Response\n\nIn special cases, (such as XHR post requests) a full Captcha page render might not be an option. In such cases, using the Advanced Blocking Response returns a JSON object continaing all the information needed to render your own Captcha challenge implementation, be it a popup modal, a section on the page, etc. The Advanced Blocking Response occurs when a request contains the _Accept_ header with the value of `application/json`. A sample JSON response appears as follows:\n\n```javascript\n{\n    \"appId\": String,\n    \"jsClientSrc\": String,\n    \"firstPartyEnabled\": Boolean,\n    \"vid\": String,\n    \"uuid\": String,\n    \"hostUrl\": String,\n    \"blockScript\": String\n}\n```\n\nOnce you have the JSON response object, you can pass it to your implementation (with query strings or any other solution) and render the Captcha challenge.\n\nIn addition, you can add the `_pxOnCaptchaSuccess` callback function on the window object of your Captcha page to react according to the Captcha status. For example when using a modal, you can use this callback to close the modal once the Captcha is successfullt solved. \u003cbr/\u003e An example of using the `_pxOnCaptchaSuccess` callback is as follows:\n\n```javascript\nwindow._pxOnCaptchaSuccess = function (isValid) {\n    if (isValid) {\n        alert('yay');\n    } else {\n        alert('nay');\n    }\n};\n```\n\nFor details on how to create a custom Captcha page, refer to the [documentation](https://docs.perimeterx.com/pxconsole/docs/customize-challenge-page)\n\n\u003e If you wish to disable this behavior when the _Accept_ header has the value of `application/json`, set the following configuration:\n\u003e\n\u003e ```javascript\n\u003e const pxConfig = {\n\u003e   ...\n\u003e   px_advanced_blocking_response_enabled: false\n\u003e   ...\n\u003e };\n\u003e ```\n\n## \u003ca name=\"multipleAppSupport\"\u003e\u003c/a\u003e Multiple App Support\n\nIf you use two different apps on the same node runtime, you can create two instances and use them on two routes:\n\n```javascript\n'use strict';\n\nconst express = require('express');\nconst perimeterx = require('perimeterx-node-express');\n\nconst server = express();\n\n/* the px-module and parser need to be initialized before any route usage */\nconst pxConfig1 = {\n    px_app_id: 'PX_APP_ID_1',\n    px_cookie_secret: 'PX_COOKIE_ENCRYPTION_KEY',\n    px_auth_token: 'PX_TOKEN_1',\n};\nconst middlewareApp1 = perimeterx.new(pxConfig1).middleware;\nconst app1Router = express.Router();\napp1Router.use(middlewareApp1);\napp1Router.get('/hello', (req, res) =\u003e {\n    res.send('Hello from App1');\n});\nserver.use('/app1', app1Router);\n\nconst pxConfig2 = {\n    px_app_id: 'PX_APP_ID_2',\n    px_cookie_secret: 'PX_COOKIE_ENCRYPTION_KEY',\n    px_auth_token: 'PX_TOKEN_2',\n};\nconst middlewareApp2 = perimeterx.new(pxConfig2).middleware;\nconst app2Router = express.Router();\napp2Router.use(middlewareApp2);\napp2Router.get('/app2', (req, res) =\u003e {\n    res.send('Hello from App2');\n});\nserver.use('/app2', app1Router);\n\nserver.listen(8081, () =\u003e {\n    console.log('server started');\n});\n``\n\n## \u003ca name=“additionalInformation”\u003e\u003c/a\u003e Additional Information\n\n### URI Delimiters\n\nPerimeterX 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., `$`, `\u0026`) are not used to split the URI as they are considered valid characters in the URI path.\n\n## Thanks\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHumanSecurity%2Fperimeterx-node-express","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHumanSecurity%2Fperimeterx-node-express","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHumanSecurity%2Fperimeterx-node-express/lists"}