dockerls 1.0.0__py3-none-any.whl

dockerls/application/services/remediation.py

@@ -0,0 +1,321 @@
+"""Deriva um patch de Dockerfile a partir das vulnerabilidades encontradas.
+
+O que esta ferramenta analisa é uma **imagem publicada**, não o Dockerfile de
+quem a executa -- e não há como recuperar um do outro. Então o produto honesto
+não é "o seu Dockerfile corrigido": é um patch que parte da imagem analisada e
+aplica, em camadas, exatamente o que os achados justificam. Quem tem o
+Dockerfile original copia as linhas; quem não tem constrói em cima.
+
+Cada ação sai do dado, nunca de um palpite:
+
+* pacotes de SO com correção disponível -> `apk upgrade` / `apt-get upgrade`,
+  escolhido pela distro que o próprio scanner reportou no `Target`;
+* pacotes de linguagem com correção -> upgrade do gerenciador correspondente;
+* o npm embutido nas imagens Node -> as duas saídas reais (atualizar ou
+  remover), porque `apk upgrade` não toca nele;
+* achados sem correção -> nenhuma ação inventada, apenas o registro de que
+  sobram e de que só trocar de base resolve.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from dockerls.domain.entities.vulnerability import PackageOrigin
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+    from dockerls.application.dto.analysis import ImageAnalysis
+    from dockerls.domain.entities.vulnerability import Vulnerability
+
+# Marcadores de distro no `Target` do Trivy -> comando de upgrade. A ordem
+# importa só para "ubuntu" não casar antes de "debian" em alvos que citam as
+# duas; ambos usam apt, então o resultado é o mesmo de qualquer forma.
+_OS_UPGRADE = (
+    ("alpine", "apk", "apk upgrade --no-cache"),
+    ("wolfi", "apk", "apk upgrade --no-cache"),
+    ("chainguard", "apk", "apk upgrade --no-cache"),
+    ("debian", "apt", "apt-get update && apt-get upgrade -y && rm -rf /var/lib/apt/lists/*"),
+    ("ubuntu", "apt", "apt-get update && apt-get upgrade -y && rm -rf /var/lib/apt/lists/*"),
+    ("redhat", "dnf", "dnf upgrade -y && dnf clean all"),
+    ("centos", "dnf", "dnf upgrade -y && dnf clean all"),
+    ("rocky", "dnf", "dnf upgrade -y && dnf clean all"),
+    ("alma", "dnf", "dnf upgrade -y && dnf clean all"),
+    ("amazon", "dnf", "dnf upgrade -y && dnf clean all"),
+    ("photon", "tdnf", "tdnf upgrade -y && tdnf clean all"),
+    ("suse", "zypper", "zypper update -y && zypper clean --all"),
+)
+
+# Ecossistema de linguagem -> como atualizar um pacote nomeado.
+_LANG_UPGRADE = {
+    "npm": "npm install -g {packages}",
+    "yarn": "yarn global upgrade {packages}",
+    "pip": "pip install --no-cache-dir --upgrade {packages}",
+    "gem": "gem update {packages}",
+    "composer": "composer global update {packages}",
+}
+
+_LANG_MARKERS = {
+    "npm": ("npm", "node-pkg", "node_modules", "yarn"),
+    "pip": ("pip", "python-pkg", "site-packages", "poetry"),
+    "gem": ("gem", "gemspec", "ruby"),
+    "composer": ("composer", "php"),
+}
+
+_NPM_BUNDLE_MARKERS = ("node_modules/npm", "/npm/")
+
+
+@dataclass(frozen=True)
+class RemediationAction:
+    """Uma linha do patch, com o motivo que a justifica."""
+
+    title: str
+    dockerfile: str
+    rationale: str
+    addresses: tuple[str, ...] = ()
+    #: Ações que não podem ser aplicadas junto com outra (atualizar o npm
+    #: versus removê-lo). O chamador escolhe uma; ambas ficam no patch,
+    #: com a alternativa comentada.
+    alternative_to: str = ""
+
+    @property
+    def fixes(self) -> int:
+        return len(self.addresses)
+
+
+@dataclass
+class RemediationPlan:
+    image_reference: str
+    actions: list[RemediationAction] = field(default_factory=list)
+    #: CVEs que nenhuma ação deste plano resolve.
+    unresolved: tuple[str, ...] = ()
+    base_suggestion: str = ""
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.actions and not self.base_suggestion
+
+    @property
+    def resolved_count(self) -> int:
+        """Achados distintos cobertos por pelo menos uma ação."""
+        covered: set[str] = set()
+        for action in self.actions:
+            covered.update(action.addresses)
+        return len(covered)
+
+
+def _ecosystem_of(vuln: Vulnerability) -> str | None:
+    haystack = f"{vuln.package_type} {vuln.target}".lower()
+    for ecosystem, markers in _LANG_MARKERS.items():
+        if any(marker in haystack for marker in markers):
+            return ecosystem
+    return None
+
+
+def _os_upgrade_for(vulns: Sequence[Vulnerability]) -> tuple[str, str] | None:
+    """(nome do gerenciador, comando) para a distro que o scanner reportou."""
+    haystack = " ".join(f"{v.package_type} {v.target}" for v in vulns).lower()
+    for marker, manager, command in _OS_UPGRADE:
+        if marker in haystack:
+            return manager, command
+    return None
+
+
+def _is_bundled_npm(vuln: Vulnerability) -> bool:
+    return vuln.origin is PackageOrigin.LANGUAGE and any(
+        marker in vuln.target.lower() for marker in _NPM_BUNDLE_MARKERS
+    )
+
+
+def build_remediation_plan(analysis: ImageAnalysis) -> RemediationPlan:
+    """Derive the actions the findings actually justify -- and nothing else."""
+    vulns = list(analysis.scan.vulnerabilities)
+    plan = RemediationPlan(image_reference=analysis.image.full_reference)
+    if not vulns:
+        return plan
+
+    fixable = [v for v in vulns if v.is_fixable]
+    handled: set[str] = set()
+
+    # 1. O npm embutido vem primeiro: é o caso em que o upgrade genérico da
+    #    linguagem não é a melhor resposta, e em que remover resolve tudo.
+    bundled_npm = [v for v in vulns if _is_bundled_npm(v)]
+    if bundled_npm:
+        ids = tuple(v.cve_id for v in bundled_npm)
+        plan.actions.append(
+            RemediationAction(
+                title="Update the bundled npm CLI",
+                dockerfile="RUN npm install -g npm@latest",
+                rationale=(
+                    "These findings are in the npm CLI shipped inside the image, not in "
+                    "OS packages -- apk/apt upgrade does not touch them."
+                ),
+                addresses=ids,
+                alternative_to="remove-npm",
+            )
+        )
+        plan.actions.append(
+            RemediationAction(
+                title="Remove the bundled npm CLI",
+                dockerfile=(
+                    "RUN rm -rf /usr/local/lib/node_modules/npm "
+                    "/usr/local/bin/npm /usr/local/bin/npx"
+                ),
+                rationale=(
+                    "If npm is not needed at runtime (multi-stage build shipping only "
+                    "dist/), removing it clears every one of these findings outright."
+                ),
+                addresses=ids,
+                alternative_to="update-npm",
+            )
+        )
+        handled.update(ids)
+
+    # 2. Pacotes de SO com correção publicada.
+    os_fixable = [v for v in fixable if v.origin is PackageOrigin.OS]
+    if os_fixable:
+        upgrade = _os_upgrade_for(os_fixable)
+        if upgrade is not None:
+            manager, command = upgrade
+            ids = tuple(v.cve_id for v in os_fixable)
+            plan.actions.append(
+                RemediationAction(
+                    title=f"Upgrade OS packages ({manager})",
+                    dockerfile=f"RUN {command}",
+                    rationale=(
+                        f"{len(ids)} OS-package finding(s) have a fixed version published upstream."
+                    ),
+                    addresses=ids,
+                )
+            )
+            handled.update(ids)
+
+    # 3. Pacotes de linguagem com correção, agrupados por ecossistema. O npm
+    #    embutido já foi tratado acima e não se repete aqui.
+    lang_fixable = [
+        v for v in fixable if v.origin is PackageOrigin.LANGUAGE and not _is_bundled_npm(v)
+    ]
+    by_ecosystem: dict[str, list[Vulnerability]] = {}
+    for vuln in lang_fixable:
+        ecosystem = _ecosystem_of(vuln)
+        if ecosystem in _LANG_UPGRADE:
+            by_ecosystem.setdefault(str(ecosystem), []).append(vuln)
+
+    for ecosystem, items in sorted(by_ecosystem.items()):
+        # Pin ao alvo corrigido, não um upgrade cego: é o dado que o scanner
+        # já entregou, e vale mais que "atualize tudo e torça".
+        pinned = sorted({f"{v.package_name}@{v.fixed_version}" for v in items if v.package_name})
+        if not pinned:
+            continue
+        template = _LANG_UPGRADE[ecosystem]
+        if ecosystem in ("pip", "gem", "composer"):
+            pinned = [p.replace("@", "==" if ecosystem == "pip" else ":") for p in pinned]
+        ids = tuple(v.cve_id for v in items)
+        plan.actions.append(
+            RemediationAction(
+                title=f"Upgrade {ecosystem} packages",
+                dockerfile=f"RUN {template.format(packages=' '.join(pinned))}",
+                rationale=f"{len(ids)} {ecosystem} finding(s) have a published fixed version.",
+                addresses=ids,
+            )
+        )
+        handled.update(ids)
+
+    plan.unresolved = tuple(sorted({v.cve_id for v in vulns} - handled))
+
+    # 4. Trocar de base só é sugerido quando sobra algo que as camadas acima
+    #    não resolvem -- caso contrário seria conselho gratuito.
+    if plan.unresolved and not (analysis.image.is_alpine or analysis.image.is_distroless):
+        plan.base_suggestion = (
+            f"{len(plan.unresolved)} finding(s) have no published fix. A minimal base "
+            f"(alpine, distroless, or a hardened vendor image) removes the packages "
+            f"they live in rather than patching them; `dockerls recommend "
+            f"{analysis.image.name}` ranks the alternatives by measured vulnerabilities."
+        )
+
+    return plan
+
+
+def render_dockerfile_patch(plan: RemediationPlan) -> str:
+    """Render the plan as a Dockerfile that starts from the analysed image.
+
+    Não é "o seu Dockerfile corrigido" -- esta ferramenta nunca viu o seu
+    Dockerfile. É um patch aplicável: quem tem o original copia as camadas,
+    quem não tem constrói a partir daqui.
+    """
+    lines = [
+        "# Generated by dockerls --fix",
+        f"# Base: {plan.image_reference}",
+        "#",
+        "# These layers are derived from the findings of a real scan of the image",
+        "# above. dockerls analyses published images, not your Dockerfile, so this",
+        "# is a patch to apply -- copy the RUN lines into your own build, or build",
+        "# from here directly.",
+    ]
+
+    if plan.is_empty:
+        lines += [
+            "#",
+            "# Nothing to remediate: no finding in this image has a published fix",
+            "# that a layer could apply.",
+            "",
+            f"FROM {plan.image_reference}",
+            "",
+        ]
+        return "\n".join(lines)
+
+    lines += ["", f"FROM {plan.image_reference}", ""]
+
+    chosen_alternatives: set[str] = set()
+    for action in plan.actions:
+        commented = bool(action.alternative_to) and action.alternative_to in chosen_alternatives
+        if action.alternative_to:
+            chosen_alternatives.add(_action_key(action))
+
+        lines.append(f"# {action.title} -- fixes {action.fixes} finding(s)")
+        for wrapped in _wrap_comment(action.rationale):
+            lines.append(f"#   {wrapped}")
+        if commented:
+            lines.append("# Alternative to the layer above -- pick one, not both:")
+            lines.append(f"# {action.dockerfile}")
+        else:
+            lines.append(action.dockerfile)
+        lines.append("")
+
+    if plan.unresolved:
+        lines.append(f"# {len(plan.unresolved)} finding(s) remain with no published fix:")
+        for cve in plan.unresolved[:20]:
+            lines.append(f"#   {cve}")
+        if len(plan.unresolved) > 20:
+            lines.append(f"#   ... and {len(plan.unresolved) - 20} more")
+        lines.append("")
+
+    if plan.base_suggestion:
+        for wrapped in _wrap_comment(plan.base_suggestion):
+            lines.append(f"# {wrapped}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _action_key(action: RemediationAction) -> str:
+    """A ação que a alternativa dela referencia por nome."""
+    return "update-npm" if "install -g npm" in action.dockerfile else "remove-npm"
+
+
+def _wrap_comment(text: str, width: int = 72) -> list[str]:
+    words: Iterable[str] = text.split()
+    lines: list[str] = []
+    current = ""
+    for word in words:
+        candidate = f"{current} {word}".strip()
+        if len(candidate) > width and current:
+            lines.append(current)
+            current = word
+        else:
+            current = candidate
+    if current:
+        lines.append(current)
+    return lines

dockerls/application/services/scan_history_store.py

@@ -0,0 +1,88 @@
+"""Where an image's vulnerability-count history persists between runs.
+
+Mirrors `tag_history_store.py` exactly, for the same reason its own module
+docstring gives: the cache that scores lean on expires because a stale
+score is worse than none, while a history *is* the past and is worth more
+the longer it has been kept. A year-long TTL, renewed on every write, is
+what lets the second observation ever recorded still answer "since when".
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from dockerls.domain.value_objects.scan_history import ScanHistory, ScanObservation, record
+
+if TYPE_CHECKING:
+    from dockerls.domain.interfaces.cache_store import CacheStoreInterface
+
+#: A year, matching `tag_history_store.HISTORY_TTL_SECONDS`: this is the
+#: past, and it does not go stale.
+HISTORY_TTL_SECONDS = 365 * 24 * 60 * 60
+
+_KEY_PREFIX = "scan-history"
+
+
+class ScanHistoryStore:
+    """Reads and writes vulnerability-count history, keyed by reference."""
+
+    def __init__(self, cache: CacheStoreInterface | None = None):
+        self._cache = cache
+
+    async def get(self, reference: str) -> ScanHistory:
+        """The stored history, or an empty one when there is none (or it
+        could not be read)."""
+        if self._cache is None or not reference:
+            return ScanHistory(reference=reference)
+        try:
+            raw = await self._cache.get(_key(reference))
+        except Exception as e:  # pragma: no cover - the cache is the unstable path
+            logger.debug(f"Could not read the scan history of {reference}: {e}")
+            return ScanHistory(reference=reference)
+        return ScanHistory.from_dict(reference, raw)
+
+    async def observe(
+        self,
+        reference: str,
+        *,
+        digest: str,
+        critical: int,
+        high: int,
+        medium: int,
+        low: int,
+        total: int,
+        observed_at: datetime | None = None,
+    ) -> ScanHistory:
+        """Incorporates this scan's counts and returns the resulting history.
+
+        Writes only when something changed: rewriting an unchanged entry on
+        every query would do nothing but renew the TTL, which the write
+        that matters already does.
+        """
+        current = await self.get(reference)
+        observation = ScanObservation(
+            digest=digest,
+            observed_at=(observed_at or datetime.now(UTC)).isoformat(timespec="seconds"),
+            critical=critical,
+            high=high,
+            medium=medium,
+            low=low,
+            total=total,
+        )
+        updated = record(current, observation)
+        if updated is current or self._cache is None:
+            return updated
+        try:
+            await self._cache.set(
+                _key(reference), updated.to_dict(), ttl_seconds=HISTORY_TTL_SECONDS
+            )
+        except Exception as e:  # pragma: no cover - the cache is the unstable path
+            logger.debug(f"Could not write the scan history of {reference}: {e}")
+        return updated
+
+
+def _key(reference: str) -> str:
+    return f"{_KEY_PREFIX}:{reference}"

