\n \n
\n ![](\"https://img.shields.io/badge/Version-1.5.2.1-blueviolet?style=for-the-badge&logo=github\"){kind=icon}
![](\"https://img.shields.io/badge/Tested%20on-Termux-black?style=for-the-badge&logo=termux\"){kind=icon}
![](\"https://img.shields.io/badge/Tested%20on-Windows-cyan?style=for-the-badge&logo=Windows\"){kind=icon}
![](\"https://img.shields.io/badge/Tested%20on-Linux-black?style=for-the-badge&logo=Linux\"){kind=icon}
![](\"https://img.shields.io/pepy/dt/user-scanner?style=for-the-badge\")
![\"Discord\"](\"https://img.shields.io/badge/Discord-Join%20Chat-7289da?style=for-the-badge&logo=discord&logoColor=white\"){kind=icon}
![\"X](\"https://img.shields.io/badge/Follow-kaifcodec-000000?style=for-the-badge&logo=x&logoColor=white\"){kind=icon}
\n \n \n \n
\n \n \n \n
\n Go beyond account enumeration. WebVetted turns an email or username into a complete identity investigation with deep OSINT enrichment, breach intel, AI analysis, and an interactive identity graph.\n
\n Start an Investigation β\n
\n \n \n \n
\n Comprehensive OSINT platform for professional investigators and analysts. Reverse email, phone number, and username search across 250+ modules. Automate your intelligence gathering with our powerful tools.\n
\n Get Started β\n
\n \n \n \n
\n Find beginner-friendly open-source issues and make your first pull request today.\n
\n Get Started β\n
\n π Looking for Phone Number OSINT? Check out our other project phonsint to uncover accounts, masked emails, and profile photos with zero SMS alerts. \n Explore phonsint β\n
\n\n## β¨ Key Features\n\n- π **Deep Email & Username OSINT:** Look up email registrations and perform advanced username profiling across 2710+ platforms.\n- π€ **Rich Metadata Scraping:** Scrapes avatars, bio descriptions, follower counts, UID numbers, seller statuses, and account attributes.\n- π **Cross-Scan & Pivot Engine:** Mines handles, profile links, and exposed email addresses from initial scans, automatically pivoting across secondary target vectors.\n- π€ **Model Context Protocol (MCP) Server:** Native AI agent integration for Claude Desktop, Cursor, Antigravity, and LLMs to run autonomous OSINT scans and recursive pivots.\n- π‘οΈ **Hudson Rock Infostealer Breach Intel:** Query infostealer malware breach logs using the `--hudson` flag for high-priority target correlation.\n- β‘ **High-Throughput Parallel Engine:** Powered by `httpx` and `curl_cffi` for maximum concurrency with automated TLS fingerprint impersonation.\n- π **Permutation & Alias Generator:** Wildcard-based username variation generation to catch typosquatting or alternative aliases.\n- π **Multi-Format Reports:** Automated exports to **PDF** (with profile photos), **JSON**, and **CSV** for pipeline integration.\n- π **Advanced Proxy Pivoting:** Built-in proxy rotation with protocol auto-detection (`http`, `socks5`) and pre-scan health validation (`--validate-proxies`).\n- π¨ **Responsive Terminal UI:** Dynamic progress tracking, self-adaptive category grids (`-lu`/`-le`), and clear status reporting.\n\n---\n\n## π Installation\n\n### π Via PyPI (Recommended)\n\n```bash\n# Upgrade pip and install user-scanner\npython3 -m pip install --upgrade pip\npip install user-scanner\n\n# Optional: Install with MCP Server support for AI agents\npip install \"user-scanner[mcp]\"\n```\n\n### π¦ Virtual Environment Setup\n\n```bash\n# Create and activate virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\Activate.ps1\n\n# Install package\npip install user-scanner\n```\n\n### βοΈ Via Nix (Linux & macOS)\n\n```bash\n# Run instantly without installing permanently\nnix run github:kaifcodec/user-scanner/main -- --help\n\n# Drop into a temporary shell with user-scanner active\nnix shell github:kaifcodec/user-scanner/main\n```\n\n---\n\n## π» Usage Guide\n\n### 1. Basic Username & Email Scanning\n\nScan a single username or email address across all available platform modules:\n\n```bash\nuser-scanner -u johndoe # Single username scan\nuser-scanner -e johndoe@gmail.com # Single email scan\nuser-scanner -u johndoe --email-domains global # Try johndoe across provider domains\n```\n\n### 2. Cross-Scan & Pivot Intelligence\n\nAn email scan proves an account exists but rarely reveals a handle. `--cross-scan` mines exposed handles, profile links, and secondary email addresses from target profiles, pivoting into multi-pass reconnaissance across all matching platforms:\n\n| Pivot Direction | What it Mines |\n| :--- | :--- |\n| `-e` β **username** | Handles or social links exposed on an email's registered profile |\n| `-u` β **username** | Secondary aliases advertised across target social profiles |\n| `-u` β **email** | Public email addresses published on target profile pages |\n| `-e` β **email** | Secondary addresses exposed by initial email profiles |\n\n```bash\nuser-scanner -u johndoe --cross-scan # Pivot from username scan\nuser-scanner -e johndoe@gmail.com --cross-scan # Pivot from email scan\nuser-scanner -e johndoe@gmail.com --cross-scan --cross-links verified # Platform-verified links only\nuser-scanner -u johndoe --cross-scan --cross-depth 2 # Follow links two hops deep\n```\n\n> π‘ *For confidence scoring, link classification rules, and cost models, see **[docs/CROSS_SCAN.md](docs/CROSS_SCAN.md)**.*\n\n### 3. Hudson Rock Malware Breach Intelligence\n\nCheck if a target username or email address has been exposed in **infostealer malware infection logs**:\n\n```bash\nuser-scanner -u johndoe --hudson # Username malware log check\nuser-scanner -e johndoe@gmail.com --hudson # Email malware log check\n```\n\n> πΌοΈ *To view output terminal screenshots and visual previews, see **[docs/EXAMPLES.md](docs/EXAMPLES.md)**.*\n\n### 4. Targeted Category & Module Scanning\n\nScan specific categories or individual modules, or list available modules in a responsive grid:\n\n```bash\nuser-scanner -u johndoe -c dev # Developer platforms only\nuser-scanner -e johndoe@gmail.com -m github # Single module check\nuser-scanner -u johndoe -m github,instagram # Specific comma-separated modules\n\nuser-scanner -lu # List user categories & modules grid\nuser-scanner -le # List email categories & modules grid\n```\n\n### 5. Bulk File Scanning\n\nScan multiple targets from an input file (one target per line):\n\n```bash\nuser-scanner -uf usernames.txt # Bulk username scan\nuser-scanner -ef emails.txt # Bulk email scan\n```\n\n### 6. Report Exports, Options & Proxies\n\n```bash\n# Export results to PDF, JSON, or CSV\nuser-scanner -u johndoe -f pdf -o report.pdf\nuser-scanner -u johndoe -f json -o results.json\n\n# Verbose URL reporting and show all results (including not found)\nuser-scanner -u johndoe -v --all\n\n# Rotate proxies with pre-scan validation check\nuser-scanner -u johndoe -P proxies.txt --validate-proxies\n```\n\n### 7. AI & LLM Agent Integration (MCP Server)\n\nConnect `user-scanner` directly to AI coding assistants and LLM platforms via the **Model Context Protocol (MCP)**. This enables AI agents (Claude Desktop, Cursor, Antigravity, Open-WebUI) to autonomously investigate handles and emails, pivot on exposed profiles, and analyze digital footprints.\n\n#### Starting the Server\n\n```bash\n# Start the MCP server over standard I/O (stdio)\nuser-scanner-mcp\n\n# Optional: Enable verbose logging to stderr\nuser-scanner-mcp -v\n```\n\n#### MCP Client Configuration\n\nAdd `user-scanner` to your client configuration (e.g. `claude_desktop_config.json` or `mcp_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"user-scanner\": {\n \"command\": \"user-scanner-mcp\"\n }\n }\n}\n```\n\n#### Exposed AI Tools\n\n| Tool | Description | Capabilities |\n| :--- | :--- | :--- |\n| `scan_username` | Deep username OSINT & profile enrichment across platforms | Targeted scans (`category`, `module`), recursive `cross_scan`, proxy injection, loudness toggles |\n| `scan_email` | Deep email verification & account discovery across platforms | Target scoping, automated link pivoting (`cross_scan`), custom proxies, loudness toggles |\n| `list_available_modules` | Dynamic catalog & module discovery | Allows AI agents to query all supported platforms and categories dynamically |\n\n---\n\n## π Documentation Hub\n\nExplore detailed documentation guides in the [`docs/`](docs/) directory:\n\n- π **[CLI Flags Reference](docs/FLAGS.md)** β Complete breakdown of every CLI flag and option.\n- π **[Cross-Scan & Pivoting Guide](docs/CROSS_SCAN.md)** β In-depth guide to multi-pass cross-scan reconnaissance.\n- π **[Pattern Syntax Guide](docs/PATTERNS.md)** β Wildcard and permutation patterns for username generation.\n- π **[Library Mode Guide](docs/USAGE.md)** β Calling the Python engine programmatically from your own scripts.\n- π **[Proxy & Network Guide](docs/PROXIES.md)** β Proxy rotation formats, health checks, and regional VPN troubleshooting.\n- πΌοΈ **[Media & Output Gallery](docs/EXAMPLES.md)** β Video demonstrations, terminal recordings, and screenshot previews.\n\n---\n\n## π Python Library Mode\n\nIntegrate the User Scanner engine directly into your Python scripts:\n\n```python\nimport asyncio\nfrom user_scanner.core import engine\nfrom user_scanner.email_scan.shopping import etsy\n\nasync def main():\n # Engine validates target against module and returns Result object\n result = await engine.check(etsy, \"test@gmail.com\")\n print(result.to_json())\n\nasyncio.run(main())\n```\n\n> π‘ *For complete Python API documentation and batch category checking examples, see **[docs/USAGE.md](docs/USAGE.md)**.*\n\n---\n\n## π Support the Project\n\nWeb platforms constantly update authentication flows. Maintaining over 2710+ scan modules requires around-the-clock commitment to keep the suite reliable and free for the cybersecurity community.\n\nIf `user-scanner` has saved you hours of manual pivoting or aided your investigations, consider supporting the project:\n\nπ **[Sponsor on GitHub](https://github.com/sponsors/kaifcodec)**\n\n### Project Sponsors\n\nHuge thanks to our amazing sponsors who support the ongoing development of `user-scanner`!\n\n\n \n ![\"soxoj\"/](\"https://github.com/soxoj.png?size=100\") \n \n @soxoj\n \n | \n \n \n ![\"hienyimba\"/](\"https://github.com/hienyimba.png?size=100\") \n \n @hienyimba\n \n | \n \n \n ![\"InDieTasten\"/](\"https://github.com/InDieTasten.png?size=100\") \n \n @InDieTasten\n \n | \n