@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/cloudflare-deploy/references/waf/README.md

@@ -0,0 +1,113 @@
+# Cloudflare WAF Expert Skill Reference
+
+**Expertise**: Cloudflare Web Application Firewall (WAF) configuration, custom rules, managed rulesets, rate limiting, attack detection, and API integration
+
+## Overview
+
+Cloudflare WAF protects web applications from attacks through managed rulesets and custom rules.
+
+**Detection (Managed Rulesets)**
+- Pre-configured rules maintained by Cloudflare
+- CVE-based rules, OWASP Top 10 coverage
+- Three main rulesets: Cloudflare Managed, OWASP CRS, Exposed Credentials
+- Actions: log, block, challenge, js_challenge, managed_challenge
+
+**Mitigation (Custom Rules & Rate Limiting)**
+- Custom expressions using Wirefilter syntax
+- Attack score-based blocking (`cf.waf.score`)
+- Rate limiting with per-IP, per-user, or custom characteristics
+- Actions: block, challenge, js_challenge, managed_challenge, log, skip
+
+## Quick Start
+
+### Deploy Cloudflare Managed Ruleset
+```typescript
+import Cloudflare from 'cloudflare';
+
+const client = new Cloudflare({ apiToken: process.env.CF_API_TOKEN });
+
+// Deploy managed ruleset to zone
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_request_firewall_managed',
+  name: 'Deploy Cloudflare Managed Ruleset',
+  rules: [{
+    action: 'execute',
+    action_parameters: {
+      id: 'efb7b8c949ac4650a09736fc376e9aee', // Cloudflare Managed Ruleset
+    },
+    expression: 'true',
+    enabled: true,
+  }],
+});
+```
+
+### Create Custom Rule
+```typescript
+// Block requests with attack score >= 40
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_request_firewall_custom',
+  name: 'Custom WAF Rules',
+  rules: [{
+    action: 'block',
+    expression: 'cf.waf.score gt 40',
+    description: 'Block high attack scores',
+    enabled: true,
+  }],
+});
+```
+
+### Create Rate Limit
+```typescript
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_ratelimit',
+  name: 'API Rate Limits',
+  rules: [{
+    action: 'block',
+    expression: 'http.request.uri.path eq "/api/login"',
+    action_parameters: {
+      ratelimit: {
+        characteristics: ['cf.colo.id', 'ip.src'],
+        period: 60,
+        requests_per_period: 10,
+        mitigation_timeout: 600,
+      },
+    },
+    enabled: true,
+  }],
+});
+```
+
+## Managed Ruleset Quick Reference
+
+| Ruleset Name | ID | Coverage |
+|--------------|----|---------| 
+| Cloudflare Managed | `efb7b8c949ac4650a09736fc376e9aee` | OWASP Top 10, CVEs |
+| OWASP Core Ruleset | `4814384a9e5d4991b9815dcfc25d2f1f` | OWASP ModSecurity CRS |
+| Exposed Credentials Check | `c2e184081120413c86c3ab7e14069605` | Credential stuffing |
+
+## Phases
+
+WAF rules execute in specific phases:
+- `http_request_firewall_managed` - Managed rulesets
+- `http_request_firewall_custom` - Custom rules
+- `http_ratelimit` - Rate limiting rules
+- `http_request_sbfm` - Super Bot Fight Mode (Pro+)
+
+## Reading Order
+
+1. **[api.md](api.md)** - SDK methods, expressions, actions, parameters
+2. **[configuration.md](configuration.md)** - Setup with Wrangler, Terraform, Pulumi
+3. **[patterns.md](patterns.md)** - Common patterns: deploy managed, rate limiting, skip, override
+4. **[gotchas.md](gotchas.md)** - Execution order, limits, expression errors
+
+## See Also
+
+- [Cloudflare WAF Docs](https://developers.cloudflare.com/waf/)
+- [Ruleset Engine](https://developers.cloudflare.com/ruleset-engine/)
+- [Expression Reference](https://developers.cloudflare.com/ruleset-engine/rules-language/)

package/skills/cloudflare-deploy/references/waf/api.md

@@ -0,0 +1,202 @@
+# API Reference
+
+## SDK Setup
+
+```typescript
+import Cloudflare from 'cloudflare';
+
+const client = new Cloudflare({
+  apiToken: process.env.CF_API_TOKEN,
+});
+```
+
+## Core Methods
+
+```typescript
+// List rulesets
+await client.rulesets.list({ zone_id: 'zone_id', phase: 'http_request_firewall_managed' });
+
+// Get ruleset
+await client.rulesets.get({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' });
+
+// Create ruleset
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_request_firewall_custom',
+  name: 'Custom WAF Rules',
+  rules: [{ action: 'block', expression: 'cf.waf.score gt 40', enabled: true }],
+});
+
+// Update ruleset (include rule id to keep existing, omit id for new rules)
+await client.rulesets.update({
+  zone_id: 'zone_id',
+  ruleset_id: 'ruleset_id',
+  rules: [
+    { id: 'rule_id', action: 'block', expression: 'cf.waf.score gt 40', enabled: true },
+    { action: 'challenge', expression: 'http.request.uri.path contains "/admin"', enabled: true },
+  ],
+});
+
+// Delete ruleset
+await client.rulesets.delete({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' });
+```
+
+## Actions & Phases
+
+### Actions by Phase
+
+| Action | Custom | Managed | Rate Limit | Description |
+|--------|--------|---------|------------|-------------|
+| `block` | ✅ | ❌ | ✅ | Block request with 403 |
+| `challenge` | ✅ | ❌ | ✅ | Show CAPTCHA challenge |
+| `js_challenge` | ✅ | ❌ | ✅ | JS-based challenge |
+| `managed_challenge` | ✅ | ❌ | ✅ | Smart challenge (recommended) |
+| `log` | ✅ | ❌ | ✅ | Log only, don't block |
+| `skip` | ✅ | ❌ | ❌ | Skip rule evaluation |
+| `execute` | ❌ | ✅ | ❌ | Deploy managed ruleset |
+
+### Phases (Execution Order)
+
+1. `http_request_firewall_custom` - Custom rules (first line of defense)
+2. `http_request_firewall_managed` - Managed rulesets (pre-configured protection)
+3. `http_ratelimit` - Rate limiting (request throttling)
+4. `http_request_sbfm` - Super Bot Fight Mode (Pro+ only)
+
+## Expression Syntax
+
+### Fields
+
+```typescript
+// Request properties
+http.request.method          // GET, POST, etc.
+http.request.uri.path        // /api/users
+http.host                    // example.com
+
+// IP and Geolocation
+ip.src                       // 192.0.2.1
+ip.geoip.country            // US, GB, etc.
+ip.geoip.continent          // NA, EU, etc.
+
+// Attack detection
+cf.waf.score                 // 0-100 attack score
+cf.waf.score.sqli           // SQL injection score
+cf.waf.score.xss            // XSS score
+
+// Headers & Cookies
+http.request.headers["authorization"][0]
+http.request.cookies["session"][0]
+lower(http.user_agent)      // Lowercase user agent
+```
+
+### Operators
+
+```typescript
+// Comparison
+eq      // Equal
+ne      // Not equal
+lt      // Less than
+le      // Less than or equal
+gt      // Greater than
+ge      // Greater than or equal
+
+// String matching
+contains        // Substring match
+matches         // Regex match (use carefully)
+starts_with     // Prefix match
+ends_with       // Suffix match
+
+// List operations
+in              // Value in list
+not             // Logical NOT
+and             // Logical AND
+or              // Logical OR
+```
+
+### Expression Examples
+
+```typescript
+'cf.waf.score gt 40' // Attack score
+'http.request.uri.path eq "/api/login" and http.request.method eq "POST"' // Path + method
+'ip.src in {192.0.2.0/24 203.0.113.0/24}' // IP blocking
+'ip.geoip.country in {"CN" "RU" "KP"}' // Country blocking
+'http.user_agent contains "bot"' // User agent
+'not http.request.headers["authorization"][0]' // Header check
+'(cf.waf.score.sqli gt 20 or cf.waf.score.xss gt 20) and http.request.uri.path starts_with "/api"' // Complex
+```
+
+## Rate Limiting Configuration
+
+```typescript
+{
+  action: 'block',
+  expression: 'http.request.uri.path starts_with "/api"',
+  action_parameters: {
+    ratelimit: {
+      // Characteristics define uniqueness: 'ip.src', 'cf.colo.id', 
+      // 'http.request.headers["key"][0]', 'http.request.cookies["session"][0]'
+      characteristics: ['cf.colo.id', 'ip.src'], // Recommended: per-IP per-datacenter
+      period: 60,                      // Time window in seconds
+      requests_per_period: 100,        // Max requests in period
+      mitigation_timeout: 600,         // Block duration in seconds
+      counting_expression: 'http.request.method ne "GET"', // Optional: filter counted requests
+      requests_to_origin: false,       // Count all requests (not just origin hits)
+    },
+  },
+  enabled: true,
+}
+```
+
+## Managed Ruleset Deployment
+
+```typescript
+{
+  action: 'execute',
+  action_parameters: {
+    id: 'efb7b8c949ac4650a09736fc376e9aee', // Cloudflare Managed
+    overrides: {
+      // Override specific rules
+      rules: [
+        { id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log', enabled: true },
+      ],
+      // Override categories: 'wordpress', 'sqli', 'xss', 'rce', etc.
+      categories: [
+        { category: 'wordpress', enabled: false },
+        { category: 'sqli', action: 'log' },
+      ],
+    },
+  },
+  expression: 'true',
+  enabled: true,
+}
+```
+
+## Skip Rules
+
+Skip rules bypass subsequent rule evaluation. Two skip types:
+
+**Skip current ruleset**: Skip remaining rules in current phase only
+```typescript
+{
+  action: 'skip',
+  action_parameters: {
+    ruleset: 'current', // Skip rest of current ruleset
+  },
+  expression: 'http.request.uri.path ends_with ".jpg" or http.request.uri.path ends_with ".css"',
+  enabled: true,
+}
+```
+
+**Skip entire phases**: Skip one or more phases completely
+```typescript
+{
+  action: 'skip',
+  action_parameters: {
+    phases: ['http_request_firewall_managed', 'http_ratelimit'], // Skip multiple phases
+  },
+  expression: 'ip.src in {192.0.2.0/24 203.0.113.0/24}',
+  enabled: true,
+}
+```
+
+**Note**: Skip rules in custom phase can skip managed/ratelimit phases, but not vice versa (execution order).

package/skills/cloudflare-deploy/references/waf/configuration.md

@@ -0,0 +1,203 @@
+# Configuration
+
+## Prerequisites
+
+**API Token**: Create at https://dash.cloudflare.com/profile/api-tokens
+- Permission: `Zone.WAF Edit` or `Zone.Firewall Services Edit`
+- Zone Resources: Include specific zones or all zones
+
+**Zone ID**: Found in dashboard > Overview > API section (right sidebar)
+
+```bash
+# Set environment variables
+export CF_API_TOKEN="your_api_token_here"
+export ZONE_ID="your_zone_id_here"
+```
+
+## TypeScript SDK Usage
+
+```bash
+npm install cloudflare
+```
+
+```typescript
+import Cloudflare from 'cloudflare';
+
+const client = new Cloudflare({ apiToken: process.env.CF_API_TOKEN });
+
+// Custom rules
+await client.rulesets.create({
+  zone_id: process.env.ZONE_ID,
+  kind: 'zone',
+  phase: 'http_request_firewall_custom',
+  name: 'Custom WAF',
+  rules: [
+    { action: 'block', expression: 'cf.waf.score gt 50', enabled: true },
+    { action: 'challenge', expression: 'http.request.uri.path eq "/admin"', enabled: true },
+  ],
+});
+
+// Managed ruleset
+await client.rulesets.create({
+  zone_id: process.env.ZONE_ID,
+  phase: 'http_request_firewall_managed',
+  rules: [{
+    action: 'execute',
+    action_parameters: { id: 'efb7b8c949ac4650a09736fc376e9aee' },
+    expression: 'true',
+  }],
+});
+
+// Rate limiting
+await client.rulesets.create({
+  zone_id: process.env.ZONE_ID,
+  phase: 'http_ratelimit',
+  rules: [{
+    action: 'block',
+    expression: 'http.request.uri.path starts_with "/api"',
+    action_parameters: {
+      ratelimit: {
+        characteristics: ['cf.colo.id', 'ip.src'],
+        period: 60,
+        requests_per_period: 100,
+        mitigation_timeout: 600,
+      },
+    },
+  }],
+});
+```
+
+## Terraform Configuration
+
+```hcl
+provider "cloudflare" {
+  api_token = var.cloudflare_api_token
+}
+
+resource "cloudflare_ruleset" "waf_custom" {
+  zone_id = var.zone_id
+  kind    = "zone"
+  phase   = "http_request_firewall_custom"
+
+  rules {
+    action     = "block"
+    expression = "cf.waf.score gt 50"
+  }
+}
+```
+
+**Managed Ruleset & Rate Limiting**:
+```hcl
+resource "cloudflare_ruleset" "waf_managed" {
+  zone_id = var.zone_id
+  name    = "Managed Ruleset"
+  kind    = "zone"
+  phase   = "http_request_firewall_managed"
+
+  rules {
+    action = "execute"
+    action_parameters {
+      id = "efb7b8c949ac4650a09736fc376e9aee"
+      overrides {
+        rules {
+          id = "5de7edfa648c4d6891dc3e7f84534ffa"
+          action = "log"
+        }
+      }
+    }
+    expression = "true"
+  }
+}
+
+resource "cloudflare_ruleset" "rate_limiting" {
+  zone_id = var.zone_id
+  phase   = "http_ratelimit"
+
+  rules {
+    action = "block"
+    expression = "http.request.uri.path starts_with \"/api\""
+    ratelimit {
+      characteristics     = ["cf.colo.id", "ip.src"]
+      period              = 60
+      requests_per_period = 100
+      mitigation_timeout  = 600
+    }
+  }
+}
+```
+
+## Pulumi Configuration
+
+```typescript
+import * as cloudflare from '@pulumi/cloudflare';
+
+const zoneId = 'zone_id';
+
+// Custom rules
+const wafCustom = new cloudflare.Ruleset('waf-custom', {
+  zoneId,
+  phase: 'http_request_firewall_custom',
+  rules: [
+    { action: 'block', expression: 'cf.waf.score gt 50', enabled: true },
+    { action: 'challenge', expression: 'http.request.uri.path eq "/admin"', enabled: true },
+  ],
+});
+
+// Managed ruleset
+const wafManaged = new cloudflare.Ruleset('waf-managed', {
+  zoneId,
+  phase: 'http_request_firewall_managed',
+  rules: [{
+    action: 'execute',
+    actionParameters: { id: 'efb7b8c949ac4650a09736fc376e9aee' },
+    expression: 'true',
+  }],
+});
+
+// Rate limiting
+const rateLimiting = new cloudflare.Ruleset('rate-limiting', {
+  zoneId,
+  phase: 'http_ratelimit',
+  rules: [{
+    action: 'block',
+    expression: 'http.request.uri.path starts_with "/api"',
+    ratelimit: {
+      characteristics: ['cf.colo.id', 'ip.src'],
+      period: 60,
+      requestsPerPeriod: 100,
+      mitigationTimeout: 600,
+    },
+  }],
+});
+```
+
+## Dashboard Configuration
+
+1. Navigate to: **Security** > **WAF**
+2. Select tab:
+   - **Managed rules** - Deploy/configure managed rulesets
+   - **Custom rules** - Create custom rules
+   - **Rate limiting rules** - Configure rate limits
+3. Click **Deploy** or **Create rule**
+
+**Testing**: Use Security Events to test expressions before deploying.
+
+## Wrangler Integration
+
+WAF configuration is zone-level (not Worker-specific). Configuration methods:
+- Dashboard UI
+- Cloudflare API via SDK
+- Terraform/Pulumi (IaC)
+
+**Workers benefit from WAF automatically** - no Worker code changes needed.
+
+**Example: Query WAF API from Worker**:
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return fetch(`https://api.cloudflare.com/client/v4/zones/${env.ZONE_ID}/rulesets`, {
+      headers: { 'Authorization': `Bearer ${env.CF_API_TOKEN}` },
+    });
+  },
+};
+```