dockerls 1.0.0__py3-none-any.whl

dockerls/domain/value_objects/production_readiness.py

@@ -0,0 +1,145 @@
+"""The one place that decides whether an image may go to production.
+
+Before this module the decision was `tier in (A, B) and not is_eol`, computed
+inside `SecurityTier` from the score alone. That expression cannot see
+whether the scan finished, whether two scanners agreed, or whether anything
+was verified at all -- so a `PARTIAL` scan with no findings in the targets it
+managed to read produced a high score, tier A, and `production_ready = True`,
+while the very same analysis reported `confidence = UNVERIFIED`.
+
+An analysis that says both things is worse than one that says neither. The
+field a CI gate reads is this one, so it is the field that must be hardest to
+fool.
+
+The policy is deliberately a *list of blockers* rather than a boolean with a
+reason attached: a reader who is told "not production ready" immediately asks
+why, and an image can fail for several independent causes at once. Every
+blocker names itself in the reader's terms, and the same list feeds the
+terminal, `--format json` and every exporter.
+
+**Absence of evidence blocks; it does not excuse.** An unknown EOL status
+does not prove the image is supported, an unresolved digest does not prove
+the tag is stable, and a missing second scanner does not prove the first one
+was right. None of those *penalise* the score -- there is nothing to penalise
+-- but none of them may be spent as if it were a positive finding either.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from dockerls.domain.value_objects.confidence import Confidence, confidence_rank
+from dockerls.domain.value_objects.security_tier import PRODUCTION_READY_TIERS, Tier
+from dockerls.domain.value_objects.tristate import Tristate
+
+
+class BlockingReason(StrEnum):
+    """Why an image is not production ready. Stable codes, so a pipeline can
+    branch on them without parsing prose."""
+
+    NOT_MEASURED = "NOT_MEASURED"
+    LOW_CONFIDENCE = "LOW_CONFIDENCE"
+    END_OF_LIFE = "END_OF_LIFE"
+    CRITICAL_FINDINGS = "CRITICAL_FINDINGS"
+    HIGH_FINDINGS = "HIGH_FINDINGS"
+    UNFIXABLE_CRITICAL = "UNFIXABLE_CRITICAL"
+    SCANNER_DIVERGENCE = "SCANNER_DIVERGENCE"
+    TIER_TOO_LOW = "TIER_TOO_LOW"
+
+
+#: What each code means where a human reads it.
+EXPLANATIONS: dict[BlockingReason, str] = {
+    BlockingReason.NOT_MEASURED: (
+        "the scan did not complete, so nothing about this image was measured"
+    ),
+    BlockingReason.LOW_CONFIDENCE: (
+        "the evidence behind this result has a material problem (see confidence reasons)"
+    ),
+    BlockingReason.END_OF_LIFE: "this release is end-of-life and will not receive security fixes",
+    BlockingReason.CRITICAL_FINDINGS: "CRITICAL vulnerabilities are present",
+    BlockingReason.HIGH_FINDINGS: "HIGH vulnerabilities are present",
+    BlockingReason.UNFIXABLE_CRITICAL: "a CRITICAL vulnerability has no fix available",
+    BlockingReason.SCANNER_DIVERGENCE: (
+        "two scanners disagreed materially and the disagreement is unresolved"
+    ),
+    BlockingReason.TIER_TOO_LOW: "the security tier is below the production threshold",
+}
+
+#: Confidence below which no image is production ready, whatever its score.
+#: MEDIUM is the floor rather than HIGH because HIGH requires a second
+#: scanner, and refusing every single-scanner installation would make the
+#: verdict a statement about the operator's toolchain instead of about the
+#: image.
+MINIMUM_CONFIDENCE = Confidence.MEDIUM
+
+
+@dataclass(frozen=True)
+class ReadinessInputs:
+    """Everything the decision depends on, stated explicitly.
+
+    A frozen record rather than a reference to the analysis DTO: the domain
+    must not depend on the application layer, and listing the inputs is what
+    makes the rule auditable without reading its callers.
+    """
+
+    tier: Tier
+    confidence: Confidence
+    scan_verified: bool
+    #: Tri-state on purpose: `UNKNOWN` does not block (nothing says the
+    #: release is dead) and does not excuse either -- it is surfaced, and it
+    #: keeps confidence from reaching the top.
+    eol: Tristate = Tristate.UNKNOWN
+    critical_count: int = 0
+    high_count: int = 0
+    unfixable_critical_count: int = 0
+    max_critical: int = 0
+    max_high: int = 0
+    has_material_divergence: bool = False
+
+
+@dataclass(frozen=True)
+class ProductionReadiness:
+    """Applies the policy and reports every reason it failed."""
+
+    inputs: ReadinessInputs
+    blockers: list[BlockingReason] = field(default_factory=list)
+
+    @classmethod
+    def evaluate(cls, inputs: ReadinessInputs) -> ProductionReadiness:
+        blockers: list[BlockingReason] = []
+
+        # Measurement first. Everything below is a statement about findings,
+        # and a statement about findings presupposes that somebody looked.
+        if not inputs.scan_verified:
+            blockers.append(BlockingReason.NOT_MEASURED)
+        if confidence_rank(inputs.confidence) < confidence_rank(MINIMUM_CONFIDENCE):
+            blockers.append(BlockingReason.LOW_CONFIDENCE)
+
+        if inputs.eol.is_true:
+            blockers.append(BlockingReason.END_OF_LIFE)
+        if inputs.critical_count > inputs.max_critical:
+            blockers.append(BlockingReason.CRITICAL_FINDINGS)
+        if inputs.high_count > inputs.max_high:
+            blockers.append(BlockingReason.HIGH_FINDINGS)
+        if inputs.unfixable_critical_count > 0:
+            blockers.append(BlockingReason.UNFIXABLE_CRITICAL)
+        if inputs.has_material_divergence:
+            blockers.append(BlockingReason.SCANNER_DIVERGENCE)
+        if inputs.tier not in PRODUCTION_READY_TIERS:
+            blockers.append(BlockingReason.TIER_TOO_LOW)
+
+        return cls(inputs=inputs, blockers=blockers)
+
+    @property
+    def is_ready(self) -> bool:
+        return not self.blockers
+
+    @property
+    def reasons(self) -> list[str]:
+        """The blockers in the reader's terms, in the order they were found."""
+        return [EXPLANATIONS[reason] for reason in self.blockers]
+
+    @property
+    def codes(self) -> list[str]:
+        return [reason.value for reason in self.blockers]

