π΅οΈββοΈ (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(mcp): reject unknown module and category names instead of scanning nothing (#735)
Vamika Singhal631827c17eba
diff --git a/README.md b/README.mdindex 1e3ada0..12b8115 100644--- a/README.md+++ b/README.md@@ -242,6 +242,8 @@ Add `user-scanner` to your client configuration (e.g. `claude_desktop_config.jso| `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 |+An unknown `category` or `module` name is rejected with an error that suggests the closest valid names, so a typo never comes back as a scan with no findings. Use `list_available_modules` to see the full catalog.+---## π Documentation Hubdiff --git a/tests/test_mcp_handlers.py b/tests/test_mcp_handlers.pyindex faa0579..d161995 100644--- a/tests/test_mcp_handlers.py+++ b/tests/test_mcp_handlers.py@@ -49,6 +49,89 @@ async def test_execute_scan_invalid_concurrency():assert not _scan_lock.locked()+async def test_execute_scan_unknown_module_is_an_error():+ from user_scanner.mcp.handlers import _scan_lock++ with pytest.raises(ValueError, match="Unknown username module 'githb'") as exc_info:+ await execute_scan({"username": "testuser", "module": "githb"}, is_email=False)+ assert "Did you mean: 'github'" in str(exc_info.value)+ assert "list_available_modules" in str(exc_info.value)+ assert not _scan_lock.locked()++ with pytest.raises(ValueError, match="Unknown email module 'no_such_site_xyz'") as exc_info:+ await execute_scan({"email": "[email protected]", "module": "no_such_site_xyz"}, is_email=True)+ assert "Did you mean" not in str(exc_info.value)+ assert "list_available_modules" in str(exc_info.value)+ assert not _scan_lock.locked()+++async def test_execute_scan_unknown_category_is_an_error():+ from user_scanner.mcp.handlers import _scan_lock++ # Category names are exact, like the CLI: a different-case spelling is+ # rejected and the correctly cased name is the first suggestion.+ with pytest.raises(ValueError, match="Unknown username category 'Social'") as exc_info:+ await execute_scan({"username": "testuser", "category": "Social"}, is_email=False)+ assert "Did you mean: 'social'" in str(exc_info.value)+ assert not _scan_lock.locked()++ with pytest.raises(ValueError, match="Unknown email category 'gamming'") as exc_info:+ await execute_scan({"email": "[email protected]", "category": "gamming"}, is_email=True)+ assert "'gaming'" in str(exc_info.value)+ assert not _scan_lock.locked()+++async def test_execute_scan_unknown_category_respects_no_nsfw():+ # 'adult' exists, but not once no_nsfw excludes it+ with pytest.raises(ValueError, match="Unknown username category 'adult'"):+ await execute_scan(+ {"username": "testuser", "category": "adult", "no_nsfw": True}, is_email=False+ )+++@patch("user_scanner.mcp.handlers._run_scan")+@patch("user_scanner.mcp.handlers.set_proxy_manager")+async def test_execute_scan_unknown_scope_never_starts_a_scan(mock_set_proxy, mock_run_scan):+ with pytest.raises(ValueError, match="Unknown username module"):+ await execute_scan(+ {"username": "testuser", "module": "githb", "proxies": ["http://127.0.0.1:8080"]},+ is_email=False,+ )+ mock_set_proxy.assert_not_called()+ mock_run_scan.assert_not_called()+++@patch("user_scanner.mcp.handlers._run_scan")+async def test_execute_scan_known_scopes_still_run(mock_run_scan):+ mock_run_scan.return_value = [Result.available()]++ # Module names resolve case-insensitively, exactly like the CLI's -m flag+ await execute_scan({"username": "testuser", "module": "GitHub"}, is_email=False)+ assert mock_run_scan.call_args[0][4] == "GitHub"++ await execute_scan({"username": "testuser", "category": "social"}, is_email=False)+ assert mock_run_scan.call_args[0][3] == "social"++ await execute_scan({"email": "[email protected]", "module": "github"}, is_email=True)+ assert mock_run_scan.call_args[0][4] == "github"+++def test_run_scan_rejects_unknown_scope():+ """The thread-side scan must not quietly return [] for a bad scope either."""+ from user_scanner.mcp.handlers import _run_scan++ config = ScanConfig(allow_loud=False, no_nsfw=False, timeout=None)+ with pytest.raises(ValueError, match="Unknown username module 'githb'"):+ _run_scan("testuser", config, False, None, "githb")+ with pytest.raises(ValueError, match="Unknown email category 'gamming'"):+ _run_scan("[email protected]", config, True, "gamming", None)++def test_tool_schema_concurrency_minimum():from user_scanner.mcp.schemas import get_tool_list@@ -113,13 +196,15 @@ async def test_execute_scan_argument_mapping(async def test_execute_scan_module_normalization(mock_run_scan):mock_run_scan.return_value = [Result.available()]- # Passing a module name with a dot (e.g. from the list_available_modules output)+ # Passing a module name with a dot (e.g. from the list_available_modules output).+ # Made.porn is an email module, so scan as email: a name that resolves to+ # nothing is an error now.arguments = {- "username": "testuser",+ "email": "[email protected]","module": "Made.porn",}- await execute_scan(arguments, is_email=False)+ await execute_scan(arguments, is_email=True)call_args = mock_run_scan.call_args[0]module_name = call_args[4]diff --git a/user_scanner/mcp/handlers.py b/user_scanner/mcp/handlers.pyindex fd6c849..87c0fd3 100644--- a/user_scanner/mcp/handlers.py+++ b/user_scanner/mcp/handlers.py@@ -1,5 +1,6 @@import asyncioimport contextlib+import difflibimport jsonimport loggingimport sys@@ -67,6 +68,58 @@ async def _run_in_thread(func: Any, *args: Any) -> Any:raise+def _module_names(is_email: bool, no_nsfw: bool) -> list[str]:+ """Return every loadable module name for the scan type, as passed to 'module'."""+ return sorted(+ module.__name__.split(".")[-1]+ for category_path in load_categories(is_email, no_nsfw).values()+ for module in load_modules(category_path)+ )+++def _unknown_scope_error(kind: str, name: str, valid: list[str], is_email: bool) -> ValueError:+ """Build the error for a 'module' or 'category' value that matches nothing.++ A typo or a stale agent plan must not look like a scan with no findings,+ so the message names the rejected value, suggests the closest valid+ choices (a different-case spelling first) and points at+ list_available_modules for the full listing.+ """+ scan_type = "email" if is_email else "username"+ by_lower = {v.lower(): v for v in valid}+ same_case_insensitive = by_lower.get(name.lower())+ suggestions = [same_case_insensitive] if same_case_insensitive else []+ for match in difflib.get_close_matches(name.lower(), list(by_lower), n=3, cutoff=0.6):+ if by_lower[match] not in suggestions:+ suggestions.append(by_lower[match])++ message = f"Unknown {scan_type} {kind} '{name}'."+ if suggestions:+ message += " Did you mean: " + ", ".join(f"'{s}'" for s in suggestions[:3]) + "?"+ message += " Use list_available_modules to see the valid choices."+ return ValueError(message)+++def _validate_scope(+ category: str | None, module_name: str | None, is_email: bool, no_nsfw: bool+) -> None:+ """Reject a 'module' or 'category' value that does not resolve to anything.++ Mirrors the CLI, which exits with "module 'x' not found" instead of+ scanning nothing. Runs before the scan lock is taken, so a rejected+ scope never touches proxies, timeouts or concurrency.+ """+ if module_name:+ if not find_module(module_name, is_email=is_email, no_nsfw=no_nsfw):+ raise _unknown_scope_error(+ "module", module_name, _module_names(is_email, no_nsfw), is_email+ )+ elif category:+ categories = load_categories(is_email, no_nsfw)+ if category not in categories:+ raise _unknown_scope_error("category", category, sorted(categories), is_email)++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)@@ -103,6 +156,9 @@ async def execute_scan(arguments: dict, is_email: bool) -> list[types.TextContenif module_name:module_name = module_name.replace(".", "_")+ # An unknown module or category is an error, not an empty scan+ _validate_scope(category, module_name, is_email, no_nsfw)+logger.info(f"Executing {'email' if is_email else 'username'} scan for: {target}")config = ScanConfig(allow_loud=allow_loud, no_nsfw=no_nsfw, timeout=timeout)@@ -198,14 +254,16 @@ def _run_scan(if module_name:modules = find_module(module_name, is_email=is_email, no_nsfw=config.no_nsfw)if not modules:- return []+ raise _unknown_scope_error(+ "module", module_name, _module_names(is_email, config.no_nsfw), is_email+ )fn = run_email_module_batch if is_email else run_user_modulereturn fn(modules, target, config)elif category:cats = load_categories(is_email, config.no_nsfw)cat_path = cats.get(category)if not cat_path:- return []+ raise _unknown_scope_error("category", category, sorted(cats), is_email)fn_cat = run_email_category_batch if is_email else run_user_categoryreturn fn_cat(cat_path, target, config)else:diff --git a/user_scanner/mcp/schemas.py b/user_scanner/mcp/schemas.pyindex 6df6c1e..6ff0d41 100644--- a/user_scanner/mcp/schemas.py+++ b/user_scanner/mcp/schemas.py@@ -59,7 +59,8 @@ def get_tool_list() -> list[types.Tool]:"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'."+ "An unknown category is rejected with an error that suggests "+ "close matches. Cannot be used with 'module'."),},"module": {@@ -67,7 +68,8 @@ def get_tool_list() -> list[types.Tool]:"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'."+ "An unknown module is rejected with an error that suggests "+ "close matches. Cannot be used with 'category'."),},"allow_loud": {