# kaushik-kishor/chainbreaker architecture

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

- Interactive diagram: https://gitdiagram.com/kaushik-kishor/chainbreaker
- Repository: https://github.com/kaushik-kishor/chainbreaker

## Overview

ChainBreaker is a real-time network intrusion detection and incident-response application. Its main workflow takes Kafka or batch network flows through parsing and ML classification, records communications and attack events in Neo4j, enriches them with kill-chain stages, and exposes graph, alert, forensic, and live telemetry views to the dashboard. The README documents these capabilities; edges below are limited to relationships shown in excerpts, SOURCE INDEX references, or README statements, so some subsystem connections are intentionally omitted.

Main entry points: [`backend/graph/neo4j_client.py`](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/graph/neo4j_client.py) (Neo4j graph store), [`backend/pipeline/orchestrator.py`](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/pipeline/orchestrator.py) (Pipeline orchestrator), [`backend/forensics/report_generator.py`](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/forensics/report_generator.py) (Forensic reports), [`backend/ingestion/kafka_consumer.py`](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ingestion/kafka_consumer.py) (Kafka consumer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Flow Ingestion"]
  node_parser["Flow parser<br/>[cicflow_parser.py]"]
  node_consumer["Kafka consumer<br/>[kafka_consumer.py]"]
  node_batchcollector["Batch collector<br/>[batch_collector.py]"]
  node_orchestrator["Pipeline orchestrator<br/>[orchestrator.py]"]
end

subgraph group_analysis["Detection &amp; Mapping"]
  node_ml["ML inference &amp; models<br/>[inference.py]"]
  node_features["Feature engineering<br/>[features.py]"]
  node_training["Model training<br/>[train.py]"]
  node_modelmanager["Model lifecycle<br/>[model_manager.py]"]
  node_mitre["ATT&amp;CK stage mapping<br/>[stage_mapper.py]"]
  node_attackmatrix["Kill-chain taxonomy<br/>[attack_matrix.py]"]
  node_temporal["Temporal analytics"]
end

subgraph group_graphstore["Attack Graph"]
  node_neo4j[("Neo4j graph store<br/>[neo4j_client.py]")]
  node_graphwriters["Graph event writers<br/>[attack_writer.py]"]
  node_killwriter["Kill-chain writer"]
  node_flowwriter["Flow writer<br/>[flow_writer.py]"]
  node_hostmanager["Host manager<br/>[host_manager.py]"]
end

subgraph group_response["Forensics &amp; Response"]
  node_forensics["Forensic analysis"]
  node_blast["Blast radius<br/>[blast_radius.py]"]
  node_profiler["Kill-chain profiler"]
  node_timeline["Event timeline"]
  node_report["Forensic reports"]
  node_agent["Response agent<br/>[kill_chain_env.py]"]
end

subgraph group_interface["API &amp; Dashboard"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_ws["WebSocket telemetry<br/>[ws.py]"]
  node_frontend["SOC dashboard<br/>[GraphView.tsx]"]
  node_client["Dashboard API client<br/>[client.ts]"]
end

node_kafka["Kafka"]
node_batch["CSV batch input"]
node_browser(("SOC analyst"))

node_kafka -->|"supplies flows"| node_consumer
node_consumer -->|"parses flows"| node_parser
node_consumer -->|"classifies flows"| node_ml
node_consumer -->|"writes flows"| node_flowwriter
node_batch -->|"supplies flows"| node_batchcollector
node_parser -->|"normalizes flows"| node_orchestrator
node_orchestrator -->|"requests predictions"| node_modelmanager
node_modelmanager -->|"scores flows"| node_ml
node_ml -->|"extracts features"| node_features
node_modelmanager -->|"trains when needed"| node_training
node_orchestrator -->|"upserts hosts"| node_hostmanager
node_orchestrator -->|"writes attack events"| node_graphwriters
node_orchestrator -->|"updates stages"| node_killwriter
node_orchestrator -.->|"maps stages"| node_mitre
node_killwriter -->|"uses taxonomy"| node_attackmatrix
node_flowwriter -.->|"writes graph"| node_neo4j
node_graphwriters -.->|"persists events"| node_neo4j
node_killwriter -->|"persists stages"| node_neo4j
node_hostmanager -->|"upserts hosts"| node_neo4j
node_orchestrator -.->|"links communications"| node_neo4j
node_neo4j -->|"provides graph data"| node_forensics
node_neo4j -->|"provides graph data"| node_blast
node_neo4j -->|"provides graph data"| node_profiler
node_neo4j -.->|"provides graph data"| node_timeline
node_report -->|"calculates impact"| node_blast
node_report -->|"summarizes stages"| node_profiler
node_report -->|"traces attack path"| node_forensics
node_report -->|"builds timeline"| node_timeline
node_agent -->|"reads incident state"| node_neo4j
node_agent -->|"contains stages"| node_killwriter
node_api -->|"registers route"| node_ws
node_ws -.->|"broadcasts graph telemetry"| node_neo4j
node_ws -->|"streams telemetry"| node_frontend
node_client -.->|"calls REST API"| node_api
node_browser -->|"views dashboard"| node_frontend
node_frontend -->|"receives live updates"| node_ws
node_temporal -.->|"adds temporal analysis"| node_orchestrator

click node_parser "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ingestion/cicflow_parser.py"
click node_consumer "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ingestion/kafka_consumer.py"
click node_batchcollector "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ingestion/batch_collector.py"
click node_orchestrator "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/pipeline/orchestrator.py"
click node_ml "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ml/inference.py"
click node_features "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ml/features.py"
click node_training "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ml/train.py"
click node_modelmanager "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ml/model_manager.py"
click node_mitre "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/mitre/stage_mapper.py"
click node_attackmatrix "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/mitre/attack_matrix.py"
click node_temporal "https://github.com/kaushik-kishor/chainbreaker/tree/main/backend/temporal"
click node_neo4j "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/graph/neo4j_client.py"
click node_graphwriters "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/graph/attack_writer.py"
click node_killwriter "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/graph/kill_chain_writer.py"
click node_flowwriter "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/graph/flow_writer.py"
click node_hostmanager "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/graph/host_manager.py"
click node_forensics "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/forensics/attack_path_tracer.py"
click node_blast "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/forensics/blast_radius.py"
click node_profiler "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/forensics/kill_chain_profiler.py"
click node_timeline "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/forensics/timeline_builder.py"
click node_report "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/forensics/report_generator.py"
click node_agent "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/agent/kill_chain_env.py"
click node_api "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/main.py"
click node_ws "https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/api/routes/ws.py"
click node_frontend "https://github.com/kaushik-kishor/chainbreaker/blob/main/frontend/src/components/GraphView.tsx"
click node_client "https://github.com/kaushik-kishor/chainbreaker/blob/main/frontend/src/api/client.ts"

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_parser,node_consumer,node_batchcollector,node_orchestrator toneBlue
class node_ml,node_features,node_training,node_modelmanager,node_mitre,node_attackmatrix,node_temporal toneAmber
class node_neo4j,node_graphwriters,node_killwriter,node_flowwriter,node_hostmanager toneMint
class node_forensics,node_blast,node_profiler,node_timeline,node_report,node_agent toneRose
class node_api,node_ws,node_frontend,node_client,node_kafka,node_batch,node_browser toneIndigo
```

## Components

### Flow Ingestion

- [Flow parser](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ingestion/cicflow_parser.py): `backend/ingestion/cicflow_parser.py`
- [Kafka consumer](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ingestion/kafka_consumer.py): `backend/ingestion/kafka_consumer.py`
- [Batch collector](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ingestion/batch_collector.py): `backend/ingestion/batch_collector.py`
- [Pipeline orchestrator](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/pipeline/orchestrator.py): `backend/pipeline/orchestrator.py`

### Detection & Mapping

- [ML inference & models](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ml/inference.py): `backend/ml/inference.py`
- [Feature engineering](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ml/features.py): `backend/ml/features.py`
- [Model training](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ml/train.py): `backend/ml/train.py`
- [Model lifecycle](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/ml/model_manager.py): `backend/ml/model_manager.py`
- [ATT&CK stage mapping](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/mitre/stage_mapper.py): `backend/mitre/stage_mapper.py`
- [Kill-chain taxonomy](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/mitre/attack_matrix.py): `backend/mitre/attack_matrix.py`
- [Temporal analytics](https://github.com/kaushik-kishor/chainbreaker/tree/main/backend/temporal): `backend/temporal`

### Attack Graph

- [Neo4j graph store](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/graph/neo4j_client.py): `backend/graph/neo4j_client.py`
- [Graph event writers](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/graph/attack_writer.py): `backend/graph/attack_writer.py`
- [Kill-chain writer](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/graph/kill_chain_writer.py): `backend/graph/kill_chain_writer.py`
- [Flow writer](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/graph/flow_writer.py): `backend/graph/flow_writer.py`
- [Host manager](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/graph/host_manager.py): `backend/graph/host_manager.py`

### Forensics & Response

- [Forensic analysis](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/forensics/attack_path_tracer.py): `backend/forensics/attack_path_tracer.py`
- [Blast radius](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/forensics/blast_radius.py): `backend/forensics/blast_radius.py`
- [Kill-chain profiler](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/forensics/kill_chain_profiler.py): `backend/forensics/kill_chain_profiler.py`
- [Event timeline](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/forensics/timeline_builder.py): `backend/forensics/timeline_builder.py`
- [Forensic reports](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/forensics/report_generator.py): `backend/forensics/report_generator.py`
- [Response agent](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/agent/kill_chain_env.py): `backend/agent/kill_chain_env.py`

### API & Dashboard

- [FastAPI routes](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/main.py): `backend/main.py`
- [WebSocket telemetry](https://github.com/kaushik-kishor/chainbreaker/blob/main/backend/api/routes/ws.py): `backend/api/routes/ws.py`
- [SOC dashboard](https://github.com/kaushik-kishor/chainbreaker/blob/main/frontend/src/components/GraphView.tsx): `frontend/src/components/GraphView.tsx`
- [Dashboard API client](https://github.com/kaushik-kishor/chainbreaker/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Other components

- **Kafka**
- **CSV batch input**
- **SOC analyst**

## Connections

- Kafka → Kafka consumer: supplies flows (evidence: `README.md`)
- Kafka consumer → Flow parser: parses flows (evidence: `backend/ingestion/kafka_consumer.py`)
- Kafka consumer → ML inference & models: classifies flows (evidence: `backend/ingestion/kafka_consumer.py`)
- Kafka consumer → Flow writer: writes flows (evidence: `backend/ingestion/kafka_consumer.py`)
- CSV batch input → Batch collector: supplies flows (evidence: `README.md`)
- Flow parser → Pipeline orchestrator: normalizes flows (evidence: `README.md`)
- Pipeline orchestrator → Model lifecycle: requests predictions (evidence: `backend/pipeline/orchestrator.py`)
- Model lifecycle → ML inference & models: scores flows (evidence: `backend/ml/model_manager.py`)
- ML inference & models → Feature engineering: extracts features (evidence: `backend/ml/inference.py`)
- Model lifecycle → Model training: trains when needed (evidence: `backend/ml/model_manager.py`)
- Pipeline orchestrator → Host manager: upserts hosts (evidence: `backend/pipeline/orchestrator.py`)
- Pipeline orchestrator → Graph event writers: writes attack events (evidence: `backend/pipeline/orchestrator.py`)
- Pipeline orchestrator → Kill-chain writer: updates stages (evidence: `backend/pipeline/orchestrator.py`)
- Pipeline orchestrator → ATT&CK stage mapping: maps stages (evidence: `backend/pipeline/orchestrator.py`)
- Kill-chain writer → Kill-chain taxonomy: uses taxonomy (evidence: `backend/graph/kill_chain_writer.py`)
- Flow writer → Neo4j graph store: writes graph (evidence: `backend/ingestion/kafka_consumer.py`)
- Graph event writers → Neo4j graph store: persists events (evidence: `README.md`)
- Kill-chain writer → Neo4j graph store: persists stages (evidence: `backend/graph/kill_chain_writer.py`)
- Host manager → Neo4j graph store: upserts hosts (evidence: `backend/graph/host_manager.py`)
- Pipeline orchestrator → Neo4j graph store: links communications (evidence: `backend/pipeline/orchestrator.py`)
- Neo4j graph store → Forensic analysis: provides graph data (evidence: `backend/forensics/attack_path_tracer.py`)
- Neo4j graph store → Blast radius: provides graph data (evidence: `backend/forensics/blast_radius.py`)
- Neo4j graph store → Kill-chain profiler: provides graph data (evidence: `backend/forensics/kill_chain_profiler.py`)
- Neo4j graph store → Event timeline: provides graph data (evidence: `backend/api/routes/forensics.py`)
- Forensic reports → Blast radius: calculates impact (evidence: `backend/forensics/report_generator.py`)
- Forensic reports → Kill-chain profiler: summarizes stages (evidence: `backend/forensics/report_generator.py`)
- Forensic reports → Forensic analysis: traces attack path (evidence: `backend/forensics/report_generator.py`)
- Forensic reports → Event timeline: builds timeline (evidence: `backend/forensics/report_generator.py`)
- Response agent → Neo4j graph store: reads incident state (evidence: `backend/agent/kill_chain_env.py`)
- Response agent → Kill-chain writer: contains stages (evidence: `backend/agent/kill_chain_env.py`)
- FastAPI routes → WebSocket telemetry: registers route (evidence: `backend/main.py`)
- WebSocket telemetry → Neo4j graph store: broadcasts graph telemetry (evidence: `README.md`)
- WebSocket telemetry → SOC dashboard: streams telemetry (evidence: `README.md`)
- Dashboard API client → FastAPI routes: calls REST API (evidence: `README.md`)
- SOC analyst → SOC dashboard: views dashboard (evidence: `README.md`)
- SOC dashboard → WebSocket telemetry: receives live updates
- Temporal analytics → Pipeline orchestrator: adds temporal analysis
