Installing the Enforcer

Prerequisites

In order to enable the HUMAN support on your Fastly service, the HUMAN Fastly Enforcer requires advanced functionality from Fastly.

Send the following e-mail to support@fastly.com:

• Subject: “Please enable HUMAN support for our Fastly service ID ”
• Body: Please enable HUMAN support for our service ID and confirm when it is completed.

Once Fastly enables HUMAN support, the following pragmas should be enabled at your service:

fix_unsent_body_drain - pragma that can be used in VCL to resolve an issue with HTTP response bodies not being fully sent to the client.

no_body_if_bereq_is_get_or_head - pragma that can be used in VCL to prevent a response body from being sent to the client if the request method is GET or HEAD.

You must request to enable functionality for each service ID that is being protected by Bot Defender. If this functionality is not enabled, requests will fail with a "503 service unavailable" error.

Setting the Binary Block Result Cookie

In order to use Fastly integration, a binary block result cookie must be defined in the HUMAN Portal:

1. Go to Admin > Policies, and select the policy.
2. In the Risk Cookie tab, select Advanced Mode, and click Continue in the pop-up.
3. Select the Cookie Version (V2), set the Binary Score/Threshold Score (100), and the Validity as appropriate.
4. Click Apply.

Manual installation

Customize Custom VCL Files and snippets

Your current VCL Files and snippets must be reviewed by a HUMAN Solution Architect.
Contact your HUMAN Solution Architect or HUMAN Support for more information.

Logging

To report on requests for detection, the Enforcer logs each request and sends it to HUMAN. The followinghttps loggersmust be configured to enable this functionality:

• PX-Async-Activities - To send async activities like Page requested, Block, etc to HUMAN's servers.
  Use the following settings to define your logger:
  • Name: PX-Async-Activities
  • URL: https://fastly-async.perimeterx.com/api/v1/collector/s2s
  • Placement: none
  • Advanced options
    
    • Content type - application/json
    • JSON log entry format - Array of JSON
  • All other fields: No change is needed, use the default values.
• PX-Telemetry - This will enable Telemetry feature which can send data about the enforcer configuration to Human Security.
  Use the following settings to define your logger:
  • Name: PX-Telemetry
  • URL: https://fastly-async.perimeterx.com/api/v2/risk/telemetry
  • Placement: none
  • Maximum Logs: 1
  • Advanced options
    
    • Content type - application/json
  • All other fields: No change is needed, use the default values.

Adding the Loggers

Fastly Web Interface:
Add https log endpoints - log-streaming-https

Fastly API:
Add https log endpoints - create-log-https
Use the following Jsons:

{
  "content_type": "application/json",
  "json_format": "1",
  "name": "PX-Async-Activities",
  "placement": "none",
  "url": "https://fastly-async.perimeterx.com/api/v1/collector/s2s"
}

{
  "content_type": "application/json",
  "json_format": "0",
  "name": "PX-Telemetry",
  "placement": "none",
  "url": "https://fastly-async.perimeterx.com/api/v2/risk/telemetry",
  "request_max_entries": 1
}

Adding a New WAF Disablement Condition (Optional)

In order to address a potential issue that may arise from running WAF rules multiple times due to an Enforcer restart request, we recommend adding a new condition to the Fastly service. This condition is specifically designed for customers who have enabled Fastly WAF but have not implemented the WAF prefetch condition.

Add the following condition to the Fastly service configuration:

{
    "name": "PX-Waf-Prefetch-Condition",
    "comment": "Condition to prevent duplicate activations of the WAF",
    "priority": "10",
    "type": "PREFETCH",
    "statement": "req.backend.is_origin && !req.http.bypasswaf"
}

This condition will effectively prevent the duplication of WAF activations and ensure a smoother operation of the integration.

Loggings endpoints (Optional):

• PX-Debug - Optional debug logging endpoint.
  Define this endpoint to use debug_severity = "debug".
• PX-Error - Optional error logging endpoint.
  Define this endpoint to use debug_severity = "error".

To define a logging endpoint - See the Fastly Logging Documentation

Uploading the VCL snippets

For complete Integration of the Enforcer, it is required to add the following snippets to the Fastly service.

• px_shield - VCL snippet to enable Fastly shielding during and after requests validation flow.
  More on Fastly shielding:
  https://docs.fastly.com/en/guides/shielding

{
    "name": "px_shield",
    "dynamic": "0",
    "type": "recv",
    "content": "set var.fastly_req_do_shield = (req.restarts == 0 || (req.restarts == 1 && req.http.X-PX-internal-flow == \"1\"));",
    "priority": "1"
}

Uploading the VCL files

Basic configuration changes to your VCL are require before uploading the VCL.

The HUMAN Fastly VCL Enforcer consists of 4 VCL files which need to be uploaded to your service. Select main.vcl as the main VCL.
(This will happen automatically if main.vcl is the first VCL uploaded).
please note: VCL object names are case sensitive.

• main.vcl - VCL name: "MAIN" - Default Fastly's VCL, customized with additional code snippets of HUMAN.
• PX.vcl - VCL name: "PX" - Contains all the internalHUMAN core logic.
• px_configs.vcl - VCL name: "PX_CONFIGS" - Contains Enforcer configuration table and additional backends configs.
• px_custom.vcl - VCL name: "PX_CUSTOM" - Contains Enforcer custom code, defined custom behavior and enforcer features.

To upload the VCLs:

Fastly Web Interface:

1. Click Upload Your First VLC File.
2. Name the VCL file MAIN. This ensures that main.vcl is your main VCL.
3. Upload the corresponding VCL file.
4. Click Create.
5. Click +Upload a New VCL File, and repeat the process for the remaining three VCL files, naming the files according to the list above.

Fastly Web Interface:
Please review: vcl-services

Fastly allows you to create your own VCL files with specialized configurations.
By default, the ability to upload custom VCL code is disabled when you sign up.
Contact support@fastly.com to upload your custom VCL code.

After completing configure the Enforcer visit Configuration Options section,
upload the finalized HUMAN VCL files, according to the Fastly documentation for uploading custom VCLs, including last section for multiple VCLs

Error Codes