Fastly Integration

The WebDecoy Fastly integration has two halves:

• Detection: Fastly streams every request your service answers to WebDecoy, which reports the automated ones, including crawlers that never run JavaScript, with their TLS fingerprint. See Detection with log streaming.
• Protection: WebDecoy adds addresses to a Fastly Access Control List (ACL) that your VCL blocks. You can do this by hand today; automatic blocking from detections is built but withheld until scores are calibrated (see Block an Address by Hand).

How It Works

Detection Created
       │
       ▼
WebDecoy Rule Engine
       │
       ├─ Check integration rules
       │  ├─ Event type matches?
       │  ├─ Score threshold met?
       │  └─ Decoy filter matches?
       │
       ├─ Automatic blocking enabled for this scorer version?
       │  (currently withheld until calibration)
       │
       ▼
Fastly ACL Entry API
       │
       └─ Add IP to ACL block list

When automatic blocking is enabled and a detection triggers the integration, WebDecoy calls the Fastly ACL Entry API (POST /service/{service_id}/acl/{acl_id}/entry) to add the IP address to your configured ACL.

Prerequisites

• Fastly account with ACL support
• Fastly API token with appropriate permissions
• An ACL container created and attached to your Fastly service
• VCL configured to block IPs in the ACL

Understanding Fastly ACLs

Fastly Access Control Lists (ACLs) work in two parts:

1. ACL Container - A named list attached to your service configuration
2. ACL Entries - The actual IP addresses or subnets in the list

ACL entries are “versionless” - once your ACL is attached to an active service version, any updates to the entries take effect immediately without requiring a new service version.

Getting a Fastly API Token

1. Log in to manage.fastly.com
2. Click Account → Personal API tokens
3. Click Create Token
4. Configure the token:
   • Name: “WebDecoy Integration”
   • Type: Automation token (recommended)
   • Scope: Select your service or Global (all services)
   • Role: Engineer or higher
5. Click Create Token
6. Copy the token immediately (you won’t see it again)

Required Permissions

The API token needs permission to:

• Read service configuration
• Create ACL entries
• Update ACL entries
• Delete ACL entries

Setting Up an ACL in Fastly

Before configuring WebDecoy, you need an ACL in your Fastly service:

1. Create the ACL Container

1. Go to your Fastly service
2. Click Edit configuration → Clone active
3. Click ACLs in the sidebar
4. Click Create ACL
5. Name it something like webdecoy_blocklist
6. Click Create

2. Add VCL to Block IPs

Add VCL code to your service to block IPs in the ACL:

acl webdecoy_blocklist {
  # Managed by WebDecoy - do not edit manually
}

sub vcl_recv {
  if (client.ip ~ webdecoy_blocklist) {
    error 403 "Forbidden";
  }
}

Alternatively, use Fastly’s IP Block List feature:

1. Go to Security → IP block list
2. Enable the feature
3. Select your ACL as the block list source

3. Activate the Configuration

1. Click Activate to deploy the new version
2. Note your Service ID and the ACL name for WebDecoy configuration

Finding Your Service ID

1. Go to manage.fastly.com
2. Click on your service
3. The Service ID is shown in the service details (or in the URL)
4. Format: alphanumeric string like SU1Z0isxPaozGVKXdv0eY

Your ACL name, not its ID

Fastly’s dashboard lists ACLs by name and does not show their IDs, so WebDecoy asks for the name. Enter it exactly as it appears under Access control lists (for example webdecoy_blocklist) and WebDecoy looks up the ID with your API token when you save. If no ACL of that name exists on the active service version, the integration is not saved and the message says so.

If you already have the ACL ID (from the Fastly API or CLI), you can enter it instead.

Setting Up the Integration

1. Go to Integrations in the WebDecoy sidebar
2. Click Fastly
3. Click Add Fastly Integration
4. Fill in the configuration:

