> This page is for Applications Protection. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.humansecurity.com/llms.txt. # Configuration Options (7.9.0 and below) **Configuration Up to v6.8.2** Configuration ```none const configKeyMapping = [ 'enableModule' 'pxAppId' 'cookieSecretKey' 'authToken' 'proxy' 'apiTimeoutMS' 'activitiesTimeout' 'customRequestHandler' 'getUserIp' 'blockingScore' 'ipHeaders' 'sendPageActivities' 'sensitiveHeaders' 'debugMode' 'maxBufferLength' 'jsRef' 'cssRef' 'customLogo' 'sensitiveRoutes' 'whitelistRoutes' 'enforcedRoutes' 'monitoredRoutes' 'dynamicConfigurations' 'moduleMode' 'firstPartyEnabled' 'additionalActivityHandler' 'enrichCustomParameters'], 'testingMode' 'whitelistExt' 'bypassMonitorHeader' 'advancedBlockingResponse' 'telemetryCommandHeader' 'customTemplateRoot' 'customTemplateData' 'filterByIP' 'filterByUserAgent' 'filterByMethod' 'externalActivities' 'pxhdSecure' 'backendUrl' 'customCookieHeader' 'enableLoginCredsExtraction' 'loginCredsExtraction' ] ``` **Configuration From v7.0.0** ## Module Enabled A boolean flag to enable/disable the HUMAN Enforcer. **Default:** true ```javascript const pxConfig = { ... px_module_enabled: false ... }; ``` ## Module Mode Sets the working mode of the Enforcer. Possible values: `monitor` - Monitor Mode\ `active_blocking` - Blocking Mode ```javascript const pxConfig = { ... 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 ```javascript const pxConfig = { ... px_blocking_score: 100 ... }; ``` ## Send Page Activities A boolean flag to enable/disable sending activities and metrics to HUMAN with each request. Enabling this feature allows data to populate the HUMAN Portal with valuable information, such as the number of requests blocked and additional API usage statistics. **Default:** true ```none const pxConfig = { ... px_send_async_activities_enabled: true ... }; ``` ## Logger Severity Sets the logging verbosity level. The available options are: `none` - no logs will be generated\ `error` - logs only when severe errors occur, best for production environments\ `debug` - logs more descriptive messages, helpful for analyzing and debugging the enforcer flow **Default:** error ```javascript const pxConfig = { ... px_logger_severity: 'debug' ... }; ``` ## Sensitive Routes An array of route prefixes that trigger a server call to HUMAN servers every time the page is viewed, regardless of viewing history. **Default:** Empty ```javascript const pxConfig = { ... px_sensitive_routes: ['/login', '/user/checkout'] ... }; ``` ## Filter By Route An array of route prefixes and/or regular expressions that are always allowed and not validated by the HUMAN Worker.\ A regular expression can be defined using `new RegExp` or directly as an expression, and will be treated as is.\ A string value of a path will be treated as a prefix. **Default:** Empty ```javascript const pxConfig = { ... px_filter_by_route: ['/contact-us', /\/user\/.*\/show/] ... }; ``` ## Enforced Specific Routes An array of route prefixes and/or regular expressions that are always validated by the HUMAN Worker (as opposed to filtered routes).\ A regular expression can be defined using `new RegExp` or directly as an expression, and will be treated as is.\ A string value of a path will be treated as a prefix. **Default:** Empty ```javascript const pxConfig = { ... px_enforced_routes: ['/home',/^\/$/] ... }; ``` ## Monitored Specific Routes An array of route prefixes and/or regular expressions that are always set to be in monitor mode. This only takes effect when the module is enabled and in blocking mode.\ A regular expression can be defined using new RegExp or directly as an expression, and will be treated as is.\ A string value of a path will be treated as a prefix. **Default:** Empty ```javascript const pxConfig = { ... px_monitored_routes: ['/home', new RegExp(/^\/$/)] ... }; ``` ## Sensitive Headers An array of headers that are not sent to HUMAN servers on API calls. **Default:** \['cookie', 'cookies'] ```javascript const pxConfig = { ... px_sensitive_headers: ['cookie', 'cookies', 'x-sensitive-header'] ... }; ``` ## IP Headers An array of trusted headers that specify an IP to be extracted. **Default:** Empty ```javascript const pxConfig = { ... px_ip_headers: ['x-user-real-ip'] ... }; ``` ## First Party Enabled A boolean flag to enable/disable first party mode. **Default:** true ```javascript const pxConfig = { ... px_first_party_enabled: true ... }; ``` ## First Party Enabled (Code Defender) A boolean flag to enable/disable Code Defender first party mode. Default: false ```javascript const pxConfig = { ... px_cd_first_party_enabled: false ... }; ``` ## Custom Request Handler A JavaScript function that adds a custom response handler to the request. **Default:** Empty ```javascript const pxConfig = { ... px_custom_request_handler: function(pxCtx, pxconfig, req, cb) { ... cb({body: result, status: 200, statusDescription: "OK", header: {key: 'Content-Type', value:'application/json'}}) } ... }; ``` ## Additional Activity Handler A JavaScript function that allows interaction with the request data collected by HUMAN before the data is returned to the HUMAN servers. Does not alter the response. **Default:** Empty ```javascript const pxConfig = { ... px_additional_activity_handler: function(pxCtx, config) { ... } ... }; ``` ## Enrich Custom Parameters With the `px_enrich_custom_parameters`  function you can add up to 10 custom parameters to be sent back to HUMAN servers. When set, the function is called before setting the payload on every request to HUMAN servers. The parameters should be passed according to the correct order (1-10). **Default:** Empty ```javascript const pxConfig = { ... px_enrich_custom_parameters: function(customParams) { customParams["custom_param1"] = "yay, test value"; return customParams; } ... }; ``` ## CSS Ref Modifies a custom CSS by adding the CSSRef directive and providing a valid URL to the CSS. **Default:** Empty ```javascript const pxConfig = { ... px_css_ref: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css' ... }; ``` ## JS Ref Adds a custom JS file by adding JSRef directive and providing the JS file that is loaded with the block page. **Default:** Empty ```javascript const pxConfig = { ... px_js_ref: 'https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js' ... }; ``` ## Custom Logo The logo is displayed at the top of the the block page.\ Max-height = 150px, Width = auto. **Default:** Empty ```javascript const pxConfig = { ... px_custom_logo: 'https://s.perimeterx.net/logo.png', ... }; ``` ## Custom Sensitive Request Allows writing your own logic to decide whether the request is sensitive. The 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\`. Implementing this configuration does not override other \`sensitive\` configurations, like \`sensitive\_routes\`. **Example** ```javascript const pxConfig = { ... px_custom_is_sensitive_request: function(req) { return req.method === 'POST' && req.body && req.body.test; } ... ``` ## Proxy Support Allows traffic to pass through a http proxy server. **Default:** Empty ```javascript const pxConfig = { ... px_proxy_url: 'https://localhost:8008', ... }; ``` ## Filter Traffic by User Agent An array of user agent constants and/or regular expressions that are always filtered and not validated by the HUMAN middleware. **Default:** Empty ```javascript const pxConfig = { ... px_filter_by_user_agent: ['testUserAgent/v1.0'] ... }; ``` ## Filter Traffic by IP An array of IP ranges / IP addresses that are always filtered and not validated by the HUMAN middleware. **Default:** Empty ```javascript const pxConfig = { ... px_filter_by_ip: ['192.168.10.0/24', '192.168.2.2'] ... }; ``` ## Bypass Monitor Header Allows you to test an enforcer’s blocking flow while you are still in Monitor Mode. When the header name is set (e.g., `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 ```javascript const pxConfig = { ... px_bypass_monitor_header: "x-px-block" ... }; ``` ## Filter Traffic by HTTP Method An array of HTTP methods that are always filtered and not validated by the HUMAN middleware. **Default:** Empty ```javascript const pxConfig = { ... px_filter_by_http_method: ['options'] ... }; ``` ## Login Credentials Extraction This feature extracts credentials (hashed username and password) from requests and sends them to HUMAN 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. If 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. > **Note** > > This feature requires access to the request body as a either an `object` or a `string` type. **Default Values** px\_compromised\_credentials\_header: "px-compromised-credentials" px\_login\_credentials\_extraction\_enabled: false px\_login\_credentials\_extraction: Empty ```javascript const pxConfig = { ... px_compromised_credentials_header: "x-px-comp-creds", px_login_credentials_extraction_enabled: true, px_login_credentials_extraction: [ { path: "/login", // login path method: "post", // supported values: post sent_through: "body", // supported values: body, header, query-param pass_field: "password", // name of the password field in the request user_field: "username" // name of the username field in the request }, ... ], ... }; ``` It is also possible to define a custom callback to extract the username and password. The function should accept the request object as a parameter and return an object with the keys `user` and `pass`. If extraction is unsuccessful, the function should return `null`. ```javascript const pxConfig = { ... px_login_credentials_extraction_enabled: true, px_login_credentials_extraction: [{ path: "/login", // login path, automatically added to sensitive routes method: "post", // supported values: post callback: (req) => { // custom implementation resulting in variables username and password if (username && password) { return { "user": username, "pass": password }; } else { return null; } } }] }; ``` ## Additional S2S Activity To enhance detection on login credentials extraction endpoints, the following additional information is sent to HUMAN via an `additional_s2s` activity: * **Response Code** - The numerical HTTP status code of the response. This is sent automatically. * **Login Success** - A boolean indicating whether the login completed successfully. See the options listed below for how to provide this data. * **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`. By default, this `additional_s2s` activity is sent automatically. If it is preferable to send this activity manually,\ it's possible to disable automatic sending by configuring the value of `px_automatic_additional_s2s_activity_enabled` to `false`. **Default Value**: true ```javascript const pxConfig = { ... px_automatic_additional_s2s_activity_enabled: false ... } ``` The activity can then be sent manually by invoking the function `sendAdditionalS2SActivity()`. The function accepts three arguments: the original HTTP request, the status code, and a boolean indicating the login successful status. ```javascript const perimeterx = require('perimeterx-node-express'); const pxConfig = { px_app_id: '', // ... }; pxInstance = perimeterx.new(pxConfig); app.use(pxInstance.middleware); app.post('/login', (req, res) => { // login flow resulting in boolean isLoginSuccessful res.status(200).json({ successful: isLoginSuccessful }); pxInstance.sendAdditionalS2SActivity(req, res.statusCode, isLoginSuccessful); }); ``` ### Login Success Reporting There are a number of different possible ways to report the success or failure of the login attempt. If left empty, the login successful status will always be reported as `false`. **Default**: Empty ```javascript const pxConfig = { ... px_login_successful_reporting_method: 'status' // supported values: status, header, body, custom ... } ``` **Status** Provide a status or array of statuses that represent a successful login. If a response's status code matches the provided value or one of the values in the provided array, the login successful status is set to `true`. Otherwise, it's set to `false`. > **Note** > > To define a range of statuses, use the `custom` reporting method. **Default**: 200 ```javascript const pxConfig = { ... px_login_successful_reporting_method: 'status', px_login_successful_status: [200, 202] // number or array of numbers ... } ``` **Header** Provide a header name and value. If the header exists on the response and matches the provided value, the login successful status 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 configuration, the login successful status is set to `false`. **Default Values** px\_login\_successful\_header\_name: x-px-login-successful px\_login\_successful\_header\_value: 1 ```javascript const pxConfig = { ... px_login_successful_reporting_method: 'header', px_login_successful_header_name: 'login-successful', px_login_successful_header_value: 'true' ... } ``` **Body** Provide a string or regular expression with which to parse the response body. If a match is found, the login successful status is set to `true`. If no match is found, the login successful status is set to `false`. **Default**: Empty ```javascript const pxConfig = { ... px_login_successful_reporting_method: 'body', px_login_successful_body_regex: 'You logged in successfully!' // string or RegExp ... } ``` **Custom** Provide a custom callback that returns a boolean indicating if the login was successful. **Default**: null ```javascript const pxConfig = { ... px_login_successful_reporting_method: 'custom', px_login_successful_custom_callback: (response) => { return response && response.locals && response.locals.isLoginSuccessful; } ... } ``` ### Raw Username When enabled, the raw username used for logins on login credentials extraction endpoints will be reported to HUMAN if (1) the credentials were identified as compromised, and (2) the login was successful as reported via the property above. **Default**: false ```javascript const pxConfig = { ... px_send_raw_username_on_additional_s2s_activity: true ... } ``` ## Advanced Blocking Response In 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 containing 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: ```json { "appId": String, "jsClientSrc": String, "firstPartyEnabled": Boolean, "vid": String, "uuid": String, "hostUrl": String, "blockScript": String } ``` Once 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. In 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 successfully solved. An example of using the `_pxOnCaptchaSuccess` callback is as follows: ```javascript window._pxOnCaptchaSuccess = function (isValid) { if (isValid) { alert('yay'); } else { alert('nay'); } }; ``` For details on how to create a custom Captcha page, refer to the [documentation](/applications/customize-challenge-page). If you wish to disable this behavior when the Accept header has the value of application/json, set the following configuration: ```javascript const pxConfig = { ... px_advanced_blocking_response_enabled: false ... }; ``` ## Sensitive GraphQL Operations For those using GraphQL endpoints, it is possible to trigger server-to-server risk calls on particular operation types or names. Like the sensitive routes feature, a request that contains an operation of the configured type or name will trigger a server call to HUMAN servers every time that operation is performed. If an operation type (e.g., `query`, `mutation`) is configured in `px_sensitive_graphql_operation_types`, **all** GraphQL operations of that type will be treated as sensitive. If an operation name is configured in `px_sensitive_graphql_operation_names`, all GraphQL operations with that name will be treated as sensitive. > **Note** > > This feature only applies to requests that contain the string `graphql` somewhere in the path name. **Default Values:** px\_sensitive\_graphql\_operation\_types: Empty px\_sensitive\_graphql\_operation\_names: Empty ```javascript const pxConfig = { ... px_sensitive_graphql_operation_types: ["mutation"], px_sensitive_graphql_operation_names: ["LoginOperation", "AccountInfoQuery"] ... }; ``` For those using GraphQL endpoints, it is possible to trigger server-to-server risk calls on particular operation types or names. Like the sensitive routes feature, a request that contains an operation of the configured type or name will trigger a server call to HUMAN servers every time that operation is performed. If an operation type (e.g., `query`, `mutation`) is configured in `px_sensitive_graphql_operation_types`, **all** GraphQL operations of that type will be treated as sensitive. If an operation name is configured in `px_sensitive_graphql_operation_names`, all GraphQL operations with that name will be treated as sensitive. > **Note** > > This feature only applies to requests that contain the string `graphql` somewhere in the path name. **Default Values:** px\_sensitive\_graphql\_operation\_types: Empty px\_sensitive\_graphql\_operation\_names: Empty ```javascript const pxConfig = { ... px_sensitive_graphql_operation_types: ["mutation"], px_sensitive_graphql_operation_names: ["LoginOperation", "AccountInfoQuery"] ... }; ``` ## User Identifiers Enable the extraction of JWT fields from requests and adding them to the risk, page requested and block activities. | Function | Default Value | Description | | ---------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `px_cors_support_enabled` | `false` | Set to `true` to enable CORS support within the HUMAN Enforcer. | | `px_cors_create_custom_block_response_headers` | `null` | Define custom headers that will be added to the block response. This is particularly required for simple CORS requests. If not set, default headers will be used. | | `px_cors_preflight_request_filter_enabled` | `false` | Set to `true` to allow the Enforcer to pass CORS preflight requests to the origin server without blocking. | | `px_cors_custom_preflight_handler` | `null` | Define a custom handler here to handle preflight requests. This allows the Enforcer to respond directly to preflight requests, bypassing the origin server if needed. | Here’s an example of how to configure your Enforcer using these functions: ```javascript const pxConfig = { ... px_cors_support_enabled: true ... }; px_cors_create_custom_block_response_headers: function(request) { return { 'Access-Control-Allow-Origin': request.headers['origin'], 'Access-Control-Allow-Methods': 'GET, POST, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type, Authorization', 'Access-Control-Allow-Credentials': 'true } }; const pxConfig = { ... px_cors_preflight_request_filter_enabled: true ... }; px_cors_custom_preflight_handler: function(request) { const response = { status: '204', }; response.headers = { 'Access-Control-Allow-Origin': request.headers['origin'] || '*', 'Access-Control-Allow-Methods': request.method, 'Access-Control-Allow-Headers': request.headers['access-control-request-headers'], 'Access-Control-Allow-Credentials': 'true', 'Access-Control-Max-Age': '86400', }; return response; }; ```