# terminalkid09/aegis-ecosystem architecture

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

- Interactive diagram: https://gitdiagram.com/terminalkid09/aegis-ecosystem
- Repository: https://github.com/terminalkid09/aegis-ecosystem

## Overview

Aegis is a local-first XDR/SIEM stack: operators use its dashboard and APIs while endpoint agents and log sources submit telemetry; the Brain normalizes and stores events, detects threats, presents alerts, and can trigger response playbooks. The graph also preserves the documented static-analysis, enrichment, notification, and deception capabilities. Relationships are limited to README-documented flows and excerpted calls; Kraken’s broader runtime wiring and several unsampled subsystems are not asserted.

Main entry points: [`aegis-brain/app/services/siem_pipeline.py`](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/siem_pipeline.py) (SIEM Pipeline), [`aegis-brain/app/api/v1/router.py`](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/api/v1/router.py) (Brain API), [`aegis-brain/app/services/playbook_engine.py`](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/playbook_engine.py) (SOAR Playbooks), [`aegis-guard/src/main/java/com/aegis/guard/Main.java`](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-guard/src/main/java/com/aegis/guard/Main.java) (Guard Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator Console"]
  node_frontend["SOC Dashboard<br/>[App.tsx]"]
end

subgraph group_endpoint["Endpoint Agents"]
  node_guard["Guard Agent<br/>[Main.java]"]
  node_systemevent["Endpoint Events<br/>[SystemEvent.java]"]
  node_nodetrace["NodeTrace Agent<br/>[agent.py]"]
  node_kernel["Kernel Sensors<br/>[aegis_exec.bpf.c]"]
end

subgraph group_brain["Aegis Brain"]
  node_api["Brain API<br/>[router.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_security["API Security<br/>[security.py]"]
  node_models["Domain Records<br/>[models.py]"]
  node_database[("Event Database<br/>[connection.py]")]
  node_metrics["Metrics<br/>[metrics.py]"]
  node_config["Brain Settings<br/>[config.py]"]
  node_logging["Structured Logging<br/>[logging.py]"]
  node_retention["Data Retention<br/>[retention.py]"]
end

subgraph group_siem["SIEM Pipeline"]
  node_link["Event Gateway"]
  node_redisqueue["Ingestion Queue<br/>[RedisService.java]"]
  node_ingest["Log Parsers<br/>[base.py]"]
  node_pipeline["SIEM Pipeline<br/>[siem_pipeline.py]"]
  node_store[("SIEM Event Store<br/>[siem_store.py]")]
  node_rules["Static Rules"]
  node_heuristics["Custom Rules"]
  node_sigma["Sigma Engine<br/>[engine.py]"]
  node_correlation["Event Correlation"]
end

subgraph group_response["Response and Enrichment"]
  node_playbooks["SOAR Playbooks<br/>[playbook_engine.py]"]
  node_commands["Agent Commands<br/>[command_queue.py]"]
  node_osint["OSINT Enrichment<br/>[osint_service.py]"]
  node_ai["AI Enrichment<br/>[ai_service.py]"]
  node_telegram["Telegram Alerts"]
  node_pki["Device PKI<br/>[pki.py]"]
end

subgraph group_kraken["Kraken Analysis"]
  node_yara["YARA Scanning<br/>[yara_engine.py]"]
  node_total["File Analysis<br/>[file_analysis.py]"]
  node_deception["Honeypot Sensors<br/>[runner.py]"]
end

node_user(("SOC Operator"))

node_user -->|"uses"| node_frontend
node_frontend -.->|"requests"| node_api
node_api -->|"routes"| node_auth
node_api -->|"secures"| node_security
node_guard -->|"emits"| node_systemevent
node_guard -.->|"submits events"| node_link
node_nodetrace -->|"submits telemetry"| node_api
node_kernel -->|"provides telemetry"| node_guard
node_link -->|"queues events"| node_redisqueue
node_redisqueue -.->|"forwards events"| node_pipeline
node_api -->|"routes log ingestion"| node_pipeline
node_pipeline -->|"parses events"| node_ingest
node_pipeline -->|"stores events"| node_store
node_pipeline -->|"runs detection"| node_sigma
node_pipeline -->|"correlates events"| node_correlation
node_pipeline -.->|"evaluates rules"| node_rules
node_pipeline -.->|"evaluates custom rules"| node_heuristics
node_pipeline -->|"triggers response"| node_playbooks
node_playbooks -->|"queues actions"| node_commands
node_playbooks -->|"records executions"| node_models
node_playbooks -.->|"uses device identity"| node_pki
node_pipeline -->|"notifies"| node_telegram
node_api -->|"offers enrichment"| node_osint
node_api -->|"offers analysis"| node_ai
node_api -->|"exposes scanning"| node_yara
node_api -->|"offers file analysis"| node_total
node_deception -.->|"sends events"| node_pipeline
node_retention -->|"purges expired data"| node_store
node_api -->|"serves metrics"| node_metrics
node_pipeline -->|"creates records"| node_models
node_pipeline -->|"reads settings"| node_config
node_pipeline -->|"logs activity"| node_logging

click node_frontend "https://github.com/terminalkid09/aegis-ecosystem/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/api/v1/router.py"
click node_auth "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/api/v1/auth.py"
click node_security "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/core/security.py"
click node_models "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/database/models.py"
click node_database "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/database/connection.py"
click node_guard "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-guard/src/main/java/com/aegis/guard/Main.java"
click node_systemevent "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-guard/src/main/java/com/aegis/guard/models/SystemEvent.java"
click node_nodetrace "https://github.com/terminalkid09/aegis-ecosystem/blob/main/NodeTrace/agents/python/agent.py"
click node_kernel "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-ebpf/aegis_exec.bpf.c"
click node_link "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-link/src/main/java/com/aegis/link/controllers/IngestionController.java"
click node_redisqueue "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-link/src/main/java/com/aegis/link/service/RedisService.java"
click node_ingest "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/ingest/base.py"
click node_pipeline "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/siem_pipeline.py"
click node_store "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/siem_store.py"
click node_rules "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/rules/rule_definitions.py"
click node_heuristics "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/rules/heuristic_engine.py"
click node_sigma "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/rules/sigma/engine.py"
click node_correlation "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/rules/correlation_engine.py"
click node_playbooks "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/playbook_engine.py"
click node_commands "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/command_queue.py"
click node_osint "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/osint_service.py"
click node_ai "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/ai_service.py"
click node_telegram "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/telegram_notifier.py"
click node_pki "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/pki.py"
click node_yara "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/yara_engine.py"
click node_total "https://github.com/terminalkid09/aegis-ecosystem/blob/main/services/kraken/app/services/file_analysis.py"
click node_deception "https://github.com/terminalkid09/aegis-ecosystem/blob/main/services/kraken/honeypot/runner.py"
click node_metrics "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/core/metrics.py"
click node_config "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/core/config.py"
click node_logging "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/core/logging.py"
click node_retention "https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/retention.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_frontend toneBlue
class node_guard,node_systemevent,node_nodetrace,node_kernel toneAmber
class node_api,node_auth,node_security,node_models,node_database,node_metrics,node_config,node_logging,node_retention toneMint
class node_link,node_redisqueue,node_ingest,node_pipeline,node_store,node_rules,node_heuristics,node_sigma,node_correlation toneRose
class node_playbooks,node_commands,node_osint,node_ai,node_telegram,node_pki,node_user toneIndigo
class node_yara,node_total,node_deception toneTeal
```

## Components

### Operator Console

- [SOC Dashboard](https://github.com/terminalkid09/aegis-ecosystem/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Endpoint Agents

- [Guard Agent](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-guard/src/main/java/com/aegis/guard/Main.java): `aegis-guard/src/main/java/com/aegis/guard/Main.java`
- [Endpoint Events](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-guard/src/main/java/com/aegis/guard/models/SystemEvent.java): `aegis-guard/src/main/java/com/aegis/guard/models/SystemEvent.java`
- [NodeTrace Agent](https://github.com/terminalkid09/aegis-ecosystem/blob/main/NodeTrace/agents/python/agent.py): `NodeTrace/agents/python/agent.py`
- [Kernel Sensors](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-ebpf/aegis_exec.bpf.c): `aegis-ebpf/aegis_exec.bpf.c`

### Aegis Brain

- [Brain API](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/api/v1/router.py): `aegis-brain/app/api/v1/router.py`
- [Authentication](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/api/v1/auth.py): `aegis-brain/app/api/v1/auth.py`
- [API Security](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/core/security.py): `aegis-brain/app/core/security.py`
- [Domain Records](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/database/models.py): `aegis-brain/app/database/models.py`
- [Event Database](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/database/connection.py): `aegis-brain/app/database/connection.py`
- [Metrics](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/core/metrics.py): `aegis-brain/app/core/metrics.py`
- [Brain Settings](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/core/config.py): `aegis-brain/app/core/config.py`
- [Structured Logging](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/core/logging.py): `aegis-brain/app/core/logging.py`
- [Data Retention](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/retention.py): `aegis-brain/app/services/retention.py`

### SIEM Pipeline

- [Event Gateway](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-link/src/main/java/com/aegis/link/controllers/IngestionController.java): `aegis-link/src/main/java/com/aegis/link/controllers/IngestionController.java`
- [Ingestion Queue](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-link/src/main/java/com/aegis/link/service/RedisService.java): `aegis-link/src/main/java/com/aegis/link/service/RedisService.java`
- [Log Parsers](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/ingest/base.py): `aegis-brain/app/ingest/base.py`
- [SIEM Pipeline](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/siem_pipeline.py): `aegis-brain/app/services/siem_pipeline.py`
- [SIEM Event Store](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/siem_store.py): `aegis-brain/app/services/siem_store.py`
- [Static Rules](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/rules/rule_definitions.py): `aegis-brain/app/rules/rule_definitions.py`
- [Custom Rules](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/rules/heuristic_engine.py): `aegis-brain/app/rules/heuristic_engine.py`
- [Sigma Engine](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/rules/sigma/engine.py): `aegis-brain/app/rules/sigma/engine.py`
- [Event Correlation](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/rules/correlation_engine.py): `aegis-brain/app/rules/correlation_engine.py`

### Response and Enrichment

- [SOAR Playbooks](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/playbook_engine.py): `aegis-brain/app/services/playbook_engine.py`
- [Agent Commands](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/command_queue.py): `aegis-brain/app/services/command_queue.py`
- [OSINT Enrichment](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/osint_service.py): `aegis-brain/app/services/osint_service.py`
- [AI Enrichment](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/ai_service.py): `aegis-brain/app/services/ai_service.py`
- [Telegram Alerts](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/telegram_notifier.py): `aegis-brain/app/services/telegram_notifier.py`
- [Device PKI](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/pki.py): `aegis-brain/app/services/pki.py`

### Kraken Analysis

- [YARA Scanning](https://github.com/terminalkid09/aegis-ecosystem/blob/main/aegis-brain/app/services/yara_engine.py): `aegis-brain/app/services/yara_engine.py`
- [File Analysis](https://github.com/terminalkid09/aegis-ecosystem/blob/main/services/kraken/app/services/file_analysis.py): `services/kraken/app/services/file_analysis.py`
- [Honeypot Sensors](https://github.com/terminalkid09/aegis-ecosystem/blob/main/services/kraken/honeypot/runner.py): `services/kraken/honeypot/runner.py`

### Other components

- **SOC Operator**

## Connections

- SOC Operator → SOC Dashboard: uses (evidence: `README.md`)
- SOC Dashboard → Brain API: requests
- Brain API → Authentication: routes (evidence: `aegis-brain/app/api/v1/router.py`)
- Brain API → API Security: secures (evidence: `aegis-brain/app/main.py`)
- Guard Agent → Endpoint Events: emits (evidence: `aegis-guard/src/main/java/com/aegis/guard/Main.java`)
- Guard Agent → Event Gateway: submits events
- NodeTrace Agent → Brain API: submits telemetry (evidence: `README.md`)
- Kernel Sensors → Guard Agent: provides telemetry (evidence: `README.md`)
- Event Gateway → Ingestion Queue: queues events (evidence: `aegis-link/src/main/java/com/aegis/link/controllers/IngestionController.java`)
- Ingestion Queue → SIEM Pipeline: forwards events
- Brain API → SIEM Pipeline: routes log ingestion (evidence: `README.md`)
- SIEM Pipeline → Log Parsers: parses events (evidence: `aegis-brain/app/services/siem_pipeline.py`)
- SIEM Pipeline → SIEM Event Store: stores events (evidence: `aegis-brain/app/services/siem_pipeline.py`)
- SIEM Pipeline → Sigma Engine: runs detection (evidence: `aegis-brain/app/services/siem_pipeline.py`)
- SIEM Pipeline → Event Correlation: correlates events (evidence: `aegis-brain/app/services/siem_pipeline.py`)
- SIEM Pipeline → Static Rules: evaluates rules
- SIEM Pipeline → Custom Rules: evaluates custom rules
- SIEM Pipeline → SOAR Playbooks: triggers response (evidence: `aegis-brain/app/services/siem_pipeline.py`)
- SOAR Playbooks → Agent Commands: queues actions (evidence: `aegis-brain/app/services/playbook_engine.py`)
- SOAR Playbooks → Domain Records: records executions (evidence: `aegis-brain/app/services/playbook_engine.py`)
- SOAR Playbooks → Device PKI: uses device identity (evidence: `aegis-brain/app/services/playbook_engine.py`)
- SIEM Pipeline → Telegram Alerts: notifies (evidence: `aegis-brain/app/services/siem_pipeline.py`)
- Brain API → OSINT Enrichment: offers enrichment (evidence: `README.md`)
- Brain API → AI Enrichment: offers analysis (evidence: `README.md`)
- Brain API → YARA Scanning: exposes scanning (evidence: `aegis-brain/app/services/yara_engine.py`)
- Brain API → File Analysis: offers file analysis (evidence: `README.md`)
- Honeypot Sensors → SIEM Pipeline: sends events
- Data Retention → SIEM Event Store: purges expired data (evidence: `aegis-brain/app/services/retention.py`)
- Brain API → Metrics: serves metrics (evidence: `aegis-brain/app/main.py`)
- SIEM Pipeline → Domain Records: creates records (evidence: `aegis-brain/app/services/siem_pipeline.py`)
- SIEM Pipeline → Brain Settings: reads settings (evidence: `aegis-brain/app/services/siem_pipeline.py`)
- SIEM Pipeline → Structured Logging: logs activity (evidence: `aegis-brain/app/services/siem_pipeline.py`)
