# dr4cule/ntro-sentinel architecture

> Architecture diagram of the GitHub repository dr4cule/ntro-sentinel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dr4cule/ntro-sentinel
- Repository: https://github.com/dr4cule/ntro-sentinel

## Overview

NTRO Sentinel passively turns mirrored traffic metadata or uploaded/replayed captures into bounded-window detections, correlated alerts, and tamper-evident records delivered through a REST/WebSocket API and analyst dashboard. The graph preserves the six documented threat classes, optional ML enrichment, and telemetry. The supplied tree does not include the dashboard asset, and several implementation excerpts are partial; dashboard delivery is therefore represented at the documented API surface, without inferring its internal implementation.

Main entry points: [`engine/stream_consumer.py`](https://github.com/dr4cule/ntro-sentinel/blob/main/engine/stream_consumer.py) (Stream Pipeline), [`ingest/service.py`](https://github.com/dr4cule/ntro-sentinel/blob/main/ingest/service.py) (Ingest Service), [`alertstore/store.py`](https://github.com/dr4cule/ntro-sentinel/blob/main/alertstore/store.py) (Hash-Chained Store), [`api/main.py`](https://github.com/dr4cule/ntro-sentinel/blob/main/api/main.py) (REST and WebSocket API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Metadata Ingest"]
  node_capture["PCAP Adapter<br/>[pcap_to_events.py]"]
  node_service["Ingest Service<br/>[service.py]"]
  node_tailer["Event Normalizer<br/>[tailer.py]"]
end

subgraph group_detect["Detection Pipeline"]
  node_pipeline["Stream Pipeline<br/>[stream_consumer.py]"]
  node_windows["Feature Windows"]
  node_ddos["DDoS Detection<br/>[rules.py]"]
  node_c2["C2 Detection<br/>[rules.py]"]
  node_dns["DGA DNS Detection<br/>[rules.py]"]
  node_tls["Encrypted Malware<br/>[rules.py]"]
  node_recon["Recon Detection<br/>[rules.py]"]
  node_exfil["Exfil Detection<br/>[rules.py]"]
  node_correlator["Source Correlator<br/>[engine.py]"]
  node_metrics["Stream Metrics<br/>[metrics.py]"]
end

subgraph group_evidence["Evidence Store"]
  node_store[("Hash-Chained Store<br/>[store.py]")]
end

subgraph group_delivery["Analyst Delivery"]
  node_api["REST and WebSocket API<br/>[main.py]"]
end

subgraph group_enrichment["Optional Enrichment"]
  node_ml["ML Inference<br/>[inference.py]"]
end

node_mirror(("Mirrored Traffic"))
node_filedrop(("Capture Files"))
node_analyst(("Analyst"))
node_redis["Redis Stream"]

node_mirror -->|"captures metadata"| node_service
node_filedrop -->|"supplies captures"| node_service
node_service -->|"parses PCAP"| node_capture
node_service -->|"normalizes logs"| node_tailer
node_capture -->|"queues events"| node_pipeline
node_tailer -->|"queues events"| node_pipeline
node_service -->|"dispatches events"| node_pipeline
node_pipeline -->|"updates windows"| node_windows
node_pipeline -->|"evaluates"| node_ddos
node_pipeline -->|"evaluates"| node_c2
node_pipeline -->|"evaluates"| node_dns
node_pipeline -->|"evaluates"| node_tls
node_pipeline -->|"evaluates"| node_recon
node_pipeline -->|"evaluates"| node_exfil
node_pipeline -->|"correlates alerts"| node_correlator
node_pipeline -->|"writes alerts"| node_store
node_service -->|"writes alerts and metrics"| node_store
node_pipeline -->|"observes processing"| node_metrics
node_service -->|"observes processing"| node_metrics
node_api -->|"reads and verifies"| node_store
node_api -->|"appends alerts"| node_store
node_analyst -->|"views and queries"| node_api
node_redis -.->|"streams events"| node_pipeline
node_dns -.->|"scores labels"| node_ml
node_exfil -.->|"enriches evidence"| node_ml

click node_capture "https://github.com/dr4cule/ntro-sentinel/blob/main/ingest/pcap_to_events.py"
click node_service "https://github.com/dr4cule/ntro-sentinel/blob/main/ingest/service.py"
click node_tailer "https://github.com/dr4cule/ntro-sentinel/blob/main/ingest/tailer.py"
click node_pipeline "https://github.com/dr4cule/ntro-sentinel/blob/main/engine/stream_consumer.py"
click node_windows "https://github.com/dr4cule/ntro-sentinel/tree/main/features"
click node_ddos "https://github.com/dr4cule/ntro-sentinel/blob/main/detectors/rules.py"
click node_c2 "https://github.com/dr4cule/ntro-sentinel/blob/main/detectors/rules.py"
click node_dns "https://github.com/dr4cule/ntro-sentinel/blob/main/detectors/rules.py"
click node_tls "https://github.com/dr4cule/ntro-sentinel/blob/main/detectors/rules.py"
click node_recon "https://github.com/dr4cule/ntro-sentinel/blob/main/detectors/rules.py"
click node_exfil "https://github.com/dr4cule/ntro-sentinel/blob/main/detectors/rules.py"
click node_correlator "https://github.com/dr4cule/ntro-sentinel/blob/main/correlation/engine.py"
click node_metrics "https://github.com/dr4cule/ntro-sentinel/blob/main/engine/metrics.py"
click node_store "https://github.com/dr4cule/ntro-sentinel/blob/main/alertstore/store.py"
click node_api "https://github.com/dr4cule/ntro-sentinel/blob/main/api/main.py"
click node_ml "https://github.com/dr4cule/ntro-sentinel/blob/main/models/inference.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_capture,node_service,node_tailer toneBlue
class node_pipeline,node_windows,node_ddos,node_c2,node_dns,node_tls,node_recon,node_exfil,node_correlator,node_metrics,node_redis toneAmber
class node_store toneMint
class node_api toneRose
class node_ml,node_mirror,node_filedrop,node_analyst toneIndigo
```

## Components

### Metadata Ingest

- [PCAP Adapter](https://github.com/dr4cule/ntro-sentinel/blob/main/ingest/pcap_to_events.py): `ingest/pcap_to_events.py`
- [Ingest Service](https://github.com/dr4cule/ntro-sentinel/blob/main/ingest/service.py): `ingest/service.py`
- [Event Normalizer](https://github.com/dr4cule/ntro-sentinel/blob/main/ingest/tailer.py): `ingest/tailer.py`

### Detection Pipeline

- [Stream Pipeline](https://github.com/dr4cule/ntro-sentinel/blob/main/engine/stream_consumer.py): `engine/stream_consumer.py`
- [Feature Windows](https://github.com/dr4cule/ntro-sentinel/tree/main/features): `features`
- [DDoS Detection](https://github.com/dr4cule/ntro-sentinel/blob/main/detectors/rules.py): `detectors/rules.py`
- [C2 Detection](https://github.com/dr4cule/ntro-sentinel/blob/main/detectors/rules.py): `detectors/rules.py`
- [DGA DNS Detection](https://github.com/dr4cule/ntro-sentinel/blob/main/detectors/rules.py): `detectors/rules.py`
- [Encrypted Malware](https://github.com/dr4cule/ntro-sentinel/blob/main/detectors/rules.py): `detectors/rules.py`
- [Recon Detection](https://github.com/dr4cule/ntro-sentinel/blob/main/detectors/rules.py): `detectors/rules.py`
- [Exfil Detection](https://github.com/dr4cule/ntro-sentinel/blob/main/detectors/rules.py): `detectors/rules.py`
- [Source Correlator](https://github.com/dr4cule/ntro-sentinel/blob/main/correlation/engine.py): `correlation/engine.py`
- [Stream Metrics](https://github.com/dr4cule/ntro-sentinel/blob/main/engine/metrics.py): `engine/metrics.py`

### Evidence Store

- [Hash-Chained Store](https://github.com/dr4cule/ntro-sentinel/blob/main/alertstore/store.py): `alertstore/store.py`

### Analyst Delivery

- [REST and WebSocket API](https://github.com/dr4cule/ntro-sentinel/blob/main/api/main.py): `api/main.py`

### Optional Enrichment

- [ML Inference](https://github.com/dr4cule/ntro-sentinel/blob/main/models/inference.py): `models/inference.py`

### Other components

- **Mirrored Traffic**
- **Capture Files**
- **Analyst**
- **Redis Stream**

## Connections

- Mirrored Traffic → Ingest Service: captures metadata
- Capture Files → Ingest Service: supplies captures
- Ingest Service → PCAP Adapter: parses PCAP
- Ingest Service → Event Normalizer: normalizes logs
- PCAP Adapter → Stream Pipeline: queues events
- Event Normalizer → Stream Pipeline: queues events
- Ingest Service → Stream Pipeline: dispatches events
- Stream Pipeline → Feature Windows: updates windows
- Stream Pipeline → DDoS Detection: evaluates
- Stream Pipeline → C2 Detection: evaluates
- Stream Pipeline → DGA DNS Detection: evaluates
- Stream Pipeline → Encrypted Malware: evaluates
- Stream Pipeline → Recon Detection: evaluates
- Stream Pipeline → Exfil Detection: evaluates
- Stream Pipeline → Source Correlator: correlates alerts
- Stream Pipeline → Hash-Chained Store: writes alerts
- Ingest Service → Hash-Chained Store: writes alerts and metrics
- Stream Pipeline → Stream Metrics: observes processing
- Ingest Service → Stream Metrics: observes processing
- REST and WebSocket API → Hash-Chained Store: reads and verifies
- REST and WebSocket API → Hash-Chained Store: appends alerts
- Analyst → REST and WebSocket API: views and queries
- Redis Stream → Stream Pipeline: streams events
- DGA DNS Detection → ML Inference: scores labels
- Exfil Detection → ML Inference: enriches evidence