# parathputhuvai/packet-watch architecture

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

- Interactive diagram: https://gitdiagram.com/parathputhuvai/packet-watch
- Repository: https://github.com/parathputhuvai/packet-watch

## Overview

Packet Watch is a passive, Windows command-line network intrusion analyzer. Its principal workflow captures live packets, parses them into normalized fields, enriches TLS fingerprints, updates rolling per-source state, evaluates signature detectors, scores and filters alerts, then presents them and writes periodic or final PDF/CSV reports. The graph also preserves the documented reputation, MITRE, and timeline capabilities. Source excerpts support the main orchestration and several internal calls; some subsystem links are based on the README, and unsampled integrations are not expanded beyond documented behavior.

Main entry points: [`packet_watch/cli/app.py`](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/cli/app.py) (Monitor orchestration), [`packet_watch/detection/engine.py`](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/detection/engine.py) (Detection engine), [`packet_watch/cli/main.py`](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/cli/main.py) (CLI commands), [`packet_watch/capture/live.py`](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/capture/live.py) (Live capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and capture"]
  node_cli["CLI commands<br/>[main.py]"]
  node_settings["Configuration<br/>[settings.py]"]
  node_capture["Live capture<br/>[live.py]"]
  node_app["Monitor orchestration<br/>[app.py]"]
end

subgraph group_analysis["Packet analysis"]
  node_parser["Packet parser<br/>[packet_parser.py]"]
  node_tls["JA3 enrichment<br/>[pipeline.py]"]
  node_sslbl["SSLBL feed client<br/>[ja3.py]"]
  node_rolling[("Rolling state<br/>[rolling.py]")]
  node_signatures["Signature detectors"]
  node_detector_common["Rule helpers<br/>[common.py]"]
  node_engine["Detection engine<br/>[engine.py]"]
  node_models["Packet and alert models<br/>[models.py]"]
end

subgraph group_alerting["Alert enrichment"]
  node_severity["Severity scoring<br/>[scoring.py]"]
  node_whitelist["Whitelist filtering<br/>[filter.py]"]
  node_reputation["IP reputation<br/>[abuseipdb.py]"]
  node_mitre["MITRE mapping<br/>[mapping.py]"]
  node_timeline["Alert timeline<br/>[timeline.py]"]
  node_logging["Logging<br/>[logging.py]"]
end

subgraph group_output["Presentation and reports"]
  node_terminal["Rich terminal output<br/>[app.py]"]
  node_csv["CSV reports<br/>[csv_report.py]"]
  node_pdf["PDF reports<br/>[pdf_report.py]"]
end

node_operator(("Operator"))
node_abuse_service(("AbuseIPDB"))
node_sslbl_service(("SSLBL threat feed"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_settings
node_cli -->|"dispatches commands"| node_app
node_app -->|"starts capture"| node_capture
node_capture -->|"delivers packets"| node_app
node_app -->|"parses packets"| node_parser
node_app -->|"enriches TLS"| node_tls
node_tls -->|"calculates and looks up"| node_sslbl
node_sslbl -->|"fetches feed"| node_sslbl_service
node_app -->|"processes parsed packets"| node_engine
node_engine -->|"observes packet"| node_rolling
node_engine -->|"dispatches detection"| node_signatures
node_signatures -->|"uses rule helpers"| node_detector_common
node_rolling -->|"uses request heuristics"| node_detector_common
node_engine -->|"scores results"| node_severity
node_engine -->|"checks suppression"| node_whitelist
node_engine -->|"creates alerts"| node_models
node_app -.->|"enriches alert IPs"| node_reputation
node_app -->|"records alerts"| node_timeline
node_app -->|"prints alerts"| node_terminal
node_app -->|"writes CSV"| node_csv
node_app -->|"writes PDF"| node_pdf
node_reputation -.->|"queries reputation"| node_abuse_service
node_app -->|"sets up logging"| node_logging

click node_cli "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/cli/main.py"
click node_settings "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/config/settings.py"
click node_capture "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/capture/live.py"
click node_parser "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/parser/packet_parser.py"
click node_tls "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/threat_intel/pipeline.py"
click node_sslbl "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/threat_intel/ja3.py"
click node_rolling "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/state/rolling.py"
click node_signatures "https://github.com/parathputhuvai/packet-watch/tree/main/packet_watch/detectors"
click node_detector_common "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/detectors/common.py"
click node_engine "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/detection/engine.py"
click node_models "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/models/models.py"
click node_severity "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/severity/scoring.py"
click node_whitelist "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/whitelist/filter.py"
click node_reputation "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/threat_intel/abuseipdb.py"
click node_mitre "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/mitre/mapping.py"
click node_timeline "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/correlation/timeline.py"
click node_app "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/cli/app.py"
click node_terminal "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/cli/app.py"
click node_csv "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/reporting/csv_report.py"
click node_pdf "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/reporting/pdf_report.py"
click node_logging "https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/utils/logging.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_settings,node_capture,node_app toneBlue
class node_parser,node_tls,node_sslbl,node_rolling,node_signatures,node_detector_common,node_engine,node_models toneAmber
class node_severity,node_whitelist,node_reputation,node_mitre,node_timeline,node_logging toneMint
class node_terminal,node_csv,node_pdf toneRose
class node_operator,node_abuse_service,node_sslbl_service toneIndigo
```

## Components

### CLI and capture

- [CLI commands](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/cli/main.py): `packet_watch/cli/main.py`
- [Configuration](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/config/settings.py): `packet_watch/config/settings.py`
- [Live capture](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/capture/live.py): `packet_watch/capture/live.py`
- [Monitor orchestration](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/cli/app.py): `packet_watch/cli/app.py`

### Packet analysis

- [Packet parser](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/parser/packet_parser.py): `packet_watch/parser/packet_parser.py`
- [JA3 enrichment](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/threat_intel/pipeline.py): `packet_watch/threat_intel/pipeline.py`
- [SSLBL feed client](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/threat_intel/ja3.py): `packet_watch/threat_intel/ja3.py`
- [Rolling state](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/state/rolling.py): `packet_watch/state/rolling.py`
- [Signature detectors](https://github.com/parathputhuvai/packet-watch/tree/main/packet_watch/detectors): `packet_watch/detectors`
- [Rule helpers](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/detectors/common.py): `packet_watch/detectors/common.py`
- [Detection engine](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/detection/engine.py): `packet_watch/detection/engine.py`
- [Packet and alert models](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/models/models.py): `packet_watch/models/models.py`

### Alert enrichment

- [Severity scoring](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/severity/scoring.py): `packet_watch/severity/scoring.py`
- [Whitelist filtering](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/whitelist/filter.py): `packet_watch/whitelist/filter.py`
- [IP reputation](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/threat_intel/abuseipdb.py): `packet_watch/threat_intel/abuseipdb.py`
- [MITRE mapping](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/mitre/mapping.py): `packet_watch/mitre/mapping.py`
- [Alert timeline](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/correlation/timeline.py): `packet_watch/correlation/timeline.py`
- [Logging](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/utils/logging.py): `packet_watch/utils/logging.py`

### Presentation and reports

- [Rich terminal output](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/cli/app.py): `packet_watch/cli/app.py`
- [CSV reports](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/reporting/csv_report.py): `packet_watch/reporting/csv_report.py`
- [PDF reports](https://github.com/parathputhuvai/packet-watch/blob/main/packet_watch/reporting/pdf_report.py): `packet_watch/reporting/pdf_report.py`

### Other components

- **Operator**
- **AbuseIPDB**
- **SSLBL threat feed**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Configuration: loads settings (evidence: `packet_watch/cli/main.py`)
- CLI commands → Monitor orchestration: dispatches commands (evidence: `packet_watch/cli/main.py`)
- Monitor orchestration → Live capture: starts capture (evidence: `packet_watch/cli/app.py`)
- Live capture → Monitor orchestration: delivers packets (evidence: `packet_watch/cli/app.py`)
- Monitor orchestration → Packet parser: parses packets (evidence: `packet_watch/cli/app.py`)
- Monitor orchestration → JA3 enrichment: enriches TLS (evidence: `packet_watch/cli/app.py`)
- JA3 enrichment → SSLBL feed client: calculates and looks up (evidence: `packet_watch/threat_intel/pipeline.py`)
- SSLBL feed client → SSLBL threat feed: fetches feed (evidence: `packet_watch/threat_intel/ja3.py`)
- Monitor orchestration → Detection engine: processes parsed packets (evidence: `packet_watch/cli/app.py`)
- Detection engine → Rolling state: observes packet (evidence: `packet_watch/detection/engine.py`)
- Detection engine → Signature detectors: dispatches detection (evidence: `packet_watch/detection/engine.py`)
- Signature detectors → Rule helpers: uses rule helpers (evidence: `packet_watch/detectors/dns_tunneling.py`)
- Rolling state → Rule helpers: uses request heuristics (evidence: `packet_watch/state/rolling.py`)
- Detection engine → Severity scoring: scores results (evidence: `packet_watch/detection/engine.py`)
- Detection engine → Whitelist filtering: checks suppression (evidence: `packet_watch/detection/engine.py`)
- Detection engine → Packet and alert models: creates alerts (evidence: `packet_watch/detection/engine.py`)
- Monitor orchestration → IP reputation: enriches alert IPs
- Monitor orchestration → Alert timeline: records alerts (evidence: `packet_watch/cli/app.py`)
- Monitor orchestration → Rich terminal output: prints alerts (evidence: `packet_watch/cli/app.py`)
- Monitor orchestration → CSV reports: writes CSV (evidence: `packet_watch/cli/app.py`)
- Monitor orchestration → PDF reports: writes PDF (evidence: `packet_watch/cli/app.py`)
- IP reputation → AbuseIPDB: queries reputation
- Monitor orchestration → Logging: sets up logging (evidence: `packet_watch/cli/app.py`)
