37a867c485
- Complete Cloudflare Terraform configuration (DNS, WAF, tunnels, access) - WAF Intelligence MCP server with threat analysis and ML classification - GitOps automation with PR workflows and drift detection - Observatory monitoring stack with Prometheus/Grafana - IDE operator rules for governed development - Security playbooks and compliance frameworks - Autonomous remediation and state reconciliation
197 lines
4.0 KiB
Markdown
197 lines
4.0 KiB
Markdown
# 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
|