Field	Description
Name	A friendly name for this integration
API Token	Your Fastly API token
Service ID	Your Fastly service ID
ACL name	The ACL to add blocked IPs to, as named in Fastly
ACL ID	Optional. Leave empty and WebDecoy looks it up from the name
Action	What to do when triggered (see below)

5. Click Create Integration

Detection with Log Streaming

Log streaming is detection, so it is included on the Free plan. On Free, create the integration with the Log Only action; Block IP requires a paid plan or an active trial.

Fastly’s HTTPS logging endpoint sends WebDecoy the requests your service answered: client IP, user agent, path, status, cache result and the TLS fingerprint (JA4). WebDecoy reports the automated ones to your dashboard and drops the rest; ordinary visitors are never stored. Nothing changes in your responses.

Because the stream includes your scripts and styles, WebDecoy also reports page requests from a browser user agent whose visit never fetched them: a scraper copying a browser’s name takes the HTML and leaves. Each page is held for 45 seconds so its assets can arrive in later batches, and a page is left undecided rather than guessed when the evidence is missing. See A browser that never drew the page.

It needs the integration tied to one site, so its rows land on that site.

1. On the integration, under Detection: log streaming, select Set up log streaming. WebDecoy shows a URL, a custom header, a log format and the options to set. Copy the header value now: it is shown once.

2. In Fastly, open the service, then Logging, and create an HTTPS endpoint:

   Fastly field	Value
   URL	The URL WebDecoy showed
   Custom header name	X-WebDecoy-Log-Secret
   Custom header value	The secret WebDecoy showed
   Log format	The format WebDecoy showed, pasted as is
   Content type	application/x-ndjson
   JSON log entry format	Newline delimited
   Maximum bytes	5000000
   Compression	None or gzip

3. Activate the new service version. Before its first delivery, Fastly checks that WebDecoy expects your service; WebDecoy answers for services with streaming turned on.

4. Prove it: curl -A "WebDecoy-Test/1.0" https://your-site.example/. A detection labeled Test appears once Fastly delivers the log. The first delivery after activating a version can take about five minutes; after that, Fastly sends a batch every few seconds from each location that served traffic. The integration shows the last delivery and how many requests it reported.

Replace secret issues a new URL and secret; the old ones stop working at once. Turn off stops WebDecoy accepting the stream; remove the logging endpoint in Fastly too.

Requests Fastly logs again at a shield POP are counted once.

Action Types

Action	Description
Block IP	Add the IP to the Fastly ACL (blocked by your VCL)
Log Only	Record the event without adding to ACL

Trigger Configuration

Event Types

Choose when the integration should trigger:

Option	Description
All Detections	Trigger on any detection
High Risk Detections (Score >= 80)	Only trigger when the detection’s bot score is 80 or higher

Minimum Score (optional)

Set a threshold score (0-100). The integration only triggers for detections whose threat score (unified_score, or the bot score when there is none) is at or above this value.

Recommended thresholds:

Use Case	Threshold
Aggressive blocking	50+
Standard protection	70+
Conservative (fewer false positives)	85+

Decoy Filter

Optionally restrict the integration to specific decoys. Leave empty to trigger for all decoys in your organization.

Managing Integrations

View Status

Each integration shows:

• Trigger Count - How many times it has fired
• Failure Count - How many API calls failed
• Last Triggered - When it last fired
• Last Error - Most recent error message (if any)

Test Integration

Click Test to check the connection. WebDecoy asks Fastly, read-only, whether the stored token can read the configured ACL, and shows Fastly’s own answer if it cannot (for example a token without write access, or an ACL name that does not exist). A test changes nothing at Fastly and does not count as a trigger.

Block an Address by Hand

Automatic blocking acts only on detections whose score has been calibrated, so you can also add an address yourself. On the Fastly integration page, under Changes on this provider, choose Block an address, then enter the address, how long the block should last and a reason, and select Apply block. WebDecoy adds the ACL entry, reads it back to confirm Fastly holds it, and removes it when it expires. A Fastly ACL entry has no expiry of its own, so the removal is ours.

