memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,215 @@
+# 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}` },
+    })
+  },
+}
+```

package/skills/cloudflare/references/waf/gotchas.md

@@ -0,0 +1,208 @@
+# Gotchas & Troubleshooting
+
+## Execution Order
+
+**Problem:** Rules execute in unexpected order
+**Cause:** Misunderstanding phase execution
+**Solution:**
+
+Phases execute sequentially (can't be changed):
+
+1. `http_request_firewall_custom` - Custom rules
+2. `http_request_firewall_managed` - Managed rulesets
+3. `http_ratelimit` - Rate limiting
+
+Within phase: top-to-bottom, first match wins (unless `skip`)
+
+```typescript
+// WRONG: Can't mix phase-specific actions
+await client.rulesets.create({
+  phase: 'http_request_firewall_custom',
+  rules: [
+    { action: 'block', expression: 'cf.waf.score gt 50' },
+    { action: 'execute', action_parameters: { id: 'managed_id' } }, // WRONG
+  ],
+});
+
+// CORRECT: Separate rulesets per phase
+await client.rulesets.create({ phase: 'http_request_firewall_custom', rules: [...] });
+await client.rulesets.create({ phase: 'http_request_firewall_managed', rules: [...] });
+```
+
+## Expression Errors
+
+**Problem:** Syntax errors prevent deployment
+**Cause:** Invalid field/operator/syntax
+**Solution:**
+
+```typescript
+// Common mistakes
+'http.request.path' → 'http.request.uri.path' // Correct field
+'ip.geoip.country eq US' → 'ip.geoip.country eq "US"' // Quote strings
+'http.user_agent eq "Mozilla"' → 'lower(http.user_agent) contains "mozilla"' // Case sensitivity
+'matches ".*[.jpg"' → 'matches ".*\\.jpg$"' // Valid regex
+```
+
+Test expressions in Security Events before deploying.
+
+## Skip Rule Pitfalls
+
+**Problem:** Skip rules don't work as expected
+**Cause:** Misunderstanding skip scope
+**Solution:**
+
+Skip types:
+
+- `ruleset: 'current'` - Skip remaining rules in current ruleset only
+- `phases: ['phase_name']` - Skip entire phases
+
+```typescript
+// WRONG: Trying to skip managed rules from custom phase
+// In http_request_firewall_custom:
+{
+  action: 'skip',
+  action_parameters: { ruleset: 'current' },
+  expression: 'ip.src in {192.0.2.0/24}',
+}
+// This only skips remaining custom rules, not managed rules
+
+// CORRECT: Skip specific phases
+{
+  action: 'skip',
+  action_parameters: {
+    phases: ['http_request_firewall_managed', 'http_ratelimit'],
+  },
+  expression: 'ip.src in {192.0.2.0/24}',
+}
+```
+
+## Update Replaces All Rules
+
+**Problem:** Updating ruleset deletes other rules
+**Cause:** `update()` replaces entire rule list
+**Solution:**
+
+```typescript
+// WRONG: This deletes all existing rules!
+await client.rulesets.update({
+  zone_id: 'zone_id',
+  ruleset_id: 'ruleset_id',
+  rules: [{ action: 'block', expression: 'cf.waf.score gt 50' }],
+})
+
+// CORRECT: Get existing rules first
+const ruleset = await client.rulesets.get({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' })
+await client.rulesets.update({
+  zone_id: 'zone_id',
+  ruleset_id: 'ruleset_id',
+  rules: [...ruleset.rules, { action: 'block', expression: 'cf.waf.score gt 50' }],
+})
+```
+
+## Override Conflicts
+
+**Problem:** Managed ruleset overrides don't apply
+**Cause:** Rule ID doesn't exist or category name incorrect
+**Solution:**
+
+```typescript
+// List managed ruleset rules to find IDs
+const ruleset = await client.rulesets.get({
+  zone_id: 'zone_id',
+  ruleset_id: 'efb7b8c949ac4650a09736fc376e9aee',
+});
+console.log(ruleset.rules.map(r => ({ id: r.id, description: r.description })));
+
+// Use correct IDs in overrides
+{ action: 'execute', action_parameters: { id: 'efb7b8c949ac4650a09736fc376e9aee',
+  overrides: { rules: [{ id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log' }] } } }
+```
+
+## False Positives
+
+**Problem:** Legitimate traffic blocked
+**Cause:** Aggressive rules/thresholds
+**Solution:**
+
+1. Start with log mode: `overrides: { action: 'log' }`
+2. Review Security Events to identify false positives
+3. Override specific rules: `overrides: { rules: [{ id: 'rule_id', action: 'log' }] }`
+
+## Rate Limiting NAT Issues
+
+**Problem:** Users behind NAT hit rate limits too quickly
+**Cause:** Multiple users sharing single IP
+**Solution:**
+
+Add more characteristics: User-Agent, session cookie, or authorization header
+
+```typescript
+{
+  action: 'block',
+  expression: 'http.request.uri.path starts_with "/api"',
+  action_parameters: {
+    ratelimit: {
+      characteristics: ['cf.colo.id', 'ip.src', 'http.request.cookies["session"][0]'],
+      period: 60,
+      requests_per_period: 100,
+    },
+  },
+}
+```
+
+## Performance Issues
+
+**Problem:** Increased latency
+**Cause:** Complex expressions, excessive rules
+**Solution:**
+
+1. Skip static assets early: `action: 'skip'` for `\\.(jpg|css|js)$`
+2. Path-based deployment: Only run managed on `/api` or `/admin`
+3. Disable unused categories: `{ category: 'wordpress', enabled: false }`
+4. Prefer string operators over regex: `starts_with` vs `matches`
+
+## Limits & Quotas
+
+| Resource                   | Free       | Pro        | Business   | Enterprise |
+| -------------------------- | ---------- | ---------- | ---------- | ---------- |
+| Custom rules               | 5          | 20         | 100        | 1000       |
+| Rate limiting rules        | 1          | 10         | 25         | 100        |
+| Rule expression length     | 4096 chars | 4096 chars | 4096 chars | 4096 chars |
+| Rules per ruleset          | 75         | 75         | 400        | 1000       |
+| Managed rulesets           | Yes        | Yes        | Yes        | Yes        |
+| Rate limit characteristics | 2          | 3          | 5          | 5          |
+
+**Important Notes:**
+
+- Rules execute in order; first match wins (except skip rules)
+- Expression evaluation stops at first `false` in AND chains
+- `matches` regex operator is slower than string operators
+- Rate limit counting happens before mitigation
+
+## API Errors
+
+**Problem:** API calls fail with cryptic errors
+**Cause:** Invalid parameters or permissions
+**Solution:**
+
+```typescript
+// Error: "Invalid phase" → Use exact phase name
+phase: 'http_request_firewall_custom'
+
+// Error: "Ruleset already exists" → Use update() or list first
+const rulesets = await client.rulesets.list({ zone_id, phase: 'http_request_firewall_custom' });
+if (rulesets.result.length > 0) {
+  await client.rulesets.update({ zone_id, ruleset_id: rulesets.result[0].id, rules: [...] });
+}
+
+// Error: "Action not supported" → Check phase/action compatibility
+// 'execute' only in http_request_firewall_managed
+// Rate limit config only in http_ratelimit phase
+
+// Error: "Expression parse error" → Common fixes:
+'ip.geoip.country eq "US"'   // Quote strings
+'cf.waf.score gt 40'         // Use 'gt' not '>'
+'http.request.uri.path'      // Not 'http.request.path'
+```
+
+**Tip**: Test expressions in dashboard Security Events before deploying.

package/skills/cloudflare/references/waf/patterns.md

@@ -0,0 +1,236 @@
+# Common Patterns
+
+## Deploy Managed Rulesets
+
+```typescript
+// Deploy Cloudflare Managed Ruleset (default)
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_request_firewall_managed',
+  name: 'Cloudflare Managed Ruleset',
+  rules: [
+    {
+      action: 'execute',
+      action_parameters: {
+        id: 'efb7b8c949ac4650a09736fc376e9aee', // Cloudflare Managed
+        // Or: '4814384a9e5d4991b9815dcfc25d2f1f' for OWASP CRS
+        // Or: 'c2e184081120413c86c3ab7e14069605' for Exposed Credentials
+      },
+      expression: 'true', // All requests
+      // Or: 'http.request.uri.path starts_with "/api"' for specific paths
+      enabled: true,
+    },
+  ],
+})
+```
+
+## Override Managed Ruleset
+
+```typescript
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  phase: 'http_request_firewall_managed',
+  rules: [
+    {
+      action: 'execute',
+      action_parameters: {
+        id: 'efb7b8c949ac4650a09736fc376e9aee',
+        overrides: {
+          // Override specific rules
+          rules: [
+            { id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log' },
+            { id: '75a0060762034b9dad4e883afc121b4c', enabled: false },
+          ],
+          // Override categories: wordpress, sqli, xss, rce, etc.
+          categories: [
+            { category: 'wordpress', enabled: false },
+            { category: 'sqli', action: 'log' },
+          ],
+        },
+      },
+      expression: 'true',
+    },
+  ],
+})
+```
+
+## Custom Rules
+
+```typescript
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_request_firewall_custom',
+  name: 'Custom WAF Rules',
+  rules: [
+    // Attack score-based
+    { action: 'block', expression: 'cf.waf.score gt 50', enabled: true },
+    { action: 'challenge', expression: 'cf.waf.score gt 20', enabled: true },
+
+    // Specific attack types
+    {
+      action: 'block',
+      expression: 'cf.waf.score.sqli gt 30 or cf.waf.score.xss gt 30',
+      enabled: true,
+    },
+
+    // Geographic blocking
+    { action: 'block', expression: 'ip.geoip.country in {"CN" "RU"}', enabled: true },
+  ],
+})
+```
+
+## Rate Limiting
+
+```typescript
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_ratelimit',
+  name: 'Rate Limits',
+  rules: [
+    // Per-IP global limit
+    {
+      action: 'block',
+      expression: 'true',
+      action_parameters: {
+        ratelimit: {
+          characteristics: ['cf.colo.id', 'ip.src'],
+          period: 60,
+          requests_per_period: 100,
+          mitigation_timeout: 600,
+        },
+      },
+    },
+
+    // Login endpoint (stricter)
+    {
+      action: 'block',
+      expression: 'http.request.uri.path eq "/api/login"',
+      action_parameters: {
+        ratelimit: {
+          characteristics: ['ip.src'],
+          period: 60,
+          requests_per_period: 5,
+          mitigation_timeout: 600,
+        },
+      },
+    },
+
+    // API writes only (using counting_expression)
+    {
+      action: 'block',
+      expression: 'http.request.uri.path starts_with "/api"',
+      action_parameters: {
+        ratelimit: {
+          characteristics: ['cf.colo.id', 'ip.src'],
+          period: 60,
+          requests_per_period: 50,
+          counting_expression: 'http.request.method ne "GET"',
+        },
+      },
+    },
+  ],
+})
+```
+
+## Skip Rules
+
+```typescript
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_request_firewall_custom',
+  name: 'Skip Rules',
+  rules: [
+    // Skip static assets (current ruleset only)
+    {
+      action: 'skip',
+      action_parameters: { ruleset: 'current' },
+      expression: 'http.request.uri.path matches "\\.(jpg|css|js|woff2?)$"',
+    },
+
+    // Skip all WAF phases for trusted IPs
+    {
+      action: 'skip',
+      action_parameters: {
+        phases: ['http_request_firewall_managed', 'http_ratelimit'],
+      },
+      expression: 'ip.src in {192.0.2.0/24}',
+    },
+  ],
+})
+```
+
+## Complete Setup Example
+
+Combine all three phases for comprehensive protection:
+
+```typescript
+const client = new Cloudflare({ apiToken: process.env.CF_API_TOKEN })
+const zoneId = process.env.ZONE_ID
+
+// 1. Custom rules (execute first)
+await client.rulesets.create({
+  zone_id: zoneId,
+  phase: 'http_request_firewall_custom',
+  rules: [
+    {
+      action: 'skip',
+      action_parameters: { phases: ['http_request_firewall_managed', 'http_ratelimit'] },
+      expression: 'ip.src in {192.0.2.0/24}',
+    },
+    { action: 'block', expression: 'cf.waf.score gt 50' },
+    { action: 'managed_challenge', expression: 'cf.waf.score gt 20' },
+  ],
+})
+
+// 2. Managed ruleset (execute second)
+await client.rulesets.create({
+  zone_id: zoneId,
+  phase: 'http_request_firewall_managed',
+  rules: [
+    {
+      action: 'execute',
+      action_parameters: {
+        id: 'efb7b8c949ac4650a09736fc376e9aee',
+        overrides: { categories: [{ category: 'wordpress', enabled: false }] },
+      },
+      expression: 'true',
+    },
+  ],
+})
+
+// 3. Rate limiting (execute third)
+await client.rulesets.create({
+  zone_id: zoneId,
+  phase: 'http_ratelimit',
+  rules: [
+    {
+      action: 'block',
+      expression: 'true',
+      action_parameters: {
+        ratelimit: {
+          characteristics: ['cf.colo.id', 'ip.src'],
+          period: 60,
+          requests_per_period: 100,
+          mitigation_timeout: 600,
+        },
+      },
+    },
+    {
+      action: 'block',
+      expression: 'http.request.uri.path eq "/api/login"',
+      action_parameters: {
+        ratelimit: {
+          characteristics: ['ip.src'],
+          period: 60,
+          requests_per_period: 5,
+          mitigation_timeout: 600,
+        },
+      },
+    },
+  ],
+})
+```