# ctrlsam/careless-whisper-python architecture

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

- Interactive diagram: https://gitdiagram.com/ctrlsam/careless-whisper-python
- Repository: https://github.com/ctrlsam/careless-whisper-python

## Overview

Careless Whisper is a Python proof of concept for analyzing delivery-receipt timing and running silent-message floods. The primary workflow configures a fingerprint scan, sends probes through a messenger, correlates receipt and send-order evidence, infers device and activity states, then reports or exports results. A separate DoS tool sends high-payload messages. The graph includes the documented exporters and Prometheus/Grafana monitoring capability; implementation excerpts establish only selected runtime links, so unsampled integrations are not treated as verified calls.

Main entry points: [`carelesswhisper/tools/fingerprint/main.py`](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/fingerprint/main.py) (Fingerprint runner), [`carelesswhisper/tools/dos/main.py`](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/dos/main.py) (Flood runner), [`carelesswhisper/exporters/base.py`](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/exporters/base.py) (Exporter contract), [`carelesswhisper/messengers/base.py`](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/messengers/base.py) (Messenger interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User tools"]
  node_cli["Interactive CLI<br/>[main.py]"]
  node_cli_ui["Terminal display<br/>[ui.py]"]
  node_fingerprint_tool["Fingerprint runner<br/>[main.py]"]
  node_fingerprint_settings["Scan settings<br/>[config.py]"]
  node_dos_tool["Flood runner<br/>[main.py]"]
  node_dos_settings["Flood settings<br/>[config.py]"]
end

subgraph group_runtime["Probe runtime"]
  node_messenger_api["Messenger interface<br/>[base.py]"]
  node_whatsapp["WhatsApp adapter<br/>[whatsapp.py]"]
  node_exploit["Receipt correlation<br/>[exploit.py]"]
end

subgraph group_analysis["Analysis and telemetry"]
  node_fingerprint["Behavior analysis<br/>[fingerprint.py]"]
end

subgraph group_outputs["Export and monitoring"]
  node_csv["CSV exporter<br/>[csv.py]"]
  node_jsonl["JSONL exporter<br/>[jsonl.py]"]
  node_sqlite[("SQLite exporter<br/>[sqlite.py]")]
  node_export_api["Exporter contract<br/>[base.py]"]
  node_metrics["Prometheus metrics<br/>[metrics.py]"]
end

node_user(("Operator"))
node_target(("Target device"))
node_prometheus["Prometheus scrape"]
node_grafana["Grafana dashboards"]

node_user -->|"runs"| node_cli
node_cli -->|"updates"| node_cli_ui
node_cli -->|"starts"| node_fingerprint_tool
node_user -->|"runs"| node_fingerprint_tool
node_fingerprint_tool -->|"uses settings"| node_fingerprint_settings
node_fingerprint_tool -->|"configures callbacks"| node_messenger_api
node_fingerprint_tool -->|"registers listeners"| node_exploit
node_fingerprint_tool -->|"registers reports"| node_fingerprint
node_fingerprint_tool -->|"saves results"| node_export_api
node_fingerprint_tool -->|"publishes analysis"| node_metrics
node_messenger_api -->|"implemented by"| node_whatsapp
node_whatsapp -.->|"sends probes"| node_target
node_target -.->|"returns receipts"| node_whatsapp
node_exploit -->|"sends silent messages"| node_messenger_api
node_exploit -->|"provides receipt evidence"| node_fingerprint
node_user -->|"runs"| node_dos_tool
node_dos_tool -->|"uses settings"| node_dos_settings
node_dos_tool -->|"sends flood messages"| node_messenger_api
node_dos_tool -.->|"floods"| node_target
node_fingerprint_tool -.->|"selects exporter"| node_csv
node_fingerprint_tool -.->|"selects exporter"| node_jsonl
node_fingerprint_tool -.->|"selects exporter"| node_sqlite
node_export_api -->|"implemented by"| node_csv
node_export_api -->|"implemented by"| node_jsonl
node_export_api -->|"implemented by"| node_sqlite
node_fingerprint_tool -.->|"enables metrics"| node_metrics
node_metrics -->|"exposes metrics"| node_prometheus
node_prometheus -->|"feeds dashboards"| node_grafana

click node_cli "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/cli/main.py"
click node_cli_ui "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/cli/ui.py"
click node_fingerprint_tool "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/fingerprint/main.py"
click node_fingerprint_settings "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/fingerprint/config.py"
click node_dos_tool "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/dos/main.py"
click node_dos_settings "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/dos/config.py"
click node_messenger_api "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/messengers/base.py"
click node_whatsapp "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/messengers/whatsapp.py"
click node_exploit "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/exploit.py"
click node_fingerprint "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/fingerprint.py"
click node_csv "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/exporters/csv.py"
click node_jsonl "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/exporters/jsonl.py"
click node_sqlite "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/exporters/sqlite.py"
click node_export_api "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/exporters/base.py"
click node_metrics "https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/metrics.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_cli_ui,node_fingerprint_tool,node_fingerprint_settings,node_dos_tool,node_dos_settings toneBlue
class node_messenger_api,node_whatsapp,node_exploit toneAmber
class node_fingerprint toneMint
class node_csv,node_jsonl,node_sqlite,node_export_api,node_metrics toneRose
class node_user,node_target,node_prometheus,node_grafana toneIndigo
```

## Components

### User tools

- [Interactive CLI](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/cli/main.py): `carelesswhisper/tools/cli/main.py`
- [Terminal display](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/cli/ui.py): `carelesswhisper/tools/cli/ui.py`
- [Fingerprint runner](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/fingerprint/main.py): `carelesswhisper/tools/fingerprint/main.py`
- [Scan settings](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/fingerprint/config.py): `carelesswhisper/tools/fingerprint/config.py`
- [Flood runner](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/dos/main.py): `carelesswhisper/tools/dos/main.py`
- [Flood settings](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/tools/dos/config.py): `carelesswhisper/tools/dos/config.py`

### Probe runtime

- [Messenger interface](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/messengers/base.py): `carelesswhisper/messengers/base.py`
- [WhatsApp adapter](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/messengers/whatsapp.py): `carelesswhisper/messengers/whatsapp.py`
- [Receipt correlation](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/exploit.py): `carelesswhisper/exploit.py`

### Analysis and telemetry

- [Behavior analysis](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/fingerprint.py): `carelesswhisper/fingerprint.py`

### Export and monitoring

- [CSV exporter](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/exporters/csv.py): `carelesswhisper/exporters/csv.py`
- [JSONL exporter](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/exporters/jsonl.py): `carelesswhisper/exporters/jsonl.py`
- [SQLite exporter](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/exporters/sqlite.py): `carelesswhisper/exporters/sqlite.py`
- [Exporter contract](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/exporters/base.py): `carelesswhisper/exporters/base.py`
- [Prometheus metrics](https://github.com/ctrlsam/careless-whisper-python/blob/main/carelesswhisper/metrics.py): `carelesswhisper/metrics.py`

### Other components

- **Operator**
- **Target device**
- **Prometheus scrape**
- **Grafana dashboards**

## Connections

- Operator → Interactive CLI: runs (evidence: `README.md`)
- Interactive CLI → Terminal display: updates (evidence: `carelesswhisper/tools/cli/main.py`)
- Interactive CLI → Fingerprint runner: starts (evidence: `carelesswhisper/tools/cli/main.py`)
- Operator → Fingerprint runner: runs (evidence: `README.md`)
- Fingerprint runner → Scan settings: uses settings (evidence: `carelesswhisper/tools/fingerprint/main.py`)
- Fingerprint runner → Messenger interface: configures callbacks (evidence: `carelesswhisper/tools/fingerprint/main.py`)
- Fingerprint runner → Receipt correlation: registers listeners (evidence: `carelesswhisper/tools/fingerprint/main.py`)
- Fingerprint runner → Behavior analysis: registers reports (evidence: `carelesswhisper/tools/fingerprint/main.py`)
- Fingerprint runner → Exporter contract: saves results (evidence: `carelesswhisper/tools/fingerprint/main.py`)
- Fingerprint runner → Prometheus metrics: publishes analysis (evidence: `carelesswhisper/tools/fingerprint/main.py`)
- Messenger interface → WhatsApp adapter: implemented by (evidence: `carelesswhisper/messengers/whatsapp.py`)
- WhatsApp adapter → Target device: sends probes (evidence: `README.md`)
- Target device → WhatsApp adapter: returns receipts (evidence: `README.md`)
- Receipt correlation → Messenger interface: sends silent messages (evidence: `carelesswhisper/exploit.py`)
- Receipt correlation → Behavior analysis: provides receipt evidence (evidence: `carelesswhisper/fingerprint.py`)
- Operator → Flood runner: runs (evidence: `README.md`)
- Flood runner → Flood settings: uses settings (evidence: `carelesswhisper/tools/dos/main.py`)
- Flood runner → Messenger interface: sends flood messages (evidence: `carelesswhisper/tools/dos/main.py`)
- Flood runner → Target device: floods (evidence: `README.md`)
- Fingerprint runner → CSV exporter: selects exporter (evidence: `README.md`)
- Fingerprint runner → JSONL exporter: selects exporter (evidence: `README.md`)
- Fingerprint runner → SQLite exporter: selects exporter (evidence: `README.md`)
- Exporter contract → CSV exporter: implemented by (evidence: `carelesswhisper/exporters/csv.py`)
- Exporter contract → JSONL exporter: implemented by (evidence: `carelesswhisper/exporters/jsonl.py`)
- Exporter contract → SQLite exporter: implemented by (evidence: `carelesswhisper/exporters/sqlite.py`)
- Fingerprint runner → Prometheus metrics: enables metrics (evidence: `README.md`)
- Prometheus metrics → Prometheus scrape: exposes metrics (evidence: `carelesswhisper/metrics.py`)
- Prometheus scrape → Grafana dashboards: feeds dashboards (evidence: `README.md`)
