How atlegang-dotcom/portguard works
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: main.py Runtime entry · guard.py Packet decisions · capture.py SYN capture · alerting.py Alert formatting
Components 15
Runtime orchestration
- Runtime entry
port_guard/main.py - CLI options
port_guard/cli.py - Allowlist
port_guard/allowlist.py
Traffic capture
- Interface helper
port_guard/helper.py - SYN capture
port_guard/capture.py - Packet helpers
port_guard/helper.py
Scan analysis
- Packet decisions
port_guard/guard.py - Port tracker
port_guard/tracker.py - Window filtering
port_guard/helper.py - Scan detector
port_guard/detector.py
Alert output
- Alert formatting
port_guard/alerting.py
Other components
- Administrator
- Incoming packets
- Terminal
- JSONL log
Connections 22
- Administrator → CLI options: sets options
README.md - Runtime entry → CLI options: parses options
port_guard/main.py - Runtime entry → Interface helper: lists interfaces
port_guard/main.py - Runtime entry → Allowlist: loads allowlist
port_guard/main.py - Runtime entry → Port tracker: creates tracker
port_guard/main.py - Runtime entry → SYN capture: starts capture
port_guard/main.py - Incoming packets → SYN capture: supplies packets
README.md - SYN capture → Interface helper: lists interfaces
port_guard/capture.py - SYN capture → Packet helpers: extracts source IP
port_guard/capture.py - SYN capture → Runtime entry: calls callback
port_guard/main.py - Runtime entry → Packet decisions: handles packet
port_guard/main.py - Packet decisions → SYN capture: extracts SYN info
port_guard/guard.py - Packet decisions → Allowlist: checks source
port_guard/guard.py - Packet decisions → Port tracker: records and reads hits
port_guard/guard.py - Port tracker → Window filtering: filters hits
port_guard/tracker.py - Packet decisions → Scan detector: evaluates scan
port_guard/guard.py - Packet decisions → Alert formatting: builds alert
port_guard/guard.py - Runtime entry → Port tracker: prunes history
port_guard/main.py - Runtime entry → Alert formatting: formats alert
port_guard/main.py - Alert formatting → Terminal: renders message
README.md - Runtime entry → Alert formatting: logs optionally
port_guard/main.py - Alert formatting → JSONL log: appends JSONL
port_guard/alerting.py