otacon 1.0.0__py3-none-any.whl

otacon/__init__.py

@@ -0,0 +1,11 @@
+"""Otacon — domain impersonation detector.
+
+A toolkit for detecting typosquatting, homoglyph attacks and combosquatting.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("otacon")
+except PackageNotFoundError:
+    __version__ = "dev"

otacon/__main__.py

@@ -0,0 +1,3 @@
+from otacon.cli import app
+
+app()

otacon/_asyncutils.py

@@ -0,0 +1,35 @@
+"""Async utilities — event loop compatibility and concurrent execution."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from collections.abc import Coroutine
+from typing import Any, TypeVar
+
+__all__ = ["run_async"]
+
+T = TypeVar("T")
+
+# Windows ProactorEventLoop raises ConnectionResetError (WinError 10054) on
+# normal HTTP connection teardowns. SelectorEventLoop doesn't have this issue.
+# Python 3.12+ exposes loop_factory on asyncio.run(); older versions need the
+# now-deprecated set_event_loop_policy path.
+_WIN_LOOP_FACTORY: type[asyncio.AbstractEventLoop] | None = None
+if sys.platform == "win32":
+    if sys.version_info >= (3, 12):
+        _WIN_LOOP_FACTORY = asyncio.SelectorEventLoop
+    else:
+        asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+
+def run_async(coro: Coroutine[Any, Any, T]) -> T:
+    """Run an async coroutine with platform-appropriate event loop configuration.
+
+    On Windows, uses SelectorEventLoop to avoid ConnectionResetError on HTTP teardowns.
+    On Python 3.12+, uses loop_factory parameter; on older versions relies on
+    set_event_loop_policy configuration.
+    """
+    if _WIN_LOOP_FACTORY is not None:
+        return asyncio.run(coro, loop_factory=_WIN_LOOP_FACTORY)  # type: ignore[call-arg]
+    return asyncio.run(coro)

otacon/_scanner.py

