dockerls 1.0.0__py3-none-any.whl

dockerls/infrastructure/evidence.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+from dockerls.infrastructure.redaction import redact
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+_UNSAFE_PATH_CHARS = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def slugify_reference(reference: str) -> str:
+    """Flatten an image reference into a single safe path segment.
+
+    Deliberately collapses "/" and ":" instead of preserving them: the
+    evidence directory must stay flat and inside its root, so a reference
+    can never steer a write outside `.dockerls/scans/`.
+    """
+    slug = _UNSAFE_PATH_CHARS.sub("_", reference).strip("._-")
+    return slug[:120] or "image"
+
+
+# Backwards-compatible private alias.
+_slugify = slugify_reference
+
+
+class EvidenceStore:
+    """Persists the raw JSON emitted by each scanner so any displayed score
+    can be traced back to the exact scanner output it was derived from."""
+
+    def __init__(self, root: Path):
+        self._root = root
+
+    async def record_scan(self, image_reference: str, scanner: str, raw: str) -> str:
+        """Write one scanner's raw JSON output. Returns the file path, or an
+        empty string when the evidence could not be persisted (evidence is
+        an audit aid -- never a reason to fail a scan)."""
+        return await asyncio.to_thread(self._record_scan_sync, image_reference, scanner, raw)
+
+    def _record_scan_sync(self, image_reference: str, scanner: str, raw: str) -> str:
+        stamp = datetime.now(tz=UTC).strftime("%Y%m%dT%H%M%S%f")
+        name = f"{slugify_reference(image_reference)}__{slugify_reference(scanner)}__{stamp}.json"
+        path = self._root / name
+        try:
+            self._root.mkdir(parents=True, exist_ok=True)
+            # Redacted on the way to disk, with the same patterns the log
+            # sink uses. A raw scan artifact is the file people attach to
+            # tickets and paste into chats, and a scanner that fails an
+            # authenticated pull echoes the request it attempted -- headers
+            # included. Masking logs but not evidence covered the door
+            # nobody walks through.
+            path.write_text(redact(raw), encoding="utf-8")
+        except OSError as e:
+            logger.warning(f"Could not persist scan evidence for {image_reference}: {e}")
+            return ""
+        return str(path)
+
+    async def record_manifest(
+        self,
+        query: str,
+        entries: list[dict[str, Any]],
+        provenance: dict[str, Any] | None = None,
+    ) -> str:
+        """Write the score <-> evidence linkage for one `recommend` run."""
+        return await asyncio.to_thread(self._record_manifest_sync, query, entries, provenance)
+
+    def _record_manifest_sync(
+        self,
+        query: str,
+        entries: list[dict[str, Any]],
+        provenance: dict[str, Any] | None = None,
+    ) -> str:
+        stamp = datetime.now(tz=UTC).strftime("%Y%m%dT%H%M%S")
+        path = self._root / f"{slugify_reference(query)}__manifest__{stamp}.json"
+        payload = {
+            "query": query,
+            "generated_at": datetime.now(tz=UTC).isoformat(),
+            # What produced these numbers: which DockerLs, which scanner at
+            # which version, and the fingerprint the cache was keyed on. An
+            # analysis nobody can reconstruct is an assertion, not evidence,
+            # and until this block existed the manifest recorded the verdict
+            # without recording what reached it.
+            "provenance": provenance or {},
+            "images": entries,
+        }
+        try:
+            self._root.mkdir(parents=True, exist_ok=True)
+            path.write_text(redact(json.dumps(payload, indent=2, default=str)), encoding="utf-8")
+        except OSError as e:
+            logger.warning(f"Could not persist evidence manifest for {query}: {e}")
+            return ""
+        return str(path)

dockerls/infrastructure/hashing.py

