mirror of
https://github.com/ksyasuda/dotfiles.git
synced 2026-03-20 18:11:27 -07:00
update skills
This commit is contained in:
@@ -0,0 +1,44 @@
|
||||
# Cloudflare API Shield Reference
|
||||
|
||||
Expert guidance for API Shield - comprehensive API security suite for discovery, protection, and monitoring.
|
||||
|
||||
## Reading Order
|
||||
|
||||
| Task | Files to Read |
|
||||
|------|---------------|
|
||||
| Initial setup | README → configuration.md |
|
||||
| Implement JWT validation | configuration.md → api.md |
|
||||
| Add schema validation | configuration.md → patterns.md |
|
||||
| Detect API attacks | patterns.md → api.md |
|
||||
| Debug issues | gotchas.md |
|
||||
|
||||
## Feature Selection
|
||||
|
||||
What protection do you need?
|
||||
|
||||
```
|
||||
├─ Validate request/response structure → Schema Validation 2.0 (configuration.md)
|
||||
├─ Verify auth tokens → JWT Validation (configuration.md)
|
||||
├─ Client certificates → mTLS (configuration.md)
|
||||
├─ Detect BOLA attacks → BOLA Detection (patterns.md)
|
||||
├─ Track auth coverage → Auth Posture (patterns.md)
|
||||
├─ Stop volumetric abuse → Abuse Detection (patterns.md)
|
||||
└─ Discover shadow APIs → API Discovery (api.md)
|
||||
```
|
||||
|
||||
## In This Reference
|
||||
|
||||
- **[configuration.md](configuration.md)** - Setup, session identifiers, rules, token/mTLS configs
|
||||
- **[api.md](api.md)** - Endpoint management, discovery, validation APIs, GraphQL operations
|
||||
- **[patterns.md](patterns.md)** - Common patterns, progressive rollout, OWASP mappings, workflows
|
||||
- **[gotchas.md](gotchas.md)** - Troubleshooting, false positives, performance, best practices
|
||||
|
||||
## Quick Start
|
||||
|
||||
API Shield: Enterprise-grade API security (Discovery, Schema Validation 2.0, JWT, mTLS, BOLA Detection, Auth Posture). Available as Enterprise add-on with preview access.
|
||||
|
||||
## See Also
|
||||
|
||||
- [API Shield Docs](https://developers.cloudflare.com/api-shield/)
|
||||
- [API Reference](https://developers.cloudflare.com/api/resources/api_gateway/)
|
||||
- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)
|
||||
141
.agents/skills/cloudflare-deploy/references/api-shield/api.md
Normal file
141
.agents/skills/cloudflare-deploy/references/api-shield/api.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# API Reference
|
||||
|
||||
Base: `/zones/{zone_id}/api_gateway`
|
||||
|
||||
## Endpoints
|
||||
|
||||
```bash
|
||||
GET /operations # List
|
||||
GET /operations/{op_id} # Get single
|
||||
POST /operations/item # Create: {endpoint,host,method}
|
||||
POST /operations # Bulk: {operations:[{endpoint,host,method}]}
|
||||
DELETE /operations/{op_id} # Delete
|
||||
DELETE /operations # Bulk delete: {operation_ids:[...]}
|
||||
```
|
||||
|
||||
## Discovery
|
||||
|
||||
```bash
|
||||
GET /discovery/operations # List discovered
|
||||
PATCH /discovery/operations/{op_id} # Update: {state:"saved"|"ignored"}
|
||||
PATCH /discovery/operations # Bulk: {operation_ids:{id:{state}}}
|
||||
GET /discovery # OpenAPI export
|
||||
```
|
||||
|
||||
## Config
|
||||
|
||||
```bash
|
||||
GET /configuration # Get session ID config
|
||||
PUT /configuration # Update: {auth_id_characteristics:[{name,type:"header"|"cookie"}]}
|
||||
```
|
||||
|
||||
## Token Validation
|
||||
|
||||
```bash
|
||||
GET /token_validation # List
|
||||
POST /token_validation # Create: {name,location:{header:"..."},jwks:"..."}
|
||||
POST /jwt_validation_rules # Rule: {name,hostname,token_validation_id,action:"block"}
|
||||
```
|
||||
|
||||
## Workers Integration
|
||||
|
||||
### Access JWT Claims
|
||||
```js
|
||||
export default {
|
||||
async fetch(req, env) {
|
||||
// Access validated JWT payload
|
||||
const jwt = req.cf?.jwt?.payload?.[env.JWT_CONFIG_ID]?.[0];
|
||||
if (jwt) {
|
||||
const userId = jwt.sub;
|
||||
const role = jwt.role;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Access mTLS Info
|
||||
```js
|
||||
export default {
|
||||
async fetch(req, env) {
|
||||
const tls = req.cf?.tlsClientAuth;
|
||||
if (tls?.certVerified === 'SUCCESS') {
|
||||
const fingerprint = tls.certFingerprintSHA256;
|
||||
// Authenticated client
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic JWKS Update
|
||||
```js
|
||||
export default {
|
||||
async scheduled(event, env) {
|
||||
const jwks = await (await fetch('https://auth.example.com/.well-known/jwks.json')).json();
|
||||
await fetch(`https://api.cloudflare.com/client/v4/zones/${env.ZONE_ID}/api_gateway/token_validation/${env.CONFIG_ID}`, {
|
||||
method: 'PATCH',
|
||||
headers: {'Authorization': `Bearer ${env.CF_API_TOKEN}`, 'Content-Type': 'application/json'},
|
||||
body: JSON.stringify({jwks: JSON.stringify(jwks)})
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Firewall Fields
|
||||
|
||||
### Core Fields
|
||||
```js
|
||||
cf.api_gateway.auth_id_present // Session ID present
|
||||
cf.api_gateway.request_violates_schema // Schema violation
|
||||
cf.api_gateway.fallthrough_triggered // No endpoint match
|
||||
cf.tls_client_auth.cert_verified // mTLS cert valid
|
||||
cf.tls_client_auth.cert_fingerprint_sha256
|
||||
```
|
||||
|
||||
### JWT Validation (2026)
|
||||
```js
|
||||
// Modern validation syntax
|
||||
is_jwt_valid(http.request.jwt.payload["{config_id}"][0])
|
||||
|
||||
// Legacy (still supported)
|
||||
cf.api_gateway.jwt_claims_valid
|
||||
|
||||
// Extract claims
|
||||
lookup_json_string(http.request.jwt.payload["{config_id}"][0], "claim_name")
|
||||
```
|
||||
|
||||
### Risk Labels (2026)
|
||||
```js
|
||||
// BOLA detection
|
||||
cf.api_gateway.cf-risk-bola-enumeration // Sequential resource access detected
|
||||
cf.api_gateway.cf-risk-bola-pollution // Parameter pollution detected
|
||||
|
||||
// Authentication posture
|
||||
cf.api_gateway.cf-risk-missing-auth // Endpoint lacks authentication
|
||||
cf.api_gateway.cf-risk-mixed-auth // Inconsistent auth patterns
|
||||
```
|
||||
|
||||
## BOLA Detection
|
||||
|
||||
```bash
|
||||
GET /user_schemas/{schema_id}/bola # Get BOLA config
|
||||
PATCH /user_schemas/{schema_id}/bola # Update: {enabled:true}
|
||||
```
|
||||
|
||||
## Auth Posture
|
||||
|
||||
```bash
|
||||
GET /discovery/authentication_posture # List unprotected endpoints
|
||||
```
|
||||
|
||||
## GraphQL Protection
|
||||
|
||||
```bash
|
||||
GET /settings/graphql_protection # Get limits
|
||||
PUT /settings/graphql_protection # Set: {max_depth,max_size}
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [configuration.md](configuration.md) - Setup guides for all features
|
||||
- [patterns.md](patterns.md) - Firewall rules and common patterns
|
||||
- [API Gateway API Docs](https://developers.cloudflare.com/api/resources/api_gateway/)
|
||||
@@ -0,0 +1,192 @@
|
||||
# Configuration
|
||||
|
||||
## Schema Validation 2.0 Setup
|
||||
|
||||
> ⚠️ **Classic Schema Validation deprecated.** Use Schema Validation 2.0.
|
||||
|
||||
**Upload schema (Dashboard):**
|
||||
```
|
||||
Security > API Shield > Schema Validation > Add validation
|
||||
- Upload .yml/.yaml/.json (OpenAPI v3.0)
|
||||
- Endpoints auto-added to Endpoint Management
|
||||
- Action: Log | Block | None
|
||||
- Body inspection: JSON payloads
|
||||
```
|
||||
|
||||
**Change validation action:**
|
||||
```
|
||||
Security > API Shield > Settings > Schema Validation
|
||||
Per-endpoint: Filter → ellipses → Change action
|
||||
Default action: Set global mitigation action
|
||||
```
|
||||
|
||||
**Migration from Classic:**
|
||||
```
|
||||
1. Export existing schema (if available)
|
||||
2. Delete all Classic schema validation rules
|
||||
3. Wait 5 min for cache clear
|
||||
4. Re-upload via Schema Validation 2.0 interface
|
||||
5. Verify in Security > Events
|
||||
```
|
||||
|
||||
**Fallthrough rule** (catch-all unknown endpoints):
|
||||
```
|
||||
Security > API Shield > Settings > Fallthrough > Use Template
|
||||
- Select hostnames
|
||||
- Create rule with cf.api_gateway.fallthrough_triggered
|
||||
- Action: Log (discover) or Block (strict)
|
||||
```
|
||||
|
||||
**Body inspection:** Supports `application/json`, `*/*`, `application/*`. Disable origin MIME sniffing to prevent bypasses.
|
||||
|
||||
## JWT Validation
|
||||
|
||||
**Setup token config:**
|
||||
```
|
||||
Security > API Shield > Settings > JWT Settings > Add configuration
|
||||
- Name: "Auth0 JWT Config"
|
||||
- Location: Header/Cookie + name (e.g., "Authorization")
|
||||
- JWKS: Paste public keys from IdP
|
||||
```
|
||||
|
||||
**Create validation rule:**
|
||||
```
|
||||
Security > API Shield > API Rules > Add rule
|
||||
- Hostname: api.example.com
|
||||
- Deselect endpoints to ignore
|
||||
- Token config: Select config
|
||||
- Enforce presence: Ignore or Mark as non-compliant
|
||||
- Action: Log/Block/Challenge
|
||||
```
|
||||
|
||||
**Rate limit by JWT claim:**
|
||||
```wirefilter
|
||||
lookup_json_string(http.request.jwt.claims["{config_id}"][0], "sub")
|
||||
```
|
||||
|
||||
**Special cases:**
|
||||
- Two JWTs, different IdPs: Create 2 configs, select both, "Validate all"
|
||||
- IdP migration: 2 configs + 2 rules, adjust actions per state
|
||||
- Bearer prefix: API Shield handles with/without
|
||||
- Nested claims: Dot notation `user.email`
|
||||
|
||||
## Mutual TLS (mTLS)
|
||||
|
||||
**Setup:**
|
||||
```
|
||||
SSL/TLS > Client Certificates > Create Certificate
|
||||
- Generate CF-managed CA (all plans)
|
||||
- Upload custom CA (Enterprise, max 5)
|
||||
```
|
||||
|
||||
**Configure mTLS rule:**
|
||||
```
|
||||
Security > API Shield > mTLS
|
||||
- Select hostname(s)
|
||||
- Choose certificate(s)
|
||||
- Action: Block/Log/Challenge
|
||||
```
|
||||
|
||||
**Test:**
|
||||
```bash
|
||||
openssl req -x509 -newkey rsa:4096 -keyout client-key.pem -out client-cert.pem -days 365
|
||||
curl https://api.example.com/endpoint --cert client-cert.pem --key client-key.pem
|
||||
```
|
||||
|
||||
## Session Identifiers
|
||||
|
||||
Critical for BOLA Detection, Sequence Mitigation, and analytics. Configure header/cookie that uniquely IDs API users.
|
||||
|
||||
**Examples:** JWT sub claim, session token, API key, custom user ID header
|
||||
|
||||
**Configure:**
|
||||
```
|
||||
Security > API Shield > Settings > Session Identifiers
|
||||
- Type: Header/Cookie
|
||||
- Name: "X-User-ID" or "Authorization"
|
||||
```
|
||||
|
||||
## BOLA Detection
|
||||
|
||||
Detects Broken Object Level Authorization attacks (enumeration + parameter pollution).
|
||||
|
||||
**Enable:**
|
||||
```
|
||||
Security > API Shield > Schema Validation > [Select Schema] > BOLA Detection
|
||||
- Enable detection
|
||||
- Threshold: Sensitivity level (Low/Medium/High)
|
||||
- Action: Log or Block
|
||||
```
|
||||
|
||||
**Requirements:**
|
||||
- Schema Validation 2.0 enabled
|
||||
- Session identifiers configured
|
||||
- Minimum traffic: 1000+ requests/day per endpoint
|
||||
|
||||
## Authentication Posture
|
||||
|
||||
Identifies unprotected or inconsistently protected endpoints.
|
||||
|
||||
**View report:**
|
||||
```
|
||||
Security > API Shield > Authentication Posture
|
||||
- Shows endpoints lacking JWT/mTLS
|
||||
- Highlights mixed authentication patterns
|
||||
```
|
||||
|
||||
**Remediate:**
|
||||
1. Review flagged endpoints
|
||||
2. Add JWT validation rules
|
||||
3. Configure mTLS for sensitive endpoints
|
||||
4. Monitor posture score
|
||||
|
||||
## Volumetric Abuse + GraphQL
|
||||
|
||||
**Volumetric Abuse Detection:**
|
||||
`Security > API Shield > Settings > Volumetric Abuse Detection`
|
||||
- Enable per-endpoint monitoring, set thresholds, action: Log | Challenge | Block
|
||||
|
||||
**GraphQL Protection:**
|
||||
`Security > API Shield > Settings > GraphQL Protection`
|
||||
- Max query depth: 10, max size: 100KB, block introspection (production)
|
||||
|
||||
## Terraform
|
||||
|
||||
```hcl
|
||||
# Session identifier
|
||||
resource "cloudflare_api_shield" "main" {
|
||||
zone_id = var.zone_id
|
||||
auth_id_characteristics {
|
||||
type = "header"
|
||||
name = "Authorization"
|
||||
}
|
||||
}
|
||||
|
||||
# Add endpoint
|
||||
resource "cloudflare_api_shield_operation" "users_get" {
|
||||
zone_id = var.zone_id
|
||||
method = "GET"
|
||||
host = "api.example.com"
|
||||
endpoint = "/api/users/{id}"
|
||||
}
|
||||
|
||||
# JWT validation rule
|
||||
resource "cloudflare_ruleset" "jwt_validation" {
|
||||
zone_id = var.zone_id
|
||||
name = "API JWT Validation"
|
||||
kind = "zone"
|
||||
phase = "http_request_firewall_custom"
|
||||
|
||||
rules {
|
||||
action = "block"
|
||||
expression = "(http.host eq \"api.example.com\" and not is_jwt_valid(http.request.jwt.payload[\"{config_id}\"][0]))"
|
||||
description = "Block invalid JWTs"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [api.md](api.md) - API endpoints and Workers integration
|
||||
- [patterns.md](patterns.md) - Firewall rules and deployment patterns
|
||||
- [gotchas.md](gotchas.md) - Troubleshooting and limits
|
||||
@@ -0,0 +1,125 @@
|
||||
# Gotchas & Troubleshooting
|
||||
|
||||
## Common Errors
|
||||
|
||||
### "Schema Validation 2.0 not working after migration"
|
||||
|
||||
**Cause:** Classic rules still active, conflicting with new system
|
||||
**Solution:**
|
||||
1. Delete ALL Classic schema validation rules
|
||||
2. Clear Cloudflare cache (wait 5 min)
|
||||
3. Re-upload schema via new Schema Validation 2.0 interface
|
||||
4. Verify in Security > Events
|
||||
5. Check action is set (Log/Block)
|
||||
|
||||
### "Schema validation blocking valid requests"
|
||||
|
||||
**Cause:** Schema too restrictive, missing fields, or incorrect types
|
||||
**Solution:**
|
||||
1. Check Firewall Events for violation details
|
||||
2. Review schema in Settings
|
||||
3. Test schema in Swagger Editor
|
||||
4. Use Log mode to validate before blocking
|
||||
5. Update schema with correct specifications
|
||||
6. Ensure Schema Validation 2.0 (not Classic)
|
||||
|
||||
### "JWT validation failing"
|
||||
|
||||
**Cause:** JWKS mismatch with IdP, expired token, wrong header/cookie name, or clock skew
|
||||
**Solution:**
|
||||
1. Verify JWKS matches IdP configuration
|
||||
2. Check token `exp` claim is valid
|
||||
3. Confirm header/cookie name matches config
|
||||
4. Test token at jwt.io
|
||||
5. Account for clock skew (±5 min tolerance)
|
||||
6. Use modern syntax: `is_jwt_valid(http.request.jwt.payload["{config_id}"][0])`
|
||||
|
||||
### "BOLA detection false positives"
|
||||
|
||||
**Cause:** Legitimate sequential access patterns, bulk operations, or sensitivity too high
|
||||
**Solution:**
|
||||
1. Review BOLA events in Security > Events
|
||||
2. Lower sensitivity threshold (High → Medium → Low)
|
||||
3. Exclude legitimate bulk operations from detection
|
||||
4. Ensure session identifiers uniquely identify users
|
||||
5. Verify minimum traffic requirements met (1000+ req/day)
|
||||
|
||||
### "Risk labels not appearing in firewall rules"
|
||||
|
||||
**Cause:** Feature not enabled, insufficient traffic, or missing session identifiers
|
||||
**Solution:**
|
||||
1. Verify Schema Validation 2.0 enabled
|
||||
2. Enable BOLA Detection in schema settings
|
||||
3. Configure session identifiers (required for BOLA)
|
||||
4. Wait 24-48h for ML model training
|
||||
5. Check minimum traffic thresholds met
|
||||
|
||||
### "Endpoint discovery not finding APIs"
|
||||
|
||||
**Cause:** Insufficient traffic (<500 reqs/10d), non-2xx responses, Worker direct requests, or incorrect session ID config
|
||||
**Solution:** Ensure 500+ requests in 10 days, 2xx responses from edge (not Workers direct), configure session IDs correctly. ML updates daily.
|
||||
|
||||
### "Sequence detection false positives"
|
||||
|
||||
**Cause:** Lookback window issues, non-unique session IDs, or model sensitivity
|
||||
**Solution:**
|
||||
1. Review lookback settings (10 reqs to managed endpoints, 10min window)
|
||||
2. Ensure session ID uniqueness per user (not shared tokens)
|
||||
3. Adjust positive/negative model balance
|
||||
4. Exclude legitimate workflows from detection
|
||||
|
||||
### "GraphQL protection blocking valid queries"
|
||||
|
||||
**Cause:** Query depth/size limits too restrictive, complex but legitimate queries
|
||||
**Solution:**
|
||||
1. Review blocked query patterns in Security > Events
|
||||
2. Increase max_depth (default: 10) if needed
|
||||
3. Increase max_size (default: 100KB) for complex queries
|
||||
4. Whitelist specific query signatures
|
||||
5. Use Log mode to tune before blocking
|
||||
|
||||
### "Token invalid"
|
||||
|
||||
**Cause:** Configuration error, JWKS mismatch, or expired token
|
||||
**Solution:** Verify config matches IdP, update JWKS, check token expiration
|
||||
|
||||
### "Schema violation"
|
||||
|
||||
**Cause:** Missing required fields, wrong data types, or spec mismatch
|
||||
**Solution:** Review schema against actual requests, ensure all required fields present, validate types match spec
|
||||
|
||||
### "Fallthrough"
|
||||
|
||||
**Cause:** Unknown endpoint or pattern mismatch
|
||||
**Solution:** Update schema with all endpoints, check path pattern matching
|
||||
|
||||
### "mTLS failed"
|
||||
|
||||
**Cause:** Certificate untrusted/expired or wrong CA
|
||||
**Solution:** Verify cert chain, check expiration, confirm correct CA uploaded
|
||||
|
||||
## Limits (2026)
|
||||
|
||||
| Resource/Limit | Value | Notes |
|
||||
|----------------|-------|-------|
|
||||
| OpenAPI version | v3.0.x only | No external refs, must be valid |
|
||||
| Schema operations | 10K (Enterprise) | Contact for higher limits |
|
||||
| JWT validation sources | Headers/cookies only | No query params/body |
|
||||
| Endpoint discovery | 500+ reqs/10d | Minimum for ML model |
|
||||
| Path normalization | Automatic | `/profile/238` → `/profile/{var1}` |
|
||||
| Schema parameters | No `content` field | No object param validation |
|
||||
| BOLA detection | 1000+ reqs/day/endpoint | Per-endpoint minimum |
|
||||
| Session ID uniqueness | Required | BOLA/Sequence need unique IDs |
|
||||
| GraphQL max depth | 1-50 | Default: 10 |
|
||||
| GraphQL max size | 1KB-1MB | Default: 100KB |
|
||||
| JWT claim nesting | 10 levels max | Use dot notation |
|
||||
| mTLS CA certificates | 5 custom max | CF-managed unlimited |
|
||||
| Schema upload size | 5MB max | Compressed OpenAPI spec |
|
||||
| Volumetric abuse baseline | 7 days training | Initial ML period |
|
||||
| Auth Posture refresh | Daily | Updated nightly |
|
||||
|
||||
## See Also
|
||||
|
||||
- [configuration.md](configuration.md) - Setup guides to avoid common issues
|
||||
- [patterns.md](patterns.md) - Best practices and progressive rollout
|
||||
- [API Shield Docs](https://developers.cloudflare.com/api-shield/)
|
||||
@@ -0,0 +1,180 @@
|
||||
# Patterns & Use Cases
|
||||
|
||||
## Protect API with Schema + JWT
|
||||
|
||||
```bash
|
||||
# 1. Upload OpenAPI schema
|
||||
POST /zones/{zone_id}/api_gateway/user_schemas
|
||||
|
||||
# 2. Configure JWT validation
|
||||
POST /zones/{zone_id}/api_gateway/token_validation
|
||||
{
|
||||
"name": "Auth0",
|
||||
"location": {"header": "Authorization"},
|
||||
"jwks": "{...}"
|
||||
}
|
||||
|
||||
# 3. Create JWT rule
|
||||
POST /zones/{zone_id}/api_gateway/jwt_validation_rules
|
||||
|
||||
# 4. Set schema validation action
|
||||
PUT /zones/{zone_id}/api_gateway/settings/schema_validation
|
||||
{"validation_default_mitigation_action": "block"}
|
||||
```
|
||||
|
||||
## Progressive Rollout
|
||||
|
||||
```
|
||||
1. Log mode: Observe false positives
|
||||
- Schema: Action = Log
|
||||
- JWT: Action = Log
|
||||
|
||||
2. Block subset: Protect critical endpoints
|
||||
- Change specific endpoint actions to Block
|
||||
- Monitor firewall events
|
||||
|
||||
3. Full enforcement: Block all violations
|
||||
- Change default action to Block
|
||||
- Handle fallthrough with custom rule
|
||||
```
|
||||
|
||||
## BOLA Detection
|
||||
|
||||
### Enumeration Detection
|
||||
Detects sequential resource access (e.g., `/users/1`, `/users/2`, `/users/3`).
|
||||
|
||||
```javascript
|
||||
// Block BOLA enumeration attempts
|
||||
(cf.api_gateway.cf-risk-bola-enumeration and http.host eq "api.example.com")
|
||||
// Action: Block or Challenge
|
||||
```
|
||||
|
||||
### Parameter Pollution
|
||||
Detects duplicate/excessive parameters in requests.
|
||||
|
||||
```javascript
|
||||
// Block parameter pollution
|
||||
(cf.api_gateway.cf-risk-bola-pollution and http.host eq "api.example.com")
|
||||
// Action: Block
|
||||
```
|
||||
|
||||
### Combined BOLA Protection
|
||||
```javascript
|
||||
// Comprehensive BOLA rule
|
||||
(cf.api_gateway.cf-risk-bola-enumeration or cf.api_gateway.cf-risk-bola-pollution)
|
||||
and http.host eq "api.example.com"
|
||||
// Action: Block
|
||||
```
|
||||
|
||||
## Authentication Posture
|
||||
|
||||
### Detect Missing Auth
|
||||
```javascript
|
||||
// Log endpoints lacking authentication
|
||||
(cf.api_gateway.cf-risk-missing-auth and http.host eq "api.example.com")
|
||||
// Action: Log (for audit)
|
||||
```
|
||||
|
||||
### Detect Mixed Auth
|
||||
```javascript
|
||||
// Alert on inconsistent auth patterns
|
||||
(cf.api_gateway.cf-risk-mixed-auth and http.host eq "api.example.com")
|
||||
// Action: Log (review required)
|
||||
```
|
||||
|
||||
## Fallthrough Detection (Shadow APIs)
|
||||
|
||||
```javascript
|
||||
// WAF Custom Rule
|
||||
(cf.api_gateway.fallthrough_triggered and http.host eq "api.example.com")
|
||||
// Action: Log (discover unknown) or Block (strict)
|
||||
```
|
||||
|
||||
## Rate Limiting by User
|
||||
|
||||
```javascript
|
||||
// Rate Limiting Rule (modern syntax)
|
||||
(http.host eq "api.example.com" and
|
||||
is_jwt_valid(http.request.jwt.payload["{config_id}"][0]))
|
||||
|
||||
// Rate: 100 req/60s
|
||||
// Counting expression: lookup_json_string(http.request.jwt.payload["{config_id}"][0], "sub")
|
||||
```
|
||||
|
||||
## Volumetric Abuse Response
|
||||
|
||||
```javascript
|
||||
// Detect abnormal traffic spikes
|
||||
(cf.api_gateway.volumetric_abuse_detected and http.host eq "api.example.com")
|
||||
// Action: Challenge or Rate Limit
|
||||
|
||||
// Combined with rate limiting
|
||||
(cf.api_gateway.volumetric_abuse_detected or
|
||||
cf.threat_score gt 50) and http.host eq "api.example.com"
|
||||
// Action: JS Challenge
|
||||
```
|
||||
|
||||
## GraphQL Protection
|
||||
|
||||
```javascript
|
||||
// Block oversized queries
|
||||
(http.request.uri.path eq "/graphql" and
|
||||
cf.api_gateway.graphql_query_size gt 100000)
|
||||
// Action: Block
|
||||
|
||||
// Block deep nested queries
|
||||
(http.request.uri.path eq "/graphql" and
|
||||
cf.api_gateway.graphql_query_depth gt 10)
|
||||
// Action: Block
|
||||
```
|
||||
|
||||
## Architecture Patterns
|
||||
|
||||
**Public API:** Discovery + Schema Validation 2.0 + JWT + Rate Limiting + Bot Management
|
||||
**Partner API:** mTLS + Schema Validation + Sequence Mitigation
|
||||
**Internal API:** Discovery + Schema Learning + Auth Posture
|
||||
|
||||
## OWASP API Security Top 10 Mapping (2026)
|
||||
|
||||
| OWASP Issue | API Shield Solutions |
|
||||
|-------------|---------------------|
|
||||
| API1:2023 Broken Object Level Authorization | **BOLA Detection** (enumeration + pollution), Sequence mitigation, Schema, JWT, Rate Limiting |
|
||||
| API2:2023 Broken Authentication | **Auth Posture**, mTLS, JWT validation, Bot Management |
|
||||
| API3:2023 Broken Object Property Auth | Schema validation, JWT validation |
|
||||
| API4:2023 Unrestricted Resource Access | Rate Limiting, **Volumetric Abuse Detection**, **GraphQL Protection**, Bot Management |
|
||||
| API5:2023 Broken Function Level Auth | Schema validation, JWT validation, Auth Posture |
|
||||
| API6:2023 Unrestricted Business Flows | Sequence mitigation, Bot Management |
|
||||
| API7:2023 SSRF | Schema validation, WAF managed rules |
|
||||
| API8:2023 Security Misconfiguration | **Schema Validation 2.0**, Auth Posture, WAF rules |
|
||||
| API9:2023 Improper Inventory Management | **API Discovery**, Schema learning, Auth Posture |
|
||||
| API10:2023 Unsafe API Consumption | JWT validation, Schema validation, WAF managed |
|
||||
|
||||
## Monitoring
|
||||
|
||||
**Security Events:** `Security > Events` → Filter: Action = block, Service = API Shield
|
||||
**Firewall Analytics:** `Analytics > Security` → Filter by `cf.api_gateway.*` fields
|
||||
**Logpush fields:** APIGatewayAuthIDPresent, APIGatewayRequestViolatesSchema, APIGatewayFallthroughDetected, JWTValidationResult
|
||||
|
||||
## Availability (2026)
|
||||
|
||||
| Feature | Availability | Notes |
|
||||
|---------|-------------|-------|
|
||||
| mTLS (CF-managed CA) | All plans | Self-service |
|
||||
| Endpoint Management | All plans | Limited operations |
|
||||
| Schema Validation 2.0 | All plans | Limited operations |
|
||||
| API Discovery | Enterprise | 10K+ ops |
|
||||
| JWT Validation | Enterprise add-on | Full validation |
|
||||
| BOLA Detection | Enterprise add-on | Requires session IDs |
|
||||
| Auth Posture | Enterprise add-on | Security audit |
|
||||
| Volumetric Abuse Detection | Enterprise add-on | Traffic analysis |
|
||||
| GraphQL Protection | Enterprise add-on | Query limits |
|
||||
| Sequence Mitigation | Enterprise (beta) | Contact team |
|
||||
| Full Suite | Enterprise add-on | All features |
|
||||
|
||||
**Enterprise limits:** 10K operations (contact for higher). Preview access available for non-contract evaluation.
|
||||
|
||||
## See Also
|
||||
|
||||
- [configuration.md](configuration.md) - Setup all features before creating rules
|
||||
- [api.md](api.md) - Firewall field reference and API endpoints
|
||||
- [gotchas.md](gotchas.md) - Common issues and limits
|
||||
Reference in New Issue
Block a user