dockerls 1.0.0__py3-none-any.whl

dockerls/application/use_cases/registry_audit.py

@@ -0,0 +1,133 @@
+"""Perguntar ao registry o que ele conta sobre uma imagem publicada.
+
+A metade pura está em `domain/value_objects/registry_audit.py`. Aqui mora o
+que ela não pode fazer: falar com o registry.
+
+Cada checagem é uma pergunta com resposta de três valores, e a terceira --
+"não deu para perguntar" -- é a razão de este módulo existir em vez de uma
+sequência de `if`. Um registry que não responde sobre a assinatura produziria,
+num código com booleano, exatamente a mesma saída de um registry que respondeu
+"não há assinatura". As duas frases levam a decisões opostas.
+
+A assinatura e a atestação são procuradas onde o cosign as publica: como tags
+derivadas do digest (`sha256-<hex>.sig` e `sha256-<hex>.att`). É uma convenção
+do sigstore, não do OCI -- então a ausência delas significa "não está assinado
+*com cosign nesse esquema*", e a explicação diz isso em vez de afirmar que
+ninguém assinou nada.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from dockerls.domain.entities.image import DockerImage
+from dockerls.domain.value_objects.registry_audit import (
+    AuditCheck,
+    AuditFinding,
+    RegistryAudit,
+)
+from dockerls.domain.value_objects.tristate import Tristate
+
+if TYPE_CHECKING:
+    from dockerls.application.services.tag_history_store import TagHistoryStore
+    from dockerls.integrations.registry.inspector import RegistryInspector
+
+
+class RegistryAuditUseCase:
+    """Apura o que o protocolo OCI revela sobre uma referência publicada."""
+
+    def __init__(self, inspector: RegistryInspector, history: TagHistoryStore | None = None):
+        self._inspector = inspector
+        self._history = history
+
+    async def execute(self, reference: str) -> RegistryAudit:
+        name, tag, given_digest = _split(reference)
+        if not name:
+            return RegistryAudit(reference=reference)
+
+        digest = given_digest or await self._digest(name, tag)
+        findings = [
+            AuditFinding(
+                check=AuditCheck.RESOLVABLE,
+                state=Tristate.of(bool(digest)),
+                detail=digest,
+            ),
+            AuditFinding(
+                check=AuditCheck.PINNED_REFERENCE,
+                state=Tristate.of(bool(given_digest)),
+            ),
+            # O inspector fala com o registry sem nenhuma credencial. Ter
+            # obtido resposta *é* a medição do acesso anônimo -- não uma
+            # inferência sobre ela.
+            AuditFinding(
+                check=AuditCheck.PUBLICLY_READABLE,
+                state=Tristate.of(bool(digest)) if not given_digest else Tristate.UNKNOWN,
+            ),
+            await self._tag_stability(name, tag, given_digest=bool(given_digest)),
+        ]
+
+        if digest:
+            findings.append(await self._cosign_artifact(name, digest, AuditCheck.SIGNATURE_PRESENT))
+            findings.append(
+                await self._cosign_artifact(name, digest, AuditCheck.ATTESTATION_PRESENT)
+            )
+        else:
+            # Sem digest não há o que procurar: reportar `UNKNOWN` é a única
+            # resposta honesta, e é diferente de "não há assinatura".
+            findings.append(
+                AuditFinding(check=AuditCheck.SIGNATURE_PRESENT, state=Tristate.UNKNOWN)
+            )
+            findings.append(
+                AuditFinding(check=AuditCheck.ATTESTATION_PRESENT, state=Tristate.UNKNOWN)
+            )
+
+        return RegistryAudit(reference=reference, digest=digest, findings=tuple(findings))
+
+    async def _digest(self, name: str, tag: str) -> str:
+        try:
+            return await self._inspector.resolve_digest(DockerImage(name=name, tag=tag))
+        except Exception as e:  # pragma: no cover - rede é o caminho instável
+            logger.debug(f"Could not resolve {name}:{tag}: {e}")
+            return ""
+
+    async def _tag_stability(self, name: str, tag: str, *, given_digest: bool) -> AuditFinding:
+        """Se a tag já mudou de digest -- a evidência *medida* de mutabilidade.
+
+        A configuração de imutabilidade do registry é uma declaração; o
+        histórico é uma observação. Quando as duas discordam, a observação é
+        que descreve o que aconteceu de fato.
+        """
+        if given_digest or self._history is None:
+            return AuditFinding(check=AuditCheck.TAG_STABLE, state=Tristate.UNKNOWN)
+        history = await self._history.get(f"{name}:{tag}")
+        if history.is_empty:
+            return AuditFinding(check=AuditCheck.TAG_STABLE, state=Tristate.UNKNOWN)
+        return AuditFinding(
+            check=AuditCheck.TAG_STABLE,
+            state=Tristate.of(history.moves == 0),
+            detail=history.explain(),
+        )
+
+    async def _cosign_artifact(self, name: str, digest: str, check: AuditCheck) -> AuditFinding:
+        """Procura a tag derivada onde o cosign publica assinatura/atestação."""
+        suffix = ".sig" if check is AuditCheck.SIGNATURE_PRESENT else ".att"
+        derived = f"{digest.replace(':', '-')}{suffix}"
+        try:
+            found = await self._inspector.resolve_digest(DockerImage(name=name, tag=derived))
+        except Exception as e:  # pragma: no cover - rede é o caminho instável
+            logger.debug(f"Could not query {derived}: {e}")
+            return AuditFinding(check=check, state=Tristate.UNKNOWN)
+        # "" aqui é resposta: o registry falou e não tem essa tag. O caso de
+        # não conseguir falar cai no `except` acima, e vira UNKNOWN.
+        return AuditFinding(check=check, state=Tristate.of(bool(found)), detail=found)
+
+
+def _split(reference: str) -> tuple[str, str, str]:
+    """`nome`, `tag`, `digest` -- com os vazios explícitos."""
+    remainder, _, digest = reference.partition("@")
+    head, slash, last = remainder.rpartition("/")
+    name_part, _, tag = last.partition(":")
+    name = f"{head}{slash}{name_part}"
+    return name, tag or "latest", digest

dockerls/application/use_cases/search_images.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from dockerls.application.services.teardown import close_quietly, sources_of
+
+if TYPE_CHECKING:
+    from dockerls.domain.entities.image import DockerImage
+    from dockerls.domain.interfaces.image_repository import ImageRepositoryInterface
+
+
+class SearchImagesUseCase:
+    def __init__(self, repository: ImageRepositoryInterface):
+        self._repository = repository
+
+    async def execute(self, image_name: str, limit: int = 100) -> list[DockerImage]:
+        try:
+            return await self._repository.search_tags(image_name, limit=limit)
+        finally:
+            # The repository keeps one connection pool alive for the whole
+            # run so requests can reuse it, which makes handing it back the
+            # caller's job rather than a context manager's.
+            await close_quietly(*sources_of(self._repository))

dockerls/application/use_cases/upgrade_base.py

@@ -0,0 +1,167 @@
+"""Perguntar ao registry o que cada `FROM` aponta hoje, e propor a correção.
+
+A metade pura do trabalho está em `domain/value_objects/base_upgrade.py`. Aqui
+mora a única coisa que ela não pode fazer: falar com o registry para descobrir
+o digest que uma tag aponta *neste momento*.
+
+A comparação entre esse digest e o que está escrito no Dockerfile é o que
+detecta a base que apodreceu -- o caso que não avisa ninguém. Foi assim que
+uma base de meados de 2024 continuou sendo construída nesta imagem por meses,
+carregando duas CVEs CRITICAL do `libexpat1` que já tinham correção publicada.
+O Dockerfile estava "corretamente" fixado por digest o tempo todo; fixar sem
+nunca reavaliar é como trancar a porta e jogar fora o calendário.
+
+Uma base que o registry não soube responder fica `UNRESOLVED`, nunca
+"atualizada": é ausência de resposta, e o resto desta ferramenta é construído
+sobre a recusa de transformar isso em afirmação.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from dockerls.domain.entities.image import DockerImage
+from dockerls.domain.value_objects.base_upgrade import (
+    BaseFinding,
+    BaseStatus,
+    DeclaredBase,
+    classify,
+    parse_bases,
+    rewrite,
+)
+
+if TYPE_CHECKING:
+    from dockerls.application.services.tag_history_store import TagHistoryStore
+    from dockerls.domain.value_objects.tag_history import TagHistory
+    from dockerls.integrations.registry.inspector import RegistryInspector
+
+
+@dataclass
+class UpgradeBaseResult:
+    """O que foi encontrado e, quando pedido, o que foi aplicado."""
+
+    dockerfile: str
+    findings: list[BaseFinding] = field(default_factory=list)
+    #: Substituições escritas em disco. Zero em `--dry-run`, e zero também
+    #: quando não havia nada a mudar.
+    applied: int = 0
+    #: Conteúdo resultante, escrito ou não. Serve para mostrar o diff.
+    updated_content: str = ""
+    error: str = ""
+    #: Histórico de digests por referência (`nome:tag`), quando há onde
+    #: guardá-lo. É o que transforma "esta base mudou" em "esta base muda com
+    #: esta frequência" -- duas frases que pedem decisões diferentes.
+    histories: dict[str, TagHistory] = field(default_factory=dict)
+
+    @property
+    def outdated(self) -> list[BaseFinding]:
+        return [f for f in self.findings if f.status is BaseStatus.PINNED_STALE]
+
+    @property
+    def unpinned(self) -> list[BaseFinding]:
+        return [f for f in self.findings if f.status is BaseStatus.UNPINNED]
+
+    @property
+    def unresolved(self) -> list[BaseFinding]:
+        return [f for f in self.findings if f.status is BaseStatus.UNRESOLVED]
+
+    @property
+    def needs_action(self) -> bool:
+        return any(f.status.needs_action for f in self.findings)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "dockerfile": self.dockerfile,
+            "applied": self.applied,
+            "bases": [
+                {
+                    "line": f.base.line,
+                    "reference": f.base.reference,
+                    "stage": f.base.stage,
+                    "status": str(f.status),
+                    "explanation": f.explain(),
+                    "current_digest": f.current_digest,
+                    "proposed": f.proposed_reference,
+                    "digest_arg": f.base.digest_arg,
+                    "history": self._history_dict(f.base),
+                }
+                for f in self.findings
+            ],
+            "error": self.error,
+        }
+
+    def history_for(self, base: DeclaredBase) -> TagHistory | None:
+        return self.histories.get(_history_key(base))
+
+    def _history_dict(self, base: DeclaredBase) -> dict[str, object] | None:
+        history = self.history_for(base)
+        return history.to_dict() if history and not history.is_empty else None
+
+
+def _history_key(base: DeclaredBase) -> str:
+    return f"{base.name}:{base.tag or 'latest'}"
+
+
+class UpgradeBaseUseCase:
+    """Confere as bases de um Dockerfile contra o registry."""
+
+    def __init__(self, inspector: RegistryInspector, history: TagHistoryStore | None = None):
+        self._inspector = inspector
+        self._history = history
+
+    async def execute(
+        self, dockerfile_path: str | Path, *, apply: bool = True
+    ) -> UpgradeBaseResult:
+        path = Path(dockerfile_path)
+        if path.is_dir():
+            path = path / "Dockerfile"
+        if not path.is_file():
+            return UpgradeBaseResult(dockerfile=str(path), error=f"Dockerfile not found at {path}")
+
+        content = path.read_text(encoding="utf-8")
+        bases = parse_bases(content)
+        if not bases:
+            return UpgradeBaseResult(dockerfile=str(path), error="no FROM instruction found")
+
+        findings: list[BaseFinding] = []
+        histories: dict[str, TagHistory] = {}
+        for base in bases:
+            digest = await self._current_digest(base)
+            findings.append(classify(base, digest))
+            if self._history is not None and digest:
+                key = _history_key(base)
+                histories[key] = await self._history.observe(key, digest)
+        updated, would_apply = rewrite(content, findings)
+
+        result = UpgradeBaseResult(
+            dockerfile=str(path),
+            findings=findings,
+            updated_content=updated,
+            histories=histories,
+        )
+        if apply and would_apply and updated != content:
+            try:
+                path.write_text(updated, encoding="utf-8")
+            except OSError as e:
+                # Não conseguir escrever não invalida o diagnóstico: o
+                # relatório continua válido e a pessoa aplica à mão.
+                result.error = f"could not write {path}: {e}"
+                return result
+            result.applied = would_apply
+        return result
+
+    async def _current_digest(self, base: DeclaredBase) -> str:
+        """O digest que a tag aponta agora, ou "" quando não deu para perguntar."""
+        name = getattr(base, "name", "")
+        tag = getattr(base, "tag", "") or "latest"
+        if not name:
+            return ""
+        try:
+            return await self._inspector.resolve_digest(DockerImage(name=name, tag=tag))
+        except Exception as e:  # pragma: no cover - rede é o caminho instável
+            logger.debug(f"Could not resolve the digest of {name}:{tag}: {e}")
+            return ""

