dockerls 1.0.0__py3-none-any.whl

dockerls/domain/security_controls.py

@@ -0,0 +1,362 @@
+"""Published security controls, and which of this tool's rules implement them.
+
+`analyze-dockerfile` has always answered with a code: `DF002 failed`. That
+code means nothing outside this repository. A reader who wants to know
+whether the rule is a real requirement or one maintainer's preference has
+nowhere to look, and an auditor who needs to map findings onto a compliance
+framework has to do it by hand, from the message text.
+
+This module closes that gap by naming, for each rule, the published control
+it implements. The value is not decoration: a finding that cites *CIS Docker
+Benchmark 4.1* can be argued about, escalated, waived with a reason, and
+mapped to an audit programme. A finding that cites `DF002` can only be
+obeyed or ignored.
+
+**Every identifier and title here was verified against its primary source**
+rather than recalled, on 2026-08-18:
+
+* **CIS Docker Benchmark, section 4** -- checked against Docker's own
+  implementation of the benchmark, `docker/docker-bench-security`
+  (`tests/4_container_images.sh`), which carries the control numbers and
+  titles verbatim.
+* **OWASP Docker Security Cheat Sheet** -- checked against the published
+  cheat sheet at cheatsheetseries.owasp.org, whose rules are numbered
+  `RULE #0` through `RULE #13`.
+* **NIST SP 800-190** -- checked against the table of contents of the
+  official NIST publication.
+
+That verification is the point, and it changed the content: three of the
+four citations drafted from memory were wrong. `NIST SP 800-190 4.4.2` is
+*Unbounded network access from containers*, not "least privilege", and
+`OWASP RULE #8` is *Set filesystem and volumes to read-only*, not "minimal
+base images". A tool that refuses to state a vulnerability count it did not
+measure cannot cite a control it did not check either.
+
+Where no published control covers a rule, that is stated rather than
+stretched: `controls_for` returns an empty tuple, and the renderers say the
+rule is this project's own guidance. Inventing a plausible-looking control
+number would be worse than having none, because it is the kind of error that
+survives review.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class ControlSource(StrEnum):
+    """Where a control is published. Cited by name so a reader can find it."""
+
+    CIS_DOCKER = "CIS Docker Benchmark"
+    NIST_800_190 = "NIST SP 800-190"
+    OWASP_DOCKER = "OWASP Docker Security Cheat Sheet"
+    DOCKER_DOCS = "Docker documentation"
+    OCI_SPEC = "OCI Image Format Specification"
+
+
+@dataclass(frozen=True)
+class Control:
+    """One published control, quoted rather than paraphrased.
+
+    `title` is the source's own wording. Paraphrasing would make the
+    citation unsearchable, which defeats the purpose of having one.
+    """
+
+    source: ControlSource
+    #: The source's identifier: "4.1", "RULE #2", "4.1.2". Empty for
+    #: documentation that is cited by page rather than by number.
+    identifier: str
+    title: str
+
+    def __str__(self) -> str:
+        head = f"{self.source.value} {self.identifier}".strip()
+        return f"{head} -- {self.title}"
+
+
+# --- The catalogue, verified against primary sources ---------------------
+
+CIS_4_1 = Control(
+    ControlSource.CIS_DOCKER, "4.1", "Ensure that a user for the container has been created"
+)
+CIS_4_2 = Control(
+    ControlSource.CIS_DOCKER, "4.2", "Ensure that containers use only trusted base images"
+)
+CIS_4_3 = Control(
+    ControlSource.CIS_DOCKER,
+    "4.3",
+    "Ensure that unnecessary packages are not installed in the container",
+)
+CIS_4_4 = Control(
+    ControlSource.CIS_DOCKER,
+    "4.4",
+    "Ensure images are scanned and rebuilt to include security patches",
+)
+CIS_4_6 = Control(
+    ControlSource.CIS_DOCKER,
+    "4.6",
+    "Ensure that HEALTHCHECK instructions have been added to container images",
+)
+CIS_4_7 = Control(
+    ControlSource.CIS_DOCKER,
+    "4.7",
+    "Ensure update instructions are not used alone in the Dockerfile",
+)
+CIS_4_8 = Control(
+    ControlSource.CIS_DOCKER, "4.8", "Ensure setuid and setgid permissions are removed"
+)
+CIS_4_9 = Control(
+    ControlSource.CIS_DOCKER, "4.9", "Ensure that COPY is used instead of ADD in Dockerfiles"
+)
+CIS_4_10 = Control(ControlSource.CIS_DOCKER, "4.10", "Ensure secrets are not stored in Dockerfiles")
+CIS_4_12 = Control(ControlSource.CIS_DOCKER, "4.12", "Ensure all signed artifacts are validated")
+
+OWASP_2 = Control(ControlSource.OWASP_DOCKER, "RULE #2", "Set a user")
+OWASP_4 = Control(
+    ControlSource.OWASP_DOCKER, "RULE #4", "Prevent in-container privilege escalation"
+)
+OWASP_9 = Control(
+    ControlSource.OWASP_DOCKER,
+    "RULE #9",
+    "Integrate container scanning tools into your CI/CD pipeline",
+)
+OWASP_12 = Control(
+    ControlSource.OWASP_DOCKER, "RULE #12", "Utilize Docker Secrets for Sensitive Data Management"
+)
+OWASP_13 = Control(ControlSource.OWASP_DOCKER, "RULE #13", "Enhance Supply Chain Security")
+
+NIST_4_1_1 = Control(ControlSource.NIST_800_190, "4.1.1", "Image vulnerabilities")
+NIST_4_1_2 = Control(ControlSource.NIST_800_190, "4.1.2", "Image configuration defects")
+NIST_4_1_4 = Control(ControlSource.NIST_800_190, "4.1.4", "Embedded clear text secrets")
+NIST_4_1_5 = Control(ControlSource.NIST_800_190, "4.1.5", "Use of untrusted images")
+
+DOCKER_MULTISTAGE = Control(ControlSource.DOCKER_DOCS, "", "Multi-stage builds")
+DOCKER_ENTRYPOINT = Control(ControlSource.DOCKER_DOCS, "", "Dockerfile reference: ENTRYPOINT")
+DOCKER_BUILD_CONTEXT = Control(ControlSource.DOCKER_DOCS, "", "Build context and .dockerignore")
+OCI_ANNOTATIONS = Control(ControlSource.OCI_SPEC, "", "Pre-defined annotation keys")
+
+
+@dataclass(frozen=True)
+class RuleMapping:
+    """A DockerLs rule, the controls it implements, and why it matters.
+
+    `rationale` is this project's own words: the controls say *what*, and a
+    reader deciding whether to act needs *why*, in terms of what an attacker
+    gains. Keeping them in separate fields is what stops a paraphrase from
+    being mistaken for a quotation.
+    """
+
+    rule_id: str
+    summary: str
+    rationale: str
+    controls: tuple[Control, ...] = ()
+
+    @property
+    def is_documented(self) -> bool:
+        """False when this is DockerLs's own guidance, not a published control."""
+        return bool(self.controls)
+
+
+RULE_MAPPINGS: tuple[RuleMapping, ...] = (
+    RuleMapping(
+        rule_id="DF001",
+        summary="Pin the base image",
+        rationale=(
+            "A floating tag means the image you tested and the image that ships can "
+            "differ with no change on your side, so nothing you verified about the "
+            "base still holds at deploy time."
+        ),
+        controls=(CIS_4_2, NIST_4_1_5, OWASP_13),
+    ),
+    RuleMapping(
+        rule_id="DF002",
+        summary="Run as a non-root user",
+        rationale=(
+            "A process running as uid 0 starts from the most privileged position "
+            "available inside the container, so any code-execution bug begins with "
+            "control of the filesystem and of anything mounted into it."
+        ),
+        controls=(CIS_4_1, OWASP_2, NIST_4_1_2),
+    ),
+    RuleMapping(
+        rule_id="DF003",
+        summary="Use a multi-stage build",
+        rationale=(
+            "Compilers, headers and package managers are needed to build and never "
+            "needed to run. A builder stage is how they stay out of the shipped "
+            "image without giving up a reproducible build."
+        ),
+        controls=(CIS_4_3, DOCKER_MULTISTAGE),
+    ),
+    RuleMapping(
+        rule_id="DF004",
+        summary="Keep secrets out of ENV and ARG",
+        rationale=(
+            "A value in ENV is in the image metadata, readable by anyone who can "
+            "pull it, and it survives in the layer history even if a later layer "
+            "removes it."
+        ),
+        controls=(CIS_4_10, NIST_4_1_4, OWASP_12),
+    ),
+    RuleMapping(
+        rule_id="DF005",
+        summary="Clean the package manager cache in the same layer",
+        rationale=(
+            "A cache removed in a later layer is still present in the one that "
+            "created it, so the image carries the bytes and the attack surface "
+            "while appearing not to."
+        ),
+        controls=(CIS_4_3, CIS_4_7),
+    ),
+    RuleMapping(
+        rule_id="DF006",
+        summary="Declare a HEALTHCHECK",
+        rationale=(
+            "An orchestrator that cannot distinguish a wedged container from a "
+            "healthy one keeps sending it traffic. This is availability rather "
+            "than confidentiality, which is why it weighs less than the rest."
+        ),
+        controls=(CIS_4_6,),
+    ),
+    RuleMapping(
+        rule_id="DF007",
+        summary="Label the image with provenance metadata",
+        rationale=(
+            "Standard annotations are what let a responder answer 'where did this "
+            "image come from and which commit built it' during an incident, "
+            "without guessing from the tag."
+        ),
+        controls=(OCI_ANNOTATIONS,),
+    ),
+    RuleMapping(
+        rule_id="DF008",
+        summary="Start from a minimal base",
+        rationale=(
+            "Every package in the base is code nobody in your organisation audited "
+            "and a future CVE somebody will have to triage; the smallest base that "
+            "runs your application is the smallest such backlog."
+        ),
+        controls=(CIS_4_3, NIST_4_1_2),
+    ),
+    RuleMapping(
+        rule_id="DF009",
+        summary="Do not install sudo",
+        rationale=(
+            "sudo exists to cross a privilege boundary, and it is setuid to do it. "
+            "In a container that should already be running unprivileged, it is a "
+            "ready-made escalation path."
+        ),
+        controls=(CIS_4_8, OWASP_4),
+    ),
+    RuleMapping(
+        rule_id="DF010",
+        summary="Use exec form for ENTRYPOINT and CMD",
+        rationale=(
+            "Shell form starts a shell as pid 1, which swallows SIGTERM: the "
+            "container stops being able to shut down cleanly, and orchestrators "
+            "fall back to killing it."
+        ),
+        controls=(DOCKER_ENTRYPOINT,),
+    ),
+    RuleMapping(
+        rule_id="DF011",
+        summary="Avoid shipping an interactive shell",
+        rationale=(
+            "A shell turns a limited primitive -- a file write, a template "
+            "injection -- into arbitrary command execution, and it is the first "
+            "thing most published container exploit chains reach for."
+        ),
+        controls=(CIS_4_3, NIST_4_1_2),
+    ),
+    RuleMapping(
+        rule_id="DF012",
+        summary="Keep a .dockerignore",
+        rationale=(
+            "Without one the build context carries .git, .env and local "
+            "credentials to the daemon, and anything a COPY happens to match ends "
+            "up in the image."
+        ),
+        controls=(CIS_4_10, DOCKER_BUILD_CONTEXT),
+    ),
+    RuleMapping(
+        rule_id="DF013",
+        summary="Use COPY instead of ADD",
+        rationale=(
+            "ADD does two things COPY does not, and neither is written on the line: "
+            "it fetches URLs with nothing verifying what came back, and it "
+            "auto-extracts local archives, so a tarball carrying '../../etc' writes "
+            "outside the destination. A reader sees what looks like a copy."
+        ),
+        controls=(CIS_4_9, NIST_4_1_5),
+    ),
+    RuleMapping(
+        rule_id="DF014",
+        summary="Do not pipe a downloaded script into a shell",
+        rationale=(
+            "`curl | sh` leaves the script nowhere: nothing signs it, nothing checks a "
+            "digest, and no layer records what ran. Whoever controls that host, the "
+            "path to it, or the DNS in between chooses what executes as root during "
+            "your build, and the Dockerfile keeps reading the same."
+        ),
+        controls=(NIST_4_1_5, OWASP_13),
+    ),
+    RuleMapping(
+        rule_id="DF015",
+        summary="Do not leave setuid or setgid binaries in the image",
+        rationale=(
+            "A setuid binary runs as its owner, and the owner is root. In a container "
+            "that correctly runs as an unprivileged user, it is the ready-made path "
+            "back to uid 0 -- the one piece missing to turn a limited command "
+            "execution into a complete one."
+        ),
+        controls=(CIS_4_8, OWASP_4, NIST_4_1_2),
+    ),
+    RuleMapping(
+        rule_id="DF016",
+        summary="Pin the version of every installed package",
+        rationale=(
+            "An unpinned `apt-get install`, `apk add`, `pip install` or `npm install` "
+            "resolves against whatever the index serves the day the build runs -- the "
+            "same Dockerfile can install different bytes, and a different CVE, "
+            "tomorrow than it did today. This is a reproducibility rule this project "
+            "checked no published benchmark for by name, not a citation stretched to "
+            "fit."
+        ),
+        controls=(),
+    ),
+    RuleMapping(
+        rule_id="DF017",
+        summary="Multi-architecture build awareness",
+        rationale=(
+            "`TARGETPLATFORM`/`--platform` have no correct state to check for, only "
+            "presence or absence -- this is informational, not a pass/fail control, "
+            "and exists to flag a package version pinned for one architecture that is "
+            "not guaranteed to exist, or to mean the same package, on another."
+        ),
+        controls=(),
+    ),
+)
+
+_BY_RULE: dict[str, RuleMapping] = {mapping.rule_id: mapping for mapping in RULE_MAPPINGS}
+
+
+def mapping_for(rule_id: str | None) -> RuleMapping | None:
+    """The mapping for `rule_id`, or None when the rule is not catalogued.
+
+    None is a legitimate answer, not a gap to paper over: a rule this
+    catalogue does not cover must render without a citation rather than
+    with a guessed one.
+    """
+    if not rule_id:
+        return None
+    return _BY_RULE.get(rule_id.strip().upper())
+
+
+def controls_for(rule_id: str | None) -> tuple[Control, ...]:
+    mapping = mapping_for(rule_id)
+    return mapping.controls if mapping else ()
+
+
+def references_for(rule_id: str | None) -> list[str]:
+    """Citations as display strings, for serialisation and rendering."""
+    return [str(control) for control in controls_for(rule_id)]

