# atlegang-dotcom/portguard architecture

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

- Interactive diagram: https://gitdiagram.com/atlegang-dotcom/portguard
- Repository: https://github.com/atlegang-dotcom/portguard

## Overview

PortGuard is a command-line TCP port-scan monitor. The administrator configures a threshold, rolling window, and optional allowlist or log; the runtime captures incoming SYN packets, filters allowed sources, tracks distinct destination ports, evaluates scan status and severity, then prints alerts and optionally appends JSON lines. The graph follows the calls shown in the excerpts. Capture, tracking, filtering, and alert construction are distinct stages; helper functions support those stages. The external packet source, terminal, and optional log file are shown separately.

Main entry points: [`port_guard/main.py`](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/main.py) (Runtime entry), [`port_guard/guard.py`](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/guard.py) (Packet decisions), [`port_guard/capture.py`](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/capture.py) (SYN capture), [`port_guard/alerting.py`](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/alerting.py) (Alert formatting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_main["Runtime entry<br/>[main.py]"]
  node_cli["CLI options<br/>[cli.py]"]
  node_allowlist["Allowlist<br/>[allowlist.py]"]
end

subgraph group_traffic["Traffic capture"]
  node_interface_helper["Interface helper<br/>[helper.py]"]
  node_capture["SYN capture<br/>[capture.py]"]
  node_packet_helper["Packet helpers<br/>[helper.py]"]
end

subgraph group_analysis["Scan analysis"]
  node_guard["Packet decisions<br/>[guard.py]"]
  node_tracker["Port tracker<br/>[tracker.py]"]
  node_time_helper["Window filtering<br/>[helper.py]"]
  node_detector["Scan detector<br/>[detector.py]"]
end

subgraph group_alerts["Alert output"]
  node_alerting["Alert formatting<br/>[alerting.py]"]
end

node_admin(("Administrator"))
node_packet_source(("Incoming packets"))
node_terminal(("Terminal"))
node_log_file["JSONL log"]

node_admin -->|"sets options"| node_cli
node_main -->|"parses options"| node_cli
node_main -->|"lists interfaces"| node_interface_helper
node_main -->|"loads allowlist"| node_allowlist
node_main -->|"creates tracker"| node_tracker
node_main -->|"starts capture"| node_capture
node_packet_source -->|"supplies packets"| node_capture
node_capture -->|"lists interfaces"| node_interface_helper
node_capture -->|"extracts source IP"| node_packet_helper
node_capture -->|"calls callback"| node_main
node_main -->|"handles packet"| node_guard
node_guard -->|"extracts SYN info"| node_capture
node_guard -->|"checks source"| node_allowlist
node_guard -->|"records and reads hits"| node_tracker
node_tracker -->|"filters hits"| node_time_helper
node_guard -->|"evaluates scan"| node_detector
node_guard -->|"builds alert"| node_alerting
node_main -->|"prunes history"| node_tracker
node_main -->|"formats alert"| node_alerting
node_alerting -->|"renders message"| node_terminal
node_main -->|"logs optionally"| node_alerting
node_alerting -->|"appends JSONL"| node_log_file

click node_main "https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/main.py"
click node_cli "https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/cli.py"
click node_allowlist "https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/allowlist.py"
click node_interface_helper "https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/helper.py"
click node_capture "https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/capture.py"
click node_packet_helper "https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/helper.py"
click node_guard "https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/guard.py"
click node_tracker "https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/tracker.py"
click node_time_helper "https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/helper.py"
click node_detector "https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/detector.py"
click node_alerting "https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/alerting.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_main,node_cli,node_allowlist toneBlue
class node_interface_helper,node_capture,node_packet_helper toneAmber
class node_guard,node_tracker,node_time_helper,node_detector toneMint
class node_alerting toneRose
class node_admin,node_packet_source,node_terminal,node_log_file toneIndigo
```

## Components

### Runtime orchestration

- [Runtime entry](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/main.py): `port_guard/main.py`
- [CLI options](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/cli.py): `port_guard/cli.py`
- [Allowlist](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/allowlist.py): `port_guard/allowlist.py`

### Traffic capture

- [Interface helper](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/helper.py): `port_guard/helper.py`
- [SYN capture](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/capture.py): `port_guard/capture.py`
- [Packet helpers](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/helper.py): `port_guard/helper.py`

### Scan analysis

- [Packet decisions](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/guard.py): `port_guard/guard.py`
- [Port tracker](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/tracker.py): `port_guard/tracker.py`
- [Window filtering](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/helper.py): `port_guard/helper.py`
- [Scan detector](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/detector.py): `port_guard/detector.py`

### Alert output

- [Alert formatting](https://github.com/atlegang-dotcom/portguard/blob/main/port_guard/alerting.py): `port_guard/alerting.py`

### Other components

- **Administrator**
- **Incoming packets**
- **Terminal**
- **JSONL log**

## Connections

- Administrator → CLI options: sets options (evidence: `README.md`)
- Runtime entry → CLI options: parses options (evidence: `port_guard/main.py`)
- Runtime entry → Interface helper: lists interfaces (evidence: `port_guard/main.py`)
- Runtime entry → Allowlist: loads allowlist (evidence: `port_guard/main.py`)
- Runtime entry → Port tracker: creates tracker (evidence: `port_guard/main.py`)
- Runtime entry → SYN capture: starts capture (evidence: `port_guard/main.py`)
- Incoming packets → SYN capture: supplies packets (evidence: `README.md`)
- SYN capture → Interface helper: lists interfaces (evidence: `port_guard/capture.py`)
- SYN capture → Packet helpers: extracts source IP (evidence: `port_guard/capture.py`)
- SYN capture → Runtime entry: calls callback (evidence: `port_guard/main.py`)
- Runtime entry → Packet decisions: handles packet (evidence: `port_guard/main.py`)
- Packet decisions → SYN capture: extracts SYN info (evidence: `port_guard/guard.py`)
- Packet decisions → Allowlist: checks source (evidence: `port_guard/guard.py`)
- Packet decisions → Port tracker: records and reads hits (evidence: `port_guard/guard.py`)
- Port tracker → Window filtering: filters hits (evidence: `port_guard/tracker.py`)
- Packet decisions → Scan detector: evaluates scan (evidence: `port_guard/guard.py`)
- Packet decisions → Alert formatting: builds alert (evidence: `port_guard/guard.py`)
- Runtime entry → Port tracker: prunes history (evidence: `port_guard/main.py`)
- Runtime entry → Alert formatting: formats alert (evidence: `port_guard/main.py`)
- Alert formatting → Terminal: renders message (evidence: `README.md`)
- Runtime entry → Alert formatting: logs optionally (evidence: `port_guard/main.py`)
- Alert formatting → JSONL log: appends JSONL (evidence: `port_guard/alerting.py`)
