@bcelep/capint 0.4.2 → 0.7.0

package/skills/cloudflare/references/api-shield/configuration.md

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

package/skills/cloudflare/references/api-shield/gotchas.md

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

package/skills/cloudflare/references/api-shield/patterns.md

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

package/skills/cloudflare/references/argo-smart-routing/README.md

@@ -0,0 +1,90 @@
+# Cloudflare Argo Smart Routing Skill Reference
+
+## Overview
+
+Cloudflare Argo Smart Routing is a performance optimization service that detects real-time network issues and routes web traffic across the most efficient network path. It continuously monitors network conditions and intelligently routes traffic through the fastest, most reliable routes in Cloudflare's network.
+
+**Note on Smart Shield:** Argo Smart Routing is being integrated into Cloudflare's Smart Shield product for enhanced DDoS protection and performance. Existing Argo customers maintain full functionality with gradual migration to Smart Shield features.
+
+## Quick Start
+
+### Enable via cURL
+```bash
+curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing" \
+  -H "Authorization: Bearer YOUR_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"value": "on"}'
+```
+
+### Enable via TypeScript SDK
+```typescript
+import Cloudflare from 'cloudflare';
+
+const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN });
+
+const result = await client.argo.smartRouting.edit({
+  zone_id: 'your-zone-id',
+  value: 'on',
+});
+
+console.log(`Argo enabled: ${result.value}`);
+```
+
+## Core Concepts
+
+### What It Does
+- **Intelligent routing**: Detects congestion, outages, packet loss in real-time
+- **Global optimization**: Routes across 300+ Cloudflare data centers
+- **Automatic failover**: Switches paths when issues detected (typically <1s)
+- **Works with existing setup**: No origin changes required
+
+### Billing Model
+- Usage-based: Charged per GB of traffic (excluding DDoS/WAF mitigated traffic)
+- Requires billing configuration before enabling
+- Available on Enterprise+ plans (check zone eligibility)
+
+### When to Use
+- **High-traffic production sites** with global user base
+- **Latency-sensitive applications** (APIs, real-time services)
+- **Sites behind Cloudflare proxy** (orange-clouded DNS records)
+- **Combined with Tiered Cache** for maximum performance gains
+
+### When NOT to Use
+- Development/staging environments (cost control)
+- Low-traffic sites (<1TB/month) where cost may exceed benefit
+- Sites with primarily single-region traffic
+
+## Should I Enable Argo?
+
+| Your Situation | Recommendation |
+|----------------|----------------|
+| Global production app, >1TB/month traffic | ✅ Enable - likely ROI positive |
+| Enterprise plan, latency-critical APIs | ✅ Enable - performance matters |
+| Regional site, <100GB/month traffic | ⚠️ Evaluate - cost may not justify |
+| Development/staging environment | ❌ Disable - use in production only |
+| Not yet configured billing | ❌ Configure billing first |
+
+## Reading Order by Task
+
+| Your Goal | Start With | Then Read |
+|-----------|------------|-----------|
+| Enable Argo for first time | Quick Start above → [configuration.md](configuration.md) | [gotchas.md](gotchas.md) |
+| Use TypeScript/Python SDK | [api.md](api.md) | [patterns.md](patterns.md) |
+| Terraform/IaC setup | [configuration.md](configuration.md) | - |
+| Enable for Spectrum TCP app | [patterns.md](patterns.md) → Spectrum section | [api.md](api.md) |
+| Troubleshoot enablement issue | [gotchas.md](gotchas.md) | [api.md](api.md) |
+| Manage billing/usage | [patterns.md](patterns.md) → Billing section | [gotchas.md](gotchas.md) |
+
+## In This Reference
+
+- **[api.md](api.md)** - API endpoints, SDK methods, error handling, Python/TypeScript examples
+- **[configuration.md](configuration.md)** - Terraform setup, environment config, billing configuration
+- **[patterns.md](patterns.md)** - Tiered Cache integration, Spectrum TCP apps, billing management, validation patterns
+- **[gotchas.md](gotchas.md)** - Common errors, permission issues, limits, best practices
+
+## See Also
+
+- [Cloudflare Argo Smart Routing Docs](https://developers.cloudflare.com/argo-smart-routing/)
+- [Cloudflare Smart Shield](https://developers.cloudflare.com/smart-shield/)
+- [Spectrum Documentation](https://developers.cloudflare.com/spectrum/)
+- [Tiered Cache](https://developers.cloudflare.com/cache/how-to/tiered-cache/)