--- title: Configuration options --- Personally Identifiable Information (PII) is information that can be used on its own or with other information to identify a single person, or to identify an individual in context. It is important for us to keep personal private information out of our servers. Therefore, by default, we do not send the request body and cookies to HUMAN backend servers, the entire communication is based on headers data. PII is not a recommended setting. If PII is essential for your organization, contact [HUMAN Support](/applications/human-customer-support). When PII is enabled, HUMAN does not store a client’s full IP information (Client IP, HTTP Headers). In IPv4 this is done by zeroing 4th IP octet (for example, the IP 1.2.3.4 will be stored as 1.2.3.0). In IPv6 this is done by zeroing the last four (4) octets (for example, the IP 1:2:3:4:1:2:3:4 will be stored as 1:2:3:4:1:2:3:0). Removing the IP's last octet can result small reduction of detection capability, usually for the models and signatures that are based on IPs. ## Module Enabled A boolean flag to enable or disable the HUMAN worker. **Default:** true ## Module Mode Sets the working mode of the Enforcer. **Monitor mode** - Use this mode to fine-tune and test your system. When in the Monitor mode, the Enforcer will pass through requests that would otherwise be blocked based on their score. See [Blocking Score](#blocking-score). **Active Blocking mode** - Switch to this mode after making sure the Enforcer is operating properly in the Monitor mode. The Enforcer will block requests, if their score is equal to or higher than the set value. | Version | Description | |--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 21.0.0 and up | Name: px_module_mode
Values:

monitor — Monitor mode (default)
active_blocking — Active Blocking mode

| | 20.3.1 and below | Name: module_mode
Values:

0 - Monitor mode (default)
1 - Active Blocking mode

| ## Blocking Score Sets the minimum blocking score of a request. Possible values: - Any integer between 0 and 100. **Default:** 100 ## Monitor Specific Routes When in Active Blocking mode, use this feature to define an array of trusted routes to monitor only. The Enforcer treats these routes as if it was in Monitor mode. This means the Enforcer passes requests on these routes that would otherwise be blocked. For more on the difference between the modes, see [Module Mode](#module-mode). This can be useful for testing. For example, you can put newly introduced routes in the Monitor mode to fine-tune them while continuing to actively protect the rest of your assets. If you want certain paths to completely bypass the Enforcer instead, see [Path Whitelist](#path-whitelist) instead. **Default:** Empty | Version | Description | |-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 22.0.0 and up | Routes should be configured as a single regular expression (PCRE). For case-insensitive matching, the regex should end with the `i` flag.
Example: `/^(./category/?.)\|(./product/?.)$/i` | | 21.0.0 and up | Use commas to separate between monitored routes in the string.
Example: `/profile,/test,/login` | ## Monitor Specific Routes Regex (deprecated) This feature was removed in v22.0.0. Use [Monitor Specific Routes](#monitor-specific-routes) instead. This feature is still available for v21.0.0 and up. When in the Active Blocking mode, use this feature to define regular expressions of trusted routes to be monitored only. Such routes will be treated, as if the Enforcer were in the Monitor mode. For example, you can put newly introduced routes in the Monitor mode to fine-tune them, while continuing to actively protect the rest of your assets. For more on the difference between the modes, see [Module Mode](#module-mode). **Default:** Empty Use commas to separate between regular expressions in the string: /^profile.?,/login.\* ## Enforced Specific Routes You may want certain requests to be enforced by HUMAN, even when the Enforcer is in the Monitor mode. Requests for predefined route prefixes will go through the full enforcement workflow, and may be blocked based on their score. **Default:** Empty | Version | Description | |-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 22.0.0 and up | Routes should be configured as a single regular expression (PCRE). For case-insensitive matching, the regex should end with the `i` flag. Example: `/^(./category/?.)\|(./product/?.)$/i` | | 21.0.0 and up | Use commas to separate between monitored routes in the string. Example: `/profile,/test,/login` | ## Enforce Specific Routes Regex (deprecated) This feature was removed in v22.0.0. Use [Enforced Specific Routes](#enforced-specific-routes) instead. This feature is still available for v21.0.0 and up. You may want certain requests to be enforced by HUMAN, even when the Enforcer is in the Monitor mode. Requests for predefined regular expressions will go through the full enforcement workflow, and may be blocked based on their score. **Default:** Empty Use commas to separate between regular expressions in the string: `/^profile.? , /login.\*` ## User ID Retrieval Allows retrieving user IDs from the SalesForce database using an API. Enable this feature, if you are using HUMAN Account Defender. **Default:** Disabled ## First Party Enabled Enables the module to send/receive data to/from the sensor, acting as a "reverse-proxy" for client requests and sensor activities. To setup first party support, follow the [Setting Up First Party](/applications/sfcc-first-party) section. First Party Mode may also require additional changes on the sensor snippet. For more information, refer to the portal. Possible values: - `true` - `false` **Default:** `false` ## Send Block Activities A boolean flag to enable/disable sending block activities to HUMAN with each request. **Default:** true ## Send Page Activities A boolean flag to enable/disable sending activities and metrics to HUMAN for each page request. Enabling this feature provides data that populates the HUMAN portal with valuable information such as the number of requests blocked and API usage statistics. **Default:** true ## Logger Severity Sets the Logger Severity mode of the Enforcer. | Version | Description | |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 21.0.0 and up | Name: px_logger_severity
Values:

