{"id":"75dbe4a9-77cf-4d33-9c8f-de894dadb766","slug":"digital-footprint","kind":"mcp","name":"digital-footprint","summary":"Self-hosted PII exposure detection and personal data removal system. Scans public sources for data leaks and automates removal requests.","owner":"marc-shade","repoUrl":"https://github.com/marc-shade/digital-footprint","license":"MIT","licenseTier":"permissive","trust":"community","stars":4,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-02-23T22:13:26.000Z","addedAt":"2026-10-21T16:54:00.515Z","logoUrl":"https://avatars.githubusercontent.com/u/167566032?u=6afed681e3d35eaf85bf597a858116cb8ca01071&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["data-analytics"],"tags":["ai","machine-learning","python"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T01:14:15.806Z","sample":false,"url":"https://conduits.dev/tools/digital-footprint","language":"Python","transports":["stdio"],"install":{"pypi":"digital-footprint"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Digital Footprint Manager\n\n<p align=\"center\">\n  <img src=\"assets/bigfoot-hacker.png\" alt=\"Bigfoot cleaning up your digital footprint on a 1980s computer\" width=\"600\">\n</p>\n\nSelf-hosted personal data removal and privacy protection system. Replicates the capabilities of online footprint removal services through an MCP server, Claude Code skills, and automated pipelines.\n\n## What It Does\n\n- **Discovers** your exposure across 50 data brokers, breach databases, dark web paste sites, and 3,000+ username registries\n- **Removes** your data via automated CCPA/GDPR opt-out emails, web form submissions, and guided manual processes\n- **Monitors** for re-listing, new breaches, and dark web appearances on a recurring schedule\n- **Escalates** brokers that ignore 2+ requests by drafting an FTC / state-AG complaint (you file it)\n- **Alerts** you via email when new threats are detected\n- **Reports** your risk score and full exposure in Markdown reports\n\n> **Operational notes.** (1) Live opt-out submissions only fire when you opt\n> in (`submit_removals=True`); the default pipeline is a dry run that records\n> intended removals without contacting any broker. (2) Automated *discovery*\n> and post-removal *verification* require a `search_url_pattern` per broker.\n> 4 are live-verified today (radaris, thatsthem, zabasearch, addresses);\n> the rest are unpopulated and skipped (logged, never reported as clean).\n> (3) Many major people-search sites (Spokeo, FastPeopleSearch,\n> TruePeopleSearch, USPhoneBook, ...) serve **anti-bot challenge pages** to\n> the headless scanner, so they cannot be auto-discovered from a plain IP.\n> The scanner now detects this and reports `blocked` (not a false all-clear);\n> reaching those sites needs residential proxies + CAPTCHA solving, or a real\n> logged-in browser (the Cowork approach). Blind opt-out submission does not\n> need discovery at all.\n\n## Architecture\n\n```\ndigital_footprint/\n  config.py              # Environment-based configuration\n  db.py                  # SQLite database (WAL mode)\n  models.py              # Person, Broker, Finding, Removal, Breach, Scan\n  broker_registry.py     # YAML broker loader\n  brokers/               # 50 data broker definitions (YAML)\n  scanners/              # Breach, username, dark web, Google dork, Playwright\n  removers/              # Email, web form, manual removal + verification + escalation\n    templates/           # 6 Jinja2 legal templates (CCPA, GDPR, followup, complaint)\n  monitors/              # Dark web monitoring orchestrator\n  reporters/             # Exposure report generator with risk scoring\n  scheduler/             # Cron-based job runner (breach, dark web, verify, report)\n  pipeline/              # End-to-end protection orchestrator + email alerter\n  tools/                 # MCP tool implementations\nserver.py                # FastMCP server entry point\nscheduler.py             # Cron CLI entry point\n```\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.11+\n- [Claude Code](https://claude.ai/code) (for MCP integration and skills)\n\n### Install\n\n```bash\ngit clone https://github.com/marc-shade/digital-footprint.git\ncd digital-footprint\npython -m venv venv && source venv/bin/activate\npip install -e \".[dev]\"      # runtime + test deps; drop [dev] for runtime only\nplaywright install chromium  # browser for broker scanning / form submission\n```\n\nThis installs the `dfp` command:\n\n```bash\ndfp --help\ndfp scan dorks \"Your Name\" --email you@example.com\ndfp broker list\ndfp report 1 --format pdf --output exposure.pdf   # markdown|json|html|pdf\n```\n\n### Configure\n\nCreate a `.env` file:\n\n```bash\n# Required for breach checking\nHIBP_API_KEY=your_hibp_key              # haveibeenpwned.com ($3.50/mo)\n\n# Optional: enhanced breach data\nDEHASHED_API_KEY=your_dehashed_key      # dehashed.com ($5/mo)\nDEHASHED_EMAIL=your_email\n\n# Optional: automated email removals\nSMTP_HOST=smtp.gmail.com\nSMTP_PORT=587\nSMTP_USER=your_email\nSMTP_PASSWORD=your_app_password\n\n# Optional: alert notifications\nALERT_EMAIL=alerts@yourdomain.com\n\n# Optional: CAPTCHA solving for web form removals\nCAPTCHA_API_KEY=your_2captcha_key\n\n# Optional: encrypt PII at rest (off by default)\nDIGITAL_FOOTPRINT_ENCRYPT=1\n```\n\n### Encryption at rest\n\nPersonal data (names, emails, phones, addresses, dates of birth, finding\nURLs) can be encrypted at rest. It is **off by default** — the database is\nplaintext and logs a warning on open. Turn it on with either:\n\n- `DIGITAL_FOOTPRINT_ENCRYPT=1` — generates and loads a key file next to the\n  DB (`db.key`, `chmod 600`). Keep that file safe; losing it makes the data\n  unrecoverable.\n- `DIGITAL_FOOTPRINT_DB_KEY=<fernet key>` — bring your own key\n  (`python -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\"`).\n\nWhen enabled, PII columns are Fernet-encrypted (AES-128-CBC + HMAC) and the DB\nfile shows no personal data to `strings`. This is field-level encryption:\nschema, column names, timestamps and status values remain visible; breach rows\nare pseudonymous (linked only by an integer id). To encrypt an existing\nplaintext database, enable a key and call `Database.migrate_to_encrypted()`.\n\n### Run the MCP Server\n\n```bash\npython -m digital_footprint\n```\n\nOr add to your Claude Code MCP config (`~/.claude.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"digital-footprint\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"digital_footprint\"],\n      \"cwd\": \"/path/to/digital-footprint\"\n    }\n  }\n}\n```\n\n### Schedule Recurring Scans\n\nAdd to your crontab (`crontab -e`):\n\n```cron\n0 3 * * * cd /path/to/digital-footprint && /path/to/venv/bin/python scheduler.py >> scheduler.log 2>&1\n```\n\nThis runs breach rechecks (weekly), dark web monitoring (every 3 days), removal verification (daily), confirmation-inbox processing (daily), re-listing re-checks (weekly), and report generation (weekly). When a broker still lists you after a removal, the verify job resubmits the opt-out (once), then drafts an FTC / state-AG complaint if it is still ignored — set `DIGITAL_FOOTPRINT_AUTO_RESUBMIT=1` to have it re-send automatically, otherwise it records that a resubmit is due. When a broker you'd already cleared re-lists you, the re-listing re-check reopens a fresh removal automatically.\n\n### Email confirmation loop\n\nMany brokers email a \"click to confirm your removal\" link; without it the\nopt-out never completes. Set `IMAP_HOST` / `IMAP_USER` / `IMAP_PASSWORD` (a\ndedicated inbox) and the `process_confirmations` scheduler job polls it,\nmatches each message to a pending removal, and extracts the confirmation link.\nWith `DIGITAL_FOOTPRINT_AUTO_CONFIRM=1` it visits the link automatically;\notherwise it records the link on the removal for you to click. For safety, a\nlink is only ever visited if it is on the broker's own domain — a phishing\nmessage in the inbox is never clicked.\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `footprint_protect` | Run the full protection pipeline: scan, remove, monitor, report |\n| `footprint_scan` | Full exposure scan for a person |\n| `footprint_breach_check` | Check email against HIBP and DeHashed breach databases |\n| `footprint_username_search` | Search username across 3,000+ sites via Maigret |\n| `footprint_google_dork` | Generate Google dork queries for finding exposed data |\n| `footprint_broker_check` | Check a specific data broker for a person's data |\n| `footprint_exposure_report` | Generate a comprehensive exposure report |\n| `footprint_broker_remove` | Submit a removal request to a data broker |\n| `footprint_removal_status` | View status of pending removal requests |\n| `footprint_verify_removals` | Re-scan brokers to verify removals completed |\n| `footprint_dark_web_monitor` | Monitor dark web paste sites, Ahmia.fi, and holehe |\n| `footprint_social_audit` | Audit social media privacy settings |\n| `footprint_schedule_status` | View scheduler status and job history |\n\n## Claude Code Skills\n\n| Skill | Description |\n|-------|-------------|\n| `/protect` | Full protection pipeline workflow |\n| `/exposure` | Run exposure scan and generate report |\n| `/breach` | Check for credential exposure in breaches |\n| `/removal` | Submit and track data broker removals |\n| `/monitor` | Dark web and social media monitoring |\n| `/schedule` | View and manage scheduled jobs |\n| `/footprint` | Overview of all capabilities |\n\n## Data Broker Registry\n\n50 broker definitions in YAML covering:\n\n- **People search engines** (BeenVerified, Spokeo, WhitePages, Intelius, etc.)\n- **Background check services** (TruthFinder, InstantCheckmate, etc.)\n- **Marketing data brokers** (Acxiom, Oracle Data Cloud, Epsilon, etc.)\n- **Social/genealogy** (Ancestry, Classmates, MyLife, etc.)\n\nEach broker definition includes opt-out method, URL, difficulty rating, CCPA/GDPR compliance, and recheck interval.\n\n## Legal Templates\n\nSix Jinja2 templates for automated opt-out emails and escalation:\n\n- `ccpa_deletion.j2` — California Consumer Privacy Act deletion request\n- `ccpa_do_not_sell.j2` — CCPA Do Not Sell My Personal Information\n- `gdpr_erasure.j2` — GDPR Right to Erasure (Article 17)\n- `generic_removal.j2` — General data removal request\n- `followup.j2` — Follow-up (second request) for unresponsive brokers\n- `regulatory_complaint.j2` — FTC / state-AG complaint draft, generated after a broker ignores 2+ requests\n\n## Risk Scoring\n\nExposure reports include a 0-100 risk score based on weighted findings:\n\n| Severity | Weight | Examples |\n|----------|--------|----------|\n| Critical | 25 | Passwords in breaches, SSN exposure |\n| High | 10 | Email in dark web pastes, financial data |\n| Medium | 5 | Name/address on people-search sites |\n| Low | 2 | Username found on social platforms |\n\nScores map to labels: **CRITICAL** (75+), **HIGH** (50-74), **MODERATE** (25-49), **LOW** (0-24).\n\nReports render in **markdown, JSON, HTML, or PDF** (`dfp report <id> --format …`,\nor the `footprint_exposure_report` MCP tool with a `format` argument). PDF uses\nfpdf2 (pure-Python, no native dependencies).\n\n## Tests\n\n```bash\npython -m pytest tests/ -v\n```\n\n349 tests covering all modules. Zero external API calls in tests — all external services are mocked. This includes an end-to-end MCP suite that drives the server's tools through the real FastMCP client.\n\n## External Services\n\n| Service | Purpose | Cost |\n|---------|---------|------|\n| [Have I Been Pwned](https://haveibeenpwned.com/API/v3) | Breach and paste monitoring | $3.50/mo |\n| [DeHashed](https://dehashed.com) | Enhanced breach data | $5/mo |\n| [Maigret](https://github.com/soxoj/maigret) | Username search (3,000+ sites) | Free (local) |\n| [Ahmia.fi](https://ahmia.fi) | Tor hidden service search | Free |\n| [holehe](https://github.com/megadose/holehe) | Email registration check | Free (local) |\n\n## License\n\nReleased under the [MIT License](LICENSE). Copyright (c) 2026 Marc Shade.\n\n## Disclaimer\n\nThis is a self-hosted tool for exercising your own data-privacy rights (CCPA,\nGDPR, and similar). Use it only against your own personal information, or on\nbehalf of someone who has authorized you. Automated access to third-party\nsites may be subject to their terms of service; you are responsible for how\nyou operate it. Provided \"as is,\" without warranty (see LICENSE).\n"}