# vidura2/project-psd architecture

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

- Interactive diagram: https://gitdiagram.com/vidura2/project-psd
- Repository: https://github.com/vidura2/project-psd

## Overview

A single-file passive detector captures TCP traffic, filters eligible SYN packets and ignored sources, then tracks unique destinations in sliding windows to detect vertical and horizontal scans. Per-source cooldown controls alert emission; alerts go to stdout and a log file. The README also describes deployment visibility and distributed log aggregation, but those are operational arrangements rather than implemented subsystems. The graph reflects the sampled implementation in the sole source file.

Main entry points: [`port_scan_detector.py`](https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py) (Alert formatting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Packet capture"]
  node_cli["CLI setup"]
  node_detector["Detector startup"]
end

subgraph group_detection["Scan detection"]
  node_packet_filter["Packet filtering"]
  node_allowlist["Ignore sources"]
  node_trackers[("Window trackers")]
  node_pruning["Window pruning"]
  node_vertical["Vertical detection"]
  node_horizontal["Horizontal detection"]
end

subgraph group_alerting["Alerting"]
  node_cooldown[("Cooldown tracking")]
  node_alert["Alert formatting"]
  node_logger["Alert logging"]
end

node_operator(("Operator"))
node_scapy["Scapy sniff"]
node_stdout["Standard output"]
node_logfile["Alert log file"]

node_operator -->|"configures"| node_cli
node_cli -->|"constructs"| node_detector
node_detector -->|"starts capture"| node_scapy
node_scapy -->|"delivers packets"| node_packet_filter
node_packet_filter -->|"checks source"| node_allowlist
node_allowlist -->|"records eligible"| node_trackers
node_trackers -->|"supplies timestamps"| node_pruning
node_pruning -->|"counts ports"| node_vertical
node_pruning -->|"counts hosts"| node_horizontal
node_vertical -->|"triggers"| node_alert
node_horizontal -->|"triggers"| node_alert
node_alert -->|"checks cooldown"| node_cooldown
node_alert -->|"emits message"| node_logger
node_logger -->|"writes"| node_stdout
node_logger -->|"writes"| node_logfile

click node_cli "https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py"
click node_detector "https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py"
click node_packet_filter "https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py"
click node_allowlist "https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py"
click node_trackers "https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py"
click node_pruning "https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py"
click node_vertical "https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py"
click node_horizontal "https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py"
click node_cooldown "https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py"
click node_alert "https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py"
click node_logger "https://github.com/vidura2/project-psd/blob/main/port_scan_detector.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_cli,node_detector toneBlue
class node_packet_filter,node_allowlist,node_trackers,node_pruning,node_vertical,node_horizontal toneAmber
class node_cooldown,node_alert,node_logger toneMint
class node_operator,node_scapy,node_stdout,node_logfile toneIndigo
```

## Components

### Packet capture

- [CLI setup](https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py): `port_scan_detector.py`
- [Detector startup](https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py): `port_scan_detector.py`

### Scan detection

- [Packet filtering](https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py): `port_scan_detector.py`
- [Ignore sources](https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py): `port_scan_detector.py`
- [Window trackers](https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py): `port_scan_detector.py`
- [Window pruning](https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py): `port_scan_detector.py`
- [Vertical detection](https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py): `port_scan_detector.py`
- [Horizontal detection](https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py): `port_scan_detector.py`

### Alerting

- [Cooldown tracking](https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py): `port_scan_detector.py`
- [Alert formatting](https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py): `port_scan_detector.py`
- [Alert logging](https://github.com/vidura2/project-psd/blob/main/port_scan_detector.py): `port_scan_detector.py`

### Other components

- **Operator**
- **Scapy sniff**
- **Standard output**
- **Alert log file**

## Connections

- Operator → CLI setup: configures
- CLI setup → Detector startup: constructs
- Detector startup → Scapy sniff: starts capture
- Scapy sniff → Packet filtering: delivers packets
- Packet filtering → Ignore sources: checks source
- Ignore sources → Window trackers: records eligible
- Window trackers → Window pruning: supplies timestamps
- Window pruning → Vertical detection: counts ports
- Window pruning → Horizontal detection: counts hosts
- Vertical detection → Alert formatting: triggers
- Horizontal detection → Alert formatting: triggers
- Alert formatting → Cooldown tracking: checks cooldown
- Alert formatting → Alert logging: emits message
- Alert logging → Standard output: writes
- Alert logging → Alert log file: writes