dockerls 1.0.0__py3-none-any.whl

dockerls/domain/value_objects/vex.py

@@ -0,0 +1,249 @@
+"""O `.dockerls-ignore.yaml` dito em OpenVEX, sem inventar a afirmação.
+
+Um arquivo de isenção já é um documento VEX em tudo menos no formato: ele
+tem o CVE, tem a justificativa e tem o prazo. O que faltava era emiti-lo
+num formato que o resto do mundo lê -- Trivy e Grype consomem OpenVEX
+nativamente --, para que uma exceção decidida uma vez valesse no pipeline
+inteiro em vez de só dentro desta ferramenta.
+
+**A parte difícil, e é onde quase toda implementação erra.** VEX tem quatro
+estados, e o que quase todo mundo emite para uma isenção é `not_affected`.
+Mas `not_affected` é uma afirmação **técnica**: diz que o código vulnerável
+não está presente, ou não é alcançável, ou já está mitigado -- e o padrão
+exige que se diga qual das cinco razões é, de um vocabulário fechado.
+
+Uma justificativa em texto livre como "a equipe aceitou o risco até o Q3"
+não é nenhuma das cinco. Traduzi-la para `not_affected` seria transformar
+uma decisão de risco numa afirmação técnica que ninguém fez -- exatamente o
+tipo de substituição que este projeto existe para não cometer.
+
+Então:
+
+* se a regra **declara** uma das cinco justificativas do padrão, o
+  documento sai como `not_affected` com ela;
+* se não declara, sai como `affected` com um `action_statement` carregando
+  o texto que a pessoa escreveu. O consumidor vê a exceção, vê o motivo, e
+  não recebe uma alegação técnica que a ferramenta inventou.
+
+O prazo entra no `action_statement` porque VEX não tem campo para
+expiração: uma isenção sem prazo visível é uma isenção que ninguém revisa.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from datetime import date
+
+#: A versão do vocabulário que este módulo emite.
+OPENVEX_CONTEXT = "https://openvex.dev/ns/v0.2.0"
+
+
+class VexStatus(StrEnum):
+    """Os quatro estados do padrão. Não há um quinto para "risco aceito"."""
+
+    NOT_AFFECTED = "not_affected"
+    AFFECTED = "affected"
+    FIXED = "fixed"
+    UNDER_INVESTIGATION = "under_investigation"
+
+
+class VexJustification(StrEnum):
+    """O vocabulário fechado que `not_affected` exige.
+
+    Fechado é o ponto: cada uma destas é uma afirmação verificável sobre o
+    código, e é por isso que texto livre não cabe aqui.
+    """
+
+    COMPONENT_NOT_PRESENT = "component_not_present"
+    VULNERABLE_CODE_NOT_PRESENT = "vulnerable_code_not_present"
+    VULNERABLE_CODE_NOT_IN_EXECUTE_PATH = "vulnerable_code_not_in_execute_path"
+    VULNERABLE_CODE_CANNOT_BE_CONTROLLED_BY_ADVERSARY = (
+        "vulnerable_code_cannot_be_controlled_by_adversary"
+    )
+    INLINE_MITIGATIONS_ALREADY_EXIST = "inline_mitigations_already_exist"
+
+
+def parse_justification(value: str) -> VexJustification | None:
+    """A justificativa do padrão, ou None quando o texto não é uma delas.
+
+    None não é erro: é o caso normal. A maioria das isenções é decisão de
+    risco, e o documento sai como `affected` por causa disso.
+    """
+    try:
+        return VexJustification(value.strip().lower())
+    except ValueError:
+        return None
+
+
+class InvalidVexStatementError(ValueError):
+    """Uma afirmação que o padrão não permite emitir.
+
+    `ValueError` porque a CLI já trata `ValueError` como erro de uso. Ela é
+    levantada na construção, e não na serialização, para que o documento
+    inválido nunca chegue a existir.
+    """
+
+
+@dataclass(frozen=True)
+class VexStatement:
+    """Uma afirmação sobre um CVE num produto."""
+
+    cve: str
+    status: VexStatus
+    justification: VexJustification | None = None
+    action_statement: str = ""
+
+    def __post_init__(self) -> None:
+        """`not_affected` sem justificativa é a afirmação vazia que o padrão
+        proíbe -- e a que este módulo inteiro existe para não emitir.
+
+        O OpenVEX exige uma das cinco justificativas para `not_affected`
+        justamente porque o estado é uma alegação técnica: sem a
+        justificativa ele diz "o CVE não se aplica" sem dizer o que foi
+        verificado, e um consumidor que o leia suprime o achado com base em
+        nada. `statement_for` nunca constrói isso; o invariante mora aqui
+        porque a classe é pública e outro chamador o construiria sem saber.
+
+        Também recusa um CVE vazio: uma afirmação sobre nenhuma
+        vulnerabilidade não é uma afirmação, e num documento ela vira uma
+        entrada que casa com o que o consumidor decidir.
+        """
+        if not self.cve.strip():
+            raise InvalidVexStatementError(
+                "a VEX statement needs a vulnerability identifier: a statement about "
+                "no CVE asserts nothing, and consumers match it against whatever they like"
+            )
+        if self.status is VexStatus.NOT_AFFECTED and self.justification is None:
+            raise InvalidVexStatementError(
+                f"'not_affected' for {self.cve} needs one of the five OpenVEX "
+                "justifications: without one it claims the vulnerability does not "
+                "apply without saying what was checked, and a consumer would suppress "
+                "the finding on the strength of nothing. Use 'affected' with an "
+                "action_statement to record an accepted risk"
+            )
+        if self.justification is not None and self.status is not VexStatus.NOT_AFFECTED:
+            raise InvalidVexStatementError(
+                f"a justification only belongs on 'not_affected'; {self.cve} is "
+                f"'{self.status}'. The vocabulary describes why the vulnerable code "
+                "cannot be reached, which says nothing about a product that is affected"
+            )
+
+    def to_dict(self, products: Sequence[str], timestamp: str) -> dict[str, Any]:
+        statement: dict[str, Any] = {
+            "vulnerability": {"name": self.cve},
+            "products": [{"@id": product} for product in products],
+            "status": str(self.status),
+            "timestamp": timestamp,
+        }
+        if self.justification is not None:
+            statement["justification"] = str(self.justification)
+        if self.action_statement:
+            # `action_statement` é o campo que o padrão prevê para
+            # `affected`, e é onde o texto humano cabe sem virar alegação
+            # técnica.
+            statement["action_statement"] = self.action_statement
+        return statement
+
+
+@dataclass(frozen=True)
+class VexDocument:
+    """Um documento OpenVEX pronto para ser lido por outra ferramenta."""
+
+    author: str
+    products: tuple[str, ...]
+    statements: tuple[VexStatement, ...]
+    timestamp: str = ""
+    version: int = 1
+
+    def to_dict(self) -> dict[str, Any]:
+        stamp = self.timestamp or datetime.now(tz=UTC).isoformat()
+        return {
+            "@context": OPENVEX_CONTEXT,
+            # O `@id` precisa ser estável para o mesmo conteúdo e diferente
+            # para conteúdos diferentes; derivá-lo do documento é o que
+            # torna dois arquivos comparáveis sem abrir os dois.
+            "@id": f"https://openvex.dev/docs/dockerls/{self._fingerprint(stamp)}",
+            "author": self.author,
+            "timestamp": stamp,
+            "version": self.version,
+            "statements": [s.to_dict(self.products, stamp) for s in self.statements],
+        }
+
+    def to_json(self, *, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, sort_keys=False)
+
+    def _fingerprint(self, stamp: str) -> str:
+        import hashlib
+
+        material = "|".join(
+            [self.author, stamp, *self.products, *(f"{s.cve}:{s.status}" for s in self.statements)]
+        )
+        return hashlib.sha256(material.encode("utf-8")).hexdigest()[:32]
+
+
+@dataclass(frozen=True)
+class ExemptionInput:
+    """O que uma regra de isenção traz, sem depender do modelo que a leu."""
+
+    cve: str
+    justification: str = ""
+    expires: date | None = None
+    #: A justificativa do padrão, quando quem escreveu declarou uma.
+    vex_justification: str = ""
+    extra: dict[str, str] = field(default_factory=dict)
+
+
+def statement_for(exemption: ExemptionInput) -> VexStatement:
+    """Traduz uma isenção, sem transformar risco aceito em alegação técnica."""
+    declared = parse_justification(exemption.vex_justification)
+    if declared is not None:
+        return VexStatement(
+            cve=exemption.cve,
+            status=VexStatus.NOT_AFFECTED,
+            justification=declared,
+            action_statement=_with_expiry("", exemption),
+        )
+    return VexStatement(
+        cve=exemption.cve,
+        status=VexStatus.AFFECTED,
+        action_statement=_with_expiry(
+            exemption.justification or "exempted in .dockerls-ignore.yaml, with no reason given",
+            exemption,
+        ),
+    )
+
+
+def _with_expiry(text: str, exemption: ExemptionInput) -> str:
+    """Anexa o prazo, que o VEX não tem campo para carregar.
+
+    Uma isenção sem prazo visível é uma isenção que ninguém revisa, e o
+    prazo é justamente a parte que o arquivo de origem sabe e o documento
+    perderia.
+    """
+    if exemption.expires is None:
+        return text
+    note = f"exemption expires on {exemption.expires.isoformat()}"
+    return f"{text}; {note}" if text else note
+
+
+def build_document(
+    exemptions: Sequence[ExemptionInput],
+    *,
+    products: Sequence[str],
+    author: str,
+    timestamp: str = "",
+) -> VexDocument:
+    """Monta o documento a partir das isenções ativas."""
+    return VexDocument(
+        author=author,
+        products=tuple(products),
+        statements=tuple(statement_for(e) for e in exemptions),
+        timestamp=timestamp,
+    )

dockerls/exit_codes.py

@@ -0,0 +1,23 @@
+"""The exit code contract every DockerLs command honours.
+
+A pipeline can only branch on these numbers, so they are defined once here
+instead of appearing as integer literals scattered through the CLI. The same
+table is documented in the README under "Exit codes".
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+# The command ran and nothing violated a policy.
+EXIT_OK: Final[int] = 0
+
+# The command could not run to completion: a missing dependency, a network
+# failure, a Dockerfile that does not exist, a failing `docker build`.
+# Nothing was measured, so the result says nothing about security.
+EXIT_ERROR: Final[int] = 1
+
+# The command ran fine and the result violates a policy: a validation check
+# failed (`errors > 0`), or `--fail-on` was triggered. This is the code a
+# pipeline gate should treat as "the image is not allowed through".
+EXIT_POLICY: Final[int] = 2

