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.

21.0 KB
Raw Blame
"""Second scan pass driven by the first pass's metadata.

An email scan proves an account exists but rarely names it. When a profile does
expose a handle or a link to another platform, that handle can be scanned as a
username β€” reaching accounts no email check can see.

Two kinds of hit come out of that, and they are not equally trustworthy: a site
a pivot named by handle, and a site where the same handle merely happens to be
taken. Every hit is scored so the difference survives into the report.
"""

from dataclasses import dataclass
from types import ModuleType
from typing import Dict, Iterable, List, Optional, Set, Tuple

from colorama import Fore, Style

from user_scanner.core.confidence import (
    ORDER,
    Confidence,
    RankedEmail,
    build_anchors,
    rank_emails,
    score,
)
from user_scanner.core.email_orchestrator import run_email_full_batch, run_email_module_batch
from user_scanner.core.helpers import (
    ScanConfig,
    find_module,
    get_site_name,
    is_loud,
    load_categories,
    load_modules,
)
from user_scanner.core.orchestrator import run_user_full, run_user_module
from user_scanner.core.pivots import (
    Pivot,
    extract_email_pivots,
    extract_pivots,
    module_stem,
    rank_usernames,
    select_email_pivots,
    select_pivots,
)
from user_scanner.core.result import Result

DEFAULT_SWEEP = 3
DEFAULT_DEPTH = 1
LINK_CHOICES = ("all", "verified", "none")
EMAIL_CHOICES = ("all", "verified", "none")

_CONFIDENCE_COLOR = {
    Confidence.CONFIRMED: Fore.GREEN,
    Confidence.LIKELY: Fore.CYAN,
    Confidence.CANDIDATE: Fore.WHITE,
    Confidence.CONFLICTING: Fore.YELLOW,
}


@dataclass(frozen=True)
class CrossScanConfig:
    links: str = "all"
    # Module and category names the run was restricted to, so -m and -c narrow
    # this pass exactly as they narrowed the first one. Names, not modules: an
    # email run's -m names email modules, and the sweep needs the username
    # module of the same site.
    modules: Tuple[str, ...] = ()
    categories: Tuple[str, ...] = ()
    # Which addresses found in scan metadata may be scanned as emails. Defaults
    # tighter than `links` because the cost of being wrong is higher: a stray
    # username pivot wastes a request, a stray address puts a third party in the
    # report and can hand them to a module that mails them.
    emails: str = "verified"
    # How many targets may be swept against every module, across all rounds β€”
    # usernames and addresses draw on the same budget, since sweeping either one
    # costs a full pass over that scan type. Zero turns sweeping off entirely,
    # leaving only the sites a pivot named.
    sweep: int = DEFAULT_SWEEP
    depth: int = DEFAULT_DEPTH


