About Enforcers

The HUMAN Enforcer is a lightweight SDK that’s responsible for the enforcement functionality in HUMAN Applications Protection products. After the HUMAN Sensor collects and analyzes user signals on your application, it sends a cookie with a risk score to the Enforcer. Based on this score, the Enforcer decides whether to allow or block the request. The Enforcer also asynchronously reports its decision to the HUMAN Detector so that our model can continuously improve.

Generally, the Enforcer is installed server-side on your CDN, load balancer, or at the origin, but this may vary depending on your use case. Refer to our supported frameworks for more information.

Supported frameworks

Required configurations

Typically, you’ll integrate an Enforcer during your onboarding with help from a dedicated Solutions Engineer. Each Enforcer framework has different deployment steps and customizable configurations to best suit your environment, so we recommend referring to your specific framework’s documentation for detailed information. However, we generally encourage including the following configurations for minimum enforcement and reporting functionality across all Enforcers:

Risk Cookie behavior

The Risk Cookie is the cookie with the risk score that’s sent by the Sensor. Depending on the score, the Enforcer will block or pass the request. HUMAN uses two versions of the Risk Cookie: the v2 (_px2) and v3 (_px3). Each Enforcer may support one or both of these cookies. Be sure to refer to each Enforcer’s configuration documentation for more information.

Cookie v3

The v3 Risk Cookie (_px3) is the latest version of the Risk Cookie. We strongly recommend your Enforcer uses the v3 cookie whenever possible. This is because the v3 cookie sends an encrypted payload with more robust information about the request compared to the v2:

1
{	
2
    "u": <uuid>, 
3
    "v": <vid>,
4
    "t": <timestamp>,
5
    "a": <action>,
6
    "s": <score>,
7
    "x": <cookieSigningFields>    
8
}

In particular, the score (s) is a number from 0-100 assigned by the HUMAN Detector based on how risky it determined the request to be. Based on this scale, the Enforcer passes or blocks the request.

Cookie v2

The v2 Risk Cookie (_px2) is a base64 encoded string with the following payload:

1
{
2
    "h": <hmac>,
3
    "u": <uuid>,
4
    "t": <timestamp>,
5
    "v": <vid>
6
}

To determine whether a request should be blocked or not, the HUMAN Detector signs the v2 cookie’s HMAC value with an additional string of either ”1” (block) or ”0” (pass). This means that v2 uses binary decisioning when blocking.

V2 Risk Cookie Enforcer support

The following Enforcers only support the v2 Risk Cookie. All other Enforcer frameworks support the v3 cookie or both versions.

• Akamai ESI
• Akamai EdgeWorker
• Apigee
• Edgio Edge Functions
• F5 BIG-IP
• Fastly JavaScript Compute@Edge
• Fastly VCL

Hostnames

All Enforcers use the following hostnames:

• Risk API: sapi-<appid>.perimeterx.net
• Asynchronous activities: collector-<appid>.perimeterx.net
• First-party routes:
  • Client: client.perimeterx.net
  • CAPTCHA: captcha.px-cdn.net
  • Alternative CAPTCHA: captcha.px-cloud.net

API IPs

The Enforcer accesses the Risk API via a set of pre-provisioned IP addresses from the various points of presence HUMAN has around the globe. These IP addresses are updated from time to time for availability and latency optimization. While this isn’t a requirement, you may choose to maintain a list of these as allowed IP addresses as part of your firewall rules to allow access from your infrastructure to our API servers. Click here for a list of our current IPs.

If you use the first-party snippet delivery, which pulls our snippet and delivers it through the your domain, then we recommend referencing your framework’s official documentation on how to also allow the snippet CDN IPs.

Block response types

When the Enforcer blocks a request, it may return one of the following response types:

• For mobile requests, the Enforcer returns a mobile-specific response. See our Mobile SDK documentation for more information.
• If the Advanced Blocking Response (ABR) (px_advanced_blocking_response_enabled) configuration is enabled, the Enforcer returns a unique Advanced Blocking Response. Not all Enforcers may support ABR. Be sure to reference your specific framework’s documentation for more information.
• Otherwise, the Enforcer returns a standard HTTP/HTTPS response code:
  • 403 Forbidden: This is returned in two distinct scenarios:
    • When the Enforcer shows a challenge to the request, such as the HUMAN Challenge or the Precheck interstitial. In this case, the Enforcer also returns a JSON or HTML block payload that instructs the client to show the appropriate challenge.
    • When the Enforcer shows a hard block page without a challenge that cannot be passed.
  • 429 Too Many Requests: This is returned when the Enforcer shows a block page with a rate limit response code.