Skip to content

🕵️‍♂️ (2-in-1) Email & Username OSINT suite featuring native MCP support for deep data extraction just from a single Email/Username. Analyzes 2720+ actively maintained scan vectors (210+ email / 2510+ username) for security research, investigations, and digital footprinting.

fix: address all PR review findings

Kaif5ae7db47b524
diff --git a/.github/workflows/lint-pr.yml b/.github/workflows/lint-pr.yml
index 614eb1f..3f9a4bc 100644
--- a/.github/workflows/lint-pr.yml
+++ b/.github/workflows/lint-pr.yml
@@ -25,7 +25,7 @@ jobs:
- name: Install linters
run: |
python -m pip install --upgrade pip
- pip install httpx curl_cffi colorama types-colorama rich mcp
+ pip install httpx curl_cffi colorama types-colorama rich "mcp>=1.2.0,<2"
pip install ruff==0.15.22 mypy
- name: Run ruff
diff --git a/.github/workflows/lint-push.yml b/.github/workflows/lint-push.yml
index bbae2b7..dce9531 100644
--- a/.github/workflows/lint-push.yml
+++ b/.github/workflows/lint-push.yml
@@ -26,7 +26,7 @@ jobs:
- name: Install linters
run: |
python -m pip install --upgrade pip
- pip install httpx curl_cffi colorama types-colorama rich mcp
+ pip install httpx curl_cffi colorama types-colorama rich "mcp>=1.2.0,<2"
pip install ruff==0.15.22 mypy
- name: Run ruff
diff --git a/pyproject.toml b/pyproject.toml
index 611e879..3777174 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -26,7 +26,7 @@ keywords = ["osint", "email-osint", "username-osint", "python", "cli-tool", "cyb
[project.optional-dependencies]
dev = ["pytest", "pytest-cov", "pytest-anyio", "anyio[trio]"]
pdf = ["reportlab>=4.0.0", "pillow>=10.0.0", "svglib>=1.5.0"]
-mcp = ["mcp>=1.2.0"]
+mcp = ["mcp>=1.2.0,<2"]
[project.urls]
Homepage = "https://github.com/kaifcodec/user-scanner"
diff --git a/user_scanner/core/helpers.py b/user_scanner/core/helpers.py
index 6c7fe75..f17a694 100644
--- a/user_scanner/core/helpers.py
+++ b/user_scanner/core/helpers.py
@@ -71,7 +71,7 @@ class ScanConfig:
_global_timeout: Optional[float] = None
-def set_global_timeout(timeout: float) -> None:
+def set_global_timeout(timeout: Optional[float]) -> None:
global _global_timeout
_global_timeout = timeout
diff --git a/user_scanner/mcp/handlers.py b/user_scanner/mcp/handlers.py
index 5053545..49dd0ce 100644
--- a/user_scanner/mcp/handlers.py
+++ b/user_scanner/mcp/handlers.py
@@ -1,49 +1,61 @@
import asyncio
+import contextlib
import json
import logging
+import sys
import mcp.types as types
from typing import Any
-from user_scanner.core import engine
from user_scanner.core.formatter import into_json
-from user_scanner.core.helpers import find_module, load_categories, load_modules, get_site_name, ScanConfig, set_proxy_manager, set_global_timeout
+from user_scanner.core.helpers import (
+ find_module,
+ load_categories,
+ load_modules,
+ get_site_name,
+ ScanConfig,
+ set_proxy_manager,
+ set_global_timeout,
+)
from user_scanner.core.cross_scan import run_cross_scan, CrossScanConfig
-from user_scanner.core.orchestrator import set_concurrency as set_user_concurrency
-from user_scanner.core.email_orchestrator import set_concurrency as set_email_concurrency
+from user_scanner.core.orchestrator import (
+ run_user_full,
+ run_user_category,
+ run_user_module,
+ set_concurrency as set_user_concurrency,
+)
+from user_scanner.core.email_orchestrator import (
+ run_email_full_batch,
+ run_email_category_batch,
+ run_email_module_batch,
+ set_concurrency as set_email_concurrency,
+)
+from user_scanner.core.result import Status
logger = logging.getLogger("user-scanner-mcp")
+# Default concurrency values (must match orchestrator/email_orchestrator defaults)
+_DEFAULT_USER_CONCURRENCY = 60
+_DEFAULT_EMAIL_CONCURRENCY = 25
+
+# Serialise scans so concurrent tool calls don't stomp global state
+_scan_lock = asyncio.Lock()
+
+
async def execute_scan(arguments: dict, is_email: bool) -> list[types.TextContent]:
target_key = "email" if is_email else "username"
target = arguments.get(target_key)
-
+
if not target:
raise ValueError(f"Missing '{target_key}' argument")
-
+
category = arguments.get("category")
module_name = arguments.get("module")
allow_loud = arguments.get("allow_loud", False)
no_nsfw = arguments.get("no_nsfw", False)
proxies = arguments.get("proxies")
-
- if proxies:
- logger.info(f"Setting up proxy manager with {len(proxies)} proxies.")
- set_proxy_manager(proxies=proxies)
- else:
- # Clear it just in case this is a subsequent request
- set_proxy_manager(proxies=None)
-
timeout = arguments.get("timeout")
- if timeout is not None:
- set_global_timeout(float(timeout))
- else:
- set_global_timeout(None) # type: ignore
-
concurrency = arguments.get("concurrency")
- if concurrency is not None:
- set_user_concurrency(int(concurrency))
- set_email_concurrency(int(concurrency))
-
+
cross_scan = arguments.get("cross_scan", False)
cross_links = arguments.get("cross_links", "all")
cross_emails = arguments.get("cross_emails", "verified")
@@ -53,63 +65,136 @@ async def execute_scan(arguments: dict, is_email: bool) -> list[types.TextConten
if category and module_name:
raise ValueError("Cannot specify both 'category' and 'module'. Choose one.")
+ # Normalise module name the same way the CLI does (__main__.py:518)
+ if module_name:
+ module_name = module_name.replace(".", "_")
+
logger.info(f"Executing {'email' if is_email else 'username'} scan for: {target}")
-
- # Construct base config
+
config = ScanConfig(allow_loud=allow_loud, no_nsfw=no_nsfw, timeout=timeout)
-
- # 1. Run Initial Scan
- results = []
+
+ async with _scan_lock:
+ # Apply global settings, wrapped in try/finally to always restore
+ try:
+ if proxies:
+ logger.info(f"Setting up proxy manager with {len(proxies)} proxies.")
+ set_proxy_manager(proxies=proxies)
+ else:
+ set_proxy_manager(proxies=None)
+
+ if timeout is not None:
+ set_global_timeout(float(timeout))
+ else:
+ set_global_timeout(None)
+
+ if concurrency is not None:
+ set_user_concurrency(int(concurrency))
+ set_email_concurrency(int(concurrency))
+ else:
+ set_user_concurrency(_DEFAULT_USER_CONCURRENCY)
+ set_email_concurrency(_DEFAULT_EMAIL_CONCURRENCY)
+
+ # Redirect stdout to stderr so orchestrator print() calls
+ # don't corrupt the JSON-RPC stdio stream
+ with contextlib.redirect_stdout(sys.stderr):
+ results = await asyncio.to_thread(
+ _run_scan, target, config, is_email, category, module_name
+ )
+
+ if cross_scan:
+ logger.info(
+ f"Running cross-scan (depth={cross_depth}, sweep={cross_sweep})"
+ )
+ cross_configs = CrossScanConfig(
+ links=cross_links,
+ emails=cross_emails,
+ sweep=cross_sweep,
+ depth=cross_depth,
+ modules=(module_name,) if module_name else (),
+ categories=(category,) if category else (),
+ )
+ cross_results = run_cross_scan(results, config, cross_configs)
+ results.extend(cross_results)
+ finally:
+ # Restore defaults so the next request starts clean
+ set_proxy_manager(proxies=None)
+ set_global_timeout(None)
+ set_user_concurrency(_DEFAULT_USER_CONCURRENCY)
+ set_email_concurrency(_DEFAULT_EMAIL_CONCURRENCY)
+
+ # Build response envelope with per-status counts
+ found = [r for r in results if r.status == Status.TAKEN]
+ errors = [r for r in results if r.status == Status.ERROR]
+ skipped = [r for r in results if r.status == Status.SKIPPED]
+
+ envelope: dict[str, Any] = {
+ "summary": {
+ "total_scanned": len(results),
+ "found": len(found),
+ "not_found": len(results) - len(found) - len(errors) - len(skipped),
+ "errors": len(errors),
+ "skipped": len(skipped),
+ },
+ "results": json.loads(into_json(found)),
+ }
+
+ if errors:
+ envelope["errored_sites"] = [
+ r.site_name for r in errors if r.site_name
+ ]
+
+ logger.info(f"Found {len(found)} total valid results.")
+ return [types.TextContent(type="text", text=json.dumps(envelope, indent=2))]
+
+
+def _run_scan(
+ target: str,
+ config: ScanConfig,
+ is_email: bool,
+ category: str | None,
+ module_name: str | None,
+) -> list:
+ """Run the scan synchronously via the orchestrators (not engine.check*).
+
+ The orchestrators enforce allow_loud, no_nsfw, and loud-module gating
+ exactly as the CLI does.
+ """
if module_name:
- modules = find_module(module_name, is_email=is_email, no_nsfw=no_nsfw)
+ modules = find_module(module_name, is_email=is_email, no_nsfw=config.no_nsfw)
if not modules:
- return [types.TextContent(type="text", text=f"Error: Module '{module_name}' not found.")]
- # For simplicity in MCP, we just use engine.check which ignores loud checks if directly targeted
- # But to be safe, we just run the first module
- result = await engine.check(modules[0], target)
- results = [result]
+ return []
+ fn = run_email_module_batch if is_email else run_user_module
+ return fn(modules, target, config)
elif category:
- try:
- results = await engine.check_category(category, target, is_email=is_email)
- except ValueError as e:
- return [types.TextContent(type="text", text=json.dumps({"error": str(e)}))]
+ cats = load_categories(is_email, config.no_nsfw)
+ cat_path = cats.get(category)
+ if not cat_path:
+ return []
+ fn_cat = run_email_category_batch if is_email else run_user_category
+ return fn_cat(cat_path, target, config)
else:
- results = await engine.check_all(target, is_email=is_email)
-
- # 2. Cross-Scan if requested
- if cross_scan:
- logger.info(f"Running cross-scan (depth={cross_depth}, sweep={cross_sweep})")
- cross_configs = CrossScanConfig(
- links=cross_links,
- emails=cross_emails,
- sweep=cross_sweep,
- depth=cross_depth,
- modules=(module_name,) if module_name else (),
- categories=(category,) if category else (),
- )
- # run_cross_scan modifies/returns a list of new results
- cross_results = await asyncio.to_thread(run_cross_scan, results, config, cross_configs)
- results.extend(cross_results)
-
- # 3. Filter and Format
- # Filter out empty results to save LLM context window limits
- found = [r for r in results if r.is_found()]
- logger.info(f"Found {len(found)} total valid results.")
- return [types.TextContent(type="text", text=into_json(found))]
+ fn_full = run_email_full_batch if is_email else run_user_full
+ return fn_full(target, config)
+
async def handle_list_available_modules(arguments: dict) -> list[types.TextContent]:
is_email = arguments.get("is_email", False)
- categories = load_categories(is_email=is_email)
-
- output: dict[str, Any] = {"scan_type": "email" if is_email else "username", "categories": {}}
-
+ no_nsfw = arguments.get("no_nsfw", False)
+ categories = load_categories(is_email=is_email, no_nsfw=no_nsfw)
+
+ output: dict[str, Any] = {
+ "scan_type": "email" if is_email else "username",
+ "categories": {},
+ }
+
for cat_name, cat_path in categories.items():
modules = load_modules(cat_path)
site_names = [get_site_name(m) for m in modules]
output["categories"][cat_name] = site_names
-
+
return [types.TextContent(type="text", text=json.dumps(output, indent=2))]
+
async def call_tool(name: str, arguments: dict | None) -> list[types.TextContent]:
"""Route the tool call to the correct handler."""
if not arguments:
diff --git a/user_scanner/mcp/schemas.py b/user_scanner/mcp/schemas.py
index 8c4fe48..60439a4 100644
--- a/user_scanner/mcp/schemas.py
+++ b/user_scanner/mcp/schemas.py
@@ -1,107 +1,186 @@
import mcp.types as types
from typing import Any
+
def get_tool_list() -> list[types.Tool]:
"""Provide the list of tools available from this server."""
-
+
# Common cross-scan parameters schema
cross_scan_props = {
"cross_scan": {
- "type": "boolean",
- "description": "Set to true to enable recursive OSINT pivoting. The engine will automatically extract emails, alternative usernames, and links found in the initial results and scan them too, building a deep web of connections."
+ "type": "boolean",
+ "description": (
+ "Set to true to enable recursive OSINT pivoting. The engine will "
+ "automatically extract emails, alternative usernames, and links "
+ "found in the initial results and scan them too, building a deep "
+ "web of connections."
+ ),
},
"cross_links": {
"type": "string",
"enum": ["all", "verified", "none"],
- "description": "Controls link pivoting strictness during a cross-scan. 'all' pivots from any bio link. 'verified' only pivots from platform-proven connections. 'none' disables link pivoting. Default: 'all'."
+ "description": (
+ "Controls link pivoting strictness during a cross-scan. "
+ "'all' pivots from any bio link. 'verified' only pivots from "
+ "platform-proven connections. 'none' disables link pivoting. "
+ "Default: 'all'."
+ ),
},
"cross_emails": {
"type": "string",
"enum": ["all", "verified", "none"],
- "description": "Controls email pivoting strictness during a cross-scan. 'verified' (default) only scans addresses explicitly published in an email field. 'all' includes scraping emails from bio text."
+ "description": (
+ "Controls email pivoting strictness during a cross-scan. "
+ "'verified' (default) only scans addresses explicitly published "
+ "in an email field. 'all' includes scraping emails from bio text."
+ ),
},
"cross_depth": {
"type": "integer",
- "description": "How deep the recursive link-following should go. Default: 1. Increase for deeper but slower investigations."
+ "description": (
+ "How deep the recursive link-following should go. Default: 1. "
+ "Increase for deeper but slower investigations."
+ ),
},
"cross_sweep": {
"type": "integer",
- "description": "How many targets the cross-scan should automatically sweep against all modules. Default: 3. Set to 0 to only scan sites explicitly named in pivots (prevents handle collisions)."
- }
+ "description": (
+ "How many targets the cross-scan should automatically sweep "
+ "against all modules. Default: 3. Set to 0 to only scan sites "
+ "explicitly named in pivots (prevents handle collisions)."
+ ),
+ },
}
# Common basic parameters schema
basic_props = {
"category": {
- "type": "string",
- "description": "Optional category to restrict the scan to (e.g. 'social', 'gaming', 'dev'). Use list_available_modules to see options. Cannot be used with 'module'."
+ "type": "string",
+ "description": (
+ "Optional category to restrict the scan to (e.g. 'social', "
+ "'gaming', 'dev'). Use list_available_modules to see options. "
+ "Cannot be used with 'module'."
+ ),
},
"module": {
- "type": "string",
- "description": "Optional specific site/module to restrict the scan to (e.g. 'github'). Use list_available_modules to see options. Cannot be used with 'category'."
+ "type": "string",
+ "description": (
+ "Optional specific site/module to restrict the scan to "
+ "(e.g. 'github'). Use list_available_modules to see options. "
+ "Cannot be used with 'category'."
+ ),
},
"allow_loud": {
"type": "boolean",
- "description": "WARNING: Set to true ONLY if stealth is not required. Enabling this runs aggressive modules that may trigger password reset emails and alert the target. Default: false (stealth mode)."
+ "description": (
+ "WARNING: Set to true ONLY if stealth is not required. "
+ "Enabling this runs aggressive modules that may trigger "
+ "password reset emails and alert the target. "
+ "Default: false (stealth mode)."
+ ),
},
"no_nsfw": {
"type": "boolean",
- "description": "Set to true to disable scanning of adult/NSFW sites. Default: false."
+ "description": (
+ "Set to true to disable scanning of adult/NSFW sites. "
+ "Default: false."
+ ),
},
"proxies": {
"type": "array",
"items": {"type": "string"},
- "description": "An optional list of proxy URLs (e.g. 'http://proxy:port') to use for the scan. Recommended to avoid rate limits."
+ "description": (
+ "An optional list of proxy URLs (e.g. 'http://proxy:port') "
+ "to use for the scan. Recommended to avoid rate limits."
+ ),
},
"timeout": {
"type": "integer",
- "description": "Override default request timeout in seconds. Useful if the target sites are slow or you are using slow proxies."
+ "description": (
+ "Override default request timeout in seconds. Useful if the "
+ "target sites are slow or you are using slow proxies."
+ ),
},
"concurrency": {
"type": "integer",
- "description": "Override default concurrency limit (how many requests to make in parallel)."
- }
+ "description": (
+ "Override default concurrency limit (how many requests to "
+ "make in parallel)."
+ ),
+ },
}
- username_props: dict[str, Any] = {"username": {"type": "string", "description": "The handle/username to scan for."}}
+ username_props: dict[str, Any] = {
+ "username": {
+ "type": "string",
+ "description": "The handle/username to scan for.",
+ },
+ }
username_props.update(basic_props)
username_props.update(cross_scan_props)
- email_props: dict[str, Any] = {"email": {"type": "string", "description": "The email address to scan for."}}
+ email_props: dict[str, Any] = {
+ "email": {
+ "type": "string",
+ "description": "The email address to scan for.",
+ },
+ }
email_props.update(basic_props)
email_props.update(cross_scan_props)
return [
- types.Tool( # type: ignore
+ types.Tool( # type: ignore[call-arg]
name="scan_username",
- description="Scans for the presence of a username across platforms. Can be scoped to a specific category or module, and can recursively cross-scan linked profiles.",
+ description=(
+ "Scans for the presence of a username across platforms. "
+ "Can be scoped to a specific category or module, and can "
+ "recursively cross-scan linked profiles."
+ ),
inputSchema={
"type": "object",
"properties": username_props,
- "required": ["username"]
- }
+ "required": ["username"],
+ },
),
- types.Tool( # type: ignore
+ types.Tool( # type: ignore[call-arg]
name="scan_email",
- description="Scans for the presence of an email across platforms. Can be scoped to a specific category or module, and can recursively cross-scan linked profiles.",
+ description=(
+ "Scans for the presence of an email across platforms. "
+ "Can be scoped to a specific category or module, and can "
+ "recursively cross-scan linked profiles."
+ ),
inputSchema={
"type": "object",
"properties": email_props,
- "required": ["email"]
- }
+ "required": ["email"],
+ },
),
- types.Tool( # type: ignore
+ types.Tool( # type: ignore[call-arg]
name="list_available_modules",
- description="Lists all available categories and modules (sites) supported by the scanner. Use this to discover valid inputs for the 'category' and 'module' parameters.",
+ description=(
+ "Lists all available categories and modules (sites) "
+ "supported by the scanner. Use this to discover valid "
+ "inputs for the 'category' and 'module' parameters."
+ ),
inputSchema={
"type": "object",
"properties": {
"is_email": {
"type": "boolean",
- "description": "If true, lists email scan modules. If false, lists username scan modules. Default: False"
- }
+ "description": (
+ "If true, lists email scan modules. "
+ "If false, lists username scan modules. "
+ "Default: false."
+ ),
+ },
+ "no_nsfw": {
+ "type": "boolean",
+ "description": (
+ "If true, excludes adult/NSFW modules from "
+ "the listing. Default: false."
+ ),
+ },
},
- "required": ["is_email"]
- }
- )
+ },
+ ),
]
diff --git a/user_scanner/mcp/server.py b/user_scanner/mcp/server.py
index 32b7e20..faa8fa7 100644
--- a/user_scanner/mcp/server.py
+++ b/user_scanner/mcp/server.py
@@ -18,35 +18,43 @@ from user_scanner.mcp.handlers import call_tool
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
- stream=sys.stderr
+ stream=sys.stderr,
)
logger = logging.getLogger("user-scanner-mcp")
app = Server("user-scanner")
[email protected]_tools() # type: ignore
+
[email protected]_tools() # type: ignore[attr-defined]
async def handle_list_tools():
"""Provide the list of tools available from this server."""
return get_tool_list()
[email protected]_tool() # type: ignore
+
[email protected]_tool() # type: ignore[attr-defined]
async def handle_call_tool(name: str, arguments: dict | None):
"""Execute the requested tool and return the OSINT scan results."""
return await call_tool(name, arguments)
+
async def run():
"""Run the server over standard input/output streams."""
async with stdio_server() as (read_stream, write_stream):
await app.run(
read_stream,
write_stream,
- app.create_initialization_options()
+ app.create_initialization_options(),
)
+
def main():
"""Entry point for the MCP server script."""
parser = argparse.ArgumentParser(description="user-scanner MCP server")
- parser.add_argument("-v", "--verbose", action="store_true", help="Enable verbose logging output to stderr")
+ parser.add_argument(
+ "-v", "--verbose",
+ action="store_true",
+ help="Enable verbose logging output to stderr",
+ )
args = parser.parse_args()
if not args.verbose:
@@ -54,8 +62,9 @@ def main():
else:
logger.setLevel(logging.INFO)
logger.info("Starting user-scanner MCP server over stdio in verbose mode...")
-
+
asyncio.run(run())
+
if __name__ == "__main__":
main()