> 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 Reference ## Overview All HUMAN enforcer configuration is stored in a data group named `pxconfig`. Configuration values are read from this data group at runtime. ### Modifying Configuration To modify a configuration value, use the following command on the F5 shell: ```bash modify /ltm data-group internal pxconfig records modify { KEY_NAME { data VALUE } } ``` Where: * `KEY_NAME` is the name of the configuration directive * `VALUE` is the value to set **Example:** Enable blocking mode: ```bash modify /ltm data-group internal pxconfig records modify { module_mode { data 2 } } ``` **Example:** Set a custom IP header: ```bash modify /ltm data-group internal pxconfig records modify { ip_header { data X-Forwarded-For } } ``` ## Directives | Directive | Description | Default | Value | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------- | ------ | | app_id | HUMAN application id | NONE | String | | cookie_secret_key | Cookie hashing secret (salt) | NONE | String | | auth_token | JWT used to authenticate with px servers | NONE | String | | enable_module | Sets the module on/off | 1 | int | | module_mode | Sets the module working mode: `2` = blocking, `1` = sync monitor, `0` = async monitor | 1 | int | | whitelisted_routes_class | Name of the class for allowlist routes | px\_\\_whitelisted_routes | String | | whitelisted_query_params_class | Name of the class for allowlist query parameters | px\_\\_whitelisted_query_params | String | | specific_routes_class | Name of the class for specific routes | px\_\\_specific_routes | String | | sensitive_routes_class | Name of the class for sensitive routes | px\_\\_sensitive_routes | String | | monitor_routes_class | Name of the class for monitor routes (domain/path based monitor mode) | px\_\\_monitor_routes | String | | send_page_activities | Toggles send page requested activity | 0 | int | | send_block_activities | Toggles send block activities | 1 | int | | excluded_extensions | Flags which extensions the module will skip | regex String | String | | risk_vs | Correlates with the virtual server for making risk api calls | px_backend\_\\_vip | String | | risk_timeout | Sets the timeout for api calls (in milliseconds) | 2500 | int | | debug | Toggles debug mode on/off, see troubleshooting for more information | 0 | int | | ip_header | Custom user header that contains real user ip | NONE | String | | sensitive_headers | List of sensitive headers not to send in risk api calls | \["cookie"] | list | | custom_logo | Path to url that contains a logo to be displayed on default block page | NONE | String | | js_ref | Path to url that contains a custom js file to inject into the default block page | NONE | String | | css_ref | Path to url that contains a custom css file to inject into the default block page | NONE | String | | allowed_domains | A list of domain names on which the enforcer will run on. Run on all if blank | \[""] | list | | enable_module_header_name | The header name that should be used to enable the module (The header's value should be `True`) | NONE | String | | whitelist_ips | A list of ips/CIDRs to allow. If empty all the requests will be processed. | \[""] | list | | bypass_monitor_header | The header name that can be used to bypass monitor mode on blocking activities. | NONE | String | | enable_advanced_blocking_response | Toggles the use of advanced blocking response | 1 | int | | custom_cookie_header | A header name which will be used to extract the HUMAN cookie from. | NONE | String | | enable_first_party | Toggles first-party mode on/off. | 1 | int | | enable_sensor_injection | Toggles automatic JavaScript sensor injection on/off | 0 | int | | enable_score_header | Toggles sending the risk score to origin via `x-px-score` header | 0 | int | | px_data_enrichment_header_name | Header name to use for sending PXDE (data enrichment) payload to origin | NONE | String | | ci_login_credentials_extraction_enabled | Enables/disables login credentials extraction. `1` = enabled, `0` = disabled | 0 | int | | ci_login_credentials_extraction_class | Name of the data group class containing login endpoint configuration | (empty) | String | | ci_credentials_intelligence_version | CI protocol version. `v2` for standard login, `multistep_sso` for multi-step SSO | v2 | String | | ci_compromised_credentials_header | Header name for sending compromised credentials result to origin | x-px-compromised-credentials | String | | ci_additional_s2s_activity_header_enabled | When `1`, origin forwards activity. When `0`, enforcer sends via syslog | 0 | int | | ci_send_raw_username_on_additional_s2s_activity | When `1`, includes raw username in additional S2S activity | 0 | int | | ci_login_successful_reporting_method | Method to determine login success: `header` or `status`. Empty to disable | (empty) | String | | ci_login_successful_header_name | Response header name to check for login success (when method is `header`) | (empty) | String | | ci_login_successful_header_value | Response header value indicating successful login (when method is `header`) | (empty) | String | | ci_login_successful_status | HTTP status code indicating successful login (when method is `status`) | 200 | String | ## Directives containing APP_ID Some directives in the configuration may require a specific name which contains the appID of the application taken from the portal. The name in the configuration must be identical to the name configured in the data group/virtual server/pool. A mismatch in the name may lead to errors on the module. ## Configuration Examples ### Enable Blocking Mode ```bash modify /ltm data-group internal pxconfig records modify { module_mode { data 2 } } ``` ### Enable Sensor Injection When enabled, the iRule will automatically inject the HUMAN JavaScript sensor into HTML pages: ```bash modify /ltm data-group internal pxconfig records modify { enable_sensor_injection { data 1 } } ``` > **Note** > > When sensor injection is enabled, the iRule will remove the `Accept-Encoding` header from incoming requests so the origin will NOT return compressed content. Make sure to enable compression on the LTM level if you use script injection. ### Enable Score Header Send the risk score to your origin server for custom handling: ```bash modify /ltm data-group internal pxconfig records modify { enable_score_header { data 1 } } ``` This will add an `x-px-score` header to requests forwarded to your origin. ### Enable Data Enrichment Header Send the PXDE (PerimeterX Data Enrichment) payload to your origin: ```bash modify /ltm data-group internal pxconfig records modify { px_data_enrichment_header_name { data x-px-data-enrichment } } ``` ### Set Custom IP Header If your application is behind a proxy or CDN, specify the header containing the real client IP: ```bash modify /ltm data-group internal pxconfig records modify { ip_header { data X-Real-IP } } ``` ### Enable Debug Logging For troubleshooting, enable debug logging: ```bash modify /ltm data-group internal pxconfig records modify { debug { data 1 } } ``` > **Note** > > Remember to disable debug logging in production as it can impact performance. ## Credential Intelligence The Credential Intelligence feature extracts credentials (hashed username and password) from login requests and sends them to HUMAN as additional info in the Risk API call. If credentials are found to be compromised, the enforcer can notify your origin via a header. > **Note** > > Credential Intelligence must be enabled in your HUMAN Console before configuring the enforcer. Contact your HUMAN representative for access. ### Enable Credential Intelligence To enable Credential Intelligence, configure the following in the `pxconfig` data group: ```bash # Enable the feature modify /ltm data-group internal pxconfig records modify { ci_login_credentials_extraction_enabled { data 1 } } # Set the login credentials extraction class name modify /ltm data-group internal pxconfig records modify { ci_login_credentials_extraction_class { data px_login_credentials } } ``` ### Configure Protocol Version Choose the appropriate protocol version for your login flow: **Standard Login (v2)** - Username and password are submitted in a single request: ```bash modify /ltm data-group internal pxconfig records modify { ci_credentials_intelligence_version { data v2 } } ``` **Multi-Step SSO (multistep_sso)** - Username and password are submitted in separate requests: ```bash modify /ltm data-group internal pxconfig records modify { ci_credentials_intelligence_version { data multistep_sso } } ``` > **Note** > > For multi-step SSO, configure your extraction class with a path pattern that matches both login steps. On each step, only the username OR password will be present, and the enforcer will detect which field is available. ### Configure Compromised Credentials Header When credentials are checked, the enforcer adds a header to the request with the result: ```bash modify /ltm data-group internal pxconfig records modify { ci_compromised_credentials_header { data x-px-compromised-credentials } } ``` The header value will be `0` (not compromised) or `1` (compromised), based on the HUMAN Risk API response. > **Note** > > The header is only added when Credential Intelligence is enabled and the Risk API returns data enrichment information. ### Configure Login Success Reporting To report whether login attempts were successful, configure one of the following methods: **Status-Based Reporting** - Determine success based on HTTP response status code: ```bash modify /ltm data-group internal pxconfig records modify { ci_login_successful_reporting_method { data status } } modify /ltm data-group internal pxconfig records modify { ci_login_successful_status { data 200 } } ``` **Header-Based Reporting** - Determine success based on a response header: ```bash modify /ltm data-group internal pxconfig records modify { ci_login_successful_reporting_method { data header } } modify /ltm data-group internal pxconfig records modify { ci_login_successful_header_name { data x-login-success } } modify /ltm data-group internal pxconfig records modify { ci_login_successful_header_value { data true } } ``` ### Configure Additional S2S Activity Additional S2S activity sends enhanced login attempt data to HUMAN, including response code, login success status, and optionally the raw username. **Method 1: Origin Forwards Activity (Header-Based)** The enforcer adds activity data as headers for your origin to forward to HUMAN: ```bash modify /ltm data-group internal pxconfig records modify { ci_additional_s2s_activity_header_enabled { data 1 } } ``` When enabled, the enforcer adds: * `px-additional-activity` - JSON containing the activity data * `px-additional-activity-url` - The HUMAN endpoint URL to forward the data to Your origin is responsible for forwarding this data to HUMAN. **Method 2: Enforcer Sends Directly (Default)** When `ci_additional_s2s_activity_header_enabled` is `0`, the enforcer sends the additional S2S activity directly via syslog during the HTTP response phase. ### Include Raw Username in Additional S2S Activity To include the raw (unhashed) username in the additional S2S activity: ```bash modify /ltm data-group internal pxconfig records modify { ci_send_raw_username_on_additional_s2s_activity { data 1 } } ``` > **Note** > > The raw username is only included when credentials were successfully extracted from the request.