# maluta/privacy-scanner architecture

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

- Interactive diagram: https://gitdiagram.com/maluta/privacy-scanner
- Repository: https://github.com/maluta/privacy-scanner

## Overview

Privacy Scanner is a cross-platform defensive tool for finding WiFi-connected surveillance devices. A user starts a scan against a detected or specified network; the scanner discovers hosts, gathers manufacturer and network-service evidence, classifies risk, and presents results in the terminal and an HTML report. The phases are documented as a seven-stage pipeline, while the implementation is largely concentrated in scripts/scan.py. The graph preserves the documented Linux-only Bash alternative and report capabilities; phase-to-phase links are based on the README rather than inspected call sites.

Main entry points: [`scripts/scan.py`](https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py) (Python Scanner), [`scripts/report_html.py`](https://github.com/maluta/privacy-scanner/blob/main/scripts/report_html.py) (HTML Generator), [`scripts/scan.sh`](https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.sh) (Linux Bash Scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Scan Workflow"]
  node_python_scan["Python Scanner<br/>[scan.py]"]
  node_scan_context["Scan Context<br/>[scan.py]"]
  node_host_discovery["Host Discovery<br/>[scan.py]"]
  node_port_scan["Port Scan<br/>[scan.py]"]
  node_service_discovery["Service Discovery<br/>[scan.py]"]
end

subgraph group_analysis["Evidence Analysis"]
  node_oui_analysis["OUI Analysis<br/>[scan.py]"]
  node_deep_inspection["Deep Inspection<br/>[scan.py]"]
  node_risk_classification["Risk Classification<br/>[scan.py]"]
end

subgraph group_outputs["Results"]
  node_terminal_report["Terminal Results<br/>[scan.py]"]
  node_html_generator["HTML Generator<br/>[report_html.py]"]
  node_html_report["Offline HTML Report"]
  node_raw_data["Raw Scan Data"]
end

subgraph group_alternatives["Platform Alternatives"]
  node_bash_scanner["Linux Bash Scanner<br/>[scan.sh]"]
end

node_user(("Scanner User"))
node_network(("WiFi Network"))
node_nmap["nmap"]

node_user -->|"starts scan"| node_python_scan
node_python_scan -.->|"configures state"| node_scan_context
node_python_scan -->|"runs phase"| node_host_discovery
node_host_discovery -->|"discovers hosts"| node_network
node_host_discovery -->|"uses ping scan"| node_nmap
node_host_discovery -->|"feeds host evidence"| node_oui_analysis
node_oui_analysis -->|"feeds device targets"| node_port_scan
node_port_scan -->|"precedes phase"| node_service_discovery
node_service_discovery -->|"precedes phase"| node_deep_inspection
node_deep_inspection -->|"feeds evidence"| node_risk_classification
node_python_scan -->|"prints results"| node_terminal_report
node_python_scan -->|"generates report"| node_html_generator
node_html_generator -->|"writes report"| node_html_report
node_python_scan -->|"saves scan data"| node_raw_data
node_user -->|"starts Linux scan"| node_bash_scanner

click node_python_scan "https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py"
click node_scan_context "https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py"
click node_host_discovery "https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py"
click node_oui_analysis "https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py"
click node_port_scan "https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py"
click node_service_discovery "https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py"
click node_deep_inspection "https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py"
click node_risk_classification "https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py"
click node_terminal_report "https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py"
click node_html_generator "https://github.com/maluta/privacy-scanner/blob/main/scripts/report_html.py"
click node_bash_scanner "https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.sh"

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_python_scan,node_scan_context,node_host_discovery,node_port_scan,node_service_discovery,node_user toneBlue
class node_oui_analysis,node_deep_inspection,node_risk_classification toneAmber
class node_terminal_report,node_html_generator,node_html_report,node_raw_data toneMint
class node_bash_scanner toneRose
class node_network,node_nmap toneIndigo
```

## Components

### Scan Workflow

- [Python Scanner](https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py): `scripts/scan.py`
- [Scan Context](https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py): `scripts/scan.py`
- [Host Discovery](https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py): `scripts/scan.py`
- [Port Scan](https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py): `scripts/scan.py`
- [Service Discovery](https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py): `scripts/scan.py`

### Evidence Analysis

- [OUI Analysis](https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py): `scripts/scan.py`
- [Deep Inspection](https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py): `scripts/scan.py`
- [Risk Classification](https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py): `scripts/scan.py`

### Results

- [Terminal Results](https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.py): `scripts/scan.py`
- [HTML Generator](https://github.com/maluta/privacy-scanner/blob/main/scripts/report_html.py): `scripts/report_html.py`
- **Offline HTML Report**
- **Raw Scan Data**

### Platform Alternatives

- [Linux Bash Scanner](https://github.com/maluta/privacy-scanner/blob/main/scripts/scan.sh): `scripts/scan.sh`

### Other components

- **Scanner User**
- **WiFi Network**
- **nmap**

## Connections

- Scanner User → Python Scanner: starts scan (evidence: `README.md`)
- Python Scanner → Scan Context: configures state (evidence: `scripts/scan.py`)
- Python Scanner → Host Discovery: runs phase (evidence: `README.md`)
- Host Discovery → WiFi Network: discovers hosts (evidence: `README.md`)
- Host Discovery → nmap: uses ping scan (evidence: `README.md`)
- Host Discovery → OUI Analysis: feeds host evidence (evidence: `README.md`)
- OUI Analysis → Port Scan: feeds device targets (evidence: `README.md`)
- Port Scan → Service Discovery: precedes phase (evidence: `README.md`)
- Service Discovery → Deep Inspection: precedes phase (evidence: `README.md`)
- Deep Inspection → Risk Classification: feeds evidence (evidence: `README.md`)
- Python Scanner → Terminal Results: prints results (evidence: `README.md`)
- Python Scanner → HTML Generator: generates report (evidence: `README.md`)
- HTML Generator → Offline HTML Report: writes report (evidence: `README.md`)
- Python Scanner → Raw Scan Data: saves scan data (evidence: `README.md`)
- Scanner User → Linux Bash Scanner: starts Linux scan (evidence: `README.md`)