dockerls 1.0.0__py3-none-any.whl

dockerls/application/services/cross_validation.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import asyncio
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from dockerls.domain.entities.vulnerability import Severity, finding_identity
+
+if TYPE_CHECKING:
+    from dockerls.application.dto.analysis import ImageAnalysis
+    from dockerls.domain.entities.scan_result import ScanResult
+    from dockerls.domain.interfaces.scanner import ScannerInterface
+
+# A second scanner never reproduces the first one's findings exactly -- the
+# databases differ and each maps severities its own way. Only a difference
+# that is both large in absolute terms *and* large relative to what was found
+# is treated as a real disagreement worth flagging.
+DEFAULT_ABS_TOLERANCE = 2
+DEFAULT_REL_TOLERANCE = 0.5
+
+
+class CrossValidationOutcome(StrEnum):
+    """What the second opinion amounted to.
+
+    Kept as a named outcome rather than a boolean because the three
+    interesting states are not "agrees / disagrees" but "agrees",
+    "differs in ways two databases normally differ", and "tells a
+    different story" -- and the last of those must reach the confidence
+    model, while the middle one merely stops it reaching the top.
+    """
+
+    NO_SECOND_SCANNER = "NO_SECOND_SCANNER"
+    AGREEMENT = "AGREEMENT"
+    MINOR_DIVERGENCE = "MINOR_DIVERGENCE"
+    MATERIAL_DIVERGENCE = "MATERIAL_DIVERGENCE"
+
+
+#: Severity bands compared by identity. LOW and MEDIUM are deliberately out:
+#: their populations are large, the two databases classify them differently
+#: as a matter of course, and comparing them would make every image look
+#: disputed.
+_COMPARED_SEVERITIES = (Severity.CRITICAL, Severity.HIGH)
+
+
+# Validations are independent of each other, so they run concurrently. The
+# cap keeps a handful of scanner processes from thrashing the machine.
+DEFAULT_WORKERS = 5
+
+
+#: Worst-first, so `_worse` needs no comparison table of its own.
+_SEVERITY_OF_OUTCOME = {
+    CrossValidationOutcome.MATERIAL_DIVERGENCE: 3,
+    CrossValidationOutcome.MINOR_DIVERGENCE: 2,
+    CrossValidationOutcome.AGREEMENT: 1,
+    CrossValidationOutcome.NO_SECOND_SCANNER: 0,
+}
+
+
+def _worse(a: CrossValidationOutcome, b: CrossValidationOutcome) -> CrossValidationOutcome:
+    return a if _SEVERITY_OF_OUTCOME[a] >= _SEVERITY_OF_OUTCOME[b] else b
+
+
+#: How many differing findings to name before the message stops being
+#: readable. The full picture is in the raw evidence of both scanners.
+_MAX_EXAMPLES = 3
+
+
+def _examples(identities: set[str]) -> str:
+    """Name a few of the disputed findings, so the reader can go and look."""
+    if not identities:
+        return ""
+    shown = sorted(identities)[:_MAX_EXAMPLES]
+    names = ", ".join(identity.split("|", 1)[0] for identity in shown)
+    more = len(identities) - len(shown)
+    return f" [{names}{f', +{more} more' if more > 0 else ''}]"
+
+
+class CrossValidator:
+    """Re-scans top candidates with a second scanner and flags material
+    disagreements, so a score is never presented at full confidence when
+    two independent scanners tell different stories."""
+
+    def __init__(
+        self,
+        scanner: ScannerInterface | None,
+        abs_tolerance: int = DEFAULT_ABS_TOLERANCE,
+        rel_tolerance: float = DEFAULT_REL_TOLERANCE,
+        workers: int = DEFAULT_WORKERS,
+    ):
+        self._scanner = scanner
+        self._abs_tolerance = abs_tolerance
+        self._rel_tolerance = rel_tolerance
+        self._workers = max(1, workers)
+
+    @property
+    def enabled(self) -> bool:
+        return self._scanner is not None
+
+    @property
+    def scanner(self) -> ScannerInterface | None:
+        return self._scanner
+
+    async def validate(self, analyses: list[ImageAnalysis]) -> None:
+        """Annotate each analysis in place with `scan_divergence` and the
+        secondary scanner's evidence path.
+
+        The DB is refreshed once before the batch, then the validations run
+        concurrently -- they share no state, so serializing them only added
+        latency.
+        """
+        if self._scanner is None or not analyses:
+            return
+        if not await self._scanner.is_available():
+            logger.info("Cross-validation scanner unavailable; skipping")
+            return
+
+        refresh_db = getattr(self._scanner, "refresh_db", None)
+        if callable(refresh_db):
+            await refresh_db()
+
+        prefetched = await self._prescan(analyses)
+
+        semaphore = asyncio.Semaphore(self._workers)
+
+        async def guarded(analysis: ImageAnalysis) -> None:
+            async with semaphore:
+                await self._validate_one(analysis, prefetched)
+
+        await asyncio.gather(*[guarded(a) for a in analyses])
+
+    async def _prescan(self, analyses: list[ImageAnalysis]) -> dict[str, ScanResult]:
+        """Mede os finalistas de uma vez, quando a engine Go existe.
+
+        São poucos scans -- os finalistas, não as cem candidatas --, então o
+        ganho aqui é menor que no passo principal. Vale mesmo assim: é o
+        mesmo caminho, e mantê-lo fora criaria uma segunda forma de
+        orquestrar scans para o projeto manter.
+
+        `{}` quando não há engine, e o caminho de sempre responde.
+        """
+        batch = getattr(self._scanner, "batch", None)
+        if batch is None:
+            return {}
+        # A chave é a referência: o dedup por digest não se aplica aqui,
+        # porque os finalistas já vieram deduplicados do passo principal.
+        targets = [(a.image.full_reference, a.image.digest or "") for a in analyses]
+        outcome = await batch.scan_batch(targets)
+        if outcome is None:
+            return {}
+        return {
+            reference: result
+            for (reference, _), result in zip(targets, outcome.results, strict=True)
+        }
+
+    async def _validate_one(
+        self, analysis: ImageAnalysis, prefetched: dict[str, ScanResult] | None = None
+    ) -> None:
+        if self._scanner is None:
+            return
+        reference = analysis.image.full_reference
+        secondary = (prefetched or {}).get(reference)
+        if secondary is None:
+            secondary = await self._scanner.scan(reference)
+
+        if not secondary.is_verified:
+            logger.warning(
+                f"Cross-validation of {reference} did not complete "
+                f"({secondary.status.value}: {secondary.error_message or 'no details'})"
+            )
+            return
+
+        if secondary.evidence_path:
+            analysis.evidence_paths[secondary.scanner] = secondary.evidence_path
+
+        outcome, description = self.compare(analysis.scan, secondary)
+        analysis.cross_validation = outcome.value
+        analysis.cross_validation_detail = description
+        if outcome is CrossValidationOutcome.MATERIAL_DIVERGENCE:
+            logger.warning(f"Material scanner divergence for {reference}: {description}")
+            # `scan_divergence` remains the field the table, the exporters
+            # and the confidence model already read, and it stays reserved
+            # for material disagreement -- a minor one is recorded in
+            # `cross_validation` without disputing the score.
+            analysis.scan_divergence = description
+        elif outcome is CrossValidationOutcome.MINOR_DIVERGENCE:
+            logger.info(f"Minor scanner divergence for {reference}: {description}")
+
+    def compare(
+        self, primary: ScanResult, secondary: ScanResult
+    ) -> tuple[CrossValidationOutcome, str]:
+        """Classify two scans of the same image by *which* findings differ.
+
+        Comparing counts alone accepted a case it should not: two scanners
+        each reporting one CRITICAL, for two entirely different CVEs, agreed
+        perfectly on the arithmetic while describing different images. What
+        is compared here is the set of findings, so that case reads as the
+        divergence it is.
+        """
+        parts: list[str] = []
+        worst = CrossValidationOutcome.AGREEMENT
+
+        for severity in _COMPARED_SEVERITIES:
+            mine = {finding_identity(v) for v in primary.vulnerabilities if v.severity is severity}
+            theirs = {
+                finding_identity(v) for v in secondary.vulnerabilities if v.severity is severity
+            }
+            only_mine = mine - theirs
+            only_theirs = theirs - mine
+            if not only_mine and not only_theirs:
+                continue
+
+            magnitude = len(only_mine) + len(only_theirs)
+            baseline = max(len(mine), len(theirs), 1)
+            material = (
+                magnitude > self._abs_tolerance and (magnitude / baseline) > self._rel_tolerance
+            )
+            worst = _worse(
+                worst,
+                CrossValidationOutcome.MATERIAL_DIVERGENCE
+                if material
+                else CrossValidationOutcome.MINOR_DIVERGENCE,
+            )
+            parts.append(
+                f"{severity.value}: {primary.scanner} found {len(mine)} "
+                f"({len(only_mine)} not seen by {secondary.scanner}), "
+                f"{secondary.scanner} found {len(theirs)} "
+                f"({len(only_theirs)} not seen by {primary.scanner})"
+                + _examples(only_mine | only_theirs)
+            )
+
+        return worst, "; ".join(parts)

