dockerls 1.0.0__py3-none-any.whl

dockerls/__init__.py

@@ -0,0 +1,31 @@
+"""DockerLs: Enterprise Docker Image Security Advisor."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["__version__"]
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve `__version__` sob demanda.
+
+    `importlib.metadata` custa ~24ms para importar, e este `__init__` roda
+    antes de qualquer `dockerls.*` -- ou seja, todo comando da CLI pagava
+    esse preço, inclusive os que nunca mostram a versão. Com o
+    `__getattr__` de módulo (PEP 562) quem escreve
+    `from dockerls import __version__` continua funcionando igual, e quem
+    não escreve não paga.
+    """
+    if name != "__version__":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        resolved = version("dockerls")
+    except PackageNotFoundError:
+        # Editable/dev checkout without an installed distribution record.
+        resolved = "0.0.0+dev"
+    globals()["__version__"] = resolved
+    return resolved

dockerls/application/dto/__init__.py

@@ -0,0 +1,3 @@
+from dockerls.application.dto.analysis import AnalysisResult, ComparisonResult, ImageAnalysis
+
+__all__ = ["AnalysisResult", "ImageAnalysis", "ComparisonResult"]

dockerls/application/dto/analysis.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from dockerls.domain.entities.image import DockerImage
+from dockerls.domain.entities.image_facts import HardeningFacts
+from dockerls.domain.entities.recommendation import Recommendation
+from dockerls.domain.entities.scan_result import ScanResult
+from dockerls.domain.entities.vulnerability import Vulnerability
+from dockerls.domain.value_objects.confidence import Confidence
+from dockerls.domain.value_objects.scan_plan import DeferredTag
+from dockerls.domain.value_objects.tristate import Tristate
+
+
+class DimensionReport(BaseModel):
+    """A derived score plus everything needed to defend it.
+
+    Both the hardening and attack-surface models are computed over the
+    facts that could be determined, so the number alone is not enough: a
+    reader needs the coverage it was computed at, and the named findings on
+    either side. Carrying them together means the terminal, the JSON output
+    and every exporter show the same defence of the same number.
+    """
+
+    score: float = 0.0
+    #: Share of the model that could be determined, 0.0-1.0.
+    coverage: float = 0.0
+    #: False when coverage was too thin for the score to mean anything. The
+    #: renderers show "n/a" rather than a confident-looking number.
+    reportable: bool = False
+    #: Determined properties that counted in the image's favour.
+    positives: list[str] = Field(default_factory=list)
+    #: Determined properties that counted against it.
+    negatives: list[str] = Field(default_factory=list)
+    #: Properties nothing could establish, named rather than omitted.
+    undetermined: list[str] = Field(default_factory=list)
+
+
+class ImageAnalysis(BaseModel):
+    image: DockerImage
+    scan: ScanResult
+    security_score: float
+    tier: str
+    remediation_score: int
+    # The domain's verdict. Written **only** by the central
+    # ProductionReadiness policy (see application/services/verdict.py), never
+    # by the tier: the tier can see the score and nothing else, so it cannot
+    # tell a clean image from an image nobody managed to scan. Defaults to
+    # False so an analysis that never reached the policy is not ready by
+    # omission rather than ready by omission.
+    production_ready: bool = False
+    #: Stable codes for every rule the image failed (NOT_MEASURED,
+    #: END_OF_LIFE, ...), so a pipeline can branch without parsing prose.
+    readiness_blockers: list[str] = Field(default_factory=list)
+    #: The same blockers in the reader's terms.
+    readiness_reasons: list[str] = Field(default_factory=list)
+    # Kept as the boolean every exporter and template already reads. It
+    # answers False both for "supported" and for "nobody could tell", which
+    # is why `eol_status` carries the three-valued truth beside it.
+    is_eol: bool = False
+    #: TRUE / FALSE / UNKNOWN. An unknown lifecycle does not penalise the
+    #: score -- there is nothing to penalise -- but it is never spent as if
+    #: it were a confirmation that the release is still supported.
+    eol_status: Tristate = Tristate.UNKNOWN
+    is_lts: bool = False
+    recommendation: Recommendation | None = None
+    # Set when a second scanner disagreed materially with the primary one.
+    # A non-empty value means the score must be presented as disputed.
+    scan_divergence: str = ""
+    #: AGREEMENT / MINOR_DIVERGENCE / MATERIAL_DIVERGENCE / NO_SECOND_SCANNER.
+    #: Distinct from `scan_divergence`, which stays reserved for the material
+    #: case: two databases differing on a finding or two is ordinary, and
+    #: calling that "disputed" would make every image look contested.
+    cross_validation: str = "NO_SECOND_SCANNER"
+    #: Which findings differed, named, so the disagreement can be checked.
+    cross_validation_detail: str = ""
+    # Docker Hub linkage. `hub_tag_verified` is deliberately tri-state:
+    # True = confirmed present, False = confirmed absent, None = not checked
+    # (image not on Docker Hub, or verification unavailable).
+    hub_url: str = ""
+    hub_tag_verified: bool | None = None
+    # scanner name -> raw scan JSON path, backing the score shown above.
+    evidence_paths: dict[str, str] = Field(default_factory=dict)
+
+    # --- Multi-dimensional assessment ------------------------------------
+    # The evidence record every derived dimension below is computed from,
+    # carried so a consumer can recompute them or apply its own policy.
+    facts: HardeningFacts = Field(default_factory=HardeningFacts)
+    # How well the image is configured, independently of its CVE counts.
+    hardening: DimensionReport = Field(default_factory=DimensionReport)
+    # How much an attacker inherits inside the container. Higher is *worse*.
+    attack_surface: DimensionReport = Field(default_factory=DimensionReport)
+    # How much the evidence behind all of the above is worth. Defaults to
+    # UNVERIFIED so an analysis that skipped assessment can never read as
+    # trustworthy by omission.
+    confidence: Confidence = Confidence.UNVERIFIED
+    confidence_reasons: list[str] = Field(default_factory=list)
+    # Plain-language reasons this image ranked where it did, so a
+    # recommendation never reduces to an unexplained number.
+    why: list[str] = Field(default_factory=list)
+    # Costs and caveats of moving to this image, stated alongside the
+    # reasons. A recommendation that lists only upsides is advertising.
+    trade_offs: list[str] = Field(default_factory=list)
+    # Set when this tag has previously been observed (by an earlier run) on
+    # a *different* digest than the one just resolved. Empty when this is
+    # the first time this tag was seen, or when it has stayed on the same
+    # digest since. `base` already reports this for Dockerfile-pinned bases
+    # (see `tag_history.py`/`base_cmd.py`); this is the same fact for a tag
+    # looked up directly with `analyze`.
+    tag_drift_note: str = ""
+    # Set when a previous `analyze` run of this exact reference recorded
+    # different vulnerability counts than this scan just found. Empty on the
+    # first scan ever recorded, or when the counts are unchanged since the
+    # last one. Unlike `tag_drift_note`, this applies to a digest reference
+    # too: the same bytes can gain a CVE between two scans as the scanner's
+    # database learns about it.
+    vuln_trend_note: str = ""
+
+    @property
+    def pinned_reference(self) -> str:
+        """What to actually deploy: digest-pinned when one was resolved."""
+        return self.image.pinned_reference
+
+
+class BaselineCriteria(BaseModel):
+    """The exact thresholds an image had to clear to count as a match.
+
+    Carried on the result so "no image found matching baseline" can state
+    what the baseline actually was instead of leaving the user to guess.
+    """
+
+    max_critical: int
+    max_high: int
+    max_medium: int
+
+    def describe(self) -> str:
+        return (
+            f"{self.max_critical} Critical, "
+            f"{self.max_high} High, "
+            f"{self.max_medium} Medium (and not EOL)"
+        )
+
+
+class UnverifiedImage(BaseModel):
+    """A tag that could not be scanned successfully.
+
+    These never carry a score or a tier -- an image with no proof of a
+    successful scan is reported as unverified, not ranked.
+    """
+
+    image_reference: str
+    status: str
+    reason: str
+    # Causa classificada (DB_INIT_FAILED, TIMEOUT, NOT_FOUND, ...). O terminal
+    # mostra isto; `reason` guarda o stderr completo para log e --format json.
+    kind: str = "UNKNOWN"
+
+
+class RunMetrics(BaseModel):
+    """What the run actually did, as opposed to what it found.
+
+    The pipeline already knew every one of these numbers and discarded all
+    of them, so "why did that take four minutes" and "is the cache working"
+    were unanswerable from the outside. They are the difference between
+    tags *discovered* and scans *performed*, which the digest deduplication
+    and the cache can make very different.
+
+    Carried on the result rather than printed, so `--format json` and the
+    terminal report the same figures.
+    """
+
+    tags_discovered: int = 0
+    # Tags left after collapsing those that share a manifest digest. The gap
+    # between this and `tags_discovered` is what deduplication saved.
+    unique_digests: int = 0
+    cache_hits: int = 0
+    # Scanner invocations actually made, excluding cache hits and duplicates.
+    scans_performed: int = 0
+    cross_validations: int = 0
+    workers: int = 0
+    # Tags that arrived without a digest and were pinned to one. Each is a
+    # registry HEAD that buys deduplication across every source.
+    digests_resolved: int = 0
+    # Candidates whose OCI config was fetched and verified, which is what
+    # makes their hardening facts measurements rather than claims.
+    images_inspected: int = 0
+    #: Which scanner, at which version, produced this run's measurements.
+    #: Reported rather than assumed: two runs of the same command against the
+    #: same image are only comparable if this matches.
+    scanner_identity: str = ""
+
+    @property
+    def duplicates_collapsed(self) -> int:
+        return max(0, self.tags_discovered - self.unique_digests)
+
+    @property
+    def cache_hit_rate(self) -> float:
+        """Share of candidates answered from cache, 0.0-1.0."""
+        considered = self.cache_hits + self.scans_performed
+        return self.cache_hits / considered if considered else 0.0
+
+
+class AnalysisResult(BaseModel):
+    query: str
+    total_tags_scanned: int
+    baseline_met: bool
+    recommendations: list[ImageAnalysis] = []
+    alternatives: list[ImageAnalysis] = []
+    errors: list[str] = []
+    # Run accounting, used to render the summary line above the table.
+    total_tags_analyzed: int = 0
+    unverified: list[UnverifiedImage] = []
+    log_file: str = ""
+    evidence_manifest: str = ""
+    baseline: BaselineCriteria | None = None
+    # Catalogues that returned at least one candidate for this query.
+    sources_searched: list[str] = []
+    metrics: RunMetrics = Field(default_factory=RunMetrics)
+    #: Tags que a busca encontrou e que este run deliberadamente **não
+    #: mediu**, com o motivo de cada uma. Deliberadamente separado de
+    #: `unverified`: ali estão as medições que falharam, aqui as que nunca
+    #: foram tentadas. As duas são ausência de medição, e nenhuma das duas
+    #: é um veredito sobre a imagem -- mas confundi-las esconderia que uma
+    #: é escolha desta ferramenta e a outra é uma falha.
+    deferred: list[DeferredTag] = []
+    #: Quantas tags a busca trouxe, antes de qualquer corte.
+    tags_discovered: int = 0
+
+    @property
+    def unverified_count(self) -> int:
+        return len(self.unverified)
+
+    @property
+    def deferred_count(self) -> int:
+        return len(self.deferred)
+
+
+class ComparisonResult(BaseModel):
+    """O que a comparação mediu, e o que ela não conseguiu medir.
+
+    `images` carrega **apenas** as imagens cujo scan completou. Uma imagem
+    que ninguém conseguiu escanear não entra aqui em hipótese alguma: ela
+    tem `security_score` 0.0 e tier F por construção (o fallback de
+    `AnalyzeImageUseCase`), e uma linha na tabela de comparação com esses
+    valores afirma que a imagem foi medida e foi mal -- que é exatamente a
+    substituição que esta ferramenta existe para não fazer. As que
+    falharam ficam em `unverified`, com a causa classificada.
+    """
+
+    images: list[ImageAnalysis]
+    winner: str = ""
+    summary: str = ""
+    common_vulns: list[Vulnerability] = []
+    unique_vulns: dict[str, list[Vulnerability]] = {}
+    #: As referências pedidas que não puderam ser medidas, na ordem em que
+    #: foram pedidas. Nunca recebem score nem tier.
+    unverified: list[UnverifiedImage] = []