dockerls/domain/value_objects/provenance.py

@@ -0,0 +1,211 @@
+"""A cadeia entre o que entrou no build e o que saiu dele.
+
+Um relatório de segurança afirma coisas sobre uma imagem. Sem procedência, a
+afirmação não é verificável: dois builds do mesmo `--tag` produziam relatórios
+indistinguíveis mesmo partindo de Dockerfiles diferentes, e nada ligava o
+scan ao artefato que ele mediu. Numa cadeia de fornecimento, "nós escaneamos
+essa imagem" sem digest é uma frase sobre nada.
+
+O registro tem duas metades, e as duas existem por um motivo distinto:
+
+* **antes do build** -- digest do Dockerfile, digest do contexto, digests das
+  imagens base declaradas nos `FROM`, e a revisão do repositório. Isto
+  responde "o que foi construído".
+* **depois do build** -- id da imagem, digest do manifesto publicado, e a
+  identidade do scanner que a mediu. Isto responde "o que saiu, e quem
+  atestou".
+
+A parte que faz disto controle e não decoração é a verificação entre as duas:
+o Dockerfile e o contexto são digeridos de novo **depois** do build, e se
+mudaram no meio do caminho o registro é marcado como quebrado. Um build cuja
+entrada mudou enquanto ele acontecia não produziu a imagem que o relatório
+descreve -- seja por edição concorrente, seja porque alguém quis exatamente
+isso. É o mesmo princípio que governa o resto desta ferramenta: uma coisa que
+não pôde ser verificada não é apresentada como verificada.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class ProvenanceStatus(StrEnum):
+    """O que o registro pode afirmar sobre si mesmo."""
+
+    #: Entrada e saída digeridas, e a entrada não mudou durante o build.
+    VERIFIED = "VERIFIED"
+    #: O build aconteceu, mas algo não pôde ser digerido (contexto grande
+    #: demais, arquivo ilegível). Não é uma acusação -- é a ausência de prova.
+    INCOMPLETE = "INCOMPLETE"
+    #: O Dockerfile ou o contexto mudaram entre o início e o fim do build.
+    #: A imagem existe; o que ela não tem é uma entrada conhecida.
+    INPUT_CHANGED = "INPUT_CHANGED"
+
+
+@dataclass(frozen=True)
+class SourceDigests:
+    """O que entrou. Medido antes do `docker build` começar."""
+
+    dockerfile: str = ""
+    context: str = ""
+    context_files: int = 0
+    #: `FROM` declarado -> digest resolvido, quando resolvível. Uma base sem
+    #: digest é uma tag móvel, e dizer isso é mais útil do que omitir.
+    base_images: dict[str, str] = field(default_factory=dict)
+    git_revision: str = ""
+    #: Repositório com alterações não commitadas no momento do build. O commit
+    #: sozinho mentiria sobre o que gerou a imagem.
+    git_dirty: bool = False
+
+
+@dataclass(frozen=True)
+class ArtifactDigests:
+    """O que saiu. Medido depois do build, e depois do push quando há um."""
+
+    image_id: str = ""
+    #: Digest do manifesto no registry. Só existe após o push -- é o único
+    #: identificador que outra máquina consegue usar para puxar exatamente
+    #: esta imagem.
+    repo_digest: str = ""
+    published_reference: str = ""
+    scanner: str = ""
+
+
+@dataclass(frozen=True)
+class BuildProvenance:
+    """Procedência completa de um build, pronta para ser arquivada."""
+
+    tag: str
+    source: SourceDigests = field(default_factory=SourceDigests)
+    artifact: ArtifactDigests = field(default_factory=ArtifactDigests)
+    #: Digests recalculados após o build. Iguais aos de `source` num build
+    #: íntegro.
+    source_after: SourceDigests = field(default_factory=SourceDigests)
+    started_at: str = ""
+    finished_at: str = ""
+
+    @property
+    def status(self) -> ProvenanceStatus:
+        if not self.source.dockerfile or not self.source_after.dockerfile:
+            return ProvenanceStatus.INCOMPLETE
+        if (
+            self.source.dockerfile != self.source_after.dockerfile
+            or self.source.context != self.source_after.context
+        ):
+            return ProvenanceStatus.INPUT_CHANGED
+        if not self.artifact.image_id:
+            return ProvenanceStatus.INCOMPLETE
+        return ProvenanceStatus.VERIFIED
+
+    @property
+    def is_verified(self) -> bool:
+        return self.status is ProvenanceStatus.VERIFIED
+
+    def explain(self) -> str:
+        """Uma frase que um humano usa para decidir se confia no registro."""
+        if self.status is ProvenanceStatus.INPUT_CHANGED:
+            changed = []
+            if self.source.dockerfile != self.source_after.dockerfile:
+                changed.append("the Dockerfile")
+            if self.source.context != self.source_after.context:
+                changed.append("the build context")
+            return (
+                f"{' and '.join(changed)} changed during the build: the image exists, "
+                "but does not correspond to the input measured at the start"
+            )
+        if self.status is ProvenanceStatus.INCOMPLETE:
+            return (
+                "provenance incomplete: part of the input or the output could not be "
+                "digested, so the chain does not close"
+            )
+        return "input and output digested, and the input did not change during the build"
+
+    @staticmethod
+    def from_dict(raw: object) -> BuildProvenance:
+        """Reconstrói o documento arquivado, para conferi-lo depois.
+
+        Um documento é uma afirmação sobre um build que já terminou, e quem o
+        lê -- um passo de CI, uma revisão de incidente -- precisa recalcular o
+        `status` a partir dos digests, e não aceitar o `status` gravado. Um
+        campo `"status": "VERIFIED"` num arquivo JSON é editável por qualquer
+        um; a comparação entre `source` e `source_after_build` não é.
+
+        O que não parsear vira campo vazio, o que leva o status a
+        `INCOMPLETE` -- nunca a `VERIFIED` por omissão.
+        """
+        if not isinstance(raw, dict):
+            return BuildProvenance(tag="")
+        source = _mapping(raw.get("source"))
+        after = _mapping(raw.get("source_after_build"))
+        artifact = _mapping(raw.get("artifact"))
+        bases = source.get("base_images")
+        return BuildProvenance(
+            tag=_text(raw.get("tag")),
+            source=SourceDigests(
+                dockerfile=_text(source.get("dockerfile_sha256")),
+                context=_text(source.get("context_sha256")),
+                context_files=_count(source.get("context_files")),
+                base_images=(
+                    {str(k): str(v) for k, v in bases.items()} if isinstance(bases, dict) else {}
+                ),
+                git_revision=_text(source.get("git_revision")),
+                git_dirty=source.get("git_dirty") is True,
+            ),
+            source_after=SourceDigests(
+                dockerfile=_text(after.get("dockerfile_sha256")),
+                context=_text(after.get("context_sha256")),
+            ),
+            artifact=ArtifactDigests(
+                image_id=_text(artifact.get("image_id")),
+                repo_digest=_text(artifact.get("repo_digest")),
+                published_reference=_text(artifact.get("published_reference")),
+                scanner=_text(artifact.get("scanner")),
+            ),
+            started_at=_text(raw.get("started_at")),
+            finished_at=_text(raw.get("finished_at")),
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        """O documento arquivado junto do relatório.
+
+        Formato próprio, e propositalmente plano: um consumidor precisa
+        conseguir comparar dois builds com um `diff` sem instalar nada.
+        """
+        return {
+            "tag": self.tag,
+            "status": str(self.status),
+            "explanation": self.explain(),
+            "started_at": self.started_at,
+            "finished_at": self.finished_at,
+            "source": {
+                "dockerfile_sha256": self.source.dockerfile,
+                "context_sha256": self.source.context,
+                "context_files": self.source.context_files,
+                "base_images": dict(self.source.base_images),
+                "git_revision": self.source.git_revision,
+                "git_dirty": self.source.git_dirty,
+            },
+            "source_after_build": {
+                "dockerfile_sha256": self.source_after.dockerfile,
+                "context_sha256": self.source_after.context,
+            },
+            "artifact": {
+                "image_id": self.artifact.image_id,
+                "repo_digest": self.artifact.repo_digest,
+                "published_reference": self.artifact.published_reference,
+                "scanner": self.artifact.scanner,
+            },
+        }
+
+
+def _mapping(value: object) -> dict[str, object]:
+    return value if isinstance(value, dict) else {}
+
+
+def _text(value: object) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _count(value: object) -> int:
+    return value if isinstance(value, int) and not isinstance(value, bool) and value >= 0 else 0

dockerls/domain/value_objects/recipe_diff.py

@@ -0,0 +1,188 @@
+"""O que muda de superfície entre duas receitas de imagem base.
+
+O menu do `base-image` faz a pessoa escolher família, runtime e pacotes, e
+cada escolha custa alguma coisa. O custo aparece na hora de marcar o pacote,
+uma linha por vez -- o que não ajuda em nada na pergunta que de fato se faz:
+"alpine ou debian para isto?". Comparar exigia gerar os dois Dockerfiles e ler
+os dois lado a lado, contando pacotes na mão.
+
+Este módulo responde a pergunta como diferença: o que a receita B tem que a A
+não tem, o que ela perde, e o que cada uma dessas trocas significa. É puro --
+recebe duas receitas e devolve o delta, sem tocar em registry, disco ou build.
+
+**O que ele deliberadamente não faz é eleger uma vencedora.** Contar pacotes
+não mede vulnerabilidade: uma base com menos pacotes e um deles desatualizado
+é pior do que uma com mais pacotes e todos corrigidos, e esta ferramenta
+inteira é construída sobre a recusa de apresentar como medido o que não foi
+medido. O delta descreve as trocas com precisão e manda escanear as duas -- que
+é a única coisa que responde de verdade.
+
+A troca de família tem destaque próprio porque é a única que muda o contrato
+binário: alpine é musl, debian e ubuntu são glibc. Uma dependência compilada
+sem roda musllinux não instala do outro lado, e descobrir isso no diff custa
+segundos; descobrir no build de produção custa a janela de deploy.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from dockerls.domain.value_objects.base_recipe import PACKAGE_CATALOG, BaseRecipe
+
+_BY_KEY = {choice.key: choice for choice in PACKAGE_CATALOG}
+
+
+@dataclass(frozen=True)
+class PackageDelta:
+    """Um pacote que existe só de um lado, com o que ele traz junto."""
+
+    key: str
+    purpose: str
+    cost: str
+
+    @staticmethod
+    def of(key: str) -> PackageDelta:
+        choice = _BY_KEY.get(key)
+        if choice is None:
+            # Pacote fora do catálogo não deveria chegar aqui (a receita
+            # valida antes), mas o diff não é lugar de levantar: descrever o
+            # que não se conhece como desconhecido é mais útil que estourar.
+            return PackageDelta(key=key, purpose="not catalogued", cost="unknown")
+        return PackageDelta(key=choice.key, purpose=choice.purpose, cost=choice.cost)
+
+    def to_dict(self) -> dict[str, str]:
+        return {"package": self.key, "purpose": self.purpose, "cost": self.cost}
+
+
+@dataclass(frozen=True)
+class RecipeDiff:
+    """As diferenças entre duas receitas, da esquerda para a direita."""
+
+    left: BaseRecipe
+    right: BaseRecipe
+    added: tuple[PackageDelta, ...] = field(default_factory=tuple)
+    removed: tuple[PackageDelta, ...] = field(default_factory=tuple)
+
+    @property
+    def family_changed(self) -> bool:
+        return self.left.family is not self.right.family
+
+    @property
+    def libc_changed(self) -> bool:
+        """A troca que quebra binário compilado, e não só tamanho de imagem."""
+        return self.left.family.libc != self.right.family.libc
+
+    @property
+    def runtime_changed(self) -> bool:
+        return self.left.runtime is not self.right.runtime
+
+    @property
+    def manager_strip_changed(self) -> bool:
+        return self.left.strip_bundled_manager != self.right.strip_bundled_manager
+
+    @property
+    def pinning_changed(self) -> bool:
+        return bool(self.left.digest) != bool(self.right.digest)
+
+    @property
+    def has_changes(self) -> bool:
+        return bool(
+            self.added
+            or self.removed
+            or self.family_changed
+            or self.runtime_changed
+            or self.manager_strip_changed
+            or self.pinning_changed
+        )
+
+    def notes(self) -> list[str]:
+        """As trocas que não são pacote, ditas em uma linha cada."""
+        lines: list[str] = []
+        both_install = self.left.family.installs_packages and self.right.family.installs_packages
+        if self.libc_changed:
+            lines.append(
+                f"libc changes from {self.left.family.libc} to "
+                f"{self.right.family.libc}: compiled dependencies need a wheel for the "
+                "new one, or they get built from source -- and some simply do not build"
+            )
+        elif self.family_changed:
+            lines.append(
+                f"family changes from {self.left.family} to {self.right.family}, "
+                "keeping the same libc"
+            )
+        if self.runtime_changed:
+            lines.append(f"runtime changes from {self.left.runtime} to {self.right.runtime}")
+        if not both_install:
+            distroless = (
+                self.right.family if not self.right.family.installs_packages else self.left.family
+            )
+            lines.append(
+                f"{distroless} has no package manager and no shell: nothing can be "
+                "installed into it afterwards, and no `docker exec` will work"
+            )
+        # Numa distroless não há gerenciador embutido para remover: dizer que
+        # um lado "remove e o outro não" descreveria uma diferença que não
+        # existe, e a nota do distroless logo acima já cobre o caso.
+        if self.manager_strip_changed and both_install:
+            quem = "the right" if self.right.strip_bundled_manager else "the left"
+            lines.append(
+                f"only {quem} removes the package manager the official image ships -- "
+                "the largest surface difference between the two, and it does not show "
+                "up in a package count"
+            )
+        if self.pinning_changed:
+            solta = "the right" if not self.right.digest else "the left"
+            lines.append(
+                f"{solta} sits on a moving tag, with no digest: two builds of the same "
+                "file can produce different images"
+            )
+        return lines
+
+    def verdict(self) -> str:
+        """Por que este diff não elege uma vencedora."""
+        return (
+            "this is a content diff, not a vulnerability diff: counting packages does "
+            "not measure CVEs, and the only answer to which of the two is safer comes "
+            "from scanning both. Build them and run `dockerls scan` on each"
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "left": _describe(self.left),
+            "right": _describe(self.right),
+            "added": [d.to_dict() for d in self.added],
+            "removed": [d.to_dict() for d in self.removed],
+            "libc_changed": self.libc_changed,
+            "notes": self.notes(),
+            "verdict": self.verdict(),
+        }
+
+
+def compare(left: BaseRecipe, right: BaseRecipe) -> RecipeDiff:
+    """As diferenças da receita `left` para a `right`."""
+    esquerda = set(left.packages)
+    direita = set(right.packages)
+    return RecipeDiff(
+        left=left,
+        right=right,
+        added=tuple(PackageDelta.of(k) for k in sorted(direita - esquerda)),
+        removed=tuple(PackageDelta.of(k) for k in sorted(esquerda - direita)),
+    )
+
+
+def _describe(recipe: BaseRecipe) -> dict[str, object]:
+    try:
+        reference = recipe.base.reference
+    except Exception:
+        # Combinação sem imagem publicada: o diff ainda descreve o resto, e
+        # `validate()` é quem recusa a receita impossível.
+        reference = f"{recipe.runtime} on {recipe.family} (no published image)"
+    return {
+        "family": str(recipe.family),
+        "runtime": str(recipe.runtime),
+        "libc": recipe.family.libc,
+        "reference": reference,
+        "packages": list(recipe.packages),
+        "pinned": bool(recipe.digest),
+        "strips_bundled_manager": recipe.strip_bundled_manager,
+    }