# razeini/wirewarden architecture

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

- Interactive diagram: https://gitdiagram.com/razeini/wirewarden
- Repository: https://github.com/razeini/wirewarden

## Overview

WireWarden is a hybrid Python/C network intrusion detection and prevention engine with a provisioned Grafana/Loki observability stack. Its primary workflow captures packets, queues them by flow for worker analysis, detects threats, applies defensive firewall rules when warranted, and emits structured logs for monitoring. The detection stages and monitoring flow are documented in the README; the supplied main.py excerpts show key runtime components, but omit some implementation details, so links rely on documented relationships where noted.

Main entry points: [`main.py`](https://github.com/razeini/wirewarden/blob/main/main.py) (Worker Pool), [`promtail-config.yml`](https://github.com/razeini/wirewarden/blob/main/promtail-config.yml) (Promtail), [`grafana/dashboards/dashboard-WireWarden Security Overview.json`](https://github.com/razeini/wirewarden/blob/main/grafana/dashboards/dashboard-WireWarden%20Security%20Overview.json) (Security Dashboard), [`grafana/provisioning/dashboards/dashboards.yml`](https://github.com/razeini/wirewarden/blob/main/grafana/provisioning/dashboards/dashboards.yml) (Dashboard Provisioning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and Analysis"]
  node_capture_engine["Packet Capture<br/>[main.py]"]
  node_flow_queue["Flow Queues<br/>[main.py]"]
  node_workers["Worker Pool<br/>[main.py]"]
end

subgraph group_detection["Threat Detection"]
  node_anomaly["Scan and DoS<br/>[main.py]"]
  node_dns["DNS Entropy<br/>[main.py]"]
  node_dpi_dispatch["DPI Pipeline<br/>[main.py]"]
  node_keyword_dpi["Keyword Matcher<br/>[main.py]"]
  node_native_dpi["Native Signatures<br/>[dpi.c]"]
  node_flow_tails["Flow Tail Tracking<br/>[main.py]"]
end

subgraph group_defense["Active Defense"]
  node_firewall["Firewall Manager<br/>[main.py]"]
  node_cleanup["Cleanup Worker<br/>[main.py]"]
end

subgraph group_observability["Observability"]
  node_json_logs["Structured Logs<br/>[main.py]"]
  node_promtail["Promtail"]
  node_loki[("Loki")]
  node_grafana["Grafana"]
  node_dashboard["Security Dashboard"]
  node_provisioning["Dashboard Provisioning<br/>[dashboards.yml]"]
end

node_nic(("Network Traffic"))

node_nic -->|"supplies packets"| node_capture_engine
node_capture_engine -->|"enqueues by flow"| node_flow_queue
node_flow_queue -->|"dispatches packets"| node_workers
node_workers -->|"checks traffic"| node_anomaly
node_workers -->|"checks queries"| node_dns
node_workers -->|"inspects payloads"| node_dpi_dispatch
node_dpi_dispatch -->|"scans keywords"| node_keyword_dpi
node_dpi_dispatch -->|"scans signatures"| node_native_dpi
node_dpi_dispatch -->|"tracks boundaries"| node_flow_tails
node_anomaly -->|"blocks offenders"| node_firewall
node_cleanup -->|"purges windows"| node_anomaly
node_cleanup -->|"expires rules"| node_firewall
node_workers -->|"writes events"| node_json_logs
node_firewall -->|"logs outcomes"| node_json_logs
node_json_logs -->|"ships log stream"| node_promtail
node_promtail -->|"pushes logs"| node_loki
node_loki -->|"feeds queries"| node_grafana
node_provisioning -->|"loads dashboard"| node_grafana
node_dashboard -->|"renders panels"| node_grafana

click node_capture_engine "https://github.com/razeini/wirewarden/blob/main/main.py"
click node_flow_queue "https://github.com/razeini/wirewarden/blob/main/main.py"
click node_workers "https://github.com/razeini/wirewarden/blob/main/main.py"
click node_anomaly "https://github.com/razeini/wirewarden/blob/main/main.py"
click node_dns "https://github.com/razeini/wirewarden/blob/main/main.py"
click node_dpi_dispatch "https://github.com/razeini/wirewarden/blob/main/main.py"
click node_keyword_dpi "https://github.com/razeini/wirewarden/blob/main/main.py"
click node_native_dpi "https://github.com/razeini/wirewarden/blob/main/c_src/dpi.c"
click node_flow_tails "https://github.com/razeini/wirewarden/blob/main/main.py"
click node_firewall "https://github.com/razeini/wirewarden/blob/main/main.py"
click node_cleanup "https://github.com/razeini/wirewarden/blob/main/main.py"
click node_json_logs "https://github.com/razeini/wirewarden/blob/main/main.py"
click node_promtail "https://github.com/razeini/wirewarden/blob/main/promtail-config.yml"
click node_dashboard "https://github.com/razeini/wirewarden/blob/main/grafana/dashboards/dashboard-WireWarden%20Security%20Overview.json"
click node_provisioning "https://github.com/razeini/wirewarden/blob/main/grafana/provisioning/dashboards/dashboards.yml"

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_engine,node_flow_queue,node_workers toneBlue
class node_anomaly,node_dns,node_dpi_dispatch,node_keyword_dpi,node_native_dpi,node_flow_tails toneAmber
class node_firewall,node_cleanup toneMint
class node_json_logs,node_promtail,node_loki,node_grafana,node_dashboard,node_provisioning toneRose
class node_nic toneIndigo
```

## Components

### Capture and Analysis

- [Packet Capture](https://github.com/razeini/wirewarden/blob/main/main.py): `main.py`
- [Flow Queues](https://github.com/razeini/wirewarden/blob/main/main.py): `main.py`
- [Worker Pool](https://github.com/razeini/wirewarden/blob/main/main.py): `main.py`

### Threat Detection

- [Scan and DoS](https://github.com/razeini/wirewarden/blob/main/main.py): `main.py`
- [DNS Entropy](https://github.com/razeini/wirewarden/blob/main/main.py): `main.py`
- [DPI Pipeline](https://github.com/razeini/wirewarden/blob/main/main.py): `main.py`
- [Keyword Matcher](https://github.com/razeini/wirewarden/blob/main/main.py): `main.py`
- [Native Signatures](https://github.com/razeini/wirewarden/blob/main/c_src/dpi.c): `c_src/dpi.c`
- [Flow Tail Tracking](https://github.com/razeini/wirewarden/blob/main/main.py): `main.py`

### Active Defense

- [Firewall Manager](https://github.com/razeini/wirewarden/blob/main/main.py): `main.py`
- [Cleanup Worker](https://github.com/razeini/wirewarden/blob/main/main.py): `main.py`

### Observability

- [Structured Logs](https://github.com/razeini/wirewarden/blob/main/main.py): `main.py`
- [Promtail](https://github.com/razeini/wirewarden/blob/main/promtail-config.yml): `promtail-config.yml`
- **Loki**
- **Grafana**
- [Security Dashboard](https://github.com/razeini/wirewarden/blob/main/grafana/dashboards/dashboard-WireWarden%20Security%20Overview.json): `grafana/dashboards/dashboard-WireWarden Security Overview.json`
- [Dashboard Provisioning](https://github.com/razeini/wirewarden/blob/main/grafana/provisioning/dashboards/dashboards.yml): `grafana/provisioning/dashboards/dashboards.yml`

### Other components

- **Network Traffic**

## Connections

- Network Traffic → Packet Capture: supplies packets (evidence: `README.md`)
- Packet Capture → Flow Queues: enqueues by flow (evidence: `main.py`)
- Flow Queues → Worker Pool: dispatches packets (evidence: `README.md`)
- Worker Pool → Scan and DoS: checks traffic (evidence: `README.md`)
- Worker Pool → DNS Entropy: checks queries (evidence: `main.py`)
- Worker Pool → DPI Pipeline: inspects payloads (evidence: `main.py`)
- DPI Pipeline → Keyword Matcher: scans keywords (evidence: `main.py`)
- DPI Pipeline → Native Signatures: scans signatures (evidence: `main.py`)
- DPI Pipeline → Flow Tail Tracking: tracks boundaries (evidence: `main.py`)
- Scan and DoS → Firewall Manager: blocks offenders (evidence: `README.md`)
- Cleanup Worker → Scan and DoS: purges windows (evidence: `README.md`)
- Cleanup Worker → Firewall Manager: expires rules (evidence: `README.md`)
- Worker Pool → Structured Logs: writes events (evidence: `README.md`)
- Firewall Manager → Structured Logs: logs outcomes (evidence: `main.py`)
- Structured Logs → Promtail: ships log stream (evidence: `README.md`)
- Promtail → Loki: pushes logs (evidence: `README.md`)
- Loki → Grafana: feeds queries (evidence: `README.md`)
- Dashboard Provisioning → Grafana: loads dashboard (evidence: `README.md`)
- Security Dashboard → Grafana: renders panels (evidence: `README.md`)
