dockerls 1.0.0__py3-none-any.whl

dockerls/domain/value_objects/build_policy.py

@@ -0,0 +1,412 @@
+"""A política da organização, escrita uma vez e conferida em todo build.
+
+`--fail-on critical` é um portão, mas é um portão que mora na linha de comando
+-- e uma regra que mora na linha de comando é uma regra que cada pipeline
+reescreve à mão. Bastava um `--fail-on high` esquecido num repositório para
+que a política da organização deixasse de valer ali, sem que nada acusasse.
+
+Este módulo é a política como dado: um `.dockerls-policy.yaml` versionado junto
+do código, conferido contra o que foi **medido** neste build. A parte aqui é
+pura -- recebe os fatos e devolve as violações -- para que cada regra seja
+testável contra o número exato que a produziu.
+
+Três princípios moldam o que existe e o que não existe aqui:
+
+* **Só entra o que é mensurável.** Não há regra de "não use pacotes inseguros"
+  ou "mantenha a imagem pequena": não há como decidir isso a partir de um
+  build, e uma regra que não pode ser avaliada é uma regra que reprova por
+  engano ou aprova por omissão. As duas corroem a confiança no portão.
+* **Não medir nunca aprova.** Toda regra que dependa de uma medição que não
+  aconteceu vira violação, não silêncio. É o mesmo princípio que impede uma
+  imagem não escaneada de ser apresentada como segura.
+* **A política nunca afrouxa o que a linha de comando apertou.** Quando as
+  duas discordam, vale a mais estrita. Um arquivo no repositório não pode
+  desligar um portão que o pipeline pediu -- senão bastaria commitar um YAML
+  para publicar o que não passaria.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from dockerls.domain.value_objects.gate import SEVERITY_THRESHOLDS, merge_gates
+from dockerls.domain.value_objects.tristate import Tristate
+
+#: Severidades que uma contagem pode nomear. `unknown` entra: um scanner que
+#: reporta um achado sem severidade ainda reportou um achado, e um teto sobre
+#: ele é legítimo.
+SEVERITY_ORDER: tuple[str, ...] = ("critical", "high", "medium", "low", "unknown")
+
+#: Limiares que o portão aceita, do mais brando para o mais estrito -- e a
+#: ordem é essa mesmo. `--fail-on low` reprova em LOW *e em tudo acima dele*,
+#: então é o limiar mais exigente que existe; `--fail-on critical` é o mais
+#: permissivo. Confundir os dois foi um bug real aqui: `effective_fail_on`
+#: escolhia por "gravidade da palavra" e devolvia `critical` quando um lado
+#: pedia `high`, afrouxando em silêncio um portão que alguém tinha apertado.
+#:
+#: `unknown` fica de fora porque o portão não sabe avaliá-lo: aceitá-lo na
+#: política produziria um build que morre com erro técnico no meio do
+#: caminho, em vez de uma política recusada na leitura do arquivo.
+#: Reexportado de `gate.py`, que é onde a escala mora agora: duas
+#: definições de "mais estrito" divergiriam na primeira mudança.
+GATE_THRESHOLDS: tuple[str, ...] = SEVERITY_THRESHOLDS
+
+
+class PolicyRule(StrEnum):
+    """Cada regra que a política pode exigir, nomeada para o relatório."""
+
+    FAIL_ON = "fail_on"
+    MAX_VULNERABILITIES = "max_vulnerabilities"
+    REQUIRE_SCAN = "require_scan"
+    REQUIRE_PINNED_BASES = "require_pinned_bases"
+    REQUIRE_NONROOT = "require_nonroot"
+    REQUIRED_LABELS = "required_labels"
+    ALLOWED_BASE_REGISTRIES = "allowed_base_registries"
+    REQUIRE_PROVENANCE = "require_provenance"
+
+
+@dataclass(frozen=True)
+class BaseFact:
+    """Uma base declarada, reduzida ao que a política consegue avaliar."""
+
+    reference: str
+    registry: str
+    pinned: bool
+
+
+@dataclass(frozen=True)
+class PolicyFacts:
+    """O que este build mediu. Tudo que a política tem para trabalhar."""
+
+    #: Se um scanner chegou a rodar. `False` não é "zero vulnerabilidades".
+    scan_ran: bool = False
+    #: Contagem por severidade, do scan que rodou.
+    severity_counts: dict[str, int] = field(default_factory=dict)
+    bases: tuple[BaseFact, ...] = ()
+    labels: dict[str, str] = field(default_factory=dict)
+    #: Se a imagem roda sem privilégio. `UNKNOWN` quando o Dockerfile não
+    #: permitiu decidir -- e a política trata isso como violação, não como sim.
+    nonroot: Tristate = Tristate.UNKNOWN
+    #: `VERIFIED`, `INCOMPLETE`, `INPUT_CHANGED`, ou "" quando não houve
+    #: registro de procedência neste build.
+    provenance_status: str = ""
+
+
+@dataclass(frozen=True)
+class PolicyViolation:
+    """Uma regra que este build não cumpriu, e por quê."""
+
+    rule: PolicyRule
+    message: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"rule": str(self.rule), "message": self.message}
+
+
+@dataclass(frozen=True)
+class BuildPolicy:
+    """As exigências declaradas em `.dockerls-policy.yaml`."""
+
+    #: O portão que reprova o build: uma severidade (`critical`), `kev`,
+    #: `epss>=N`, ou vários separados por vírgula. Vazio deixa a decisão
+    #: com a linha de comando.
+    fail_on: str = ""
+    #: Teto por severidade (`{"high": 5}`). Um teto de zero é diferente de
+    #: `fail_on`: permite tolerar 3 HIGH e nenhum CRITICAL no mesmo arquivo.
+    max_vulnerabilities: dict[str, int] = field(default_factory=dict)
+    require_scan: bool = False
+    require_pinned_bases: bool = False
+    require_nonroot: bool = False
+    required_labels: tuple[str, ...] = ()
+    #: Registries de onde as bases podem vir. Vazio não restringe; declarado,
+    #: restringe **todas** as bases, inclusive as de estágios intermediários.
+    allowed_base_registries: tuple[str, ...] = ()
+    require_provenance: bool = False
+
+    @property
+    def is_empty(self) -> bool:
+        """Uma política que não exige nada. Vale saber: um arquivo presente e
+        vazio quase sempre significa um erro de digitação nas chaves."""
+        return not (
+            self.fail_on
+            or self.max_vulnerabilities
+            or self.require_scan
+            or self.require_pinned_bases
+            or self.require_nonroot
+            or self.required_labels
+            or self.allowed_base_registries
+            or self.require_provenance
+        )
+
+    def effective_fail_on(self, requested: str) -> str:
+        """O portão que vale, entre o da política e o da linha de comando.
+
+        Severidade contra severidade continua sendo a regra antiga: vence o
+        limiar **mais baixo na escala**, e não a palavra mais assustadora --
+        `--fail-on low` reprova em LOW e em tudo acima, enquanto `critical`
+        só olha CRITICAL. Nem o arquivo do repositório desliga um portão que
+        o pipeline pediu, nem uma flag afrouxa a política da organização.
+
+        Portões de tipos diferentes não competem: somam. `kev` e `high` são
+        perguntas diferentes sobre coisas diferentes, e escolher uma
+        descartaria a outra em silêncio. A regra vive em
+        `domain/value_objects/gate.py` para que a política e o portão do
+        build não possam divergir sobre o que "mais estrito" significa.
+        """
+        return merge_gates(self.fail_on, requested)
+
+    @staticmethod
+    def production() -> BuildPolicy:
+        """O perfil de produção: o conjunto que uma imagem publicada precisa.
+
+        Existe porque a alternativa é uma lista de sete flags que cada pipeline
+        digita de novo, esquecendo uma diferente por vez. Nomear o conjunto faz
+        a omissão virar uma decisão visível (`--no-policy`, `--fail-on low`) em
+        vez de um esquecimento invisível.
+
+        `fail_on` fica em `critical` e não em `high` de propósito. Um perfil que
+        ninguém consegue cumprir é um perfil que as pessoas desligam inteiro, e
+        `high` reprova praticamente toda base Debian num dia qualquer. O teto de
+        `high` fica declarado à parte, onde se enxerga e se discute.
+        """
+        return BuildPolicy(
+            fail_on="critical",
+            require_scan=True,
+            require_pinned_bases=True,
+            require_nonroot=True,
+            require_provenance=True,
+            required_labels=(
+                "org.opencontainers.image.source",
+                "org.opencontainers.image.vendor",
+                "security.contact",
+            ),
+        )
+
+    def merged_with(self, other: BuildPolicy | None) -> BuildPolicy:
+        """Este perfil somado a outro, sempre pelo lado mais estrito.
+
+        Serve para `--production` conviver com um `.dockerls-policy.yaml`: o
+        arquivo do repositório pode **apertar** o perfil (exigir um rótulo a
+        mais, um registry específico), e não pode afrouxá-lo. Uma exigência
+        declarada em qualquer um dos dois vale nos dois.
+        """
+        if other is None:
+            return self
+        tetos = {**other.max_vulnerabilities}
+        for severity, limit in self.max_vulnerabilities.items():
+            tetos[severity] = min(limit, tetos.get(severity, limit))
+        return BuildPolicy(
+            fail_on=self.effective_fail_on(other.fail_on),
+            max_vulnerabilities=tetos,
+            require_scan=self.require_scan or other.require_scan,
+            require_pinned_bases=self.require_pinned_bases or other.require_pinned_bases,
+            require_nonroot=self.require_nonroot or other.require_nonroot,
+            require_provenance=self.require_provenance or other.require_provenance,
+            required_labels=tuple(dict.fromkeys((*self.required_labels, *other.required_labels))),
+            allowed_base_registries=(
+                # Interseção não: duas listas disjuntas produziriam um conjunto
+                # vazio, que significa "não restringe" -- exatamente o oposto do
+                # que as duas pediram. A união mantém as duas restrições
+                # satisfazíveis e cada base ainda precisa estar em alguma delas.
+                tuple(
+                    dict.fromkeys((*self.allowed_base_registries, *other.allowed_base_registries))
+                )
+            ),
+        )
+
+    def static_subset(self) -> BuildPolicy:
+        """A política reduzida ao que se decide sem construir nem escanear.
+
+        Uma varredura de frota lê Dockerfiles; ela não constrói imagem nem
+        chama scanner. Aplicar as regras que dependem de scan ali produziria
+        uma violação por arquivo, todas dizendo a mesma coisa ("não houve
+        scan") -- e uma lista em que tudo está vermelho não distingue nada.
+
+        As regras removidas não são consideradas cumpridas: elas continuam
+        valendo no `build`, que é onde há medição para conferi-las.
+        """
+        return BuildPolicy(
+            require_pinned_bases=self.require_pinned_bases,
+            require_nonroot=self.require_nonroot,
+            required_labels=self.required_labels,
+            allowed_base_registries=self.allowed_base_registries,
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "fail_on": self.fail_on,
+            "max_vulnerabilities": dict(self.max_vulnerabilities),
+            "require_scan": self.require_scan,
+            "require_pinned_bases": self.require_pinned_bases,
+            "require_nonroot": self.require_nonroot,
+            "required_labels": list(self.required_labels),
+            "allowed_base_registries": list(self.allowed_base_registries),
+            "require_provenance": self.require_provenance,
+        }
+
+
+def evaluate(policy: BuildPolicy, facts: PolicyFacts) -> list[PolicyViolation]:
+    """As regras que este build não cumpriu, na ordem em que foram declaradas.
+
+    Uma lista vazia significa "nenhuma regra foi violada", e não "está tudo
+    bem": uma política vazia não viola nada e também não garante nada. Quem
+    consome precisa olhar a política junto do resultado, e é por isso que
+    `is_empty` existe.
+    """
+    violations: list[PolicyViolation] = []
+
+    _check_scan(policy, facts, violations)
+    _check_ceilings(policy, facts, violations)
+    _check_bases(policy, facts, violations)
+    _check_nonroot(policy, facts, violations)
+    _check_labels(policy, facts, violations)
+    _check_provenance(policy, facts, violations)
+    return violations
+
+
+def _check_scan(policy: BuildPolicy, facts: PolicyFacts, violations: list[PolicyViolation]) -> None:
+    if policy.require_scan and not facts.scan_ran:
+        violations.append(
+            PolicyViolation(
+                rule=PolicyRule.REQUIRE_SCAN,
+                message=(
+                    "the policy requires a scan and no scanner ran: an image that "
+                    "could not be measured is not an image without vulnerabilities"
+                ),
+            )
+        )
+
+
+def _check_ceilings(
+    policy: BuildPolicy, facts: PolicyFacts, violations: list[PolicyViolation]
+) -> None:
+    if not policy.max_vulnerabilities:
+        return
+    if not facts.scan_ran:
+        # Sem scan não há contagem, e "contagem ausente" não é "contagem
+        # dentro do teto". Aprovar aqui esvaziaria toda regra de teto numa
+        # máquina sem scanner.
+        violations.append(
+            PolicyViolation(
+                rule=PolicyRule.MAX_VULNERABILITIES,
+                message=(
+                    "the policy declares per-severity ceilings and no scanner ran: "
+                    "there is no count to check them against"
+                ),
+            )
+        )
+        return
+    for severity in SEVERITY_ORDER:
+        if severity not in policy.max_vulnerabilities:
+            continue
+        limit = policy.max_vulnerabilities[severity]
+        found = facts.severity_counts.get(severity, 0)
+        if found > limit:
+            violations.append(
+                PolicyViolation(
+                    rule=PolicyRule.MAX_VULNERABILITIES,
+                    message=(
+                        f"{found} {severity.upper()} vulnerability(ies) against a "
+                        f"policy ceiling of {limit}"
+                    ),
+                )
+            )
+
+
+def _check_bases(
+    policy: BuildPolicy, facts: PolicyFacts, violations: list[PolicyViolation]
+) -> None:
+    if policy.require_pinned_bases:
+        if not facts.bases:
+            violations.append(
+                PolicyViolation(
+                    rule=PolicyRule.REQUIRE_PINNED_BASES,
+                    message=(
+                        "the policy requires digest-pinned bases and no base could "
+                        "be read from the Dockerfile"
+                    ),
+                )
+            )
+        for base in facts.bases:
+            if not base.pinned:
+                violations.append(
+                    PolicyViolation(
+                        rule=PolicyRule.REQUIRE_PINNED_BASES,
+                        message=(
+                            f"{base.reference} is not pinned by digest: what was "
+                            "tested and what ships to production can be different "
+                            "bytes with no change of yours"
+                        ),
+                    )
+                )
+
+    if not policy.allowed_base_registries:
+        return
+    permitidos = {r.lower() for r in policy.allowed_base_registries}
+    for base in facts.bases:
+        # Uma base sem host explícito vem do Docker Hub; tratá-la como "sem
+        # registry" faria a regra ignorar exatamente o caso mais comum.
+        registry = (base.registry or "docker.io").lower()
+        if registry not in permitidos:
+            violations.append(
+                PolicyViolation(
+                    rule=PolicyRule.ALLOWED_BASE_REGISTRIES,
+                    message=(
+                        f"{base.reference} comes from {registry}, which is not among "
+                        f"the allowed registries ({', '.join(sorted(permitidos))})"
+                    ),
+                )
+            )
+
+
+def _check_nonroot(
+    policy: BuildPolicy, facts: PolicyFacts, violations: list[PolicyViolation]
+) -> None:
+    if not policy.require_nonroot or facts.nonroot.is_true:
+        return
+    motivo = (
+        "the image runs as root"
+        if facts.nonroot.is_false
+        else "the user the image runs as could not be determined, and not "
+        "determining is not the same as being in order"
+    )
+    violations.append(
+        PolicyViolation(
+            rule=PolicyRule.REQUIRE_NONROOT,
+            message=f"the policy requires running without privilege: {motivo}",
+        )
+    )
+
+
+def _check_labels(
+    policy: BuildPolicy, facts: PolicyFacts, violations: list[PolicyViolation]
+) -> None:
+    for label in policy.required_labels:
+        if not facts.labels.get(label, "").strip():
+            violations.append(
+                PolicyViolation(
+                    rule=PolicyRule.REQUIRED_LABELS,
+                    message=(
+                        f"required label missing or empty: {label} -- without it "
+                        "nobody knows who to turn to when this image shows up in an "
+                        "alert at three in the morning"
+                    ),
+                )
+            )
+
+
+def _check_provenance(
+    policy: BuildPolicy, facts: PolicyFacts, violations: list[PolicyViolation]
+) -> None:
+    if not policy.require_provenance:
+        return
+    if facts.provenance_status == "VERIFIED":
+        return
+    detalhe = facts.provenance_status or "no record was produced"
+    violations.append(
+        PolicyViolation(
+            rule=PolicyRule.REQUIRE_PROVENANCE,
+            message=(f"the policy requires verified provenance, and the record is: {detalhe}"),
+        )
+    )

dockerls/domain/value_objects/confidence.py

@@ -0,0 +1,156 @@
+"""How much the evidence behind a verdict is worth.
+
+Every number this tool prints is the output of a chain: discover a
+candidate, resolve it to a digest, scan it, cross-check it with a second
+scanner, read its configuration. Links in that chain break routinely -- a
+registry rate-limits, a second scanner is not installed, a catalogue is
+stale -- and the result is still a table full of numbers. Without a
+confidence signal, a score produced from one scanner on an unresolved tag is
+rendered identically to one produced from two agreeing scanners on a pinned
+digest, and the reader has no way to tell them apart.
+
+The rule the rest of this codebase is built on gets its final expression
+here: **a technical failure never becomes a security statement.** A scan
+that did not complete is UNVERIFIED, which is not a bad score -- it is the
+absence of a score, and the ranking layer refuses to recommend it at all.
+
+The four levels:
+
+* `UNVERIFIED` -- no completed scan. Nothing may be concluded, in either
+  direction. This is a floor: no other signal can lift a candidate out of it.
+* `LOW` -- scanned, but with a material problem: two scanners disagreed
+  substantially, or the reference could not be pinned to a digest and the
+  registry could not confirm it.
+* `MEDIUM` -- scanned and consistent, with some evidence missing (no second
+  scanner, no digest, or thin hardening coverage).
+* `HIGH` -- scanned, pinned to a digest, confirmed in its registry, and
+  corroborated by a second scanner that agreed.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import NamedTuple
+
+
+class Confidence(StrEnum):
+    UNVERIFIED = "UNVERIFIED"
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+
+    @property
+    def is_recommendable(self) -> bool:
+        """Whether a candidate at this confidence may be presented as a pick.
+
+        UNVERIFIED never is. LOW may be shown -- with its reasons -- but the
+        ranking layer will not put it above a comparable MEDIUM/HIGH result.
+        """
+        return self is not Confidence.UNVERIFIED
+
+
+#: Ordering for comparisons, worst first. Written out rather than relying on
+#: declaration order, so a future level inserted in the middle cannot
+#: silently reorder existing comparisons.
+CONFIDENCE_ORDER: tuple[Confidence, ...] = (
+    Confidence.UNVERIFIED,
+    Confidence.LOW,
+    Confidence.MEDIUM,
+    Confidence.HIGH,
+)
+
+
+def confidence_rank(level: Confidence) -> int:
+    return CONFIDENCE_ORDER.index(level)
+
+
+class ConfidenceInputs(NamedTuple):
+    """The facts that decide a confidence level.
+
+    A plain record rather than a reference to the analysis DTO: the domain
+    must not depend on the application layer, and stating the inputs
+    explicitly makes the rule below auditable in one screen.
+    """
+
+    #: The primary scan completed and produced a parsed result.
+    scan_verified: bool
+    #: A second scanner ran and produced a comparable result.
+    cross_validated: bool = False
+    #: A second scanner ran and disagreed materially with the first.
+    scanners_disagree: bool = False
+    #: A second scanner ran and differed on individual findings without the
+    #: disagreement being material. Two vulnerability databases legitimately
+    #: differ at the margins, so this does not refute the result -- but it is
+    #: not the clean corroboration that HIGH is meant to represent either.
+    scanners_differ_slightly: bool = False
+    #: The candidate is pinned to a manifest digest.
+    digest_resolved: bool = False
+    #: The registry that owns the reference confirmed the tag exists.
+    #: Tri-state upstream (None = not checked); False is a real refutation.
+    registry_verified: bool | None = None
+    #: Share of the hardening model that could be determined, 0.0-1.0.
+    hardening_coverage: float = 0.0
+
+
+#: Hardening coverage below which the evidence is considered thin. Matches
+#: the reporting threshold of the hardening model itself, so a score that is
+#: not worth printing cannot silently prop up a HIGH confidence.
+THIN_COVERAGE = 0.25
+
+
+class ConfidenceAssessment:
+    """Derives a confidence level and the reasons behind it."""
+
+    def __init__(self, inputs: ConfidenceInputs):
+        self._inputs = inputs
+        self._reasons: list[str] = []
+        self._level = self._assess()
+
+    @property
+    def level(self) -> Confidence:
+        return self._level
+
+    @property
+    def reasons(self) -> list[str]:
+        """Why this level, in the reader's terms. Never empty."""
+        return list(self._reasons)
+
+    def _assess(self) -> Confidence:
+        i = self._inputs
+
+        # The floor. Checked first and returned immediately: nothing below
+        # is allowed to reason its way past a missing measurement.
+        if not i.scan_verified:
+            self._reasons.append("no completed scan: nothing was measured")
+            return Confidence.UNVERIFIED
+
+        if i.registry_verified is False:
+            self._reasons.append("the registry that owns this reference does not have this tag")
+            return Confidence.LOW
+
+        if i.scanners_disagree:
+            self._reasons.append("two scanners disagreed materially on the vulnerability counts")
+            return Confidence.LOW
+
+        if not i.digest_resolved and i.registry_verified is not True:
+            self._reasons.append("reference is not pinned to a digest and was not confirmed")
+            return Confidence.LOW
+
+        gaps: list[str] = []
+        if not i.cross_validated:
+            gaps.append("only one scanner ran")
+        if i.scanners_differ_slightly:
+            gaps.append("the second scanner differed on individual findings")
+        if not i.digest_resolved:
+            gaps.append("no manifest digest resolved")
+        if i.hardening_coverage < THIN_COVERAGE:
+            gaps.append("little of the image configuration could be inspected")
+
+        if gaps:
+            self._reasons.extend(gaps)
+            return Confidence.MEDIUM
+
+        self._reasons.append("scanned, pinned to a digest, confirmed in its registry")
+        if i.cross_validated:
+            self._reasons.append("corroborated by a second scanner that agreed")
+        return Confidence.HIGH