# yogesh-ss7/athena_soca architecture

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

- Interactive diagram: https://gitdiagram.com/yogesh-ss7/athena_soca
- Repository: https://github.com/yogesh-ss7/athena_soca

## Overview

SOC Triage is a modular-monolith security-event triage product. Its documented workflow ingests and normalizes Sysmon/Windows events, extracts embedding features, combines vector retrieval and Sigma-rule results into a score, obtains a structured LLM verdict, and exposes analyst review and evaluation. The CLI excerpts confirm replay ingestion, parsing, normalization, feature extraction, persistence, and knowledge-base construction; the API excerpt confirms database initialization. Several later-stage implementations are unsampled, so those documented links cite the README rather than implying source inspection.

Main entry points: [`soc_triage/cli/main.py`](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/cli/main.py) (CLI), [`soc_triage/retrieval/kb_builder.py`](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/retrieval/kb_builder.py) (Knowledge Base Builder), [`soc_triage/triage`](https://github.com/yogesh-ss7/athena_soca/tree/main/soc_triage/triage) (LLM Triager), [`soc_triage/scoring`](https://github.com/yogesh-ss7/athena_soca/tree/main/soc_triage/scoring) (Combined Scorer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Event Intake"]
  node_replay["File Replay<br/>[file_replay.py]"]
  node_parsing["Event Parsers<br/>[parsers.py]"]
  node_normalizer["Deterministic Normalizer<br/>[normalizer.py]"]
end

subgraph group_analysis["Detection Analysis"]
  node_features["Feature Extractor<br/>[extractor.py]"]
  node_embedder["Embedding Models<br/>[embedder.py]"]
  node_vector[("Vector Retrieval<br/>[numpy_store.py]")]
  node_kb["Knowledge Base Builder<br/>[kb_builder.py]"]
  node_rules["Sigma Rules"]
  node_scoring["Combined Scorer"]
end

subgraph group_verdict["Triage and Review"]
  node_triager["LLM Triager"]
  node_review["Analyst Review Queue"]
end

subgraph group_platform["Interfaces and State"]
  node_events[("Event Repository<br/>[repositories.py]")]
  node_database[("Database<br/>[database.py]")]
  node_api["FastAPI Service<br/>[app.py]"]
  node_cli["CLI<br/>[main.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["Evaluation and Reporting"]
end

node_operator(("SOC Operator"))
node_ollama["Ollama"]

node_operator -->|"runs commands"| node_cli
node_cli -->|"streams events"| node_replay
node_cli -->|"dispatches parsing"| node_parsing
node_cli -->|"normalizes events"| node_normalizer
node_cli -->|"extracts features"| node_features
node_cli -->|"saves events"| node_events
node_cli -->|"builds index"| node_kb
node_kb -.->|"embeds events"| node_embedder
node_kb -.->|"indexes vectors"| node_vector
node_events -.->|"uses engine"| node_database
node_api -->|"initializes schema"| node_database
node_features -->|"creates vectors"| node_embedder
node_vector -->|"provides neighbors"| node_scoring
node_rules -->|"provides rule hits"| node_scoring
node_scoring -->|"routes for verdict"| node_triager
node_triager -.->|"requests verdict"| node_ollama
node_triager -->|"queues for review"| node_review
node_review -->|"presents decisions"| node_operator
node_evaluation -->|"reports metrics"| node_operator

click node_replay "https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/ingest/file_replay.py"
click node_parsing "https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/normalize/parsers.py"
click node_normalizer "https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/normalize/normalizer.py"
click node_features "https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/features/extractor.py"
click node_embedder "https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/retrieval/embedder.py"
click node_vector "https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/retrieval/numpy_store.py"
click node_kb "https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/retrieval/kb_builder.py"
click node_rules "https://github.com/yogesh-ss7/athena_soca/tree/main/soc_triage/rules"
click node_scoring "https://github.com/yogesh-ss7/athena_soca/tree/main/soc_triage/scoring"
click node_triager "https://github.com/yogesh-ss7/athena_soca/tree/main/soc_triage/triage"
click node_review "https://github.com/yogesh-ss7/athena_soca/tree/main/soc_triage/review"
click node_events "https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/storage/repositories.py"
click node_database "https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/storage/database.py"
click node_api "https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/api/app.py"
click node_cli "https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/cli/main.py"
click node_evaluation "https://github.com/yogesh-ss7/athena_soca/tree/main/soc_triage/evalkit"

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_replay,node_parsing,node_normalizer toneBlue
class node_features,node_embedder,node_vector,node_kb,node_rules,node_scoring toneAmber
class node_triager,node_review toneMint
class node_events,node_database,node_api,node_cli toneRose
class node_evaluation,node_operator,node_ollama toneIndigo
```

## Components

### Event Intake

- [File Replay](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/ingest/file_replay.py): `soc_triage/ingest/file_replay.py`
- [Event Parsers](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/normalize/parsers.py): `soc_triage/normalize/parsers.py`
- [Deterministic Normalizer](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/normalize/normalizer.py): `soc_triage/normalize/normalizer.py`

### Detection Analysis

- [Feature Extractor](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/features/extractor.py): `soc_triage/features/extractor.py`
- [Embedding Models](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/retrieval/embedder.py): `soc_triage/retrieval/embedder.py`
- [Vector Retrieval](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/retrieval/numpy_store.py): `soc_triage/retrieval/numpy_store.py`
- [Knowledge Base Builder](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/retrieval/kb_builder.py): `soc_triage/retrieval/kb_builder.py`
- [Sigma Rules](https://github.com/yogesh-ss7/athena_soca/tree/main/soc_triage/rules): `soc_triage/rules`
- [Combined Scorer](https://github.com/yogesh-ss7/athena_soca/tree/main/soc_triage/scoring): `soc_triage/scoring`

### Triage and Review

- [LLM Triager](https://github.com/yogesh-ss7/athena_soca/tree/main/soc_triage/triage): `soc_triage/triage`
- [Analyst Review Queue](https://github.com/yogesh-ss7/athena_soca/tree/main/soc_triage/review): `soc_triage/review`

### Interfaces and State

- [Event Repository](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/storage/repositories.py): `soc_triage/storage/repositories.py`
- [Database](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/storage/database.py): `soc_triage/storage/database.py`
- [FastAPI Service](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/api/app.py): `soc_triage/api/app.py`
- [CLI](https://github.com/yogesh-ss7/athena_soca/blob/main/soc_triage/cli/main.py): `soc_triage/cli/main.py`

### Evaluation

- [Evaluation and Reporting](https://github.com/yogesh-ss7/athena_soca/tree/main/soc_triage/evalkit): `soc_triage/evalkit`

### Other components

- **SOC Operator**
- **Ollama**

## Connections

- SOC Operator → CLI: runs commands (evidence: `soc_triage/cli/main.py`)
- CLI → File Replay: streams events (evidence: `soc_triage/cli/main.py`)
- CLI → Event Parsers: dispatches parsing (evidence: `soc_triage/cli/main.py`)
- CLI → Deterministic Normalizer: normalizes events (evidence: `soc_triage/cli/main.py`)
- CLI → Feature Extractor: extracts features (evidence: `soc_triage/cli/main.py`)
- CLI → Event Repository: saves events (evidence: `soc_triage/cli/main.py`)
- CLI → Knowledge Base Builder: builds index (evidence: `soc_triage/cli/main.py`)
- Knowledge Base Builder → Embedding Models: embeds events
- Knowledge Base Builder → Vector Retrieval: indexes vectors
- Event Repository → Database: uses engine
- FastAPI Service → Database: initializes schema (evidence: `soc_triage/api/app.py`)
- Feature Extractor → Embedding Models: creates vectors (evidence: `README.md`)
- Vector Retrieval → Combined Scorer: provides neighbors (evidence: `README.md`)
- Sigma Rules → Combined Scorer: provides rule hits (evidence: `README.md`)
- Combined Scorer → LLM Triager: routes for verdict (evidence: `README.md`)
- LLM Triager → Ollama: requests verdict (evidence: `README.md`)
- LLM Triager → Analyst Review Queue: queues for review (evidence: `README.md`)
- Analyst Review Queue → SOC Operator: presents decisions (evidence: `README.md`)
- Evaluation and Reporting → SOC Operator: reports metrics (evidence: `README.md`)