Edge WAF deployment using the Next-Gen WAF control panel

The Edge WAF deployment method allows you to add the Next-Gen WAF as an edge security service onto Fastly's Edge Cloud platform using both VCL and Compute services.

Prerequisites

Prior to mapping Compute services to Next-Gen WAF sites (also known as workspaces), our support team must enable Compute for your corp (also known as account).

Limitations and caveats

Keep in mind the following things when working with the Edge WAF deployment method:

• Adding the Next-Gen WAF via the Edge WAF deployment method to an existing Fastly VCL service counts against the service chain limit.
• We automatically support backends on VCL services defined using the Fastly API, CLI, or web interface. However, if you've already defined your backends manually, automatic origin synchronization won't happen and your traffic won't be served properly. To fix this, redefine your backends. Learn more about defining backends in our integration documentation.
• We automatically support VCL directors on VCL services as long as they are defined using the Fastly API.

Deploying at the edge

To deploy at the edge, you will need a corp (account) and at least one site (workspace) to protect. Setup involves making calls to the Signal Sciences API. For VCL services, these API calls create a deployment and add privileged dynamic VCL snippets that enable inspection. For Compute services, these API calls create a deployment and authorize your service to make calls to the Next-Gen WAF.

Creating the edge security service

Create a new edge security service by calling the Edge WAF deployment API endpoint. This API call creates a new edge security service associated with your corp (account) and site (workspace). You will need to replace ${corpName} and ${siteName} with those of the corp (account) and site (workspace) you are adding the edge security service to. Your ${corpname} and ${siteName} are both present in the address of your Next-Gen WAF control panel, such as https://dashboard.signalsciences.net/corps/${corpName}/sites/${siteName}.

$ curl -X PUT "https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/edgeDeployment" \
-H "x-api-user:${SIGSCI_EMAIL}" \
-H "x-api-token:${SIGSCI_TOKEN}" \
-H "Fastly-Key: ${FASTLY_KEY}" \
-H "Content-Type: application/json" \
-d '{"authorizedServices": [ "${fastlySID}" ] }'

Run this API call again for each site (workspace) you want to deploy on.

If successful, you will receive an HTTP 200 response with a blank response body ({}). Once this is returned, wait 1-2 minutes to allow the edge resources to be created.

To confirm the Compute instance resources associated with the site (workspace) have been created, query the edgeDeployment endpoint again using the following request:

$ curl -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
-H "Content-Type: application/json" \
"https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/edgeDeployment"

The query should now return the appropriate Compute instance associated with the Next-Gen WAF site (workspace) in the URL path with no services attached. To attach the appropriate service, refer to Mapping to the Fastly service.

{"AgentHostName":"se--${corpName}--{SiteUID}.edgecompute.app","ServicesAttached":[]}

Mapping to a Fastly VCL service

To map your corp (account) and site (workspace) to an existing Fastly VCL service and synchronize the origins, follow these steps:

1. Using the curl command line tool, call the PUT deliveryIntegration/${fastlySID} API endpoint in a terminal application:

   1. Unix-based
   2. Windows-based

   $ curl -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
   -H "Fastly-Key: ${FASTLY_KEY}" -H 'Content-Type: application/json' -X PUT \
   "https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/deliveryIntegration/${fastlySID}"

   This API call will create and activate a new service version with dynamic VCL snippets automatically added to the service. By default, the service will be activated and set to 0% traffic ramping. You can override those defaults by providing parameters in the JSON body:

   • activateVersion - activate Fastly service version after clone. Possible values are true or false (unquoted). If not specified, defaults to true.
   • percentEnabled - percentage of traffic to send to the Next-Gen WAF. Possible values are integers values 0 to 100 (unquoted). If not specified, defaults to 0. This can be adjusted later. Check out Traffic ramping for details.

   For example, to disable initial activation and set initial traffic ramping to 10%, add the curl parameter -d '{"activateVersion": false, "percentEnabled": 10}' to the usual call:

   $ curl -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
   -H "Fastly-Key: ${FASTLY_KEY}" -H 'Content-Type: application/json' -X PUT \
   -d '{"activateVersion": false, "percentEnabled": 10}' \
   "https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/deliveryIntegration/${fastlySID}"

   This API call requires the Fastly-Key header for authentication. The Fastly API key must have write access to the Fastly service ID. This API call will create and activate a new service version with dynamic VCL snippets automatically added to the service.

2. Optionally, follow these steps again for each additional Fastly service that you want to deploy on.

   If your origins change, you will need to call the PUT deliveryIntegration/${fastlySID}/backends API endpoint again to resynchronize the backends.