def run_cross_scan(
    results: List[Result], configs: ScanConfig, cross_configs: CrossScanConfig
) -> List[Result]:
    """Mine finished results for usernames and scan them.

    Runs ``depth`` rounds: each round pivots off the accounts the previous one
    found, so a handle reachable only through a chain of profile links is still
    reached. Returns every round's results; the caller owns merging them into
    its own list for export.
    """
    print(f"\n{Fore.MAGENTA}== CROSS-SCAN =={Style.RESET_ALL}")

    scope = _scope(cross_configs, configs)
    email_modules = _email_scope(cross_configs, configs)
    # Either half alone is a usable pass, so this only gives up when the
    # restriction leaves neither a username module nor an email module.
    if scope is not None and not scope and email_modules is not None and not email_modules:
        print(
            f"{Fore.YELLOW}[!] The -m/-c restriction names no username or email "
            f"module, so there is nothing to cross-scan.{Style.RESET_ALL}"
        )
        return []

    depth = max(1, cross_configs.depth)
    budget = max(0, cross_configs.sweep)
    all_pivots: List[Pivot] = []
    cross_results: List[Result] = []
    swept: Set[str] = _already_swept(results)
    checked: Set[Tuple[str, str]] = set()
    scanned_emails: Set[str] = _already_scanned(results)
    email_ratings: Dict[str, Confidence] = {}
    source: List[Result] = list(results)

    for round_number in range(1, depth + 1):
        pivots = _fresh_pivots(source, cross_configs.links, swept, checked)
        ranked = _fresh_emails(source, cross_configs.emails, scanned_emails)
        if not pivots and not ranked:
            if round_number == 1:
                print(
                    f"{Fore.YELLOW}[!] No usernames, links or addresses to pivot "
                    f"from.{Style.RESET_ALL}"
                )
                return []
            print(f"\n{Fore.CYAN}[i] Round {round_number}: nothing new to follow.{Style.RESET_ALL}")
            break

        if depth > 1:
            print(f"\n{Fore.MAGENTA}-- round {round_number} of {depth} --{Style.RESET_ALL}")
        if pivots:
            _print_pivots(pivots)
        if ranked:
            _print_emails(ranked)
        all_pivots.extend(pivots)

        sweepable = 0 if scope is not None and not scope else len(rank_usernames(pivots))
        for_usernames, for_emails = _split_budget(budget, sweepable, len(ranked))
        usernames = _sweep_targets(pivots, for_usernames)
        to_scan = _email_targets(ranked, for_emails, email_modules)
        budget -= len(usernames) + len(to_scan)
        swept.update(username.lower() for username in usernames)
        scanned_emails.update(entry.email for entry in to_scan)
        email_ratings.update({entry.email: entry.confidence for entry in to_scan})

        round_results: List[Result] = []
        for username in usernames:
            print(
                f"\n{Fore.CYAN}[+] Sweeping every module for username: {username}{Style.RESET_ALL}"
            )
            swept_results = (
                run_user_full(username, configs)
                if scope is None
                else run_user_module(scope, username, configs)
            )
            round_results.extend(_tag(swept_results, all_pivots, username))

        for username, modules in _named_targets(pivots, swept, checked, configs, scope).items():
            print(
                f"\n{Fore.CYAN}[+] Checking {username} on its {len(modules)} linked "
                f"site(s){Style.RESET_ALL}"
            )
            round_results.extend(
                _tag(run_user_module(modules, username, configs), all_pivots, username)
            )

        for entry in to_scan:
            print(f"\n{Fore.CYAN}[+] Scanning email: {entry.email}{Style.RESET_ALL}")
            email_results = (
                run_email_full_batch(entry.email, configs)
                if email_modules is None
                else run_email_module_batch(email_modules, entry.email, configs)
            )
            round_results.extend(_tag_emails(email_results, entry))

        checked.update((p.site, p.username.lower()) for p in pivots if p.site)
        cross_results.extend(round_results)

        if round_number < depth:
            _apply_confidence(results, cross_results, all_pivots, email_ratings)
            source = _followable(round_results)

    _apply_confidence(results, cross_results, all_pivots, email_ratings)
    _print_summary(results, cross_results)
    return cross_results


def _scope(
    cross_configs: CrossScanConfig, configs: ScanConfig
) -> Optional[List[ModuleType]]:
    """The user_scan modules this run is allowed to touch, or None if unrestricted."""
    if cross_configs.modules:
        return [
            module
            for name in cross_configs.modules
            for module in find_module(
                name.replace(".", "_"), is_email=False, no_nsfw=configs.no_nsfw
            )
        ]
    if cross_configs.categories:
        paths = load_categories(False, configs.no_nsfw)
        return [
            module
            for name in cross_configs.categories
            if name in paths
            for module in load_modules(paths[name])
        ]
    return None