dockerls/application/services/scanner_factory.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from dockerls.application.services.fallback_scanner import FallbackScanner
+from dockerls.integrations.grype.scanner import GrypeScanner
+from dockerls.integrations.trivy.scanner import TrivyScanner
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from dockerls.domain.interfaces.scanner import ScannerInterface
+    from dockerls.infrastructure.evidence import EvidenceStore
+    from dockerls.infrastructure.network.host_guard import HostGuard
+
+
+class ScannerFactory:
+    @staticmethod
+    async def create(
+        timeout: int = 300,
+        workers: int = 1,
+        cache_dir: Path | None = None,
+        evidence: EvidenceStore | None = None,
+        guard: HostGuard | None = None,
+    ) -> ScannerInterface:
+        """Build the scanner the pipeline will use.
+
+        When both tools are installed the result is a `FallbackScanner`: the
+        Trivy runs first and the Grype picks up whatever it could not measure.
+        Selecting on `is_available()` alone -- which is just `shutil.which` --
+        meant an installed-but-broken Trivy monopolised every scan and the
+        Grype was never asked, no matter how many targets failed.
+        """
+        trivy = TrivyScanner(
+            timeout=timeout,
+            workers=workers,
+            cache_dir=cache_dir,
+            evidence=evidence,
+            guard=guard,
+        )
+        grype = GrypeScanner(timeout=timeout, evidence=evidence, guard=guard, workers=workers)
+        has_trivy = await trivy.is_available()
+        has_grype = await grype.is_available()
+
+        if has_trivy and has_grype:
+            logger.info("Using Trivy, with Grype as per-scan fallback")
+            return FallbackScanner(primary=trivy, secondary=grype)
+        if has_trivy:
+            logger.info("Using Trivy scanner (Grype not installed; no fallback available)")
+            return trivy
+        if has_grype:
+            logger.info("Trivy not installed, using Grype")
+            return grype
+
+        logger.warning("No scanner available, using Trivy (commands will fail)")
+        return trivy
+
+    @staticmethod
+    async def create_secondary(
+        primary: ScannerInterface,
+        timeout: int = 300,
+        evidence: EvidenceStore | None = None,
+        guard: HostGuard | None = None,
+        workers: int = 1,
+    ) -> ScannerInterface | None:
+        """Return an *independent* scanner for cross-validation.
+
+        Cross-validation is only meaningful between two different tools, so
+        this returns None when the only available scanner is the one already
+        producing the primary results.
+        """
+        # Um `FallbackScanner` já usa os dois: revalidar com qualquer um deles
+        # confrontaria um resultado com a ferramenta que possivelmente o
+        # produziu, o que não é validação independente nenhuma.
+        if isinstance(primary, FallbackScanner):
+            primary = primary.primary
+
+        if isinstance(primary, GrypeScanner):
+            trivy = TrivyScanner(timeout=timeout, evidence=evidence, guard=guard, workers=workers)
+            return trivy if await trivy.is_available() else None
+
+        grype = GrypeScanner(timeout=timeout, evidence=evidence, guard=guard, workers=workers)
+        if await grype.is_available():
+            return grype
+        logger.info("Grype not installed; cross-validation disabled")
+        return None

