dockerls 1.0.0__py3-none-any.whl

dockerls/domain/value_objects/fleet.py

@@ -0,0 +1,174 @@
+"""Um retrato de todos os Dockerfiles de uma vez.
+
+Cada comando desta ferramenta olha para um artefato: um Dockerfile, uma
+imagem, um build. Isso resolve a pergunta de quem está com o arquivo aberto e
+não resolve nenhuma das perguntas de quem responde por trinta repositórios --
+"quantos ainda rodam como root?", "quantos fixam a base?", "por onde eu
+começo?". Sem resposta, a resposta na prática vira "por onde alguém reclamar".
+
+Este módulo é a agregação, e é pura: recebe o que foi lido de cada arquivo e
+devolve o retrato. O que ele **não** faz é tão importante quanto o que faz:
+uma varredura de frota lê Dockerfiles, não constrói imagens nem chama scanner.
+Portanto ela nunca diz que uma imagem está limpa -- ela diz o que o arquivo
+declara, e nada além. Chamar isso de "auditoria de segurança da frota" seria
+exatamente a promessa que esta ferramenta existe para não fazer.
+
+A ordenação é por número de violações e depois por caminho. O empate resolvido
+pelo caminho não é detalhe: sem ele, a mesma frota produziria uma ordem
+diferente a cada varredura, e nenhum relatório seria comparável com o
+anterior.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from dockerls.domain.value_objects.tristate import Tristate
+
+if TYPE_CHECKING:
+    from dockerls.domain.value_objects.build_policy import PolicyViolation
+
+
+@dataclass(frozen=True)
+class FleetEntry:
+    """Um Dockerfile da frota, com o que se conseguiu ler dele."""
+
+    path: str
+    #: Bases declaradas, na ordem dos `FROM`.
+    bases: tuple[str, ...] = ()
+    pinned_bases: int = 0
+    total_bases: int = 0
+    nonroot: Tristate = Tristate.UNKNOWN
+    stages: int = 1
+    violations: tuple[PolicyViolation, ...] = ()
+    #: Preenchido quando o arquivo não pôde ser lido ou analisado. Uma entrada
+    #: com erro nunca conta como conforme: é ausência de leitura.
+    error: str = ""
+
+    @property
+    def fully_pinned(self) -> bool:
+        return bool(self.total_bases) and self.pinned_bases == self.total_bases
+
+    @property
+    def readable(self) -> bool:
+        return not self.error
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "path": self.path,
+            "bases": list(self.bases),
+            "pinned_bases": self.pinned_bases,
+            "total_bases": self.total_bases,
+            "fully_pinned": self.fully_pinned,
+            "nonroot": str(self.nonroot),
+            "stages": self.stages,
+            "violations": [v.to_dict() for v in self.violations],
+            "error": self.error,
+        }
+
+
+@dataclass(frozen=True)
+class FleetReport:
+    """O retrato agregado, e a fila de trabalho que sai dele."""
+
+    root: str
+    entries: tuple[FleetEntry, ...] = field(default_factory=tuple)
+    #: Diretórios que a varredura não conseguiu percorrer. Reportar é o que
+    #: impede um relatório de parecer completo quando não é.
+    unreadable_paths: tuple[str, ...] = ()
+    #: Se a varredura parou no teto de arquivos. Um retrato truncado que não
+    #: diz que foi truncado é pior do que nenhum retrato.
+    truncated: bool = False
+    #: Se havia política declarada. Sem ela, `violations` está sempre vazio --
+    #: e isso não significa conformidade.
+    policy_applied: bool = False
+
+    @property
+    def total(self) -> int:
+        return len(self.entries)
+
+    @property
+    def readable(self) -> tuple[FleetEntry, ...]:
+        return tuple(e for e in self.entries if e.readable)
+
+    @property
+    def unreadable(self) -> tuple[FleetEntry, ...]:
+        return tuple(e for e in self.entries if not e.readable)
+
+    @property
+    def fully_pinned(self) -> int:
+        return sum(1 for e in self.readable if e.fully_pinned)
+
+    @property
+    def running_as_root(self) -> int:
+        return sum(1 for e in self.readable if e.nonroot.is_false)
+
+    @property
+    def undetermined_user(self) -> int:
+        """Arquivos em que não se conseguiu decidir o usuário.
+
+        Contado separado de `running_as_root` de propósito: juntar os dois
+        transformaria ausência de medida em acusação, e a fila de trabalho de
+        cada um é diferente."""
+        return sum(1 for e in self.readable if not e.nonroot.is_known)
+
+    @property
+    def with_violations(self) -> int:
+        return sum(1 for e in self.entries if e.violations)
+
+    @property
+    def total_violations(self) -> int:
+        return sum(len(e.violations) for e in self.entries)
+
+    def worst_first(self) -> tuple[FleetEntry, ...]:
+        """A fila de trabalho: mais violações primeiro, caminho desempata.
+
+        O desempate por caminho é o que torna duas varreduras comparáveis --
+        sem ele a mesma frota sairia em ordem diferente a cada execução.
+        """
+        return tuple(sorted(self.entries, key=lambda e: (-len(e.violations), e.path)))
+
+    def summary(self) -> str:
+        """A frase que resume o retrato sem prometer o que não foi medido."""
+        if not self.total:
+            return "no Dockerfile found"
+        partes = [
+            f"{self.total} Dockerfile(s)",
+            f"{self.fully_pinned} with every base pinned",
+        ]
+        if self.running_as_root:
+            partes.append(f"{self.running_as_root} running as root")
+        if self.undetermined_user:
+            partes.append(f"{self.undetermined_user} with an undetermined user")
+        if self.unreadable:
+            partes.append(f"{len(self.unreadable)} unreadable")
+        return ", ".join(partes)
+
+    def caveat(self) -> str:
+        """O que este relatório deliberadamente não afirma."""
+        return (
+            "this scan reads Dockerfiles: it builds no image and calls no scanner. "
+            "It reports what the files declare, and nothing about the vulnerabilities "
+            "of the images they produce"
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "root": self.root,
+            "summary": self.summary(),
+            "caveat": self.caveat(),
+            "policy_applied": self.policy_applied,
+            "truncated": self.truncated,
+            "unreadable_paths": list(self.unreadable_paths),
+            "totals": {
+                "dockerfiles": self.total,
+                "fully_pinned": self.fully_pinned,
+                "running_as_root": self.running_as_root,
+                "undetermined_user": self.undetermined_user,
+                "with_violations": self.with_violations,
+                "violations": self.total_violations,
+                "unreadable": len(self.unreadable),
+            },
+            "dockerfiles": [e.to_dict() for e in self.worst_first()],
+        }

dockerls/domain/value_objects/gate.py

@@ -0,0 +1,327 @@
+"""O que faz um build reprovar, dito como um valor e não como um `if`.
+
+O portão olhava só severidade -- `critical`, `high`, `medium`, `low` --, e
+isso era uma incoerência do projeto inteiro: a ferramenta consulta o
+catálogo CISA KEV, o EPSS e o Exploit-DB, usa os três para pontuar
+(`SecurityScore`) e para redigir o veredito, e então reprovava o build por
+um rótulo que o vendor da distro escolheu.
+
+O caso concreto que isso deixava passar: um CVE **sendo explorado hoje**,
+classificado MEDIUM pelo vendor, atravessava um `--fail-on high` sem um
+pio. E o caso inverso: um CRITICAL teórico, sem exploit publicado e com
+EPSS de 0,0003, reprovava o build. A ferramenta sabia a diferença e não a
+usava onde ela decide alguma coisa.
+
+`kev` e `epss>=N` são medições, não heurísticas -- é por isso que cabem num
+portão, e é por isso que este módulo é puro: a regra que reprova um build
+tem de ser testável sem rede, sem scanner e sem Docker.
+
+**O tristate no portão.** `kev_status` UNKNOWN significa "ninguém
+consultou", e há duas formas erradas de tratá-lo aqui. Reprovar por ele
+diria que a imagem tem CVE explorado, o que é inventar. Aprovar por ele
+gastaria a ausência de medição como tranquilidade, que é exatamente o que
+este projeto existe para não fazer -- e pior, desligaria um portão de
+segurança em silêncio numa oscilação de rede.
+
+A saída é a terceira: quem pediu `--fail-on kev` pediu que a exploração
+fosse *conferida*. Não conseguir conferir reprova o **run**, com uma
+mensagem que nomeia a causa como falta de medição e não como veredito
+sobre a imagem. São coisas diferentes e a mensagem diz qual das duas é.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from dockerls.domain.value_objects.tristate import Tristate
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+#: Limiares de severidade, do mais severo para o mais brando. Cada um
+#: reprova também tudo que for pior que ele.
+SEVERITY_THRESHOLDS: tuple[str, ...] = ("critical", "high", "medium", "low")
+
+#: `epss>=0.5`, `epss >= 0.5`, `epss>0.5`. O `>=` é o sentido pretendido; o
+#: `>` é aceito porque alguém vai escrevê-lo e recusar seria pedantismo.
+_EPSS = re.compile(r"^epss\s*>=?\s*(\d*\.?\d+)$", re.IGNORECASE)
+
+
+class GateKind(StrEnum):
+    """Sobre o que este portão pergunta."""
+
+    SEVERITY = "SEVERITY"
+    #: Listado no catálogo CISA KEV: exploração observada no mundo real.
+    KEV = "KEV"
+    #: Probabilidade EPSS de exploração nos próximos 30 dias.
+    EPSS = "EPSS"
+
+
+class GateOutcome(StrEnum):
+    """O que o portão concluiu."""
+
+    PASS = "PASS"  # noqa: S105 -- veredito de portão, não senha
+    #: Achado que dispara o portão. É um veredito sobre a imagem.
+    FAIL = "FAIL"
+    #: O portão foi pedido e não pôde ser avaliado. **Não** é um veredito
+    #: sobre a imagem: é a constatação de que a pergunta ficou sem resposta.
+    UNMEASURED = "UNMEASURED"
+
+
+class InvalidGateError(ValueError):
+    """O valor de `--fail-on` não nomeia um portão que existe."""
+
+
+@dataclass(frozen=True)
+class Finding:
+    """O mínimo que o portão precisa saber sobre um achado.
+
+    Deliberadamente não é a `Vulnerability` do domínio: o `build` carrega
+    seus achados como dicionários vindos do scanner, e obrigar uma
+    conversão só para consultar quatro campos acoplaria o portão à forma de
+    quem o chama.
+    """
+
+    cve_id: str
+    severity: str
+    kev: Tristate = Tristate.UNKNOWN
+    #: Probabilidade EPSS, ou None quando ninguém consultou. `0.0` é uma
+    #: resposta ("o FIRST pontuou em zero") e `None` é a falta dela.
+    epss: float | None = None
+    package: str = ""
+    fixed_version: str = ""
+
+    @property
+    def severity_rank(self) -> int:
+        """Posição na escala, ou -1 para uma severidade fora dela."""
+        try:
+            return SEVERITY_THRESHOLDS.index(self.severity.strip().lower())
+        except ValueError:
+            return -1
+
+
+@dataclass(frozen=True)
+class GateVerdict:
+    """O que o portão decidiu, e por quê."""
+
+    outcome: GateOutcome
+    kind: GateKind
+    #: Os achados que dispararam, na ordem em que serão mostrados.
+    offenders: tuple[Finding, ...] = ()
+    #: Frase para o humano. Nomeia a causa, nunca só "reprovou".
+    reason: str = ""
+
+    @property
+    def failed(self) -> bool:
+        """Se o build não deve prosseguir.
+
+        `UNMEASURED` conta: quem pediu o portão pediu que a pergunta fosse
+        respondida, e ela não foi.
+        """
+        return self.outcome is not GateOutcome.PASS
+
+
+@dataclass(frozen=True)
+class Gate:
+    """Um `--fail-on` já interpretado."""
+
+    kind: GateKind
+    #: Para SEVERITY, o limiar (`"high"`). Para EPSS, o piso (`0.5`).
+    severity: str = ""
+    epss_floor: float = 0.0
+    #: O texto original, para a mensagem citar o que o usuário escreveu.
+    raw: str = ""
+
+    @classmethod
+    def parse(cls, value: str) -> Gate:
+        """Interpreta o valor de `--fail-on`, ou recusa nomeando as opções.
+
+        Recusar aqui é o ponto: um limiar desconhecido caindo num
+        `return False` seria um portão que nunca reprova, em silêncio -- e
+        esse bug já existiu neste arquivo com `--fail-on medium`.
+        """
+        text = value.strip().lower()
+        if not text:
+            raise InvalidGateError("no gate was named")
+
+        if text in SEVERITY_THRESHOLDS:
+            return cls(kind=GateKind.SEVERITY, severity=text, raw=text)
+        if text == "kev":
+            return cls(kind=GateKind.KEV, raw=text)
+
+        match = _EPSS.match(text)
+        if match is not None:
+            floor = float(match.group(1))
+            if not 0.0 <= floor <= 1.0:
+                raise InvalidGateError(
+                    f"EPSS is a probability between 0 and 1; {floor} is outside it"
+                )
+            return cls(kind=GateKind.EPSS, epss_floor=floor, raw=text)
+
+        raise InvalidGateError(
+            f"unknown --fail-on gate {value!r}; expected one of "
+            f"{', '.join(SEVERITY_THRESHOLDS)}, kev, or epss>=N (e.g. epss>=0.5)"
+        )
+
+    def evaluate(
+        self, findings: Sequence[Finding], counts: Mapping[str, int] | None = None
+    ) -> GateVerdict:
+        """Decide, e diz por quê.
+
+        `counts` é a contagem por severidade do scan **completo**. Ela
+        existe porque `findings` costuma ser uma amostra: o relatório retém
+        um número limitado de achados, e deixar o portão contar a amostra
+        faria o número que reprova ser menor que o número que existe. O que
+        reprova e o que se lê têm de ser o mesmo número.
+        """
+        match self.kind:
+            case GateKind.SEVERITY:
+                return self._severity(findings, counts)
+            case GateKind.KEV:
+                return self._kev(findings)
+            case GateKind.EPSS:
+                return self._epss(findings)
+
+    def _severity(
+        self, findings: Sequence[Finding], counts: Mapping[str, int] | None
+    ) -> GateVerdict:
+        cutoff = SEVERITY_THRESHOLDS.index(self.severity)
+        levels = SEVERITY_THRESHOLDS[: cutoff + 1]
+        offenders = tuple(f for f in findings if 0 <= f.severity_rank <= cutoff)
+        total = (
+            sum(counts.get(level, 0) for level in levels) if counts is not None else len(offenders)
+        )
+        if total == 0:
+            return GateVerdict(GateOutcome.PASS, self.kind)
+        return GateVerdict(
+            GateOutcome.FAIL,
+            self.kind,
+            offenders,
+            f"{total} finding(s) at or above {self.severity.upper()}",
+        )
+
+    def _kev(self, findings: Sequence[Finding]) -> GateVerdict:
+        listed = tuple(f for f in findings if f.kev is Tristate.TRUE)
+        if listed:
+            return GateVerdict(
+                GateOutcome.FAIL,
+                self.kind,
+                listed,
+                f"{len(listed)} finding(s) are in the CISA KEV catalogue, which means "
+                "exploitation observed in the wild",
+            )
+        # Nada listado. Resta saber se a pergunta chegou a ser feita.
+        if findings and all(f.kev is Tristate.UNKNOWN for f in findings):
+            return GateVerdict(
+                GateOutcome.UNMEASURED,
+                self.kind,
+                (),
+                "the KEV gate was requested and the catalogue was never consulted, so "
+                "nothing here was checked against it. This is an absent measurement, "
+                "not a finding: the image may or may not carry an exploited CVE, and "
+                "this run cannot say which",
+            )
+        return GateVerdict(GateOutcome.PASS, self.kind)
+
+    def _epss(self, findings: Sequence[Finding]) -> GateVerdict:
+        scored = tuple(f for f in findings if f.epss is not None)
+        over = tuple(f for f in scored if f.epss is not None and f.epss >= self.epss_floor)
+        if over:
+            worst = max(f.epss or 0.0 for f in over)
+            return GateVerdict(
+                GateOutcome.FAIL,
+                self.kind,
+                over,
+                f"{len(over)} finding(s) at or above an EPSS of {self.epss_floor:g} "
+                f"(worst: {worst:.3f}), the probability of exploitation in the next "
+                "30 days",
+            )
+        if findings and not scored:
+            return GateVerdict(
+                GateOutcome.UNMEASURED,
+                self.kind,
+                (),
+                f"the EPSS gate was requested and no finding carries a score, so "
+                f"nothing here was compared against {self.epss_floor:g}. This is an "
+                "absent measurement, not a finding",
+            )
+        return GateVerdict(GateOutcome.PASS, self.kind)
+
+
+@dataclass(frozen=True)
+class GateSet:
+    """Vários portões, todos obrigatórios.
+
+    Existe porque "mais estrito" deixou de ser uma comparação possível.
+    Entre `high` e `critical` dá para dizer qual reprova mais; entre
+    `critical` e `kev` não dá -- são perguntas diferentes sobre coisas
+    diferentes, e escolher uma seria descartar a outra em silêncio.
+
+    Quando a política do repositório pede um portão e a linha de comando
+    pede outro, os dois valem. É a única regra que não afrouxa nenhum dos
+    dois lados.
+    """
+
+    gates: tuple[Gate, ...]
+
+    @classmethod
+    def parse(cls, value: str) -> GateSet:
+        """Interpreta `"critical"`, `"kev"` ou `"critical,kev,epss>=0.5"`."""
+        parts = [piece.strip() for piece in value.split(",") if piece.strip()]
+        if not parts:
+            raise InvalidGateError("no gate was named")
+        return cls(tuple(Gate.parse(part) for part in parts))
+
+    @property
+    def raw(self) -> str:
+        return ",".join(gate.raw for gate in self.gates)
+
+    def evaluate(
+        self, findings: Sequence[Finding], counts: Mapping[str, int] | None = None
+    ) -> tuple[GateVerdict, ...]:
+        """Os vereditos que **não** passaram, na ordem declarada.
+
+        Vazio significa aprovado. Devolver só as falhas é deliberado: o
+        chamador precisa listar o que reprovou, e um veredito PASS na
+        mensagem seria ruído no log do CI.
+        """
+        return tuple(
+            verdict
+            for verdict in (gate.evaluate(findings, counts) for gate in self.gates)
+            if verdict.failed
+        )
+
+
+def merge_gates(declared: str, requested: str) -> str:
+    """O portão que vale, entre a política do repositório e a linha de comando.
+
+    Severidade contra severidade continua sendo a regra antiga: vence a
+    **mais baixa na escala**, porque `--fail-on low` reprova em LOW e em
+    tudo acima enquanto `critical` só olha CRITICAL. Nem o arquivo desliga
+    o que o pipeline pediu, nem a flag afrouxa o que a organização exige.
+
+    Portões de tipos diferentes não competem: somam. Um `.dockerls-policy.yaml`
+    que exige `kev` e um `--fail-on high` na linha de comando produzem os
+    dois, porque descartar qualquer um seria afrouxar sem dizer.
+    """
+    sides = [value.strip() for value in (declared, requested) if value.strip()]
+    if not sides:
+        return ""
+    if len(sides) == 1:
+        return sides[0]
+
+    kept: list[str] = []
+    severities: list[str] = []
+    for side in sides:
+        for gate in GateSet.parse(side).gates:
+            if gate.kind is GateKind.SEVERITY:
+                severities.append(gate.severity)
+            elif gate.raw not in kept:
+                kept.append(gate.raw)
+    if severities:
+        strictest = max(severities, key=SEVERITY_THRESHOLDS.index)
+        kept.insert(0, strictest)
+    return ",".join(kept)