Product guides

Installing the Enforcer

Suggest Edits

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 [email protected]:

  • 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.

📘

TEST

To check that the required pragmas are enabled, open the VCL file and look for the following lines at the pragmas section at the top of the file:

pragma optional_param fix_unsent_body_drain true;

pragma optional_param no_body_if_bereq_is_get_or_head true;

If fix_unsent_body_drain and no_body_if_bereq_is_get_or_head pragmas are not there - HUMAN isn’t enabled at your service.

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.

🚧

Note

Automatic installation of the Fastly enforcer will be available soon on HUMAN portal. This will be supported from Fastly v8.0.0 and above.

Manual installation

3360

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:
  • 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:

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 px_logger_severity = "debug".
  • PX-Error - Optional error logging endpoint.
    Define this endpoint to use px_logger_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.

{
    "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.

🚧

Modifying MAIN.vcl file

This file serves solely as an example of how to integrate HUMAN Security subroutine calls into your code.
HUMAN Security does not edit or modify this file during upgrades.
HUMAN subroutine calls must be the first call in each subroutine on MAIN vcl.

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 [email protected] 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

📘

Note

You must activate your service version after every change performed to the VCL.

Error Codes

🚧

Error codes

HUMAN Enforcer uses its own VCL error codes.
The following Error codes should remain unused by other VCL applications.
Using any of the following codes in other applications may lead to unexpected behavior.

  • 991first_party_disabled
  • 992first_party_xhr_disabled
  • 995exceeded_rate_limit, s2s_high_score, cookie_high_score
  • 996cookie_high_score

Updated 12 days ago