@@ -0,0 +1,101 @@
+"""The shared scan loop — the single place that drives the resolver over a variant set.
+
+Every entry point needs the same pipeline: generate permutations, check them
+concurrently, score each result and collect the registered ones into a report.
+The only thing that actually differs between callers is whether a live progress
+view is drawn, so that is a flag here rather than a reason to keep separate
+copies of the loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import AsyncExitStack
+
+from rich.console import Console, Group
+from rich.live import Live
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskID,
+    TextColumn,
+    TimeElapsedColumn,
+)
+
+from . import permutations, reporters, scoring
+from .models import DomainResult, ScanReport
+from .resolver import Resolver
+
+_HIJACK_WARNING = (
+    "[warn]⚠  Your DNS resolver answers nonexistent domains (NXDOMAIN hijacking)."
+    " Hijacked answers were discarded; consider scanning with a clean resolver"
+    " (e.g. 1.1.1.1).[/warn]"
+)
+
+
+def _build_progress(console: Console) -> Progress:
+    """Builds the scan progress bar: spinner, label, bar, counter, elapsed time."""
+    return Progress(
+        SpinnerColumn(style="brand"),
+        TextColumn("[field]{task.description}"),
+        BarColumn(complete_style="brand", finished_style="ok"),
+        TextColumn("[muted]{task.completed}/{task.total}"),
+        TimeElapsedColumn(),
+        console=console,
+    )
+
+
+async def run_scan(
+    target: str,
+    concurrency: int,
+    check_http: bool,
+    console: Console,
+    exclude: set[str] | None = None,
+    weights: scoring.ScoringWeights | None = None,
+    show_progress: bool = True,
+) -> ScanReport:
+    """Scans every permutation of *target* and returns the scored report.
+
+    With *show_progress* the run streams registered hits into a live table above
+    a progress bar; without it the identical loop runs silently — which is what
+    ``--quiet`` needs, since there stdout is reserved for the JSON report.
+    """
+    perms = permutations.generate(target, exclude=exclude)
+    report = ScanReport(target=target, total_permutations=len(perms))
+    if not perms:
+        return report
+
+    hits: list[DomainResult] = []
+    progress = _build_progress(console) if show_progress else None
+
+    async with AsyncExitStack() as stack:
+        live: Live | None = None
+        task_id: TaskID | None = None
+        if progress is not None:
+            task_id = progress.add_task("Checking variants", total=len(perms))
+            live = stack.enter_context(
+                Live(progress, console=console, refresh_per_second=4, transient=True)
+            )
+        # Entered after Live so the spinner already covers the resolver's own
+        # start-up work (it fetches the target's page title on entry).
+        resolver = await stack.enter_async_context(
+            Resolver(concurrency=concurrency, check_http=check_http, target=target)
+        )
+
+        for coro in asyncio.as_completed([resolver.check_one(p) for p in perms]):
+            result = await coro
+            scored = scoring.score(result, target, weights, resolver.target_title)
+            report.results.append(scored)
+            if progress is not None and task_id is not None:
+                progress.advance(task_id)
+            if scored.is_registered:
+                hits.append(scored)
+                if live is not None and progress is not None:
+                    live.update(Group(progress, reporters.build_live_table(hits, target)))
+
+        report.dns_hijack_detected = resolver.dns_hijack_detected
+
+    if report.dns_hijack_detected:
+        console.print(_HIJACK_WARNING)
+    return report

otacon/_validate.py

@@ -0,0 +1,146 @@
+"""Shared input validators — keep untrusted strings from reaching the network or filesystem.
+
+Centralised here so the CLI, interactive mode, and the resolver all enforce the
+same rules instead of each module rolling its own.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+from urllib.parse import urlparse
+
+# RFC 1035-ish: labels are 1..63 chars of [a-z0-9-], must not start/end with '-'.
+# We allow uppercase too (normalised later) and ACE/punycode labels (xn--...).
+# Total length cap at 253 octets per RFC. Reject anything with whitespace, NULs,
+# or directory separators outright — none belong in a domain.
+_LABEL_RE = re.compile(r"^(?!-)[A-Za-z0-9-]{1,63}(?<!-)$")
+
+# Windows reserved device names — case-insensitive, with or without extension.
+_WIN_RESERVED = {
+    "CON",
+    "PRN",
+    "AUX",
+    "NUL",
+    *(f"COM{i}" for i in range(1, 10)),
+    *(f"LPT{i}" for i in range(1, 10)),
+}
+
+
+def normalize_domain(value: str) -> str:
+    """Canonicalises a domain string for validation and comparison.
+
+    Trims surrounding whitespace, lowercases, drops a leading ``www.``, then
+    strips a trailing root dot. Centralised so every entry point (CLI,
+    interactive mode, permutation exclusions) normalises identically instead of
+    re-deriving the chain per call site.
+
+    Whitelist entries go through the same ``www.`` stripping as targets: they are
+    only ever compared against permutation output, and no technique emits a
+    ``www.``-prefixed FQDN (``_www_merge`` produces ``wwwexample``), so keeping
+    the prefix would make ``--exclude www.example.net`` match nothing at all.
+    """
+    return value.strip().lower().removeprefix("www.").rstrip(".")
+
+
+def is_valid_domain(domain: str) -> bool:
+    """True when *domain* is a syntactically plausible FQDN.
+
+    Rejects: empty, >253 chars, control chars / whitespace, bare IPs,
+    schemes, paths, or anything not RFC 1035-ish per-label.
+    """
+    if not domain or len(domain) > 253:
+        return False
+    if any(c.isspace() or ord(c) < 0x20 for c in domain):
+        return False
+    if "/" in domain or "\\" in domain or "@" in domain or ":" in domain:
+        return False
+    # Bare IPs are not impersonation targets.
+    try:
+        ipaddress.ip_address(domain)
+        return False
+    except ValueError:
+        pass
+    labels = domain.rstrip(".").split(".")
+    if len(labels) < 2:
+        return False
+    return all(_LABEL_RE.match(label) for label in labels)
+
+
+def first_safe_ip(ips: list[str]) -> str | None:
+    """Returns the first address in *ips* that is safe to connect to, or None.
+
+    "Safe" excludes private/loopback/link-local (which covers cloud metadata
+    endpoints)/multicast/reserved/unspecified ranges. Any unsafe address in
+    *ips* poisons the whole batch — a host answering with a mix of public and
+    internal addresses is itself a DNS-rebinding-style red flag, not just a
+    case of "pick the good one and ignore the rest".
+
+    Used by the resolver's HTTP/TLS probing, which connects to
+    attacker-influenced hosts and must not let a hostile DNS answer route
+    the connection at an internal service.
+    """
+    safe_ip: str | None = None
+    for ip_str in ips:
+        try:
+            ip = ipaddress.ip_address(ip_str)
+        except ValueError:
+            continue
+        if (
+            ip.is_private
+            or ip.is_loopback
+            or ip.is_link_local
+            or ip.is_multicast
+            or ip.is_reserved
+            or ip.is_unspecified
+        ):
+            return None
+        if safe_ip is None:
+            safe_ip = ip_str
+    return safe_ip
+
+
+def parse_redirect(url: str) -> tuple[str, str] | None:
+    """Splits a ``Location`` header into ``(hostname, scheme)``, or None if unparseable.
+
+    *hostname* comes back lowercased with the root dot stripped, and is ``""``
+    for a relative Location (``/login``); *scheme* is ``""`` when absent.
+
+    A Location header is verbatim attacker-controlled output from a lookalike
+    host, and ``urlparse`` raises ValueError on a malformed IPv6 authority
+    (``http://[evil``) rather than degrading. Every consumer goes through here
+    so one hostile redirect cannot take down a scan, a score, or a report.
+    """
+    try:
+        parsed = urlparse(url)
+    except ValueError:
+        return None
+    return (parsed.hostname or "").lower().rstrip("."), parsed.scheme
+
+
+def safe_relative_path(filename: str, base: str | None = None) -> str | None:
+    """Returns a resolved path string when *filename* is safely inside *base* (CWD by default).
+
+    Refuses: absolute paths, parent-dir escapes, Windows reserved device names,
+    NUL bytes, and anything that resolves outside *base*. Returns None on rejection.
+    """
+    from pathlib import Path
+
+    if not filename or "\x00" in filename:
+        return None
+    # Reject Windows-style drive letters cross-platform (Path.drive is empty on POSIX).
+    if re.match(r"^[A-Za-z]:", filename):
+        return None
+    candidate = Path(filename)
+    if candidate.is_absolute() or candidate.drive:
+        return None
+    stem = candidate.name.split(".")[0].upper()
+    if stem in _WIN_RESERVED:
+        return None
+    base_path = Path(base).resolve() if base else Path.cwd().resolve()
+    resolved = (base_path / candidate).resolve()
+    try:
+        resolved.relative_to(base_path)
+    except ValueError:
+        return None
+    return str(resolved)