# gorkemguler/net-sentinel architecture

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

- Interactive diagram: https://gitdiagram.com/gorkemguler/net-sentinel
- Repository: https://github.com/gorkemguler/net-sentinel

## Overview

NetSentinel monitors a local network through scheduled sensor collectors, sends their reports to a hub over an authenticated API, and turns them into device inventory, DNS observations, events, and alerts. Operators review and acknowledge results in the dashboard or API; notifications and AbuseIPDB enrichment are optional. The graph reflects the documented two-role workflow and sampled calls. Housekeeping and some enrichment details are documented but their runtime wiring was not sampled, so uncertain links are omitted.

Main entry points: [`src/netsentinel/hub/routes_api.py`](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/hub/routes_api.py) (Hub REST API), [`src/netsentinel/sensor/client.py`](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/sensor/client.py) (Hub client), [`src/netsentinel/sensor/runner.py`](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/sensor/runner.py) (Sensor scheduler), [`src/netsentinel/db.py`](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/db.py) (SQLite store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sensor["Sensor collection"]
  node_sensor_runner["Sensor scheduler<br/>[runner.py]"]
  node_arp["Device discovery<br/>[arp_discovery.py]"]
  node_passive_dns["Passive DNS<br/>[passive_dns.py]"]
  node_port_scan["Port scanning<br/>[port_scan.py]"]
  node_hub_client["Hub client<br/>[client.py]"]
end

subgraph group_hub["Hub processing"]
  node_wire_schema["Ingest contract<br/>[schemas.py]"]
  node_api["Hub REST API<br/>[routes_api.py]"]
  node_pipeline["Detection pipeline<br/>[pipeline.py]"]
  node_threatintel["Threat intelligence<br/>[threatintel.py]"]
  node_oui["Vendor lookup<br/>[oui.py]"]
  node_hub_app["Hub application<br/>[app.py]"]
end

subgraph group_state["State and configuration"]
  node_database[("SQLite store<br/>[db.py]")]
  node_models["Persisted records<br/>[models.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_operator["Operator views and alerts"]
  node_cli["CLI runtime<br/>[cli.py]"]
  node_dashboard_routes["Dashboard routes"]
  node_dashboard_templates["Dashboard views"]
  node_alerts["Alert delivery<br/>[alerts.py]"]
  node_notifier["Notification backends<br/>[notify.py]"]
  node_security["Authentication<br/>[security.py]"]
end

node_operator_actor(("Network operator"))
node_lan(("Local network"))
node_push_services["Push services"]
node_abuseipdb["AbuseIPDB"]

node_operator_actor -->|"starts roles"| node_cli
node_lan -->|"provides hosts"| node_arp
node_lan -->|"provides packets"| node_passive_dns
node_lan -->|"provides subnet"| node_port_scan
node_cli -->|"starts sensor"| node_sensor_runner
node_sensor_runner -->|"schedules discovery"| node_arp
node_sensor_runner -->|"schedules DNS flush"| node_passive_dns
node_sensor_runner -->|"schedules scans"| node_port_scan
node_sensor_runner -->|"sends reports"| node_hub_client
node_hub_client -->|"POSTs batches"| node_api
node_hub_client -->|"queries known devices"| node_api
node_api -->|"accepts batches"| node_wire_schema
node_hub_client -->|"serializes batches"| node_wire_schema
node_api -->|"processes ingest"| node_pipeline
node_pipeline -->|"creates records"| node_models
node_pipeline -->|"looks up vendors"| node_oui
node_pipeline -->|"checks indicators"| node_threatintel
node_api -->|"queries and updates"| node_database
node_dashboard_routes -->|"queries views"| node_database
node_dashboard_routes -->|"renders pages"| node_dashboard_templates
node_hub_app -->|"registers routes"| node_api
node_hub_app -->|"registers routes"| node_dashboard_routes
node_hub_app -->|"initializes store"| node_database
node_hub_app -->|"starts alert service"| node_alerts
node_alerts -->|"delivers alerts"| node_notifier
node_notifier -->|"sends notifications"| node_push_services
node_threatintel -.->|"enriches indicators"| node_abuseipdb
node_operator_actor -->|"reviews results"| node_dashboard_routes
node_operator_actor -->|"uses API"| node_api
node_operator_actor -->|"authenticates"| node_security
node_hub_client -->|"sends bearer token"| node_security
node_database -->|"stores tables"| node_models
node_config -->|"configures connection"| node_database
node_config -->|"configures uplink"| node_hub_client
node_config -->|"selects backend"| node_notifier

click node_cli "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/cli.py"
click node_sensor_runner "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/sensor/runner.py"
click node_arp "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/sensor/collectors/arp_discovery.py"
click node_passive_dns "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/sensor/collectors/passive_dns.py"
click node_port_scan "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/sensor/collectors/port_scan.py"
click node_hub_client "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/sensor/client.py"
click node_wire_schema "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/schemas.py"
click node_api "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/hub/routes_api.py"
click node_pipeline "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/hub/pipeline.py"
click node_threatintel "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/threatintel.py"
click node_oui "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/oui.py"
click node_hub_app "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/hub/app.py"
click node_dashboard_routes "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/hub/routes_dashboard.py"
click node_dashboard_templates "https://github.com/gorkemguler/net-sentinel/tree/main/src/netsentinel/hub/templates"
click node_alerts "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/hub/alerts.py"
click node_notifier "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/notify.py"
click node_security "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/security.py"
click node_database "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/db.py"
click node_models "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/models.py"
click node_config "https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/config.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_sensor_runner,node_arp,node_passive_dns,node_port_scan,node_hub_client toneBlue
class node_wire_schema,node_api,node_pipeline,node_threatintel,node_oui,node_hub_app toneAmber
class node_database,node_models,node_config toneMint
class node_cli,node_dashboard_routes,node_dashboard_templates,node_alerts,node_notifier,node_security toneRose
class node_operator_actor,node_lan,node_push_services,node_abuseipdb toneIndigo
```

## Components

### Sensor collection

- [Sensor scheduler](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/sensor/runner.py): `src/netsentinel/sensor/runner.py`
- [Device discovery](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/sensor/collectors/arp_discovery.py): `src/netsentinel/sensor/collectors/arp_discovery.py`
- [Passive DNS](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/sensor/collectors/passive_dns.py): `src/netsentinel/sensor/collectors/passive_dns.py`
- [Port scanning](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/sensor/collectors/port_scan.py): `src/netsentinel/sensor/collectors/port_scan.py`
- [Hub client](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/sensor/client.py): `src/netsentinel/sensor/client.py`

### Hub processing

- [Ingest contract](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/schemas.py): `src/netsentinel/schemas.py`
- [Hub REST API](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/hub/routes_api.py): `src/netsentinel/hub/routes_api.py`
- [Detection pipeline](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/hub/pipeline.py): `src/netsentinel/hub/pipeline.py`
- [Threat intelligence](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/threatintel.py): `src/netsentinel/threatintel.py`
- [Vendor lookup](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/oui.py): `src/netsentinel/oui.py`
- [Hub application](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/hub/app.py): `src/netsentinel/hub/app.py`

### State and configuration

- [SQLite store](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/db.py): `src/netsentinel/db.py`
- [Persisted records](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/models.py): `src/netsentinel/models.py`
- [Runtime settings](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/config.py): `src/netsentinel/config.py`

### Operator views and alerts

- [CLI runtime](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/cli.py): `src/netsentinel/cli.py`
- [Dashboard routes](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/hub/routes_dashboard.py): `src/netsentinel/hub/routes_dashboard.py`
- [Dashboard views](https://github.com/gorkemguler/net-sentinel/tree/main/src/netsentinel/hub/templates): `src/netsentinel/hub/templates`
- [Alert delivery](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/hub/alerts.py): `src/netsentinel/hub/alerts.py`
- [Notification backends](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/notify.py): `src/netsentinel/notify.py`
- [Authentication](https://github.com/gorkemguler/net-sentinel/blob/main/src/netsentinel/security.py): `src/netsentinel/security.py`

### Other components

- **Network operator**
- **Local network**
- **Push services**
- **AbuseIPDB**

## Connections

- Network operator → CLI runtime: starts roles (evidence: `README.md`)
- Local network → Device discovery: provides hosts (evidence: `README.md`)
- Local network → Passive DNS: provides packets (evidence: `README.md`)
- Local network → Port scanning: provides subnet (evidence: `README.md`)
- CLI runtime → Sensor scheduler: starts sensor (evidence: `src/netsentinel/cli.py`)
- Sensor scheduler → Device discovery: schedules discovery (evidence: `src/netsentinel/sensor/runner.py`)
- Sensor scheduler → Passive DNS: schedules DNS flush (evidence: `src/netsentinel/sensor/runner.py`)
- Sensor scheduler → Port scanning: schedules scans (evidence: `src/netsentinel/sensor/runner.py`)
- Sensor scheduler → Hub client: sends reports (evidence: `src/netsentinel/sensor/runner.py`)
- Hub client → Hub REST API: POSTs batches (evidence: `src/netsentinel/sensor/client.py`)
- Hub client → Hub REST API: queries known devices (evidence: `src/netsentinel/sensor/client.py`)
- Hub REST API → Ingest contract: accepts batches (evidence: `src/netsentinel/hub/routes_api.py`)
- Hub client → Ingest contract: serializes batches (evidence: `src/netsentinel/sensor/client.py`)
- Hub REST API → Detection pipeline: processes ingest (evidence: `src/netsentinel/hub/routes_api.py`)
- Detection pipeline → Persisted records: creates records (evidence: `src/netsentinel/hub/pipeline.py`)
- Detection pipeline → Vendor lookup: looks up vendors (evidence: `src/netsentinel/hub/pipeline.py`)
- Detection pipeline → Threat intelligence: checks indicators (evidence: `src/netsentinel/hub/pipeline.py`)
- Hub REST API → SQLite store: queries and updates (evidence: `src/netsentinel/hub/routes_api.py`)
- Dashboard routes → SQLite store: queries views (evidence: `src/netsentinel/hub/routes_dashboard.py`)
- Dashboard routes → Dashboard views: renders pages (evidence: `src/netsentinel/hub/routes_dashboard.py`)
- Hub application → Hub REST API: registers routes (evidence: `src/netsentinel/hub/app.py`)
- Hub application → Dashboard routes: registers routes (evidence: `src/netsentinel/hub/app.py`)
- Hub application → SQLite store: initializes store (evidence: `src/netsentinel/hub/app.py`)
- Hub application → Alert delivery: starts alert service (evidence: `src/netsentinel/hub/app.py`)
- Alert delivery → Notification backends: delivers alerts (evidence: `src/netsentinel/hub/alerts.py`)
- Notification backends → Push services: sends notifications (evidence: `src/netsentinel/notify.py`)
- Threat intelligence → AbuseIPDB: enriches indicators (evidence: `README.md`)
- Network operator → Dashboard routes: reviews results (evidence: `README.md`)
- Network operator → Hub REST API: uses API (evidence: `README.md`)
- Network operator → Authentication: authenticates
- Hub client → Authentication: sends bearer token (evidence: `src/netsentinel/sensor/client.py`)
- SQLite store → Persisted records: stores tables (evidence: `src/netsentinel/db.py`)
- Runtime settings → SQLite store: configures connection (evidence: `src/netsentinel/db.py`)
- Runtime settings → Hub client: configures uplink (evidence: `src/netsentinel/sensor/client.py`)
- Runtime settings → Notification backends: selects backend (evidence: `src/netsentinel/notify.py`)
