Installing the Enforcer

Enable PerimeterX Support with Fastly

The PerimeterX Fastly Enforcer requires advanced functionality from Fastly. This must be enabled by the Fastly support team before the Enforcer can be activated.

To enable the advanced Fastly functionality, e-mail [email protected] as follows:

  • Subject: “Please enable PerimeterX support for our Fastly service ID
  • Body: Hi Fastly Support, Please enable PerimeterX support for our service ID and confirm when it is completed.

You must request to enable functionality for each service ID that is being protected by PerimeterX.

Setting the Binary Block Result Cookie

In order to use Fastly integration, a binary block result cookie must be defined in the PerimeterX 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.

📘

Important Note.

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

Manual installation

33603360

Customize Custom VCL Files and snippets

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

Logging

  • PX-Syslog - To send the required Logs to PerimeterX syslog servers the PX-Syslog must be defined.
    Use the following settings to defined your syslog:
    • Name: PX-Syslog
    • Address: px-fst-syslog.perimeterx.net : 6514
    • Use TLS: Yes
    • All other fields: No change is needed, use the default values.

Adding a Syslog

Fastly Web Interface:
Add a syslog log endpoint - log-streaming-syslog

adding syslog

Fastly API:
Add a syslog log endpoint - create-log-syslog
Use the following Json:

{
    "name": "PX-Syslog",
    "hostname": "px-fst-syslog.perimeterx.net",
    "address": "px-fst-syslog.perimeterx.net",
    "use_tls": "1",
    "port": "6514",
    "response_condition": "PX-Syslog-Condition"
}

Once the PX-Syslog is defined, you must create a new request condition to prevent the Syslog from sending every request automatically. To do this, the request condition must be defined as neverTrue:

  1. Click Attach a condition next to PX-Syslog.
  2. Click Create a New Response Condition.
  3. Name the condition NeverTrue
  4. Apply if... req.url == "neverTrue"
  5. Under Advanced option, set the priority to 10.

See the Fastly Conditions Documentation for more details.

Adding Conditions

Fastly Web Interface:

adding condition

Fastly API:
Create a syslog log endpoint - create-condition
Use the following JSON:

{
    "name": "PX-Syslog-Condition",
    "comment": "Condition to prevent duplicate logs",
    "priority": "10",
    "type": "response",
    "statement": "req.url == \"neverTrue\""
}

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.

{
    "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\" && req.http.X-PX-validated-request == \"1\"));",
    "priority": "1"
}

Uploading the VCL files

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

The PerimeterX 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 PerimeterX.
  • PX.vcl - VCL name: "PX" - Contains all the internal PerimeterX 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

PerimeterX 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 PerimeterX 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

🚧

PerimeterX Error codes

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

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

Did this page help you?