dockerls 1.0.0__py3-none-any.whl

dockerls/exporters/sarif_exporter.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+import json
+import math
+from typing import TYPE_CHECKING, Any
+
+from dockerls import __version__
+from dockerls.domain.entities.vulnerability import Severity
+from dockerls.exporters.base import ExporterInterface
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from dockerls.application.dto.analysis import AnalysisResult, ImageAnalysis
+
+_SEVERITY_TO_LEVEL = {
+    Severity.CRITICAL: "error",
+    Severity.HIGH: "error",
+    Severity.MEDIUM: "warning",
+    Severity.LOW: "note",
+    Severity.UNKNOWN: "note",
+}
+
+# GitHub code scanning reads `security-severity` as a number and buckets it:
+# >= 9.0 critical, >= 7.0 high, >= 4.0 medium, > 0.0 low. These are the floor
+# of each bucket, used only when the scanner classified a finding without
+# publishing a CVSS score -- which is the *normal* case for Debian, Alpine and
+# Ubuntu advisories, as `TrivyScanner._extract_cvss` documents.
+#
+# Emitting the literal 0.0 for those, as this exporter used to, filed every
+# unscored CRITICAL in the security dashboard at the bottom of the scale. The
+# severity the scanner actually assigned was thrown away on the way out.
+#
+# This is a translation of a category into GitHub's numeric channel, not an
+# invented measurement, so the rule records which of the two it was in
+# `properties.severity-source`.
+_SEVERITY_FLOOR = {
+    Severity.CRITICAL: 9.0,
+    Severity.HIGH: 7.0,
+    Severity.MEDIUM: 4.0,
+    Severity.LOW: 1.0,
+    Severity.UNKNOWN: 0.0,
+}
+
+# SARIF requires `reportingDescriptor.id` to be a non-empty string, and a
+# scanner can report a finding with no advisory ID at all (Trivy leaves
+# `VulnerabilityID` empty). Grouping those by package keeps the document
+# valid and keeps unrelated unnamed findings from collapsing into one rule.
+_UNIDENTIFIED_PREFIX = "DOCKERLS-UNIDENTIFIED"
+
+# The URL published in `$schema`. The document points a consumer at the
+# schema it claims to satisfy, so the URL has to resolve: the previous one
+# (`.../sarif-spec/master/Schemata/...`) 404s -- the repository's default
+# branch was renamed and the schema moved under `sarif-2.1/schema/`.
+_SCHEMA_URL = (
+    "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/"
+    "sarif-2.1/schema/sarif-schema-2.1.0.json"
+)
+
+# `artifactLocation.uri` is required to be a URI reference, and a SARIF
+# consumer keys findings by it. An analysis carrying no usable reference
+# would otherwise render as `":"` -- `f"{name}:{tag}"` over two empty
+# strings -- which is neither a URI reference nor an identifier.
+_UNKNOWN_ARTIFACT = "unknown-image"
+
+# The upper bound of the CVSS v3 base-score range. Anything outside
+# `0 < score <= 10` did not come from a CVSS calculator.
+_CVSS_MAX = 10.0
+
+
+class SARIFExporter(ExporterInterface):
+    """Exports scan findings as SARIF 2.1.0 for consumption by GitHub code
+    scanning and other SARIF-aware tooling."""
+
+    def export(self, result: AnalysisResult, output_path: Path) -> None:
+        output_path.write_bytes(self.export_string(result).encode("utf-8"))
+
+    def export_string(self, result: AnalysisResult) -> str:
+        images: list[ImageAnalysis] = [*result.recommendations, *result.alternatives]
+        rules: dict[str, dict[str, Any]] = {}
+        sarif_results: list[dict[str, Any]] = []
+
+        for analysis in images:
+            for vuln in analysis.scan.vulnerabilities:
+                rule_id = _rule_id(vuln)
+                if rule_id not in rules:
+                    rules[rule_id] = _rule_for(vuln, rule_id)
+                sarif_results.append(
+                    {
+                        "ruleId": rule_id,
+                        "level": _SEVERITY_TO_LEVEL.get(vuln.severity, "warning"),
+                        "message": {
+                            "text": (
+                                f"{vuln.severity.value} vulnerability in "
+                                f"{vuln.package_name} {vuln.installed_version}"
+                                + (f" (fix: {vuln.fixed_version})" if vuln.fixed_version else "")
+                            )
+                        },
+                        "locations": [
+                            {
+                                "physicalLocation": {
+                                    "artifactLocation": {"uri": _artifact_uri(analysis)}
+                                }
+                            }
+                        ],
+                        # Per-result rather than per-run: a SARIF file can
+                        # carry findings from several images, and a consumer
+                        # gating on confidence needs to know which image an
+                        # UNVERIFIED verdict belongs to. `properties` is the
+                        # spec's extension point, so nothing existing moves.
+                        "properties": _image_properties(analysis),
+                    }
+                )
+
+        sarif = {
+            "version": "2.1.0",
+            "$schema": _SCHEMA_URL,
+            "runs": [
+                {
+                    "tool": {
+                        "driver": {
+                            "name": "DockerLs",
+                            "informationUri": "https://github.com/Ivomsantiago/DockerLs",
+                            "version": __version__,
+                            "rules": list(rules.values()),
+                        }
+                    },
+                    "results": sarif_results,
+                }
+            ],
+        }
+        # `allow_nan=False` is the assertion, `_json_safe` is what keeps it
+        # from firing. Python's default is to emit the bare tokens `NaN` and
+        # `Infinity`, which RFC 8259 does not allow: a single non-finite
+        # score anywhere in the document makes the *whole file* unparseable
+        # to a strict reader, and GitHub code scanning's ingester is one.
+        # Every finding in the upload is then discarded together -- the
+        # failure mode this project exists to refuse, a security report that
+        # silently reports nothing.
+        return json.dumps(_json_safe(sarif), indent=2, allow_nan=False, default=str)
+
+
+def _json_safe(value: Any) -> Any:
+    """Replace non-finite floats with `None`, recursively.
+
+    A `NaN` score is not a measurement, so it is not published as one: the
+    property is emitted as JSON `null`, which a consumer reads as "no value"
+    rather than as a number that happens to compare falsely against every
+    threshold.
+    """
+    if isinstance(value, float):
+        return value if math.isfinite(value) else None
+    if isinstance(value, dict):
+        return {key: _json_safe(item) for key, item in value.items()}
+    if isinstance(value, list | tuple):
+        return [_json_safe(item) for item in value]
+    return value
+
+
+def _artifact_uri(analysis: ImageAnalysis) -> str:
+    """A non-empty URI reference naming the scanned image."""
+    for candidate in (analysis.image.full_reference, analysis.scan.image_reference):
+        text = (candidate or "").strip().strip(":")
+        if text:
+            return text
+    return _UNKNOWN_ARTIFACT
+
+
+def _image_properties(analysis: ImageAnalysis) -> dict[str, Any]:
+    """Image-level context attached to every finding from that image.
+
+    The digest is included whenever one was resolved: a SARIF file that
+    names only a tag cannot be matched back to the bytes that were scanned.
+    """
+    properties: dict[str, Any] = {
+        "image": analysis.image.full_reference,
+        "source": analysis.image.source,
+        "securityScore": analysis.security_score,
+        "tier": analysis.tier,
+        "confidence": analysis.confidence.value,
+        "productionReady": analysis.production_ready,
+        "eolStatus": analysis.eol_status.value,
+        "crossValidation": analysis.cross_validation,
+    }
+    if analysis.readiness_blockers:
+        properties["readinessBlockers"] = list(analysis.readiness_blockers)
+    if analysis.image.digest_known:
+        properties["digest"] = analysis.image.digest
+        properties["pinnedReference"] = analysis.pinned_reference
+    if analysis.hardening.reportable:
+        properties["hardeningScore"] = analysis.hardening.score
+        properties["hardeningCoverage"] = analysis.hardening.coverage
+    if analysis.attack_surface.reportable:
+        properties["attackSurfaceScore"] = analysis.attack_surface.score
+    return properties
+
+
+def _rule_id(vuln: Any) -> str:
+    """A stable, non-empty rule identifier for a finding."""
+    cve_id = (vuln.cve_id or "").strip()
+    if cve_id:
+        return cve_id
+    package = (vuln.package_name or "").strip() or "unknown-package"
+    return f"{_UNIDENTIFIED_PREFIX}-{package}"
+
+
+def _security_severity(vuln: Any) -> tuple[str, str]:
+    """Return (value, source) for GitHub's `security-severity` property.
+
+    `cvss` means the number is the scanner's measured CVSS base score.
+    `severity-band` means the advisory carried no score, so the floor of the
+    bucket matching the severity the scanner assigned is used instead --
+    otherwise an unscored CRITICAL is published to code scanning as 0.0.
+    """
+    try:
+        score = float(vuln.cvss_score)
+    except (TypeError, ValueError):
+        score = 0.0
+    # GitHub parses `security-severity` as a number. A score that is not a
+    # finite value inside the CVSS range never came from a calculator, and
+    # publishing it verbatim put the strings "inf" and "nan" in that channel
+    # -- the same "unusable value spent as evidence" that `_probability`
+    # refuses on the way in. The severity the scanner assigned is the better
+    # answer, and `severity-source` says that is what this is.
+    if math.isfinite(score) and 0.0 < score <= _CVSS_MAX:
+        return str(score), "cvss"
+    return str(_SEVERITY_FLOOR.get(vuln.severity, 0.0)), "severity-band"
+
+
+def _rule_for(vuln: Any, rule_id: str) -> dict[str, Any]:
+    severity_value, severity_source = _security_severity(vuln)
+    rule: dict[str, Any] = {
+        "id": rule_id,
+        "shortDescription": {"text": vuln.description or rule_id},
+        "properties": {
+            "security-severity": severity_value,
+            "severity-source": severity_source,
+            "tags": ["security", vuln.severity.value],
+        },
+    }
+    # Only link to NVD for a real advisory ID -- the bare detail URL for an
+    # empty ID is a 404 pointing nowhere.
+    if (vuln.cve_id or "").strip():
+        rule["helpUri"] = f"https://nvd.nist.gov/vuln/detail/{vuln.cve_id.strip()}"
+    return rule