@@ -0,0 +1,165 @@
+"""Digerir a entrada do build antes de ela virar imagem.
+
+Um relatório de segurança afirma coisas sobre uma imagem. Para a afirmação
+valer, é preciso poder responder *qual* imagem, e a partir de *qual* entrada
+-- e é aí que a cadeia arrebentava: o `build` media o resultado sem registrar
+nada sobre o que entrou. Dois builds do mesmo `--tag` produziam relatórios
+indistinguíveis mesmo partindo de Dockerfiles diferentes.
+
+O que este módulo produz é o começo dessa cadeia: um digest determinístico do
+Dockerfile e do contexto de build. Determinístico importa mais do que parece:
+o mesmo conteúdo tem de dar o mesmo hash em qualquer máquina, em qualquer
+ordem de sistema de arquivos, ou a comparação entre dois builds não significa
+nada. Por isso os caminhos entram ordenados e relativos, e o nome de cada
+arquivo entra no digest junto do conteúdo -- renomear um arquivo muda o
+contexto tanto quanto editá-lo.
+
+O `.dockerignore` é respeitado porque ele decide o que o daemon realmente
+recebe: hashear o que fica de fora produziria um digest que muda sem que a
+imagem mude, e um controle que dispara sem motivo é um controle que as
+pessoas desligam.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+#: Lido em blocos para que um contexto com artefatos grandes não seja
+#: carregado inteiro na memória só para ser digerido.
+_CHUNK_BYTES = 1024 * 1024
+
+#: Teto de arquivos digeridos. Um contexto acima disto quase sempre significa
+#: um `.dockerignore` ausente -- e é melhor recusar a medir do que devolver um
+#: digest que levou minutos e não descreve o que foi enviado.
+MAX_CONTEXT_FILES = 50_000
+
+
+class ContextTooLargeError(RuntimeError):
+    """O contexto tem mais arquivos do que se pode digerir com sentido."""
+
+
+def hash_file(path: Path) -> str:
+    """SHA-256 do conteúdo de um arquivo, em minúsculas e com prefixo."""
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        while chunk := handle.read(_CHUNK_BYTES):
+            digest.update(chunk)
+    return f"sha256:{digest.hexdigest()}"
+
+
+def hash_context(root: Path, *, dockerignore: Path | None = None) -> tuple[str, int]:
+    """Digest determinístico do contexto de build, e quantos arquivos entraram.
+
+    Devolve o par para que o relatório possa dizer *sobre o que* o digest
+    fala: um hash sozinho não distingue "contexto vazio" de "contexto que
+    ninguém conseguiu ler".
+    """
+    patterns = _ignore_patterns(dockerignore or root / ".dockerignore")
+    digest = hashlib.sha256()
+    counted = 0
+
+    for path in _walk(root, patterns):
+        counted += 1
+        if counted > MAX_CONTEXT_FILES:
+            raise ContextTooLargeError(
+                f"the build context exceeds {MAX_CONTEXT_FILES} files; "
+                "almost always that means a missing .dockerignore"
+            )
+        # O caminho entra no digest junto do conteúdo: renomear um arquivo
+        # muda o contexto tanto quanto editá-lo, e um digest que não visse o
+        # nome trataria as duas coisas como iguais.
+        relative = path.relative_to(root).as_posix()
+        digest.update(relative.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(hash_file(path).encode("ascii"))
+        digest.update(b"\n")
+
+    return f"sha256:{digest.hexdigest()}", counted
+
+
+def _walk(root: Path, patterns: list[str]) -> list[Path]:
+    """Arquivos do contexto, ordenados, sem os ignorados.
+
+    A ordenação é o que torna o digest reprodutível: a ordem em que o sistema
+    de arquivos devolve entradas não é estável entre máquinas nem entre
+    execuções, e um digest que dependesse dela seria diferente a cada vez. Por
+    isso a lista é ordenada no fim, sobre os caminhos completos -- e não a cada
+    nível durante a descida, que produziria uma ordem diferente e portanto um
+    digest diferente para o mesmo conteúdo.
+
+    **A poda acontece na descida, não depois dela.** A versão anterior
+    percorria a árvore inteira com `rglob("*")` e descartava o que o
+    `.dockerignore` excluía, o que significa abrir `.git` e `node_modules`
+    arquivo por arquivo para jogar fora cada um. Num repositório real isso é a
+    quase totalidade do trabalho: num contexto de 52.400 arquivos em que 401
+    são enviados ao daemon, 98% do tempo era gasto lendo entradas que o build
+    nunca veria. Um diretório ignorado tem todos os seus arquivos ignorados
+    pela mesma regra, então não descer nele produz exatamente o mesmo conjunto.
+    """
+    files: list[Path] = []
+    stack: list[Path] = [root]
+
+    while stack:
+        directory = stack.pop()
+        try:
+            children = list(directory.iterdir())
+        except OSError as e:
+            # Um diretório ilegível não interrompe a digestão do resto: o
+            # `.dockerignore` pode muito bem excluí-lo, e o daemon não teria
+            # recebido nada dali de qualquer forma.
+            logger.debug(f"Could not list {directory}: {e}")
+            continue
+
+        for child in children:
+            # Symlink não é seguido nem digerido, como antes: seguir um daria
+            # ao digest um conteúdo de fora do contexto.
+            if child.is_symlink():
+                continue
+            relative = child.relative_to(root).as_posix()
+            if child.is_dir():
+                if not _is_ignored(relative, patterns):
+                    stack.append(child)
+            elif child.is_file() and not _is_ignored(relative, patterns):
+                files.append(child)
+
+    # Sobre os caminhos completos, exatamente como o `sorted(rglob(...))`
+    # anterior: o digest de um contexto inalterado continua o mesmo, e um
+    # documento de procedência antigo segue comparável com um novo.
+    files.sort()
+    return files
+
+
+def _ignore_patterns(dockerignore: Path) -> list[str]:
+    if not dockerignore.is_file():
+        return []
+    patterns: list[str] = []
+    for raw in dockerignore.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = raw.strip()
+        # Negações (`!arquivo`) reincluem o que um padrão anterior tirou.
+        # Tratá-las como padrão comum excluiria exatamente o que elas mandam
+        # incluir, então ficam de fora da lista de exclusão.
+        if not line or line.startswith(("#", "!")):
+            continue
+        patterns.append(line.rstrip("/"))
+    return patterns
+
+
+def _is_ignored(relative: str, patterns: list[str]) -> bool:
+    for pattern in patterns:
+        if fnmatch.fnmatch(relative, pattern):
+            return True
+        # Um padrão de diretório cobre tudo abaixo dele: `.git` no
+        # .dockerignore significa `.git/**`, e comparar só o caminho completo
+        # deixaria passar cada arquivo lá dentro.
+        if relative.startswith(f"{pattern}/") or fnmatch.fnmatch(relative, f"{pattern}/*"):
+            return True
+        if any(fnmatch.fnmatch(part, pattern) for part in relative.split("/")[:-1]):
+            return True
+    return False

dockerls/infrastructure/logging/setup.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from dockerls.infrastructure.redaction import redact
+
+if TYPE_CHECKING:
+    from loguru import Record
+
+
+# Key names that introduce a credential, in any casing or word shape
+# ("apiKey", "api_key", "API-KEY", "dockerhub_token", "senha"). Named for
+_FILE_FORMAT = "{time:YYYY-MM-DD HH:mm:ss.SSS} | {level: <8} | {name}:{function}:{line} - {message}"
+_CONSOLE_FORMAT = (
+    "<level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan> - {message}"
+)
+
+
+def _log_filter(record: Record) -> bool:
+    record["message"] = redact(record["message"])
+    return True
+
+
+def _resolve_log_file(log_dir: Path) -> Path | None:
+    """Return a writable `<log_dir>/dockerls_<timestamp>.log`, or None when
+    no directory in the fallback chain can be created."""
+    stamp = datetime.now(tz=UTC).strftime("%Y-%m-%d_%H-%M-%S")
+    candidates = [log_dir]
+    fallback = Path.home() / ".cache" / "dockerls" / "logs"
+    if fallback != log_dir:
+        candidates.append(fallback)
+
+    for candidate in candidates:
+        try:
+            candidate.mkdir(parents=True, exist_ok=True)
+            path = candidate / f"dockerls_{stamp}.log"
+            path.touch()
+        except OSError:
+            continue
+        return path
+    return None
+
+
+# Nothing below this level ever reaches the terminal on its own. Normal CLI
+# use is not a debugging session: an INFO line on stderr is noise a pipeline
+# has to filter out, and it corrupts the Rich progress display.
+DEFAULT_CONSOLE_LEVEL = "WARNING"
+
+
+def setup_logging(
+    level: str = "INFO",
+    log_dir: Path | None = None,
+    console: bool = False,
+    console_level: str | None = None,
+) -> Path | None:
+    """Route diagnostics to a rotating log file instead of the terminal.
+
+    The CLI owns the terminal (Rich progress bars and tables), so loguru's
+    default stderr sink is always removed: scanner failures, retries and
+    debug chatter would otherwise interleave with -- and corrupt -- the
+    progress display. Set `console=True` (``--verbose``) to opt back into
+    stderr logging on top of the file sink.
+
+    `level` is the file sink's level; `console_level` is the stderr sink's
+    and defaults to WARNING regardless of `level`, so raising
+    DOCKERLS_LOG_LEVEL to DEBUG for the log file never starts spraying the
+    terminal. ``--verbose`` passes `console_level` explicitly to raise it.
+
+    Returns the active log file path so callers can point the user at it.
+    """
+    logger.remove()
+
+    log_file = _resolve_log_file(log_dir or Path("logs"))
+    if log_file is not None:
+        logger.add(
+            log_file,
+            level=level.upper(),
+            format=_FILE_FORMAT,
+            filter=_log_filter,
+            enqueue=True,
+            retention=20,
+            encoding="utf-8",
+        )
+
+    if console or log_file is None:
+        logger.add(
+            sys.stderr,
+            level=(console_level or DEFAULT_CONSOLE_LEVEL).upper(),
+            format=_CONSOLE_FORMAT,
+            filter=_log_filter,
+        )
+
+    return log_file

dockerls/infrastructure/network/guarded_client.py

@@ -0,0 +1,107 @@
+"""Apply the network policy to *every* request, not just the first one.
+
+Checking the host of a reference before opening a client is necessary and
+not sufficient. Two things happen after that check that can move the
+request somewhere else entirely, and both are controlled by the far end:
+
+* **Redirects.** `follow_redirects=True` means a registry answering `302
+  Location: http://169.254.169.254/latest/meta-data/iam/security-credentials/`
+  gets that request issued from inside the client, with the guard's verdict
+  on the *original* host still standing. The reference looked innocuous
+  because it was; the destination was chosen afterwards.
+* **`WWW-Authenticate`.** The OCI token dance takes the URL to authenticate
+  against from a header the registry sends back (`Bearer realm="..."`). That
+  is a remote party naming a URL this process will then fetch. It is the
+  same primitive as an open redirect, arriving through a different door.
+
+An `httpx` request event hook fires once per hop -- the initial request and
+every redirect -- which is exactly the granularity the policy needs. Raising
+from the hook aborts the transfer before the socket for that hop is opened.
+
+The scheme is checked in the same place. `Location: file:///etc/shadow` and
+`Location: gopher://...` are not requests this tool has any reason to make,
+and an allowlist of `http`/`https` is cheaper to reason about than an
+exhaustive list of what to refuse.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx
+from loguru import logger
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Coroutine
+    from typing import Any
+
+    from dockerls.infrastructure.network.host_guard import HostGuard
+
+#: The only schemes a hop may use. Anything else is refused by name.
+ALLOWED_SCHEMES = frozenset({"http", "https"})
+
+
+class BlockedRequestError(httpx.HTTPError):
+    """A hop the network policy refused.
+
+    Derived from `httpx.HTTPError` deliberately: every caller in this
+    codebase already treats an `HTTPError` as "could not determine", which
+    is the correct reading of a refused request. A new exception type would
+    have escaped those handlers and turned a policy decision into a crash --
+    and a crash is a worse answer than an explicit unknown.
+    """
+
+    def __init__(self, url: httpx.URL, reason: str):
+        self.url = url
+        self.reason = reason
+        super().__init__(reason)
+
+
+def guard_request(guard: HostGuard, request: httpx.Request) -> None:
+    """Raise `BlockedRequestError` unless `request` is within policy."""
+    url = request.url
+    if url.scheme not in ALLOWED_SCHEMES:
+        # httpx normalises an unsupported scheme to the empty string, so the
+        # message names what it required rather than what it got -- and the
+        # URL itself is never echoed, because a token can live in its query.
+        raise BlockedRequestError(
+            url,
+            f"Refusing a request whose scheme is not one of "
+            f"{'/'.join(sorted(ALLOWED_SCHEMES))} (got {url.scheme or 'none'}).",
+        )
+    # `url.netloc` carries any userinfo; `host` and `port` do not, and the
+    # guard must judge the name that will actually be resolved.
+    host = url.host if url.port is None else f"{url.host}:{url.port}"
+    if not host:
+        raise BlockedRequestError(url, "Refusing a request with no host.")
+    if not guard.allows(host):
+        raise BlockedRequestError(url, guard.explain(host))
+
+
+def request_hook(guard: HostGuard) -> Callable[[httpx.Request], Coroutine[Any, Any, None]]:
+    """An `httpx` async request event hook enforcing `guard` on every hop."""
+
+    async def _hook(request: httpx.Request) -> None:
+        try:
+            guard_request(guard, request)
+        except BlockedRequestError as e:
+            logger.warning(f"Blocked request to {e.url.host}: {e.reason}")
+            raise
+
+    return _hook
+
+
+def guarded_async_client(guard: HostGuard | None, **kwargs: Any) -> httpx.AsyncClient:
+    """An `httpx.AsyncClient` whose every hop is checked against `guard`.
+
+    A `None` guard builds an ordinary client: the callers that reach fixed,
+    vendor-owned endpoints (and are constructed in places with no guard to
+    hand) keep working unchanged rather than silently losing their network.
+    Those callers pass `follow_redirects=False`, so there is no second hop
+    to police in the first place.
+    """
+    if guard is None:
+        return httpx.AsyncClient(**kwargs)
+    hooks = dict(kwargs.pop("event_hooks", None) or {})
+    hooks["request"] = [*hooks.get("request", []), request_hook(guard)]
+    return httpx.AsyncClient(event_hooks=hooks, **kwargs)

