# sakoleat-kh/threat-detection-platform architecture

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

- Interactive diagram: https://gitdiagram.com/sakoleat-kh/threat-detection-platform
- Repository: https://github.com/sakoleat-kh/threat-detection-platform

## Overview

This is a rule-based threat-detection platform. Its principal workflow reads Linux authentication and web access logs, parses and normalizes events, evaluates detection rules, enriches alerts with MITRE ATT&CK data, and persists alerts for REST API investigation. The graph also includes alert-query/statistics capabilities. The dashboard is documented, but no dashboard source appears in the supplied tree. Relationships are limited to those shown in excerpts, the source index, or README; unsampled implementation details are not inferred.

Main entry points: [`app/services/ingestion.py`](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/services/ingestion.py) (Ingestion service), [`app/api/main.py`](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/api/main.py) (API application), [`app/detection/engine.py`](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/detection/engine.py) (Detection engine), [`app/repository/alert_repository.py`](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/repository/alert_repository.py) (Alert repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Log processing"]
  node_ingest_service["Ingestion service<br/>[ingestion.py]"]
  node_auth_reader["Auth log reader<br/>[auth_log_reader.py]"]
  node_linux_parser["Linux parser<br/>[linux_parser.py]"]
  node_access_reader["Access log reader"]
  node_apache_parser["Apache parser<br/>[apache_parser.py]"]
  node_normalizer["Event normalizer<br/>[normalizer.py]"]
  node_event_models["Event models"]
end

subgraph group_detect["Detection and enrichment"]
  node_engine_factory["Engine factory"]
  node_detection_engine["Detection engine<br/>[engine.py]"]
  node_rule_contract["Rule interface<br/>[rule_base.py]"]
  node_detection_rules["Detection rules"]
  node_alert_model["Alert model<br/>[alert.py]"]
  node_mitre_mapping["MITRE mapping<br/>[mapping.py]"]
end

subgraph group_storage["Alert persistence"]
  node_database_config["Database config<br/>[database.py]"]
  node_alert_repository["Alert repository"]
  node_alert_record["Alert record<br/>[db_alert.py]"]
  node_database[("SQLite database")]
end

subgraph group_api["REST API"]
  node_api_main["API application<br/>[main.py]"]
  node_ingest_router["Ingestion endpoint<br/>[ingest.py]"]
  node_alerts_router["Alert endpoints<br/>[alerts.py]"]
  node_stats_router["Statistics endpoint<br/>[stats.py]"]
end

node_log_files["Log files"]
node_api_clients(("API clients"))
node_dashboard["Web dashboard"]

node_log_files -->|"provides logs"| node_ingest_service
node_ingest_service -->|"reads auth logs"| node_auth_reader
node_ingest_service -->|"reads access logs"| node_access_reader
node_auth_reader -->|"parses lines"| node_linux_parser
node_access_reader -->|"parses lines"| node_apache_parser
node_ingest_service -->|"normalizes events"| node_normalizer
node_auth_reader -->|"yields auth events"| node_event_models
node_access_reader -->|"yields access events"| node_event_models
node_normalizer -->|"creates normalized events"| node_event_models
node_engine_factory -->|"creates engine"| node_detection_engine
node_engine_factory -->|"registers rules"| node_detection_rules
node_detection_engine -->|"evaluates rules"| node_rule_contract
node_detection_rules -->|"implement interface"| node_rule_contract
node_ingest_service -->|"runs detection"| node_detection_engine
node_detection_engine -->|"enriches alerts"| node_mitre_mapping
node_detection_engine -->|"collects alerts"| node_alert_model
node_ingest_service -->|"opens session"| node_database_config
node_ingest_service -->|"saves alerts"| node_alert_repository
node_alert_repository -->|"creates records"| node_alert_record
node_database_config -->|"configures SQLite"| node_database
node_alert_repository -->|"queries and writes"| node_database
node_api_main -->|"initializes database"| node_database_config
node_api_main -->|"mounts routes"| node_ingest_router
node_api_main -->|"mounts routes"| node_alerts_router
node_api_main -->|"mounts routes"| node_stats_router
node_ingest_router -->|"invokes ingestion"| node_ingest_service
node_ingest_router -->|"builds engine"| node_engine_factory
node_alerts_router -->|"queries alerts"| node_alert_repository
node_stats_router -->|"requests statistics"| node_alert_repository
node_api_clients -->|"requests API"| node_api_main
node_api_main -->|"serves API data"| node_dashboard

click node_ingest_service "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/services/ingestion.py"
click node_auth_reader "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/parsers/auth_log_reader.py"
click node_linux_parser "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/parsers/linux_parser.py"
click node_access_reader "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/parsers/access_log_reader.py"
click node_apache_parser "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/parsers/apache_parser.py"
click node_normalizer "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/services/normalizer.py"
click node_event_models "https://github.com/sakoleat-kh/threat-detection-platform/tree/main/app/models"
click node_engine_factory "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/services/detection_engine.py"
click node_detection_engine "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/detection/engine.py"
click node_rule_contract "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/detection/rule_base.py"
click node_detection_rules "https://github.com/sakoleat-kh/threat-detection-platform/tree/main/app/detection/rules"
click node_alert_model "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/models/alert.py"
click node_mitre_mapping "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/mitre/mapping.py"
click node_database_config "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/models/database.py"
click node_alert_repository "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/repository/alert_repository.py"
click node_alert_record "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/models/db_alert.py"
click node_api_main "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/api/main.py"
click node_ingest_router "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/api/routers/ingest.py"
click node_alerts_router "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/api/routers/alerts.py"
click node_stats_router "https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/api/routers/stats.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_ingest_service,node_auth_reader,node_linux_parser,node_access_reader,node_apache_parser,node_normalizer,node_event_models,node_api_clients toneBlue
class node_engine_factory,node_detection_engine,node_rule_contract,node_detection_rules,node_alert_model,node_mitre_mapping toneAmber
class node_database_config,node_alert_repository,node_alert_record,node_database toneMint
class node_api_main,node_ingest_router,node_alerts_router,node_stats_router toneRose
class node_log_files,node_dashboard toneIndigo
```

## Components

### Log processing

- [Ingestion service](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/services/ingestion.py): `app/services/ingestion.py`
- [Auth log reader](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/parsers/auth_log_reader.py): `app/parsers/auth_log_reader.py`
- [Linux parser](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/parsers/linux_parser.py): `app/parsers/linux_parser.py`
- [Access log reader](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/parsers/access_log_reader.py): `app/parsers/access_log_reader.py`
- [Apache parser](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/parsers/apache_parser.py): `app/parsers/apache_parser.py`
- [Event normalizer](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/services/normalizer.py): `app/services/normalizer.py`
- [Event models](https://github.com/sakoleat-kh/threat-detection-platform/tree/main/app/models): `app/models`

### Detection and enrichment

- [Engine factory](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/services/detection_engine.py): `app/services/detection_engine.py`
- [Detection engine](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/detection/engine.py): `app/detection/engine.py`
- [Rule interface](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/detection/rule_base.py): `app/detection/rule_base.py`
- [Detection rules](https://github.com/sakoleat-kh/threat-detection-platform/tree/main/app/detection/rules): `app/detection/rules`
- [Alert model](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/models/alert.py): `app/models/alert.py`
- [MITRE mapping](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/mitre/mapping.py): `app/mitre/mapping.py`

### Alert persistence

- [Database config](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/models/database.py): `app/models/database.py`
- [Alert repository](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/repository/alert_repository.py): `app/repository/alert_repository.py`
- [Alert record](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/models/db_alert.py): `app/models/db_alert.py`
- **SQLite database**

### REST API

- [API application](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/api/main.py): `app/api/main.py`
- [Ingestion endpoint](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/api/routers/ingest.py): `app/api/routers/ingest.py`
- [Alert endpoints](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/api/routers/alerts.py): `app/api/routers/alerts.py`
- [Statistics endpoint](https://github.com/sakoleat-kh/threat-detection-platform/blob/main/app/api/routers/stats.py): `app/api/routers/stats.py`

### Other components

- **Log files**
- **API clients**
- **Web dashboard**

## Connections

- Log files → Ingestion service: provides logs
- Ingestion service → Auth log reader: reads auth logs (evidence: `app/services/ingestion.py`)
- Ingestion service → Access log reader: reads access logs (evidence: `app/services/ingestion.py`)
- Auth log reader → Linux parser: parses lines (evidence: `app/parsers/auth_log_reader.py`)
- Access log reader → Apache parser: parses lines (evidence: `app/parsers/access_log_reader.py`)
- Ingestion service → Event normalizer: normalizes events (evidence: `app/services/ingestion.py`)
- Auth log reader → Event models: yields auth events (evidence: `app/parsers/auth_log_reader.py`)
- Access log reader → Event models: yields access events (evidence: `app/parsers/access_log_reader.py`)
- Event normalizer → Event models: creates normalized events (evidence: `app/services/normalizer.py`)
- Engine factory → Detection engine: creates engine (evidence: `app/services/detection_engine.py`)
- Engine factory → Detection rules: registers rules (evidence: `app/services/detection_engine.py`)
- Detection engine → Rule interface: evaluates rules (evidence: `app/detection/engine.py`)
- Detection rules → Rule interface: implement interface (evidence: `app/detection/rules/excessive_sudo.py`)
- Ingestion service → Detection engine: runs detection (evidence: `app/services/ingestion.py`)
- Detection engine → MITRE mapping: enriches alerts (evidence: `app/detection/engine.py`)
- Detection engine → Alert model: collects alerts (evidence: `app/detection/engine.py`)
- Ingestion service → Database config: opens session (evidence: `app/services/ingestion.py`)
- Ingestion service → Alert repository: saves alerts (evidence: `app/services/ingestion.py`)
- Alert repository → Alert record: creates records (evidence: `app/repository/alert_repository.py`)
- Database config → SQLite database: configures SQLite (evidence: `app/models/database.py`)
- Alert repository → SQLite database: queries and writes (evidence: `app/repository/alert_repository.py`)
- API application → Database config: initializes database (evidence: `app/api/main.py`)
- API application → Ingestion endpoint: mounts routes (evidence: `app/api/main.py`)
- API application → Alert endpoints: mounts routes (evidence: `app/api/main.py`)
- API application → Statistics endpoint: mounts routes (evidence: `app/api/main.py`)
- Ingestion endpoint → Ingestion service: invokes ingestion (evidence: `app/api/routers/ingest.py`)
- Ingestion endpoint → Engine factory: builds engine (evidence: `app/api/routers/ingest.py`)
- Alert endpoints → Alert repository: queries alerts (evidence: `app/api/routers/alerts.py`)
- Statistics endpoint → Alert repository: requests statistics (evidence: `app/api/routers/stats.py`)
- API clients → API application: requests API
- API application → Web dashboard: serves API data