The block applies wherever your VCL consults the ACL, which is usually the whole service. It cannot be limited to one hostname from WebDecoy. The button appears when exactly one Fastly integration is active and set to Block IP.

Enable/Disable

Toggle integrations on or off without deleting them. Disabled integrations don’t process any detections.

Delete

Remove an integration entirely. This doesn’t remove any IPs already added to your Fastly ACL.

Best Practices

Do’s

• Start with High Risk Detections to avoid false positives
• Use a conservative bot score threshold initially (75+)
• Create a dedicated ACL for WebDecoy (don’t mix with manual entries)
• Monitor the failure count for API issues
• Test the integration after setup
• Regularly review blocked IPs in Fastly

Don’ts

• Don’t use a token with more permissions than needed
• Don’t set the threshold too low (causes false positives)
• Don’t ignore failure counts (may indicate permission issues)
• Don’t manually edit the WebDecoy ACL entries

Troubleshooting

“Unauthorized” or “401” Errors

1. Verify your API token is correct
2. Check the token hasn’t been revoked
3. Ensure the token has permission for the service
4. Regenerate the token if needed

“ACL Not Found” or “404” Errors

1. Verify the ACL name (or ID) matches the ACL in Fastly
2. Ensure the ACL exists in your service
3. Check the service ID is correct
4. Verify the ACL is attached to an active service version

“Service Not Found” Errors

1. Verify the Service ID is correct
2. Ensure the API token has access to the service
3. Check if the service has been deleted or moved

IPs Not Being Blocked

1. Check the integration is active (not disabled)
2. Verify the event type filters match your detections
3. Check the score threshold isn’t too high
4. Remember that automatic blocking is currently withheld until scorer calibration; use Block an address to block by hand
5. Verify your VCL is configured to block IPs in the ACL
6. Check that the service version with the ACL is active
7. Look for errors in the integration status

High Failure Count

1. Check the Last Error message
2. Verify API token permissions
3. Check Fastly’s status page for outages
4. Ensure you haven’t hit API rate limits

Fastly ACL Limits

Be aware of Fastly’s limits:

Limit	Value
ACL entries per ACL	10,000 (can be increased)
API rate limits	Varies by plan

Contact Fastly support to increase limits if needed.

Viewing Blocked IPs in Fastly

To see IPs blocked by WebDecoy:

1. Go to your Fastly service
2. Click ACLs
3. Click on your WebDecoy ACL
4. View all entries
5. WebDecoy entries carry a comment of the form webdecoy:action:<id>, which identifies the change in WebDecoy’s list of changes on the provider

Removing Blocked IPs

Every ACL entry WebDecoy adds has a lifetime, and WebDecoy removes it when that expires. You can also reverse one at any time from Integrations → Fastly, under the list of changes on the provider. Deleting the integration is the exception: its credentials go with it, so entries it added stay in the ACL.

To remove one from Fastly’s side instead:

Via Fastly Dashboard

1. Go to your Fastly service
2. Click ACLs → Your WebDecoy ACL
3. Find the IP entry
4. Click Delete

Via Fastly API

curl -X DELETE \
  "https://api.fastly.com/service/{service_id}/acl/{acl_id}/entry/{entry_id}" \
  -H "Fastly-Key: YOUR_API_TOKEN"

Comparison with Other WAF Integrations

Feature	Fastly	Cloudflare	AWS WAF
Edge blocking	Yes	Yes	Yes
Immediate updates	Yes (versionless)	Yes	Yes
Subnet support	Yes	Yes	Yes
IP set management	ACLs	Firewall Rules	IP Sets
Setup complexity	Medium	Low	High

---

Next Steps

• Cloudflare - Alternative WAF integration
• AWS WAF - AWS WAF IP blocking
• Vercel - Edge middleware protection
• Overview - All integrations