umbermark-cli 1.0.0rc1__py3-none-any.whl

umbermark/core/external/ownership.py

@@ -0,0 +1,607 @@
+"""Target-ownership verification for the external scanner (UMBR-26).
+
+Active probing (port checks) may only run against a host the requester has
+proven they control. Proof is a random token published at the target:
+
+  * HTTP file ``/.well-known/umbermark-verify.txt`` containing the token
+    (https first, then plain http as a fallback), fetched from EACH resolved IP
+    separately. Only IPs that themselves serve the file are "proven" and may be
+    port-probed (strict model).
+  * DNS TXT ``umbermark-verify=<token>`` on ``<host>`` or ``_umbermark.<host>``
+    proves control of the NAME only. It is recorded but unlocks nothing, since a
+    name can be pointed at a server the requester does not run.
+
+IP-literal targets have no DNS name; the file on the IP itself is the only proof.
+
+This module is pure network/parse logic with no DB access (``core`` ships in the
+slim CLI package). Everything that touches the network is injectable so tests
+never leave the box.
+
+SSRF posture for the HTTP fetch: resolve the name ourselves, refuse the request
+if ANY resolved address is non-public, then connect to the vetted IP (pinned, so
+DNS rebinding cannot swap it afterwards). Redirects are never followed, the body
+is size-capped, and timeouts are tight.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import http.client
+import ipaddress
+import re
+import secrets
+import socket
+import ssl
+import struct
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+from umbermark.core.crypto import hash_with_pepper
+
+TOKEN_PREFIX = "umbermark-verify="
+WELL_KNOWN_PATH = "/.well-known/umbermark-verify.txt"
+MAX_BODY_BYTES = 2048
+HTTP_TIMEOUT = 1.5  # per ATTEMPT cap (see fetch_well_known)
+MAX_FETCH_IPS = 4
+DNS_TIMEOUT = 3.0
+DEFAULT_RESOLVERS = ("1.1.1.1", "8.8.8.8")
+
+_TOKEN_RE = re.compile(r"umbermark-verify=([A-Za-z0-9_\-]{16,128})")
+_BARE_TOKEN_RE = re.compile(r"^[A-Za-z0-9_\-]{16,128}$")
+
+
+# ---------------------------------------------------------------------------
+# Tokens
+# ---------------------------------------------------------------------------
+
+
+def generate_token() -> str:
+    return secrets.token_urlsafe(24)
+
+
+def hash_token(token: str) -> str:
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+def normalize_target(host: str) -> str:
+    """Canonical form used to bind a verification to exactly one target."""
+    h = host.strip().lower().rstrip(".")
+    if h.startswith("[") and h.endswith("]"):
+        h = h[1:-1]
+    return h
+
+
+def is_ip_literal(host: str) -> bool:
+    try:
+        ipaddress.ip_address(normalize_target(host))
+        return True
+    except ValueError:
+        return False
+
+
+def extract_candidates(text: str) -> list[str]:
+    """Token candidates from a TXT value or a .well-known file body."""
+    found = _TOKEN_RE.findall(text)
+    stripped = text.strip()
+    if _BARE_TOKEN_RE.match(stripped):
+        found.append(stripped)
+    return found
+
+
+def token_matches(text: str, token_hash: str) -> bool:
+    return any(
+        hmac.compare_digest(hash_token(c), token_hash) for c in extract_candidates(text)
+    )
+
+
+# ---------------------------------------------------------------------------
+# SSRF guard
+# ---------------------------------------------------------------------------
+
+_BLOCKED_NETS = [
+    ipaddress.ip_network(n)
+    for n in (
+        "0.0.0.0/8",
+        "10.0.0.0/8",
+        "100.64.0.0/10",
+        "127.0.0.0/8",
+        "169.254.0.0/16",  # link-local incl. cloud metadata 169.254.169.254
+        "172.16.0.0/12",
+        "192.0.0.0/24",
+        "192.168.0.0/16",
+        "198.18.0.0/15",
+        "224.0.0.0/4",
+        "240.0.0.0/4",
+        "::/128",
+        "::1/128",
+        "fc00::/7",
+        "fe80::/10",
+        "ff00::/8",
+    )
+]
+
+
+def is_public_ip(ip: str) -> bool:
+    try:
+        addr = ipaddress.ip_address(ip)
+    except ValueError:
+        return False
+    if isinstance(addr, ipaddress.IPv6Address) and addr.ipv4_mapped is not None:
+        addr = addr.ipv4_mapped
+    if any(addr in net for net in _BLOCKED_NETS):
+        return False
+    return addr.is_global
+
+
+class BlockedTarget(Exception):
+    """Target resolves to (or is) a non-public address."""
+
+
+# ---------------------------------------------------------------------------
+# Network path (UMBR-65): see the internet the way an outside observer does
+# ---------------------------------------------------------------------------
+#
+# Two facts of the production host make a naive scan of a target that lives on
+# the SAME server come back empty:
+#
+#   1. The host's resolver answers its own hostname from /etc/hosts
+#      (``<hostname> -> 127.0.1.1``); the SSRF guard then blocks the target.
+#      Fix: resolve scan targets through public resolvers (``SCAN_RESOLVERS``),
+#      i.e. ask what the internet sees, not what this box believes.
+#   2. Rootless podman (pasta) gives the container namespace the host's own
+#      public IP, so a connect to that IP never leaves the namespace. Fix: dial
+#      the host through pasta's host mapping (``SCANNER_HAIRPIN_ADDR``) instead.
+#
+# The hairpin path lands on the host via loopback, which the host firewall
+# accepts for EVERY port -- so it would show listeners the internet can't reach
+# (e.g. sshd on 22). Only the ports that really are public on this host
+# (``SCANNER_SELF_PUBLIC_PORTS``) are dialled; any other port fails like a
+# filtered one, which is exactly what an outside observer sees. All of this is
+# off until configured, and none of it touches the ownership gate.
+
+_scan_resolvers: tuple[str, ...] = ()
+_self_ips: frozenset[str] = frozenset()
+_hairpin_addr: str = ""
+_self_public_ports: frozenset[int] = frozenset()
+
+
+class SelfPortFiltered(OSError):
+    """A port on the scanner's own host that is not reachable from outside."""
+
+
+def _canon_ip(ip: str) -> str:
+    try:
+        return str(ipaddress.ip_address(ip))
+    except ValueError:
+        return ip
+
+
+def configure_network(
+    *,
+    resolvers: tuple[str, ...] = (),
+    self_ips: tuple[str, ...] = (),
+    hairpin_addr: str = "",
+    self_public_ports: tuple[int, ...] = (),
+) -> None:
+    """Install this process's network path (web + worker call it at boot)."""
+    global _scan_resolvers, _self_ips, _hairpin_addr, _self_public_ports
+    _scan_resolvers = tuple(resolvers)
+    _self_ips = frozenset(_canon_ip(i) for i in self_ips)
+    _hairpin_addr = hairpin_addr
+    _self_public_ports = frozenset(self_public_ports)
+
+
+def reset_network() -> None:
+    configure_network()
+
+
+def dial_address(ip: str, port: int) -> str:
+    """The address to connect to in order to reach vetted public ``ip:port``.
+
+    Identity for every target except this host's own IP (when a hairpin address
+    is configured): its public ports go via the hairpin, the rest raise
+    SelfPortFiltered so they read as filtered, as they do from outside.
+    """
+    if not _hairpin_addr or _canon_ip(ip) not in _self_ips:
+        return ip
+    if port in _self_public_ports:
+        return _hairpin_addr
+    raise SelfPortFiltered(f"port {port} on the scanner host is not public")
+
+
+def resolve_public_ips(host: str) -> list[str]:
+    """Resolve ``host``; raise BlockedTarget unless EVERY address is public."""
+    h = normalize_target(host)
+    if is_ip_literal(h):
+        ips = [h]
+    elif _scan_resolvers:
+        ips = sorted(set(udp_addr_lookup(h, _scan_resolvers)))
+    else:
+        try:
+            infos = socket.getaddrinfo(h, None, proto=socket.IPPROTO_TCP)
+        except OSError as exc:
+            raise BlockedTarget(f"cannot resolve {h}") from exc
+        ips = sorted({i[4][0] for i in infos})
+    if not ips:
+        raise BlockedTarget(f"no addresses for {h}")
+    for ip in ips:
+        if not is_public_ip(ip):
+            raise BlockedTarget(f"{h} resolves to non-public address")
+    return ips
+
+
+# ---------------------------------------------------------------------------
+# HTTP .well-known fetch
+# ---------------------------------------------------------------------------
+
+Fetcher = Callable[[str], dict[str, str]]
+
+
+def _fetch_one(
+    host: str,
+    ip: str,
+    port: int,
+    use_tls: bool,
+    timeout: float,
+    verify_tls: bool,
+) -> Optional[str]:
+    """One fetch attempt. ``timeout`` is a hard TOTAL budget for the whole
+    attempt (connect + TLS + headers + body), not a per-socket-op timeout: a
+    slow-drip server cannot hold the thread past it. A watchdog shuts the live
+    socket down at the deadline, which unblocks any pending recv."""
+    sock = socket.create_connection((dial_address(ip, port), port), timeout=timeout)
+    live = {"sock": sock}
+
+    def _kill() -> None:
+        try:
+            live["sock"].shutdown(socket.SHUT_RDWR)
+        except Exception:
+            pass
+
+    watchdog = threading.Timer(timeout, _kill)
+    watchdog.daemon = True
+    watchdog.start()
+    try:
+        if use_tls:
+            ctx = ssl.create_default_context()
+            if not verify_tls:
+                ctx.check_hostname = False
+                ctx.verify_mode = ssl.CERT_NONE
+            sock = ctx.wrap_socket(sock, server_hostname=host)
+            live["sock"] = sock
+        conn = http.client.HTTPConnection(host, port, timeout=timeout)
+        conn.sock = sock  # pinned to the vetted IP; http.client will not re-resolve
+        conn.request(
+            "GET",
+            WELL_KNOWN_PATH,
+            headers={
+                "Host": host,
+                "User-Agent": "Umbermark-Verify/1.0",
+                "Accept": "text/plain",
+                "Connection": "close",
+            },
+        )
+        resp = conn.getresponse()
+        if resp.status != 200:  # includes 3xx: redirects are never followed
+            return None
+        body = resp.read(MAX_BODY_BYTES + 1)
+        if len(body) > MAX_BODY_BYTES:
+            return None
+        return body.decode("utf-8", errors="replace")
+    finally:
+        watchdog.cancel()
+        try:
+            sock.close()
+        except Exception:
+            pass
+
+
+def fetch_well_known(
+    host: str,
+    *,
+    resolve: Callable[[str], list[str]] = resolve_public_ips,
+    attempts: tuple[tuple[int, bool], ...] = ((443, True), (80, False)),
+    timeout: float = HTTP_TIMEOUT,
+) -> dict[str, str]:
+    """``{ip: body}`` of ``/.well-known/umbermark-verify.txt`` per resolved IP.
+
+    The file is fetched from EACH resolved public IP separately (pinned), so the
+    caller learns exactly which addresses serve it. Failures (blocked address,
+    timeout, non-200, redirect, oversize) simply omit that IP.
+
+    ``timeout`` caps ONE attempt, so a firewall that drops 443 cannot starve the
+    port-80 fallback or later IPs. The total deadline is sized for 2 attempts per
+    IP and at most MAX_FETCH_IPS IPs, so the worst case stays bounded.
+    """
+    h = normalize_target(host)
+    try:
+        ips = resolve(h)
+    except Exception:  # BlockedTarget or resolver failure
+        return {}
+    ips = ips[:MAX_FETCH_IPS]
+    out: dict[str, str] = {}
+    deadline = time.monotonic() + timeout * len(attempts) * len(ips)
+    for ip in ips:
+        for port, use_tls in attempts:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0.05:
+                return out
+            try:
+                # Verify certs for names; an IP literal has no matching cert to check.
+                body = _fetch_one(
+                    h, ip, port, use_tls, min(remaining, timeout),
+                    verify_tls=not is_ip_literal(h),
+                )
+            except Exception:
+                continue
+            if body is not None:
+                out[ip] = body
+                break
+    return out
+
+
+# ---------------------------------------------------------------------------
+# DNS TXT lookup (raw UDP; no extra dependency)
+# ---------------------------------------------------------------------------
+
+TxtLookup = Callable[[str], list[str]]
+
+
+_QTYPE_A, _QTYPE_TXT, _QTYPE_AAAA = 1, 16, 28
+
+
+def build_query(name: str, qid: int, qtype: int) -> bytes:
+    header = struct.pack(">HHHHHH", qid, 0x0100, 1, 0, 0, 0)  # RD set, 1 question
+    qname = (
+        b"".join(
+            bytes([len(p)]) + p.encode("ascii") for p in name.rstrip(".").split(".")
+        )
+        + b"\x00"
+    )
+    return header + qname + struct.pack(">HH", qtype, 1)  # qtype, IN
+
+
+def build_txt_query(name: str, qid: int) -> bytes:
+    return build_query(name, qid, _QTYPE_TXT)
+
+
+def _skip_name(buf: bytes, off: int) -> int:
+    while True:
+        ln = buf[off]
+        if ln == 0:
+            return off + 1
+        if ln & 0xC0 == 0xC0:
+            return off + 2
+        off += 1 + ln
+
+
+def parse_txt_response(buf: bytes, qid: int) -> list[str]:
+    """TXT strings (a record's character-strings joined) from a DNS reply."""
+    try:
+        if len(buf) < 12:
+            return []
+        rid, flags, qd, an, _, _ = struct.unpack(">HHHHHH", buf[:12])
+        if rid != qid or flags & 0x000F:  # id mismatch or non-zero RCODE
+            return []
+        off = 12
+        for _ in range(qd):
+            off = _skip_name(buf, off) + 4
+        out: list[str] = []
+        for _ in range(an):
+            off = _skip_name(buf, off)
+            rtype, _cls, _ttl, rdlen = struct.unpack(">HHIH", buf[off : off + 10])
+            off += 10
+            rdata = buf[off : off + rdlen]
+            off += rdlen
+            if rtype != 16:
+                continue
+            parts, i = [], 0
+            while i < len(rdata):
+                ln = rdata[i]
+                parts.append(
+                    rdata[i + 1 : i + 1 + ln].decode("utf-8", errors="replace")
+                )
+                i += 1 + ln
+            out.append("".join(parts))
+        return out
+    except (struct.error, IndexError):
+        return []
+
+
+def udp_txt_lookup(
+    name: str,
+    resolvers: Optional[tuple[str, ...]] = None,
+    timeout: float = DNS_TIMEOUT,
+) -> list[str]:
+    """Single-shot UDP TXT query with a hard timeout. Empty list on any failure.
+
+    Default resolvers are the configured ``SCAN_RESOLVERS`` (UMBR-65: on the
+    production network UDP replies from 1.1.1.1/8.8.8.8 never arrive, so the
+    hard-coded defaults silently failed every DNS-TXT verification), else
+    DEFAULT_RESOLVERS.
+    """
+    if resolvers is None:
+        resolvers = _scan_resolvers or DEFAULT_RESOLVERS
+    try:
+        name.encode("ascii")
+    except UnicodeEncodeError:
+        return []
+    qid = secrets.randbelow(65536)
+    try:
+        query = build_txt_query(name, qid)
+    except Exception:
+        return []
+    for server in resolvers:
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+                s.settimeout(timeout)
+                s.sendto(query, (server, 53))
+                data, _ = s.recvfrom(4096)
+            return parse_txt_response(data, qid)
+        except Exception:
+            continue
+    return []
+
+
+def parse_addr_response(buf: bytes, qid: int) -> Optional[list[str]]:
+    """A/AAAA addresses from a DNS reply (UMBR-65).
+
+    Returns the addresses for a usable answer (NOERROR, possibly empty, or
+    NXDOMAIN -> []), and None when the reply is unusable (wrong id, not a
+    response, truncated with no answers, SERVFAIL/REFUSED, malformed) so the
+    caller can ask the next resolver. CNAME chains are followed by the
+    recursive resolver; every A/AAAA in the answer section is collected.
+    """
+    try:
+        if len(buf) < 12:
+            return None
+        rid, flags, qd, an, _, _ = struct.unpack(">HHHHHH", buf[:12])
+        if rid != qid or not flags & 0x8000:
+            return None
+        rcode = flags & 0x000F
+        if rcode == 3:  # NXDOMAIN: the name does not exist
+            return []
+        if rcode != 0:
+            return None
+        if flags & 0x0200 and an == 0:  # truncated, nothing usable
+            return None
+        off = 12
+        for _ in range(qd):
+            off = _skip_name(buf, off) + 4
+        out: list[str] = []
+        for _ in range(an):
+            off = _skip_name(buf, off)
+            rtype, _cls, _ttl, rdlen = struct.unpack(">HHIH", buf[off : off + 10])
+            off += 10
+            rdata = buf[off : off + rdlen]
+            if len(rdata) != rdlen:
+                return None
+            off += rdlen
+            if rtype == _QTYPE_A and rdlen == 4:
+                out.append(socket.inet_ntop(socket.AF_INET, rdata))
+            elif rtype == _QTYPE_AAAA and rdlen == 16:
+                out.append(socket.inet_ntop(socket.AF_INET6, rdata))
+        return out
+    except (struct.error, IndexError, ValueError, OSError):
+        return None
+
+
+def _udp_query(server: str, query: bytes, timeout: float) -> bytes:
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+        s.settimeout(timeout)
+        s.connect((server, 53))  # connected UDP: replies from anyone else are dropped
+        s.send(query)
+        return s.recv(4096)
+
+
+def udp_addr_lookup(
+    name: str,
+    resolvers: tuple[str, ...] = DEFAULT_RESOLVERS,
+    timeout: float = DNS_TIMEOUT,
+    query_fn: Callable[[str, bytes, float], bytes] = _udp_query,
+) -> list[str]:
+    """A + AAAA for ``name`` from the first resolver that gives a usable A answer.
+
+    Used instead of the host resolver for scan targets (UMBR-65), so the result
+    is what the public internet sees. A failed AAAA query just means no IPv6.
+    Empty list when nothing usable came back (the caller fails closed).
+    """
+    try:
+        name.encode("ascii")
+    except UnicodeEncodeError:
+        return []
+    for server in resolvers:
+        qid = secrets.randbelow(65536)
+        try:
+            v4 = parse_addr_response(
+                query_fn(server, build_query(name, qid, _QTYPE_A), timeout), qid
+            )
+        except Exception:
+            continue
+        if v4 is None:
+            continue
+        qid6 = secrets.randbelow(65536)
+        try:
+            v6 = parse_addr_response(
+                query_fn(server, build_query(name, qid6, _QTYPE_AAAA), timeout), qid6
+            )
+        except Exception:
+            v6 = None
+        return v4 + (v6 or [])
+    return []
+
+
+# ---------------------------------------------------------------------------
+# Orchestration
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class OwnershipResult:
+    verified: bool
+    method: str = ""  # "dns" | "http" | ""
+    detail: str = ""
+    # Public IPs that themselves served the verification file. Active checks
+    # later run only while EVERY resolved IP is inside this set.
+    ips: list[str] = field(default_factory=list)
+    # Resolved IPs that did NOT serve the file (no active checks for these).
+    unproven_ips: list[str] = field(default_factory=list)
+
+
+def verify_target_hash(target: str, pepper: str) -> str:
+    """Lookup key binding a verification to exactly one (normalized) target."""
+    return hash_with_pepper(f"ext-verify:{normalize_target(target)}", pepper)
+
+
+def check_ownership(
+    host: str,
+    token_hash: str,
+    *,
+    txt_lookup: TxtLookup = udp_txt_lookup,
+    fetch: Fetcher = fetch_well_known,
+    resolve: Callable[[str], list[str]] = resolve_public_ips,
+) -> OwnershipResult:
+    """Strict model: only a token fetched from an IP's own .well-known file puts
+    that IP in ``ips`` (and so unlocks active checks). DNS TXT proves control of
+    the NAME only; it is recorded (verified=True, method "dns") but ``ips`` stays
+    empty because a name can be pointed at someone else's server."""
+    h = normalize_target(host)
+    try:
+        resolved = resolve(h)
+    except Exception:
+        return OwnershipResult(
+            False, "", "The host does not resolve to a public address."
+        )
+    dns_ok = False
+    if not is_ip_literal(h):
+        for name in (h, f"_umbermark.{h}"):
+            try:
+                records = txt_lookup(name)
+            except Exception:
+                records = []
+            if any(token_matches(r, token_hash) for r in records):
+                dns_ok = True
+                break
+    bodies = fetch(h) or {}
+    file_ips = sorted(ip for ip, b in bodies.items() if token_matches(b, token_hash))
+    if file_ips:
+        return OwnershipResult(
+            True, "http", "verification file found", ips=file_ips,
+            unproven_ips=sorted(set(resolved) - set(file_ips)),
+        )
+    if dns_ok:
+        return OwnershipResult(
+            True, "dns", "TXT record found", unproven_ips=sorted(resolved)
+        )
+    if is_ip_literal(h):
+        return OwnershipResult(
+            False, "", f"No matching token at http(s)://{h}{WELL_KNOWN_PATH}."
+        )
+    return OwnershipResult(
+        False,
+        "",
+        "No matching DNS TXT record or .well-known file found yet. "
+        "DNS changes can take a few minutes to propagate.",
+    )