dockerls/infrastructure/network/host_guard.py

@@ -0,0 +1,117 @@
+"""Resolve a host and ask the network policy whether it may be contacted.
+
+The rule lives in the domain (`NetworkPolicy`) and knows nothing about DNS.
+This is the half that performs the lookup, which is I/O and therefore
+belongs out here -- and keeping them apart is what lets the rule be tested
+exhaustively against address literals with no network at all.
+
+Answers are memoised for the lifetime of the guard: a `recommend` run asks
+about the same handful of registries once per candidate, and a name that was
+just refused does not become acceptable a millisecond later.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlsplit
+
+from loguru import logger
+
+from dockerls.domain.value_objects.network_policy import (
+    NetworkDecision,
+    NetworkPolicy,
+    hostname_of,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+class HostGuard:
+    """Decides, with DNS, whether a host is within the configured policy."""
+
+    def __init__(self, policy: NetworkPolicy | None = None):
+        self._policy = policy or NetworkPolicy()
+        self._decisions: dict[str, NetworkDecision] = {}
+
+    @property
+    def policy(self) -> NetworkPolicy:
+        return self._policy
+
+    def decide(self, host: str) -> NetworkDecision:
+        cached = self._decisions.get(host)
+        if cached is not None:
+            return cached
+
+        if self._policy.is_allowlisted(host):
+            decision = NetworkDecision.ALLOWED_BY_ALLOWLIST
+        else:
+            hostname = hostname_of(host)
+            decision = (
+                self._policy.decide_addresses(_resolve(hostname))
+                if hostname
+                else NetworkDecision.BLOCKED_UNRESOLVABLE
+            )
+        self._decisions[host] = decision
+        return decision
+
+    def allows(self, host: str) -> bool:
+        return self.decide(host) in (
+            NetworkDecision.ALLOWED,
+            NetworkDecision.ALLOWED_BY_ALLOWLIST,
+        )
+
+    def explain(self, host: str) -> str:
+        return self._policy.explain(host, self.decide(host))
+
+
+def host_of_url(url: str) -> str:
+    """O `host[:porta]` que uma URL contataria, para o guard julgar.
+
+    `HostGuard` decide sobre hosts, nunca sobre URLs, e a diferença não é
+    cosmética: entregue a URL inteira, `hostname_of` corta no dois-pontos do
+    esquema e pergunta ao DNS por `https`, que não resolve para endereço
+    nenhum -- `BLOCKED_UNRESOLVABLE` para *toda* requisição. O efeito é uma
+    recusa que se parece com decisão de política e é bug. Quem tem uma URL
+    na mão converte aqui, uma vez, em vez de cada chamador repetir a regra.
+
+    Vive na infraestrutura, e não ao lado de `hostname_of`: o domínio é
+    testado sem rede nem disco e não importa `urllib`.
+    """
+    netloc = urlsplit(url).netloc
+    if not netloc:
+        # Já era um host: `gitlab.com`, `registry.internal:5000`.
+        return url.strip()
+    # Credenciais embutidas (`user:senha@host`) trariam um dois-pontos que
+    # não é porta; o host é o que vem depois do `@`.
+    return netloc.rpartition("@")[2]
+
+
+def _resolve(hostname: str) -> list[ipaddress.IPv4Address | ipaddress.IPv6Address]:
+    """Every address `hostname` resolves to, literals included.
+
+    A failure returns an empty list, which the policy reads as
+    "unresolvable" and therefore refuses -- the safe direction: a name that
+    cannot be resolved cannot be verified either.
+    """
+    try:
+        return [ipaddress.ip_address(hostname)]
+    except ValueError:
+        pass
+    try:
+        infos: Iterable[tuple[Any, ...]] = socket.getaddrinfo(
+            hostname, None, proto=socket.IPPROTO_TCP
+        )
+    except (OSError, UnicodeError) as e:
+        logger.debug(f"Could not resolve {hostname}: {e}")
+        return []
+
+    addresses: list[ipaddress.IPv4Address | ipaddress.IPv6Address] = []
+    for info in infos:
+        try:
+            addresses.append(ipaddress.ip_address(info[4][0]))
+        except (ValueError, IndexError):
+            continue
+    return addresses