Re-mapping a Fastly VCL service to a new site (workspace)

To re-assign the Fastly service to a new site (workspace), follow these steps:

1. Using the curl command line tool, call the DELETE deliveryIntegration/${fastlySID} API endpoint in a terminal application:

   $ curl -v -H "x-api-user: ${SIGSCI_EMAIL}" -H "x-api-token: ${SIGSCI_TOKEN}" \
   -H "Fastly-Key: ${FASTLY_KEY}" -H 'Content-Type: application/json' -X DELETE \
   "https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/deliveryIntegration/${fastlySID}"

   This API call requires the Fastly-Key header for authentication. The Fastly API key must have write access to the Fastly service ID. This API call removes all backends from the Edge WAF deployment connected to the Fastly service and detaches the Fastly service from the Edge WAF deployment.

2. Using the curl command line tool, call the PUT deliveryIntegration API endpoint in a terminal application with the new ${siteName} to create a new edge security service. For example:

   $ curl -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
   -H 'Content-Type: application/json' -X PUT \
   "https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/edgeDeployment"

   You can verify if a compute instance resource was successfully created by the above step by referring to Create the edge security service.

3. Using the curl command line tool, call the PUT deliveryIntegration/{fastlySID} API endpoint in a terminal application to map the existing Fastly service to the new ${siteName}. For example:

   $ curl -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
   -H "Fastly-Key: ${FASTLY_KEY}" -H 'Content-Type: application/json' -X PUT \
   "https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/deliveryIntegration/${fastlySID}"

   This API call will activate a new service version by updating the existing Next-Gen WAF VCL dynamic snippet with the new edge security service ID.

Synchronizing origins for VCL services

Some conditions cause origin syncing to occur automatically:

• site (workspace) configuration changes
• Agent mode (also known as Protection mode) changes
• Enabling or disabling IP Anonymization
• Rule changes (e.g., request rules, signal exclusion rules, CVE rules)
• Rule list changes (only if the list is being used by a rule)
• IP addresses flagged

If you change your origins in the Fastly control panel, you will need to take additional action to synchronize your changes using an API call. The API call makes sure origin changes applied in the Fastly control panel are reflected in the edge security service. For example:

$ curl -v -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
-H "Fastly-Key: $FASTLY_KEY" -H "Content-Type:application/json" -X PUT \
"https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/deliveryIntegration/${fastlySID}/backends"

WAF execution

Once both API calls are completed, your service will automatically be set up with dynamic VCL snippets that control the execution of the Next-Gen WAF. A new service version will be created and activated containing the additional VCL snippets.

The edge security service runs in the vcl_miss and vcl_pass subroutines. Execution priority is set to a high value to enable compatibility with any other VCL snippets that may be in use.

Traffic ramping

You can control the amount of traffic inspected by the edge security service using the Enabled dictionary key. This value is available in the Edge_Security dictionary and is automatically created when you attach a delivery service.

The default value is 0, with numbers greater than zero representing a percentage of the traffic being inspected. This means that unless you change the value of the Edge_Security Edge dictionary, your WAF will be enabled but won't inspect any traffic. If the value is set to 100, all traffic (100%) will be passed through the edge security service. If the value is less than 100, a random sample of the specified percentage will be sent through the edge security service.

Health checks

The edge security service includes a health check, which skips security processing entirely if the edge security service is unhealthy for any reason. The health check works by sending a periodic probe every 15 seconds and checking for HTTP status code 200 as an expected response. Should a check indicate an unhealthy service, all security processing is skipped until the service becomes healthy again. It may take up to 60 seconds for all security processing to be skipped.

The edge security service is modeled as an origin using the backend type. The health check lives inside the edge_security function and uses the backend.health property to check the status of the edge security service.

Determining if you already use health check logic

You can check if your service already uses health check logic by inspecting the value of the x-sigsci-edgemodule HTTP header, which is added to the request prior to being sent to the edge security service. If the value is greater than or equal to 1.6.0, then your VCL includes the health check logic.

Enabling and testing health check logic

To enable the health check for an existing service, make sure your VCL is updated to the latest version by re-running the steps in our instructions for mapping to the Fastly service. Then, test the health check logic by toggling the Agent mode (Protection mode) to Off. This will simulate an unhealthy state for the edge security service and processing will be skipped.

Using headers to customize inspection

You can use X-SigSci- headers to force the Next-Gen WAF to inspect requests, to disable inspection, and to skip initial inspection.