← Files Fastly Agent ToolkitARCHIVED FILE
skills/fastly/references/ngwaf.md
13.5 KB · Oct 10, 2026 · 18:29 UTC
# Fastly Next-Gen WAF (NGWAF)
Base: `https://api.fastly.com` | Auth: `Fastly-Key: $FASTLY_API_TOKEN` | Docs: https://www.fastly.com/documentation/reference/api/ngwaf
## Key Concepts
**Signal Sciences integration**: NGWAF can be accessed via the Fastly control panel or the legacy Signal Sciences control panel (`dashboard.signalsciences.net`). The legacy Signal Sciences API (`docs.fastly.com/signalsciences/api/`) is separate from the Fastly NGWAF API documented here. Customers with access to the Fastly control panel use the `/ngwaf/v1/` endpoints.
**Signal-based detection model**: Every request inspected by NGWAF gets tagged with zero or more signals (e.g., `SQLI`, `XSS`). Rules then match on these signals to decide actions. Signals have a `detector_scope` which can be `system`, `account`, `workspace`, or `unknown`; custom signals use the `site.*` prefix.
**Three deployment types**: NGWAF supports edge WAF deployment (runs in the Fastly edge `edge_waf_request_inspection` phase, after VCL/Compute processing), on-prem WAF deployment (module and agent on your web servers, or agent in reverse proxy mode), and cloud WAF deployment (on Fastly's cloud-hosted infrastructure). Edge deployment is the recommended approach for Fastly CDN customers. Feature availability varies by deployment type.
**Workspace model**: Workspaces (also known as sites) are user-defined sets of rules and settings. A workspace contains rules, events, requests, and configuration. Custom signals are account-level, not workspace-level. One workspace can be linked to multiple Fastly services via the enablement API. Account-level rules can target all workspaces (`"*"`) or specific workspace IDs.
**Traffic ramp**: When enabling NGWAF on a service, the `traffic_ramp` configuration controls what percentage of traffic is inspected (e.g., `"20"`).
## Enablement
Enable, disable, and configure NGWAF on individual services. Requires a `workspace_id` linking the service to an NGWAF workspace.
**Important distinction**: Enablement (this section) controls whether NGWAF is active on a service at all. Workspace mode (`block`/`log`/`off`) controls what NGWAF does with inspected traffic. To fully disable WAF on a service, use the `DELETE` endpoint below — changing workspace mode to `log` or `off` is NOT the same as disabling.
| Action | Method | Endpoint |
| --------------------- | -------- | ---------------------------------------------------------------- |
| Enable | `PUT` | `/enabled-products/v1/ngwaf/services/{service_id}` |
| Disable (full remove) | `DELETE` | `/enabled-products/v1/ngwaf/services/{service_id}` |
| Get status | `GET` | `/enabled-products/v1/ngwaf/services/{service_id}` |
| Get configuration | `GET` | `/enabled-products/v1/ngwaf/services/{service_id}/configuration` |
| Update configuration | `PATCH` | `/enabled-products/v1/ngwaf/services/{service_id}/configuration` |
| List enabled services | `GET` | `/enabled-products/v1/ngwaf/services` |
```bash
# Enable NGWAF on a service (links to a workspace)
curl -X PUT -H "Fastly-Key: $FASTLY_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"workspace_id":"7JFbo4RNA0OKdFWC04r6B3"}' \
"https://api.fastly.com/enabled-products/v1/ngwaf/services/$SERVICE_ID"
# Check enablement status
curl -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/enabled-products/v1/ngwaf/services/$SERVICE_ID"
# Disable NGWAF on a service (stops all inspection, returns 204)
curl -X DELETE -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/enabled-products/v1/ngwaf/services/$SERVICE_ID"
# Update configuration (e.g., change traffic ramp percentage)
curl -X PATCH -H "Fastly-Key: $FASTLY_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"traffic_ramp":"20"}' \
"https://api.fastly.com/enabled-products/v1/ngwaf/services/$SERVICE_ID/configuration"
```
Enable request body requires `workspace_id` (required) and optionally `traffic_ramp` (percentage of traffic to inspect). Disable returns `204 No Content`.
## Workspaces
Each workspace has a mode, attack signal thresholds, and a default blocking response code. Workspaces are also known as sites.
**Valid workspace modes** (exactly three values):
- `block` — actively blocks malicious requests
- `log` — inspects and logs but does not block (observe-only)
- `off` — disables WAF processing in the workspace
No other mode values exist. Do not try `monitor`, `disabled`, `detection`, etc.
**CLI note**: When using the Fastly CLI, the subcommand to retrieve a workspace is `get` (e.g., `fastly ngwaf workspace get`). There is NO `describe` subcommand for NGWAF resources.
| Action | Method | Endpoint |
| ---------------- | -------- | ------------------------------------------------- |
| List workspaces | `GET` | `/ngwaf/v1/workspaces` |
| Create workspace | `POST` | `/ngwaf/v1/workspaces` |
| Get workspace | `GET` | `/ngwaf/v1/workspaces/{workspace_id}` |
| Edit workspace | `PATCH` | `/ngwaf/v1/workspaces/{workspace_id}` |
| Delete workspace | `DELETE` | `/ngwaf/v1/workspaces/{workspace_id}` |
| Get top attacks | `GET` | `/ngwaf/v1/workspaces/{workspace_id}/top-attacks` |
```bash
# List all workspaces
curl -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/ngwaf/v1/workspaces?limit=100"
```
Workspace modes: `off`, `log`, `block`. The `attack_signal_thresholds` object controls how many attack signals per IP trigger flagging (`one_minute`, `ten_minutes`, `one_hour`, or `immediate`). The `default_blocking_response_code` accepts `301`, `302`, or `400-599`.
## Rules
Rules allow, block, rate-limit, or tag requests based on conditions. Two scopes: **account-level** rules (apply across workspaces) and **workspace-level** rules (apply to one workspace). Four rule types: `request`, `signal`, `rate_limit`, `templated_signal`.
### Account-Level Rules
| Action | Method | Endpoint |
| ------------------- | -------- | --------------------------- |
| List account rules | `GET` | `/ngwaf/v1/rules` |
| Create account rule | `POST` | `/ngwaf/v1/rules` |
| Get account rule | `GET` | `/ngwaf/v1/rules/{rule_id}` |
| Edit account rule | `PATCH` | `/ngwaf/v1/rules/{rule_id}` |
| Delete account rule | `DELETE` | `/ngwaf/v1/rules/{rule_id}` |
### Workspace-Level Rules
| Action | Method | Endpoint |
| --------------------- | -------- | ----------------------------------------------------- |
| List workspace rules | `GET` | `/ngwaf/v1/workspaces/{workspace_id}/rules` |
| Create workspace rule | `POST` | `/ngwaf/v1/workspaces/{workspace_id}/rules` |
| Get workspace rule | `GET` | `/ngwaf/v1/workspaces/{workspace_id}/rules/{rule_id}` |
| Edit workspace rule | `PATCH` | `/ngwaf/v1/workspaces/{workspace_id}/rules/{rule_id}` |
| Delete workspace rule | `DELETE` | `/ngwaf/v1/workspaces/{workspace_id}/rules/{rule_id}` |
Rule actions include: `block`, `allow`, `add_signal`, `exclude_signal`, `block_signal`, `browser_challenge`, `dynamic_challenge`, `verify_token`, `deception`, `log_request`. Condition fields include `ip`, `path`, `method`, `domain`, `country`, `user_agent`, `ja3_fingerprint`, `response_code`, and multival fields like `request_header`, `signal`, `query_parameter`.
## Custom Signals
Custom signals are user-defined tags that can be applied to requests via rules. They exist at the account level.
| Action | Method | Endpoint |
| -------------------- | -------- | ------------------------------- |
| List custom signals | `GET` | `/ngwaf/v1/signals` |
| Create custom signal | `POST` | `/ngwaf/v1/signals` |
| Get custom signal | `GET` | `/ngwaf/v1/signals/{signal_id}` |
| Edit custom signal | `PATCH` | `/ngwaf/v1/signals/{signal_id}` |
| Delete custom signal | `DELETE` | `/ngwaf/v1/signals/{signal_id}` |
Custom signal names generate a `reference_id` automatically: the name is lowercased, spaces become dashes, and it is prefixed with `site.` (e.g., name `foo signal` becomes `site.foo-signal`).
## Events and Requests
Events are actions NGWAF takes due to threshold-based blocking, templated rules, or site alerts. Requests are individual HTTP requests tagged with signals.
### Events
| Action | Method | Endpoint |
| ------------------- | ------- | -------------------------------------------------------------- |
| List events | `GET` | `/ngwaf/v1/workspaces/{workspace_id}/events` |
| Get event | `GET` | `/ngwaf/v1/workspaces/{workspace_id}/events/{event_id}` |
| Expire event | `PATCH` | `/ngwaf/v1/workspaces/{workspace_id}/events/{event_id}` |
| Remove flag from IP | `POST` | `/ngwaf/v1/workspaces/{workspace_id}/events/{event_id}/expire` |
List events requires a `from` parameter (RFC 3339 datetime). Filter by `signal`, `ip`, or `status` (`active`/`expired`).
```bash
# List recent events in a workspace
curl -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/ngwaf/v1/workspaces/$WORKSPACE_ID/events?from=2025-01-01T00:00:00Z&limit=100"
```
### Requests
| Action | Method | Endpoint |
| --------------------- | ------ | ------------------------------------------------------------------ |
| Search requests | `GET` | `/ngwaf/v1/workspaces/{workspace_id}/requests` |
| Get request | `GET` | `/ngwaf/v1/workspaces/{workspace_id}/requests/{request_id}` |
| Report false positive | `POST` | `/ngwaf/v1/workspaces/{workspace_id}/requests/{request_id}/report` |
The `q` parameter accepts a search query syntax (e.g., `"/a/path sqli from:-7h"`). Supports CSV export via `export=true` with `Accept: text/csv` header. Each request includes detected `signals` with `id`, `location`, `value`, `detector`, and `detector_scope`.
## Additional APIs
| Area | Key Endpoints |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Simulate | `POST /ngwaf/v1/workspaces/{workspace_id}/simulate` -- test rules against a synthetic request (100KB body limit, stateless) |
| Agents | `GET /ngwaf/v1/workspaces/{workspace_id}/agents[/{agent_id}]` -- agent status, version, decision latency (p50/p95/p99), CPU/memory |
| Agent Keys | `GET /ngwaf/v1/workspaces/{workspace_id}/agent-keys` -- list agent keys for configuration |
| Lists | `/ngwaf/v1/lists` (account-level), `/ngwaf/v1/workspaces/{workspaceId}/lists` (workspace-level) -- lists for use in rule conditions |
| Virtual Patches | `/ngwaf/v1/workspaces/{workspace_id}/virtual-patches` -- virtual patches for a workspace |
| Redactions | `/ngwaf/v1/workspaces/{workspace_id}/redactions` -- control which fields are redacted in request logs |
| Workspace Alerts | `/ngwaf/v1/workspaces/{workspace_id}/alerts` -- configure alert notifications |
| Timeseries | `/ngwaf/v1/workspaces/{workspace_id}/timeseries` -- time-bucketed signal and request metrics |
| Reports | `/ngwaf/v1/reports/signals` -- signals report data |
## Documentation
URLs below serve Markdown (use the `Accept: text/markdown` header).
| Source | URL |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| NGWAF product overview, prerequisites, billing | `https://docs.fastly.com/products/ngwaf` |
| Setup guides, configuration, deployment modes | `https://www.fastly.com/documentation/guides/next-gen-waf` |
| API reference, endpoint schemas, examples | `https://www.fastly.com/documentation/reference/api/ngwaf` |
| Edge WAF deployment setup | `https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/edge-deployment` |
| Cloud WAF deployment setup | `https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/cloud-waf` |
| Rule types, conditions, actions | `https://www.fastly.com/documentation/guides/next-gen-waf/rules` |
| Signal monitoring and custom signals | `https://www.fastly.com/documentation/guides/next-gen-waf/monitoring` |
| Attack signals overview | `https://www.fastly.com/documentation/guides/next-gen-waf/signals` |
For general Fastly platform guidance, documentation source index, and other specialized skills, see the `fastly` skill.
SHA-256: 3bb522fab9375abbaf689dc2fcb59d537f54186b68a9458636fcaf2933ed09d0