message-metadata-mirror

See what your messaging apps are really telling Meta, Google, and Telegram—in real-time.

What is this?

message-metadata-mirror is a self-hosted privacy auditing tool that captures and visualizes metadata leakage from WhatsApp, Telegram, and Signal. Install a CA certificate on your local network, and immediately see timestamps, contact graphs, IP addresses, and device fingerprints that messaging apps reveal—even when end-to-end encryption is enabled. Generate weekly privacy reports showing the gap between what companies claim is encrypted and what you're actually exposing.

Think Little Snitch meets Wireshark, built for privacy-conscious users who want proof, not promises.

Features

• Real-time metadata capture – HTTPS proxy intercepts and logs messaging app traffic without decrypting message content
• Privacy-focused analytics – See contact graphs, request timing, IP patterns, device fingerprints, and server endpoints
• Weekly privacy reports – Automated PDF exports showing what Meta/Google collected vs. their encryption claims
• One-click setup – CA certificate installer + network proxy configuration for macOS, Linux, and Raspberry Pi
• Docker-native – Deploy on any hardware (laptop, Pi, home server) with a single docker-compose up
• Privacy by design – All data stays local; no cloud syncing or telemetry
• Multi-app support – Built for WhatsApp, Telegram, and Signal (extensible analyzer framework)

Quick Start

Requirements

• Docker and Docker Compose (or Python 3.10+)
• 50MB disk space
• Network access to route devices through proxy

Installation

1. Clone and configure

   git clone https://github.com/yourusername/message-metadata-mirror.git
   cd message-metadata-mirror
   cp .env.example .env
   

2. Launch with Docker

   docker-compose up -d
   

   The web dashboard is now running at http://localhost:8080

3. Install CA certificate

   • Visit the setup page: http://localhost:8080/setup
   • Download the CA certificate and follow platform-specific installation steps
   • Configure your device to route traffic through the proxy

4. Start capturing

   • Open WhatsApp, Telegram, or Signal on your device
   • Metadata is captured automatically
   • View live captures at http://localhost:8080/captures
   • Download weekly reports from the dashboard

Headless Setup (Raspberry Pi)

docker-compose -f docker-compose.yml up -d
# Configure devices to use <pi-ip>:8080 as proxy
# Access dashboard remotely at http://<pi-ip>:8080

Usage Examples

View real-time metadata captures

Dashboard → Captures tab shows every metadata leak with timestamps, endpoints, and contact info

Generate privacy report

Dashboard → Reports tab → "Generate Weekly Report"
Creates PDF showing:
  - Message sending patterns (timestamps)
  - Contact graph (who you're talking to)
  - IP geolocation of Meta/Telegram servers
  - Device fingerprint data leaked
  - Comparison vs. published privacy policies

Export raw capture data

API: GET /api/captures?format=json
Returns structured metadata for analysis in Excel, Python, etc.

Monitor specific contact

Captures → Search by phone number or contact name
See all metadata patterns for that conversation thread

Tech Stack

Configuration

Copy .env.example to .env and adjust:

PROXY_PORT=8080              # Local proxy listen port
DATABASE_URL=sqlite:///data/captures.db
REPORT_FREQUENCY=weekly      # daily, weekly, monthly
RETENTION_DAYS=90            # Auto-purge old captures
STRIPE_API_KEY=sk_live_...   # Optional: premium features

Privacy & Security

• All data stays local – No cloud sync, no remote servers, no telemetry
• Message content is never logged – Only metadata (headers, timestamps, endpoints)
• Requires admin access – CA certificate installation prevents accidental interception
• Open source – Audit the code at any time

Limitations

• Requires network-level proxy configuration (devices must route through your network)
• Metadata analysis only—encrypted message content remains inaccessible
• Signal limits metadata exposure (smallest footprint of tested apps)
• Requires periodic CA certificate updates on devices

License

MIT – Use freely for personal privacy auditing and research. Commercial deployment requires Stripe integration for hosted services (see MONETIZATION.md).

Contributing

Issues and pull requests welcome. Priority areas:

• Additional app analyzers (iMessage, Viber, WeChat)
• Mobile app setup wizard (iOS profile installer)
• Tor routing option for metadata obfuscation

Questions? Open an issue. Want to audit your own apps? Start with the Quick Start above.