# 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:

```bash
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`):

```yaml
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`:

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

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

```jsonc
"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`):

```bash
#!/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