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.

6.9 KB
Raw Blame
import pytest

from user_scanner.core.cross_scan import (
    CrossScanConfig,
    _already_scanned,
    _already_swept,
    _email_scope,
    _fresh_emails,
    _followable,
    _fresh_pivots,
    _named_targets,
    _scope,
    _split_budget,
)
from user_scanner.core.helpers import ScanConfig, get_site_name, is_loud
from user_scanner.core.pivots import PivotKind
from user_scanner.core.result import Result


def source(**extra):
    return [Result.taken(extra=extra).update(site_name="Gravatar", is_email=True)]


GRAVATAR = source(username="johndoe", links="https://github.com/johndoe")


def test_fresh_pivots_returns_everything_on_the_first_round():
    pivots = _fresh_pivots(GRAVATAR, "all", swept=set(), checked=set())

    assert {(p.site, p.username) for p in pivots} == {("gravatar", "johndoe"), ("github", "johndoe")}


def test_a_swept_username_is_never_revisited():
    pivots = _fresh_pivots(GRAVATAR, "all", swept={"johndoe"}, checked=set())

    assert pivots == []


def test_a_checked_pair_is_not_rechecked():
    pivots = _fresh_pivots(GRAVATAR, "all", swept=set(), checked={("github", "johndoe")})

    assert {p.site for p in pivots} == {"gravatar"}


def test_a_siteless_pivot_survives_until_its_username_is_swept():
    pivots = _fresh_pivots(source(bio="https://johndoe.com/"), "all", set(), {("x", "johndoe")})

    assert [(p.site, p.username, p.kind) for p in pivots] == [(None, "johndoe", PivotKind.LINK)]


def test_only_non_conflicting_hits_are_followed():
    hits = [
        Result.taken(extra={"confidence": "confirmed"}).update(site_name="Github"),
        Result.taken(extra={"confidence": "candidate"}).update(site_name="Roblox"),
        Result.taken(extra={"confidence": "conflicting"}).update(site_name="Chess.com"),
        Result.available().update(site_name="Steam"),
    ]

    assert [r.site_name for r in _followable(hits)] == ["Github", "Roblox"]


def test_the_same_account_linked_twice_is_checked_once():
    """Two profiles linking one account β€” in any casing β€” is one request."""
    pivots = _fresh_pivots(
        [
            Result.taken(extra={"verified_accounts": "X: https://x.com/JohnDoe2 (verified)"})
            .update(site_name="Gravatar", is_email=True),
            Result.taken(extra={"links": "https://twitter.com/johndoe2"})
            .update(site_name="Linktree", is_email=True),
        ],
        "all",
        swept=set(),
        checked=set(),
    )
    targets = _named_targets(pivots, swept=set(), checked=set(), configs=ScanConfig())

    assert len(pivots) == 2
    assert [m.__name__ for mods in targets.values() for m in mods] == ["x"]
    # The best-vouched pivot supplies the casing that gets scanned.
    assert list(targets) == ["JohnDoe2"]


def test_a_username_pass_does_not_rescan_its_own_target():
    """A -u pass is already a sweep of its own handle, and sites echo that handle
    back as a pivot, so it must start out marked as swept."""
    prior = [
        Result.taken(extra={"username": "JohnDoe"}).update(site_name="Chess.com", username="JohnDoe")
    ]

    assert _already_swept(prior) == {"johndoe"}
    assert _fresh_pivots(prior, "all", _already_swept(prior), set()) == []


def test_an_email_pass_seeds_nothing():
    prior = [
        Result.taken(extra={"username": "johndoe"}).update(
            site_name="Gravatar", username="[email protected]", is_email=True
        )
    ]

    assert _already_swept(prior) == set()
    assert [p.username for p in _fresh_pivots(prior, "all", set(), set())] == ["johndoe"]


def test_an_unrestricted_run_has_no_scope():
    assert _scope(CrossScanConfig(), ScanConfig()) is None


def test_a_module_restriction_resolves_against_user_scan():
    """-m names email modules on an email run, so the sweep must re-resolve the
    same site names against user_scan."""
    scope = _scope(CrossScanConfig(modules=("github", "chess.com")), ScanConfig())

    assert sorted(m.__name__ for m in scope) == ["chess_com", "github"]


def test_a_category_restriction_resolves_to_that_folder():
    scope = _scope(CrossScanConfig(categories=("donation",)), ScanConfig())

    assert scope and all("donation" in str(m.__file__) for m in scope)


def test_named_checks_stay_inside_the_scope():
    """A pivot naming a site outside -m/-c must not be checked either."""
    pivots = _fresh_pivots(
        source(verified_accounts="GitHub: https://github.com/johndoe (verified), "
                                 "LinkedIn: https://www.linkedin.com/in/johndoe (verified)"),
        "all",
        swept=set(),
        checked=set(),
    )
    scope = _scope(CrossScanConfig(modules=("github",)), ScanConfig())
    targets = _named_targets(pivots, set(), set(), ScanConfig(), scope)

    assert [m.__name__ for mods in targets.values() for m in mods] == ["github"]


def user_hit(site_name, **extra):
    return Result.taken(extra=extra).update(site_name=site_name, username="johndoe")


def test_an_email_pass_does_not_rescan_its_own_target():
    prior = [Result.taken().update(site_name="Spotify", username="[email protected]", is_email=True)]

    assert _already_scanned(prior) == {"[email protected]"}
    assert _fresh_emails(prior, "all", _already_scanned(prior)) == []


def test_a_username_pass_seeds_no_scanned_address():
    assert _already_scanned([user_hit("Github", email="[email protected]")]) == set()


def test_verified_is_the_default_and_drops_prose_addresses():
    source = [user_hit("Github", email="[email protected]", bio="also [email protected]")]

    assert [e.email for e in _fresh_emails(source, "verified", set())] == ["[email protected]"]
    assert len(_fresh_emails(source, "all", set())) == 2
    assert _fresh_emails(source, "none", set()) == []


@pytest.mark.parametrize(
    "budget,usernames,emails,expected",
    [
        (3, 5, 2, (2, 1)),
        (3, 0, 2, (0, 2)),   # nothing to sweep, addresses take the lot
        (3, 5, 0, (3, 0)),   # no addresses, usernames keep the pre-existing budget
        (1, 2, 2, (1, 0)),   # a budget of 1 still sweeps a username first
        (2, 1, 3, (1, 1)),
        (0, 5, 5, (0, 0)),
    ],
)
def test_neither_target_kind_starves_the_other(budget, usernames, emails, expected):
    assert _split_budget(budget, usernames, emails) == expected


def test_loud_email_modules_are_skipped_rather_than_prompted():
    """The addresses reaching a cross-scan came off somebody else's profile, so
    mailing them is not a decision this pass gets to make."""
    quiet = _email_scope(CrossScanConfig(), ScanConfig())
    loud_names = {m.__name__ for m in quiet if is_loud(get_site_name(m), is_email=True)}

    assert loud_names == set()
    assert _email_scope(CrossScanConfig(), ScanConfig(allow_loud=True)) is None


def test_a_module_restriction_resolves_against_email_scan():
    scope = _email_scope(CrossScanConfig(modules=("github",)), ScanConfig())

    assert [m.__name__ for m in scope] == ["github"]


def test_emails_none_loads_no_module_at_all():
    assert _email_scope(CrossScanConfig(emails="none"), ScanConfig()) == []