dockerls 1.0.0__py3-none-any.whl

dockerls/domain/value_objects/tag_history.py

@@ -0,0 +1,180 @@
+"""Quantas vezes uma tag mudou de bytes debaixo de quem a usa.
+
+`base` já sabe dizer que a tag `python:3.12-alpine` aponta hoje para um digest
+diferente do que o Dockerfile fixou. O que ele não sabia dizer é o que essa
+frase significa: uma tag que mudou uma vez em oito meses e uma que muda toda
+semana pedem decisões opostas, e as duas produziam exatamente o mesmo
+`PINNED_STALE`.
+
+Este módulo guarda o histórico dessas observações -- digest e quando foi
+visto -- para que a mensagem deixe de ser "mudou" e passe a ser "mudou 6 vezes
+desde que começamos a olhar, a última há 3 dias". É a diferença entre um alerta
+e uma medida.
+
+Duas escolhas moldam o formato:
+
+* **Só a mudança entra.** Observar a mesma tag no mesmo digest cem vezes não é
+  cem eventos; é um. Registrar cada consulta encheria o histórico de ruído e
+  faria "6 observações" parecer "6 mudanças".
+* **A primeira observação nunca é descartada.** O histórico tem teto, mas
+  quando ele estoura são as do meio que caem. Perder a primeira apagaria
+  desde-quando -- e "mudou 6 vezes" sem o intervalo é um número sem unidade.
+
+Nada aqui afirma que uma tag *não* mudou: o histórico começa na primeira vez
+que esta ferramenta olhou, e o que aconteceu antes disso é desconhecido, não
+ausente. `explain()` diz isso em vez de esconder.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+#: Teto de observações guardadas por tag. Suficiente para enxergar uma cadência
+#: e pequeno o bastante para o histórico de um Dockerfile inteiro caber no
+#: cache sem virar um banco de dados por acidente.
+MAX_OBSERVATIONS = 24
+
+
+@dataclass(frozen=True)
+class TagObservation:
+    """Um digest, e quando esta ferramenta o viu pela primeira vez."""
+
+    digest: str
+    observed_at: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"digest": self.digest, "observed_at": self.observed_at}
+
+    @staticmethod
+    def from_dict(raw: object) -> TagObservation | None:
+        """Uma observação vinda do cache, ou `None` se a linha não presta.
+
+        O cache é conteúdo de fora do processo: uma entrada corrompida ou
+        gravada por uma versão anterior não deve derrubar um `dockerls base`.
+        """
+        if not isinstance(raw, dict):
+            return None
+        digest = raw.get("digest")
+        observed = raw.get("observed_at")
+        if not isinstance(digest, str) or not isinstance(observed, str):
+            return None
+        if not digest.strip():
+            return None
+        return TagObservation(digest=digest.strip(), observed_at=observed.strip())
+
+
+@dataclass(frozen=True)
+class TagHistory:
+    """O que se sabe sobre os movimentos de uma tag, em ordem cronológica."""
+
+    reference: str
+    observations: tuple[TagObservation, ...] = field(default_factory=tuple)
+    #: Movimentos que já não têm observação guardada, por terem caído no teto.
+    #: Sem este contador a poda faria a contagem regredir, e uma tag que muda
+    #: toda semana -- justamente a que mais importa -- apareceria como a mais
+    #: estável de todas assim que passasse de `MAX_OBSERVATIONS`.
+    dropped: int = 0
+
+    @property
+    def moves(self) -> int:
+        """Quantas vezes a tag trocou de digest desde a primeira observação.
+
+        Uma única observação é zero movimentos: é o ponto de partida, não um
+        evento.
+        """
+        return max(len(self.observations) - 1, 0) + self.dropped
+
+    @property
+    def current_digest(self) -> str:
+        return self.observations[-1].digest if self.observations else ""
+
+    @property
+    def first_seen(self) -> str:
+        return self.observations[0].observed_at if self.observations else ""
+
+    @property
+    def last_moved_at(self) -> str:
+        """Quando a tag mudou pela última vez, ou "" se ela nunca mudou aqui."""
+        return self.observations[-1].observed_at if self.moves else ""
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.observations
+
+    def explain(self) -> str:
+        """A frase que transforma o histórico numa decisão."""
+        if self.is_empty:
+            return "first time this tag is observed: there is no history to compare against"
+        if not self.moves:
+            return (
+                f"observed since {self.first_seen}, always on the same digest -- what "
+                "happened before that is unknown, not absent"
+            )
+        times = "time" if self.moves == 1 else "times"
+        return (
+            f"changed digest {self.moves} {times} since {self.first_seen}, "
+            f"the last on {self.last_moved_at}"
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "reference": self.reference,
+            "moves": self.moves,
+            "dropped_observations": self.dropped,
+            "first_seen": self.first_seen,
+            "last_moved_at": self.last_moved_at,
+            "explanation": self.explain(),
+            "observations": [o.to_dict() for o in self.observations],
+        }
+
+    @staticmethod
+    def from_dict(reference: str, raw: object) -> TagHistory:
+        """Reconstrói do cache, descartando em silêncio o que não presta.
+
+        Um histórico ilegível vira um histórico vazio -- que é honesto: não se
+        sabe nada sobre esta tag. Nunca uma exceção: o histórico é um extra
+        sobre o diagnóstico, e não pode ser o que impede o diagnóstico.
+        """
+        if not isinstance(raw, dict):
+            return TagHistory(reference=reference)
+        entries = raw.get("observations")
+        if not isinstance(entries, list):
+            return TagHistory(reference=reference)
+        parsed = [o for o in (TagObservation.from_dict(e) for e in entries) if o is not None]
+        dropped = raw.get("dropped_observations")
+        return TagHistory(
+            reference=reference,
+            observations=tuple(parsed),
+            dropped=dropped if isinstance(dropped, int) and dropped >= 0 else 0,
+        )
+
+
+def record(history: TagHistory, digest: str, observed_at: datetime) -> TagHistory:
+    """O histórico com esta observação incorporada.
+
+    Digest vazio não entra: "não foi possível perguntar ao registry" não é uma
+    observação de nada, e gravá-lo como se fosse inventaria um movimento que
+    nunca houve.
+    """
+    digest = digest.strip()
+    if not digest:
+        return history
+    if history.observations and history.observations[-1].digest == digest:
+        return history
+
+    observation = TagObservation(
+        digest=digest, observed_at=observed_at.isoformat(timespec="seconds")
+    )
+    entries = (*history.observations, observation)
+    dropped = history.dropped
+    if len(entries) > MAX_OBSERVATIONS:
+        # A primeira sobrevive porque é ela que ancora o "desde quando"; quem
+        # cai é o meio. O que cai vira contagem em `dropped`, para que podar o
+        # histórico nunca faça a tag parecer mais estável do que ela é.
+        dropped += len(entries) - MAX_OBSERVATIONS
+        entries = (entries[0], *entries[-(MAX_OBSERVATIONS - 1) :])
+    return replace(history, observations=entries, dropped=dropped)

dockerls/domain/value_objects/tool_release.py

@@ -0,0 +1,253 @@
+"""Qual artefato de release baixar, para qual plataforma.
+
+Puro de propósito: a escolha do asset é uma regra sobre nomes, e uma regra
+sobre nomes se testa exaustivamente sem rede, sem disco e sem instalar nada.
+O download, a verificação e a extração vivem em `infrastructure/toolchain`,
+que é onde o I/O pertence.
+
+Os nomes não são adivinhados, e foram confirmados por duas fontes
+independentes: a configuração de release de cada projeto (`goreleaser.yml` no
+Trivy, `.goreleaser.yaml` no Grype), que produz os arquivos, e o `install.sh`
+oficial de cada um, que os consome.
+
+    Trivy   contrib/install.sh:390
+            NAME=${PROJECT_NAME}_${VERSION}_${OS}-${ARCH}
+            CHECKSUM=${PROJECT_NAME}_${VERSION}_checksums.txt
+            adjust_os:   linux -> Linux, darwin -> macOS, windows inalterado
+            adjust_arch: amd64 -> 64bit, arm64 -> ARM64
+
+    Grype   install.sh:432 (search_for_asset)
+            asset_glob="${name}_.*_${os}_${arch}.${format}"
+            checksums:   "${name}_${version}_checksums.txt"
+            os/arch vêm de `uname` em minúsculas, sem tradução
+
+Os dois usam `zip` no Windows e `tar.gz` no resto.
+
+Uma plataforma sem artefato conhecido devolve None, e o comando recusa com
+uma mensagem em vez de tentar uma URL genérica que daria 404 depois do
+consentimento do usuário.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class OS(StrEnum):
+    LINUX = "linux"
+    WINDOWS = "windows"
+    MACOS = "macos"
+
+
+class Arch(StrEnum):
+    AMD64 = "amd64"
+    ARM64 = "arm64"
+
+
+def detect_os(system: str) -> OS | None:
+    """Traduz `platform.system()` para o enum, ou None se não suportado.
+
+    Recusar explicitamente é o ponto: um SO desconhecido tem que falhar com
+    mensagem, não escorregar para o caminho do Linux e baixar um binário
+    que não roda ali.
+    """
+    match system.strip().lower():
+        case "linux":
+            return OS.LINUX
+        case "windows":
+            return OS.WINDOWS
+        case "darwin":
+            return OS.MACOS
+        case _:
+            return None
+
+
+def detect_arch(machine: str) -> Arch | None:
+    """Traduz `platform.machine()`, cujos rótulos variam por SO.
+
+    `x86_64` no Linux e `AMD64` no Windows são a mesma arquitetura, e
+    `aarch64`/`arm64` também.
+    """
+    match machine.strip().lower():
+        case "x86_64" | "amd64" | "x64":
+            return Arch.AMD64
+        case "aarch64" | "arm64":
+            return Arch.ARM64
+        case _:
+            return None
+
+
+@dataclass(frozen=True)
+class ReleaseAsset:
+    """O que baixar e onde conferir, para uma versão e plataforma."""
+
+    #: URL do arquivo compactado com o binário.
+    archive_url: str
+    #: URL do arquivo de checksums que cobre esse arquivo.
+    checksums_url: str
+    #: Nome do arquivo dentro do `checksums.txt`, que é por onde a linha
+    #: correta é localizada.
+    archive_name: str
+    #: Nome do binário depois de extraído, com a extensão do SO.
+    binary_name: str
+    #: A página de release, para o usuário conferir de onde isto vem antes
+    #: de consentir.
+    release_url: str
+    #: Assinatura cosign do `checksums.txt`, quando o projeto publica uma.
+    #: Vazio quando não publica -- e vazio nunca significa "não assinado":
+    #: significa que este catálogo não sabe de nenhuma, que é ausência de
+    #: informação e não veredito.
+    checksums_signature_url: str = ""
+    #: Certificado keyless que acompanha a assinatura.
+    checksums_certificate_url: str = ""
+    #: Regex da identidade que precisa ter assinado, e emissor OIDC
+    #: esperado. Vazios quando não há assinatura a conferir.
+    signer_identity_pattern: str = ""
+    signer_oidc_issuer: str = ""
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    """Um scanner e como o projeto dele publica os releases."""
+
+    name: str
+    owner: str
+    repo: str
+    #: Rótulos de SO no nome do arquivo, por plataforma.
+    os_labels: dict[OS, str]
+    #: Rótulos de arquitetura no nome do arquivo.
+    arch_labels: dict[Arch, str]
+    #: Separador **entre SO e arquitetura**: o Trivy usa `-`
+    #: (`Linux-64bit`), o Grype `_` (`linux_amd64`). O separador entre
+    #: projeto, versão e plataforma é `_` nos dois -- é o que o goreleaser
+    #: emite -- e não é configurável aqui.
+    separator: str
+    #: Plataformas para as quais o projeto publica artefato.
+    supported: frozenset[tuple[OS, Arch]]
+    #: Se o projeto publica `checksums.txt.sig` e `checksums.txt.pem` ao
+    #: lado do `checksums.txt`, que é o par que o `cosign verify-blob`
+    #: consome.
+    #:
+    #: A cadeia inteira depende disto e de mais nada: a assinatura prova
+    #: que o `checksums.txt` é o que o projeto publicou, e o SHA-256 do
+    #: arquivo compactado contra a linha correspondente prova que o
+    #: arquivo é o que aquele `checksums.txt` descreve.
+    #:
+    #: `False` significa **não confirmado por este catálogo**, e não "não
+    #: assinado": ninguém aqui foi ao release ver. A instalação segue com
+    #: o checksum, e `signature_verified` fica `None` -- ausência de
+    #: verificação, dita como ausência.
+    signs_checksums: bool = False
+
+    @property
+    def repo_url(self) -> str:
+        return f"https://github.com/{self.owner}/{self.repo}"
+
+    def supports(self, os_: OS, arch: Arch) -> bool:
+        return (os_, arch) in self.supported
+
+    def asset_for(self, version: str, os_: OS, arch: Arch) -> ReleaseAsset | None:
+        """O artefato desta versão para esta plataforma, ou None.
+
+        `version` vem sem o `v` inicial: as tags são `v0.58.1` e os arquivos
+        dentro do release são `trivy_0.58.1_...`.
+        """
+        if not self.supports(os_, arch):
+            return None
+        clean = version.lstrip("v")
+        if not clean:
+            return None
+
+        extension = "zip" if os_ is OS.WINDOWS else "tar.gz"
+        platform_label = f"{self.os_labels[os_]}{self.separator}{self.arch_labels[arch]}"
+        archive = f"{self.repo}_{clean}_{platform_label}.{extension}"
+        # O goreleaser sempre nomeia o checksum com `_`, mesmo quando o
+        # template do arquivo usa outro separador.
+        checksums = f"{self.repo}_{clean}_checksums.txt"
+        base = f"{self.repo_url}/releases/download/v{clean}"
+        return ReleaseAsset(
+            archive_url=f"{base}/{archive}",
+            checksums_url=f"{base}/{checksums}",
+            archive_name=archive,
+            binary_name=f"{self.name}.exe" if os_ is OS.WINDOWS else self.name,
+            release_url=f"{self.repo_url}/releases/tag/v{clean}",
+            checksums_signature_url=(f"{base}/{checksums}.sig" if self.signs_checksums else ""),
+            checksums_certificate_url=(f"{base}/{checksums}.pem" if self.signs_checksums else ""),
+            # A identidade tem de ser deste projeto: uma assinatura válida
+            # de *outra* workflow do GitHub prova que alguém assinou, e não
+            # que quem publica esta ferramenta assinou. O emissor é o do
+            # OIDC do GitHub Actions, que é como os dois projetos assinam.
+            signer_identity_pattern=(
+                rf"^https://github\.com/{self.owner}/{self.repo}/" if self.signs_checksums else ""
+            ),
+            signer_oidc_issuer=(
+                "https://token.actions.githubusercontent.com" if self.signs_checksums else ""
+            ),
+        )
+
+
+_EVERY_PLATFORM = frozenset(
+    {
+        (OS.LINUX, Arch.AMD64),
+        (OS.LINUX, Arch.ARM64),
+        (OS.WINDOWS, Arch.AMD64),
+        (OS.MACOS, Arch.AMD64),
+        (OS.MACOS, Arch.ARM64),
+    }
+)
+
+#: Rótulos conforme `goreleaser.yml` do Trivy: CamelCase para o SO,
+#: `64bit`/`ARM64` para a arquitetura, separados por `-`. Windows não está
+#: na lista de casos especiais do template, então cai no `.Os` cru, em
+#: minúsculas.
+TRIVY = ToolSpec(
+    name="trivy",
+    owner="aquasecurity",
+    repo="trivy",
+    os_labels={OS.LINUX: "Linux", OS.WINDOWS: "windows", OS.MACOS: "macOS"},
+    arch_labels={Arch.AMD64: "64bit", Arch.ARM64: "ARM64"},
+    separator="-",
+    supported=_EVERY_PLATFORM,
+    # Não confirmado: o release do Trivy não foi inspecionado a partir
+    # deste ambiente, e afirmar que ele assina (ou que não assina) seria
+    # inventar. Fica `False`, a instalação segue pelo checksum, e
+    # `signature_verified` volta `None` -- ausência de verificação, dita
+    # como ausência.
+    signs_checksums=False,
+)
+
+#: O `.goreleaser.yaml` do Grype não declara `name_template`, então vale o
+#: default do goreleaser: tudo minúsculo, separado por `_`.
+GRYPE = ToolSpec(
+    name="grype",
+    owner="anchore",
+    repo="grype",
+    os_labels={OS.LINUX: "linux", OS.WINDOWS: "windows", OS.MACOS: "darwin"},
+    arch_labels={Arch.AMD64: "amd64", Arch.ARM64: "arm64"},
+    separator="_",
+    supported=_EVERY_PLATFORM,
+    # Confirmado no `install.sh` do próprio Grype, que baixa
+    # `checksums.txt.sig` e `checksums.txt.pem` ao lado do `checksums.txt`
+    # e chama `cosign verify-blob` com os três.
+    signs_checksums=True,
+)
+
+#: Os scanners que `doctor --install` sabe instalar, na ordem em que são
+#: oferecidos. Trivy primeiro porque é o scanner primário do projeto.
+INSTALLABLE: tuple[ToolSpec, ...] = (TRIVY, GRYPE)
+
+#: Versão usada quando `releases/latest` não pôde ser consultada -- um proxy
+#: ou allowlist restritivo devolve 403 para `api.github.com` em muitos
+#: ambientes de CI enquanto `github.com/.../releases/download/...` (o único
+#: outro host que este instalador toca) segue liberado, porque é o mesmo
+#: host que serve o próprio binário. Sem isto, `doctor --install` travava o
+#: onboarding inteiro por causa de um endpoint que nem baixa nada.
+#:
+#: Atualizada manualmente de vez em quando; não precisa ser a última versão
+#: publicada, só uma que existe e ainda recebe correção de CVE -- é um
+#: piso, não a versão que `--install` busca quando a API está acessível.
+DEFAULT_VERSIONS: dict[str, str] = {
+    "trivy": "0.58.1",
+    "grype": "0.85.0",
+}

