dockerls 1.0.0__py3-none-any.whl

dockerls/integrations/registry/private.py

@@ -0,0 +1,79 @@
+"""A private registry, reachable the same way any OCI Distribution V2
+registry is: host, optional namespace, and Basic credentials exchanged for
+a scoped bearer token at whatever realm the registry's 401 challenge names.
+
+This is deliberately one implementation, not one per vendor. ECR, Harbor,
+GHCR's container registry, Artifactory, and a self-hosted `registry:2` all
+speak the same protocol -- the only per-registry difference is the host,
+namespace, and how the operator obtained a password (`aws ecr
+get-login-password` for ECR, a personal access token for GHCR, a robot
+account for Harbor). None of that changes what this client sends over the
+wire, so none of it needs its own class.
+
+Configured through `Settings` (`DOCKERLS_PRIVATE_REGISTRY_HOST` and
+friends) and registered with `SourceRegistry` like every other source --
+`recommend`/`search`/`analyze`/`compare` never learn this exists as a
+distinct case.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from dockerls.integrations.registry.hardened import HardenedRepository
+
+if TYPE_CHECKING:
+    from dockerls.domain.entities.image import DockerImage
+    from dockerls.infrastructure.network.host_guard import HostGuard
+
+PRIVATE_REGISTRY = "Private Registry"
+
+
+class PrivateRegistryRepository(HardenedRepository):
+    """One organization's own registry, authenticated with Basic
+    credentials against the standard Docker Registry HTTP API V2 token
+    endpoint.
+
+    Unlike Chainguard/Distroless, whose `repositories` map is a small,
+    curated alias table for a handful of well-known ecosystem names, a
+    private registry's repository names *are* the query: `team/app`,
+    `internal/base-images/python`, whatever the organization's own naming
+    convention is. Multi-segment paths are accepted rather than refused --
+    that refusal in the base class exists to keep Chainguard/Distroless
+    from being asked about a reference that already names a different
+    registry, which does not apply here since this repository *is* the
+    registry the reference is being asked about.
+    """
+
+    source = PRIVATE_REGISTRY
+
+    def __init__(
+        self,
+        host: str,
+        namespace: str = "",
+        timeout: int = 30,
+        guard: HostGuard | None = None,
+        *,
+        username: str = "",
+        password: str = "",
+    ):
+        self.host = host
+        self.namespace = namespace
+        super().__init__(timeout=timeout, guard=guard, username=username, password=password)
+
+    def repositories_for(self, image_name: str) -> list[str]:
+        name = image_name.strip().strip("/")
+        if not name or ":" in name:
+            return []
+        if self.namespace:
+            return [f"{self.namespace}/{name}"]
+        return [name]
+
+    def _build_image(self, repository: str, tag: str, payload: dict[str, Any]) -> DockerImage:
+        # `is_official=False`: this is an organization's own image, not a
+        # vetted upstream catalogue like Docker Hub official images or
+        # Chainguard's -- it must not collect the scoring bonus those get.
+        # The base class defaults to `is_official=True`, so it is
+        # overridden explicitly rather than left to that default.
+        image = super()._build_image(repository, tag, payload)
+        return image.model_copy(update={"is_official": False})

dockerls/integrations/registry/urls.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from dockerls.integrations.dockerhub.urls import build_dockerhub_url
+
+# Browsable catalogue pages for the hardened sources. Neither registry
+# exposes a per-tag web page, so these link to the image's catalogue entry.
+_HARDENED_HOSTS = {
+    "cgr.dev": "https://images.chainguard.dev/directory/image/{repo}/versions",
+    "gcr.io": "https://console.cloud.google.com/gcr/images/{namespace}/global/{repo}",
+}
+
+
+def source_url(image_name: str, tag: str) -> str:
+    """Return a human-browsable URL for `image_name`:`tag` at its source.
+
+    Docker Hub images get their exact tag-filtered Hub URL; hardened
+    registries get their catalogue page. Returns "" when the source has no
+    known web presence.
+    """
+    hub = build_dockerhub_url(image_name, tag)
+    if hub:
+        return hub
+
+    parts = image_name.split("/")
+    if len(parts) < 3:
+        return ""
+    host, namespace, repo = parts[0], parts[1], "/".join(parts[2:])
+    template = _HARDENED_HOSTS.get(host)
+    if not template:
+        return ""
+    return template.format(
+        namespace=quote(namespace, safe=""),
+        repo=quote(repo, safe=""),
+    )

dockerls/integrations/scan_errors.py

@@ -0,0 +1,67 @@
+"""Classificação do stderr dos scanners em causas estáveis.
+
+Trivy e Grype relatam falhas como texto livre em stderr. Guardar só um
+prefixo cortado desse texto -- que era o que a tabela mostrava, produzindo
+coisas como `error in v...` -- não nomeia causa nenhuma e não permite agrupar
+93 falhas para descobrir que todas são a mesma.
+
+Aqui o texto vira um `ScanErrorKind`. A mensagem completa continua em
+`ScanResult.error_message`, indo para o arquivo de log e para `--format json`;
+esta classificação é o que aparece no terminal, e é o que decide se vale a
+pena tentar o mesmo alvo com o outro scanner.
+"""
+
+from __future__ import annotations
+
+import re
+
+from dockerls.domain.entities.scan_result import ScanErrorKind
+
+# Ordem importa: a primeira regra que casar vence, então as causas mais
+# específicas vêm antes das genéricas. "db error" aparece dentro de mensagens
+# que também mencionam "failed to download", por exemplo.
+_RULES: tuple[tuple[ScanErrorKind, re.Pattern[str]], ...] = (
+    (
+        ScanErrorKind.RATE_LIMITED,
+        re.compile(r"rate limit|too many requests|429|toomanyrequests", re.IGNORECASE),
+    ),
+    (
+        ScanErrorKind.AUTH_REQUIRED,
+        re.compile(
+            r"unauthorized|authentication required|forbidden|401|403|denied: requested access",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        ScanErrorKind.NOT_FOUND,
+        re.compile(
+            r"manifest unknown|not found|no such image|repository does not exist"
+            r"|name unknown|could not find the image|unable to find the specified image",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        ScanErrorKind.DB_INIT_FAILED,
+        re.compile(
+            r"db error|database error|init error|failed to download (?:vulnerability )?db"
+            r"|failed to initialize|unable to open database|bad database|db\.metadata"
+            r"|cache may be in use|database is locked|failed to open db",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        ScanErrorKind.TIMEOUT,
+        re.compile(r"timeout|timed out|deadline exceeded|context deadline", re.IGNORECASE),
+    ),
+)
+
+
+def classify_scanner_error(message: str) -> ScanErrorKind:
+    """Map a scanner's stderr onto a stable, groupable cause code."""
+    text = (message or "").strip()
+    if not text:
+        return ScanErrorKind.UNKNOWN
+    for kind, pattern in _RULES:
+        if pattern.search(text):
+            return kind
+    return ScanErrorKind.UNKNOWN

