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(mcp): reject unknown module and category names instead of scanning nothing (#735)

Vamika Singhal631827c17eba
diff --git a/README.md b/README.md
index 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 Hub
diff --git a/tests/test_mcp_handlers.py b/tests/test_mcp_handlers.py
index 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.py
index fd6c849..87c0fd3 100644
--- a/user_scanner/mcp/handlers.py
+++ b/user_scanner/mcp/handlers.py
@@ -1,5 +1,6 @@
import asyncio
import contextlib
+import difflib
import json
import logging
import 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.TextConten
if 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_module
return 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_category
return fn_cat(cat_path, target, config)
else:
diff --git a/user_scanner/mcp/schemas.py b/user_scanner/mcp/schemas.py
index 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": {