dockerls/application/services/ecosystems.py

@@ -0,0 +1,350 @@
+"""Conhecimento especializado de ecossistemas, runtimes e particularidades de segurança."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class EcosystemInsight:
+    ecosystem: str
+    version: str
+    runtime_features: list[str] = field(default_factory=list)
+    base_distro_advice: list[str] = field(default_factory=list)
+    security_guidelines: list[str] = field(default_factory=list)
+    common_pitfalls: list[str] = field(default_factory=list)
+    recommended_dockerfile_snippets: list[str] = field(default_factory=list)
+
+
+#: Nome exato do repositório -> ecossistema. Consultado antes das palavras
+#: soltas porque um nome exato não erra: `mongo` não é Go, e `maven` é Java
+#: mesmo sem a palavra "java" aparecer em lugar nenhum.
+_ECOSYSTEM_BY_NAME: dict[str, str] = {
+    "node": "node",
+    "nodejs": "node",
+    "bun": "node",
+    "deno": "node",
+    "python": "python",
+    "python3": "python",
+    "pypy": "python",
+    "go": "go",
+    "golang": "go",
+    "rust": "rust",
+    # Ferramentas de build são o ecossistema que constroem: quem roda `maven`
+    # está num projeto Java, e a alternativa endurecida que interessa é a de
+    # Java. Sem esta linha, `maven` caía em "generic" e não recebia conselho
+    # nenhum -- e ferramenta de build é exatamente onde um projeto de verdade
+    # começa o Dockerfile.
+    "maven": "java",
+    "gradle": "java",
+    "ant": "java",
+    "sbt": "java",
+    "tomcat": "java",
+    "jetty": "java",
+    "jdk": "java",
+    "jre": "java",
+    "openjdk": "java",
+    "temurin": "java",
+    "eclipse-temurin": "java",
+    "corretto": "java",
+    "amazoncorretto": "java",
+    "php": "php",
+    "composer": "php",
+    "ruby": "ruby",
+    "jruby": "ruby",
+    "dotnet": "dotnet",
+    "aspnet": "dotnet",
+}
+
+#: Fragmentos, para nomes compostos que nenhuma tabela cobre inteiramente
+#: (`nodejs22-debian12`, `python3-debian12`). A ordem importa: o primeiro que
+#: casar vence, e os mais específicos vêm antes.
+_ECOSYSTEM_KEYWORDS: tuple[tuple[str, str], ...] = (
+    ("nodejs", "node"),
+    ("node", "node"),
+    ("python", "python"),
+    ("golang", "go"),
+    ("rust", "rust"),
+    ("temurin", "java"),
+    ("openjdk", "java"),
+    ("corretto", "java"),
+    ("maven", "java"),
+    ("gradle", "java"),
+    ("java", "java"),
+    ("aspnet", "dotnet"),
+    ("dotnet", "dotnet"),
+    ("php", "php"),
+    ("ruby", "ruby"),
+)
+
+
+def detect_ecosystem_and_version(image_reference: str) -> tuple[str, str, str]:
+    """Detecta ecossistema (node, python, go, etc.), versão e distribuição base."""
+    ref_lower = image_reference.lower()
+    # O nome do repositório, sem registry e sem tag. Casar contra a referência
+    # inteira lia a tag e o host: `cgr.dev/chainguard/go:latest` não era
+    # reconhecido como Go (o "go" estava no caminho, não na tag), enquanto
+    # qualquer tag contendo "go" classificava a imagem errada.
+    repository = ref_lower.split("@", 1)[0].split(":", 1)[0].rstrip("/")
+    basename = repository.rsplit("/", 1)[-1]
+
+    # 1. Ecossistema
+    ecosystem = _ECOSYSTEM_BY_NAME.get(basename, "")
+    if not ecosystem:
+        for keyword, named in _ECOSYSTEM_KEYWORDS:
+            if keyword in basename:
+                ecosystem = named
+                break
+    ecosystem = ecosystem or "generic"
+
+    # 2. Versão
+    version = ""
+    tag_part = ref_lower.split(":")[-1] if ":" in ref_lower else ref_lower
+    v_match = re.search(r"(\d+(?:\.\d+)*)", tag_part)
+    if v_match:
+        version = v_match.group(1)
+
+    # 3. Distro base
+    distro = "debian/ubuntu"
+    if "alpine" in ref_lower:
+        distro = "alpine"
+    elif "distroless" in ref_lower:
+        distro = "distroless"
+    elif "wolfi" in ref_lower or "chainguard" in ref_lower:
+        distro = "wolfi/chainguard"
+    elif "scratch" in ref_lower:
+        distro = "scratch"
+    elif "slim" in ref_lower:
+        distro = "debian-slim"
+
+    return ecosystem, version, distro
+
+
+def get_ecosystem_insights(image_reference: str) -> EcosystemInsight:
+    """Gera insights técnicos e de segurança detalhados para a imagem e versão."""
+    ecosystem, version, distro = detect_ecosystem_and_version(image_reference)
+
+    if ecosystem == "node":
+        major = version.split(".")[0] if version else "22"
+        runtime_features = [
+            f"Node.js {major}.x V8 engine with optimised ECMAScript Modules (ESM) support.",
+            "Native environment-file support (--env-file=.env), with no need for dotenv.",
+            "Native WebSocket client and native fetch API (Undici).",
+            "Native Corepack support for managing yarn/pnpm.",
+        ]
+        base_advice = []
+        if distro == "alpine":
+            base_advice.extend(
+                [
+                    "Alpine uses musl libc: native C++ packages (sharp, bcrypt, sqlite3) "
+                    "must be compiled, or need 'libc6-compat'.",
+                    "For full compatibility without the build overhead, consider "
+                    "'node:22-bookworm-slim' (glibc).",
+                    "Official 'node:alpine' images already ship the non-root user "
+                    "'node' (UID 1000, GID 1000).",
+                ]
+            )
+        else:
+            base_advice.extend(
+                [
+                    "Debian Slim is fully compatible with pre-built glibc binaries.",
+                    "Consider 'distroless/nodejs22-debian12' to drop the shell.",
+                ]
+            )
+
+        security = [
+            "Set 'ENV NODE_ENV=production' to enable runtime optimisations and "
+            "disable devDependencies.",
+            "The bundled npm CLI has its own CVE cycle: run "
+            "'RUN npm install -g npm@latest', or drop it in a multi-stage build.",
+            "Tune '--max-old-space-size' so Node stays within the container memory limit.",
+            "Use 'USER node' (or create UID 10001) so the process never runs as root.",
+        ]
+        pitfalls = [
+            "Avoid running 'npm start' as PID 1 (npm does not forward SIGTERM); "
+            'use \'CMD ["node", "dist/index.js"]\'.',
+            "Do not leave 'node_modules' in the build context root without a .dockerignore.",
+        ]
+        snippets = [
+            'ENV NODE_ENV=production\nUSER node\nCMD ["--enable-source-maps", "dist/index.js"]',
+            'HEALTHCHECK --interval=30s --timeout=5s CMD node -e "'
+            "require('http').get('http://localhost:3000/health', (r) => {"
+            "if (r.statusCode !== 200) process.exit(1)"
+            "}).on('error', () => process.exit(1))\"",
+        ]
+        return EcosystemInsight(
+            ecosystem="Node.js",
+            version=version or "22.x",
+            runtime_features=runtime_features,
+            base_distro_advice=base_advice,
+            security_guidelines=security,
+            common_pitfalls=pitfalls,
+            recommended_dockerfile_snippets=snippets,
+        )
+
+    elif ecosystem == "python":
+        runtime_features = [
+            "Python runtime with dependency isolation through a multi-stage builder.",
+            "Supports Python 3.11/3.12/3.13, with execution-speed improvements.",
+        ]
+        base_advice = []
+        if distro == "alpine":
+            base_advice.extend(
+                [
+                    "Alpine musl does not support manylinux wheels. Libraries such as "
+                    "pandas, numpy and cryptography compile from source (slow, needs gcc).",
+                    "For Python with C/C++ dependencies, 'python:3.12-slim-bookworm' "
+                    "builds far faster and produces smaller images.",
+                ]
+            )
+        else:
+            base_advice.extend(
+                [
+                    "Debian Slim supports every pre-built manylinux wheel on PyPI, "
+                    "so the final container needs no compilers.",
+                ]
+            )
+
+        security = [
+            "Set 'ENV PYTHONUNBUFFERED=1' for unbuffered, real-time logs.",
+            "Set 'ENV PYTHONDONTWRITEBYTECODE=1' so no .pyc files are written.",
+            "Install dependencies with "
+            "'pip install --no-cache-dir --user -r requirements.txt' in the builder, "
+            "then copy '/root/.local' across for the non-root user.",
+            "Create an 'appuser' (UID 10001) to run the process.",
+        ]
+        pitfalls = [
+            "Do not write healthchecks that depend on the external 'requests' "
+            "package; use 'urllib.request.urlopen' from the standard library.",
+        ]
+        snippets = [
+            (
+                "ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1\n"
+                'USER appuser\nCMD ["python", "-u", "main.py"]'
+            ),
+            (
+                'HEALTHCHECK --interval=30s --timeout=5s CMD python -c "'
+                "import urllib.request; "
+                "urllib.request.urlopen('http://localhost:8000/health', timeout=3)\" || exit 1"
+            ),
+        ]
+        return EcosystemInsight(
+            ecosystem="Python",
+            version=version or "3.12.x",
+            runtime_features=runtime_features,
+            base_distro_advice=base_advice,
+            security_guidelines=security,
+            common_pitfalls=pitfalls,
+            recommended_dockerfile_snippets=snippets,
+        )
+
+    elif ecosystem == "go":
+        return EcosystemInsight(
+            ecosystem="Go",
+            version=version or "1.23.x",
+            runtime_features=[
+                "Statically linked native binaries, with no interpreter or runtime dependency.",
+            ],
+            base_distro_advice=[
+                "'scratch' or distroless images give the smallest surface (zero CVEs).",
+                "Copy '/etc/ssl/certs/ca-certificates.crt' from the builder for HTTPS calls.",
+            ],
+            security_guidelines=[
+                "Build with 'CGO_ENABLED=0 GOOS=linux go build -ldflags=\"-s -w\" -o app .'.",
+                "On 'scratch', use 'USER 65534:65534' (nobody): there is no /etc/passwd.",
+            ],
+            common_pitfalls=[
+                "Do not use shell-form healthchecks on scratch; "
+                'use exec form: CMD ["/app", "-health"].',
+            ],
+            recommended_dockerfile_snippets=[
+                "FROM scratch\n"
+                "COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/\n"
+                'COPY --from=builder /app/app /app\nUSER 65534:65534\nENTRYPOINT ["/app"]',
+            ],
+        )
+
+    elif ecosystem == "java":
+        return EcosystemInsight(
+            ecosystem="Java / JVM",
+            version=version or "21 LTS",
+            runtime_features=[
+                "Eclipse Temurin / Amazon Corretto JRE with container awareness.",
+            ],
+            base_distro_advice=[
+                "Use 'eclipse-temurin:21-jre-alpine' rather than the full JDK: it "
+                "drops over 300MB of tooling the runtime does not need.",
+            ],
+            security_guidelines=[
+                "Set 'JAVA_OPTS=\"-XX:+UseContainerSupport -XX:MaxRAMPercentage=75.0 "
+                "-Djava.security.egd=file:/dev/./urandom\"'.",
+                "Run as the non-root user 'appuser' (UID 10001).",
+            ],
+            common_pitfalls=[
+                "Avoid pinning heap size (-Xmx) without accounting for the container memory limit.",
+            ],
+            recommended_dockerfile_snippets=[
+                'ENV JAVA_OPTS="-XX:+UseContainerSupport -XX:MaxRAMPercentage=75.0"\n'
+                "USER appuser\n"
+                'ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS -jar /app/app.jar"]',
+            ],
+        )
+
+    elif ecosystem == "rust":
+        return EcosystemInsight(
+            ecosystem="Rust",
+            version=version or "1.82",
+            runtime_features=[
+                "Statically linked native binaries with musl and target-feature=+crt-static.",
+            ],
+            base_distro_advice=[
+                "'scratch' or distroless images reduce CVEs to zero.",
+            ],
+            security_guidelines=[
+                "Use 'cargo build --release --target x86_64-unknown-linux-musl'.",
+                "Run as non-root: 'USER 65534:65534'.",
+            ],
+            common_pitfalls=[],
+            recommended_dockerfile_snippets=[
+                (
+                    "FROM scratch\n"
+                    "COPY --from=builder /app/binary /app\n"
+                    'USER 65534:65534\nENTRYPOINT ["/app"]'
+                ),
+            ],
+        )
+
+    elif ecosystem == "php":
+        return EcosystemInsight(
+            ecosystem="PHP",
+            version=version or "8.3",
+            runtime_features=[
+                "PHP 8.3 with JIT and Opcache enabled.",
+            ],
+            base_distro_advice=[
+                "Use a multi-stage build with 'composer:2' in the builder, copying "
+                "only '/app/vendor'.",
+            ],
+            security_guidelines=[
+                "Enable Opcache for performance, and run as non-root (UID 10001).",
+            ],
+            common_pitfalls=[],
+            recommended_dockerfile_snippets=[
+                'USER appuser\nCMD ["php", "-S", "0.0.0.0:8000", "-t", "public"]',
+            ],
+        )
+
+    return EcosystemInsight(
+        ecosystem="Generic Container",
+        version=version or "latest",
+        runtime_features=["Standard Linux container."],
+        base_distro_advice=["Prefer minimal distributions such as Alpine or Distroless."],
+        security_guidelines=[
+            "Never run as root (USER 10001).",
+            "Keep a tidy .dockerignore.",
+            "Use healthchecks for liveness/readiness monitoring.",
+        ],
+        common_pitfalls=[],
+        recommended_dockerfile_snippets=[],
+    )

dockerls/application/services/fallback_scanner.py

@@ -0,0 +1,97 @@
+"""Um scanner que tenta o secundário quando o primário falha por culpa própria.
+
+O fallback para o Grype existia só na *escolha* do scanner: `ScannerFactory`
+olhava `is_available()` -- que é `shutil.which(...)` -- e, se o binário do
+Trivy estivesse no PATH, o Grype nunca mais entrava na conversa. Um Trivy
+instalado porém quebrado (DB corrompida, sem rede para baixá-la, timeout) não
+acionava fallback nenhum: as tags simplesmente eram marcadas como não
+verificadas, uma por uma.
+
+Aqui o fallback passa a ser por *scan*, e não por processo. A condição de
+acionamento é o `ScanErrorKind`: erro de DB, timeout, saída inválida e
+rate limit são falhas do scanner, e o outro tem chance real de responder.
+`NOT_FOUND` e `AUTH_REQUIRED` são fatos sobre a imagem -- perguntar de novo,
+a outra ferramenta, só dobra a espera pela mesma resposta.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from dockerls.domain.interfaces.scanner import ScannerInterface
+
+if TYPE_CHECKING:
+    from dockerls.domain.entities.scan_result import ScanResult
+
+
+class FallbackScanner(ScannerInterface):
+    """Delegates to `primary`, retrying with `secondary` on scanner-side faults."""
+
+    def __init__(self, primary: ScannerInterface, secondary: ScannerInterface):
+        self._primary = primary
+        self._secondary = secondary
+        # Contabilidade para o resumo da execução: quantas vezes o secundário
+        # salvou um alvo que o primário não conseguiu medir.
+        self.fallback_successes = 0
+        self.fallback_attempts = 0
+
+    @property
+    def primary(self) -> ScannerInterface:
+        return self._primary
+
+    @property
+    def secondary(self) -> ScannerInterface:
+        return self._secondary
+
+    async def is_available(self) -> bool:
+        return await self._primary.is_available() or await self._secondary.is_available()
+
+    async def scan(self, image_reference: str) -> ScanResult:
+        result = await self._primary.scan(image_reference)
+        if result.is_verified or not result.error_kind.is_scanner_fault:
+            return result
+
+        self.fallback_attempts += 1
+        logger.warning(
+            f"{result.scanner} failed on {image_reference} "
+            f"({result.error_kind.value}); retrying with the secondary scanner"
+        )
+        if not await self._secondary.is_available():
+            logger.info("No secondary scanner available; keeping the primary result")
+            return result
+
+        fallback = await self._secondary.scan(image_reference)
+        if not fallback.is_verified:
+            # Nenhum dos dois conseguiu: devolve o resultado do primário, que
+            # é o que descreve a falha da ferramenta que deveria ter medido.
+            logger.warning(
+                f"Secondary scanner also failed on {image_reference} ({fallback.error_kind.value})"
+            )
+            return result
+
+        self.fallback_successes += 1
+        logger.info(f"{fallback.scanner} recovered {image_reference} after {result.scanner} failed")
+        return fallback
+
+    async def refresh_db(self) -> bool:
+        """Prepara os dois bancos. O secundário só é útil se estiver pronto
+        antes de a primeira falha acontecer."""
+        primary_ok = await _refresh(self._primary)
+        await _refresh(self._secondary)
+        return primary_ok
+
+    async def close(self) -> None:
+        for scanner in (self._primary, self._secondary):
+            close = getattr(scanner, "close", None)
+            if callable(close):
+                await close()
+
+
+async def _refresh(scanner: ScannerInterface) -> bool:
+    refresh = getattr(scanner, "refresh_db", None)
+    if not callable(refresh):
+        return True
+    ok: bool = await refresh()
+    return ok