dockerls 1.0.0__py3-none-any.whl

dockerls/cli/validators.py

@@ -0,0 +1,35 @@
+"""Typer-facing adapters over the pure validators in ``dockerls.utils.validation``.
+
+They exist so an out-of-range option produces a readable CLI error instead of
+either a raw ``ValueError`` traceback or -- worse, in the case of
+``--workers 0`` -- a scan loop that blocks forever on a semaphore nobody can
+acquire.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from dockerls.utils.validation import validate_threshold, validate_workers
+
+
+def _hint(param: str) -> str:
+    return "--" + param.replace("_", "-")
+
+
+def check_threshold(value: int, param: str, *, minimum: int = 0) -> int:
+    try:
+        return validate_threshold(value, param, minimum=minimum)
+    except ValueError as e:
+        raise typer.BadParameter(str(e), param_hint=_hint(param)) from e
+
+
+def check_limit(value: int, param: str = "limit") -> int:
+    return check_threshold(value, param, minimum=1)
+
+
+def check_workers(value: int, param: str = "workers") -> int:
+    try:
+        return validate_workers(value, param)
+    except ValueError as e:
+        raise typer.BadParameter(str(e), param_hint=_hint(param)) from e

dockerls/cli/vulnerability_view.py

@@ -0,0 +1,154 @@
+"""Apresentação de listas de vulnerabilidades.
+
+Vive na camada de apresentação de propósito: ordenar para leitura humana e
+escolher rótulo de coluna são decisões de terminal, não regras de domínio. O
+que é fato sobre a vulnerabilidade -- se ela está num pacote de SO ou de
+linguagem -- mora em `Vulnerability.origin`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from dockerls.domain.entities.vulnerability import PackageOrigin
+from dockerls.domain.value_objects.tristate import Tristate
+from dockerls.integrations.exploitdb.client import EXPLOIT_URL_TEMPLATE
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from dockerls.domain.entities.vulnerability import Vulnerability
+
+# Ordem de leitura de um relatório de segurança: primeiro o que é mais grave.
+# Ordenar só por CVSS decrescente -- que era o que a tabela fazia -- empurrava
+# um CRITICAL de score 7.5 para baixo de sete HIGH de score 8.6, ou seja,
+# escondia o achado mais grave na sexta linha.
+SEVERITY_RANK = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3, "UNKNOWN": 4}
+
+_ORIGIN_LABELS = {
+    PackageOrigin.OS: "os",
+    PackageOrigin.LANGUAGE: "lang",
+    PackageOrigin.UNKNOWN: "-",
+}
+
+
+def sort_by_severity(vulns: Iterable[Vulnerability]) -> list[Vulnerability]:
+    """Severity first, then CVSS descending, then CVE id for stability."""
+    return sorted(
+        vulns,
+        key=lambda v: (
+            SEVERITY_RANK.get(v.severity.value, 4),
+            -(v.cvss_score or 0.0),
+            v.cve_id,
+        ),
+    )
+
+
+def origin_label(vuln: Vulnerability) -> str:
+    return _ORIGIN_LABELS[vuln.origin]
+
+
+def count_by_origin(vulns: Iterable[Vulnerability]) -> dict[PackageOrigin, int]:
+    counts = dict.fromkeys(PackageOrigin, 0)
+    for vuln in vulns:
+        counts[vuln.origin] += 1
+    return counts
+
+
+# Remediações que dependem de *onde* o pacote vive. A do npm é o caso que
+# motivou isto: as vulnerabilidades de `node:22-alpine` estão todas em
+# `/usr/local/lib/node_modules/npm/node_modules/`, então `apk upgrade` não
+# resolve nenhuma -- e remover o npm da imagem final resolve todas.
+_NPM_BUNDLE_MARKERS = ("node_modules/npm", "/npm/")
+
+
+def bundled_npm_findings(vulns: Iterable[Vulnerability]) -> list[Vulnerability]:
+    """Findings that come from the npm CLI bundled into the Node image."""
+    return [
+        v
+        for v in vulns
+        if v.origin is PackageOrigin.LANGUAGE
+        and any(marker in v.target.lower() for marker in _NPM_BUNDLE_MARKERS)
+    ]
+
+
+def npm_remediation_hint(vulns: Iterable[Vulnerability]) -> str:
+    """Concrete remediation for the bundled-npm case, or "" when it does not
+    apply. Returned as text so the caller decides how to render it."""
+    findings = bundled_npm_findings(vulns)
+    if not findings:
+        return ""
+    return (
+        f"{len(findings)} finding(s) come from the npm CLI bundled in the image, "
+        "not from OS packages -- `apk upgrade` / `apt upgrade` will not touch them.\n"
+        "  If npm is needed at runtime:  RUN npm install -g npm@latest\n"
+        "  If it is not (multi-stage build shipping only dist/):\n"
+        "    RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx"
+    )
+
+
+def threat_label(vuln: Vulnerability) -> str:
+    """Explorabilidade numa célula: KEV, Exploit-DB, os dois, ou nenhum dado.
+
+    Os dois sinais existiam no modelo e nunca chegavam à tela -- eram
+    calculados, entravam no score e eram descartados na exibição. Uma coluna
+    para cada custaria duas das poucas que a tabela tem sobrando, e são a
+    mesma pergunta vista de dois ângulos, então dividem uma:
+
+    * `KEV`     -- a CISA observou exploração real desta CVE;
+    * `EDB`     -- há exploit publicado no Exploit-DB, ainda não verificado;
+    * `EDB*`    -- há exploit publicado **e verificado** (alguém reproduziu);
+    * `KEV+EDB` -- os dois, com `*` quando o exploit é verificado;
+    * `No`      -- as fontes responderam e nenhuma lista esta CVE;
+    * `-`       -- nada foi consultado. **Nunca** confundir com `No`.
+
+    O `-` é o motivo de a função existir: com a fonte fora do ar, imprimir
+    `No` afirmaria que não existe exploit conhecido, que é precisamente a
+    substituição -- ausência de medida virando resultado negativo -- que
+    esta ferramenta existe para não fazer.
+    """
+    kev = vuln.kev_status is Tristate.TRUE
+    edb = vuln.exploitdb_status is Tristate.TRUE
+
+    if kev and edb:
+        return "KEV+EDB*" if vuln.exploitdb_verified else "KEV+EDB"
+    if kev:
+        return "KEV"
+    if edb:
+        return "EDB*" if vuln.exploitdb_verified else "EDB"
+
+    # Sem achado positivo: só dá para dizer "não" quando alguma fonte
+    # efetivamente respondeu sobre esta CVE.
+    if vuln.kev_status is Tristate.FALSE or vuln.exploitdb_status is Tristate.FALSE:
+        return "No"
+    return "-"
+
+
+def threat_style(vuln: Vulnerability) -> str:
+    """A cor acompanha a força da evidência, não o rótulo.
+
+    Exploração observada em produção (KEV) e exploit verificado são vermelho;
+    exploit publicado mas não verificado é amarelo, porque é um sinal mais
+    fraco e mostrá-lo com o mesmo peso exageraria o que se sabe.
+    """
+    kev = vuln.kev_status is Tristate.TRUE
+    edb = vuln.exploitdb_status is Tristate.TRUE
+    if kev or (edb and vuln.exploitdb_verified):
+        return "red bold"
+    if edb:
+        return "yellow"
+    return "dim"
+
+
+def exploit_urls(vuln: Vulnerability) -> list[str]:
+    """Links para os exploits catalogados, para quem quer julgar a fonte.
+
+    Só EDB-IDs numéricos entram numa URL: o identificador vem de um CSV de
+    terceiro, e montar link com o que vier de lá é como se constrói um
+    redirecionamento para onde o atacante quiser.
+    """
+    return [
+        EXPLOIT_URL_TEMPLATE.format(edb_id=edb_id)
+        for edb_id in vuln.exploitdb_ids
+        if edb_id.isdigit()
+    ]