dockerls/domain/value_objects/tristate.py

@@ -0,0 +1,47 @@
+"""Three-valued logic for facts about an image.
+
+A security fact has three states, not two: true, false, and *not
+determined*. Collapsing the third into `False` is the single most dangerous
+simplification available here, because every consumer downstream reads
+`has_shell = False` as "this image has no shell" -- a hardening claim -- when
+all that happened is that nobody looked.
+
+The whole hardening and attack-surface analysis is therefore built on this
+type rather than on `bool`, and an unknown never earns credit: a fact that
+could not be determined contributes nothing to a score in either direction,
+and is reported as `unknown` in the table and in `--format json`.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class Tristate(StrEnum):
+    TRUE = "true"
+    FALSE = "false"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def of(cls, value: bool | None) -> Tristate:
+        """Lift an optional bool, mapping `None` to UNKNOWN.
+
+        Use this at every boundary where a source may simply not answer --
+        `dict.get()` on a registry payload, an absent catalogue key -- so the
+        absence stays visible instead of becoming a false.
+        """
+        if value is None:
+            return cls.UNKNOWN
+        return cls.TRUE if value else cls.FALSE
+
+    @property
+    def is_known(self) -> bool:
+        return self is not Tristate.UNKNOWN
+
+    @property
+    def is_true(self) -> bool:
+        return self is Tristate.TRUE
+
+    @property
+    def is_false(self) -> bool:
+        return self is Tristate.FALSE