umbermark/core/external/probe.py

@@ -0,0 +1,103 @@
+"""Network probe abstraction for the external scanner.
+
+`ExternalProbe` is to Tier-1 what `CommandRunner` is to Tier-3: the swappable
+seam the checks run against. `FakeProbe` is the test double; `SocketProbe` (a
+real socket implementation) is added in a later slice.
+
+Every capability is optional and best-effort: a probe that cannot answer (host
+down, port filtered, handshake failed) returns a falsy value (`False`/`None`)
+rather than raising, so a single unreachable service yields SKIP/PASS — never a
+crashed scan.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional, Protocol
+
+
+@dataclass
+class SshAlgorithms:
+    """Algorithms an SSH server advertises in its pre-auth KEXINIT.
+
+    Read before any authentication — purely the public handshake offer, the
+    same data `ssh -Q` / `nmap --script ssh2-enum-algos` would surface.
+    """
+
+    kex: list[str] = field(default_factory=list)
+    ciphers: list[str] = field(default_factory=list)
+    macs: list[str] = field(default_factory=list)
+    host_keys: list[str] = field(default_factory=list)
+
+
+@dataclass
+class TlsInfo:
+    """What the TLS handshake reveals — all visible without authenticating.
+
+    ``protocols`` is every TLS/SSL version the endpoint agrees to negotiate;
+    ``days_until_expiry`` is negative once the leaf cert has expired.
+    ``unprobed`` lists versions the *scanner's own* TLS stack could not offer
+    (e.g. TLS 1.0/1.1 under an OpenSSL 3 build that refuses them), so whether
+    the server accepts them is unknown -- never read that as "not offered".
+    ``cert_readable`` is False when the leaf certificate could not be obtained
+    or parsed; ``days_until_expiry`` / ``self_signed`` are then meaningless.
+    ``chain_trusted`` is the result of a verifying handshake against a public
+    trust store (UMBR-40): True = chain verified, False = verification failed
+    (``trust_error`` says why), None = could not be checked -- unknown, which
+    is never read as trusted.
+    """
+
+    protocols: list[str] = field(default_factory=list)
+    days_until_expiry: int = 0
+    self_signed: bool = False
+    unprobed: list[str] = field(default_factory=list)
+    cert_readable: bool = True
+    chain_trusted: Optional[bool] = None
+    trust_error: str = ""
+
+
+class ExternalProbe(Protocol):
+    def tcp_connect(self, port: int, timeout: float = 3.0) -> bool:
+        """True if a TCP connection to ``port`` on the target succeeds."""
+        ...
+
+    def ssh_algorithms(
+        self, port: int = 22, timeout: float = 3.0
+    ) -> Optional[SshAlgorithms]:
+        """Algorithms offered in the SSH KEXINIT, or None if unreadable."""
+        ...
+
+    def tls_info(self, port: int = 443, timeout: float = 3.0) -> Optional[TlsInfo]:
+        """TLS protocols + leaf-cert facts, or None if no TLS service answers."""
+        ...
+
+    def http_headers(
+        self, port: int = 443, tls: bool = True, timeout: float = 3.0
+    ) -> Optional[dict]:
+        """Response headers (lowercased keys), or None if no HTTP service answers."""
+        ...
+
+
+@dataclass
+class FakeProbe:
+    """Test double — a programmable set of open ports and canned probe results."""
+
+    open_ports: set[int] = field(default_factory=set)
+    ssh_algos: Optional[SshAlgorithms] = None
+    tls: Optional[TlsInfo] = None
+    headers: Optional[dict] = None
+
+    def tcp_connect(self, port: int, timeout: float = 3.0) -> bool:
+        return port in self.open_ports
+
+    def ssh_algorithms(
+        self, port: int = 22, timeout: float = 3.0
+    ) -> Optional[SshAlgorithms]:
+        return self.ssh_algos
+
+    def tls_info(self, port: int = 443, timeout: float = 3.0) -> Optional[TlsInfo]:
+        return self.tls
+
+    def http_headers(
+        self, port: int = 443, tls: bool = True, timeout: float = 3.0
+    ) -> Optional[dict]:
+        return self.headers