dockerls/domain/value_objects/__init__.py

@@ -0,0 +1,49 @@
+"""Os objetos de valor do domínio, resolvidos sob demanda.
+
+Este pacote reexportava tudo no topo do arquivo, e o preço não era o
+import em si: cada símbolo aqui é um modelo pydantic, e o pydantic compila
+o modelo *no momento do import*. Como `import
+dockerls.domain.value_objects.image_reference` -- uma função de parsing de
+strings, sem dependência nenhuma -- executa o `__init__` do pacote antes de
+chegar no submódulo, todo comando da CLI pagava essa compilação. Eram 82ms
+em `dockerls --help`, que não pontua imagem nenhuma.
+
+O `__getattr__` de módulo (PEP 562) mantém `from dockerls.domain.value_objects
+import SecurityScore` funcionando exatamente como antes; o submódulo só é
+importado quando alguém realmente pede o nome.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from dockerls.domain.value_objects.remediation_score import RemediationScore
+    from dockerls.domain.value_objects.security_score import SecurityScore
+    from dockerls.domain.value_objects.security_tier import SecurityTier
+
+#: Nome público -> submódulo que o define.
+_EXPORTS = {
+    "RemediationScore": "remediation_score",
+    "SecurityScore": "security_score",
+    "SecurityTier": "security_tier",
+}
+
+__all__ = ["RemediationScore", "SecurityScore", "SecurityTier"]
+
+
+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)
+    # Cacheado no próprio módulo: `__getattr__` só é consultado quando o
+    # nome não está no namespace, então o segundo acesso não paga nada.
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

dockerls/domain/value_objects/attack_surface.py

@@ -0,0 +1,198 @@
+"""Attack surface: how much an attacker inherits after reaching the container.
+
+Distinct from hardening, and distinct again from vulnerabilities. Hardening
+asks "is this configured defensively"; attack surface asks "if code
+execution happens inside this container, what is already there to use". A
+shell, a package manager, a compiler and a network fetcher are each a rung
+on that ladder, and none of them is a CVE.
+
+**Size is not surface.** A 900 MB image built from a single statically
+linked binary has a smaller attack surface than a 40 MB image carrying
+busybox, apk and curl. Bytes are therefore not scored here at all; package
+*count* is, because a package is a piece of installed functionality, and
+capabilities are, because they are what the functionality can do.
+
+The scale runs 0 (nothing found that expands surface) to 100 (every scored
+item present). Like hardening, it is computed over determined facts only and
+reports its coverage, so an image nobody could inspect reads as "unknown",
+never as "clean".
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NamedTuple
+
+if TYPE_CHECKING:
+    from dockerls.domain.entities.image_facts import HardeningFacts
+    from dockerls.domain.value_objects.tristate import Tristate
+
+#: Weights, highest first. A package manager outweighs a shell: a shell lets
+#: an attacker use what is already installed, while a package manager lets
+#: them install whatever is missing.
+PACKAGE_MANAGER_WEIGHT = 25.0
+SHELL_WEIGHT = 20.0
+DEBUG_TOOLS_WEIGHT = 15.0
+SETUID_WEIGHT = 15.0
+ROOT_DEFAULT_WEIGHT = 15.0
+PACKAGE_VOLUME_WEIGHT = 10.0
+
+TOTAL_WEIGHT = (
+    PACKAGE_MANAGER_WEIGHT
+    + SHELL_WEIGHT
+    + DEBUG_TOOLS_WEIGHT
+    + SETUID_WEIGHT
+    + ROOT_DEFAULT_WEIGHT
+    + PACKAGE_VOLUME_WEIGHT
+)
+
+#: Package count at which the volume term saturates. A runtime image with a
+#: few hundred packages carries a large amount of code nobody audited.
+PACKAGE_VOLUME_CEILING = 400
+
+#: Below this share of determined weight the number is not reported, for the
+#: same reason as in the hardening model: it would look like a measurement.
+MIN_REPORTABLE_COVERAGE = 0.25
+
+
+class SurfaceItem(NamedTuple):
+    """One scored element of the surface, kept so the score can explain itself."""
+
+    name: str
+    weight: float
+    #: Surface contributed, 0.0 to `weight`.
+    contributed: float
+    determined: bool
+    detail: str = ""
+
+
+class AttackSurfaceScore:
+    """0-100 where **higher means more surface**, over determined facts only.
+
+    The inverted direction relative to every other score in this codebase is
+    deliberate and is stated everywhere the number is rendered: "attack
+    surface 80" must never be mistaken for "80% good".
+    """
+
+    def __init__(self, facts: HardeningFacts):
+        self._items = _surface_items(facts)
+        determined = [item for item in self._items if item.determined]
+        self._available = sum(item.weight for item in determined)
+        self._contributed = sum(item.contributed for item in determined)
+        self._value = (
+            round(100.0 * self._contributed / self._available, 1) if self._available > 0 else 0.0
+        )
+
+    @property
+    def value(self) -> float:
+        return self._value
+
+    @property
+    def coverage(self) -> float:
+        return round(self._available / TOTAL_WEIGHT, 3)
+
+    @property
+    def is_reportable(self) -> bool:
+        return self.coverage >= MIN_REPORTABLE_COVERAGE
+
+    @property
+    def items(self) -> list[SurfaceItem]:
+        return list(self._items)
+
+    @property
+    def present(self) -> list[str]:
+        """Surface elements confirmed present, for the explanation text."""
+        return [
+            item.detail or item.name
+            for item in self._items
+            if item.determined and item.contributed > 0.0
+        ]
+
+    @property
+    def absent(self) -> list[str]:
+        """Surface elements confirmed absent -- a genuine finding, not a default."""
+        return [
+            item.detail or item.name
+            for item in self._items
+            if item.determined and item.contributed <= 0.0
+        ]
+
+
+def _surface_items(facts: HardeningFacts) -> list[SurfaceItem]:
+    return [
+        _from_presence(
+            "package-manager",
+            PACKAGE_MANAGER_WEIGHT,
+            facts.has_package_manager,
+            present="package manager installed",
+            absent="no package manager",
+        ),
+        _from_presence(
+            "shell", SHELL_WEIGHT, facts.has_shell, present="shell present", absent="no shell"
+        ),
+        _from_presence(
+            "debug-tools",
+            DEBUG_TOOLS_WEIGHT,
+            facts.has_debug_tools,
+            present="compilers or network utilities present",
+            absent="no compilers or network utilities",
+        ),
+        _from_presence(
+            "setuid",
+            SETUID_WEIGHT,
+            facts.has_setuid,
+            present="SUID/SGID binaries present",
+            absent="no SUID/SGID binaries",
+        ),
+        _root_default(facts),
+        _package_volume(facts),
+    ]
+
+
+def _from_presence(
+    name: str, weight: float, state: Tristate, *, present: str, absent: str
+) -> SurfaceItem:
+    if not state.is_known:
+        return SurfaceItem(name, weight, 0.0, determined=False)
+    contributed = weight if state.is_true else 0.0
+    return SurfaceItem(
+        name, weight, contributed, determined=True, detail=present if state.is_true else absent
+    )
+
+
+def _root_default(facts: HardeningFacts) -> SurfaceItem:
+    """Running as root multiplies what every other element is worth."""
+    name = "root-default"
+    if not facts.runs_as_non_root.is_known:
+        return SurfaceItem(name, ROOT_DEFAULT_WEIGHT, 0.0, determined=False)
+    if facts.runs_as_non_root.is_true:
+        return SurfaceItem(
+            name, ROOT_DEFAULT_WEIGHT, 0.0, determined=True, detail="runs unprivileged"
+        )
+    return SurfaceItem(
+        name,
+        ROOT_DEFAULT_WEIGHT,
+        ROOT_DEFAULT_WEIGHT,
+        determined=True,
+        detail="runs as root by default",
+    )
+
+
+def _package_volume(facts: HardeningFacts) -> SurfaceItem:
+    """Installed code volume, scaled linearly to a ceiling.
+
+    Counted in packages, not bytes: the question is how much distinct
+    installed functionality exists, and a single large binary is one thing
+    to audit while three hundred small packages are three hundred.
+    """
+    name = "package-volume"
+    count = facts.package_count
+    if count is None:
+        return SurfaceItem(name, PACKAGE_VOLUME_WEIGHT, 0.0, determined=False)
+    ratio = min(1.0, max(0, count) / PACKAGE_VOLUME_CEILING)
+    return SurfaceItem(
+        name,
+        PACKAGE_VOLUME_WEIGHT,
+        round(PACKAGE_VOLUME_WEIGHT * ratio, 3),
+        determined=True,
+        detail=f"{count} installed packages",
+    )