def _email_scope(
    cross_configs: CrossScanConfig, configs: ScanConfig
) -> Optional[List[ModuleType]]:
    """The email_scan modules this run may touch, or None for all of them.

    Loud modules are dropped rather than prompted for. The addresses reaching
    here came off somebody else's profile, and mailing a third party is not a
    decision a second scan pass should be making; ``--allow-loud`` puts them
    back for a caller who has already accepted that.
    """
    if cross_configs.emails == "none":
        return []

    modules: Optional[List[ModuleType]] = None
    if cross_configs.modules:
        modules = [
            module
            for name in cross_configs.modules
            for module in find_module(
                name.replace(".", "_"), is_email=True, no_nsfw=configs.no_nsfw
            )
        ]
    elif cross_configs.categories:
        paths = load_categories(True, configs.no_nsfw)
        modules = [
            module
            for name in cross_configs.categories
            if name in paths
            for module in load_modules(paths[name])
        ]
    elif configs.allow_loud:
        return None
    else:
        modules = [
            module
            for path in load_categories(True, configs.no_nsfw).values()
            for module in load_modules(path)
        ]

    if not configs.allow_loud:
        modules = [m for m in modules if not is_loud(get_site_name(m), is_email=True)]
    return modules


def _already_swept(results: Iterable[Result]) -> Set[str]:
    """Usernames the first pass already ran against every module.

    A username pass is itself a sweep of its own target, and sites tend to report
    that handle straight back, so without this it would rank first and spend a
    sweep repeating the scan that just finished. An email pass contributes
    nothing here β€” its target is not a username.
    """
    return {str(r.username).lower() for r in results if not r.is_email and r.username}


def _fresh_pivots(
    source: List[Result], links: str, swept: Set[str], checked: Set[Tuple[str, str]]
) -> List[Pivot]:
    """Pivots from ``source`` that no earlier round has already acted on.

    A swept username had every module run against it, so nothing about it is
    left to do; a named pair is done once that one site has been checked.
    """
    pivots = select_pivots(extract_pivots(source), links)
    return [
        pivot
        for pivot in pivots
        if pivot.username.lower() not in swept
        and (pivot.site is None or (pivot.site, pivot.username.lower()) not in checked)
    ]


def _already_scanned(results: Iterable[Result]) -> Set[str]:
    """Addresses the first pass already ran against every email module.

    An email pass is itself a scan of its own target, and profiles routinely
    report that address straight back, so without this it would rank first and
    spend the budget repeating the scan that just finished.
    """
    return {str(r.username).lower() for r in results if r.is_email and r.username}


def _fresh_emails(source: List[Result], emails: str, scanned: Set[str]) -> List[RankedEmail]:
    """Addresses in ``source`` no earlier round has already scanned, best first."""
    pivots = [
        pivot
        for pivot in select_email_pivots(extract_email_pivots(source), emails)
        if pivot.email not in scanned
    ]
    if not pivots:
        return []
    return rank_emails(pivots, build_anchors(confirmed=_followable(source)))


def _followable(round_results: List[Result]) -> List[Result]:
    """The hits a further round may pivot off.

    An account whose metadata names someone else is a handle collision, and
    following its links would walk into a stranger's footprint.
    """
    return [
        result
        for result in round_results
        if result.is_found()
        and result.extra.get("confidence") != Confidence.CONFLICTING.value
    ]


