# essailab/deepxdr architecture

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

- Interactive diagram: https://gitdiagram.com/essailab/deepxdr
- Repository: https://github.com/essailab/deepxdr

## Overview

DeepXDR ingests security telemetry, applies baseline adjudication, correlates high-value events into Short TTPs, and supports longer MITRE ATT&CK investigations with analyst feedback. A separate AgentGuard workflow assesses nono session diffs for intent and change risk, then supports human acceptance or rollback. Analysts use the API and dashboard to inspect results and initiate investigations. The graph follows README-described flows where implementation excerpts were not available; detailed routing and several subsystem internals are therefore represented only at documented boundaries.

Main entry points: [`ai_agent/api_server/routes.py`](https://github.com/essailab/deepxdr/blob/main/ai_agent/api_server/routes.py) (API routes), [`ai_agent/agent_guard/sql_repository.py`](https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/sql_repository.py) (PostgreSQL records), [`ai_agent/mitre_attck_agent/workflows/graph.py`](https://github.com/essailab/deepxdr/blob/main/ai_agent/mitre_attck_agent/workflows/graph.py) (Long TTP investigation), [`ai_agent/api_server/main.py`](https://github.com/essailab/deepxdr/blob/main/ai_agent/api_server/main.py) (FastAPI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Telemetry and adjudication"]
  node_baseline["Baseline adjudication"]
end

subgraph group_threat["Threat analysis"]
  node_consumer["Event consumer<br/>[kafka_consumer.py]"]
  node_windows["Dynamic event windows<br/>[window_manager.py]"]
  node_short_ttp["Short TTP generation"]
  node_attack_rag["ATT&amp;CK analysis<br/>[attack_rag.py]"]
  node_long_workflow["Long TTP investigation<br/>[graph.py]"]
  node_research["Deep research<br/>[deep_researcher.py]"]
  node_feedback["Analyst feedback"]
end

subgraph group_guard["AgentGuard"]
  node_guard_consumer["AgentGuard consumer<br/>[consumer.py]"]
  node_adjudicator["Intent and risk review<br/>[adjudicator.py]"]
  node_risk_rules["Risk rules<br/>[rule_engine.py]"]
  node_rollback["Rollback handling<br/>[rollback.py]"]
  node_publisher["Rollback publisher<br/>[publisher.py]"]
end

subgraph group_data["Persistence"]
  node_es[("Elasticsearch")]
  node_postgres[("PostgreSQL records<br/>[sql_repository.py]")]
end

subgraph group_access["Analyst access"]
  node_api["FastAPI<br/>[main.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_dashboard["Analyst dashboard<br/>[dashboard.py]"]
end

node_sensors(("Falco / RASP / Suricata"))
node_events_topic["Kafka events"]
node_agent_topic["Kafka agent events"]
node_diff_store[("Diff object storage<br/>[diff_store.py]")]
node_session_topic["Session-finished topic"]
node_analyst(("Analyst"))
node_nono(("nono agent sessions"))
node_mcp["MCP defense service"]

node_sensors -->|"publish telemetry"| node_events_topic
node_events_topic -->|"consume events"| node_baseline
node_baseline -->|"forward qualified events"| node_agent_topic
node_agent_topic -->|"consume events"| node_consumer
node_consumer -->|"add events"| node_windows
node_windows -->|"deliver closed windows"| node_short_ttp
node_short_ttp -->|"map techniques"| node_attack_rag
node_short_ttp -->|"write Short TTP"| node_es
node_analyst -->|"request investigation"| node_api
node_api -->|"dispatch requests"| node_routes
node_routes -->|"start investigation"| node_long_workflow
node_long_workflow -->|"run research"| node_research
node_research -->|"request analyst input"| node_feedback
node_feedback -->|"provide direction"| node_research
node_long_workflow -->|"save investigation"| node_postgres
node_feedback -->|"save feedback"| node_postgres
node_es -->|"read TTPs"| node_routes
node_postgres -->|"read investigation records"| node_routes
node_routes -->|"return responses"| node_api
node_api -->|"serve API"| node_dashboard
node_nono -->|"store diff"| node_diff_store
node_nono -->|"publish session event"| node_events_topic
node_baseline -->|"route session events"| node_session_topic
node_session_topic -->|"consume sessions"| node_guard_consumer
node_guard_consumer -->|"read referenced diff"| node_diff_store
node_guard_consumer -->|"assess session"| node_adjudicator
node_adjudicator -->|"check change signals"| node_risk_rules
node_guard_consumer -->|"save adjudication"| node_postgres
node_routes -->|"query sessions"| node_postgres
node_analyst -->|"review findings"| node_dashboard
node_dashboard -->|"submit decisions"| node_api
node_routes -->|"request rollback"| node_rollback
node_rollback -->|"publish restore request"| node_publisher
node_publisher -->|"dispatch rollback"| node_events_topic
node_rollback -->|"record rollback state"| node_postgres
node_attack_rag -.->|"provide ATT&amp;CK context"| node_long_workflow
node_long_workflow -.->|"enrich ATT&amp;CK findings"| node_attack_rag
node_short_ttp -.->|"optional response actions"| node_mcp

click node_baseline "https://github.com/essailab/deepxdr/blob/main/baseline_adjudication/anomaly_detector.py"
click node_consumer "https://github.com/essailab/deepxdr/blob/main/ai_agent/data_consumer/kafka_consumer.py"
click node_windows "https://github.com/essailab/deepxdr/blob/main/ai_agent/ttp_generator/window_manager.py"
click node_short_ttp "https://github.com/essailab/deepxdr/blob/main/ai_agent/ttp_generator/short_ttp_generator.py"
click node_attack_rag "https://github.com/essailab/deepxdr/blob/main/ai_agent/mitre_attck_agent/attack_rag.py"
click node_long_workflow "https://github.com/essailab/deepxdr/blob/main/ai_agent/mitre_attck_agent/workflows/graph.py"
click node_research "https://github.com/essailab/deepxdr/blob/main/ai_agent/ttp_generator/dx_analyzer/deep_researcher.py"
click node_feedback "https://github.com/essailab/deepxdr/blob/main/ai_agent/ttp_generator/human_feedback_session.py"
click node_diff_store "https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/diff_store.py"
click node_guard_consumer "https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/consumer.py"
click node_adjudicator "https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/adjudicator.py"
click node_risk_rules "https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/rule_engine.py"
click node_rollback "https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/rollback.py"
click node_publisher "https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/publisher.py"
click node_es "https://github.com/essailab/deepxdr/blob/main/ai_agent/shared/database/elasticsearch_client_v8.py"
click node_postgres "https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/sql_repository.py"
click node_api "https://github.com/essailab/deepxdr/blob/main/ai_agent/api_server/main.py"
click node_routes "https://github.com/essailab/deepxdr/blob/main/ai_agent/api_server/routes.py"
click node_dashboard "https://github.com/essailab/deepxdr/blob/main/web_ui/src/web/dashboard.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_baseline toneBlue
class node_consumer,node_windows,node_short_ttp,node_attack_rag,node_long_workflow,node_research,node_feedback,node_diff_store toneAmber
class node_guard_consumer,node_adjudicator,node_risk_rules,node_rollback,node_publisher toneMint
class node_es,node_postgres toneRose
class node_api,node_routes,node_dashboard,node_sensors,node_events_topic,node_agent_topic,node_session_topic,node_analyst,node_nono,node_mcp toneIndigo
```

## Components

### Telemetry and adjudication

- [Baseline adjudication](https://github.com/essailab/deepxdr/blob/main/baseline_adjudication/anomaly_detector.py): `baseline_adjudication/anomaly_detector.py`

### Threat analysis

- [Event consumer](https://github.com/essailab/deepxdr/blob/main/ai_agent/data_consumer/kafka_consumer.py): `ai_agent/data_consumer/kafka_consumer.py`
- [Dynamic event windows](https://github.com/essailab/deepxdr/blob/main/ai_agent/ttp_generator/window_manager.py): `ai_agent/ttp_generator/window_manager.py`
- [Short TTP generation](https://github.com/essailab/deepxdr/blob/main/ai_agent/ttp_generator/short_ttp_generator.py): `ai_agent/ttp_generator/short_ttp_generator.py`
- [ATT&CK analysis](https://github.com/essailab/deepxdr/blob/main/ai_agent/mitre_attck_agent/attack_rag.py): `ai_agent/mitre_attck_agent/attack_rag.py`
- [Long TTP investigation](https://github.com/essailab/deepxdr/blob/main/ai_agent/mitre_attck_agent/workflows/graph.py): `ai_agent/mitre_attck_agent/workflows/graph.py`
- [Deep research](https://github.com/essailab/deepxdr/blob/main/ai_agent/ttp_generator/dx_analyzer/deep_researcher.py): `ai_agent/ttp_generator/dx_analyzer/deep_researcher.py`
- [Analyst feedback](https://github.com/essailab/deepxdr/blob/main/ai_agent/ttp_generator/human_feedback_session.py): `ai_agent/ttp_generator/human_feedback_session.py`

### AgentGuard

- [AgentGuard consumer](https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/consumer.py): `ai_agent/agent_guard/consumer.py`
- [Intent and risk review](https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/adjudicator.py): `ai_agent/agent_guard/adjudicator.py`
- [Risk rules](https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/rule_engine.py): `ai_agent/agent_guard/rule_engine.py`
- [Rollback handling](https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/rollback.py): `ai_agent/agent_guard/rollback.py`
- [Rollback publisher](https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/publisher.py): `ai_agent/agent_guard/publisher.py`

### Persistence

- [Elasticsearch](https://github.com/essailab/deepxdr/blob/main/ai_agent/shared/database/elasticsearch_client_v8.py): `ai_agent/shared/database/elasticsearch_client_v8.py`
- [PostgreSQL records](https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/sql_repository.py): `ai_agent/agent_guard/sql_repository.py`

### Analyst access

- [FastAPI](https://github.com/essailab/deepxdr/blob/main/ai_agent/api_server/main.py): `ai_agent/api_server/main.py`
- [API routes](https://github.com/essailab/deepxdr/blob/main/ai_agent/api_server/routes.py): `ai_agent/api_server/routes.py`
- [Analyst dashboard](https://github.com/essailab/deepxdr/blob/main/web_ui/src/web/dashboard.py): `web_ui/src/web/dashboard.py`

### Other components

- **Falco / RASP / Suricata**
- **Kafka events**
- **Kafka agent events**
- [Diff object storage](https://github.com/essailab/deepxdr/blob/main/ai_agent/agent_guard/diff_store.py): `ai_agent/agent_guard/diff_store.py`
- **Session-finished topic**
- **Analyst**
- **nono agent sessions**
- **MCP defense service**

## Connections

- Falco / RASP / Suricata → Kafka events: publish telemetry
- Kafka events → Baseline adjudication: consume events
- Baseline adjudication → Kafka agent events: forward qualified events
- Kafka agent events → Event consumer: consume events
- Event consumer → Dynamic event windows: add events
- Dynamic event windows → Short TTP generation: deliver closed windows
- Short TTP generation → ATT&CK analysis: map techniques
- Short TTP generation → Elasticsearch: write Short TTP
- Analyst → FastAPI: request investigation
- FastAPI → API routes: dispatch requests
- API routes → Long TTP investigation: start investigation
- Long TTP investigation → Deep research: run research
- Deep research → Analyst feedback: request analyst input
- Analyst feedback → Deep research: provide direction
- Long TTP investigation → PostgreSQL records: save investigation
- Analyst feedback → PostgreSQL records: save feedback
- Elasticsearch → API routes: read TTPs
- PostgreSQL records → API routes: read investigation records
- API routes → FastAPI: return responses
- FastAPI → Analyst dashboard: serve API
- nono agent sessions → Diff object storage: store diff
- nono agent sessions → Kafka events: publish session event
- Baseline adjudication → Session-finished topic: route session events
- Session-finished topic → AgentGuard consumer: consume sessions
- AgentGuard consumer → Diff object storage: read referenced diff
- AgentGuard consumer → Intent and risk review: assess session
- Intent and risk review → Risk rules: check change signals
- AgentGuard consumer → PostgreSQL records: save adjudication
- API routes → PostgreSQL records: query sessions
- Analyst → Analyst dashboard: review findings
- Analyst dashboard → FastAPI: submit decisions
- API routes → Rollback handling: request rollback
- Rollback handling → Rollback publisher: publish restore request
- Rollback publisher → Kafka events: dispatch rollback
- Rollback handling → PostgreSQL records: record rollback state
- ATT&CK analysis → Long TTP investigation: provide ATT&CK context
- Long TTP investigation → ATT&CK analysis: enrich ATT&CK findings
- Short TTP generation → MCP defense service: optional response actions