dockerls/integrations/scan_target.py

@@ -0,0 +1,57 @@
+"""Refuse a scan target the network policy would not let us contact.
+
+`trivy image X` and `grype X` open their own sockets. The SSRF guard that
+protects the registry inspector never saw those pulls, so a reference like
+`169.254.169.254/latest:v1` -- syntactically valid, and arriving from a CI
+variable, a config file or a pull request -- aimed the scanner's connection
+at the cloud metadata endpoint while the guarded door stayed shut.
+
+The check runs *before* the binary is invoked, and its refusal is an
+`ERROR` result with `BLOCKED_BY_POLICY`, never an empty finding list: an
+image nobody was allowed to measure has not been measured, and the whole
+pipeline already treats an unmeasured image as unverified rather than clean.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from dockerls.domain.entities.scan_result import ScanErrorKind, ScanResult, ScanStatus
+from dockerls.domain.value_objects.image_reference import registry_host_of
+
+if TYPE_CHECKING:
+    from dockerls.infrastructure.network.host_guard import HostGuard
+
+
+def blocked_target_reason(reference: str, guard: HostGuard | None) -> str:
+    """Why `reference` may not be scanned, or "" when it may.
+
+    No guard means no policy was configured for this scanner, and the answer
+    is "" -- the caller decides whether to run unguarded. Docker Hub
+    references carry no host and are never judged: contacting Docker Hub is
+    what this tool is for.
+    """
+    if guard is None:
+        return ""
+    host = registry_host_of(reference)
+    if not host:
+        return ""
+    if guard.allows(host):
+        return ""
+    return guard.explain(host)
+
+
+def blocked_scan_result(reference: str, scanner: str, reason: str) -> ScanResult:
+    """The result a refused target produces: an error, not an empty scan."""
+    logger.warning(f"Refusing to scan {reference} with {scanner}: {reason}")
+    return ScanResult(
+        image_reference=reference,
+        scanner=scanner,
+        scan_timestamp=datetime.now(tz=UTC).isoformat(),
+        status=ScanStatus.ERROR,
+        error_message=reason,
+        error_kind=ScanErrorKind.BLOCKED_BY_POLICY,
+    )