dockerls/application/services/source_registry.py

@@ -0,0 +1,151 @@
+"""Named image sources, resolved from a selection instead of a branch.
+
+`recommend` and `search` both need to answer "which catalogues should this
+run look at", and the answer comes from three places at once: the config
+file, the legacy `--no-hardened` flag, and the new `--source`/`--all-sources`
+options. Written as conditionals that ask `if source == "dhi"`, that logic
+would have to be repeated in every command and extended in every command
+each time a catalogue is added.
+
+So the catalogues register themselves here, and a command asks for a
+*selection*. Adding a provider is one `register()` call in the wiring layer;
+no command changes, and no branch anywhere grows a new arm.
+
+The registry deliberately knows nothing about HTTP, registries or scanners:
+a `SourceSpec` carries a name, a label and a coroutine that builds the
+repository. That keeps the application layer free of `httpx` while still
+letting the CLI enumerate what exists (`--source` help text, `doctor`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable, Iterable, Sequence
+
+    from dockerls.domain.interfaces.image_repository import ImageRepositoryInterface
+
+    SourceBuilder = Callable[[], Awaitable[ImageRepositoryInterface]]
+
+#: `--source all` and `--all-sources` mean the same thing; accepting the
+#: token as well keeps `--source` self-sufficient in scripts.
+ALL_SOURCES = "all"
+
+
+class UnknownSourceError(ValueError):
+    """Raised for a `--source` value no provider is registered under.
+
+    Carries the valid names so the CLI can say what *is* available instead
+    of only what is not.
+    """
+
+    def __init__(self, unknown: Iterable[str], available: Iterable[str]):
+        self.unknown = sorted(set(unknown))
+        self.available = list(available)
+        super().__init__(
+            f"unknown source(s): {', '.join(self.unknown)}. "
+            f"Available: {', '.join([*self.available, ALL_SOURCES])}"
+        )
+
+
+@dataclass(frozen=True)
+class SourceSpec:
+    """One catalogue DockerLs can discover candidates in."""
+
+    #: CLI token, lowercase and stable: this is what `--source` accepts.
+    name: str
+    #: Human label carried on every `DockerImage` this source produces, and
+    #: shown in the results table. Must match what the repository sets, or
+    #: the table would credit a candidate to the wrong catalogue.
+    label: str
+    #: Builds the repository. Async because some sources authenticate.
+    build: SourceBuilder
+    #: The source that sets the bulk of the candidate list. Exactly one
+    #: should be primary; it receives the full `--limit` while the others
+    #: are capped, because a broad catalogue and a curated one need very
+    #: different fan-outs.
+    primary: bool = False
+    #: Searched when no explicit `--source` is given.
+    default_enabled: bool = True
+    #: The registry behind this catalogue refuses anonymous pulls, so its
+    #: candidates cannot be scanned without credentials. Not a reason to
+    #: hide the source -- it is a reason the verdict will be UNVERIFIED,
+    #: which is exactly what the user needs to be told.
+    requires_auth: bool = False
+    #: Short note surfaced next to the source name in `--help`/`doctor`.
+    description: str = ""
+
+
+@dataclass
+class SourceRegistry:
+    """The catalogues this process knows about, in registration order."""
+
+    _specs: dict[str, SourceSpec] = field(default_factory=dict)
+
+    def register(self, spec: SourceSpec) -> None:
+        if spec.name in self._specs:
+            raise ValueError(f"source already registered: {spec.name}")
+        if spec.name == ALL_SOURCES:
+            raise ValueError(f"{ALL_SOURCES!r} is reserved and cannot name a source")
+        self._specs[spec.name] = spec
+
+    @property
+    def specs(self) -> list[SourceSpec]:
+        return list(self._specs.values())
+
+    @property
+    def names(self) -> list[str]:
+        return list(self._specs)
+
+    def get(self, name: str) -> SourceSpec | None:
+        return self._specs.get(name.strip().lower())
+
+    def resolve(
+        self,
+        selection: Sequence[str] | None = None,
+        *,
+        all_sources: bool = False,
+        include_optional: bool = True,
+    ) -> list[SourceSpec]:
+        """Which sources this run should search.
+
+        * `all_sources` (or a selection containing `all`) -- every registered
+          source, including the ones that are off by default.
+        * an explicit selection -- exactly those, in registration order so
+          the primary stays first regardless of the order they were typed.
+          An explicit selection overrides `include_optional`: asking for a
+          source by name is a stronger statement than a default.
+        * neither -- the default-enabled sources, minus the non-primary ones
+          when `include_optional` is False (that is `--no-hardened`).
+
+        Order matters downstream: the first spec becomes the composite's
+        primary and therefore gets the full tag limit.
+        """
+        requested = [s.strip().lower() for s in (selection or []) if s.strip()]
+        if all_sources or ALL_SOURCES in requested:
+            return self._ordered(self._specs)
+
+        if requested:
+            unknown = [name for name in requested if name not in self._specs]
+            if unknown:
+                raise UnknownSourceError(unknown, self.names)
+            return self._ordered({name: self._specs[name] for name in requested})
+
+        chosen = {
+            name: spec
+            for name, spec in self._specs.items()
+            if spec.default_enabled and (include_optional or spec.primary)
+        }
+        return self._ordered(chosen)
+
+    def _ordered(self, chosen: dict[str, SourceSpec]) -> list[SourceSpec]:
+        """Registration order, primary first.
+
+        `CompositeImageRepository` gives its primary the full limit and caps
+        the rest, so which spec lands in position zero is a behavioural
+        decision, not a cosmetic one.
+        """
+        selected = [spec for name, spec in self._specs.items() if name in chosen]
+        return sorted(selected, key=lambda spec: not spec.primary)