dockerls/domain/entities/__init__.py

@@ -0,0 +1,75 @@
+"""As entidades do domínio, resolvidas sob demanda.
+
+Mesmo motivo do `value_objects`: são todos modelos pydantic, que o pydantic
+compila no import, e o `__init__` do pacote roda antes de qualquer
+`from dockerls.domain.entities.image import DockerImage`. Reexportar tudo
+no topo cobrava 116ms de cada comando -- inclusive dos que não tocam em
+imagem nenhuma.
+
+`__getattr__` de módulo (PEP 562) preserva a API pública: quem importa
+daqui continua importando daqui, e só o submódulo do nome pedido é
+carregado.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from dockerls.domain.entities.dockerfile_analysis import (
+        DockerfileAnalysis,
+        DockerfileInfo,
+        DockerfileValidationResult,
+        HardeningRule,
+        SeverityLevel,
+        ValidationCheck,
+        ValidationStatus,
+    )
+    from dockerls.domain.entities.image import DockerImage
+    from dockerls.domain.entities.recommendation import Recommendation
+    from dockerls.domain.entities.scan_result import ScanResult
+    from dockerls.domain.entities.vulnerability import Vulnerability
+
+#: Nome público -> submódulo que o define.
+_EXPORTS = {
+    "DockerfileAnalysis": "dockerfile_analysis",
+    "DockerfileInfo": "dockerfile_analysis",
+    "DockerfileValidationResult": "dockerfile_analysis",
+    "HardeningRule": "dockerfile_analysis",
+    "SeverityLevel": "dockerfile_analysis",
+    "ValidationCheck": "dockerfile_analysis",
+    "ValidationStatus": "dockerfile_analysis",
+    "DockerImage": "image",
+    "Recommendation": "recommendation",
+    "ScanResult": "scan_result",
+    "Vulnerability": "vulnerability",
+}
+
+__all__ = [
+    "DockerImage",
+    "DockerfileAnalysis",
+    "DockerfileInfo",
+    "DockerfileValidationResult",
+    "HardeningRule",
+    "Recommendation",
+    "ScanResult",
+    "SeverityLevel",
+    "ValidationCheck",
+    "ValidationStatus",
+    "Vulnerability",
+]
+
+
+def __getattr__(name: str) -> Any:
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    value = getattr(import_module(f"{__name__}.{module}"), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

dockerls/domain/entities/declared_metadata.py

@@ -0,0 +1,147 @@
+"""What a catalogue *claims* about an image, kept separate from what was measured.
+
+Docker Hardened Images publishes declarative build definitions: which
+packages go in, which account the image runs as, when the release goes
+end-of-life. That is genuinely useful -- it is more than any registry API
+exposes -- but it describes the *intent* of a build, not the bytes that were
+published under a tag. A definition can be ahead of the registry, behind it,
+or describe a build that failed.
+
+So catalogue claims live in their own type, are always labelled as declared,
+and never substitute for a scan. `DockerLs` uses them to discover candidates
+and to explain trade-offs; the verdict still comes from resolving the digest
+and scanning the image.
+
+The asymmetry in the derived facts below is deliberate and load-bearing: a
+declared shell package proves a shell is present, but the *absence* of one
+proves nothing -- a busybox-derived base ships `/bin/sh` without ever naming
+it as a package. Presence therefore yields TRUE and absence yields UNKNOWN,
+never FALSE.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from dockerls.domain.value_objects.tristate import Tristate
+
+#: Packages that put an interactive shell in the image. Presence is proof;
+#: absence is not.
+SHELL_PACKAGES = frozenset(
+    {"bash", "busybox", "dash", "zsh", "ksh", "fish", "toybox", "ash", "shadow"}
+)
+
+#: Packages that put a package manager in the image, which is both an
+#: attack-surface item and a sign the image is a `-dev` variant.
+PACKAGE_MANAGER_PACKAGES = frozenset(
+    {"apt", "apt-get", "apk-tools", "dpkg", "rpm", "dnf", "yum", "microdnf", "zypper", "pacman"}
+)
+
+#: Compilers, fetchers and inspection utilities. Each one is a capability an
+#: attacker inherits if they reach code execution inside the container.
+DEBUG_TOOL_PACKAGES = frozenset(
+    {
+        "curl",
+        "wget",
+        "git",
+        "gcc",
+        "g++",
+        "clang",
+        "make",
+        "binutils",
+        "strace",
+        "ltrace",
+        "gdb",
+        "netcat",
+        "netcat-openbsd",
+        "nmap",
+        "tcpdump",
+        "procps",
+        "vim",
+        "nano",
+        "less",
+        "python3",
+        "perl",
+    }
+)
+
+
+class DeclaredImageMetadata(BaseModel):
+    """A catalogue's declaration about one image definition.
+
+    Frozen: a declaration is a record of what a source said at fetch time.
+    Mutating it after the fact would make the evidence trail unreliable.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    #: Which catalogue made the claim, e.g. "Docker Hardened Images".
+    catalog: str = ""
+    #: Where the claim can be read in full, so a user can audit it.
+    definition_url: str = ""
+    #: Human name of the definition ("Node.js 22.x").
+    display_name: str = ""
+    #: Fully-qualified repository the definition publishes to
+    #: ("dhi.io/node"). This is what makes a catalogue entry resolvable
+    #: against a registry; without it there is no candidate to verify.
+    registry_repository: str = ""
+    #: "runtime", "dev", "compat", ... -- a `-dev` variant deliberately
+    #: carries a shell and a package manager and must not be ranked as if
+    #: it were the hardened runtime image.
+    variant: str = ""
+    #: Account the definition says the image runs as. Empty when unstated.
+    run_as_user: str = ""
+    #: Declared platforms ("linux/amd64"), used for architecture matching.
+    platforms: tuple[str, ...] = ()
+    #: ISO dates from the definition; empty when unstated.
+    release_date: str = ""
+    end_of_life: str = ""
+    #: Base OS the definition builds on.
+    os_id: str = ""
+    os_version: str = ""
+    #: Number of packages the definition installs. A real signal of size and
+    #: attack surface -- and one no registry API exposes.
+    declared_package_count: int | None = None
+    entrypoint: tuple[str, ...] = ()
+    cmd: tuple[str, ...] = ()
+    #: Tags the definition says it publishes, which is what makes a
+    #: catalogue entry resolvable against the registry.
+    tags: tuple[str, ...] = ()
+    #: Package names matched against the sets above, kept so the reason for
+    #: a derived fact can be shown rather than asserted.
+    shell_packages: tuple[str, ...] = ()
+    package_manager_packages: tuple[str, ...] = ()
+    debug_tool_packages: tuple[str, ...] = ()
+
+    @property
+    def declared_non_root(self) -> Tristate:
+        """Whether the definition says the image runs as a non-root account.
+
+        `run-as: root` is an explicit FALSE. An empty `run-as` is UNKNOWN,
+        not FALSE: the definition simply did not say, and the OCI config of
+        the built image is the authority either way.
+        """
+        if not self.run_as_user:
+            return Tristate.UNKNOWN
+        return Tristate.of(self.run_as_user.lower() not in ("root", "0"))
+
+    @property
+    def declared_has_shell(self) -> Tristate:
+        return Tristate.TRUE if self.shell_packages else Tristate.UNKNOWN
+
+    @property
+    def declared_has_package_manager(self) -> Tristate:
+        return Tristate.TRUE if self.package_manager_packages else Tristate.UNKNOWN
+
+    @property
+    def declared_has_debug_tools(self) -> Tristate:
+        return Tristate.TRUE if self.debug_tool_packages else Tristate.UNKNOWN
+
+    @property
+    def is_dev_variant(self) -> bool:
+        """A development variant ships build tooling by design.
+
+        Ranked against runtime variants without this distinction, a `-dev`
+        image looks like just another candidate from a hardened catalogue.
+        """
+        return "dev" in self.variant.lower().split("-") or self.variant.lower().endswith("dev")