dockerls/exporters/base.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from dockerls.application.dto.analysis import AnalysisResult
+
+
+class ExporterInterface(ABC):
+    def export(self, result: AnalysisResult, output_path: Path) -> None:
+        output_path.write_bytes(self.export_string(result).encode("utf-8"))
+
+    @abstractmethod
+    def export_string(self, result: AnalysisResult) -> str: ...

dockerls/exporters/csv_exporter.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import csv
+import io
+from typing import TYPE_CHECKING
+
+from dockerls.exporters.base import ExporterInterface
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from dockerls.application.dto.analysis import AnalysisResult
+
+
+class CSVExporter(ExporterInterface):
+    def export(self, result: AnalysisResult, output_path: Path) -> None:
+        output_path.write_bytes(self.export_string(result).encode("utf-8"))
+
+    def export_string(self, result: AnalysisResult) -> str:
+        output = io.StringIO()
+        writer = csv.writer(output)
+        writer.writerow(
+            [
+                "Image",
+                "Tag",
+                "Score",
+                "Tier",
+                "Critical",
+                "High",
+                "Medium",
+                "Low",
+                "Fixable",
+                "Remediation Score",
+                "EOL",
+                "LTS",
+                # Appended, never inserted: a consumer indexing by column
+                # position keeps working, and one reading the header gets
+                # the new dimensions.
+                "Source",
+                "Digest",
+                "Pinned Reference",
+                "Hardening",
+                "Hardening Coverage",
+                "Attack Surface",
+                "Confidence",
+                "Production Ready",
+                "Readiness Blockers",
+                "EOL Status",
+                "Cross Validation",
+            ]
+        )
+        for a in result.recommendations or result.alternatives:
+            writer.writerow(
+                [
+                    a.image.name,
+                    a.image.tag,
+                    a.security_score,
+                    a.tier,
+                    a.scan.critical_count,
+                    a.scan.high_count,
+                    a.scan.medium_count,
+                    a.scan.low_count,
+                    a.scan.fixable_count,
+                    a.remediation_score,
+                    a.is_eol,
+                    a.is_lts,
+                    a.image.source,
+                    a.image.digest,
+                    a.pinned_reference,
+                    # "" rather than 0 when coverage was too thin: a zero
+                    # here would be read as "no hardening", which is the
+                    # opposite of "not determined".
+                    a.hardening.score if a.hardening.reportable else "",
+                    a.hardening.coverage,
+                    a.attack_surface.score if a.attack_surface.reportable else "",
+                    a.confidence.value,
+                    a.production_ready,
+                    # Codes, semicolon-separated: a CSV consumer gating on
+                    # "NOT_MEASURED" should not have to parse a sentence.
+                    ";".join(a.readiness_blockers),
+                    a.eol_status.value,
+                    a.cross_validation,
+                ]
+            )
+        return output.getvalue()

