Initial commit: Cloudflare infrastructure with WAF Intelligence
- 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
This commit is contained in:
Vault Sovereign
196
SECURITY_WAF_INTEL.md
Normal file
196
SECURITY_WAF_INTEL.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user