dockerls/application/services/alternatives_lookup.py

@@ -0,0 +1,167 @@
+"""Achar uma alternativa **medida** para uma imagem, e dizer o que ela custa.
+
+O `alternatives` já respondia isto para uma referência digitada à mão. O que
+faltava era ligar a resposta ao lugar onde a pergunta nasce: o `FROM` de um
+Dockerfile. O `base` sabia dizer que uma base apodreceu e sabia atualizar o
+digest -- e continuava propondo a mesma imagem, mais nova. Trocar `node:22`
+por `node:22` de ontem resolve a data e não resolve a escolha.
+
+Este serviço é a metade compartilhada entre os dois comandos, e existe para
+que eles não divirjam: a mesma definição de "melhor", o mesmo baseline medido,
+os mesmos trade-offs impressos ao lado dos ganhos.
+
+Duas recusas o definem:
+
+* **Sem baseline medido não há sugestão.** Se a imagem atual não pôde ser
+  escaneada, não há como afirmar que outra é melhor. O serviço devolve o
+  motivo, e quem chama reporta isso -- nunca uma alternativa apresentada
+  contra um baseline desconhecido.
+* **Uma alternativa pior não é escondida.** O plano de migração carrega
+  `score_delta` negativo quando é o caso, e quem chama decide. Filtrar
+  silenciosamente o que ficou pior transformaria a lista num argumento em vez
+  de uma medição.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from dockerls.application.services.migration import plan_migration
+
+if TYPE_CHECKING:
+    from dockerls.application.dto.analysis import ImageAnalysis
+    from dockerls.application.services.migration import MigrationPlan
+    from dockerls.application.use_cases.analyze_image import AnalyzeImageUseCase
+    from dockerls.application.use_cases.recommend_images import RecommendImagesUseCase
+
+
+@dataclass(frozen=True)
+class AlternativeSuggestion:
+    """A melhor alternativa medida para uma referência, com o custo da troca."""
+
+    reference: str
+    current: ImageAnalysis
+    candidate: ImageAnalysis
+    plan: MigrationPlan
+
+    @property
+    def improves(self) -> bool:
+        """Se a troca melhora alguma coisa que foi medida.
+
+        Um `score_delta` positivo sozinho não basta: o que decide na prática é
+        CVE a menos, e um score melhor com mais CRITICAL seria uma melhora no
+        papel.
+        """
+        return (
+            self.plan.critical_delta < 0
+            or self.plan.high_delta < 0
+            or (
+                self.plan.score_delta > 0
+                and self.plan.critical_delta <= 0
+                and self.plan.high_delta <= 0
+            )
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "for": self.reference,
+            "candidate": self.candidate.image.full_reference,
+            "pinned": self.plan.to_pinned_reference,
+            "improves": self.improves,
+            "score_delta": self.plan.score_delta,
+            "critical_delta": self.plan.critical_delta,
+            "high_delta": self.plan.high_delta,
+            "improvements": list(self.plan.improvements),
+            "trade_offs": list(self.plan.trade_offs),
+        }
+
+
+@dataclass(frozen=True)
+class AlternativeFailure:
+    """Por que não houve sugestão. Nunca confundido com "não há nada melhor"."""
+
+    reference: str
+    reason: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"for": self.reference, "reason": self.reason}
+
+
+async def best_alternative(
+    reference: str,
+    *,
+    analyzer: AnalyzeImageUseCase,
+    recommender: RecommendImagesUseCase,
+) -> AlternativeSuggestion | AlternativeFailure:
+    """A melhor alternativa medida para `reference`, ou o motivo de não haver.
+
+    O tipo de retorno é a garantia que importa: quem chama é obrigado a
+    distinguir "não achamos nada melhor" de "não conseguimos medir", porque as
+    duas coisas chegam como valores diferentes em vez de como `None`.
+    """
+    # Uma medição que não aconteceu nunca vira baseline. A frase é a mesma
+    # para as duas formas de falhar, porque significam a mesma coisa.
+    unmeasured = (
+        f"{reference} could not be scanned, so no improvement over it can be measured. "
+        "This is a technical failure, not a verdict about the image"
+    )
+    try:
+        current = await analyzer.execute(reference)
+    except (ValueError, RuntimeError) as e:
+        logger.debug(f"Could not analyze {reference}: {e}")
+        return AlternativeFailure(reference=reference, reason=unmeasured)
+
+    # A falha chega de duas formas e as duas valem o mesmo aqui. A exceção
+    # é o caso antigo; hoje um scan que não completou devolve um
+    # `ImageAnalysis` com score 0.0 e tier F por construção, e aceitá-lo
+    # como baseline faria toda candidata aparecer como uma melhora enorme
+    # sobre uma imagem que ninguém mediu -- exatamente a substituição que a
+    # primeira recusa deste módulo existe para impedir.
+    if not current.scan.is_verified:
+        return AlternativeFailure(reference=reference, reason=unmeasured)
+
+    repository = _repository_of(reference)
+    try:
+        result = await recommender.execute(repository)
+    except (ValueError, RuntimeError) as e:
+        logger.debug(f"Could not search for alternatives to {repository}: {e}")
+        return AlternativeFailure(
+            reference=reference,
+            reason=f"the search for alternatives to {repository} failed: {e}",
+        )
+
+    for candidate in result.recommendations or result.alternatives:
+        if candidate.image.full_reference == current.image.full_reference:
+            continue
+        if not candidate.confidence.is_recommendable:
+            # Uma candidata que a própria ferramenta não consegue afirmar não
+            # entra: sugerir com pouca confiança é transferir a incerteza para
+            # quem vai fazer a migração sem dizer que ela existe.
+            continue
+        return AlternativeSuggestion(
+            reference=reference,
+            current=current,
+            candidate=candidate,
+            plan=plan_migration(current, candidate),
+        )
+
+    return AlternativeFailure(
+        reference=reference,
+        reason=(
+            f"no alternative to {repository} was measured with enough confidence to be recommended"
+        ),
+    )
+
+
+def _repository_of(reference: str) -> str:
+    """A parte que a descoberta procura: `node:22@sha256:...` -> `node`."""
+    head = reference.split("@", 1)[0]
+    repository, separator, tail = head.rpartition(":")
+    # `registry:5000/app` tem `:` no host, não na tag: só é tag se o que vem
+    # depois não contiver barra.
+    if separator and "/" not in tail:
+        return repository
+    return head

dockerls/application/services/composite_repository.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from dockerls.domain.interfaces.image_repository import ImageRepositoryInterface
+
+if TYPE_CHECKING:
+    from dockerls.domain.entities.image import DockerImage
+
+
+class CompositeImageRepository(ImageRepositoryInterface):
+    """Fans a query out across every configured image source.
+
+    The primary source (Docker Hub) sets the bulk of the candidate list;
+    hardened catalogues contribute a small number of tags each. All of them
+    feed the same scan pipeline, so a hardened image wins on measured
+    vulnerabilities rather than on reputation.
+
+    A source that fails is logged and skipped -- one unreachable registry
+    must not take down a search the other sources can still answer.
+    """
+
+    def __init__(
+        self,
+        primary: ImageRepositoryInterface,
+        extra: list[ImageRepositoryInterface] | None = None,
+        extra_limit: int = 10,
+    ):
+        self._primary = primary
+        self._extra = extra or []
+        self._extra_limit = extra_limit
+
+    @property
+    def sources(self) -> list[ImageRepositoryInterface]:
+        return [self._primary, *self._extra]
+
+    async def search_tags(self, image_name: str, limit: int = 100) -> list[DockerImage]:
+        async def safe(repo: ImageRepositoryInterface, per_source_limit: int) -> list[DockerImage]:
+            try:
+                return await repo.search_tags(image_name, limit=per_source_limit)
+            except Exception as e:
+                logger.warning(f"{type(repo).__name__} search failed for {image_name}: {e}")
+                return []
+
+        results = await asyncio.gather(
+            safe(self._primary, limit),
+            *[safe(repo, self._extra_limit) for repo in self._extra],
+        )
+
+        merged: list[DockerImage] = []
+        seen: set[str] = set()
+        for source_tags in results:
+            for image in source_tags:
+                if image.full_reference in seen:
+                    continue
+                seen.add(image.full_reference)
+                merged.append(image)
+        return merged
+
+    async def get_image_metadata(self, image_name: str, tag: str) -> DockerImage | None:
+        for repo in self.sources:
+            try:
+                found = await repo.get_image_metadata(image_name, tag)
+            except Exception as e:
+                logger.warning(f"{type(repo).__name__} metadata failed for {image_name}: {e}")
+                continue
+            if found is not None:
+                return found
+        return None
+
+    async def tag_exists(self, image_name: str, tag: str) -> bool | None:
+        """Route the check to the source that owns the reference.
+
+        `image_name` here is the fully-qualified name the pipeline scanned
+        (e.g. "cgr.dev/chainguard/node"), so the owning source is whichever
+        one recognises it.
+        """
+        for repo in self.sources:
+            host = getattr(repo, "host", "")
+            if host and image_name.startswith(f"{host}/"):
+                return await _safe_tag_exists(repo, _strip_host(image_name, host), tag)
+        return await _safe_tag_exists(self._primary, image_name, tag)
+
+
+def _strip_host(image_name: str, host: str) -> str:
+    """Turn "cgr.dev/chainguard/node" back into the bare query "node" the
+    source's own `repository_for()` expects."""
+    remainder = image_name[len(host) + 1 :]
+    return remainder.split("/", 1)[1] if "/" in remainder else remainder
+
+
+async def _safe_tag_exists(
+    repo: ImageRepositoryInterface, image_name: str, tag: str
+) -> bool | None:
+    checker = getattr(repo, "tag_exists", None)
+    if not callable(checker):
+        return None
+    try:
+        result: bool | None = await checker(image_name, tag)
+    except Exception as e:
+        logger.warning(f"{type(repo).__name__} tag check failed for {image_name}:{tag}: {e}")
+        return None
+    return result