# sanjeevandev/attacktrace architecture

> Architecture diagram of the GitHub repository sanjeevandev/attacktrace, 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/sanjeevandev/attacktrace
- Repository: https://github.com/sanjeevandev/attacktrace

## Overview

ATTACKTRACE turns security logs into enriched events and correlated attack incidents, then exposes them for investigation and response. The main workflow is documented and partly visible in the pipeline, parser, correlator, and API excerpts. The graph also preserves documented graph export, dashboard, threat-intelligence, playbook, forensic-report, and WebSocket capabilities. Some API routes and integrations are only partially sampled, so uncertain internal wiring is omitted; the incident state is shown as API-managed in-memory state, not a persistent database.

Main entry points: [`src/api.py`](https://github.com/sanjeevandev/attacktrace/blob/main/src/api.py) (REST and stream API), [`src/pipeline.py`](https://github.com/sanjeevandev/attacktrace/blob/main/src/pipeline.py) (Pipeline orchestrator), [`main.py`](https://github.com/sanjeevandev/attacktrace/blob/main/main.py) (CLI entry point), [`src/parser.py`](https://github.com/sanjeevandev/attacktrace/blob/main/src/parser.py) (Security parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Detection pipeline"]
  node_pipeline["Pipeline orchestrator<br/>[pipeline.py]"]
  node_collector["Log collector<br/>[collector.py]"]
  node_parser["Security parser<br/>[parser.py]"]
  node_mapper["MITRE mapper<br/>[mitre_mapper.py]"]
  node_correlator["Threat correlator<br/>[correlation.py]"]
  node_models["Event and incident models<br/>[models.py]"]
end

subgraph group_investigation["Investigation API"]
  node_api["REST and stream API<br/>[api.py]"]
  node_incident_state["Incident state<br/>[api.py]"]
  node_websocket["Alert broadcaster"]
end

subgraph group_response["Threat response"]
  node_threat_intel["Threat intelligence<br/>[threat_intel.py]"]
  node_playbooks["Mitigation playbooks<br/>[playbooks.py]"]
  node_reporter["Forensic reporter<br/>[reporter.py]"]
end

subgraph group_presentation["Visualization and reports"]
  node_visualizer["Incident graph and dashboard<br/>[visualizer.py]"]
  node_dashboard["SOC dashboard template<br/>[dashboard.html]"]
  node_timeline["Timeline renderer<br/>[timeline.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI entry point<br/>[main.py]"]
end

node_telemetry["Security telemetry"]
node_client(("API client"))
node_browser(("SOC analyst"))
node_simulator["Stream simulator<br/>[simulate_stream.py]"]

node_telemetry -->|"submits logs"| node_client
node_client -->|"sends requests"| node_api
node_browser -->|"opens dashboard"| node_api
node_api -->|"runs ingestion"| node_pipeline
node_pipeline -->|"ingests logs"| node_collector
node_pipeline -->|"enriches events"| node_parser
node_parser -->|"maps indicators"| node_mapper
node_pipeline -->|"correlates events"| node_correlator
node_api -->|"reads and updates"| node_incident_state
node_pipeline -->|"returns incidents"| node_incident_state
node_api -->|"enriches incidents"| node_threat_intel
node_api -->|"broadcasts alerts"| node_websocket
node_api -->|"exports incident graph"| node_visualizer
node_api -->|"generates mitigations"| node_playbooks
node_api -->|"generates reports"| node_reporter
node_api -->|"serves template"| node_dashboard
node_cli -->|"runs analysis"| node_pipeline
node_cli -->|"renders incidents"| node_timeline
node_simulator -.->|"posts stream events"| node_api

click node_pipeline "https://github.com/sanjeevandev/attacktrace/blob/main/src/pipeline.py"
click node_collector "https://github.com/sanjeevandev/attacktrace/blob/main/src/collector.py"
click node_parser "https://github.com/sanjeevandev/attacktrace/blob/main/src/parser.py"
click node_mapper "https://github.com/sanjeevandev/attacktrace/blob/main/src/mitre_mapper.py"
click node_correlator "https://github.com/sanjeevandev/attacktrace/blob/main/src/correlation.py"
click node_models "https://github.com/sanjeevandev/attacktrace/blob/main/src/models.py"
click node_api "https://github.com/sanjeevandev/attacktrace/blob/main/src/api.py"
click node_incident_state "https://github.com/sanjeevandev/attacktrace/blob/main/src/api.py"
click node_websocket "https://github.com/sanjeevandev/attacktrace/blob/main/src/websocket_manager.py"
click node_threat_intel "https://github.com/sanjeevandev/attacktrace/blob/main/src/threat_intel.py"
click node_playbooks "https://github.com/sanjeevandev/attacktrace/blob/main/src/playbooks.py"
click node_reporter "https://github.com/sanjeevandev/attacktrace/blob/main/src/reporter.py"
click node_visualizer "https://github.com/sanjeevandev/attacktrace/blob/main/src/visualizer.py"
click node_dashboard "https://github.com/sanjeevandev/attacktrace/blob/main/templates/dashboard.html"
click node_cli "https://github.com/sanjeevandev/attacktrace/blob/main/main.py"
click node_timeline "https://github.com/sanjeevandev/attacktrace/blob/main/src/timeline.py"
click node_simulator "https://github.com/sanjeevandev/attacktrace/blob/main/scripts/simulate_stream.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_pipeline,node_collector,node_parser,node_mapper,node_correlator,node_models,node_client toneBlue
class node_api,node_incident_state,node_websocket toneAmber
class node_threat_intel,node_playbooks,node_reporter toneMint
class node_visualizer,node_dashboard,node_timeline toneRose
class node_cli,node_telemetry,node_browser toneIndigo
class node_simulator toneTeal
```

## Components

### Detection pipeline

- [Pipeline orchestrator](https://github.com/sanjeevandev/attacktrace/blob/main/src/pipeline.py): `src/pipeline.py`
- [Log collector](https://github.com/sanjeevandev/attacktrace/blob/main/src/collector.py): `src/collector.py`
- [Security parser](https://github.com/sanjeevandev/attacktrace/blob/main/src/parser.py): `src/parser.py`
- [MITRE mapper](https://github.com/sanjeevandev/attacktrace/blob/main/src/mitre_mapper.py): `src/mitre_mapper.py`
- [Threat correlator](https://github.com/sanjeevandev/attacktrace/blob/main/src/correlation.py): `src/correlation.py`
- [Event and incident models](https://github.com/sanjeevandev/attacktrace/blob/main/src/models.py): `src/models.py`

### Investigation API

- [REST and stream API](https://github.com/sanjeevandev/attacktrace/blob/main/src/api.py): `src/api.py`
- [Incident state](https://github.com/sanjeevandev/attacktrace/blob/main/src/api.py): `src/api.py`
- [Alert broadcaster](https://github.com/sanjeevandev/attacktrace/blob/main/src/websocket_manager.py): `src/websocket_manager.py`

### Threat response

- [Threat intelligence](https://github.com/sanjeevandev/attacktrace/blob/main/src/threat_intel.py): `src/threat_intel.py`
- [Mitigation playbooks](https://github.com/sanjeevandev/attacktrace/blob/main/src/playbooks.py): `src/playbooks.py`
- [Forensic reporter](https://github.com/sanjeevandev/attacktrace/blob/main/src/reporter.py): `src/reporter.py`

### Visualization and reports

- [Incident graph and dashboard](https://github.com/sanjeevandev/attacktrace/blob/main/src/visualizer.py): `src/visualizer.py`
- [SOC dashboard template](https://github.com/sanjeevandev/attacktrace/blob/main/templates/dashboard.html): `templates/dashboard.html`
- [Timeline renderer](https://github.com/sanjeevandev/attacktrace/blob/main/src/timeline.py): `src/timeline.py`

### User interfaces

- [CLI entry point](https://github.com/sanjeevandev/attacktrace/blob/main/main.py): `main.py`

### Other components

- **Security telemetry**
- **API client**
- **SOC analyst**
- [Stream simulator](https://github.com/sanjeevandev/attacktrace/blob/main/scripts/simulate_stream.py): `scripts/simulate_stream.py`

## Connections

- Security telemetry → API client: submits logs
- API client → REST and stream API: sends requests
- SOC analyst → REST and stream API: opens dashboard
- REST and stream API → Pipeline orchestrator: runs ingestion
- Pipeline orchestrator → Log collector: ingests logs
- Pipeline orchestrator → Security parser: enriches events
- Security parser → MITRE mapper: maps indicators
- Pipeline orchestrator → Threat correlator: correlates events
- REST and stream API → Incident state: reads and updates
- Pipeline orchestrator → Incident state: returns incidents
- REST and stream API → Threat intelligence: enriches incidents
- REST and stream API → Alert broadcaster: broadcasts alerts
- REST and stream API → Incident graph and dashboard: exports incident graph
- REST and stream API → Mitigation playbooks: generates mitigations
- REST and stream API → Forensic reporter: generates reports
- REST and stream API → SOC dashboard template: serves template
- CLI entry point → Pipeline orchestrator: runs analysis
- CLI entry point → Timeline renderer: renders incidents
- Stream simulator → REST and stream API: posts stream events