# jermsmit/whats-scanning-me architecture

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

- Interactive diagram: https://gitdiagram.com/jermsmit/whats-scanning-me
- Repository: https://github.com/jermsmit/whats-scanning-me
- Video tour (about a minute): https://gitdiagram.com/jermsmit/whats-scanning-me/video

## Overview

What's Scanning Me? is a lightweight Flask honeypot: it listens on configured attack ports, records connection attempts, and presents threat summaries and controls in a web dashboard. The main flow is incoming TCP/selected UDP traffic → event enrichment and logging → dashboard statistics or JSON export; operators can also change monitored ports through the UI. Source excerpts show the listener, event, storage, and route behavior in app.py. The README documents additional dashboard summaries and persistence; unsampled details are represented only where that documentation supports them.

Main entry points: [`app.py`](https://github.com/jermsmit/whats-scanning-me/blob/main/app.py) (Event enrichment), [`templates/dashboard.html`](https://github.com/jermsmit/whats-scanning-me/blob/main/templates/dashboard.html) (Live dashboard), [`templates/ports.html`](https://github.com/jermsmit/whats-scanning-me/blob/main/templates/ports.html) (Port controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Traffic Capture"]
  node_tcp["TCP listener<br/>[app.py]"]
  node_udp["UDP listener<br/>[app.py]"]
  node_listener_control["Listener control<br/>[app.py]"]
end

subgraph group_records["Event Records"]
  node_event_capture["Event enrichment<br/>[app.py]"]
  node_memory_events[("In-memory events<br/>[app.py]")]
  node_jsonl_log[("Persistent scan log<br/>[app.py]")]
end

subgraph group_web["Dashboard and API"]
  node_dashboard["Dashboard route<br/>[app.py]"]
  node_stats["Threat statistics<br/>[app.py]"]
  node_dashboard_ui["Live dashboard<br/>[dashboard.html]"]
  node_export_api["JSON export<br/>[app.py]"]
end

subgraph group_settings["Monitoring Controls"]
  node_config[("Port configuration<br/>[app.py]")]
  node_port_management["Port management route<br/>[app.py]"]
  node_ports_ui["Port controls<br/>[ports.html]"]
end

node_attacker(("Remote scanner"))
node_hostname_dns["Hostname resolver"]
node_operator(("Operator"))
node_browser["Web browser"]

node_attacker -->|"connects TCP"| node_tcp
node_attacker -->|"sends UDP"| node_udp
node_tcp -->|"dispatches event"| node_event_capture
node_udp -->|"dispatches event"| node_event_capture
node_event_capture -.->|"resolves hostname"| node_hostname_dns
node_event_capture -->|"reads service config"| node_config
node_event_capture -->|"updates events"| node_memory_events
node_event_capture -->|"appends record"| node_jsonl_log
node_jsonl_log -->|"loads history"| node_memory_events
node_listener_control -->|"reads ports"| node_config
node_listener_control -->|"starts listener"| node_tcp
node_listener_control -->|"starts listener"| node_udp
node_browser -->|"requests page"| node_dashboard
node_dashboard -->|"renders page"| node_dashboard_ui
node_dashboard_ui -->|"polls summaries"| node_stats
node_stats -->|"reads events"| node_memory_events
node_browser -->|"submits changes"| node_port_management
node_port_management -->|"renders controls"| node_ports_ui
node_port_management -->|"saves ports"| node_config
node_port_management -->|"changes listener"| node_listener_control
node_browser -->|"requests export"| node_export_api
node_export_api -->|"reads events"| node_memory_events
node_operator -->|"views dashboard"| node_browser

click node_tcp "https://github.com/jermsmit/whats-scanning-me/blob/main/app.py"
click node_udp "https://github.com/jermsmit/whats-scanning-me/blob/main/app.py"
click node_listener_control "https://github.com/jermsmit/whats-scanning-me/blob/main/app.py"
click node_event_capture "https://github.com/jermsmit/whats-scanning-me/blob/main/app.py"
click node_memory_events "https://github.com/jermsmit/whats-scanning-me/blob/main/app.py"
click node_jsonl_log "https://github.com/jermsmit/whats-scanning-me/blob/main/app.py"
click node_config "https://github.com/jermsmit/whats-scanning-me/blob/main/app.py"
click node_dashboard "https://github.com/jermsmit/whats-scanning-me/blob/main/app.py"
click node_stats "https://github.com/jermsmit/whats-scanning-me/blob/main/app.py"
click node_dashboard_ui "https://github.com/jermsmit/whats-scanning-me/blob/main/templates/dashboard.html"
click node_port_management "https://github.com/jermsmit/whats-scanning-me/blob/main/app.py"
click node_ports_ui "https://github.com/jermsmit/whats-scanning-me/blob/main/templates/ports.html"
click node_export_api "https://github.com/jermsmit/whats-scanning-me/blob/main/app.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_tcp,node_udp,node_listener_control,node_browser toneBlue
class node_event_capture,node_memory_events,node_jsonl_log toneAmber
class node_dashboard,node_stats,node_dashboard_ui,node_export_api toneMint
class node_config,node_port_management,node_ports_ui toneRose
class node_attacker,node_hostname_dns,node_operator toneIndigo
```

## Components

### Traffic Capture

- [TCP listener](https://github.com/jermsmit/whats-scanning-me/blob/main/app.py): `app.py`
- [UDP listener](https://github.com/jermsmit/whats-scanning-me/blob/main/app.py): `app.py`
- [Listener control](https://github.com/jermsmit/whats-scanning-me/blob/main/app.py): `app.py`

### Event Records

- [Event enrichment](https://github.com/jermsmit/whats-scanning-me/blob/main/app.py): `app.py`
- [In-memory events](https://github.com/jermsmit/whats-scanning-me/blob/main/app.py): `app.py`
- [Persistent scan log](https://github.com/jermsmit/whats-scanning-me/blob/main/app.py): `app.py`

### Dashboard and API

- [Dashboard route](https://github.com/jermsmit/whats-scanning-me/blob/main/app.py): `app.py`
- [Threat statistics](https://github.com/jermsmit/whats-scanning-me/blob/main/app.py): `app.py`
- [Live dashboard](https://github.com/jermsmit/whats-scanning-me/blob/main/templates/dashboard.html): `templates/dashboard.html`
- [JSON export](https://github.com/jermsmit/whats-scanning-me/blob/main/app.py): `app.py`

### Monitoring Controls

- [Port configuration](https://github.com/jermsmit/whats-scanning-me/blob/main/app.py): `app.py`
- [Port management route](https://github.com/jermsmit/whats-scanning-me/blob/main/app.py): `app.py`
- [Port controls](https://github.com/jermsmit/whats-scanning-me/blob/main/templates/ports.html): `templates/ports.html`

### Other components

- **Remote scanner**
- **Hostname resolver**
- **Operator**
- **Web browser**

## Connections

- Remote scanner → TCP listener: connects TCP
- Remote scanner → UDP listener: sends UDP
- TCP listener → Event enrichment: dispatches event
- UDP listener → Event enrichment: dispatches event
- Event enrichment → Hostname resolver: resolves hostname
- Event enrichment → Port configuration: reads service config
- Event enrichment → In-memory events: updates events
- Event enrichment → Persistent scan log: appends record
- Persistent scan log → In-memory events: loads history
- Listener control → Port configuration: reads ports
- Listener control → TCP listener: starts listener
- Listener control → UDP listener: starts listener
- Web browser → Dashboard route: requests page
- Dashboard route → Live dashboard: renders page
- Live dashboard → Threat statistics: polls summaries
- Threat statistics → In-memory events: reads events
- Web browser → Port management route: submits changes
- Port management route → Port controls: renders controls
- Port management route → Port configuration: saves ports
- Port management route → Listener control: changes listener
- Web browser → JSON export: requests export
- JSON export → In-memory events: reads events
- Operator → Web browser: views dashboard