dockerls 1.0.0__py3-none-any.whl

dockerls/domain/value_objects/inheritance.py

@@ -0,0 +1,352 @@
+"""De quem é cada CVE: da base que você escolheu, ou das camadas que você escreveu.
+
+Um relatório de build diz "47 vulnerabilidades" e manda a pessoa consertar. A
+pergunta que ela faz em seguida -- toda vez -- é "consertar *o quê*?", e a
+contagem não responde. Nesta ferramenta a resposta apareceu por acaso: uma
+`base-node` recém-gerada reprovava com um CRITICAL que não vinha de nada que o
+Dockerfile fazia, e sim do npm que a imagem oficial embute. Foi preciso um
+terceiro produto para descobrir isso.
+
+Este módulo faz esse cruzamento em casa. Escaneia-se a base declarada no `FROM`
+e a imagem construída, e comparam-se os dois conjuntos de achados pela mesma
+identidade que a validação cruzada entre scanners já usa (`CVE|pacote`). O
+resultado divide as vulnerabilidades em três, e as três levam a ações
+completamente diferentes:
+
+* **`INHERITED`** -- está na base e continua na sua imagem. Nada no seu
+  Dockerfile causou, e nada no seu Dockerfile resolve: ou a base é atualizada,
+  ou é trocada. É aqui que costuma morar a grande maioria.
+* **`INTRODUCED`** -- não está na base e está na sua imagem. Veio do que você
+  instalou, copiou ou construiu. É a única parte sobre a qual o seu código tem
+  poder direto.
+* **`REMOVED`** -- estava na base e não está mais. O `apk upgrade` do seu
+  Dockerfile, ou a remoção de um pacote, resolveu. Aparece porque é a medida
+  do que o seu endurecimento efetivamente comprou.
+
+A regra que sustenta o módulo é a de sempre: **sem os dois scans não há
+atribuição.** Se a base não pôde ser escaneada, o resultado é `UNAVAILABLE` e
+o relatório diz isso -- nunca "tudo é seu" nem "tudo é herdado", que seriam as
+duas maneiras de transformar ausência de medição em acusação.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from dockerls.domain.entities.vulnerability import finding_identity
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from dockerls.domain.entities.vulnerability import Vulnerability
+
+
+class FindingOrigin(StrEnum):
+    """De onde cada achado veio, do ponto de vista de quem escreveu o build."""
+
+    INHERITED = "INHERITED"
+    INTRODUCED = "INTRODUCED"
+    REMOVED = "REMOVED"
+
+
+#: O que fazer com cada grupo, dito em uma linha.
+ACTIONS: dict[FindingOrigin, str] = {
+    FindingOrigin.INHERITED: (
+        "came from the base and no line of your Dockerfile fixes it: update the base "
+        "(`dockerls base`) or swap it (`dockerls base --alternatives`)"
+    ),
+    FindingOrigin.INTRODUCED: (
+        "came from what this Dockerfile installs, copies or builds: the part you have "
+        "direct power over"
+    ),
+    FindingOrigin.REMOVED: (
+        "was in the base and is no longer in the final image: the measure of what your "
+        "hardening bought"
+    ),
+}
+
+
+@dataclass(frozen=True)
+class AttributedFinding:
+    """Um achado, e de quem ele é."""
+
+    identity: str
+    cve_id: str
+    package_name: str
+    severity: str
+    origin: FindingOrigin
+    #: Versão em que o upstream publicou a correção, quando publicou. Vazio é
+    #: "não há correção", e essa distinção é metade do plano de trabalho:
+    #: atualizar não resolve o que ninguém corrigiu.
+    fixed_version: str = ""
+
+    @property
+    def fixable(self) -> bool:
+        return bool(self.fixed_version.strip())
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "cve": self.cve_id,
+            "package": self.package_name,
+            "severity": self.severity,
+            "origin": str(self.origin),
+            "fixed_version": self.fixed_version,
+            "fixable": self.fixable,
+        }
+
+
+#: Severidades da mais grave para a menos, para o plano abrir pelo que importa.
+_SEVERITY_RANK = ("CRITICAL", "HIGH", "MEDIUM", "LOW", "UNKNOWN")
+
+
+@dataclass(frozen=True)
+class RemediationBucket:
+    """Um grupo do plano de trabalho: mesma origem, mesma situação de correção.
+
+    Existe porque origem sozinha não é plano. "41 vêm da base" ainda não diz se
+    atualizar a base adianta -- e a resposta muda tudo: se nenhuma delas tem
+    correção publicada, atualizar é trabalho perdido e trocar a base é o único
+    caminho.
+    """
+
+    origin: FindingOrigin
+    fixable: bool
+    findings: tuple[AttributedFinding, ...]
+
+    @property
+    def count(self) -> int:
+        return len(self.findings)
+
+    @property
+    def critical(self) -> int:
+        return sum(1 for f in self.findings if f.severity.upper() == "CRITICAL")
+
+    def action(self) -> str:
+        """O que fazer com este grupo, e o que essa ação não garante."""
+        if self.origin is FindingOrigin.INHERITED:
+            if self.fixable:
+                return (
+                    "a fix is published upstream: updating the base may resolve it -- "
+                    "may, because a fix existing does not mean whoever publishes the "
+                    "base has rebuilt with it. `dockerls base` checks whether the tag "
+                    "moved"
+                )
+            return (
+                "no fix is published: updating the base resolves nothing here. "
+                "Swapping the base is the only path -- `dockerls base --alternatives` "
+                "measures the candidates"
+            )
+        if self.fixable:
+            return "a fix is published: raise the dependency version in your manifest and rebuild"
+        return (
+            "no fix is published and the package is yours: consider removing, "
+            "replacing or isolating it. This is the group where a documented exemption "
+            "in `.dockerls-ignore.yaml` makes sense -- with an expiry date"
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "origin": str(self.origin),
+            "fixable": self.fixable,
+            "count": self.count,
+            "critical": self.critical,
+            "action": self.action(),
+            "findings": [f.to_dict() for f in self.findings],
+        }
+
+
+@dataclass(frozen=True)
+class InheritanceReport:
+    """A divisão entre o que é da base e o que é seu."""
+
+    base_reference: str = ""
+    #: Vazio quando a atribuição foi possível. Preenchido com o motivo quando
+    #: não foi -- e aí nenhuma contagem abaixo significa coisa alguma.
+    unavailable_reason: str = ""
+    findings: tuple[AttributedFinding, ...] = field(default_factory=tuple)
+
+    @property
+    def available(self) -> bool:
+        return not self.unavailable_reason
+
+    def of(self, origin: FindingOrigin) -> tuple[AttributedFinding, ...]:
+        return tuple(f for f in self.findings if f.origin is origin)
+
+    @property
+    def inherited(self) -> tuple[AttributedFinding, ...]:
+        return self.of(FindingOrigin.INHERITED)
+
+    @property
+    def introduced(self) -> tuple[AttributedFinding, ...]:
+        return self.of(FindingOrigin.INTRODUCED)
+
+    @property
+    def removed(self) -> tuple[AttributedFinding, ...]:
+        return self.of(FindingOrigin.REMOVED)
+
+    @property
+    def inherited_share(self) -> float:
+        """Fração das vulnerabilidades da imagem que vieram da base, 0.0--1.0.
+
+        Só conta o que está *na imagem*: `REMOVED` descreve o que não está lá,
+        e incluí-lo no denominador diluiria a conta com achados que ninguém
+        precisa tratar.
+        """
+        presentes = len(self.inherited) + len(self.introduced)
+        return len(self.inherited) / presentes if presentes else 0.0
+
+    def plan(self) -> tuple[RemediationBucket, ...]:
+        """O plano de trabalho: origem cruzada com "existe correção?".
+
+        Origem sozinha diz de quem é o problema; correção diz se ele tem
+        solução. Só as duas juntas dizem o que fazer na segunda-feira.
+
+        `REMOVED` fica de fora: não está na imagem, e um plano que lista o que
+        já não existe faz a lista parecer maior do que o trabalho é.
+        """
+        buckets: list[RemediationBucket] = []
+        for origin in (FindingOrigin.INHERITED, FindingOrigin.INTRODUCED):
+            for fixable in (True, False):
+                achados = tuple(
+                    sorted(
+                        (f for f in self.of(origin) if f.fixable is fixable),
+                        key=_by_severity,
+                    )
+                )
+                if achados:
+                    buckets.append(
+                        RemediationBucket(origin=origin, fixable=fixable, findings=achados)
+                    )
+        # O grupo com mais CRITICAL abre a lista: é onde a primeira hora de
+        # trabalho rende mais, e ordenar por total faria um monte de LOW passar
+        # à frente de dois CRITICAL sem correção.
+        return tuple(sorted(buckets, key=lambda b: (-b.critical, -b.count)))
+
+    @property
+    def fixable_inherited(self) -> int:
+        return sum(1 for f in self.inherited if f.fixable)
+
+    def explain(self) -> str:
+        """A frase que responde "consertar o quê?"."""
+        if not self.available:
+            return (
+                f"the vulnerabilities could not be attributed: {self.unavailable_reason}. "
+                "Without both scans, calling them yours or the base's would be inventing"
+            )
+        herdadas, suas = len(self.inherited), len(self.introduced)
+        if not herdadas and not suas:
+            if self.removed:
+                # É o melhor resultado possível, e a versão anterior o
+                # escondia atrás de "nada a atribuir": a imagem está limpa
+                # *e* o build tirou coisa da base. Vale dizer.
+                quantas = len(self.removed)
+                if quantas == 1:
+                    return (
+                        "no vulnerabilities in this image, and the 1 the base had did "
+                        "not survive the build"
+                    )
+                return (
+                    f"no vulnerabilities in this image, and the {quantas} the base had "
+                    "did not survive the build"
+                )
+            return "no vulnerabilities to attribute in this image"
+        partes = [
+            f"{herdadas} of {herdadas + suas} {_come(herdadas)} from the base "
+            f"{self.base_reference}",
+            f"{suas} {_come(suas)} from the layers of this Dockerfile",
+        ]
+        if self.removed:
+            quantas = len(self.removed)
+            partes.append(
+                f"{quantas} the base had {'was' if quantas == 1 else 'were'} removed by the build"
+            )
+        if herdadas:
+            # A pergunta imediatamente seguinte a "41 vêm da base" é "e
+            # atualizar a base resolve?". Responder junto poupa a viagem.
+            corrigiveis = self.fixable_inherited
+            partes.append(
+                f"{corrigiveis} of the inherited {_have(corrigiveis)} a fix published upstream"
+            )
+        return "; ".join(partes)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "base": self.base_reference,
+            "available": self.available,
+            "unavailable_reason": self.unavailable_reason,
+            "explanation": self.explain(),
+            "counts": {
+                "inherited": len(self.inherited),
+                "introduced": len(self.introduced),
+                "removed": len(self.removed),
+            },
+            "inherited_share": round(self.inherited_share, 3),
+            "actions": {str(origin): action for origin, action in ACTIONS.items()},
+            "plan": [b.to_dict() for b in self.plan()],
+            "findings": [f.to_dict() for f in self.findings],
+        }
+
+
+def attribute(
+    built: Iterable[Vulnerability],
+    base: Iterable[Vulnerability],
+    *,
+    base_reference: str,
+) -> InheritanceReport:
+    """Divide os achados entre herdados da base, introduzidos e removidos.
+
+    A identidade comparada é `CVE|pacote`, a mesma da validação cruzada entre
+    scanners: o mesmo CVE em dois pacotes são dois problemas a resolver, e o
+    mesmo pacote com dois CVEs também. A versão instalada fica de fora de
+    propósito -- a base e a imagem final frequentemente reportam o mesmo pacote
+    com strings de versão normalizadas de formas diferentes, e comparar isso
+    fabricaria diferença a partir de formatação.
+    """
+    por_identidade_construida = {finding_identity(v): v for v in built}
+    identidades_base = {finding_identity(v): v for v in base}
+
+    achados: list[AttributedFinding] = []
+    for identity, vuln in por_identidade_construida.items():
+        origin = (
+            FindingOrigin.INHERITED if identity in identidades_base else FindingOrigin.INTRODUCED
+        )
+        achados.append(_attributed(identity, vuln, origin))
+
+    for identity, vuln in identidades_base.items():
+        if identity not in por_identidade_construida:
+            achados.append(_attributed(identity, vuln, FindingOrigin.REMOVED))
+
+    return InheritanceReport(base_reference=base_reference, findings=tuple(achados))
+
+
+def unavailable(base_reference: str, reason: str) -> InheritanceReport:
+    """A atribuição que não pôde ser feita, com o motivo em vez de um palpite."""
+    return InheritanceReport(base_reference=base_reference, unavailable_reason=reason)
+
+
+def _attributed(identity: str, vuln: Vulnerability, origin: FindingOrigin) -> AttributedFinding:
+    return AttributedFinding(
+        identity=identity,
+        cve_id=vuln.cve_id,
+        package_name=vuln.package_name,
+        severity=str(vuln.severity),
+        origin=origin,
+        fixed_version=vuln.fixed_version,
+    )
+
+
+def _come(quantidade: int) -> str:
+    return "comes" if quantidade == 1 else "come"
+
+
+def _have(quantidade: int) -> str:
+    return "has" if quantidade == 1 else "have"
+
+
+def _by_severity(finding: AttributedFinding) -> tuple[int, str]:
+    """Mais grave primeiro; CVE desempata para a ordem ser estável."""
+    severity = finding.severity.upper()
+    rank = _SEVERITY_RANK.index(severity) if severity in _SEVERITY_RANK else len(_SEVERITY_RANK)
+    return rank, finding.cve_id

dockerls/domain/value_objects/network_policy.py

@@ -0,0 +1,280 @@
+"""Where DockerLs is allowed to send a request, and why that needs a policy.
+
+An image reference is user input, and it carries a hostname. `dockerls
+analyze 169.254.169.254/latest` is a well-formed reference, and resolving it
+means issuing `GET https://169.254.169.254/v2/latest/manifests/...` -- the
+cloud metadata endpoint. On a CI runner, a reference arriving from a pull
+request, a config file or an environment variable therefore turns this tool
+into an SSRF primitive against the host's internal network. The response body
+never reaches the requester, but the *reach* does, and blind is still SSRF.
+
+The naive fix -- refuse every private address -- is wrong here, and the
+project brief says so explicitly: internal registries on RFC1918 addresses
+are ordinary, legitimate infrastructure, and a scanner that cannot look at
+`registry.internal:5000` is a scanner nobody can use. So the policy
+distinguishes two things that get lumped together:
+
+* **loopback and link-local** are refused by default. No legitimate registry
+  is reachable at `127.0.0.1` *from the perspective of a reference someone
+  else supplied*, and `169.254.0.0/16` is where every cloud provider parks
+  its credential endpoint. This is the actual attack.
+* **private ranges** (RFC1918, unique-local) are allowed by default, because
+  that is where real internal registries live -- and tightened with a single
+  setting when a deployment wants to.
+
+Either default can be overridden, and an explicit host allowlist wins over
+both: an operator who genuinely runs a registry on localhost says so once.
+
+Hostnames are judged by where they *resolve*, not by how they are spelled:
+`localhost` and an attacker-controlled name whose A record points at
+127.0.0.1 are the same request, and only one of them looks suspicious in a
+config file. Resolving a name is I/O, so it does not happen here -- this
+module decides over addresses it is handed, and
+`infrastructure/network/host_guard.py` is what performs the lookup. That
+split is what keeps the rule testable without a network and the domain free
+of sockets.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class NetworkDecision(StrEnum):
+    """Why a host was allowed or refused. Reported, never silent."""
+
+    ALLOWED = "ALLOWED"
+    ALLOWED_BY_ALLOWLIST = "ALLOWED_BY_ALLOWLIST"
+    BLOCKED_LOOPBACK = "BLOCKED_LOOPBACK"
+    BLOCKED_LINK_LOCAL = "BLOCKED_LINK_LOCAL"
+    BLOCKED_PRIVATE = "BLOCKED_PRIVATE"
+    BLOCKED_UNSPECIFIED = "BLOCKED_UNSPECIFIED"
+    BLOCKED_UNRESOLVABLE = "BLOCKED_UNRESOLVABLE"
+    BLOCKED_SPECIAL = "BLOCKED_SPECIAL"
+    BLOCKED_SCHEME = "BLOCKED_SCHEME"
+
+
+#: Decisions that permit the request.
+_ALLOWING = (NetworkDecision.ALLOWED, NetworkDecision.ALLOWED_BY_ALLOWLIST)
+
+
+@dataclass(frozen=True)
+class NetworkPolicy:
+    """What a reference is permitted to make this process talk to."""
+
+    #: RFC1918 / unique-local. Default True: internal registries are normal.
+    allow_private_networks: bool = True
+    #: 127.0.0.0/8, ::1. Default False -- this is the SSRF case, and a
+    #: registry on localhost is a deliberate, local choice that deserves to
+    #: be stated.
+    allow_loopback: bool = False
+    #: 169.254.0.0/16, fe80::/10. Default False: cloud metadata lives here
+    #: and nothing else legitimate does.
+    allow_link_local: bool = False
+    #: Hosts permitted regardless of where they resolve, exactly as written
+    #: in the reference (host or host:port).
+    allowed_hosts: frozenset[str] = field(default_factory=frozenset)
+
+    def is_allowlisted(self, host: str) -> bool:
+        """Whether `host` is permitted outright, before any lookup.
+
+        Checked first by the caller so an operator who deliberately runs a
+        registry on localhost is never subjected to a DNS round-trip to be
+        told what they already declared.
+        """
+        candidates = {host.strip().lower(), hostname_of(host).lower()}
+        return bool(candidates & {entry.strip().lower() for entry in self.allowed_hosts})
+
+    def decide_addresses(
+        self, addresses: list[ipaddress.IPv4Address | ipaddress.IPv6Address]
+    ) -> NetworkDecision:
+        """Classify a host from the addresses it resolves to.
+
+        **Every** address must pass. A name answering with one public and
+        one loopback address is the shape of a DNS-rebinding attack, and the
+        connection would be free to use either.
+        """
+        if not addresses:
+            # A name that resolves to nothing cannot be reached anyway;
+            # refusing here keeps the failure on the policy's terms rather
+            # than as a connection error deep inside an HTTP client.
+            return NetworkDecision.BLOCKED_UNRESOLVABLE
+        for address in addresses:
+            decision = self._classify(address)
+            if decision not in _ALLOWING:
+                return decision
+        return NetworkDecision.ALLOWED
+
+    def explain(self, host: str, decision: NetworkDecision) -> str:
+        """A refusal a reader can act on, naming the setting that changes it."""
+        return _EXPLANATIONS.get(decision, "").format(host=host)
+
+    def _classify(self, address: ipaddress.IPv4Address | ipaddress.IPv6Address) -> NetworkDecision:
+        # An IPv6 address may *carry* an IPv4 one. `::ffff:127.0.0.1`,
+        # `2002:7f00:1::` (6to4) and `64:ff9b::7f00:1` (NAT64) all reach
+        # 127.0.0.1 on a host with the matching translation configured, and
+        # only the first of the three is recognised by `is_loopback`. Judge
+        # the address that would actually be contacted, then fall through to
+        # judging the wrapper too -- a tunnel does not launder a destination.
+        embedded = _embedded_ipv4(address)
+        if embedded is not None:
+            decision = self._classify(embedded)
+            if decision not in _ALLOWING:
+                return decision
+
+        if address.is_unspecified or _in_any(address, _WILDCARD_SOURCE):
+            # 0.0.0.0/8 in full, not just the exact 0.0.0.0: Linux routes
+            # `0.x.y.z` to the local host, so the whole block is a spelling
+            # of "loopback" that `is_loopback` does not catch.
+            return NetworkDecision.BLOCKED_UNSPECIFIED
+        if address.is_loopback:
+            return (
+                NetworkDecision.ALLOWED if self.allow_loopback else NetworkDecision.BLOCKED_LOOPBACK
+            )
+        if address.is_link_local:
+            return (
+                NetworkDecision.ALLOWED
+                if self.allow_link_local
+                else NetworkDecision.BLOCKED_LINK_LOCAL
+            )
+        if _in_any(address, _SPECIAL) or address.is_multicast:
+            # Shared/benchmark/reserved space and the carrier-grade NAT block
+            # where Alibaba Cloud serves instance credentials
+            # (100.100.100.200). None of it hosts a registry, all of it is
+            # reachable from a CI runner, so it is refused outright rather
+            # than folded into `allow_private_networks` -- an operator who
+            # turns private networks on to reach 10.0.0.0/8 has not thereby
+            # asked for a route to a metadata service.
+            #
+            # `is_reserved` used to be part of this condition and was
+            # removed: for an IPv4-mapped IPv6 address (`::ffff:a.b.c.d`),
+            # its answer has changed between CPython patch releases (a
+            # private embedded address such as `::ffff:10.0.0.5` came back
+            # reserved on some 3.11.x builds and not on others), so the
+            # exact same instability the module comment above already
+            # calls out for `is_global` applied here too, just unnoticed.
+            # Every range this project actually intends to block through
+            # `is_reserved` is already named explicitly in `_SPECIAL`
+            # (TEST-NETs, the 240.0.0.0/4 block, NAT64, discard-only,
+            # documentation) or handled by the embedded-address recursion
+            # above -- a security boundary should not move with the
+            # runtime's patch version.
+            return NetworkDecision.BLOCKED_SPECIAL
+        if address.is_private:
+            return (
+                NetworkDecision.ALLOWED
+                if self.allow_private_networks
+                else NetworkDecision.BLOCKED_PRIVATE
+            )
+        return NetworkDecision.ALLOWED
+
+
+#: 0.0.0.0/8. `is_unspecified` is only true for the single address 0.0.0.0,
+#: but the whole block behaves as "this host" on Linux.
+_WILDCARD_SOURCE = (ipaddress.ip_network("0.0.0.0/8"),)
+
+#: Ranges that are neither public nor plausible registry homes. Enumerated
+#: rather than derived from `is_global`, whose membership has changed between
+#: Python releases -- a security boundary should not move with the runtime.
+_SPECIAL = (
+    ipaddress.ip_network("100.64.0.0/10"),  # RFC 6598 CGNAT; Alibaba metadata
+    ipaddress.ip_network("192.0.0.0/24"),  # IETF protocol assignments
+    ipaddress.ip_network("192.0.2.0/24"),  # TEST-NET-1
+    ipaddress.ip_network("192.88.99.0/24"),  # deprecated 6to4 relay anycast
+    ipaddress.ip_network("198.18.0.0/15"),  # benchmarking
+    ipaddress.ip_network("198.51.100.0/24"),  # TEST-NET-2
+    ipaddress.ip_network("203.0.113.0/24"),  # TEST-NET-3
+    ipaddress.ip_network("240.0.0.0/4"),  # reserved, incl. 255.255.255.255
+    ipaddress.ip_network("64:ff9b::/96"),  # NAT64
+    ipaddress.ip_network("64:ff9b:1::/48"),  # local-use NAT64
+    ipaddress.ip_network("100::/64"),  # discard-only
+    ipaddress.ip_network("2001:db8::/32"),  # documentation
+)
+
+#: 6to4 (RFC 3056) and Teredo (RFC 4380) prefixes, whose payload is an IPv4
+#: address that the host may actually route to.
+_SIXTOFOUR = ipaddress.ip_network("2002::/16")
+_TEREDO = ipaddress.ip_network("2001::/32")
+_NAT64 = ipaddress.ip_network("64:ff9b::/96")
+
+
+def _in_any(
+    address: ipaddress.IPv4Address | ipaddress.IPv6Address,
+    networks: tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...],
+) -> bool:
+    return any(address.version == net.version and address in net for net in networks)
+
+
+def _embedded_ipv4(
+    address: ipaddress.IPv4Address | ipaddress.IPv6Address,
+) -> ipaddress.IPv4Address | None:
+    """The IPv4 address an IPv6 address encodes, if it encodes one.
+
+    Covers the four encodings a host can be configured to translate:
+    IPv4-mapped and IPv4-compatible (`::ffff:a.b.c.d`, `::a.b.c.d`), 6to4,
+    Teredo and NAT64. Returns None for an ordinary IPv6 address.
+    """
+    if not isinstance(address, ipaddress.IPv6Address):
+        return None
+    if address.ipv4_mapped is not None:
+        return address.ipv4_mapped
+    if address.sixtofour is not None and address in _SIXTOFOUR:
+        return address.sixtofour
+    if address.teredo is not None and address in _TEREDO:
+        # (server, client); the client is the address packets reach.
+        return address.teredo[1]
+    if address in _NAT64:
+        return ipaddress.IPv4Address(int(address) & 0xFFFFFFFF)
+    return None
+
+
+_EXPLANATIONS = {
+    NetworkDecision.BLOCKED_LOOPBACK: (
+        "{host} resolves to a loopback address. Refused by default: a reference that "
+        "reaches localhost is how an untrusted image name becomes a request to a "
+        "service on this machine. Set network_allow_loopback = true, or add the host "
+        "to network_allowed_hosts, if this is deliberate."
+    ),
+    NetworkDecision.BLOCKED_LINK_LOCAL: (
+        "{host} resolves to a link-local address (169.254.0.0/16). Refused by default: "
+        "this is where cloud providers serve instance credentials. Set "
+        "network_allow_link_local = true only if you know why you need it."
+    ),
+    NetworkDecision.BLOCKED_PRIVATE: (
+        "{host} resolves to a private address and network_allow_private_networks is "
+        "off. Turn it on, or add the host to network_allowed_hosts."
+    ),
+    NetworkDecision.BLOCKED_UNSPECIFIED: (
+        "{host} resolves to an unspecified address (0.0.0.0/8 or ::), which names this "
+        "host rather than a registry."
+    ),
+    NetworkDecision.BLOCKED_UNRESOLVABLE: "{host} could not be resolved to any address.",
+    NetworkDecision.BLOCKED_SPECIAL: (
+        "{host} resolves into reserved, shared or carrier-grade-NAT space (for example "
+        "100.64.0.0/10, where some clouds serve instance credentials). No registry is "
+        "published there; add the host to network_allowed_hosts if this is deliberate."
+    ),
+    NetworkDecision.BLOCKED_SCHEME: (
+        "{host} was requested over a scheme other than http/https, which this tool never follows."
+    ),
+}
+
+
+def hostname_of(host: str) -> str:
+    """Strip an optional `:port`, leaving the name or literal address.
+
+    IPv6 literals in a registry reference are bracketed (`[::1]:5000`), so
+    the bracket form is handled before the naive rsplit that would otherwise
+    cut a bare `::1` in half.
+    """
+    value = host.strip()
+    if not value:
+        return ""
+    if value.startswith("["):
+        closing = value.find("]")
+        return value[1:closing] if closing > 1 else ""
+    if value.count(":") == 1:
+        return value.rsplit(":", 1)[0]
+    return value