dockerls/cache/sqlite_cache.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import TYPE_CHECKING, Any, NamedTuple, cast
+
+from sqlalchemy import CursorResult, delete, func, select
+from sqlalchemy.dialects.sqlite import insert as sqlite_insert
+
+from dockerls.domain.interfaces.cache_store import CacheStoreInterface
+from dockerls.infrastructure.database.models import CacheEntry, create_db_engine
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from sqlalchemy.orm import Session
+
+# Bump this when the shape of cached payloads changes so stale entries from
+# an older schema are treated as misses instead of crashing on load.
+# v2: ImageAnalysis gained verification metadata (scan evidence paths, Hub
+# tag state, scanner divergence) and ScanResult gained `evidence_path`.
+# v3: ImageAnalysis gained the assessment fields (hardening facts, hardening
+# and attack-surface reports, confidence, why/trade-offs) and ScanResult
+# gained the scanner-reported base distribution. A v2 row would still
+# *validate* against the new model -- pydantic would fill the missing fields
+# with their defaults -- and that is exactly the problem: the defaults are
+# "nothing determined" and `UNVERIFIED`, so a stale row would present an
+# image as uninspected rather than as unscanned. Orphaning the old rows
+# costs one cold run and removes the ambiguity entirely.
+# v4: ImageAnalysis gained the readiness verdict (production_ready is now
+# written by the central policy, and its default flipped to False), the
+# three-valued EOL status, and the cross-validation outcome; Vulnerability
+# gained the three-valued KEV status and the EPSS provenance fields. A v3 row
+# would validate and fill all of them with defaults -- which read as
+# "nothing determined" and would present a cached image as uninspected
+# rather than as measured.
+CACHE_SCHEMA_VERSION = "v4"
+
+
+class CacheStats(NamedTuple):
+    """What `dockerls cache stats` reports.
+
+    Entries expire lazily -- a stale row is dropped when it is next read --
+    so `expired` is the amount `dockerls cache cleanup` would reclaim right
+    now, and the gap between it and `total` is what the cache is holding on
+    to for nothing.
+    """
+
+    total: int
+    expired: int
+    size_bytes: int
+    path: str
+
+
+class SQLiteCache(CacheStoreInterface):
+    def __init__(self, db_path: Path):
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._db_path = db_path
+        self._engine, self._session_factory = create_db_engine(str(db_path))
+
+    def _session(self) -> Session:
+        return self._session_factory()
+
+    def close(self) -> None:
+        """Dispose the SQLAlchemy engine and release its pooled connection.
+
+        Nothing here ever called this: the engine opened in `__init__` lived
+        until the process exited, which is why `pytest` -- which keeps the
+        interpreter running across thousands of these -- reported unclosed
+        `sqlite3.Connection` objects (`ResourceWarning`) from tests that
+        never mention caching at all. A short-lived CLI invocation masked
+        the same leak by exiting anyway.
+        """
+        self._engine.dispose()
+
+    def __enter__(self) -> SQLiteCache:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def _versioned_key(self, key: str) -> str:
+        return f"{CACHE_SCHEMA_VERSION}:{key}"
+
+    async def get(self, key: str) -> Any | None:
+        return await asyncio.to_thread(self._get_sync, key)
+
+    def _get_sync(self, key: str) -> Any | None:
+        vkey = self._versioned_key(key)
+        with self._session() as session:
+            stmt = select(CacheEntry).where(CacheEntry.key == vkey)
+            entry = session.execute(stmt).scalar_one_or_none()
+            if entry is None:
+                return None
+            if entry.expires_at < time.time():
+                session.delete(entry)
+                session.commit()
+                return None
+            return json.loads(entry.value)
+
+    async def set(self, key: str, value: Any, ttl_seconds: int = 86400) -> None:
+        await asyncio.to_thread(self._set_sync, key, value, ttl_seconds)
+
+    def _set_sync(self, key: str, value: Any, ttl_seconds: int) -> None:
+        vkey = self._versioned_key(key)
+        serialized = json.dumps(value, default=str)
+        expires_at = time.time() + ttl_seconds
+        # Writes run on a thread pool (`asyncio.to_thread`) and `recommend`
+        # issues them concurrently, so select-then-insert had a real window:
+        # two threads could both miss and then both INSERT the same unique
+        # key. A single atomic upsert closes it -- SQLite's ON CONFLICT does
+        # the check and the write in one statement.
+        stmt = (
+            sqlite_insert(CacheEntry)
+            .values(key=vkey, value=serialized, expires_at=expires_at)
+            .on_conflict_do_update(
+                index_elements=[CacheEntry.key],
+                set_={"value": serialized, "expires_at": expires_at},
+            )
+        )
+        with self._session() as session:
+            session.execute(stmt)
+            session.commit()
+
+    async def delete(self, key: str) -> None:
+        await asyncio.to_thread(self._delete_sync, key)
+
+    def _delete_sync(self, key: str) -> None:
+        vkey = self._versioned_key(key)
+        with self._session() as session:
+            session.execute(delete(CacheEntry).where(CacheEntry.key == vkey))
+            session.commit()
+
+    async def clear(self) -> None:
+        await asyncio.to_thread(self._clear_sync)
+
+    def _clear_sync(self) -> None:
+        with self._session() as session:
+            session.execute(delete(CacheEntry))
+            session.commit()
+
+    async def cleanup_expired(self) -> int:
+        return await asyncio.to_thread(self._cleanup_expired_sync)
+
+    def _cleanup_expired_sync(self) -> int:
+        with self._session() as session:
+            stmt = delete(CacheEntry).where(CacheEntry.expires_at < time.time())
+            result = cast("CursorResult[Any]", session.execute(stmt))
+            session.commit()
+            return result.rowcount
+
+    async def stats(self) -> CacheStats:
+        return await asyncio.to_thread(self._stats_sync)
+
+    def _stats_sync(self) -> CacheStats:
+        now = time.time()
+        with self._session() as session:
+            total = session.execute(select(func.count()).select_from(CacheEntry)).scalar_one()
+            expired = session.execute(
+                select(func.count()).select_from(CacheEntry).where(CacheEntry.expires_at < now)
+            ).scalar_one()
+        return CacheStats(
+            total=int(total),
+            expired=int(expired),
+            size_bytes=self._size_on_disk(),
+            path=str(self._db_path),
+        )
+
+    def _size_on_disk(self) -> int:
+        """Bytes the cache occupies, including the WAL sidecar.
+
+        The write-ahead log holds committed data that has not been
+        checkpointed back into the main file yet, so reporting only the
+        `.db` would understate the footprint -- sometimes by most of it.
+        """
+        total = 0
+        for suffix in ("", "-wal", "-shm"):
+            part = self._db_path.with_name(self._db_path.name + suffix)
+            try:
+                total += part.stat().st_size
+            except OSError:
+                continue
+        return total

