🕵️♂️ (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.
Python cybersecuritycybersecurity-toolsemail-osintethical-hackingethical-hacking-toolsidentificationinfosecosintosint-emailosint-toolosint-toolsosint-usernamepentestingpythonredteam-toolsredteamingthreat-intelligence
fix: address all PR review findings
Kaif5ae7db47b524
diff --git a/.github/workflows/lint-pr.yml b/.github/workflows/lint-pr.ymlindex 614eb1f..3f9a4bc 100644--- a/.github/workflows/lint-pr.yml+++ b/.github/workflows/lint-pr.yml@@ -25,7 +25,7 @@ jobs:- name: Install lintersrun: |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 ruffdiff --git a/.github/workflows/lint-push.yml b/.github/workflows/lint-push.ymlindex bbae2b7..dce9531 100644--- a/.github/workflows/lint-push.yml+++ b/.github/workflows/lint-push.yml@@ -26,7 +26,7 @@ jobs:- name: Install lintersrun: |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 ruffdiff --git a/pyproject.toml b/pyproject.tomlindex 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.pyindex 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 = timeoutdiff --git a/user_scanner/mcp/handlers.py b/user_scanner/mcp/handlers.pyindex 5053545..49dd0ce 100644--- a/user_scanner/mcp/handlers.py+++ b/user_scanner/mcp/handlers.py@@ -1,49 +1,61 @@import asyncio+import contextlibimport jsonimport logging+import sysimport mcp.types as typesfrom typing import Any-from user_scanner.core import enginefrom 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 Statuslogger = 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.TextContenif 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.pyindex 8c4fe48..60439a4 100644--- a/user_scanner/mcp/schemas.py+++ b/user_scanner/mcp/schemas.py@@ -1,107 +1,186 @@import mcp.types as typesfrom typing import Any+def get_tool_list() -> list[types.Tool]:"""Provide the list of tools available from this server."""-+# Common cross-scan parameters schemacross_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 schemabasic_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.pyindex 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_toollogging.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()