# User Scanner
---
A powerful **2-in-1 OSINT suite** engineered for deep **Email and Username Intelligence**.
With **465+ total scan vectors**βincluding **175+ email-integrated sites** and **290+ username platforms**βyou can map digital footprints, analyze target behavior, uncover interests, full metadata of usernames and verify account registrations in seconds.
---
## π Sponsored by
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.
Start an Investigation β
---
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.
Get Started β
---
## β¨ Key Features
- π **Deep Email & Username OSINT:** Look up email registrations and perform advanced username profiling across 465+ platforms.
- π€ **Rich Metadata Scraping:** Scrapes avatars, bio descriptions, follower counts, UID numbers, seller statuses, and account attributes.
- π **Cross-Scan & Pivot Engine:** Mines handles, profile links, and exposed email addresses from initial scans, automatically pivoting across secondary target vectors.
- π€ **Model Context Protocol (MCP) Server:** Native AI agent integration for Claude Desktop, Cursor, Antigravity, and LLMs to run autonomous OSINT scans and recursive pivots.
- π‘οΈ **Hudson Rock Infostealer Breach Intel:** Query infostealer malware breach logs using the `--hudson` flag for high-priority target correlation.
- β‘ **High-Throughput Parallel Engine:** Powered by `httpx` and `curl_cffi` for maximum concurrency with automated TLS fingerprint impersonation.
- π **Permutation & Alias Generator:** Wildcard-based username variation generation to catch typosquatting or alternative aliases.
- π **Multi-Format Reports:** Automated exports to **PDF** (with profile photos), **JSON**, and **CSV** for pipeline integration.
- π **Advanced Proxy Pivoting:** Built-in proxy rotation with protocol auto-detection (`http`, `socks5`) and pre-scan health validation (`--validate-proxies`).
- π¨ **Responsive Terminal UI:** Dynamic progress tracking, self-adaptive category grids (`-lu`/`-le`), and clear status reporting.
---
## π Installation
### π Via PyPI (Recommended)
```bash
# Upgrade pip and install user-scanner
python3 -m pip install --upgrade pip
pip install user-scanner
# Optional: Install with MCP Server support for AI agents
pip install "user-scanner[mcp]"
```
### π¦ Virtual Environment Setup
```bash
# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\Activate.ps1
# Install package
pip install user-scanner
```
### βοΈ Via Nix (Linux & macOS)
```bash
# Run instantly without installing permanently
nix run github:kaifcodec/user-scanner/main -- --help
# Drop into a temporary shell with user-scanner active
nix shell github:kaifcodec/user-scanner/main
```
---
## π» Usage Guide
### 1. Basic Username & Email Scanning
Scan a single username or email address across all available platform modules:
```bash
user-scanner -u johndoe # Single username scan
user-scanner -e johndoe@gmail.com # Single email scan
```
### 2. Cross-Scan & Pivot Intelligence
An 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:
| Pivot Direction | What it Mines |
| :--- | :--- |
| `-e` β **username** | Handles or social links exposed on an email's registered profile |
| `-u` β **username** | Secondary aliases advertised across target social profiles |
| `-u` β **email** | Public email addresses published on target profile pages |
| `-e` β **email** | Secondary addresses exposed by initial email profiles |
```bash
user-scanner -u johndoe --cross-scan # Pivot from username scan
user-scanner -e johndoe@gmail.com --cross-scan # Pivot from email scan
user-scanner -e johndoe@gmail.com --cross-scan --cross-links verified # Platform-verified links only
user-scanner -u johndoe --cross-scan --cross-depth 2 # Follow links two hops deep
```
> π‘ *For confidence scoring, link classification rules, and cost models, see **[docs/CROSS_SCAN.md](docs/CROSS_SCAN.md)**.*
### 3. Hudson Rock Malware Breach Intelligence
Check if a target username or email address has been exposed in **infostealer malware infection logs**:
```bash
user-scanner -u johndoe --hudson # Username malware log check
user-scanner -e johndoe@gmail.com --hudson # Email malware log check
```
> πΌοΈ *To view output terminal screenshots and visual previews, see **[docs/EXAMPLES.md](docs/EXAMPLES.md)**.*
### 4. Targeted Category & Module Scanning
Scan specific categories or individual modules, or list available modules in a responsive grid:
```bash
user-scanner -u johndoe -c dev # Developer platforms only
user-scanner -e johndoe@gmail.com -m github # Single module check
user-scanner -u johndoe -m github,instagram # Specific comma-separated modules
user-scanner -lu # List user categories & modules grid
user-scanner -le # List email categories & modules grid
```
### 5. Bulk File Scanning
Scan multiple targets from an input file (one target per line):
```bash
user-scanner -uf usernames.txt # Bulk username scan
user-scanner -ef emails.txt # Bulk email scan
```
### 6. Report Exports, Options & Proxies
```bash
# Export results to PDF, JSON, or CSV
user-scanner -u johndoe -f pdf -o report.pdf
user-scanner -u johndoe -f json -o results.json
# Verbose URL reporting and show all results (including not found)
user-scanner -u johndoe -v --all
# Rotate proxies with pre-scan validation check
user-scanner -u johndoe -P proxies.txt --validate-proxies
```
### 7. AI & LLM Agent Integration (MCP Server)
Connect `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.
#### Starting the Server
```bash
# Start the MCP server over standard I/O (stdio)
user-scanner-mcp
# Optional: Enable verbose logging to stderr
user-scanner-mcp -v
```
#### MCP Client Configuration
Add `user-scanner` to your client configuration (e.g. `claude_desktop_config.json` or `mcp_config.json`):
```json
{
"mcpServers": {
"user-scanner": {
"command": "user-scanner-mcp"
}
}
}
```
#### Exposed AI Tools
| Tool | Description | Capabilities |
| :--- | :--- | :--- |
| `scan_username` | Deep username OSINT & profile enrichment across platforms | Targeted scans (`category`, `module`), recursive `cross_scan`, proxy injection, loudness toggles |
| `scan_email` | Deep email verification & account discovery across platforms | Target scoping, automated link pivoting (`cross_scan`), custom proxies, loudness toggles |
| `list_available_modules` | Dynamic catalog & module discovery | Allows AI agents to query all supported platforms and categories dynamically |
---
## π Documentation Hub
Explore detailed documentation guides in the [`docs/`](docs/) directory:
- π **[CLI Flags Reference](docs/FLAGS.md)** β Complete breakdown of every CLI flag and option.
- π **[Cross-Scan & Pivoting Guide](docs/CROSS_SCAN.md)** β In-depth guide to multi-pass cross-scan reconnaissance.
- π **[Pattern Syntax Guide](docs/PATTERNS.md)** β Wildcard and permutation patterns for username generation.
- π **[Library Mode Guide](docs/USAGE.md)** β Calling the Python engine programmatically from your own scripts.
- π **[Proxy & Network Guide](docs/PROXIES.md)** β Proxy rotation formats, health checks, and regional VPN troubleshooting.
- πΌοΈ **[Media & Output Gallery](docs/EXAMPLES.md)** β Video demonstrations, terminal recordings, and screenshot previews.
---
## π Python Library Mode
Integrate the User Scanner engine directly into your Python scripts:
```python
import asyncio
from user_scanner.core import engine
from user_scanner.email_scan.shopping import etsy
async def main():
# Engine validates target against module and returns Result object
result = await engine.check(etsy, "test@gmail.com")
print(result.to_json())
asyncio.run(main())
```
> π‘ *For complete Python API documentation and batch category checking examples, see **[docs/USAGE.md](docs/USAGE.md)**.*
---
## π Support the Project
Web platforms constantly update authentication flows. Maintaining over 465+ scan modules requires around-the-clock commitment to keep the suite reliable and free for the cybersecurity community.
If `user-scanner` has saved you hours of manual pivoting or aided your investigations, consider supporting the project:
π **[Sponsor on GitHub](https://github.com/sponsors/kaifcodec)**
### Project Sponsors
Huge thanks to our amazing sponsors who support the ongoing development of `user-scanner`!
---
## π Contributing
We welcome community contributions! Please read our **[Contributing Guidelines](CONTRIBUTING.md)** before opening a PR or submitting new scan modules.
---
## β οΈ Disclaimer
This tool is provided strictly for **educational purposes**, **authorized security research**, and **defensive OSINT investigations**. The developers assume no liability and are not responsible for any misuse, unintended consequences, or legal actions resulting from the deployment of this software.