def _split_budget(budget: int, usernames: int, emails: int) -> Tuple[int, int]:
    """Share one sweep budget between the two target kinds.

    Half is offered to addresses, rounded down so a budget of 1 still sweeps a
    username β€” the behaviour before addresses existed β€” and whatever one kind
    cannot use falls to the other. Neither can starve the other outright: with
    any budget at all, both get a slot as soon as there are two to give.
    """
    if budget <= 0:
        return 0, 0
    for_emails = min(budget // 2, emails)
    for_usernames = min(budget - for_emails, usernames)
    return for_usernames, min(budget - for_usernames, emails)


def _sweep_targets(pivots: List[Pivot], budget: int) -> List[str]:
    ranked = rank_usernames(pivots)

    if budget <= 0:
        # Only a username no pivot ever tied to a site goes unchecked; one that
        # names a site elsewhere is still reached by that named check.
        routed = {p.username.lower() for p in pivots if p.site}
        unreachable = sorted({p.username for p in pivots if p.username.lower() not in routed})
        print(
            f"{Fore.YELLOW}[!] Username sweep off β€” checking only the sites pivots "
            f"named.{Style.RESET_ALL}"
        )
        if unreachable:
            print(
                f"{Fore.YELLOW}[!] {len(unreachable)} pivot username(s) name no site "
                f"({', '.join(unreachable)}) and are not checked{Style.RESET_ALL}"
            )
        return []

    usernames = ranked[:budget]
    deferred = ranked[len(usernames) :]
    if deferred:
        print(
            f"{Fore.YELLOW}[!] Not sweeping {len(deferred)} username(s) "
            f"({', '.join(deferred)}) β€” raise --cross-sweep{Style.RESET_ALL}"
        )
    return usernames


def _email_targets(
    ranked: List[RankedEmail], budget: int, modules: Optional[List[ModuleType]]
) -> List[RankedEmail]:
    if modules is not None and not modules:
        if ranked:
            print(
                f"{Fore.YELLOW}[!] The -m/-c restriction names no email module, so "
                f"no address is scanned.{Style.RESET_ALL}"
            )
        return []

    if budget <= 0:
        if ranked:
            print(
                f"{Fore.YELLOW}[!] No sweep budget left for {len(ranked)} address(es) "
                f"β€” raise --cross-sweep{Style.RESET_ALL}"
            )
        return []

    taken = ranked[:budget]
    deferred = ranked[len(taken) :]
    if deferred:
        print(
            f"{Fore.YELLOW}[!] Not scanning {len(deferred)} address(es) "
            f"({', '.join(entry.email for entry in deferred)}) β€” raise "
            f"--cross-sweep{Style.RESET_ALL}"
        )
    return taken


def _print_emails(ranked: List[RankedEmail]) -> None:
    print(f"{Fore.GREEN}[+] {len(ranked)} address(es) extracted{Style.RESET_ALL}")
    for entry in ranked:
        color = _CONFIDENCE_COLOR[entry.confidence]
        print(
            f"  {color}{entry.confidence.value:<12}{Style.RESET_ALL}"
            f"{entry.email:<32} {Fore.WHITE}{', '.join(entry.sources)}{Style.RESET_ALL}"
        )


def _print_pivots(pivots: List[Pivot]) -> None:
    print(f"{Fore.GREEN}[+] {len(pivots)} pivot(s) extracted{Style.RESET_ALL}")
    for pivot in pivots:
        tag = f"[{pivot.kind.value}]"
        print(
            f"  {Fore.CYAN}{tag:<11}{Style.RESET_ALL}"
            f"{pivot.username:<24} {(pivot.site or '(any site)'):<16} "
            f"{Fore.WHITE}{pivot.origin}{Style.RESET_ALL}"
        )


def _named_targets(
    pivots: Iterable[Pivot],
    swept: Set[str],
    checked: Set[Tuple[str, str]],
    configs: ScanConfig,
    scope: Optional[List[ModuleType]] = None,
) -> Dict[str, List[ModuleType]]:
    """Modules to check for pivots whose username was not swept.

    A swept username already ran against every module, so only the pivots left
    over need their one named site checked.
    """
    # Grouped case-insensitively, matching how `swept` and `checked` compare:
    # two profiles can link the same account in different cases, and scanning it
    # once per casing is a duplicate request for one account. Pivots arrive
    # best-vouched first, so the first casing seen is the one worth reporting.
    sites_by_username: Dict[str, Set[str]] = {}
    casing: Dict[str, str] = {}
    for pivot in pivots:
        key = pivot.username.lower()
        if not pivot.site or key in swept or (pivot.site, key) in checked:
            continue
        casing.setdefault(key, pivot.username)
        sites_by_username.setdefault(key, set()).add(pivot.site)

    allowed = None if scope is None else {module.__name__ for module in scope}

    targets: Dict[str, List[ModuleType]] = {}
    for key, sites in sites_by_username.items():
        if allowed is not None:
            sites = {site for site in sites if site in allowed}
        username = casing[key]
        modules = [
            module
            for site in sorted(sites)
            for module in find_module(site, is_email=False, no_nsfw=configs.no_nsfw)
        ]
        if modules:
            targets[username] = modules
    return targets


def _tag(results: List[Result], pivots: Iterable[Pivot], username: str) -> List[Result]:
    """Record on each hit why its username was scanned.

    A username often arrives from several pivots at once; only the best-vouched
    class is reported, since that is the claim the scan rests on.
    """
    matching = [pivot for pivot in pivots if pivot.username.lower() == username.lower()]
    if not matching:
        return results

    best = min(pivot.kind.rank for pivot in matching)
    strongest = [pivot for pivot in matching if pivot.kind.rank == best]
    label = f"{strongest[0].kind.value} from {', '.join(sorted({p.origin for p in strongest}))}"

    for result in results:
        if result.is_found():
            result.update(extra={"pivot_source": label})
    return results


def _tag_emails(results: List[Result], entry: RankedEmail) -> List[Result]:
    """Record on each hit which profile published the address that found it."""
    label = f"address from {', '.join(entry.sources)}"
    for result in results:
        if result.is_found():
            result.update(extra={"pivot_source": label})
    return results


def _apply_confidence(
    prior: Iterable[Result],
    cross_results: Iterable[Result],
    pivots: Iterable[Pivot],
    email_ratings: Dict[str, Confidence],
) -> None:
    """Rate every hit, and record the rating on it.

    Scoring runs once the pass is over because the anchors come from its own
    confirmed hits β€” a sweep hit cannot be judged before the accounts it is
    judged against have been fetched.

    An account reached by scanning an address inherits that address's rating
    rather than being scored on its own metadata: the account is only as well
    tied to the target as the address that led to it, and an email module's
    verdict says nothing about who owns the mailbox.
    """
    named = {(p.site, p.username.lower()) for p in pivots if p.site}
    hits = [r for r in cross_results if r.is_found()]
    anchors = build_anchors(
        confirmed=[r for r in hits if _is_named(r, named)],
        emails=[str(r.username) for r in prior if r.is_email and r.username],
        urls=[p.url for p in pivots if p.url],
    )

    for result in hits:
        inherited = email_ratings.get(str(result.username or "").lower()) if result.is_email else None
        rating = inherited or score(result, anchors, confirmed=_is_named(result, named))
        result.update(extra={"confidence": rating.value})


def _is_named(result: Result, named: Set[Tuple[str, str]]) -> bool:
    stem = module_stem(str(result.site_name or ""))
    return bool(stem) and (stem, str(result.username or "").lower()) in named


def _print_summary(prior: Iterable[Result], cross_results: Iterable[Result]) -> None:
    hits = [r for r in cross_results if r.is_found()]
    print(f"\n{Fore.CYAN}[i] Cross-scan complete.{Style.RESET_ALL}")
    print(f"  Accounts found: {len(hits)}")

    addresses = sorted({str(r.username) for r in hits if r.is_email and r.username})
    if addresses:
        print(f"  Reached via address: {', '.join(addresses)}")

    by_rating = {rating: _sites_rated(hits, rating) for rating in ORDER}
    for rating in ORDER:
        sites = by_rating[rating]
        if not sites:
            continue
        color = _CONFIDENCE_COLOR[rating]
        print(f"    {color}{rating.value:<12}{Style.RESET_ALL}{len(sites):>4}  {rating.explanation}")

    for rating in (Confidence.CONFIRMED, Confidence.LIKELY, Confidence.CONFLICTING):
        sites = by_rating[rating]
        if sites:
            color = _CONFIDENCE_COLOR[rating]
            print(f"\n  {color}{rating.value}:{Style.RESET_ALL} {', '.join(sites)}")

    prior_sites = {str(r.site_name).lower() for r in prior if r.is_found() and r.site_name}
    new_sites = sorted(
        {
            str(r.site_name)
            for r in hits
            if r.site_name and str(r.site_name).lower() not in prior_sites
        }
    )
    if not new_sites:
        print(f"\n  {Fore.YELLOW}No sites beyond the first pass.{Style.RESET_ALL}")
        return
    print(f"\n  {Fore.GREEN}New sites the first pass missed ({len(new_sites)}):{Style.RESET_ALL}")
    print(f"    {', '.join(new_sites)}")


def _sites_rated(hits: Iterable[Result], rating: Confidence) -> List[str]:
    return sorted(
        f"{r.site_name} ({r.username})"
        for r in hits
        if r.extra.get("confidence") == rating.value
    )