update skills

This commit is contained in:
2026-03-17 16:53:22 -07:00
parent 0b0783ef8e
commit f9a530667e
389 changed files with 54512 additions and 1 deletions

View File

@@ -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/)

View 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/)

View File

@@ -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

View File

@@ -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/)

View File

@@ -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