# balericaai/armageddon architecture

> Architecture diagram of the GitHub repository balericaai/armageddon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/balericaai/armageddon
- Repository: https://github.com/balericaai/armageddon

## Overview

Armageddon is a collection of progressively more capable cloud-security labs, culminating in Agent 11: a governed AI/MCP platform alongside threat-analysis agents. The visible incident-handler workflow gathers cloud logs and configuration evidence, generates an incident report with Bedrock, stores artifacts in S3, and notifies through SNS. Agent 11 separates policy, network assessment, model routing, service runtime, and telemetry. Some lab12 subsystems are substantial but unsampled; their nodes reflect the tree and documented module roles, while uncertain connections are omitted.

Main entry points: [`SEIR_Foundations/lab12/lab12e/mcp/orchestrator.py`](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/mcp/orchestrator.py) (MCP Orchestration), [`SEIR_Foundations/LAB1/lambda/handler.py`](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/LAB1/lambda/handler.py) (Incident Handler), [`SEIR_Foundations/lab12/lab12e/routing/model_router.py`](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/routing/model_router.py) (Model Eligibility), [`SEIR_Foundations/lab12/lab12d/agents/fusion.py`](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12d/agents/fusion.py) (Threat Fusion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cloud_labs["Cloud Evidence Labs"]
  node_incident_lambda["Incident Handler<br/>[handler.py]"]
  node_lab2_cli["Security CLI<br/>[malgus_cli.py]"]
  node_lab2_detectors["Exposure Detectors"]
  node_lab3_evidence["Boundary Evidence"]
  node_report_mergers["Report Mergers"]
end

subgraph group_incident_agents["Incident Agents"]
  node_waf_agent["WAF Correlation"]
  node_soar_agent["SOAR Response"]
  node_dashboard_agent["Executive Dashboard"]
  node_compliance_lambda["Compliance<br/>[compliance.py]"]
end

subgraph group_threat_intel["Threat Intelligence"]
  node_fusion["Threat Fusion<br/>[fusion.py]"]
  node_provider["Threat Providers"]
  node_threat_report["Threat Reports<br/>[report.py]"]
  node_utc_time["UTC Time Helper<br/>[time.py]"]
end

subgraph group_agent_platform["Agent 11 Platform"]
  node_mcp_client["MCP Client<br/>[client.py]"]
  node_mcp_orchestrator["MCP Orchestration<br/>[orchestrator.py]"]
  node_governance["Governance<br/>[orchestrator.py]"]
  node_policy["Policy Evaluation<br/>[orchestrator.py]"]
  node_network["Network Assessment<br/>[orchestrator.py]"]
  node_model_router["Model Eligibility<br/>[model_router.py]"]
  node_ai_runtime["AI Runtime<br/>[orchestrator.py]"]
  node_telemetry["Telemetry Delivery<br/>[orchestrator.py]"]
  node_ai_models["AI Domain Models<br/>[model.py]"]
  node_ai_capability["Capabilities<br/>[capability.py]"]
  node_ai_service["AI Services<br/>[service.py]"]
  node_route_contract["Route Contracts<br/>[routing.py]"]
  node_route_types["Routing Vocabulary<br/>[routing_enums.py]"]
  node_event_types["Telemetry Events<br/>[event.py]"]
end

node_engineer(("Operator"))
node_aws_logs[("Cloud Logs")]
node_aws_config[("Cloud Config")]
node_bedrock{{"Amazon Bedrock"}}
node_s3_reports[("Report Storage")]
node_sns{{"Notifications"}}

node_engineer -->|"invokes"| node_incident_lambda
node_incident_lambda -->|"queries"| node_aws_logs
node_incident_lambda -->|"reads"| node_aws_config
node_incident_lambda -->|"generates report"| node_bedrock
node_incident_lambda -->|"stores artifacts"| node_s3_reports
node_incident_lambda -->|"publishes notice"| node_sns
node_model_router -->|"evaluates models"| node_ai_models
node_model_router -->|"checks capability"| node_ai_capability
node_model_router -->|"checks service"| node_ai_service
node_route_contract -->|"uses vocabulary"| node_route_types
node_network -->|"uses vocabulary"| node_route_types
node_telemetry -->|"coordinates events"| node_event_types
node_provider -->|"uses time helper"| node_utc_time
node_fusion -.->|"collects evidence"| node_provider
node_fusion -.->|"produces findings"| node_threat_report
node_mcp_orchestrator -.->|"dispatches requests"| node_mcp_client
node_mcp_orchestrator -.->|"coordinates governance"| node_governance
node_mcp_orchestrator -.->|"applies policy"| node_policy
node_mcp_orchestrator -.->|"assesses paths"| node_network
node_mcp_orchestrator -.->|"routes requests"| node_model_router
node_mcp_orchestrator -.->|"invokes runtime"| node_ai_runtime
node_mcp_orchestrator -.->|"emits telemetry"| node_telemetry

click node_incident_lambda "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/LAB1/lambda/handler.py"
click node_lab2_cli "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/LAB2/python/malgus_cli.py"
click node_lab2_detectors "https://github.com/balericaai/armageddon/tree/main/SEIR_Foundations/LAB2/python"
click node_lab3_evidence "https://github.com/balericaai/armageddon/tree/main/SEIR_Foundations/Lab3/python"
click node_report_mergers "https://github.com/balericaai/armageddon/tree/main/SEIR_Foundations/Lab5/python"
click node_waf_agent "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/agent/waf_threat_correlation_agent.py"
click node_soar_agent "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12a/agent/soar_response_agent.py"
click node_dashboard_agent "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12b/agent/executive_dashboard_agent.py"
click node_compliance_lambda "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12c/lambda/compliance.py"
click node_fusion "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12d/agents/fusion.py"
click node_provider "https://github.com/balericaai/armageddon/tree/main/SEIR_Foundations/lab12/lab12d/providers"
click node_threat_report "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12d/agents/report.py"
click node_mcp_client "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/mcp/client.py"
click node_mcp_orchestrator "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/mcp/orchestrator.py"
click node_governance "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/mcp/company_onprem_governance/orchestrator.py"
click node_policy "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/policy/orchestrator.py"
click node_network "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/network/orchestrator.py"
click node_model_router "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/routing/model_router.py"
click node_ai_runtime "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/models_runtime/orchestrator.py"
click node_telemetry "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/telemetry/orchestrator.py"
click node_ai_models "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/models/ai/model.py"
click node_ai_capability "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/models/ai/capability.py"
click node_ai_service "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/models/ai/service.py"
click node_route_contract "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/models/ai/routing.py"
click node_route_types "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/models/enums/routing_enums.py"
click node_event_types "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/telemetry/event.py"
click node_utc_time "https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12d/utils/time.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_incident_lambda,node_lab2_cli,node_lab2_detectors,node_lab3_evidence,node_report_mergers toneBlue
class node_waf_agent,node_soar_agent,node_dashboard_agent,node_compliance_lambda,node_aws_logs,node_aws_config,node_s3_reports toneAmber
class node_fusion,node_provider,node_threat_report,node_utc_time toneMint
class node_mcp_client,node_mcp_orchestrator,node_governance,node_policy,node_network,node_model_router,node_ai_runtime,node_telemetry,node_ai_models,node_ai_capability,node_ai_service,node_route_contract,node_route_types,node_event_types toneRose
class node_engineer,node_bedrock,node_sns toneIndigo
```

## Components

### Cloud Evidence Labs

- [Incident Handler](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/LAB1/lambda/handler.py): `SEIR_Foundations/LAB1/lambda/handler.py`
- [Security CLI](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/LAB2/python/malgus_cli.py): `SEIR_Foundations/LAB2/python/malgus_cli.py`
- [Exposure Detectors](https://github.com/balericaai/armageddon/tree/main/SEIR_Foundations/LAB2/python): `SEIR_Foundations/LAB2/python`
- [Boundary Evidence](https://github.com/balericaai/armageddon/tree/main/SEIR_Foundations/Lab3/python): `SEIR_Foundations/Lab3/python`
- [Report Mergers](https://github.com/balericaai/armageddon/tree/main/SEIR_Foundations/Lab5/python): `SEIR_Foundations/Lab5/python`

### Incident Agents

- [WAF Correlation](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/agent/waf_threat_correlation_agent.py): `SEIR_Foundations/lab12/agent/waf_threat_correlation_agent.py`
- [SOAR Response](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12a/agent/soar_response_agent.py): `SEIR_Foundations/lab12/lab12a/agent/soar_response_agent.py`
- [Executive Dashboard](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12b/agent/executive_dashboard_agent.py): `SEIR_Foundations/lab12/lab12b/agent/executive_dashboard_agent.py`
- [Compliance](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12c/lambda/compliance.py): `SEIR_Foundations/lab12/lab12c/lambda/compliance.py`

### Threat Intelligence

- [Threat Fusion](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12d/agents/fusion.py): `SEIR_Foundations/lab12/lab12d/agents/fusion.py`
- [Threat Providers](https://github.com/balericaai/armageddon/tree/main/SEIR_Foundations/lab12/lab12d/providers): `SEIR_Foundations/lab12/lab12d/providers`
- [Threat Reports](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12d/agents/report.py): `SEIR_Foundations/lab12/lab12d/agents/report.py`
- [UTC Time Helper](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12d/utils/time.py): `SEIR_Foundations/lab12/lab12d/utils/time.py`

### Agent 11 Platform

- [MCP Client](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/mcp/client.py): `SEIR_Foundations/lab12/lab12e/mcp/client.py`
- [MCP Orchestration](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/mcp/orchestrator.py): `SEIR_Foundations/lab12/lab12e/mcp/orchestrator.py`
- [Governance](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/mcp/company_onprem_governance/orchestrator.py): `SEIR_Foundations/lab12/lab12e/mcp/company_onprem_governance/orchestrator.py`
- [Policy Evaluation](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/policy/orchestrator.py): `SEIR_Foundations/lab12/lab12e/policy/orchestrator.py`
- [Network Assessment](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/network/orchestrator.py): `SEIR_Foundations/lab12/lab12e/network/orchestrator.py`
- [Model Eligibility](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/routing/model_router.py): `SEIR_Foundations/lab12/lab12e/routing/model_router.py`
- [AI Runtime](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/models_runtime/orchestrator.py): `SEIR_Foundations/lab12/lab12e/models_runtime/orchestrator.py`
- [Telemetry Delivery](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/telemetry/orchestrator.py): `SEIR_Foundations/lab12/lab12e/telemetry/orchestrator.py`
- [AI Domain Models](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/models/ai/model.py): `SEIR_Foundations/lab12/lab12e/models/ai/model.py`
- [Capabilities](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/models/ai/capability.py): `SEIR_Foundations/lab12/lab12e/models/ai/capability.py`
- [AI Services](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/models/ai/service.py): `SEIR_Foundations/lab12/lab12e/models/ai/service.py`
- [Route Contracts](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/models/ai/routing.py): `SEIR_Foundations/lab12/lab12e/models/ai/routing.py`
- [Routing Vocabulary](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/models/enums/routing_enums.py): `SEIR_Foundations/lab12/lab12e/models/enums/routing_enums.py`
- [Telemetry Events](https://github.com/balericaai/armageddon/blob/main/SEIR_Foundations/lab12/lab12e/telemetry/event.py): `SEIR_Foundations/lab12/lab12e/telemetry/event.py`

### Other components

- **Operator**
- **Cloud Logs**
- **Cloud Config**
- **Amazon Bedrock**
- **Report Storage**
- **Notifications**

## Connections

- Operator → Incident Handler: invokes (evidence: `SEIR_Foundations/LAB1/lambda/handler.py`)
- Incident Handler → Cloud Logs: queries (evidence: `SEIR_Foundations/LAB1/lambda/handler.py`)
- Incident Handler → Cloud Config: reads (evidence: `SEIR_Foundations/LAB1/lambda/handler.py`)
- Incident Handler → Amazon Bedrock: generates report (evidence: `SEIR_Foundations/LAB1/lambda/handler.py`)
- Incident Handler → Report Storage: stores artifacts (evidence: `SEIR_Foundations/LAB1/lambda/handler.py`)
- Incident Handler → Notifications: publishes notice (evidence: `SEIR_Foundations/LAB1/lambda/handler.py`)
- Model Eligibility → AI Domain Models: evaluates models (evidence: `SEIR_Foundations/lab12/lab12e/routing/model_router.py`)
- Model Eligibility → Capabilities: checks capability (evidence: `SEIR_Foundations/lab12/lab12e/routing/model_router.py`)
- Model Eligibility → AI Services: checks service (evidence: `SEIR_Foundations/lab12/lab12e/routing/model_router.py`)
- Route Contracts → Routing Vocabulary: uses vocabulary (evidence: `SEIR_Foundations/lab12/lab12e/models/ai/routing.py`)
- Network Assessment → Routing Vocabulary: uses vocabulary (evidence: `SEIR_Foundations/lab12/lab12e/network/orchestrator.py`)
- Telemetry Delivery → Telemetry Events: coordinates events (evidence: `SEIR_Foundations/lab12/lab12e/telemetry/orchestrator.py`)
- Threat Providers → UTC Time Helper: uses time helper (evidence: `SEIR_Foundations/lab12/lab12d/utils/time.py`)
- Threat Fusion → Threat Providers: collects evidence
- Threat Fusion → Threat Reports: produces findings
- MCP Orchestration → MCP Client: dispatches requests
- MCP Orchestration → Governance: coordinates governance
- MCP Orchestration → Policy Evaluation: applies policy
- MCP Orchestration → Network Assessment: assesses paths
- MCP Orchestration → Model Eligibility: routes requests
- MCP Orchestration → AI Runtime: invokes runtime
- MCP Orchestration → Telemetry Delivery: emits telemetry