dockerls/infrastructure/config/policy_file.py

@@ -0,0 +1,165 @@
+"""Ler `.dockerls-policy.yaml` -- e recusar o que não se entende.
+
+Aqui mora a única diferença de comportamento importante entre este arquivo e
+o `.dockerls-ignore.yaml`: **um arquivo de política malformado é erro, não
+ausência de política**.
+
+O motivo é a direção da falha. Uma regra de ignore que não carrega deixa de
+esconder uma CVE -- o resultado é mais alarme, e alarme a mais é seguro. Uma
+regra de política que não carrega deixa de exigir alguma coisa, e o build
+passa parecendo ter sido conferido. Uma chave digitada errado (`require_non_root`
+em vez de `require_nonroot`) viraria um portão aberto com cara de fechado, e
+ninguém descobre isso olhando a saída verde.
+
+Por isso: chave desconhecida é erro, tipo errado é erro, YAML quebrado é erro,
+severidade inexistente é erro. Só a ausência do arquivo é silêncio -- e é
+silêncio explícito, porque aí ninguém declarou nada.
+
+O YAML passa pelo `safe_load_yaml`, que já recusa documentos grandes demais,
+profundos demais ou expandidos demais antes de construir qualquer coisa: um
+arquivo de política pode perfeitamente vir de um repositório que não é seu.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from dockerls.domain.value_objects.build_policy import (
+    SEVERITY_ORDER,
+    BuildPolicy,
+)
+from dockerls.domain.value_objects.gate import GateSet, InvalidGateError
+from dockerls.utils.safe_yaml import UnsafeYAMLError, safe_load_yaml
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+DEFAULT_POLICY_FILENAME = ".dockerls-policy.yaml"
+
+#: As chaves aceitas. Qualquer outra é erro -- ver o docstring do módulo.
+_KNOWN_KEYS = frozenset(
+    {
+        "fail_on",
+        "max_vulnerabilities",
+        "require_scan",
+        "require_pinned_bases",
+        "require_nonroot",
+        "required_labels",
+        "allowed_base_registries",
+        "require_provenance",
+    }
+)
+
+
+class PolicyFileError(ValueError):
+    """O arquivo existe e não pôde ser entendido. Nunca vira política vazia."""
+
+
+def find_policy_file(context: Path) -> Path | None:
+    """O arquivo de política do contexto de build, se houver um."""
+    candidate = context / DEFAULT_POLICY_FILENAME
+    return candidate if candidate.is_file() else None
+
+
+def load_policy(path: Path) -> BuildPolicy:
+    """Carrega a política declarada, ou levanta explicando o que está errado."""
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as e:
+        raise PolicyFileError(f"could not read {path}: {e}") from e
+
+    try:
+        data = safe_load_yaml(raw, origin=str(path))
+    except UnsafeYAMLError as e:
+        raise PolicyFileError(f"{path}: {e}") from e
+
+    if data is None:
+        raise PolicyFileError(
+            f"{path} is empty. An empty policy file is almost always a mistake; "
+            "remove it if the intent is to have no policy."
+        )
+    if not isinstance(data, dict):
+        raise PolicyFileError(f"{path}: the document must be a map of rules")
+
+    desconhecidas = sorted(set(data) - _KNOWN_KEYS)
+    if desconhecidas:
+        raise PolicyFileError(
+            f"{path}: unknown rule(s): {', '.join(desconhecidas)}. "
+            f"Accepted rules are: {', '.join(sorted(_KNOWN_KEYS))}. "
+            "A mistyped key would be an open gate that looks closed."
+        )
+
+    policy = BuildPolicy(
+        fail_on=_severity(data, "fail_on", path),
+        max_vulnerabilities=_ceilings(data, path),
+        require_scan=_flag(data, "require_scan", path),
+        require_pinned_bases=_flag(data, "require_pinned_bases", path),
+        require_nonroot=_flag(data, "require_nonroot", path),
+        required_labels=_strings(data, "required_labels", path),
+        allowed_base_registries=_strings(data, "allowed_base_registries", path),
+        require_provenance=_flag(data, "require_provenance", path),
+    )
+    if policy.is_empty:
+        raise PolicyFileError(
+            f"{path}: no rule was declared. A file that is present but demands "
+            "nothing is indistinguishable from a gate that is switched off."
+        )
+    return policy
+
+
+def _flag(data: dict[str, Any], key: str, path: Path) -> bool:
+    value = data.get(key, False)
+    if not isinstance(value, bool):
+        raise PolicyFileError(f"{path}: {key} must be true or false, not {value!r}")
+    return value
+
+
+def _severity(data: dict[str, Any], key: str, path: Path) -> str:
+    value = data.get(key, "")
+    if not value:
+        return ""
+    # Recusar aqui é o que evita um build que morre com erro técnico no meio
+    # do caminho por causa de uma linha de YAML. `unknown` é severidade
+    # válida numa contagem e não é portão válido; `kev` e `epss>=N` são, e
+    # quem decide isso é `GateSet.parse`, para que o arquivo e a linha de
+    # comando não possam discordar sobre o que existe.
+    if not isinstance(value, str):
+        raise PolicyFileError(f"{path}: {key} must be a string, not {value!r}")
+    try:
+        GateSet.parse(value)
+    except InvalidGateError as e:
+        raise PolicyFileError(f"{path}: {key} is not a valid gate -- {e}") from e
+    return value.strip().lower()
+
+
+def _ceilings(data: dict[str, Any], path: Path) -> dict[str, int]:
+    value = data.get("max_vulnerabilities", {})
+    if not value:
+        return {}
+    if not isinstance(value, dict):
+        raise PolicyFileError(f"{path}: max_vulnerabilities must be a map of severity to number")
+    ceilings: dict[str, int] = {}
+    for severity, limit in value.items():
+        chave = str(severity).strip().lower()
+        if chave not in SEVERITY_ORDER:
+            raise PolicyFileError(f"{path}: unknown severity in max_vulnerabilities: {severity!r}")
+        # `bool` é subclasse de `int` em Python: `high: true` passaria como
+        # teto de 1, que não é o que ninguém quis dizer.
+        if not isinstance(limit, int) or isinstance(limit, bool) or limit < 0:
+            raise PolicyFileError(
+                f"{path}: the {chave} ceiling must be an integer >= 0, not {limit!r}"
+            )
+        ceilings[chave] = limit
+    return ceilings
+
+
+def _strings(data: dict[str, Any], key: str, path: Path) -> tuple[str, ...]:
+    value = data.get(key, [])
+    if not value:
+        return ()
+    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+        raise PolicyFileError(f"{path}: {key} must be a list of strings")
+    itens = tuple(v.strip() for v in value if v.strip())
+    if not itens:
+        raise PolicyFileError(f"{path}: {key} was declared with no usable value")
+    return itens

dockerls/infrastructure/config/settings.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import contextlib
+import os
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    TomlConfigSettingsSource,
+)
+
+from dockerls.domain.value_objects.scan_plan import DEFAULT_SCAN_BUDGET
+
+
+def _default_cache_dir() -> Path:
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    if xdg:
+        return Path(xdg) / "dockerls"
+    return Path.home() / ".cache" / "dockerls"
+
+
+def _default_state_dir() -> Path:
+    xdg = os.environ.get("XDG_STATE_HOME")
+    if xdg:
+        return Path(xdg) / "dockerls"
+    return Path.home() / ".local" / "state" / "dockerls"
+
+
+def _default_log_dir() -> Path:
+    return _default_state_dir() / "logs"
+
+
+def _default_evidence_dir() -> Path:
+    return _default_state_dir() / "scans"
+
+
+def _default_config_path() -> Path:
+    """~/.config/dockerls/config.toml (or $XDG_CONFIG_HOME/dockerls/config.toml)."""
+    xdg_config = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg_config) if xdg_config else Path.home() / ".config"
+    return base / "dockerls" / "config.toml"
+
+
+class Settings(BaseSettings):
+    """Configuration resolved, highest priority first, from: constructor
+    kwargs -> environment variables -> ~/.config/dockerls/config.toml ->
+    field defaults. DOCKERHUB_USERNAME and DOCKERHUB_TOKEN keep
+    their historical unprefixed env var names for backward compatibility;
+    every other setting is DOCKERLS_<FIELD_NAME>.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="DOCKERLS_",
+        toml_file=_default_config_path(),
+        extra="ignore",
+    )
+
+    cache_dir: Path = Field(default_factory=_default_cache_dir)
+    cache_ttl_seconds: int = 86400
+    # Tag existence is cached separately and more briefly: a tag
+    # disappearing matters sooner than a score going slightly stale.
+    tag_cache_ttl_seconds: int = 6 * 3600
+    max_tags: int = 100
+    # Quantas das tags descobertas este run realmente mede. `max_tags`
+    # governa a *descoberta*; isto governa a *medição*, e são coisas
+    # diferentes: descobrir 100 tags custa uma chamada HTTP, medir as 100
+    # custa dois a quatro minutos de Trivy para exibir cinco.
+    #
+    # O corte não esconde nada. As tags não medidas voltam no resultado
+    # (`deferred`) com o motivo -- quase sempre "existe uma tag mais nova
+    # da mesma linha" --, porque uma tag não medida não é uma tag pior.
+    # `0` mede todas, que é o comportamento anterior.
+    scan_budget: int = DEFAULT_SCAN_BUDGET
+    # 0 means "derive from this machine": each worker holds a scanner
+    # process that wants a core and hundreds of megabytes, so a flat number
+    # oversubscribes small runners and underuses large ones. Any explicit
+    # value is honoured as given -- the operator knows their machine.
+    workers: int = 0
+    max_critical: int = 0
+    max_high: int = 0
+    max_medium: int = 5
+    dockerhub_username: str = Field(default="", validation_alias="DOCKERHUB_USERNAME")
+    dockerhub_token: str = Field(default="", validation_alias="DOCKERHUB_TOKEN")
+    log_level: str = "INFO"
+    # Diagnostics go here, never to the terminal (see setup_logging).
+    log_dir: Path = Field(default_factory=_default_log_dir)
+    # Raw scanner JSON, kept so every displayed score is auditable.
+    evidence_dir: Path = Field(default_factory=_default_evidence_dir)
+    # Trivy's own cache root; the per-worker cache pool is built next to it.
+    trivy_cache_dir: Path | None = None
+    # Re-scan the top candidates with the secondary scanner and flag
+    # material disagreements instead of showing an undisputed score.
+    cross_validate: bool = True
+    # Confirm each recommended tag really exists on Docker Hub.
+    verify_hub_tags: bool = True
+    # Concurrent secondary scans during cross-validation. 0 means "derive
+    # from this machine", like `workers`: these are scanner processes too,
+    # and five of them on a two-core runner contend for exactly the same
+    # cores the primary scan just finished using.
+    cross_validate_workers: int = 0
+    # Search free hardened catalogues (Chainguard, Distroless) alongside
+    # Docker Hub, so a hardened image can win on measured vulnerabilities.
+    include_hardened_sources: bool = True
+    # Tags pulled per hardened source; these catalogues are small and their
+    # listings are unordered, so a wide fetch buys nothing.
+    hardened_tag_limit: int = 10
+    # Docker Hardened Images. Off by default because dhi.io refuses
+    # anonymous pulls: without credentials its candidates cannot be scanned,
+    # and an unscannable candidate is reported UNVERIFIED rather than
+    # ranked. `--source dhi` turns it on for a single run regardless.
+    include_dhi_source: bool = False
+    # How long the DHI catalogue index stays usable before it is refetched.
+    # The catalogue moves a few times a day; six hours keeps discovery
+    # current while costing one GitHub API request per window.
+    dhi_catalog_ttl_seconds: int = 6 * 3600
+    # Definition files read per DHI query. Each is one CDN request, and a
+    # popular image has dozens across OS variants and build flavours.
+    dhi_definition_limit: int = 12
+    # Raises GitHub's anonymous 60-requests/hour ceiling for catalogue
+    # refreshes. Read-only public data: no scope is required.
+    github_token: str = Field(default="", validation_alias="DOCKERLS_GITHUB_TOKEN")
+    # Resolve every unpinned tag to a manifest digest before scanning. This
+    # is what makes deduplication work across sources: without it, tags that
+    # share a manifest are scanned once each.
+    resolve_digests: bool = True
+    # Fetch the OCI config of each finalist to measure how it is configured
+    # (non-root, ports, entrypoint) instead of relying on vendor claims.
+    inspect_image_config: bool = True
+    # Where an image reference is allowed to make this process connect. A
+    # reference is user input, so without these a crafted name reaches the
+    # cloud metadata endpoint or a service on the runner. Private ranges are
+    # allowed by default because internal registries are ordinary; loopback
+    # and link-local are not, because that is the actual attack.
+    network_allow_private_networks: bool = True
+    network_allow_loopback: bool = False
+    network_allow_link_local: bool = False
+    #: Hosts permitted regardless of where they resolve ("registry:5000").
+    network_allowed_hosts: list[str] = Field(default_factory=list)
+    scanner_timeout: int = 300
+    http_timeout: int = 30
+    retry_max_attempts: int = 3
+    retry_backoff_base: float = 2.0
+    enable_threat_intel: bool = True
+    # A private/organization registry: host, optional namespace prefix, and
+    # Basic credentials exchanged for a bearer token at the standard Docker
+    # Registry HTTP API V2 token endpoint -- the same protocol ECR, Harbor,
+    # GHCR's container registry and a self-hosted `registry:2` all speak.
+    # Off by default (empty host): a source nobody configured must not
+    # appear as an option, the same reasoning `include_dhi_source` follows
+    # for a source that needs credentials to be useful.
+    private_registry_host: str = ""
+    private_registry_namespace: str = ""
+    private_registry_username: str = Field(
+        default="", validation_alias="DOCKERLS_PRIVATE_REGISTRY_USERNAME"
+    )
+    private_registry_password: str = Field(
+        default="", validation_alias="DOCKERLS_PRIVATE_REGISTRY_PASSWORD"
+    )
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            TomlConfigSettingsSource(settings_cls),
+            file_secret_settings,
+        )
+
+    def model_post_init(self, __context: object) -> None:
+        # Legacy opt-out flag from before the DOCKERLS_ env prefix was
+        # introduced; keep honoring it alongside DOCKERLS_ENABLE_THREAT_INTEL.
+        if os.environ.get("DOCKERLS_DISABLE_THREAT_INTEL"):
+            self.enable_threat_intel = False
+
+    @property
+    def db_path(self) -> Path:
+        return self.cache_dir / "cache.db"
+
+    def ensure_dirs(self) -> None:
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        # Log and evidence dirs are best-effort: a read-only working
+        # directory must degrade (setup_logging falls back to the cache dir,
+        # evidence recording is skipped) rather than abort the command.
+        for path in (self.log_dir, self.evidence_dir):
+            with contextlib.suppress(OSError):
+                path.mkdir(parents=True, exist_ok=True)