user-scanner README

The project's README from github.com/kaifcodec/user-scanner. As one markdown file: README.md.

User Scanner

User Scanner Logo

Discord

kaifcodec%2Fuser-scanner | Trendshift

A powerful 2-in-1 OSINT suite engineered for deep Email and Username Intelligence.

With 550+ total scan vectors—including 175+ email-integrated sites and 375+ username platforms—you can map digital footprints, analyze target behavior, uncover interests, full metadata of usernames and verify account registrations in seconds.

💖 Sponsored by

WebVetted Sponsor Banner
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 →

banner-github
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 →

banner-github
Find beginner-friendly open-source issues and make your first pull request today.
Get Started →

✨ Key Features

🚀 Installation

# 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

# 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)

# 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:

user-scanner -u johndoe             # Single username scan
user-scanner -e [email protected]   # 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 
user-scanner -u johndoe --cross-scan                                  # Pivot from username scan
user-scanner -e [email protected] --cross-scan                        # Pivot from email scan
user-scanner -e [email protected] --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.*

3. Hudson Rock Malware Breach Intelligence

Check if a target username or email address has been exposed in infostealer malware infection logs:

user-scanner -u johndoe --hudson             # Username malware log check
user-scanner -e [email protected] --hudson   # Email malware log check

🖼️ *To view output terminal screenshots and visual previews, see docs/EXAMPLES.md.*

4. Targeted Category & Module Scanning

Scan specific categories or individual modules, or list available modules in a responsive grid:

user-scanner -u johndoe -c dev                # Developer platforms only
user-scanner -e [email protected] -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):

user-scanner -uf usernames.txt   # Bulk username scan
user-scanner -ef emails.txt      # Bulk email scan

6. Report Exports, Options & Proxies

# 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

# 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):

{
  "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/ directory:

🐍 Python Library Mode

Integrate the User Scanner engine directly into your Python scripts:

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, "[email protected]")
    print(result.to_json())

asyncio.run(main())

💡 *For complete Python API documentation and batch category checking examples, see docs/USAGE.md.*

💖 Support the Project

Web platforms constantly update authentication flows. Maintaining over 550+ 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

Project Sponsors

Huge thanks to our amazing sponsors who support the ongoing development of user-scanner!

soxoj
@soxoj 		hienyimba
@hienyimba 		InDieTasten
@InDieTasten

📜 Contributing

We welcome community contributions! Please read our Contributing Guidelines 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.

user-scanner (kaifcodec/user-scanner)

Searching Database…

5.4K ·GitHub
User-scanner
Что это такое?User Scanner — это CLI-инструмент для OSINT (разведки по открытым источникам), который принимает адрес электронной почты или имя пользователя и проверяет их на более чем 2720 платформах (210+ векторов для email, 2510+ векторов для имён пользователей), чтобы находить цифровые следы, собирать метаданные профилей и выявлять связанные аккаунты.
Это CLI-инструмент или то, что я вызываю из кода?В первую очередь это инструмент командной строки, но также есть режим библиотеки Python для программного запуска движка сканирования и MCP-сервер, чтобы ИИ-агенты, такие как Claude Desktop или Cursor, могли запускать сканирования сами.
Как мне установить и запустить это?Установить можно через PyPI (рекомендуется), в виртуальном окружении или через Nix в Linux/macOS, а затем запустить проверку одного имени пользователя или email по всем доступным модулям.
Что используется внутри для сканирования?Написан на Python; для массовых параллельных запросов использует httpx и curlcffi с автоматической имитацией TLS-отпечатка, чтобы не быть обнаруженным.
Почему сканирование может не работать или нужны прокси?Сайты постоянно меняют процессы авторизации, поэтому модули со временем могут ломаться; в инструмент встроена ротация прокси с проверкой их работоспособности (--validate-proxies), чтобы обходить ограничения частоты запросов и региональные блокировки.
Для кого это сделано?Для исследователей безопасности, red team-специалистов, тестировщиков на проникновение и OSINT-аналитиков, которые занимаются разрешённым сбором цифровых следов и сопоставлением утечек.
Это работает и на Windows?Это Python-пакет, который устанавливается через PyPI везде, где работает Python; путь установки через Nix явно указан только для Linux и macOS.
А есть ли юридические или этические подводные камни при использовании?Инструмент предоставляется исключительно в учебных целях и для разрешённых исследований в области безопасности; разработчики снимают с себя ответственность за неправомерное использование.
Что на самом деле делает --cross-scan?Он извлекает никнеймы, ссылки на профили и вспомогательные email-адреса, засвеченные в найденных профилях цели, а затем автоматически запускает второй раунд сканирования по этим новым идентификаторам для более глубокой разведки.
Для чего нужен флаг --hudson?Он проверяет по журналам утечек от инфостилеров Hudson Rock, не появлялись ли имя пользователя или email цели в данных заражённых машин; полезно для приоритетного сопоставления утечек.
Могут ли ИИ-агенты вроде Claude использовать это напрямую?Да, user-scanner поставляется с собственным MCP-сервером, который предоставляет инструменты scan-username, scan-email и list-available-modules, поэтому агенты в Claude Desktop, Cursor или Antigravity могут проводить автономные OSINT-расследования и дальнейший поиск по найденным связям.
В каких форматах отчётов я могу экспортировать результаты?Результаты сканирования можно экспортировать в PDF (включая фото профилей), JSON и CSV для дальнейшей интеграции в пайплайны.
What are similar projects?maigret, spiderfoot, Anthropic-Cybersecurity-Skills, Claude-Red, dsh-redteam-model, awesome-osint, redamon, awesome-hacker-search-engines
Which topics is it in?redteaming, osint-tools, osint-tool, threat-intelligence, ethical-hacking, infosec, osint, pentesting, cybersecurity, security-tools, mcp, security
Creator
kaifcodec
Size
2.5 MB
Stars
5.4K
Updated
CommitOct 16Releasev1.5.2Sep 17
Age
11mo
Commits · 90 Days