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(core): enforce positive lower bound on concurrency across cli, mcp, and orchestrators (#696)

Kaif0424e19d807e
diff --git a/docs/FLAGS.md b/docs/FLAGS.md
index b75d380..3e47930 100644
--- a/docs/FLAGS.md
+++ b/docs/FLAGS.md
@@ -28,7 +28,7 @@
| `-s, --stop STOP` | Limit the number of permutations generated |
| `-d, --delay DELAY` | Delay (in seconds) between requests |
| `-t, --timeout TIMEOUT` | Override default request timeout in seconds |
-| `-C, --concurrency CONC` | Override default concurrency limit |
+| `-C, --concurrency CONC` | Override default concurrency limit (must be at least 1) |
| `-f, --format {csv,json,pdf}`| Select output format |
| `--no-pdf-media` | Disable profile photo media fetching in PDF reports (conserves bandwidth on metered proxies) |
| `-o, --output OUTPUT` | Save results to a file (Can be used directly without `-f`) |
diff --git a/tests/test_email_orchestrator.py b/tests/test_email_orchestrator.py
index 4f65b1e..15f7dd3 100644
--- a/tests/test_email_orchestrator.py
+++ b/tests/test_email_orchestrator.py
@@ -1,13 +1,23 @@
def test_set_concurrency():
+ import pytest
from user_scanner.core.email_orchestrator import set_concurrency
import user_scanner.core.email_orchestrator as email_orchestrator
original_max = email_orchestrator.MAX_CONCURRENT_REQUESTS
- set_concurrency(5)
- assert email_orchestrator.MAX_CONCURRENT_REQUESTS == 5
-
- # restore
- set_concurrency(original_max)
+ try:
+ set_concurrency(5)
+ assert email_orchestrator.MAX_CONCURRENT_REQUESTS == 5
+
+ set_concurrency(1)
+ assert email_orchestrator.MAX_CONCURRENT_REQUESTS == 1
+
+ with pytest.raises(ValueError, match="Concurrency must be at least 1"):
+ set_concurrency(0)
+
+ with pytest.raises(ValueError, match="Concurrency must be at least 1"):
+ set_concurrency(-5)
+ finally:
+ set_concurrency(original_max)
def test_run_email_batch_multiple_categories_grouped(capsys, monkeypatch):
diff --git a/tests/test_helpers.py b/tests/test_helpers.py
index cd55f2c..58e7c3a 100644
--- a/tests/test_helpers.py
+++ b/tests/test_helpers.py
@@ -231,6 +231,18 @@ def test_username_file_unreadable(tmp_path, run_main):
assert code == 1
+def test_cli_concurrency_positive_bound(run_main, capsys):
+ code_zero = run_main(["-u", "alice", "-C", "0", "-m", "github"])
+ assert code_zero == 2
+ err_zero = capsys.readouterr().err
+ assert "must be at least 1" in err_zero
+
+ code_neg = run_main(["-u", "alice", "--concurrency", "-5", "-m", "github"])
+ assert code_neg == 2
+ err_neg = capsys.readouterr().err
+ assert "must be at least 1" in err_neg
+
+
@patch("httpx.AsyncClient")
def test_validate_proxy_all_invalid(mock_client):
instance = MagicMock()
diff --git a/tests/test_mcp_handlers.py b/tests/test_mcp_handlers.py
index 5216684..faa0579 100644
--- a/tests/test_mcp_handlers.py
+++ b/tests/test_mcp_handlers.py
@@ -35,6 +35,32 @@ async def test_execute_scan_category_and_module_together():
)
+async def test_execute_scan_invalid_concurrency():
+ from user_scanner.mcp.handlers import _scan_lock
+
+ for invalid_c in [0, -1, -10]:
+ with pytest.raises(ValueError, match="Concurrency must be at least 1"):
+ await execute_scan({"username": "testuser", "concurrency": invalid_c}, is_email=False)
+ assert not _scan_lock.locked()
+
+ with pytest.raises(ValueError, match="Invalid concurrency value"):
+ await execute_scan({"username": "testuser", "concurrency": "not_an_int"}, is_email=False)
+ assert not _scan_lock.locked()
+
+
+def test_tool_schema_concurrency_minimum():
+ from user_scanner.mcp.schemas import get_tool_list
+
+ tools = get_tool_list()
+ scan_tools = [t for t in tools if t.name in ("scan_username", "scan_email")]
+ assert len(scan_tools) == 2
+ for t in scan_tools:
+ conc_prop = t.inputSchema["properties"]["concurrency"]
+ assert conc_prop["type"] == "integer"
+ assert conc_prop["minimum"] == 1
+
+
@pytest.mark.anyio
@patch("user_scanner.mcp.handlers._run_scan")
@patch("user_scanner.mcp.handlers.set_global_timeout")
diff --git a/tests/test_orchestrator.py b/tests/test_orchestrator.py
index 3f8efec..82d0a04 100644
--- a/tests/test_orchestrator.py
+++ b/tests/test_orchestrator.py
@@ -52,16 +52,26 @@ def test_run_checks_category_threaded(monkeypatch, tmp_path):
def test_set_concurrency():
+ import pytest
from user_scanner.core.orchestrator import set_concurrency
import user_scanner.core.orchestrator as orchestrator
original_max = orchestrator.MAX_CONCURRENT_REQUESTS
- set_concurrency(10)
- assert orchestrator.MAX_CONCURRENT_REQUESTS == 10
- assert orchestrator._shared_executor._max_workers == max(10 * 2, 250)
-
- # restore
- set_concurrency(original_max)
+ try:
+ set_concurrency(10)
+ assert orchestrator.MAX_CONCURRENT_REQUESTS == 10
+ assert orchestrator._shared_executor._max_workers == max(10 * 2, 250)
+
+ set_concurrency(1)
+ assert orchestrator.MAX_CONCURRENT_REQUESTS == 1
+
+ with pytest.raises(ValueError, match="Concurrency must be at least 1"):
+ set_concurrency(0)
+
+ with pytest.raises(ValueError, match="Concurrency must be at least 1"):
+ set_concurrency(-5)
+ finally:
+ set_concurrency(original_max)
def test_run_batch_multiple_categories_grouped(capsys, monkeypatch):
diff --git a/user_scanner/__main__.py b/user_scanner/__main__.py
index fc7f2f4..60b6f26 100644
--- a/user_scanner/__main__.py
+++ b/user_scanner/__main__.py
@@ -154,7 +154,7 @@ def main():
"-C",
"--concurrency",
type=int,
- help="Override default concurrency limit (default: 60 for username, 25 for email scan)",
+ help="Override default concurrency limit (minimum: 1, default: 60 for username, 25 for email scan)",
)
parser.add_argument(
@@ -260,6 +260,8 @@ def main():
set_global_timeout(args.timeout)
if args.concurrency is not None:
+ if args.concurrency < 1:
+ parser.error(f"argument -C/--concurrency: must be at least 1, got {args.concurrency}")
from user_scanner.core.email_orchestrator import set_concurrency as set_email_concurrency
from user_scanner.core.orchestrator import set_concurrency as set_user_concurrency
set_email_concurrency(args.concurrency)
diff --git a/user_scanner/core/email_orchestrator.py b/user_scanner/core/email_orchestrator.py
index 9c16edd..8539df6 100644
--- a/user_scanner/core/email_orchestrator.py
+++ b/user_scanner/core/email_orchestrator.py
@@ -56,6 +56,8 @@ httpx.Client.__init__ = _patched_client_init # type: ignore[method-assign]
MAX_CONCURRENT_REQUESTS = 25
def set_concurrency(val: int):
+ if val < 1:
+ raise ValueError(f"Concurrency must be at least 1, got {val}")
global MAX_CONCURRENT_REQUESTS
MAX_CONCURRENT_REQUESTS = val
diff --git a/user_scanner/core/orchestrator.py b/user_scanner/core/orchestrator.py
index c481b80..f0d278a 100644
--- a/user_scanner/core/orchestrator.py
+++ b/user_scanner/core/orchestrator.py
@@ -28,6 +28,8 @@ MAX_CONCURRENT_REQUESTS = 60
_shared_executor = concurrent.futures.ThreadPoolExecutor(max_workers=max(MAX_CONCURRENT_REQUESTS * 2, 250))
def set_concurrency(val: int):
+ if val < 1:
+ raise ValueError(f"Concurrency must be at least 1, got {val}")
global MAX_CONCURRENT_REQUESTS, _shared_executor
MAX_CONCURRENT_REQUESTS = val
_shared_executor = concurrent.futures.ThreadPoolExecutor(max_workers=max(val * 2, 250))
diff --git a/user_scanner/mcp/handlers.py b/user_scanner/mcp/handlers.py
index 19595ab..fd6c849 100644
--- a/user_scanner/mcp/handlers.py
+++ b/user_scanner/mcp/handlers.py
@@ -91,6 +91,14 @@ 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.")
+ if concurrency is not None:
+ try:
+ conc_val = int(concurrency)
+ except (ValueError, TypeError) as e:
+ raise ValueError(f"Invalid concurrency value: {concurrency}") from e
+ if conc_val < 1:
+ raise ValueError(f"Concurrency must be at least 1, got {concurrency}")
+
# Normalise module name the same way the CLI does (__main__.py:518)
if module_name:
module_name = module_name.replace(".", "_")
diff --git a/user_scanner/mcp/schemas.py b/user_scanner/mcp/schemas.py
index 60439a4..6df6c1e 100644
--- a/user_scanner/mcp/schemas.py
+++ b/user_scanner/mcp/schemas.py
@@ -103,9 +103,10 @@ def get_tool_list() -> list[types.Tool]:
},
"concurrency": {
"type": "integer",
+ "minimum": 1,
"description": (
"Override default concurrency limit (how many requests to "
- "make in parallel)."
+ "make in parallel). Must be at least 1."
),
},
}