menu
search close

Edge Deployment

access_time Updated Jun 2, 2023

The Edge deployment method allows you to add the Signal Sciences as an edge security service onto Fastly’s Edge Cloud Platform without needing to make any modifications to your own hosting environment.

Limitations and caveats

This feature works with backends defined in VCL services using the API, CLI, or web interface. Backend definitions defined manually in VCL or snippets can be supported by redefining them using the API, CLI, or web interface. This will offer validation and enable a number of features not available to VCL-defined backends, including shielding. Learn more about defining backends in our integration documentation.

We automatically support VCL directors as long as they are defined using the Fastly API. We do not, however, currently support Hash or Client directors. This feature requires a one-time configuration change that needs to be performed by Fastly. Contact sales@fastly.com for more information.

Deploying at the edge

To deploy at the edge, you will need a Signal Sciences corp and at least one site to protect. Setup involves making calls to the Signal Sciences API. These API calls will add privileged dynamic VCL snippets to your service that enable inspection.

Creating the edge security service

Create a new edge security service by calling the edge deployment API endpoint. This API call creates a new edge security service associated with your corp and site. You will need to replace ${corpName} and ${siteName} with those of the corp and site you are adding the edge security service to. Your ${corpname} and ${siteName} are both present in the address of your Signal Sciences console, such as https://dashboard.signalsciences.net/corps/${corpName}/sites/${siteName}.

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"

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

Mapping to the Fastly service

To map your corp and site to an existing Fastly service and synchronize the origins, follow these steps:

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

    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}/edgeDeployment/${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}/edgeDeployment/${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 edgeDeployment/${fastlySID}/backends API endpoint again to resynchronize the backends.

To re-assign the Fastly service to another site, follow these steps:

  1. Using the curl command line tool, call the DELETE edgeDeployment/${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}/edgeDeployment/${fastlySID}"

    This API call requires Fastly-Key header for authentication. The Fastly API key must have write access to the Fastly service ID. In the Fastly app, a draft version of the service is created. The draft version removes the mapping to the old site.

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

    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}/edgeDeployment/${fastlySID}"

    In the Fastly app, a new sigsci_config custom VCL file that maps the corp and site name to the service and synchronizes the origins is added to the existing draft version of the service.

  3. Using the curl command line tool, call the PUT edgeDeployment/${fastlySID} API endpoint in a terminal application as above, but with 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}/edgeDeployment/${fastlySID}"

Synchronizing origins

IMPORTANT: Failure to synchronize origins may result in your traffic not being inspected properly. Requests sent to a backend that does not exist in the edge security service will be served a 503 Unknown wasm backend error. You can correct this issue by running an API call to properly sync origins after any changes.

Some conditions cause origin syncing to occur automatically:

  • Site configuration changes
  • Agent mode changes (e.g., blocking, not blocking)
  • 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 Console, 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 Console 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}/edgeDeployment/${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.

Note: The Edge_Security Edge dictionary no longer uses The DISABLED field. To control blocking and logging behavior of an edge security service or turn off agent configurations entirely, use the web interface instead.

Health checks

The edge security service includes a health check inside the edge_security function. Using the backend.health property, this health check will skip security processing entirely if the edge security service is unhealthy for any reason. The edge security service is modeled as an origin using the backend type and uses the same health check feature.

The health check works by sending a periodic probe every 15 seconds and checks for an HTTP status code 200 as an expected response. Should a check indicate an unhealthy service, all security processing will be skipped until the service becomes healthy again. It may take up to 60 seconds for all security processing to be skipped.

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 to Off. This will simulate an unhealthy state for the edge security service and processing will be skipped.

list
list On this page