dockerls 1.0.0__py3-none-any.whl

dockerls/domain/entities/dockerfile_analysis.py

@@ -0,0 +1,318 @@
+"""Entidades para análise e validação de Dockerfiles."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from dockerls.domain.security_controls import mapping_for, references_for
+
+
+class ValidationStatus(StrEnum):
+    """Status de uma validação de Dockerfile."""
+
+    # "a verificação passou", não uma senha.
+    PASS = "PASS"  # nosec B105  # noqa: S105
+    WARN = "WARN"
+    FAIL = "FAIL"
+    SKIP = "SKIP"
+
+
+class SeverityLevel(StrEnum):
+    """Níveis de severidade para regras de segurança."""
+
+    CRITICAL = "CRITICAL"
+    HIGH = "HIGH"
+    MEDIUM = "MEDIUM"
+    LOW = "LOW"
+    INFO = "INFO"
+
+
+@dataclass
+class ValidationCheck:
+    """Resultado de uma única verificação de validação."""
+
+    check: str
+    status: ValidationStatus
+    message: str
+    severity: SeverityLevel = SeverityLevel.INFO
+    line: int | None = None
+    rule_id: str | None = None
+    fix_suggestion: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def references(self) -> list[str]:
+        """Published controls this finding implements, as citable strings.
+
+        Empty when the rule is DockerLs's own guidance rather than a
+        published control -- which the renderers state, instead of leaving
+        the reader to assume a citation was merely omitted.
+        """
+        return references_for(self.rule_id)
+
+    @property
+    def rationale(self) -> str:
+        """Why the rule matters, in terms of what an attacker gains."""
+        mapping = mapping_for(self.rule_id)
+        return mapping.rationale if mapping else ""
+
+    def model_dump(self) -> dict[str, Any]:
+        """Retorna dicionário serializável."""
+        return {
+            "check": self.check,
+            "status": self.status.value,
+            "message": self.message,
+            "severity": self.severity.value,
+            "line": self.line,
+            "rule_id": self.rule_id,
+            # The published controls this rule implements, resolved from the
+            # catalogue rather than stored per check: the mapping is static,
+            # and duplicating it into every finding is how the two drift.
+            # Emitted in the payload because a consumer mapping findings onto
+            # a compliance programme should not have to know the catalogue.
+            "references": self.references,
+            "rationale": self.rationale,
+            "fix_suggestion": self.fix_suggestion,
+            "details": self.details,
+        }
+
+
+@dataclass
+class HardeningRule:
+    """Regra de hardening sugerida para um Dockerfile."""
+
+    priority: SeverityLevel
+    title: str
+    description: str
+    current_state: str
+    suggested_fix: str
+    reason: str
+    line: int | None = None
+    dockerfile_snippet: str | None = None
+
+    def model_dump(self) -> dict[str, Any]:
+        """Retorna dicionário serializável."""
+        return {
+            "priority": self.priority.value,
+            "title": self.title,
+            "description": self.description,
+            "current_state": self.current_state,
+            "suggested_fix": self.suggested_fix,
+            "reason": self.reason,
+            "line": self.line,
+            "dockerfile_snippet": self.dockerfile_snippet,
+        }
+
+
+@dataclass
+class DockerfileValidationResult:
+    """Resultado da validação completa de um Dockerfile."""
+
+    dockerfile_path: str
+    passed: int = 0
+    warnings: int = 0
+    errors: int = 0
+    skipped: int = 0
+    checks: list[ValidationCheck] = field(default_factory=list)
+    recommendations: list[HardeningRule] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_valid(self) -> bool:
+        """True se não houver erros críticos."""
+        return self.errors == 0
+
+    @property
+    def total_checks(self) -> int:
+        """Total de verificações realizadas."""
+        return self.passed + self.warnings + self.errors + self.skipped
+
+    def add_check(self, check: ValidationCheck) -> None:
+        """Adiciona um resultado de verificação."""
+        self.checks.append(check)
+        if check.status == ValidationStatus.PASS:
+            self.passed += 1
+        elif check.status == ValidationStatus.WARN:
+            self.warnings += 1
+        elif check.status == ValidationStatus.FAIL:
+            self.errors += 1
+        elif check.status == ValidationStatus.SKIP:
+            self.skipped += 1
+
+    def model_dump(self) -> dict[str, Any]:
+        """Retorna dicionário serializável."""
+        return {
+            "dockerfile_path": self.dockerfile_path,
+            "passed": self.passed,
+            "warnings": self.warnings,
+            "errors": self.errors,
+            "skipped": self.skipped,
+            "total_checks": self.total_checks,
+            "is_valid": self.is_valid,
+            "checks": [c.model_dump() for c in self.checks],
+            "recommendations": [r.model_dump() for r in self.recommendations],
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class DockerfileInfo:
+    """Informações extraídas de um Dockerfile.
+
+    Os campos de usuário e de base descrevem o **estágio final** -- o único
+    que vira a imagem que roda. Um `USER node` num estágio de build não
+    protege nada em produção, e por um tempo era exatamente isso que fazia a
+    validação dar PASS num container que subia como root.
+    """
+
+    base_images: list[str] = field(default_factory=list)
+    stages: int = 1
+    has_user_directive: bool = False
+    user_name: str | None = None
+    user_uid: int | None = None
+    # Base do estágio final, já resolvida através de `FROM <alias>`.
+    final_base_image: str | None = None
+    has_healthcheck: bool = False
+    has_labels: bool = False
+    labels: dict[str, str] = field(default_factory=dict)
+    exposes_ports: list[int] = field(default_factory=list)
+    entrypoint: str | None = None
+    cmd: str | None = None
+    uses_buildkit: bool = False
+    has_secrets_in_env: bool = False
+    secret_env_vars: list[str] = field(default_factory=list)
+    package_managers_used: list[str] = field(default_factory=list)
+    cache_cleaned: bool = False
+    uses_sudo: bool = False
+    uses_latest_tag: bool = False
+    copy_commands: list[dict[str, Any]] = field(default_factory=list)
+    #: Cada `ADD`, com o que nele é diferente de um `COPY`: origens
+    #: remotas, arquivos que serão descompactados sozinhos, e se veio com
+    #: `--checksum`.
+    add_commands: list[dict[str, Any]] = field(default_factory=list)
+    run_commands: list[dict[str, Any]] = field(default_factory=list)
+    #: `ARG SEGREDO=valor`. Um ARG **com valor** fica no Dockerfile e no
+    #: histórico; um ARG sem valor é parâmetro de build e não é infração.
+    has_secrets_in_build_args: bool = False
+    secret_build_args: list[str] = field(default_factory=list)
+    #: `curl ... | sh`: script da rede executado sem nada tê-lo conferido.
+    pipes_remote_script_to_shell: bool = False
+    remote_script_lines: list[int] = field(default_factory=list)
+    #: `chmod u+s` / `chmod 4755`: binário setuid deixado dentro da imagem.
+    sets_setuid_bit: bool = False
+    setuid_lines: list[int] = field(default_factory=list)
+    #: `RUN --mount=type=secret,id=...`: a forma correta do BuildKit de
+    #: passar um segredo para um `RUN`, sem ele sobrar em ENV/ARG nem em
+    #: nenhuma camada. Distinto de `has_secrets_in_env`/`_build_args`: usar
+    #: isto não desculpa um segredo que ainda esteja em ENV ou ARG.
+    uses_secret_mount: bool = False
+    secret_mount_ids: list[str] = field(default_factory=list)
+    #: Pacotes instalados sem versão fixada -- `apt-get install curl` sem
+    #: `=<versão>`, `apk add` sem `=`, `pip install` sem `==`, `npm install`
+    #: sem `@<versão>`. Reprodutibilidade de build, não confidencialidade:
+    #: a mesma linha pode instalar bytes diferentes amanhã.
+    unpinned_packages: list[dict[str, Any]] = field(default_factory=list)
+    #: `npm install`/`npm ci` presente, mas sem `package-lock.json` ao lado
+    #: do Dockerfile -- sem lockfile, nem a versão instalada localmente é
+    #: reprodutível no build seguinte.
+    npm_lockfile_missing: bool = False
+    #: `ARG TARGETPLATFORM`/`TARGETARCH`/`BUILDPLATFORM`, ou `FROM
+    #: --platform=...`: o Dockerfile declara ciência de build multi-arch.
+    declares_multi_arch: bool = False
+    platform_args: list[str] = field(default_factory=list)
+    raw_lines: list[str] = field(default_factory=list)
+
+    def model_dump(self) -> dict[str, Any]:
+        """Retorna dicionário serializável."""
+        return {
+            "base_images": self.base_images,
+            "final_base_image": self.final_base_image,
+            "stages": self.stages,
+            "has_user_directive": self.has_user_directive,
+            "user_name": self.user_name,
+            "user_uid": self.user_uid,
+            "has_healthcheck": self.has_healthcheck,
+            "has_labels": self.has_labels,
+            "labels": self.labels,
+            "exposes_ports": self.exposes_ports,
+            "entrypoint": self.entrypoint,
+            "cmd": self.cmd,
+            "uses_buildkit": self.uses_buildkit,
+            "has_secrets_in_env": self.has_secrets_in_env,
+            "secret_env_vars": self.secret_env_vars,
+            "package_managers_used": self.package_managers_used,
+            "cache_cleaned": self.cache_cleaned,
+            "uses_sudo": self.uses_sudo,
+            "uses_latest_tag": self.uses_latest_tag,
+            "copy_commands": self.copy_commands,
+            "add_commands": self.add_commands,
+            "run_commands": self.run_commands,
+            "has_secrets_in_build_args": self.has_secrets_in_build_args,
+            "secret_build_args": self.secret_build_args,
+            "pipes_remote_script_to_shell": self.pipes_remote_script_to_shell,
+            "sets_setuid_bit": self.sets_setuid_bit,
+            "uses_secret_mount": self.uses_secret_mount,
+            "secret_mount_ids": self.secret_mount_ids,
+            "unpinned_packages": self.unpinned_packages,
+            "npm_lockfile_missing": self.npm_lockfile_missing,
+            "declares_multi_arch": self.declares_multi_arch,
+            "platform_args": self.platform_args,
+        }
+
+
+@dataclass
+class DockerfileAnalysis:
+    """Análise completa de um Dockerfile."""
+
+    info: DockerfileInfo
+    validation: DockerfileValidationResult
+    security_score: int = 0
+    security_tier: str = "C"
+    #: Se este Dockerfile parece derivado de um dos templates hardened
+    #: (`--base`), alterado à mão depois. Puramente informativo -- não
+    #: entra no score nem no tier, que continuam medindo o Dockerfile como
+    #: ele é, não de onde ele veio.
+    template_origin: TemplateOriginMatch | None = None
+
+    @property
+    def is_production_ready(self) -> bool:
+        """True se o Dockerfile está pronto para produção."""
+        return self.security_tier in ("A", "B") and self.validation.is_valid
+
+    def model_dump(self) -> dict[str, Any]:
+        """Retorna dicionário serializável."""
+        return {
+            "info": self.info.model_dump(),
+            "validation": self.validation.model_dump(),
+            "security_score": self.security_score,
+            "security_tier": self.security_tier,
+            "is_production_ready": self.is_production_ready,
+            "template_origin": self.template_origin.model_dump() if self.template_origin else None,
+        }
+
+
+@dataclass
+class TemplateOriginMatch:
+    """A Dockerfile that looks like one of the 39 hardened templates, edited
+    by hand afterwards.
+
+    `similarity` is a plain line-based ratio (`difflib.SequenceMatcher`),
+    not a security judgement -- a 60% match is still worth naming, because
+    "this drifted from `node-alpine`" is a more useful starting point than
+    treating the file as if it came from nowhere. `diff` carries only the
+    lines that differ, unified-diff style, so the reader sees the edit
+    instead of two full files.
+    """
+
+    template_name: str
+    similarity: float
+    diff: list[str] = field(default_factory=list)
+
+    def model_dump(self) -> dict[str, Any]:
+        return {
+            "template_name": self.template_name,
+            "similarity": self.similarity,
+            "diff": self.diff,
+        }

dockerls/domain/entities/image.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from dockerls.domain.entities.declared_metadata import DeclaredImageMetadata
+from dockerls.domain.value_objects.image_reference import registry_host_of
+
+#: Label carried by candidates discovered on Docker Hub. Defined here rather
+#: than written as a literal in each provider so the source registry, the
+#: results table and the repositories cannot disagree about the spelling.
+DOCKER_HUB = "Docker Hub"
+
+
+class DockerImage(BaseModel):
+    name: str
+    tag: str
+    digest: str = ""
+    size_bytes: int = 0
+    architecture: str = "amd64"
+    available_architectures: list[str] = Field(default_factory=list)
+    os: str = "linux"
+    last_updated: datetime | None = None
+    pull_count: int = 0
+    is_official: bool = False
+    is_signed: bool = False
+    full_reference: str = ""
+    # Which catalogue this tag came from: "Docker Hub", "Chainguard",
+    # "Distroless". Shown in the results table so a recommendation from a
+    # hardened source is identifiable at a glance.
+    source: str = DOCKER_HUB
+    # What the catalogue that published this image claims about it. Present
+    # only for sources that publish build definitions (Docker Hardened
+    # Images). A claim, never a measurement -- see DeclaredImageMetadata.
+    declared: DeclaredImageMetadata | None = None
+
+    def model_post_init(self, __context: object) -> None:
+        if not self.full_reference:
+            self.full_reference = f"{self.name}:{self.tag}"
+
+    @property
+    def registry_host(self) -> str:
+        """Registry this image lives on, or "" for Docker Hub.
+
+        Delegates to the shared rule so the registry this reports and the
+        registry the network policy judges can never diverge -- two copies
+        of "what counts as a host" is exactly how `localhost/evil` ends up
+        guarded in one place and not the other.
+        """
+        return registry_host_of(self.name)
+
+    @property
+    def pinned_reference(self) -> str:
+        """The immutable reference for this image, when one is known.
+
+        A tag is a moving pointer: `node:22` today and `node:22` next week
+        are different bytes, so a recommendation naming only a tag cannot be
+        checked against the scan that produced it. When the digest is known
+        the pinned form is what should be deployed and what evidence is
+        recorded against; without one, the tag is the best available and is
+        returned unchanged rather than faked.
+        """
+        if not self.digest:
+            return self.full_reference
+        return f"{self.name}@{self.digest}"
+
+    @property
+    def digest_known(self) -> bool:
+        return bool(self.digest)
+
+    @property
+    def age_known(self) -> bool:
+        """Whether this source told us when the tag was last published.
+
+        The OCI tag-listing API returns names only, so hardened registries
+        usually cannot date their tags. Scoring must treat that as "unknown"
+        rather than "ancient", or every Chainguard image is penalised for a
+        fact the registry simply did not report.
+        """
+        return self.last_updated is not None
+
+    @property
+    def age_days(self) -> int:
+        if not self.last_updated:
+            return 365
+        delta = datetime.now(tz=self.last_updated.tzinfo) - self.last_updated
+        return max(0, delta.days)
+
+    @property
+    def is_alpine(self) -> bool:
+        return "alpine" in self.tag.lower()
+
+    @property
+    def is_distroless(self) -> bool:
+        return "distroless" in self.tag.lower() or "distroless" in self.name.lower()
+
+    _HARDENED_MARKERS = ("chainguard", "cgr.dev", "wolfi", "bitnami")
+
+    @property
+    def is_hardened_source(self) -> bool:
+        """True for images from vendors that specialize in minimal,
+        security-hardened bases (Chainguard, Wolfi, Bitnami)."""
+        name = self.name.lower()
+        return any(marker in name for marker in self._HARDENED_MARKERS)
+
+    @property
+    def recently_updated(self) -> bool:
+        return self.age_days <= 30

dockerls/domain/entities/image_facts.py

@@ -0,0 +1,137 @@
+"""What was actually determined about an image, and who determined it.
+
+This is the evidence record that the hardening and attack-surface analyses
+read from. Three rules shape it, and all three exist because the alternative
+is a tool that reports confident nonsense:
+
+1. **Every fact is three-valued.** A property that could not be determined
+   is UNKNOWN, and UNKNOWN never earns credit in either direction.
+
+2. **Every fact records its source.** "Runs as non-root" carries a very
+   different weight when it comes from the OCI config of a resolved digest
+   than when a vendor's build definition claims it. Both are recorded; only
+   one is verification.
+
+3. **Nothing is inferred from a name.** An image called `distroless` is not
+   evidence of anything. The facts here come from the registry, from the
+   scanner, or from a catalogue declaration -- never from a substring.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+from dockerls.domain.value_objects.tristate import Tristate
+
+
+class EvidenceSource(StrEnum):
+    """Where a fact came from, ordered by how much it is worth.
+
+    `REGISTRY` and `SCANNER` are measurements of the published artifact.
+    `CATALOG` is a vendor's declaration about a build -- useful, auditable,
+    and not a measurement. The distinction is carried all the way to the
+    JSON output so a consumer can apply its own policy to declared facts.
+    """
+
+    #: OCI image config fetched from the registry at a resolved digest.
+    REGISTRY = "registry"
+    #: Package inventory observed by a vulnerability scanner.
+    SCANNER = "scanner"
+    #: A build definition published by the image's vendor.
+    CATALOG = "catalog"
+    #: Nothing determined this.
+    NONE = "none"
+
+
+class HardeningFacts(BaseModel):
+    """Per-image evidence, with the origin of each determined fact.
+
+    Defaults are all UNKNOWN/empty on purpose: an image nobody inspected
+    must read as "nothing is known", never as "nothing was found".
+    """
+
+    # --- Privilege -------------------------------------------------------
+    #: Whether the image's *default* execution account is not root. An image
+    #: that sets no USER runs as root, so an empty `User` in a config that
+    #: was actually fetched is a determined FALSE, not an unknown.
+    runs_as_non_root: Tristate = Tristate.UNKNOWN
+    #: The configured user string, verbatim ("node", "65532", "" for unset).
+    user: str = ""
+
+    # --- Contents --------------------------------------------------------
+    has_shell: Tristate = Tristate.UNKNOWN
+    has_package_manager: Tristate = Tristate.UNKNOWN
+    has_debug_tools: Tristate = Tristate.UNKNOWN
+    #: SUID/SGID binaries cannot be determined without unpacking the
+    #: filesystem, which this tool does not do. Kept as a declared field so
+    #: the gap is visible rather than silently absent.
+    has_setuid: Tristate = Tristate.UNKNOWN
+    #: Packages the image is known to contain. None when nothing counted
+    #: them -- which is different from zero.
+    package_count: int | None = None
+
+    # --- Runtime configuration -------------------------------------------
+    #: Ports the image declares. Empty list means "declared none" only when
+    #: the config was fetched; `ports_known` says which case this is.
+    exposed_ports: list[int] = Field(default_factory=list)
+    has_healthcheck: Tristate = Tristate.UNKNOWN
+    entrypoint: list[str] = Field(default_factory=list)
+    cmd: list[str] = Field(default_factory=list)
+
+    # --- Composition -----------------------------------------------------
+    layer_count: int | None = None
+    size_bytes: int | None = None
+    os_family: str = ""
+
+    #: fact name -> the source that determined it. A fact absent from this
+    #: mapping was never determined by anything.
+    evidence: dict[str, EvidenceSource] = Field(default_factory=dict)
+
+    #: True once an OCI config was actually fetched, which is what makes
+    #: "no ports declared" and "no USER set" readable as facts.
+    config_verified: bool = False
+
+    #: Places where a catalogue's declaration and the published image
+    #: disagree, in the reader's terms. This is the single most valuable
+    #: output of comparing declared metadata against a measurement, and it
+    #: is surfaced rather than resolved silently: a vendor claiming an image
+    #: runs unprivileged while its config says root is exactly the kind of
+    #: thing a security tool exists to notice.
+    conflicts: list[str] = Field(default_factory=list)
+
+    def source_of(self, fact: str) -> EvidenceSource:
+        return self.evidence.get(fact, EvidenceSource.NONE)
+
+    def is_verified(self, fact: str) -> bool:
+        """Whether `fact` was measured rather than declared.
+
+        The ranking layer uses this to keep a vendor's claim from carrying
+        the same weight as a registry measurement.
+        """
+        return self.source_of(fact) in (EvidenceSource.REGISTRY, EvidenceSource.SCANNER)
+
+    @property
+    def ports_known(self) -> bool:
+        return self.config_verified or bool(self.exposed_ports)
+
+    @property
+    def privileged_ports(self) -> list[int]:
+        """Declared ports below 1024.
+
+        Binding one of these traditionally requires elevated privileges or
+        an explicit capability, so an image declaring them is telling us
+        something about how it expects to be run.
+        """
+        return [port for port in self.exposed_ports if port < 1024]
+
+    @property
+    def determined_count(self) -> int:
+        """How many facts anything actually determined.
+
+        Reported alongside every derived score, because a score computed
+        over two facts and a score computed over ten are not comparable and
+        must not be presented as if they were.
+        """
+        return len(self.evidence)

dockerls/domain/entities/recommendation.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+
+class ActionType(StrEnum):
+    UPGRADE_IMAGE = "UPGRADE_IMAGE"
+    SWITCH_TAG = "SWITCH_TAG"
+    REBUILD_IMAGE = "REBUILD_IMAGE"
+    UPDATE_PACKAGE = "UPDATE_PACKAGE"
+    SWITCH_BASE = "SWITCH_BASE"
+    WAIT_UPSTREAM = "WAIT_UPSTREAM"
+    RESCAN = "RESCAN"
+
+
+class RemediationStep(BaseModel):
+    step_number: int
+    action: ActionType
+    description: str
+    from_value: str = ""
+    to_value: str = ""
+    expected_impact: str = ""
+
+
+class Recommendation(BaseModel):
+    image_reference: str
+    security_score: float
+    tier: str
+    remediation_score: int
+    steps: list[RemediationStep] = []
+    summary: str = ""