dockerls/cli/analysis_baseline.py

@@ -0,0 +1,98 @@
+"""Cross-referencing a `build` run against an earlier `analyze-dockerfile`.
+
+`analyze-dockerfile` and `build` both validate the same Dockerfile -- build
+always does it as its first step -- but the two commands ran as two
+separate documents, with no way to say whether what `analyze-dockerfile`
+found earlier was actually fixed by the time `build` ran. This closes that
+gap for whoever passes `analyze-dockerfile --output <file>` into `build
+--compare-to-analysis <file>`: nothing is inferred that either command did
+not already measure, this only compares the two results check by check.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from dockerls.domain.entities.dockerfile_analysis import DockerfileValidationResult
+
+
+class BaselineLoadError(ValueError):
+    """The file at `--compare-to-analysis` is not a usable analyze-dockerfile report."""
+
+
+@dataclass(frozen=True)
+class AnalysisComparison:
+    """What changed, check by check, between the earlier report and now."""
+
+    #: Checks that were FAIL or WARN in the baseline and still are now.
+    still_present: tuple[str, ...] = ()
+    #: Checks that were FAIL or WARN in the baseline and are PASS now.
+    resolved: tuple[str, ...] = ()
+    #: Checks that are FAIL or WARN now but were not flagged in the baseline.
+    newly_introduced: tuple[str, ...] = ()
+
+    @property
+    def baseline_total(self) -> int:
+        return len(self.still_present) + len(self.resolved)
+
+    def model_dump(self) -> dict[str, object]:
+        return {
+            "still_present": list(self.still_present),
+            "resolved": list(self.resolved),
+            "newly_introduced": list(self.newly_introduced),
+        }
+
+
+def load_baseline_findings(path: str | Path) -> dict[str, str]:
+    """The FAIL/WARN check names from a report `analyze-dockerfile --output`
+    wrote, as `{check_name: status}`.
+
+    Raises `BaselineLoadError` for anything that is not that document --
+    missing file, invalid JSON, or JSON that is valid but is not an
+    analyze-dockerfile report -- so the caller can report one clear cause
+    instead of a `KeyError` three lines deep.
+    """
+    try:
+        raw = Path(path).read_text(encoding="utf-8")
+    except OSError as e:
+        raise BaselineLoadError(f"could not read {path}: {e}") from e
+    try:
+        document = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise BaselineLoadError(f"{path} is not valid JSON: {e}") from e
+
+    validation = document.get("validation") if isinstance(document, dict) else None
+    if not isinstance(validation, dict):
+        raise BaselineLoadError(
+            f"{path} does not look like an analyze-dockerfile report (no 'validation' key)"
+        )
+    checks = validation.get("checks")
+    if not isinstance(checks, list):
+        raise BaselineLoadError(f"{path} has no 'validation.checks' list to compare against")
+
+    return {
+        check["check"]: check["status"]
+        for check in checks
+        if isinstance(check, dict)
+        and check.get("status") in ("FAIL", "WARN")
+        and isinstance(check.get("check"), str)
+    }
+
+
+def compare(baseline: dict[str, str], current: DockerfileValidationResult) -> AnalysisComparison:
+    """Baseline FAIL/WARN checks against the checks in `current`."""
+    current_bad = {
+        c.check: c.status.value for c in current.checks if c.status.value in ("FAIL", "WARN")
+    }
+
+    still_present = tuple(sorted(name for name in baseline if name in current_bad))
+    resolved = tuple(sorted(name for name in baseline if name not in current_bad))
+    newly_introduced = tuple(sorted(name for name in current_bad if name not in baseline))
+
+    return AnalysisComparison(
+        still_present=still_present, resolved=resolved, newly_introduced=newly_introduced
+    )