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.

17.1 KB
Raw Blame
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