257 lines
20 KiB
Markdown
257 lines
20 KiB
Markdown
---
|
|
|
|
# Cognition Flow Diagram
|
|
## How a Single Query Travels Through the CLOUDFLARE Infrastructure
|
|
|
|
**Implements:** The Fourfold Work from [RED-BOOK.md](RED-BOOK.md) — Nigredo → Albedo → Citrinitas → Rubedo
|
|
|
|
**See Also:** [DEMO_COGNITION.md](DEMO_COGNITION.md) for live transcripts showing the Cognition Flow in action — one blessed query and one forbidden query demonstrating guardrails.
|
|
**Layer 0 Spec:** [LAYER0_SHADOW.md](LAYER0_SHADOW.md) for the pre-boot classifier and routing membrane.
|
|
|
|
---
|
|
|
|
## The Flow (8 Layers, with Layer 0 pre-boot)
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
│ LAYER 0: Shadow Eval (Pre-Boot) │
|
|
│ ────────────────────────────────────────────────────────────────────── │
|
|
│ Before doctrine loads: │
|
|
│ ├─ Classify: blessed | ambiguous | forbidden | catastrophic │
|
|
│ ├─ Topology detect: infra | data | identity | runtime | meta │
|
|
│ ├─ Risk estimate: 1 → 5 │
|
|
│ ├─ Routing: │
|
|
│ │ - blessed → Layer 1 (Boot) │
|
|
│ │ - ambiguous → clarification request (no load) │
|
|
│ │ - forbidden → Layer 4 (Guardrails) direct │
|
|
│ │ - catastrophic → fail closed + log anomalies/preboot_shield.jsonl │
|
|
│ └─ Full spec: LAYER0_SHADOW.md │
|
|
└────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
│ LAYER 1: Boot (Doctrine Load) │
|
|
│ ────────────────────────────────────────────────────────────────────── │
|
|
│ On IDE start: │
|
|
│ ├─ seed_ide_rules.py symlinks IDE_OPERATOR_RULES.md │
|
|
│ ├─ IDE loads: │
|
|
│ │ - AGENTS.md (agent definitions + MCP tool permissions) │
|
|
│ │ - IDE_OPERATOR_RULES.md (Terraform/GitOps/Zero Trust policy) │
|
|
│ │ - FIRST_RUN.md (initial setup + rules summary) │
|
|
│ │ - MULTI_ACCOUNT_AUTH.md (multi-account MCP configuration) │
|
|
│ └─ Result: AI soaked in doctrine before first query │
|
|
└────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
│ LAYER 2: Query Routing │
|
|
│ ────────────────────────────────────────────────────────────────────── │
|
|
│ User query: "add a WAF rule to block bots" │
|
|
│ ├─ Parse intent: Infrastructure change (Cloudflare) │
|
|
│ ├─ Route to agents (from AGENTS.md): │
|
|
│ │ - Primary: cloudflare-ops (has Terraform + Cloudflare tools) │
|
|
│ │ - Secondary: security-audit (for compliance check) │
|
|
│ └─ Select tools needed: │
|
|
│ - gh_grep (find similar patterns) │
|
|
│ - filesystem (read terraform/waf.tf) │
|
|
│ - waf_intelligence (analyze threat, generate rule) │
|
|
│ - cloudflare (query live config if multi-account) │
|
|
└────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
│ LAYER 3: MCP Tool Orchestration │
|
|
│ ────────────────────────────────────────────────────────────────────── │
|
|
│ Step 1: Search Phase (gh_grep MCP) │
|
|
│ ├─ Query: "Cloudflare WAF bot blocking patterns" │
|
|
│ ├─ Result: 12 similar implementations found │
|
|
│ └─ Pattern extracted: cf.bot_management.score lt 30 │
|
|
│ │
|
|
│ Step 2: Context Phase (filesystem MCP) │
|
|
│ ├─ Read: terraform/waf.tf │
|
|
│ ├─ Parse current rules: 4 custom, 2 managed │
|
|
│ └─ Identify insertion point: After resource "cloudflare_ruleset" │
|
|
│ │
|
|
│ Step 3: Intelligence Phase (WAF Intelligence MCP - Phase 7) │
|
|
│ ├─ Load: mcp/waf_intelligence/orchestrator.py │
|
|
│ ├─ Analyze current WAF baseline │
|
|
│ ├─ Check threat intel for bot networks │
|
|
│ ├─ Multi-Account Support (MULTI_ACCOUNT_AUTH.md): │
|
|
│ │ ├─ Detect cross-account query (e.g., "compare prod vs staging") │
|
|
│ │ ├─ Invoke parallel MCPs: │
|
|
│ │ │ - cloudflare_prod: {env:CLOUDFLARE_API_TOKEN_PROD} │
|
|
│ │ │ - cloudflare_staging: {env:CLOUDFLARE_API_TOKEN_STAGING} │
|
|
│ │ ├─ Compare results (e.g., WAF rules diff) │
|
|
│ │ └─ Enforce access: Only if agent.tools permits (opencode.jsonc) │
|
|
│ ├─ Generate rule with ML classifier: │
|
|
│ │ { │
|
|
│ │ "expression": "(cf.bot_management.score lt 30)", │
|
|
│ │ "action": "block", │
|
|
│ │ "confidence": 92, │
|
|
│ │ "severity": "high", │
|
|
│ │ "threat_type": "scanner" │
|
|
│ │ } │
|
|
│ └─ Check auto-deploy criteria: ✓ (confidence ≥ 85%) │
|
|
└────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
│ LAYER 4: Guardrail Validation (AGENT_GUARDRAILS.md) │
|
|
│ ────────────────────────────────────────────────────────────────────── │
|
|
│ Rule 1: Did you search first? (Global Rule #2) │
|
|
│ └─ ✓ gh_grep executed, found patterns │
|
|
│ Rule 2: Terraform only? (Global Rule #1, #5) │
|
|
│ └─ ✓ Generating HCL, not manual dashboard │
|
|
│ Rule 3: No secrets? (IDE_OPERATOR_RULES.md) │
|
|
│ └─ ✓ No API tokens in code │
|
|
│ Rule 4: WAF rule documented? (Global Rule #1) │
|
|
│ └─ ✓ Description includes confidence + threat_type │
|
|
│ Rule 5: Zero Trust? (Global Rule #3) │
|
|
│ └─ ✓ No bypass rules, blocks hostile traffic │
|
|
│ Rule 6: GitOps workflow? (Global Rule #2) │
|
|
│ └─ ✓ Will create PR, not direct apply │
|
|
│ Rule 7: Compliance? (Global Rule #4) │
|
|
│ └─ ✓ Logging enabled, audit trail in observatory/ │
|
|
│ Rule 8: Drift check? (Global Rule #5) │
|
|
│ └─ ✓ terraform validate will run in PR │
|
|
│ │
|
|
│ Result: ✅ ALL GUARDRAILS PASSED │
|
|
└────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
│ LAYER 5: Terraform Generation │
|
|
│ ────────────────────────────────────────────────────────────────────── │
|
|
│ Generate HCL: │
|
|
│ resource "cloudflare_ruleset" "bot_blocking" { │
|
|
│ for_each = cloudflare_zone.domains │
|
|
│ zone_id = each.value.id │
|
|
│ name = "Bot Blocking Rule" │
|
|
│ rules { │
|
|
│ action = "block" │
|
|
│ expression = "(cf.bot_management.score lt 30)" │
|
|
│ description = "Block bots - confidence: 92%, threat: scanner" │
|
|
│ } │
|
|
│ } │
|
|
│ │
|
|
│ Write to: terraform/waf.tf (new block after existing rules) │
|
|
└────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
│ LAYER 6: GitOps Workflow │
|
|
│ ────────────────────────────────────────────────────────────────────── │
|
|
│ Step 1: Create branch │
|
|
│ └─ Branch name: feature/waf-bot-blocking-rule │
|
|
│ Step 2: Stage & commit │
|
|
│ └─ Message: "feat(waf): Add bot blocking (confidence: 92%)" │
|
|
│ Step 3: Push to remote │
|
|
│ Step 4: Create PR │
|
|
│ ├─ Title: Add WAF rule to block low-score bots │
|
|
│ ├─ Description: Auto-generated via WAF Intelligence │
|
|
│ └─ Labels: security, waf, auto-generated │
|
|
│ Step 5: CI/CD triggers │
|
|
│ ├─ terraform validate │
|
|
│ ├─ terraform plan │
|
|
│ └─ Await review + approval │
|
|
└────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
│ LAYER 7: Telemetry & Logging │
|
|
│ ────────────────────────────────────────────────────────────────────── │
|
|
│ Log to: observatory/cognition_flow_logs.jsonl │
|
|
│ { │
|
|
│ "timestamp": "2025-12-09T02:15:00Z", │
|
|
│ "query": "add a WAF rule to block bots", │
|
|
│ "agent": "cloudflare-ops", │
|
|
│ "tools_used": ["gh_grep", "filesystem", "waf_intelligence"], │
|
|
│ "guardrails_passed": true, │
|
|
│ "terraform_generated": true, │
|
|
│ "pr_created": true, │
|
|
│ "pr_number": 42, │
|
|
│ "confidence": 92, │
|
|
│ "threat_type": "scanner" │
|
|
│ } │
|
|
│ │
|
|
│ Also logged: │
|
|
│ ├─ COMPLIANCE_LEDGER.jsonl (if compliance check ran) │
|
|
│ └─ anomalies/*.jsonl (if any guardrail warnings) │
|
|
└────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Summary: The Machine in Motion
|
|
|
|
**Input:** "add a WAF rule to block bots"
|
|
|
|
**Output:**
|
|
- ✅ Terraform HCL generated
|
|
- ✅ PR created (GitOps)
|
|
- ✅ All 8 guardrails passed
|
|
- ✅ Compliance logged
|
|
- ✅ Ready for human review
|
|
|
|
**What Didn't Happen:**
|
|
- ❌ No manual dashboard clicks
|
|
- ❌ No secrets committed
|
|
- ❌ No direct apply (GitOps enforced)
|
|
- ❌ No undocumented rules
|
|
|
|
---
|
|
|
|
## Multi-Account Enhancements
|
|
|
|
From **MULTI_ACCOUNT_AUTH.md**, the flow now supports:
|
|
|
|
**Cross-Account Queries:**
|
|
```
|
|
"Compare production vs staging WAF rules"
|
|
```
|
|
|
|
**Flow Modifications:**
|
|
- Layer 2 (Routing): Detects multi-account intent
|
|
- Layer 3 (MCP): Invokes `cloudflare_prod` + `cloudflare_staging` in parallel
|
|
- Layer 4 (Guardrails): Validates agent has permission for both accounts
|
|
- Layer 5 (Terraform): Generates diff + remediation plan
|
|
- Layer 6 (GitOps): Creates PR with cross-account comparison
|
|
- Layer 7 (Telemetry): Logs which accounts were accessed
|
|
|
|
**Security:** Each agent's `tools` config in `opencode.jsonc` controls which accounts it can access (e.g., `security-audit` only gets `cloudflare_prod`, not staging or dev).
|
|
|
|
---
|
|
|
|
## Error Recovery
|
|
|
|
If any layer fails:
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
│ Error Recovery Sub-Layer │
|
|
│ ────────────────────────────────────────────────────────────────────── │
|
|
│ ├─ Log failure to: anomalies/query_failures.jsonl │
|
|
│ ├─ Retry: Break query into sub-tasks (e.g., search only) │
|
|
│ ├─ Notify: Via slack MCP if configured │
|
|
│ └─ Escalate: If critical (e.g., PCI-DSS flag), require manual review │
|
|
└────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Scalability Note
|
|
|
|
For large projects:
|
|
- **Token limits?** Split into sub-queries (Layer 2)
|
|
- **High volume?** Parallel agents (up to 3)
|
|
- **Multi-account?** Per-environment MCPs (MULTI_ACCOUNT_AUTH.md)
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- **DEMO_COGNITION.md** — Live transcripts (blessed + forbidden queries)
|
|
- **AGENT_GUARDRAILS.md** — The 8 guardrail rules
|
|
- **AGENTS.md** — Agent definitions and MCP tool permissions
|
|
- **IDE_OPERATOR_RULES.md** — Terraform/GitOps/Zero Trust policy
|
|
- **MULTI_ACCOUNT_AUTH.md** — Multi-account MCP configuration
|
|
- **MCP_GUIDE.md** — Complete MCP server reference
|
|
|
|
---
|
|
|
|
**This is the Cognition Engine.** Every query flows through these 8 layers.
|
|
**Shadow Eval → Doctrine → Routing → Tools → Guardrails → Terraform → GitOps → Logs (then back to Shadow Eval).**
|