20 KiB
20 KiB
# Cognition Flow Diagram
## How a Single Query Travels Through the CLOUDFLARE Infrastructure
Implements: The Fourfold Work from RED-BOOK.md — Nigredo → Albedo → Citrinitas → Rubedo
See Also: 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 for the pre-boot classifier and routing membrane.
Layer 0 Spec: 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_stagingin 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).