vm-cloudflare/SECURITY_WAF_INTEL.md

WAF Intelligence Guardrail

This document explains how to use the local WAF Intelligence engine to analyze Terraform WAF configuration, generate remediation rules, and map them to compliance frameworks (e.g. PCI-DSS 6.6, OWASP-ASVS 13).

The engine is fully local:

• No external APIs
• No internet required
• Deterministic: same input → same output
• $0 per run

---

1. CLI Usage

From the project root:

cd /Users/sovereign/Desktop/CLOUDFLARE

# Human-readable report
python3 -m mcp.waf_intelligence \
  --file terraform/waf.tf \
  --format text \
  --limit 3

# Machine-readable JSON (for CI/CD or tooling)
python3 -m mcp.waf_intelligence \
  --file terraform/waf.tf \
  --format json \
  --limit 3

# Exit codes / enforcement
python3 -m mcp.waf_intelligence \
  --file terraform/waf.tf \
  --format json \
  --limit 5 \
  --fail-on-error

• Exit code 0 → no error-severity violations
• Exit code 2 → at least one error-severity violation

---

2. CI Integration

A GitHub Actions job can enforce this guardrail on every push/PR.

Example workflow (.github/workflows/waf_intel.yml):

name: WAF Intelligence Guardrail

on:
  push:
    paths:
      - 'terraform/**'
      - 'mcp/waf_intelligence/**'
  pull_request:
    paths:
      - 'terraform/**'
      - 'mcp/waf_intelligence/**'

jobs:
  waf-intel:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          if [ -f requirements.txt ]; then
            pip install -r requirements.txt
          fi

      - name: Run WAF Intelligence (enforced)
        run: |
          python -m mcp.waf_intelligence \
            --file terraform/waf.tf \
            --format text \
            --limit 5 \
            --fail-on-error

This job fails the pipeline if any error-severity issues are found.

---

3. OpenCode / MCP Usage

A local MCP server is registered in opencode.jsonc as waf_intel:

"waf_intel": {
  "type": "local",
  "command": ["python3", "waf_intel_mcp.py"],
  "enabled": true,
  "timeout": 300000
}

waf_intel_mcp.py delegates to the in-repo MCP stdio JSON-RPC implementation (mcp.waf_intelligence.mcp_server), so it does not require installing a separate Python MCP SDK.

The security-audit agent has waf_intel enabled in its tools section:

"security-audit": {
  "tools": {
    "filesystem": true,
    "git": true,
    "github": true,
    "gh_grep": true,
    "waf_intel": true
  }
}

Example: single file from OpenCode

/agent security-audit
Use waf_intel.analyze_waf with:
- file = "terraform/waf.tf"
- limit = 3
- severity_threshold = "warning"

Summarize:
- each finding,
- the suggested Terraform rule,
- and the PCI-DSS / OWASP mappings.

Example: multiple files + only errors

/agent security-audit
Call waf_intel.analyze_waf with:
- files = ["terraform/waf*.tf"]
- limit = 5
- severity_threshold = "error"

List which files have error-level issues and what they are.

The MCP server behind waf_intel supports:

• file: single file path
• files: list of file paths or glob patterns (e.g. "terraform/waf*.tf")
• limit: max insights per file
• severity_threshold: "info" | "warning" | "error"

---

4. Optional: Pre-commit Hook

To prevent committing WAF regressions locally, add this as .git/hooks/pre-commit and mark it executable (chmod +x .git/hooks/pre-commit):

#!/usr/bin/env bash
set -e

echo "[pre-commit] Running WAF Intelligence…"

python3 -m mcp.waf_intelligence \
  --file terraform/waf.tf \
  --format text \
  --limit 3 \
  --fail-on-error

echo "[pre-commit] WAF Intelligence passed."

If an error-severity issue exists, the hook will fail and block the commit.

---

5. What This Gives You

• Local security oracle for Terraform WAF
• Actionable findings (message, severity, confidence, hint)
• Remediation rules (impact / effort scores)
• Compliance mapping (e.g. PCI-DSS 6.6, OWASP-ASVS 13)
• Integration points:
  • CLI (manual and scripts)
  • CI/CD (GitHub Actions, etc.)
  • OpenCode security-audit agent (MCP tool)
  • Pre-commit hooks