umbermark-cli 1.0.0__py3-none-any.whl

umbermark/core/access.py

@@ -0,0 +1,896 @@
+"""AccessContext: *how can an attacker reach this host and how do they authenticate?*
+
+Hardening verdicts are only meaningful relative to exposure. "SSH password
+auth enabled" is critical on an internet-facing box and a minor note on a box
+whose only SSH path is a VPN overlay. This module builds one `AccessContext`
+per scan that checks consult to scale severity (and to avoid advice such as
+"open port 22" that would make things worse).
+
+The context is built by a registry of *detectors* (see `DETECTORS`). Each
+detector declares the collector commands it needs; the builder issues all of
+them up front, once per runner (cached on the runner), and then runs the
+detectors in order. Because `detect_platform` builds the context, the
+Tier-2 capture script (which enumerates commands from `detect_platform` +
+the checks) includes every command, and bundle replay never asks for one
+that was not captured. `tests/unit/test_capture_enumeration_guard.py`
+enforces this.
+
+Dimensions currently modelled
+-----------------------------
+* network reachability of SSH: PUBLIC / OVERLAY_ONLY (VPN overlay) /
+  PRIVATE_ONLY / UNKNOWN
+* ssh authentication strength: PASSWORD_POSSIBLE / KEY_ONLY / KEY_PLUS_2FA /
+  CA_CERTS / UNKNOWN
+* privilege-escalation authentication: SUDO_LOCAL_PASSWORD /
+  SUDO_DIRECTORY (PAM sss/krb5/winbind/ldap) / NONE (pam_permit) / UNKNOWN
+* local account status (usable password vs locked vs no login shell). The
+  account command prints one character of the shadow password field, never
+  a hash.
+
+Reachability honesty
+--------------------
+"No public address on any interface" does NOT prove a host is private: cloud
+providers commonly map a public IP 1:1 onto a private NIC address (the public
+address is never on the interface). So `PRIVATE_ONLY` is only chosen with
+corroborating evidence (a firewall that drops the port from every public
+interface, or sshd bound only to private/loopback addresses). Absent that the
+answer is UNKNOWN, and checks do not reduce severity for UNKNOWN.
+
+FUTURE detectors (not implemented; each would add collector commands and a
+detector, nothing else needs to change)
+------------------------------------------------------------------------
+* SSH certificate authorities: TrustedUserCAKeys / AuthorizedPrincipals files
+* second factor in PAM: google-authenticator, Duo, pam_u2f, pam_oath
+* AllowUsers / AllowGroups / DenyUsers / Match blocks (per-user and
+  per-source auth overrides)
+* GSSAPI / Kerberos SSH authentication
+* cloud session managers: SSM, IAP, OS Login, Azure Bastion, serial console
+* ProxyJump-only bastion topologies (SSH reachable only from a jump host)
+* other overlays: WireGuard peer configs, ZeroTier, Nebula, OpenVPN routes
+* port knocking / single-packet authorisation
+* provider-side security groups and cloud firewalls (invisible from the host)
+* ip6tables / per-VRF / network-namespace firewalls
+"""
+from __future__ import annotations
+
+import ipaddress
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+
+from umbermark.core.check import Severity
+from umbermark.core.firewall import (
+    _DPORT_RE,
+    _NFT_COMMENT_RE,
+    _parse_port_spec,
+    Exposure,
+    Firewall,
+    classify_address,
+    is_loopback_iface,
+    is_overlay_iface,
+    sources_are_private,
+)
+from umbermark.core.ssh import CommandResult, CommandRunner
+
+
+class Reachability(Enum):
+    PUBLIC = "public"
+    OVERLAY_ONLY = "overlay-only"
+    PRIVATE_ONLY = "private-only"
+    UNKNOWN = "unknown"
+
+
+class SshAuth(Enum):
+    PASSWORD_POSSIBLE = "password-possible"
+    KEY_ONLY = "key-only"
+    KEY_PLUS_2FA = "key+2fa"
+    CA_CERTS = "ca-certs"
+    UNKNOWN = "unknown"
+
+
+class SudoAuth(Enum):
+    LOCAL_PASSWORD = "sudo-local-password"
+    DIRECTORY = "sudo-directory"
+    NONE = "none"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class Collector:
+    command: str
+    sudo: bool = False
+    timeout: float = 10.0
+
+
+@dataclass
+class Interface:
+    name: str
+    addrs: list[tuple[str, str]] = field(default_factory=list)  # (address, class)
+
+
+@dataclass
+class Account:
+    name: str
+    flag: str          # first char of the shadow password field ('!', '*', '$', '' ...)
+    shell: str
+
+    @property
+    def usable_password(self) -> bool:
+        return self.flag not in ("!", "*")
+
+    @property
+    def can_login(self) -> bool:
+        return bool(self.shell) and not self.shell.endswith(("nologin", "/false"))
+
+
+@dataclass
+class AccessContext:
+    raw: dict[str, CommandResult] = field(default_factory=dict)
+    interfaces: list[Interface] = field(default_factory=list)
+    firewall: Firewall = field(default_factory=Firewall)
+    listeners: list[tuple[str, int]] = field(default_factory=list)
+    listen_readable: bool = False
+    ssh_ports: tuple[int, ...] = (22,)
+    ssh_facts_readable: bool = False
+    ssh_password_sources: list[str] = field(default_factory=list)  # file:line where PasswordAuthentication yes
+    pam: dict[str, list[str]] = field(default_factory=dict)        # service -> auth lines
+    accounts: dict[str, Account] = field(default_factory=dict)
+    accounts_readable: bool = False
+    has_global_ipv6: bool | None = None   # None = interface data unreadable
+    dnat_ports: list[tuple[int, int]] = field(default_factory=list)
+    dnat_unknown: bool = False             # DNAT / port publishing seen, ports not determinable
+    dnat_evidence: list[str] = field(default_factory=list)
+    ssh_match_password: list[tuple[str, str]] = field(default_factory=list)  # (Match criteria, file:line)
+    reachability: Reachability = Reachability.UNKNOWN
+    reachability_note: str = "reachability not determined"
+    ssh_auth: SshAuth = SshAuth.UNKNOWN
+    ssh_auth_note: str = ""
+    sudo_auth: SudoAuth = SudoAuth.UNKNOWN
+    sudo_auth_note: str = ""
+
+    @property
+    def has_public_address(self) -> bool:
+        return any(c == "public" for i in self.interfaces if not is_overlay_iface(i.name)
+                   for _, c in i.addrs)
+
+    def dnat_suspect(self, port: int) -> bool:
+        """True if `port` may be reachable through DNAT / published-port forwarding,
+        which bypasses the INPUT chain, so an INPUT drop proves nothing for it."""
+        return self.dnat_unknown or any(lo <= port <= hi for lo, hi in self.dnat_ports)
+
+    def account(self, name: str) -> Account | None:
+        return self.accounts.get(name)
+
+
+# --------------------------------------------------------------------------- #
+# Collectors (strings are shared verbatim with the checks so the capture
+# enumerator deduplicates them)
+# --------------------------------------------------------------------------- #
+C_IP = Collector("ip -o addr show 2>/dev/null", timeout=5)
+C_NFT = Collector("nft list ruleset 2>/dev/null", sudo=True, timeout=5)
+C_IPT = Collector("iptables -S 2>/dev/null", sudo=True, timeout=5)
+C_UFW = Collector("ufw status 2>/dev/null", sudo=True, timeout=5)
+C_UFW_V = Collector("ufw status verbose 2>/dev/null", sudo=True, timeout=5)
+C_SS = Collector("ss -tln 2>/dev/null", sudo=True, timeout=10)
+C_SS_P = Collector("ss -tlnp 2>/dev/null", sudo=True, timeout=10)
+C_IP6T = Collector("ip6tables -S 2>/dev/null", sudo=True, timeout=5)
+C_IPT_NAT = Collector("iptables -t nat -S 2>/dev/null", sudo=True, timeout=5)
+# Docker with the legacy iptables backend while `iptables` is the nft front-end: the DOCKER chain
+# and DNAT rules live only in the legacy tables (UMBR-27). Absent binary -> rc != 0 -> ignored.
+# Gated on the table already being loaded: running iptables-legacy otherwise makes the kernel
+# autoload ip_tables/iptable_nat and create empty tables, which changes the host.
+# `sh -c '...'` keeps each a single simple command, so the runner's `sudo -n ` prefix covers the
+# grep AND iptables-legacy (a bare `a && b` would run only `a` as root and `b` would fail with
+# "you must be root", silently dropping the result for every non-root sudo user).
+C_IPT_LEGACY = Collector(
+    "sh -c 'grep -qx filter /proc/net/ip_tables_names 2>/dev/null && iptables-legacy -S 2>/dev/null'",
+    sudo=True, timeout=5)
+C_IPT_LEGACY_NAT = Collector(
+    "sh -c 'grep -qx nat /proc/net/ip_tables_names 2>/dev/null && iptables-legacy -t nat -S 2>/dev/null'",
+    sudo=True, timeout=5)
+C_SSHD = Collector("sshd -T 2>/dev/null", sudo=True, timeout=10)
+# Effective per-context sshd config (UMBR-27): `sshd -T` alone shows only the non-Match values.
+# Two contexts: root from a documentation-range address, and the first ordinary account
+# (uid 1000-59999 with a login shell). The second fails harmlessly (rc != 0, ignored) if no
+# such account exists or sshd is too old for -C.
+C_SSHD_ROOT = Collector("sshd -T -C user=root,host=x,addr=203.0.113.1 2>/dev/null", sudo=True, timeout=10)
+C_SSHD_USER = Collector(
+    "sshd -T -C \"user=$(awk -F: '$3>=1000 && $3<60000 && $7!~/(nologin|false)$/ {print $1; exit}' /etc/passwd),"
+    "host=x,addr=203.0.113.1\" 2>/dev/null",
+    sudo=True, timeout=10,
+)
+# File:line of PasswordAuthentication and Match lines (in order) from the main config and drop-ins.
+# `sshd -T` shows only the non-Match values; a Match block can switch passwords back on.
+# (Command string is unchanged on purpose: existing captured bundles are keyed by it.)
+C_SSHD_SRC = Collector(
+    "grep -rEin '^[[:space:]]*(Match[[:space:]]|PasswordAuthentication)' /etc/ssh/sshd_config /etc/ssh/sshd_config.d/ 2>/dev/null",
+    sudo=True, timeout=5,
+)
+# Same shape for the other ways a Match block can re-enable a password-type login (UMBR-27):
+# KbdInteractiveAuthentication (legacy ChallengeResponseAuthentication) and AuthenticationMethods.
+C_SSHD_SRC_EXTRA = Collector(
+    "grep -rEin '^[[:space:]]*(Match[[:space:]]|KbdInteractiveAuthentication|ChallengeResponseAuthentication|"
+    "AuthenticationMethods)' /etc/ssh/sshd_config /etc/ssh/sshd_config.d/ 2>/dev/null",
+    sudo=True, timeout=5,
+)
+C_PAM = Collector(
+    "grep -HE '^[[:space:]]*-?(auth|@include)' /etc/pam.d/sshd /etc/pam.d/sudo "
+    "/etc/pam.d/common-auth /etc/pam.d/system-auth 2>/dev/null",
+    sudo=True, timeout=5,
+)
+# Prints "<user> [<first char of shadow pw field>] <shell>". One character only:
+# '!' or '*' = locked/no password, '$' = a hash exists. NEVER the hash itself.
+C_ACCOUNTS = Collector(
+    "awk -F: 'NR==FNR{s[$1]=$7;next}{print $1, \"[\" substr($2,1,1) \"]\", s[$1]}' "
+    "/etc/passwd /etc/shadow 2>/dev/null",
+    sudo=True, timeout=5,
+)
+
+
+def _ok(ctx: AccessContext, col: Collector) -> str | None:
+    r = ctx.raw.get(col.command)
+    return r.stdout if (r is not None and r.ok) else None
+
+
+# --------------------------------------------------------------------------- #
+# Detectors
+# --------------------------------------------------------------------------- #
+class Detector:
+    name = ""
+    collectors: tuple[Collector, ...] = ()
+
+    def detect(self, ctx: AccessContext) -> None:  # pragma: no cover - interface
+        raise NotImplementedError
+
+
+_IP_RE = re.compile(r"^\d+:\s+(\S+?)(?:@\S+)?\s+inet6?\s+([0-9a-fA-F:.]+)/\d+")
+
+
+class InterfacesDetector(Detector):
+    name = "interfaces"
+    collectors = (C_IP,)
+
+    def detect(self, ctx: AccessContext) -> None:
+        out = _ok(ctx, C_IP) or ""
+        ifaces: dict[str, Interface] = {}
+        for line in out.splitlines():
+            m = _IP_RE.match(line.strip())
+            if not m:
+                continue
+            name, addr = m.group(1), m.group(2)
+            ifaces.setdefault(name, Interface(name)).addrs.append((addr, classify_address(addr)))
+        ctx.interfaces = list(ifaces.values())
+        if ifaces:
+            ctx.has_global_ipv6 = any(
+                ":" in a and c == "public"
+                for i in ifaces.values() if not is_overlay_iface(i.name) for a, c in i.addrs
+            )
+
+
+class FirewallDetector(Detector):
+    name = "firewall"
+    collectors = (C_NFT, C_IPT, C_IP6T, C_UFW, C_UFW_V)
+
+    def detect(self, ctx: AccessContext) -> None:
+        ufw = _ok(ctx, C_UFW_V)
+        if not ufw:
+            ufw = _ok(ctx, C_UFW)
+        public = [i.name for i in ctx.interfaces
+                  if not is_loopback_iface(i.name) and not is_overlay_iface(i.name)]
+        ctx.firewall = Firewall(
+            nft=_ok(ctx, C_NFT), iptables=_ok(ctx, C_IPT), ufw=ufw, public_ifaces=public,
+            ip6tables=_ok(ctx, C_IP6T), ipv6=ctx.has_global_ipv6,
+        )
+
+
+_WILDCARDS = ("0.0.0.0", "*", "[::]", "::")
+
+
+def parse_listeners(ss_output: str) -> list[tuple[str, int]]:
+    out: list[tuple[str, int]] = []
+    for line in ss_output.splitlines():
+        if not line.startswith("LISTEN"):
+            continue
+        cols = line.split()
+        if len(cols) < 4:
+            continue
+        host, _, port = cols[3].rpartition(":")
+        if not port.isdigit():
+            continue
+        host = host.strip("[]").split("%")[0] or "*"
+        out.append(("::" if host == "::" else host, int(port)))
+    return out
+
+
+class ListenDetector(Detector):
+    name = "listeners"
+    collectors = (C_SS,)
+
+    def detect(self, ctx: AccessContext) -> None:
+        out = _ok(ctx, C_SS)
+        if out and out.strip():
+            ctx.listeners = parse_listeners(out)
+            ctx.listen_readable = True
+
+
+_PROXY_PROCS = {"docker-proxy", "rootlessport"}
+_SS_USERS_RE = re.compile(r'\("([^"]+)"')
+
+
+class DnatDetector(Detector):
+    """Evidence that some ports are reachable via DNAT / published-port forwarding.
+
+    Docker, rootful podman and hand-written DNAT deliver traffic through
+    PREROUTING + FORWARD, so an INPUT-chain drop says nothing about those ports.
+    Rootless podman via pasta binds on the host and DOES traverse INPUT, so it is
+    deliberately not evidence. When DNAT exists but its ports cannot be
+    determined, every port is treated as suspect (dnat_unknown).
+    """
+
+    name = "dnat"
+    collectors = (C_IPT_NAT, C_IPT_LEGACY, C_IPT_LEGACY_NAT, C_SS_P)
+
+    def detect(self, ctx: AccessContext) -> None:
+        ev = ctx.dnat_evidence
+        for raw in (_ok(ctx, C_NFT) or "").splitlines():
+            line = _NFT_COMMENT_RE.sub(" ", raw).split("#", 1)[0]
+            if re.match(r"\s*chain\s+DOCKER\b", line):
+                ev.append("nft DOCKER chain")
+                ctx.dnat_unknown = True
+            if re.search(r"\bdnat\b", line):
+                ev.append("nft dnat rule")
+                mm = _DPORT_RE.search(line)
+                ports = _parse_port_spec(mm.group(3), {}) if mm else None
+                if ports:
+                    ctx.dnat_ports += ports
+                else:
+                    ctx.dnat_unknown = True
+        if re.search(r"^-N\s+DOCKER\b", _ok(ctx, C_IPT) or "", re.M):
+            ev.append("iptables DOCKER chain")
+            ctx.dnat_unknown = True
+        # Legacy-backend tables (same chain/DNAT evidence, labelled so reports show the source).
+        # When `iptables` is itself the legacy binary the output is byte-identical: skip it.
+        leg_f = _ok(ctx, C_IPT_LEGACY) or ""
+        leg_n = _ok(ctx, C_IPT_LEGACY_NAT) or ""
+        if leg_f and leg_f == (_ok(ctx, C_IPT) or ""):
+            leg_f = ""
+        if leg_n and leg_n == (_ok(ctx, C_IPT_NAT) or ""):
+            leg_n = ""
+        if re.search(r"^-N\s+DOCKER\b", leg_f, re.M) or re.search(r"^-N\s+DOCKER\b", leg_n, re.M):
+            ev.append("iptables-legacy DOCKER chain")
+            ctx.dnat_unknown = True
+        for label, text in (("iptables", _ok(ctx, C_IPT_NAT)), ("iptables-legacy", leg_n)):
+            self._scan_nat(ctx, label, text or "")
+        for line in (_ok(ctx, C_SS_P) or "").splitlines():
+            if not line.startswith("LISTEN"):
+                continue
+            if not _PROXY_PROCS & set(_SS_USERS_RE.findall(line)):
+                continue
+            cols = line.split()
+            port = cols[3].rpartition(":")[2] if len(cols) > 3 else ""
+            if port.isdigit():
+                ctx.dnat_ports.append((int(port), int(port)))
+                ev.append(f"port-publishing proxy listening on {port}")
+            else:
+                ctx.dnat_unknown = True
+
+    @staticmethod
+    def _scan_nat(ctx: AccessContext, label: str, text: str) -> None:
+        ev = ctx.dnat_evidence
+        for line in text.splitlines():
+            if re.search(r"-j\s+DNAT\b", line):
+                ev.append(f"{label} DNAT rule")
+                mm = re.search(r"--dport\s+([\d:]+)", line)
+                ports = _parse_port_spec(mm.group(1).replace(":", "-"), {}) if mm else None
+                if ports:
+                    ctx.dnat_ports += ports
+                else:
+                    ctx.dnat_unknown = True
+
+
+_PAM_DIRECTORY = re.compile(r"pam_(sss|krb5|winbind|ldap|ccreds)\b")
+_PAM_2FA = re.compile(r"pam_(google_authenticator|duo|u2f|oath|yubico|radius_auth)\b")
+
+
+_AUTH_RE = re.compile(r"^-?auth\s+(\[[^\]]*\]|\S+)\s+(\S+)")
+_INCLUDE_RE = re.compile(r"^(?:@include\s+(\S+)|-?auth\s+(?:include|substack)\s+(\S+))")
+
+
+def effective_auth_stack(pam: dict[str, list[str]], service: str,
+                         _seen: tuple[str, ...] = ()) -> list[tuple[str, str]]:
+    """Ordered (control, module) auth entries for `service`, following includes."""
+    out: list[tuple[str, str]] = []
+    for line in pam.get(service, []):
+        if line.startswith("#"):
+            continue
+        inc = _INCLUDE_RE.match(line)
+        if inc:
+            name = inc.group(1) or inc.group(2)
+            if name not in _seen and len(_seen) < 6:
+                out += effective_auth_stack(pam, name, _seen + (service,))
+            continue
+        m = _AUTH_RE.match(line)
+        if m:
+            out.append((m.group(1).lower(), m.group(2).rsplit("/", 1)[-1].lower()))
+    return out
+
+
+def classify_sudo_auth(stack: list[tuple[str, str]]) -> tuple[SudoAuth, str]:
+    """Walk sudo's effective auth stack in order.
+
+    * a directory module (sss/krb5/winbind/ldap) reached BEFORE any non-optional
+      pam_unix -> DIRECTORY;
+    * a non-optional pam_unix first -> LOCAL_PASSWORD (a directory module after
+      it is only a fallback, so local credentials remain in play);
+    * `sufficient` pam_permit (or required pam_permit with no real auth module)
+      -> NONE: sudo asks for nothing.
+
+    Limitation: `substack` lines are flattened, so a done/die inside a substack ends the whole
+    simulated walk rather than only the substack; a substacked file ending in
+    `sufficient pam_permit` followed by a required pam_unix in the parent can be over-reported
+    as NONE.
+    """
+    if not stack:
+        return SudoAuth.UNKNOWN, "sudo PAM auth stack not readable"
+    # First: can someone with NO valid credential get through? Simulate the whole stack with
+    # every real module failing (UMBR-27). Only then classify which backend is in play.
+    if _pam_permits_without_credentials(stack):
+        return SudoAuth.NONE, (
+            "sudo PAM stack lets a failed authentication through: a pam_permit is reachable "
+            "after the real authentication module fails, so no credential is actually required"
+        )
+    for control, module in stack:
+        if "pam_permit" in module:
+            continue
+        if _PAM_DIRECTORY.search(module):
+            return SudoAuth.DIRECTORY, f"sudo authenticates via a directory backend ({module})"
+        if "pam_unix" in module and control != "optional":
+            return SudoAuth.LOCAL_PASSWORD, "sudo authenticates against local accounts (pam_unix)"
+    return SudoAuth.UNKNOWN, "sudo PAM stack not recognised"
+
+
+# Linux-PAM simple controls expressed as [result=action ...] tables (pam.conf(5)).
+_PAM_SIMPLE = {
+    "required": {"success": "ok", "default": "bad"},
+    "requisite": {"success": "ok", "default": "die"},
+    "sufficient": {"success": "done", "default": "ignore"},
+    "optional": {"success": "ignore", "default": "ignore"},
+}
+_PAM_KV = re.compile(r"(\w+)=(\w+)")
+
+
+def _pam_actions(control: str) -> dict[str, str]:
+    control = control.strip()
+    if control.startswith("["):
+        return {k.lower(): v.lower() for k, v in _PAM_KV.findall(control)}
+    return _PAM_SIMPLE.get(control.lower(), _PAM_SIMPLE["optional"])
+
+
+# Ways a real module can fail (pam_sss answers user_unknown for a local account and
+# authinfo_unavail when the directory is offline), each simulated separately.
+_PAM_FAIL_CODES = ("auth_err", "user_unknown", "authinfo_unavail", "cred_insufficient", "maxtries")
+
+
+def _pam_walk(stack: list[tuple[str, str]], fail_code: str) -> bool:
+    """One libpam (pam_dispatch.c) auth-chain pass: pam_permit succeeds, pam_deny fails with
+    auth_err, real credential modules fail with `fail_code`, everything else is skipped.
+
+    State is (impression, status) as libpam keeps it: ok/done only take effect while
+    the impression is undefined (or positive with status still success) and they copy the
+    module's result into status, so `ok` on a failing module makes the stack fail. bad/die set
+    a negative impression. reset clears both. A `[...=N]` jump only skips N modules. A `done`
+    under a negative impression does not stop the walk (pam_dispatch.c only stops when the
+    impression is not negative), so a later `reset` can still revive the stack.
+    Starts failed (PAM_MUST_FAIL_CODE); True means the stack ends in PAM_SUCCESS.
+
+    Known limitation: substacks are flattened by effective_auth_stack, so a done/die inside a
+    substack ends the whole walk here, while libpam ends only the substack.
+    """
+    impression, ok = "undef", False          # ok == (status == PAM_SUCCESS)
+    i = 0
+    while i < len(stack):
+        control, module = stack[i]
+        i += 1
+        if "pam_permit" in module:
+            result = "success"
+        elif "pam_deny" in module:
+            result = "auth_err"
+        elif "pam_unix" in module or _PAM_DIRECTORY.search(module):
+            result = fail_code
+        else:
+            continue
+        acts = _pam_actions(control)
+        action = acts.get(result) or acts.get("default") or "bad"
+        if action == "ignore":
+            continue
+        if action == "reset":
+            impression, ok = "undef", False
+            continue
+        if action.isdigit():
+            i += int(action)                 # jump: no change to impression or status
+            continue
+        if action in ("bad", "die"):
+            if impression != "negative":
+                impression, ok = "negative", False
+            if action == "die":
+                return False
+            continue
+        # ok / done
+        if impression == "undef" or (impression == "positive" and ok):
+            impression, ok = "positive", result == "success"
+        if action == "done" and impression != "negative":
+            return ok
+    return ok
+
+
+def _pam_permits_without_credentials(stack: list[tuple[str, str]]) -> bool:
+    """True if some plausible credential failure still ends the stack in success (sudo with
+    no valid credential). Each failure code in _PAM_FAIL_CODES is simulated on the real
+    modules; one success is enough.
+
+    `[success=N]` jumps count entries in the flattened (include-expanded) stack, which
+    matches how distro stacks are written (the jump sits in the same file as its target).
+    """
+    return any(_pam_walk(stack, code) for code in _PAM_FAIL_CODES)
+
+
+class PamDetector(Detector):
+    """Sudo credential backend (local passwd vs directory vs none) from the PAM stacks."""
+
+    name = "pam"
+    collectors = (C_PAM,)
+
+    def detect(self, ctx: AccessContext) -> None:
+        r = ctx.raw.get(C_PAM.command)
+        # grep exits 2 when one of the (distro-specific) files is missing even
+        # though others matched, so trust stdout rather than the exit code.
+        text = r.stdout if r is not None else ""
+        for line in text.splitlines():
+            svc, sep, rest = line.partition(":")
+            rest = rest.strip()
+            if not sep or not rest or rest.startswith("#"):
+                continue
+            ctx.pam.setdefault(svc.rsplit("/", 1)[-1], []).append(rest)
+        ctx.sudo_auth, ctx.sudo_auth_note = classify_sudo_auth(effective_auth_stack(ctx.pam, "sudo"))
+
+
+def _sshd_value(text: str, key: str) -> str | None:
+    m = re.search(rf"^{key}\s+(.+)$", text, re.M | re.I)
+    return m.group(1).strip().lower() if m else None
+
+
+_SRC_RE = re.compile(r"^(?P<file>[^:]+):(?P<line>\d+):(?P<text>.*)$")
+
+
+def parse_sshd_sources(text: str, pam_2fa: bool = False,
+                       usepam: bool = True) -> tuple[list[str], list[tuple[str, str]]]:
+    """Return (global 'PasswordAuthentication yes' sources, [(Match criteria, file:line)]).
+
+    A Match block runs to the next Match or the end of its file; `Match all` is global.
+    `pam_2fa` / `usepam` are the host's global facts, applied to Match hits the way the global
+    classification applies them: a Match KbdInteractiveAuthentication needs UsePAM, and a
+    key-first AuthenticationMethods with a PAM 2FA module is not a password path.
+    """
+    global_yes: list[str] = []
+    match_yes: list[tuple[str, str]] = []
+    cur_file, criteria = None, None
+    for raw in text.splitlines():
+        m = _SRC_RE.match(raw)
+        if not m:
+            continue
+        f, ln, body = m.group("file"), m.group("line"), m.group("text").strip()
+        if f != cur_file:
+            cur_file, criteria = f, None
+        mm = re.match(r"Match\s+(.*)$", body, re.I)
+        if mm:
+            crit = mm.group(1).strip()
+            criteria = None if crit.lower() == "all" else crit
+            continue
+        if re.match(r"PasswordAuthentication\s+yes\b", body, re.I):
+            if criteria is None:
+                global_yes.append(f"{f}:{ln}:{body}")
+            else:
+                match_yes.append((criteria, f"{f}:{ln}"))
+        elif criteria is not None:
+            # Other password-ish ways back in, inside a Match block only (the global values
+            # are read from `sshd -T`). `where` names the directive since it is not the password one.
+            if re.match(r"(KbdInteractiveAuthentication|ChallengeResponseAuthentication)\s+yes\b", body, re.I):
+                if usepam:
+                    match_yes.append((criteria, f"{f}:{ln}: {body}"))
+            else:
+                am = re.match(r"AuthenticationMethods\s+(.+)$", body, re.I)
+                if am and _methods_allow_password(am.group(1), pam_2fa):
+                    match_yes.append((criteria, f"{f}:{ln}: {body}"))
+    return global_yes, match_yes
+
+
+def _methods_allow_password(value: str, pam_2fa: bool = False) -> bool:
+    """True if an AuthenticationMethods value lets a password-type factor in, consistent with
+    SshAuthDetector._classify: any alternative that needs no key but allows password or
+    keyboard-interactive, or a key followed by such a factor when no PAM 2FA module is known
+    (`publickey,password` is then reported, as it is for the global value). Callers pass
+    the host's real pam_2fa value (PamDetector runs before SshAuthDetector)."""
+    for alt in value.strip().strip('"').lower().split():
+        methods = [m.split(":")[0] for m in alt.split(",")]
+        if pam_2fa and methods[0] == "publickey" and "password" not in methods:
+            continue
+        if "password" in methods or "keyboard-interactive" in methods:
+            return True
+    return False
+
+
+def _effective_weak_auth(sshd_t: str, pam_2fa: bool = False) -> str | None:
+    """Reason string if an `sshd -T` dump (global or `-C` context) accepts password-ish auth.
+    AuthenticationMethods is evaluated first, as _classify does: it overrides the
+    PasswordAuthentication / KbdInteractive flags."""
+    methods = _sshd_value(sshd_t, "authenticationmethods") or "any"
+    if methods != "any":
+        return f"AuthenticationMethods {methods}" if _methods_allow_password(methods, pam_2fa) else None
+    if _sshd_value(sshd_t, "passwordauthentication") == "yes":
+        return "PasswordAuthentication yes"
+    usepam = _sshd_value(sshd_t, "usepam") == "yes"
+    kbd = _sshd_value(sshd_t, "kbdinteractiveauthentication") == "yes" or \
+        _sshd_value(sshd_t, "challengeresponseauthentication") == "yes"
+    if kbd and usepam:
+        return "KbdInteractiveAuthentication yes with UsePAM"
+    return None
+
+
+class SshAuthDetector(Detector):
+    name = "ssh-auth"
+    collectors = (C_SSHD, C_SSHD_SRC, C_SSHD_SRC_EXTRA, C_SSHD_ROOT, C_SSHD_USER)
+
+    def detect(self, ctx: AccessContext) -> None:
+        pam_2fa = bool(_PAM_2FA.search("\n".join(ctx.pam.get("sshd", []) + ctx.pam.get("common-auth", []))))
+        usepam = _sshd_value(_ok(ctx, C_SSHD) or "", "usepam") != "no"   # unknown -> assume on
+        global_yes, ctx.ssh_match_password = parse_sshd_sources(_ok(ctx, C_SSHD_SRC) or "", pam_2fa, usepam)
+        ctx.ssh_password_sources = global_yes
+        ctx.ssh_match_password += parse_sshd_sources(_ok(ctx, C_SSHD_SRC_EXTRA) or "", pam_2fa, usepam)[1]
+        # Effective per-context config (sshd -T -C): catches Match blocks the grep cannot
+        # interpret (Match order, Include, defaults). Only added when the global config is clean.
+        # "Clean" is decided by _classify (ctx.ssh_auth), not by a second heuristic.
+        self._classify(ctx)
+        if ctx.ssh_auth not in (SshAuth.PASSWORD_POSSIBLE,):
+            for label, col in (("user=root addr=203.0.113.1", C_SSHD_ROOT),
+                               ("first ordinary user addr=203.0.113.1", C_SSHD_USER)):
+                why = _effective_weak_auth(_ok(ctx, col) or "", pam_2fa)
+                if why:
+                    ctx.ssh_match_password.append((label, f"sshd -T -C: {why}"))
+        if ctx.ssh_match_password and ctx.ssh_auth != SshAuth.PASSWORD_POSSIBLE:
+            crit, where = ctx.ssh_match_password[0]
+            ctx.ssh_auth = SshAuth.PASSWORD_POSSIBLE
+            ctx.ssh_auth_note = f"password auth enabled for Match {crit} ({where})"
+
+    def _classify(self, ctx: AccessContext) -> None:
+        text = _ok(ctx, C_SSHD)
+        if not text:
+            ctx.ssh_auth, ctx.ssh_auth_note = SshAuth.UNKNOWN, "sshd -T unavailable"
+            return
+        ctx.ssh_facts_readable = True
+        ports = tuple(int(p) for p in re.findall(r"^port\s+(\d+)", text, re.M | re.I))
+        ctx.ssh_ports = ports or (22,)
+        password = _sshd_value(text, "passwordauthentication") == "yes"
+        kbd = _sshd_value(text, "kbdinteractiveauthentication") == "yes" or \
+            _sshd_value(text, "challengeresponseauthentication") == "yes"
+        usepam = _sshd_value(text, "usepam") == "yes"
+        methods = _sshd_value(text, "authenticationmethods") or "any"
+        ca = (_sshd_value(text, "trustedusercakeys") or "none") not in ("none", "")
+        pam_2fa = bool(_PAM_2FA.search("\n".join(ctx.pam.get("sshd", []) + ctx.pam.get("common-auth", []))))
+
+        if methods != "any":
+            alts = [a.split(",") for a in methods.split()]
+            if all(a and a[0] == "publickey" for a in alts):
+                if any(len(a) > 1 and "keyboard-interactive" in a for a in alts) and pam_2fa and kbd:
+                    ctx.ssh_auth, ctx.ssh_auth_note = SshAuth.KEY_PLUS_2FA, "AuthenticationMethods requires publickey + PAM 2FA"
+                elif all(len(a) == 1 for a in alts):
+                    ctx.ssh_auth = SshAuth.CA_CERTS if ca else SshAuth.KEY_ONLY
+                    ctx.ssh_auth_note = "AuthenticationMethods publickey only"
+                else:
+                    ctx.ssh_auth, ctx.ssh_auth_note = SshAuth.PASSWORD_POSSIBLE, \
+                        "publickey followed by a password-type factor (no 2FA module found)"
+                return
+            ctx.ssh_auth, ctx.ssh_auth_note = SshAuth.PASSWORD_POSSIBLE, \
+                f"AuthenticationMethods allows a non-key path ({methods})"
+            return
+        if password or (kbd and usepam):
+            ctx.ssh_auth = SshAuth.PASSWORD_POSSIBLE
+            ctx.ssh_auth_note = "PasswordAuthentication yes" if password else "keyboard-interactive via PAM"
+            return
+        ctx.ssh_auth = SshAuth.CA_CERTS if ca else SshAuth.KEY_ONLY
+        ctx.ssh_auth_note = "public keys" + (" and CA-signed certificates" if ca else "") + " only"
+
+
+_ACCT_RE = re.compile(r"^(\S+)\s+\[(.?)\]\s*(\S*)\s*$")
+
+
+class AccountsDetector(Detector):
+    name = "accounts"
+    collectors = (C_ACCOUNTS,)
+
+    def detect(self, ctx: AccessContext) -> None:
+        out = _ok(ctx, C_ACCOUNTS)
+        if not out or not out.strip():
+            return
+        for line in out.splitlines():
+            m = _ACCT_RE.match(line.strip())
+            if m:
+                ctx.accounts[m.group(1)] = Account(m.group(1), m.group(2), m.group(3))
+        ctx.accounts_readable = bool(ctx.accounts)
+
+
+_TAILNET_ULA = ipaddress.ip_network("fd7a:115c:a1e0::/48")
+
+
+def _is_overlay_addr(addr: str, overlay_addrs: set[str]) -> bool:
+    """Overlay evidence: bound to a VPN interface's own address, 100.64.0.0/10
+    (Tailscale and other CGNAT-range overlays) or the Tailscale IPv6 ULA range."""
+    if addr in overlay_addrs or classify_address(addr) == "cgnat":
+        return True
+    try:
+        return ipaddress.ip_address(addr) in _TAILNET_ULA
+    except ValueError:
+        return False
+
+
+def classify_reachability(ctx: AccessContext) -> tuple[Reachability, str]:
+    ports = ctx.ssh_ports or (22,)
+    fw = ctx.firewall
+    port_s = "/".join(str(p) for p in ports)
+
+    listen_addrs = [a for a, p in ctx.listeners if p in ports] if ctx.listen_readable else []
+    wildcard_listen = any(a in _WILDCARDS for a in listen_addrs)
+    if listen_addrs and not wildcard_listen:
+        non_lo = [a for a in listen_addrs if classify_address(a) != "loopback"]
+        if not non_lo:
+            return Reachability.PRIVATE_ONLY, f"sshd (tcp/{port_s}) listens on loopback only"
+        overlay_addrs = {a for i in ctx.interfaces if is_overlay_iface(i.name) for a, _ in i.addrs}
+        if all(_is_overlay_addr(a, overlay_addrs) for a in non_lo):
+            return Reachability.OVERLAY_ONLY, f"sshd (tcp/{port_s}) is bound only to VPN-overlay addresses"
+        # Any other specific bind (RFC1918, link-local, a public address) proves nothing:
+        # a private NIC address can sit behind 1:1 NAT. Fall through to firewall evidence.
+
+    if fw.readable:
+        verdicts = [(p, fw.evaluate(p, "tcp")) for p in ports]
+        acc = [(p, v) for p, v in verdicts if v.state == Exposure.ACCEPTED]
+        if acc:
+            p, v = acc[0]
+            how = "an explicit rule" if v.explicit else "the default policy"
+            return Reachability.PUBLIC, f"firewall accepts tcp/{p} from public interfaces ({how})"
+        unknown = [(p, v) for p, v in verdicts if v.state == Exposure.UNKNOWN]
+        if unknown:
+            return Reachability.UNKNOWN, f"firewall evidence incomplete for tcp/{unknown[0][0]}: {unknown[0][1].detail}"
+        restricted = [(p, v) for p, v in verdicts if v.state == Exposure.RESTRICTED]
+        if restricted:
+            srcs = sorted({s for _, v in restricted for s in v.sources})
+            if srcs and sources_are_private(srcs):
+                return Reachability.PRIVATE_ONLY, \
+                    f"firewall accepts tcp/{port_s} only from private sources ({', '.join(srcs[:4])})"
+            return Reachability.UNKNOWN, \
+                f"firewall accepts tcp/{port_s} only for specific sources ({', '.join(srcs[:4]) or 'unparsed condition'}); exposure not classified"
+        # Every SSH port is dropped from every public interface.
+        via = sorted({i for p in ports for i in fw.reachable_via_overlay(p)})
+        if via:
+            return Reachability.OVERLAY_ONLY, \
+                f"firewall drops tcp/{port_s} from public interfaces; it is accepted only on VPN overlay {', '.join(via)}"
+        return Reachability.PRIVATE_ONLY, \
+            f"firewall drops tcp/{port_s} from every public interface (no public path found)"
+
+    # No readable firewall: be honest about what is and is not proven.
+    if ctx.has_public_address and (wildcard_listen or not ctx.listen_readable):
+        return Reachability.PUBLIC, \
+            "a public address is configured on a network interface and no firewall rules were readable"
+    if ctx.interfaces and not ctx.has_public_address:
+        return Reachability.UNKNOWN, (
+            "no public address on any interface, but this does not prove the host is private "
+            "(cloud public IPs are often 1:1 NAT and never appear on the NIC) and no firewall or "
+            "listen evidence corroborates it"
+        )
+    return Reachability.UNKNOWN, "insufficient evidence (no readable firewall, interface or listen data)"
+
+
+class ReachabilityDetector(Detector):
+    name = "reachability"
+    collectors = ()
+
+    def detect(self, ctx: AccessContext) -> None:
+        ctx.reachability, ctx.reachability_note = classify_reachability(ctx)
+
+
+# Order matters: later detectors read what earlier ones wrote.
+DETECTORS: list[Detector] = [
+    InterfacesDetector(),
+    FirewallDetector(),
+    ListenDetector(),
+    DnatDetector(),
+    PamDetector(),
+    SshAuthDetector(),
+    AccountsDetector(),
+    ReachabilityDetector(),
+]
+
+
+def all_collectors() -> list[Collector]:
+    seen: dict[str, Collector] = {}
+    for det in DETECTORS:
+        for col in det.collectors:
+            prev = seen.get(col.command)
+            if prev is None:
+                seen[col.command] = col
+            elif col.sudo and not prev.sudo:
+                seen[col.command] = col
+    return list(seen.values())
+
+
+def build_access_context(runner: CommandRunner) -> AccessContext:
+    ctx = AccessContext()
+    for col in all_collectors():  # all commands issued up front
+        ctx.raw[col.command] = runner.run(col.command, sudo=col.sudo, timeout=col.timeout)
+    for det in DETECTORS:
+        try:
+            det.detect(ctx)
+        except Exception:  # a detector must never break a scan; its fields stay UNKNOWN
+            continue
+    return ctx
+
+
+_CACHE_ATTR = "_umbermark_access_ctx"
+
+
+def get_access_context(runner: CommandRunner) -> AccessContext:
+    """Build (once per runner) and return the AccessContext."""
+    cached = getattr(runner, _CACHE_ATTR, None)
+    if isinstance(cached, AccessContext):
+        return cached
+    ctx = build_access_context(runner)
+    try:
+        setattr(runner, _CACHE_ATTR, ctx)
+    except (AttributeError, TypeError):
+        pass
+    return ctx
+
+
+# --------------------------------------------------------------------------- #
+# Severity scaling helpers used by checks
+# --------------------------------------------------------------------------- #
+_STEP_DOWN = {
+    Severity.CRITICAL: Severity.MEDIUM,
+    Severity.HIGH: Severity.MEDIUM,
+    Severity.MEDIUM: Severity.LOW,
+    Severity.LOW: Severity.LOW,
+}
+
+
+def is_nonpublic(ctx: AccessContext) -> bool:
+    return ctx.reachability in (Reachability.OVERLAY_ONLY, Reachability.PRIVATE_ONLY)
+
+
+def scale_for_reachability(
+    severity: Severity, weight: int, ctx: AccessContext
+) -> tuple[Severity, int, str]:
+    """Scale (severity, weight) by exposure. Returns (severity, weight, note).
+
+    PUBLIC: unchanged, empty note. OVERLAY_ONLY / PRIVATE_ONLY: one-step lower
+    severity and a quarter of the weight (min 1), with the reason. UNKNOWN:
+    unchanged, but says so (we never claim low exposure without evidence).
+    """
+    r = ctx.reachability
+    if r == Reachability.PUBLIC:
+        return severity, weight, ""
+    if r == Reachability.UNKNOWN:
+        return severity, weight, (
+            f"Exposure could not be determined ({ctx.reachability_note}); severity not reduced."
+        )
+    scaled = max(1, -(-weight // 4))  # ceil(weight / 4)
+    return _STEP_DOWN[severity], scaled, (
+        f"SSH is not publicly reachable ({r.value}: {ctx.reachability_note}); "
+        "severity reduced accordingly."
+    )
+
+
+def maybe_context(runner: CommandRunner) -> AccessContext | None:
+    """get_access_context that tolerates exotic runners (never raises)."""
+    try:
+        return get_access_context(runner)
+    except Exception:
+        return None
+