dockerls/exporters/factory.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from dockerls.exporters.csv_exporter import CSVExporter
+from dockerls.exporters.html_exporter import HTMLExporter
+from dockerls.exporters.json_exporter import JSONExporter
+from dockerls.exporters.markdown_exporter import MarkdownExporter
+from dockerls.exporters.sarif_exporter import SARIFExporter
+
+if TYPE_CHECKING:
+    from dockerls.exporters.base import ExporterInterface
+
+
+class ExporterFactory:
+    _exporters: dict[str, type[ExporterInterface]] = {
+        "json": JSONExporter,
+        "csv": CSVExporter,
+        "html": HTMLExporter,
+        "markdown": MarkdownExporter,
+        "md": MarkdownExporter,
+        "sarif": SARIFExporter,
+    }
+
+    @classmethod
+    def create(cls, format_name: str) -> ExporterInterface:
+        key = format_name.lower()
+        if key not in cls._exporters:
+            supported = ", ".join(sorted(cls._exporters.keys()))
+            raise ValueError(f"Unsupported format: {format_name}. Supported: {supported}")
+        return cls._exporters[key]()

dockerls/exporters/html_exporter.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from dockerls.exporters.base import ExporterInterface
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from dockerls.application.dto.analysis import AnalysisResult, ImageAnalysis
+
+
+class HTMLExporter(ExporterInterface):
+    def export(self, result: AnalysisResult, output_path: Path) -> None:
+        output_path.write_bytes(self.export_string(result).encode("utf-8"))
+
+    def export_string(self, result: AnalysisResult) -> str:
+        items = result.recommendations or result.alternatives
+        rows = "\n".join(self._row(a) for a in items)
+        status = "Baseline Met" if result.baseline_met else "Alternative Recommendations"
+        return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>DockerLs Report - {_esc(result.query)}</title>
+<style>
+body {{ font-family: system-ui, sans-serif; margin: 2rem; background: #fafafa; color: #1a1a1a; }}
+h1 {{ border-bottom: 2px solid #333; padding-bottom: .5rem; }}
+table {{ border-collapse: collapse; width: 100%; margin: 1rem 0; }}
+.note {{ font-size: 0.9em; opacity: 0.8; }}
+th, td {{ border: 1px solid #ddd; padding: 8px 12px; text-align: left; }}
+th {{ background: #333; color: #fff; }}
+tr:nth-child(even) {{ background: #f2f2f2; }}
+.s {{ color: #16a34a; font-weight: bold; }}
+.a {{ color: #2563eb; font-weight: bold; }}
+.b {{ color: #d97706; font-weight: bold; }}
+.c {{ color: #dc2626; font-weight: bold; }}
+.info {{ background: #fff; padding: 1rem; border: 1px solid #ddd;
+  border-radius: 4px; margin: 1rem 0; }}
+</style>
+</head>
+<body>
+<h1>DockerLs Security Report</h1>
+<div class="info">
+<p><strong>Query:</strong> {_esc(result.query)}</p>
+<p><strong>Tags Scanned:</strong> {result.total_tags_scanned}</p>
+<p><strong>Status:</strong> {status}</p>
+</div>
+<table>
+<thead><tr>
+<th>Image</th><th>Source</th><th>Score</th><th>Tier</th>
+<th>Critical</th><th>High</th><th>Medium</th><th>Low</th>
+<th>Fixable</th><th>Remediation</th><th>EOL</th>
+<th title="higher is better">Hardening</th>
+<th title="LOWER is better">Attack Surface</th><th>Confidence</th>
+</tr></thead>
+<tbody>{rows}</tbody>
+</table>
+{self._why(result)}
+<p class="note">Hardening and attack surface are scored over the facts that could be
+determined about each image; "n/a" means too little was determined for a number to
+mean anything. Neither is summed into the security score: a well-configured image with
+CRITICAL findings is a well-configured vulnerable image.</p>
+</body>
+</html>"""
+
+    def _why(self, result: AnalysisResult) -> str:
+        """The case for the top pick, so the ranking is auditable in the report."""
+        items = result.recommendations or result.alternatives
+        if not items:
+            return ""
+        best = items[0]
+        reasons = "".join(f"<li>{_esc(reason)}</li>" for reason in best.why)
+        costs = "".join(f"<li>{_esc(cost)}</li>" for cost in best.trade_offs)
+        pinned = (
+            f"<p><strong>Pin to:</strong> <code>{_esc(best.pinned_reference)}</code></p>"
+            if best.image.digest_known
+            else ""
+        )
+        return (
+            f"<h2>Why {_esc(best.image.full_reference)}?</h2>"
+            f"<ul>{reasons}</ul>"
+            + (f"<h3>Trade-offs</h3><ul>{costs}</ul>" if costs else "")
+            + f"<p><strong>Confidence:</strong> {_esc(best.confidence.value)} "
+            f"({_esc('; '.join(best.confidence_reasons))})</p>" + pinned
+        )
+
+    def _row(self, a: ImageAnalysis) -> str:
+        t = a.tier.lower()
+        return (
+            f"<tr><td>{_esc(a.image.full_reference)}</td>"
+            f"<td>{_esc(a.image.source)}</td><td>{a.security_score}</td>"
+            f'<td class="{t}">{a.tier}</td>'
+            f"<td>{a.scan.critical_count}</td><td>{a.scan.high_count}</td>"
+            f"<td>{a.scan.medium_count}</td><td>{a.scan.low_count}</td>"
+            f"<td>{a.scan.fixable_count}</td><td>{a.remediation_score}/100</td>"
+            f"<td>{'Yes' if a.is_eol else 'No'}</td>"
+            f"<td>{f'{a.hardening.score:.0f}' if a.hardening.reportable else 'n/a'}</td>"
+            f"<td>{f'{a.attack_surface.score:.0f}' if a.attack_surface.reportable else 'n/a'}</td>"
+            f"<td>{_esc(a.confidence.value)}</td></tr>"
+        )
+
+
+def _esc(s: str) -> str:
+    return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace('"', "&quot;")

dockerls/exporters/json_exporter.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from dockerls.exporters.base import ExporterInterface
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from dockerls.application.dto.analysis import AnalysisResult
+
+
+class JSONExporter(ExporterInterface):
+    def export(self, result: AnalysisResult, output_path: Path) -> None:
+        output_path.write_bytes(self.export_string(result).encode("utf-8"))
+
+    def export_string(self, result: AnalysisResult) -> str:
+        return json.dumps(result.model_dump(), indent=2, default=str)

dockerls/exporters/markdown_exporter.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from dockerls.exporters.base import ExporterInterface
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from dockerls.application.dto.analysis import AnalysisResult
+
+
+class MarkdownExporter(ExporterInterface):
+    def export(self, result: AnalysisResult, output_path: Path) -> None:
+        output_path.write_bytes(self.export_string(result).encode("utf-8"))
+
+    def export_string(self, result: AnalysisResult) -> str:
+        items = result.recommendations or result.alternatives
+        status = "Baseline Met" if result.baseline_met else "Alternative Recommendations"
+        lines = [
+            "# DockerLs Security Report",
+            "",
+            f"**Query:** {result.query}",
+            f"**Tags Scanned:** {result.total_tags_scanned}",
+            f"**Status:** {status}",
+            "",
+            "## Results",
+            "",
+            "| Image | Source | Score | Tier | Critical | High | Medium | Low | Fixable "
+            "| Remediation | EOL | Hardening | Attack Surface | Confidence |",
+            "|-------|--------|-------|------|----------|------|--------|-----|---------"
+            "|-------------|-----|-----------|----------------|------------|",
+        ]
+        for a in items:
+            eol = "Yes" if a.is_eol else "No"
+            hardening = f"{a.hardening.score:.0f}" if a.hardening.reportable else "n/a"
+            surface = f"{a.attack_surface.score:.0f}" if a.attack_surface.reportable else "n/a"
+            lines.append(
+                f"| {a.image.full_reference} | {a.image.source} | {a.security_score} | {a.tier} "
+                f"| {a.scan.critical_count} | {a.scan.high_count} "
+                f"| {a.scan.medium_count} | {a.scan.low_count} "
+                f"| {a.scan.fixable_count} | {a.remediation_score}/100 | {eol} "
+                f"| {hardening} | {surface} | {a.confidence.value} |"
+            )
+
+        if items:
+            best = items[0]
+            lines += ["", "## Why this image", ""]
+            lines += [f"- {reason}" for reason in best.why] or ["- (no reasons recorded)"]
+            if best.trade_offs:
+                lines += ["", "### Trade-offs", ""]
+                lines += [f"- {cost}" for cost in best.trade_offs]
+            if best.image.digest_known:
+                lines += ["", f"**Pin to:** `{best.pinned_reference}`"]
+            lines += [
+                "",
+                f"**Confidence:** {best.confidence.value} ({'; '.join(best.confidence_reasons)})",
+                "",
+                "> Hardening is scored over the facts that could be determined, and its "
+                "coverage is reported with it. It is never summed into the security score: "
+                "a well-configured image with CRITICAL findings is a well-configured "
+                "vulnerable image.",
+            ]
+
+        if items and items[0].recommendation:
+            rec = items[0].recommendation
+            lines += [
+                "",
+                "## Top Recommendation",
+                "",
+                f"**Image:** {rec.image_reference}",
+                f"**Score:** {rec.security_score}",
+                f"**Summary:** {rec.summary}",
+            ]
+            if rec.steps:
+                lines += ["", "### Remediation Steps", ""]
+                for s in rec.steps:
+                    desc = s.description
+                    if s.from_value and s.to_value:
+                        desc += f" ({s.from_value} -> {s.to_value})"
+                    lines.append(f"{s.step_number}. {desc}")
+
+        lines.append("")
+        return "\n".join(lines)