Upgrade to Fastly VCL v10

Upgrade to HUMAN's Fastly VCL Enforcer Version 10

Before We Start

The HUMAN Fastly VCL Enforcer consists of a number of different components: VCL files, snippets, and logging endpoints. The majority of the Fastly VCL enforcer logic is housed in four VCL files that need to be uploaded to your service:

📘

Before starting

These 3 custom VCL files will be provided to you by a HUMAN Solution Architect: px.vcl , px_configs.vcl , px_custom.vcl

To ensure that you are taking advantage of the latest features, several configurations and deploy changes need to be made in order to upgrade your Fastly VCL Enforcer to version 10. This document serves as a comprehensive guide to the changes that must be made.

1. Add Async Activities and Telemetry logging endpoints.

📘

This change is required if upgrading from version <9.x.

Instead of using a Syslog log streaming endpoint, we've changed our async activities and telemetry logs to use Fastly's HTTP logging endpoint.

This change requires removing the oler PX-Syslog logging endpoint and configuring two new logging endpoints instead. For more information about Fastly log streaming, see here.

Delete the PX-Syslog Logging Endpoint

1. On your Fastly service, go to "Logging" tab.
2. Delete the TCP logging endpoint named PX-Syslog.

Add the Async Activities Logging Endpoint

1. On your Fastly service, go to "Logging" tab

2. Add a new Logging endpoint with the information below:

   • Name: PX-Async-Activities
   • URL: https://collector-<px_app_id>.perimeterx.net/api/v1/collector/s2s
   • Placement: none
   • Maximum bytes: 500000
   • Advanced options:
     • Content type - application/json
     • JSON log entry format - Array of JSON
     • All other fields: No change is needed, use the default values.

Add the Telemetry Logging Endpoint

1. On your Fastly service, go to "Logging" tab

2. Use the following settings to define a new additional logger:

   • Name: PX-Telemetry
   • URL: https://collector-<px_app_id>.perimeterx.net/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.

2. Adjust custom functions in the PX_CUSTOM VCL file.

As part of an effort to reduce HUMAN's Fastly VCL workspace footprint, many custom subroutines in the PX_CUSTOM VCL file have been changed to return boolean values instead of setting headers.

The follwing custom subroutines were changed and need to be adjusted accordingly:

• px_custom_check_sensitive_route
• px_custom_check_sensitive_graphql_operation
• px_custom_filter_by_http_method
• px_custom_filter_by_user_agent
• px_custom_filter_by_route
• px_custom_filter_by_extension
• px_custom_filter_by_ip
• px_custom_enforced_routes
• px_custom_monitored_routes
• px_custom_check_enabled_route

What needs to be changed?

1. Make a copy of your PX_CUSTOM VCL file on your local computer.
2. Upload the new v10 PX_CUSTOM VCL file to your Fastly service.
3. Compare each custom subroutine on your previous PX_CUSTOM VCL with the new subroutine, and transfer the previously existing implementation to the new PX_CUSTOM VCL file. All desired logic should remain the same (pay special attention to conditionals and regular expressions!), but modify the return values of the subroutine as needed.

📘

Example

We've adjusted px_custom_check_sensitive_route subroutine to return a boolean value instead of setting a header.

Here is the previous implementation of this subroutine:

Vcl

# implementation in v9.x and below
sub px_custom_check_sensitive_route {
    if (req.url.path ~ {"<sensitive_routes>"}) {
        set req.http.X-PX-sensitive-route = "1";
    }
}

Compare this with the newer implementation fo the subroutine:

Vcl

# implementation in v10
sub px_custom_check_sensitive_route BOOL {
    if (req.url.path ~ {"<sensitive_routes>"}) {
        return true;
    }
    return false;
}

The regular expression in the condition (i.e., <sensitive_routes>) should stay the same for both implementations. The difference is that instead of setting the X-PX-sensitive-route header, we can simply return true.

3. Validate the px_configs configuration table in the PX_CONFIGS VCL file.

Several configuration options were deprecated in Fastly VCL v10. If one or more configurations in the list below are present in the px_configs table of the PX_CONFIGS VCL file, please modify them accordingly.

• px_module_mode - The "async_monitor" value is no longer available. The "monitor" value should be used instead.
• px_block_all_size_exceeded_post_requests - This configuration field has been removed. POST requests with bodies larger than 8 KB will go through normal processing.
• px_block_size_exceeded_post_requests_specific_routes - This configuration field has been removed. POST requests with bodies larger than 8 KB will go through normal processing.
• px_block_size_exceeded_post_requests_by_size - This configuration field has been removed. POST requests with bodies larger than 8 KB will go through normal processing.

4. Remove references to X-PX-* headers.

In version 9.x and earlier, HUMAN used headers beginning with x-px-* to store information during the duration of the Fastly request life cycle. These headers have been renamed in version 10 and will no longer be present on the request. Any references to these headers in your Fastly VCL code should be removed.

🚧

If you have logic in your Fastly VCL files that relies on these x-px-* headers, please reach out to your HUMAN Solution Architect or Customer Support for guidance on how to align this code with version 10.