error (default) - The Enforcer logs only errors and fatal events (for example, exceptions).
debug - The Enforcer logs all debugging events.

| | 20.3.1 and below | Name: debug_mode
Values:

false (default) - The Enforcer logs only errors and fatal events (for example, exceptions).
true - The Enforcer logs all debugging events.

| Once enabled, HUMAN debug messages are sent in the following template: `[PerimeterX - DEBUG][APP_ID] - MESSAGE` - for debug messages `[PerimeterX - ERROR][APP_ID] - MESSAGE` - for error messages Log example of a valid request: ``` [2017-12-04 14:02:48.170 GMT] DEBUG PipelineCallServlet|9502992|Sites-SiteGenesis-Site|Default-Start|PipelineCall|jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== custom Sites-SiteGenesis-Site STOREFRONT jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== k1OX8IhVJVpqAAAK-0-00 9135655695325170688 - [PerimeterX - DEBUG][APP_ID] - Starting request verification [2017-12-04 14:02:48.171 GMT] DEBUG PipelineCallServlet|9502992|Sites-SiteGenesis-Site|Default-Start|PipelineCall|jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== custom Sites-SiteGenesis-Site STOREFRONT jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== k1OX8IhVJVpqAAAK-0-00 9135655695325170688 - [PerimeterX - DEBUG][APP_ID] - Request context created successfully [2017-12-04 14:02:48.171 GMT] DEBUG PipelineCallServlet|9502992|Sites-SiteGenesis-Site|Default-Start|PipelineCall|jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== custom Sites-SiteGenesis-Site STOREFRONT jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== k1OX8IhVJVpqAAAK-0-00 9135655695325170688 - [PerimeterX - DEBUG][APP_ID] - No Captcha cookie present on the request [2017-12-04 14:02:48.171 GMT] DEBUG PipelineCallServlet|9502992|Sites-SiteGenesis-Site|Default-Start|PipelineCall|jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== custom Sites-SiteGenesis-Site STOREFRONT jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== k1OX8IhVJVpqAAAK-0-00 9135655695325170688 - [PerimeterX - DEBUG][APP_ID] - Cookie V3 found, Evaluating [2017-12-04 14:02:48.394 GMT] DEBUG PipelineCallServlet|9502992|Sites-SiteGenesis-Site|Default-Start|PipelineCall|jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== custom Sites-SiteGenesis-Site STOREFRONT jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== k1OX8IhVJVpqAAAK-0-00 9135655695325170688 - [PerimeterX - DEBUG][APP_ID] - Cookie evaluation ended successfully, risk score: 0 ``` ## Sensitive Routes Routes that trigger a server call to HUMAN servers every time the page is viewed, regardless of viewing history. Sensitive routes refer to routes that may be more prone to bot attacks than others such as routes that execute payments or handle personal information. You can configure these routes as sensitive for more stringent protection. | Version | Description | |-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 22.0.0 and up | Routes should be configured as a single regular expression (PCRE). For case-insensitive matching, the regex should end with the `i` flag.
Example: `/^(./category/?.)|(./product/?.)$/i` | | 21.4.3 and below| A comma separated list of route prefixes | **Default:** Empty ## Sensitive Headers A comma separated list of headers that are not sent to HUMAN servers on API calls. **Default:** 'cookie', 'cookies' ## Path Whitelist Filters out requests based on their route. A request to a filtered route will not be enforced or blocked and will not generate any risk or async activities. Routes should be configured as a single regular expression (PCRE). For case-insensitive matching, the regex should end with the i flag. Default: Empty | Version | Description | |-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | 22.0.0 and up | Routes should be configured as a single regular expression (PCRE). For case-insensitive matching, the regex should end with the `i` flag.
Example: `/^(./allowed_route/?.)|(./filtered_route/?.)$/i` | | 21.4.3 and below| A comma separated list of paths to filter.
Example: `/Sites-Site/, /PXRedirect` | **Default:** Empty ## Allow by IP/CIDR A comma separated list of IPs or CIDRs to allow. For example: `192.168.0.100, 192.168.100.0/24` **Default:** Empty ## IP Headers A comma separated list of comma separated trusted headers that specify an IP to be extracted. If the list is empty, the default IP header `cf-connecting-ip` is used. **Default:** Empty ## SCAPI Custom Header Name When using [SCAPI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html) (for example, PWA Kit or Composable Storefront), the cartridge does not receive the original client request headers and cookies. To pass these through, use a proxy to send these original headers (for example, as a comma-separated key-value list) and set this configuration option to the name of that custom header. Alternatively, you can send individual original headers with names prefixed by `c_px-`. The cartridge will extract and use those as well. For more on SCAPI header limitations and alternative protection options, such as using an Enforcer on a proxy or CDN in front of SCAPI, see [SCAPI Protection Considerations](/applications/salesforce-commerce-cloud-cartridge/scapi-protection-considerations). **Default:** Empty ## CSS Ref Modifies a custom CSS by adding the CSSRef directive and providing a valid URL to the CSS. **Default:** Empty ## 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 ## Custom Logo The logo is displayed at the top of the block page. Max-height = 150px, Width = auto. **Default:** Empty ## Custom Block Page Template The template name to use to render a block page. **Default:** block\_template (the default block page template) If you want to customize the Block page, follow the instructions on this page [Customized Block Page](/applications/salesforce-commerce-cloud-cartridge/customized-block-page). ## Enrich Custom Parameters ### v22.0.0 and up This custom function enriches activities sent from the Enforcer to HUMAN with additional custom data. This data can include user information, session IDs, or other data that HUMAN should have access to. These custom parameters are defined by a configurable function that must return an object that contains these custom parameters. There is a limit of 10 custom parameters. This property cannot be set using Business Manager and can only be added directly to the cartridge files. To implement the handler, edit the pxCustomFunctionsConfig.js file located at: `/int_perimeterx/cartridge/scripts/config`. 1. Uncomment the `enrichCustomParameters` function. 2. Also uncomment the `corresponding module.exports` line that exports the function. 3. Add your custom logic inside the function. **Parameters:** - `customParameters` — An object that contains the custom parameters to be sent to HUMAN **Returns:** the custom parameters object ```javascript v22.0.0 and up function enrichCustomParameters(customParameters) { customParams["custom_param1"] = "test value"; customParams["custom_param1"] = "second value"; return customParameters; } ``` ### v21.4.3 and below The function should be added directly to the `pxConfig.js` file. **Default:** Empty ```javascript v21.4.3 and below pxConfig["enrichCustomParameters"] = function(customParams) { customParams["custom_param1"] = "yay, test value"; return customParams; } module.exports = { enrichCustomParameters: enrichCustomParameters }; ``` ## Additional Activity Handler Only available for v22.0.0 and up The additional activity handler is a custom function passed to the Enforcer. The Enforcer runs this callback just before sending page_requested or block activity to the collector, then forwards the request to the next step in the pipeline. A common use case is to set the score as a variable on the session object. Then, the application can read the score and do what is defined within the application's logic. This property cannot be set using Business Manager and can only be added directly to the cartridge files. To implement the handler, edit the pxCustomFunctionsConfig.js file located at: `/int_perimeterx/cartridge/scripts/config`. 1. Uncomment the `additionalActivityHandler` function. 2. Also uncomment the corresponding `module.exports` line that exports the function. 3. Add your custom logic inside the function. **Parameters:** - `config`: Human configuration - `pxContext`: The context object **Returns:** void ```javascript function additionalActivityHandler(pxContext, config) { // Custom logic here // For example, set the score as a variable on the session session.privacy.PXCompromised = pxContext.score; } module.exports = { additionalActivityHandler: additionalActivityHandler, }; ``` ### Custom Is Sensitive Request This configuration is meant for cases that require more complex custom logic. It is recommended to use the `px_sensitive_routes` configuration for simpler cases. Only available for v22.1.0 and up Requests can be configured as sensitive, meaning risk API calls will be made even if the request contains a valid, unexpired cookie. This configurable function provides a way to define which requests should be considered sensitive based on custom logic. The function returns a boolean indicating whether the request should be considered sensitive or not. This property cannot be set using Business Manager and can only be added directly to the cartridge files. To implement the handler, edit the pxCustomFunctionsConfig.js file located at: `/int_perimeterx/cartridge/scripts/config`. 1. Uncomment the `customIsSensitiveRequest` function. 2. Also uncomment the corresponding `module.exports` line that exports the function. 3. Add your custom logic inside the function. **Parameters:** None **Default**: `null` ```javascript function customIsSensitiveRequest() { // Implement your logic to determine if a risk API call should be called. // Return true if the request is sensitive, false otherwise. // Example: return request.getHttpMethod() === 'POST' || request.getHttpMethod() === 'PUT'; } module.exports = { customIsSensitiveRequest: customIsSensitiveRequest, }; ``` ## 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 `Bypass Monitor Mode Header` property. **Default:** Empty ## Credentials Intelligence The Credentials Intelligence feature allows you to safeguard your users login information by leveraging HUMAN's database of compromised credentials. **TO enable this feature:** 1. Change the `PX_loginCredentialsExtractionEnabled` value to `true`. Default: `false` 2. In `PX_loginCredentialsExtraction`, add unique login extraction paths by defining an array of credential extraction definition objects. Each of these represents a particular type of request, from which to extract credentials. You need to define the following fields: | Field | Supported Values | | -------------- | -------------------------------- | | `path` | Any string. Must start with `/`. | | `method` | `get`, `post`, `put` | | `sent_through` | `body`, `header`, `query-param` | | `path_type` | `regex`, `exact` | | `user_field` | Any string | | `pass_field` | Any string | Below is an example of a valid array that lists three different login endpoints, from which credentials should be extracted: ```json [{ "method": "get", "path_type": "exact", "path": "/login/query", "sent_through": "query-param", "pass_field": "password", "user_field": "username" }, { "method": "post", "path_type": "exact", "path": "/login-nested-object", "sent_through": "body", "pass_field": "nested.password", "user_field": "nested.username" }, { "method": "post", "path_type": "regex", "path": "^/user/[A-Za-z0-9]{8,12}/session$", "sent_through": "body", "pass_field": "password", "user_field": "username" }] ``` 3. In `PX_ciVersion`, select either the single step (`v2`), or multi-step login (`multistep_sso`). Default: `v2`. 4. In `PX_sendRawUsernameOnAdditionalS2SActivity`, select whether the original username used for the login attempt should be sent to HUMAN to aid in detection. Default: `false`. **Additional S2S Activity** To enhance detection on login credentials extraction endpoints, the following additional information is sent to HUMAN via an additional\_s2s activity: Login Success - A boolean flag indicating whether the login attempt was successful. To allow HUMAN to send this activity, add the following to your code, and pass an object that contains the login success indication and the status code as a parameter: ```javascript var HookManager = require('dw/system/HookMgr'); HookManager.callHook('app.scripts.additionalS2SHandling', 'additionalS2SHandling', { login_successful: , status_code: }); ``` If the request contains credentials, the variable `session.private.PXCompromised` will be populated after enforcement with a boolean flag indicating whether the credentials are compromised.