# tracehanami/aiva-ks architecture

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

## Overview

AIVA-KS is a kernel-behavior security monitoring and investigation platform. Its principal workflow observes syscall telemetry, turns it into behavioral features and an attack graph, maps evidence to ATT&CK, and presents risk, explanations, and response recommendations to analysts. The README documents the intended collector/Kafka flow, while the sampled demo confirms the analysis-to-response stages. Backend persistence and the dashboard/API are additional product branches. Kafka, feature extraction, and prediction are documented capabilities but their runtime wiring is not shown in sampled source.

Main entry points: [`backend/app/main.py`](https://github.com/tracehanami/aiva-ks/blob/master/backend/app/main.py) (Security engine API), [`backend/app/api`](https://github.com/tracehanami/aiva-ks/tree/master/backend/app/api) (REST and WebSocket routes), [`ai/graph_engine/graph_builder.py`](https://github.com/tracehanami/aiva-ks/blob/master/ai/graph_engine/graph_builder.py) (Behavioral graph), [`ai/mitre_mapping/mapping_engine.py`](https://github.com/tracehanami/aiva-ks/blob/master/ai/mitre_mapping/mapping_engine.py) (MITRE mapping)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_observe["Telemetry"]
  node_kernel(("Linux kernel"))
  node_sensors["eBPF sensors"]
  node_collector["Go collector<br/>[collector.go]"]
  node_kafka["Kafka stream"]
end

subgraph group_analysis["Security Analysis"]
  node_features["Feature extraction"]
  node_graph["Behavioral graph<br/>[graph_builder.py]"]
  node_prediction["Intent prediction"]
  node_mitre["MITRE mapping<br/>[mapping_engine.py]"]
  node_explain["Evidence and narrative<br/>[explainer.py]"]
  node_heatmap["Threat heatmap<br/>[heatmap_engine.py]"]
end

subgraph group_response["Response"]
  node_response_policy["Policy engine<br/>[policy_engine.py]"]
  node_executor["Response executor<br/>[policy_engine.py]"]
end

subgraph group_backend["API and Storage"]
  node_engine["Security engine API<br/>[main.py]"]
  node_api_routes["REST and WebSocket routes"]
  node_copilot["Copilot service<br/>[copilot_service.py]"]
  node_replay["Incident replay<br/>[replay_service.py]"]
  node_alerts["Alert service<br/>[alert_service.py]"]
  node_orm["Persistence models<br/>[orm.py]"]
  node_db[("PostgreSQL database<br/>[session.py]")]
end

subgraph group_ui["Analyst Interface"]
  node_frontend["React dashboard<br/>[App.tsx]"]
end

node_analyst(("Security analyst"))

node_kernel -->|"emits syscalls"| node_sensors
node_sensors -->|"streams events"| node_collector
node_collector -->|"publishes events"| node_kafka
node_kafka -->|"feeds telemetry"| node_features
node_features -->|"enriches events"| node_graph
node_graph -->|"provides evidence"| node_mitre
node_mitre -->|"grounds narrative"| node_explain
node_graph -->|"supplies risk graph"| node_heatmap
node_graph -->|"maintains graph state"| node_engine
node_engine -->|"ingests events"| node_graph
node_engine -->|"maps events"| node_mitre
node_engine -->|"computes scores"| node_heatmap
node_engine -->|"generates explanations"| node_explain
node_engine -->|"evaluates response"| node_response_policy
node_mitre -->|"provides technique matches"| node_response_policy
node_response_policy -->|"returns actions"| node_executor
node_api_routes -.->|"serves security state"| node_engine
node_api_routes -->|"handles alert operations"| node_alerts
node_api_routes -.->|"routes chat"| node_copilot
node_api_routes -.->|"routes replay"| node_replay
node_alerts -->|"queries alerts"| node_orm
node_orm -.->|"persists records"| node_db
node_frontend -.->|"requests dashboard data"| node_api_routes
node_analyst -->|"investigates and approves"| node_frontend

click node_sensors "https://github.com/tracehanami/aiva-ks/tree/master/ebpf/src"
click node_collector "https://github.com/tracehanami/aiva-ks/blob/master/ebpf/userspace/collector.go"
click node_features "https://github.com/tracehanami/aiva-ks/tree/master/ai/feature_extraction"
click node_graph "https://github.com/tracehanami/aiva-ks/blob/master/ai/graph_engine/graph_builder.py"
click node_prediction "https://github.com/tracehanami/aiva-ks/tree/master/ai/intent_prediction"
click node_mitre "https://github.com/tracehanami/aiva-ks/blob/master/ai/mitre_mapping/mapping_engine.py"
click node_explain "https://github.com/tracehanami/aiva-ks/blob/master/ai/explainability/explainer.py"
click node_heatmap "https://github.com/tracehanami/aiva-ks/blob/master/ai/threat_heatmap/heatmap_engine.py"
click node_engine "https://github.com/tracehanami/aiva-ks/blob/master/backend/app/main.py"
click node_response_policy "https://github.com/tracehanami/aiva-ks/blob/master/response-engine/policy_engine.py"
click node_executor "https://github.com/tracehanami/aiva-ks/blob/master/response-engine/policy_engine.py"
click node_api_routes "https://github.com/tracehanami/aiva-ks/tree/master/backend/app/api"
click node_copilot "https://github.com/tracehanami/aiva-ks/blob/master/backend/app/services/copilot_service.py"
click node_replay "https://github.com/tracehanami/aiva-ks/blob/master/backend/app/services/replay_service.py"
click node_alerts "https://github.com/tracehanami/aiva-ks/blob/master/backend/app/services/alert_service.py"
click node_orm "https://github.com/tracehanami/aiva-ks/blob/master/backend/app/models/orm.py"
click node_db "https://github.com/tracehanami/aiva-ks/blob/master/backend/app/db/session.py"
click node_frontend "https://github.com/tracehanami/aiva-ks/blob/master/frontend/src/App.tsx"

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_kernel,node_sensors,node_collector,node_kafka toneBlue
class node_features,node_graph,node_prediction,node_mitre,node_explain,node_heatmap toneAmber
class node_response_policy,node_executor toneMint
class node_engine,node_api_routes,node_copilot,node_replay,node_alerts,node_orm,node_db toneRose
class node_frontend,node_analyst toneIndigo
```

## Components

### Telemetry

- **Linux kernel**
- [eBPF sensors](https://github.com/tracehanami/aiva-ks/tree/master/ebpf/src): `ebpf/src`
- [Go collector](https://github.com/tracehanami/aiva-ks/blob/master/ebpf/userspace/collector.go): `ebpf/userspace/collector.go`
- **Kafka stream**

### Security Analysis

- [Feature extraction](https://github.com/tracehanami/aiva-ks/tree/master/ai/feature_extraction): `ai/feature_extraction`
- [Behavioral graph](https://github.com/tracehanami/aiva-ks/blob/master/ai/graph_engine/graph_builder.py): `ai/graph_engine/graph_builder.py`
- [Intent prediction](https://github.com/tracehanami/aiva-ks/tree/master/ai/intent_prediction): `ai/intent_prediction`
- [MITRE mapping](https://github.com/tracehanami/aiva-ks/blob/master/ai/mitre_mapping/mapping_engine.py): `ai/mitre_mapping/mapping_engine.py`
- [Evidence and narrative](https://github.com/tracehanami/aiva-ks/blob/master/ai/explainability/explainer.py): `ai/explainability/explainer.py`
- [Threat heatmap](https://github.com/tracehanami/aiva-ks/blob/master/ai/threat_heatmap/heatmap_engine.py): `ai/threat_heatmap/heatmap_engine.py`

### Response

- [Policy engine](https://github.com/tracehanami/aiva-ks/blob/master/response-engine/policy_engine.py): `response-engine/policy_engine.py`
- [Response executor](https://github.com/tracehanami/aiva-ks/blob/master/response-engine/policy_engine.py): `response-engine/policy_engine.py`

### API and Storage

- [Security engine API](https://github.com/tracehanami/aiva-ks/blob/master/backend/app/main.py): `backend/app/main.py`
- [REST and WebSocket routes](https://github.com/tracehanami/aiva-ks/tree/master/backend/app/api): `backend/app/api`
- [Copilot service](https://github.com/tracehanami/aiva-ks/blob/master/backend/app/services/copilot_service.py): `backend/app/services/copilot_service.py`
- [Incident replay](https://github.com/tracehanami/aiva-ks/blob/master/backend/app/services/replay_service.py): `backend/app/services/replay_service.py`
- [Alert service](https://github.com/tracehanami/aiva-ks/blob/master/backend/app/services/alert_service.py): `backend/app/services/alert_service.py`
- [Persistence models](https://github.com/tracehanami/aiva-ks/blob/master/backend/app/models/orm.py): `backend/app/models/orm.py`
- [PostgreSQL database](https://github.com/tracehanami/aiva-ks/blob/master/backend/app/db/session.py): `backend/app/db/session.py`

### Analyst Interface

- [React dashboard](https://github.com/tracehanami/aiva-ks/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`

### Other components

- **Security analyst**

## Connections

- Linux kernel → eBPF sensors: emits syscalls (evidence: `README.md`)
- eBPF sensors → Go collector: streams events (evidence: `README.md`)
- Go collector → Kafka stream: publishes events (evidence: `README.md`)
- Kafka stream → Feature extraction: feeds telemetry (evidence: `README.md`)
- Feature extraction → Behavioral graph: enriches events (evidence: `README.md`)
- Behavioral graph → MITRE mapping: provides evidence (evidence: `demo_full_pipeline.py`)
- MITRE mapping → Evidence and narrative: grounds narrative (evidence: `ai/explainability/explainer.py`)
- Behavioral graph → Threat heatmap: supplies risk graph (evidence: `ai/threat_heatmap/heatmap_engine.py`)
- Behavioral graph → Security engine API: maintains graph state (evidence: `backend/app/main.py`)
- Security engine API → Behavioral graph: ingests events (evidence: `backend/app/main.py`)
- Security engine API → MITRE mapping: maps events (evidence: `backend/app/main.py`)
- Security engine API → Threat heatmap: computes scores (evidence: `backend/app/main.py`)
- Security engine API → Evidence and narrative: generates explanations (evidence: `backend/app/main.py`)
- Security engine API → Policy engine: evaluates response (evidence: `backend/app/main.py`)
- MITRE mapping → Policy engine: provides technique matches (evidence: `response-engine/policy_engine.py`)
- Policy engine → Response executor: returns actions (evidence: `response-engine/policy_engine.py`)
- REST and WebSocket routes → Security engine API: serves security state
- REST and WebSocket routes → Alert service: handles alert operations (evidence: `backend/app/api/alerts.py`)
- REST and WebSocket routes → Copilot service: routes chat
- REST and WebSocket routes → Incident replay: routes replay
- Alert service → Persistence models: queries alerts (evidence: `backend/app/services/alert_service.py`)
- Persistence models → PostgreSQL database: persists records
- React dashboard → REST and WebSocket routes: requests dashboard data
- Security analyst → React dashboard: investigates and approves (evidence: `frontend/src/App.tsx`)
