🕵️♂️ (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
import sys
import threading
import json
from types import SimpleNamespace
from unittest.mock import MagicMock, AsyncMock, patch
import pytest
from user_scanner.__main__ import main
from user_scanner.core import helpers
from user_scanner.core.result import Result
from user_scanner.core.helpers import _get_config_path, load_config, save_config_value, CONFIG_PATH
def test_get_site_name():
def module(name: str) -> SimpleNamespace:
return SimpleNamespace(**{"__name__": name})
assert helpers.get_site_name(module("X")) == "X (Twitter)"
assert helpers.get_site_name(module("x")) == "X (Twitter)"
assert helpers.get_site_name(module("user_scanner.github")) == "Github"
assert helpers.get_site_name(module("user_scanner.chess_com")) == "Chess.com"
def test_parse_email_domain_scopes_dedupes_in_order(monkeypatch):
monkeypatch.setitem(helpers.EMAIL_DOMAIN_SCOPES, "test", ("gmail.com", "example.com"))
domains = helpers.parse_email_domain_scopes("global,test")
global_domains = helpers.EMAIL_DOMAIN_SCOPES["global"]
assert domains[: len(global_domains)] == global_domains
assert domains.count("gmail.com") == 1
assert domains[-1] == "example.com"
def test_parse_email_domain_scopes_all():
assert helpers.parse_email_domain_scopes("all") == tuple(
dict.fromkeys(
domain
for domains in helpers.EMAIL_DOMAIN_SCOPES.values()
for domain in domains
)
)
def test_parse_email_domain_scopes_rejects_unknown():
with pytest.raises(ValueError, match="Unknown email domain scope 'mars'"):
helpers.parse_email_domain_scopes("global,mars")
@pytest.fixture
def run_main(monkeypatch):
def _run(args):
monkeypatch.setattr(sys, "argv", ["user-scanner"] + args)
monkeypatch.setattr("user_scanner.__main__.check_for_updates", lambda: None)
monkeypatch.setattr("user_scanner.__main__.update_self", lambda: None)
monkeypatch.setattr("user_scanner.__main__.print_banner", lambda: None)
# Added **kwargs to handle show_url argument
monkeypatch.setattr(
"user_scanner.__main__.run_email_module_batch",
lambda m, t, config, **kwargs: [
Result.taken(username=t, site_name=m, is_email=True)
],
)
# Added **kwargs to handle show_url argument
monkeypatch.setattr(
"user_scanner.__main__.run_user_module",
lambda module, target, config, **kwargs: [
Result.taken(username=target, site_name=module, is_email=False)
],
)
try:
main()
return 0
except SystemExit as exc:
return exc.code
return _run
def test_bulk_emails_valid(tmp_path, run_main, capsys):
email_file = tmp_path / "test_emails.txt"
email_file.write_text("""[email protected]
[email protected]
[email protected]""")
exit_code = run_main(["-ef", str(email_file), "-m", "github"])
out = capsys.readouterr().out
assert "Loaded 3 emails" in out
assert exit_code == 0
def test_bulk_emails_partially_valid(tmp_path, run_main, capsys):
email_file = tmp_path / "test_emails.txt"
email_file.write_text("""[email protected]
invalid-email
[email protected]""")
exit_code = run_main(["-ef", str(email_file), "-m", "github"])
out = capsys.readouterr().out
assert "Skipping invalid email format: invalid-email" in out
assert "Loaded 2 emails" in out
assert exit_code == 0
def test_bulk_emails_single_valid(tmp_path, run_main, capsys):
email_file = tmp_path / "test_emails.txt"
email_file.write_text("""[email protected]
invalid-email
invalid-email3""")
exit_code = run_main(["-ef", str(email_file), "-m", "github"])
out = capsys.readouterr().out
assert "Loaded 1 email" in out
assert exit_code == 0
def test_bulk_emails_invalid(tmp_path, run_main):
email_file = tmp_path / "test_emails.txt"
email_file.write_text("""invalid-email-1
invalid-email-2
invalid-email-3@""")
exit_code = run_main(["-ef", str(email_file), "-m", "github"])
assert exit_code == 1
def test_bulk_emails_empty_file(tmp_path, run_main):
email_file = tmp_path / "test_emails.txt"
email_file.write_text("")
exit_code = run_main(["-ef", str(email_file), "-m", "github"])
assert exit_code == 1
def test_bulk_emails_no_file(run_main):
exit_code = run_main(["-ef", "no_file.txt", "-m", "github"])
assert exit_code == 1
def test_bulk_emails_skip_comments_blank_lines(tmp_path, run_main, capsys):
email_file = tmp_path / "test_emails.txt"
email_file.write_text("""[email protected]
# comment
[email protected]
""")
exit_code = run_main(["-ef", str(email_file), "-m", "github"])
out = capsys.readouterr().out
assert "Loaded 2 emails" in out
assert exit_code == 0
def test_email_file_unreadable(tmp_path, run_main):
email_file = tmp_path / "test_emails.txt"
email_file.write_text("[email protected]")
email_file.chmod(0)
code = run_main(["-ef", str(email_file), "-m", "github"])
assert code == 1
def test_bulk_usernames_valid(tmp_path, run_main, capsys):
username_file = tmp_path / "test_usernames.txt"
username_file.write_text("""user1
user2
user3""")
exit_code = run_main(["-uf", str(username_file), "-m", "github"])
out = capsys.readouterr().out
assert "Loaded 3 usernames" in out
assert exit_code == 0
def test_bulk_usernames_single_valid(tmp_path, run_main, capsys):
username_file = tmp_path / "test_usernames.txt"
username_file.write_text("user1")
exit_code = run_main(["-uf", str(username_file), "-m", "github"])
out = capsys.readouterr().out
assert "Loaded 1 username" in out
assert exit_code == 0
def test_bulk_usernames_empty_file(tmp_path, run_main):
username_file = tmp_path / "test_usernames.txt"
username_file.write_text("")
exit_code = run_main(["-uf", str(username_file), "-m", "github"])
assert exit_code == 1
def test_bulk_usernames_no_file(run_main):
exit_code = run_main(["-uf", "no_file.txt", "-m", "github"])
assert exit_code == 1
def test_bulk_usernames_skip_comments_blank_lines(tmp_path, run_main, capsys):
username_file = tmp_path / "test_usernames.txt"
username_file.write_text("""user1
# comment
user2""")
exit_code = run_main(["-uf", str(username_file), "-m", "github"])
out = capsys.readouterr().out
assert "Loaded 2 usernames" in out
assert exit_code == 0
def test_username_email_domains_use_email_modules(run_main, capsys):
exit_code = run_main(["-u", "alice", "--email-domains", "usa", "-m", "github"])
out = capsys.readouterr().out
assert "Checking email: [email protected]" in out
assert "Checking email: [email protected]" in out
assert "Checking email: [email protected]" in out
assert exit_code == 0
def test_username_file_unreadable(tmp_path, run_main):
username_file = tmp_path / "test_usernames.txt"
username_file.write_text("user")
username_file.chmod(0)
code = run_main(["-uf", str(username_file), "-m", "github"])
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
@pytest.mark.parametrize(
"flag, value, message",
[
("--stop", "0", "must be at least 1"),
("--stop", "-3", "must be at least 1"),
("--delay", "-1", "must be at least 0"),
("--delay", "nan", "finite"),
("--delay", "inf", "finite"),
("--delay", "1e9", "at most"),
("--timeout", "0", "greater than 0"),
("--timeout", "-5", "greater than 0"),
("--timeout", "nan", "finite"),
("--timeout", "inf", "finite"),
("--timeout", "99999", "at most"),
("--cross-depth", "0", "must be at least 1"),
("--cross-depth", "-2", "must be at least 1"),
("--cross-sweep", "-1", "must be at least 0"),
("--stop", "abc", "Invalid"),
("--concurrency", "501", "must be at most 500"),
("--concurrency", "1000000000000000000", "must be at most 500"),
],
)
def test_cli_numeric_options_are_bounded(run_main, capsys, flag, value, message):
code = run_main(["-u", "alice", flag, value, "-m", "github"])
assert code == 2
err = capsys.readouterr().err
assert flag in err
assert message in err
@patch("httpx.AsyncClient")
def test_validate_proxy_all_invalid(mock_client):
instance = MagicMock()
mock_client.return_value.__aenter__.return_value = instance
response = MagicMock()
response.status_code = 302
instance.get = AsyncMock(return_value=response)
proxies = ["http://proxy1.example.com:8080", "http://proxy2.example.com:3128"]
result = helpers.validate_proxies(proxies)
assert result == []
@patch("httpx.AsyncClient")
def test_validate_proxy_partially_invalid(mock_client):
def side_effect(*args, **kwargs):
proxy = kwargs.get("proxy")
instance = MagicMock()
if proxy and "invalid" in proxy:
instance.get = AsyncMock(side_effect=Exception("connection failed"))
else:
response = MagicMock()
response.status_code = 200
instance.get = AsyncMock(return_value=response)
cm = MagicMock()
cm.__aenter__.return_value = instance
cm.__aexit__.return_value = None
return cm
mock_client.side_effect = side_effect
proxies = ["http://invalid", "socks5://socks-proxy.example.com:1080"]
result = helpers.validate_proxies(proxies)
assert result == ["socks5://socks-proxy.example.com:1080"]
def test_validate_proxy_empty_list():
result = helpers.validate_proxies([])
assert result == []
@patch("httpx.AsyncClient")
def test_validate_proxy_timeout(mock_client):
instance = MagicMock()
mock_client.return_value.__aenter__.return_value = instance
instance.get = AsyncMock(side_effect=helpers.httpx.TimeoutException("timeout"))
proxies = ["http://proxy1.example.com:8080"]
result = helpers.validate_proxies(proxies, timeout=1)
assert result == []
@patch("httpx.AsyncClient")
def test_validate_proxy_single_worker(mock_client):
instance = MagicMock()
mock_client.return_value.__aenter__.return_value = instance
response = MagicMock()
response.status_code = 200
instance.get = AsyncMock(return_value=response)
proxies = ["http://proxy1.example.com:8080", "http://proxy2.example.com:3128"]
result = helpers.validate_proxies(proxies, max_workers=1)
assert result == proxies
def test_validate_proxy_rejects_proxy_that_cannot_tunnel_tls():
# Answers every plaintext request with a forged 204 but refuses CONNECT,
# so it cannot carry an HTTPS request end to end.
import socket
import threading
server = socket.socket()
server.bind(("127.0.0.1", 0))
server.listen(8)
port = server.getsockname()[1]
requests: list[bytes] = []
def serve():
while True:
try:
conn, _ = server.accept()
except OSError:
return
with conn:
data = conn.recv(4096)
requests.append(data)
if data.startswith(b"CONNECT"):
conn.sendall(b"HTTP/1.1 405 Method Not Allowed\r\nContent-Length: 0\r\n\r\n")
else:
conn.sendall(b"HTTP/1.1 204 No Content\r\n\r\n")
threading.Thread(target=serve, daemon=True).start()
try:
result = helpers.validate_proxies([f"http://127.0.0.1:{port}"], timeout=2)
finally:
server.close()
assert result == []
assert requests and all(r.startswith(b"CONNECT") for r in requests)
def test_proxy_manager_add_protocol(tmp_path):
proxy_file = tmp_path / "test_proxies.txt"
proxy_file.write_text("""proxy1.example.com:8080
socks5://socks-proxy.example.com:1080""")
manager = helpers.ProxyManager(str(proxy_file))
assert manager.count() == 2
assert manager.proxies[0].startswith("http://")
assert manager.proxies[1].startswith("socks5://")
def test_proxy_manager_preserves_explicit_schemes(tmp_path):
proxy_file = tmp_path / "test_proxies.txt"
proxy_file.write_text("""socks4://legacy-proxy.example.com:1080
socks5h://onion-proxy.example.com:9050
https://secure-proxy.example.com:443""")
manager = helpers.ProxyManager(str(proxy_file))
assert manager.proxies == [
"socks4://legacy-proxy.example.com:1080",
"socks5h://onion-proxy.example.com:9050",
"https://secure-proxy.example.com:443",
]
def test_proxy_manager_no_poxy_file(tmp_path):
with pytest.raises(FileNotFoundError) as exc_info:
helpers.ProxyManager("no_proxy_file.txt")
assert exc_info.type is FileNotFoundError
def test_proxy_manager_empty_file_only_comments(tmp_path):
proxy_file = tmp_path / "test_proxy.txt"
proxy_file.write_text("""#comment
""")
with pytest.raises(Exception):
helpers.ProxyManager(str(proxy_file))
def test_proxy_rotation(tmp_path):
proxy_file = tmp_path / "test_proxy.txt"
proxy_file.write_text("""http://1
http://2
http://3""")
manager = helpers.ProxyManager(str(proxy_file))
assert manager.get_next_proxy() == "http://1"
assert manager.get_next_proxy() == "http://2"
assert manager.get_next_proxy() == "http://3"
assert manager.get_next_proxy() == "http://1"
def test_single_proxy_rotation(tmp_path):
proxy_file = tmp_path / "test_proxy.txt"
proxy_file.write_text("http://1")
manager = helpers.ProxyManager(str(proxy_file))
for _ in range(3):
assert manager.get_next_proxy() == "http://1"
def test_global_manager(tmp_path):
proxy_file = tmp_path / "test_proxy.txt"
proxy_file.write_text("""http://1
http://2""")
helpers.set_proxy_manager(str(proxy_file))
p1 = helpers.get_proxy()
p2 = helpers.get_proxy()
assert p1 != p2
assert helpers.get_proxy_count() == 2
def test_thread_safe_rotation(tmp_path):
proxy_file = tmp_path / "test_proxy.txt"
proxy_file.write_text("""http://1
http://2
http://3""")
manager = helpers.ProxyManager(str(proxy_file))
results = []
def worker():
results.append(manager.get_next_proxy())
threads = [threading.Thread(target=worker) for _ in range(50)]
for t in threads:
t.start()
for t in threads:
t.join()
assert len(results) == 50
def test_get_config_path_default(monkeypatch):
monkeypatch.delenv("USER_SCANNER_CONFIG", raising=False)
path = _get_config_path()
assert path == CONFIG_PATH
def test_get_config_path_env_override(monkeypatch, tmp_path):
custom_path = tmp_path / "custom_config.json"
monkeypatch.setenv("USER_SCANNER_CONFIG", str(custom_path))
path = _get_config_path()
assert path == custom_path
def test_load_config_creates_default(tmp_path):
config_file = tmp_path / "new_config.json"
data = load_config(path=config_file)
assert config_file.exists()
assert data["auto_update_status"] is True
assert data["auto_hudson_prompt"] is True
def test_load_config_reads_existing(tmp_path):
config_file = tmp_path / "existing.json"
existing_data = {
"auto_update_status": False,
"auto_hudson_prompt": False
}
config_file.write_text(json.dumps(existing_data))
data = load_config(path=config_file)
assert data == existing_data
def test_save_config_value_updates_keys(tmp_path):
config_file = tmp_path / "test_save.json"
save_config_value("auto_update_status", False, path=config_file)
data = load_config(path=config_file)
assert data["auto_update_status"] is False
assert data["auto_hudson_prompt"] is True
save_config_value("auto_hudson_prompt", False, path=config_file)
data = load_config(path=config_file)
assert data["auto_hudson_prompt"] is False
assert data["auto_update_status"] is False
def test_load_config_handles_corrupt_json(tmp_path):
config_file = tmp_path / "corrupt.json"
config_file.write_text("{ 'broken': true, }")
data = load_config(path=config_file)
assert data["auto_update_status"] is True
assert data["auto_hudson_prompt"] is True
def test_save_config_value_creates_directory(tmp_path):
nested_path = tmp_path / "subdir" / "nested_config.json"
save_config_value("auto_update_status", True, path=nested_path)
assert nested_path.exists()
assert nested_path.parent.is_dir()
def test_hudson_config_value():
from user_scanner.core.helpers import _get_config_path, load_config
actual_path = _get_config_path()
data = load_config(path=actual_path)
status = data.get("auto_hudson_prompt")
assert status is True, f"FAIL: Actual config at {actual_path} has auto_hudson_prompt set to {status} (Expected: True)"
def test_global_timeout():
from user_scanner.core.helpers import set_global_timeout, get_global_timeout
set_global_timeout(10.5)
assert get_global_timeout() == 10.5
set_global_timeout(None)
assert get_global_timeout() is None