dockerls 1.0.0__py3-none-any.whl

dockerls/application/services/tag_history_store.py

@@ -0,0 +1,76 @@
+"""Onde o histórico de uma tag persiste entre execuções.
+
+A metade pura está em `domain/value_objects/tag_history.py`. Aqui mora só o
+que ela não pode fazer: guardar o que foi visto para que a próxima execução
+saiba comparar.
+
+O cache já existente serve, com uma diferença que importa: entradas de cache
+normais expiram porque uma resposta velha é pior que nenhuma. Um histórico é o
+oposto -- ele *é* o passado, e vale mais quanto mais antigo. Por isso o TTL
+aqui é de um ano e é renovado a cada gravação: um histórico que expira em 24h
+nunca chega a registrar a segunda observação, e a pergunta que este módulo
+existe para responder ("com que frequência esta tag muda?") ficaria sem
+resposta para sempre.
+
+Nada aqui levanta exceção para fora. O histórico enriquece o diagnóstico do
+`base`; se o cache estiver indisponível ou corrompido, o diagnóstico continua,
+apenas sem a frase extra. Um extra que derruba o principal não é um extra.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from dockerls.domain.value_objects.tag_history import TagHistory, record
+
+if TYPE_CHECKING:
+    from dockerls.domain.interfaces.cache_store import CacheStoreInterface
+
+#: Um ano. O histórico é o passado; ele não fica obsoleto, fica valioso.
+HISTORY_TTL_SECONDS = 365 * 24 * 60 * 60
+
+_KEY_PREFIX = "tag-history"
+
+
+class TagHistoryStore:
+    """Lê e grava o histórico de digests por referência de tag."""
+
+    def __init__(self, cache: CacheStoreInterface | None = None):
+        self._cache = cache
+
+    async def get(self, reference: str) -> TagHistory:
+        """O histórico guardado, ou um vazio quando não há (ou não deu para ler)."""
+        if self._cache is None or not reference:
+            return TagHistory(reference=reference)
+        try:
+            raw = await self._cache.get(_key(reference))
+        except Exception as e:  # pragma: no cover - o cache é o caminho instável
+            logger.debug(f"Could not read the history of {reference}: {e}")
+            return TagHistory(reference=reference)
+        return TagHistory.from_dict(reference, raw)
+
+    async def observe(self, reference: str, digest: str) -> TagHistory:
+        """Incorpora o digest observado agora e devolve o histórico resultante.
+
+        Grava apenas quando algo mudou: reescrever a mesma entrada a cada
+        consulta só serviria para renovar o TTL, e a renovação já acontece na
+        gravação que importa.
+        """
+        current = await self.get(reference)
+        updated = record(current, digest, datetime.now(UTC))
+        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 - o cache é o caminho instável
+            logger.debug(f"Could not write the history of {reference}: {e}")
+        return updated
+
+
+def _key(reference: str) -> str:
+    return f"{_KEY_PREFIX}:{reference}"

dockerls/application/services/teardown.py

@@ -0,0 +1,50 @@
+"""Release the resources a use case borrowed, without letting cleanup lose a result.
+
+Scanners hold temporary Trivy cache directories; repositories hold an
+`httpx.AsyncClient` whose connection pool is kept alive for the whole run so
+requests can reuse it. Both therefore have to be handed back, and the only
+place that knows when a run is over is the use case that started it.
+
+Everything here is duck-typed on `close()` for the same reason the rest of
+the pipeline is: a test double, a repository with no pool, and a scanner
+that owns nothing all need to work without implementing anything.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loguru import logger
+
+
+async def close_quietly(*resources: Any) -> None:
+    """Await `close()` on each resource that has one.
+
+    A failure to clean up is logged and swallowed. It must never replace the
+    result the caller is about to return: an unclosed socket is a smaller
+    problem than a completed scan being reported as an error, which is what
+    letting the exception escape a `finally` would do.
+    """
+    for resource in resources:
+        if resource is None:
+            continue
+        close = getattr(resource, "close", None)
+        if not callable(close):
+            continue
+        try:
+            await close()
+        except Exception as e:  # pragma: no cover - cleanup must not mask results
+            logger.warning(f"Cleanup failed for {type(resource).__name__}: {e}")
+
+
+def sources_of(repository: Any) -> list[Any]:
+    """The individual image sources behind a repository.
+
+    `CompositeImageRepository` exposes a real list of them; anything else --
+    a single client, or a test double whose attributes are auto-created --
+    is the one source it is.
+    """
+    sources = getattr(repository, "sources", None)
+    if isinstance(sources, list | tuple):
+        return list(sources)
+    return [repository]

dockerls/application/services/verdict.py

@@ -0,0 +1,298 @@
+"""Turn measurements into a verdict, and make the verdict explain itself.
+
+The scoring pieces each answer one question -- how vulnerable, how hardened,
+how much surface, how trustworthy is the evidence. This is where they are
+put together into what the user actually asked for: *should I run this*, and
+*why did it beat the alternative*.
+
+Two rules govern the composition, and both exist because the obvious
+alternative is wrong:
+
+**Hardening never offsets vulnerabilities.** The dimensions are reported
+side by side and are never summed. A perfectly configured image carrying an
+unfixable CRITICAL is a perfectly configured vulnerable image, and the
+production-ready verdict it gets is the one its CVEs earn. `SecurityTier`
+already enforces the ceiling; nothing here may route around it.
+
+**Confidence is a gate, not a decoration.** An UNVERIFIED candidate is not a
+low-scoring candidate: it is one about which nothing is known, and the
+ranking refuses to place it above anything that was actually measured.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from dockerls.application.services.cross_validation import CrossValidationOutcome
+from dockerls.domain.value_objects.attack_surface import AttackSurfaceScore
+from dockerls.domain.value_objects.confidence import (
+    Confidence,
+    ConfidenceAssessment,
+    ConfidenceInputs,
+    confidence_rank,
+)
+from dockerls.domain.value_objects.hardening import HardeningScore
+from dockerls.domain.value_objects.production_readiness import (
+    ProductionReadiness,
+    ReadinessInputs,
+)
+from dockerls.domain.value_objects.security_tier import Tier
+from dockerls.domain.value_objects.tristate import Tristate
+
+if TYPE_CHECKING:
+    from dockerls.application.dto.analysis import ImageAnalysis
+    from dockerls.domain.entities.image_facts import HardeningFacts
+
+from dockerls.application.dto.analysis import DimensionReport
+
+
+def apply_facts(analysis: ImageAnalysis, facts: HardeningFacts) -> None:
+    """Attach an evidence record and the two dimensions derived from it.
+
+    In-place, matching how `CrossValidator` annotates an analysis: the
+    pipeline enriches one object as evidence arrives rather than rebuilding
+    it at each stage.
+    """
+    hardening = HardeningScore(facts)
+    surface = AttackSurfaceScore(facts)
+
+    analysis.facts = facts
+    analysis.hardening = DimensionReport(
+        score=hardening.value,
+        coverage=hardening.coverage,
+        reportable=hardening.is_reportable,
+        positives=hardening.strengths,
+        negatives=hardening.weaknesses,
+        undetermined=hardening.undetermined,
+    )
+    analysis.attack_surface = DimensionReport(
+        score=surface.value,
+        coverage=surface.coverage,
+        reportable=surface.is_reportable,
+        # Inverted relative to hardening on purpose: for surface, the
+        # elements *present* are what count against the image.
+        positives=surface.absent,
+        negatives=surface.present,
+        undetermined=[item.name for item in surface.items if not item.determined],
+    )
+
+
+def finalize_verdict(analysis: ImageAnalysis, *, cross_validated: bool) -> None:
+    """Set confidence and the explanation, once all evidence is in.
+
+    Called after tag verification and cross-validation, because both feed
+    the confidence assessment: computing it earlier would report a
+    confidence that ignores the checks still to come.
+    """
+    assessment = ConfidenceAssessment(
+        ConfidenceInputs(
+            scan_verified=analysis.scan.is_verified,
+            cross_validated=cross_validated,
+            scanners_disagree=bool(analysis.scan_divergence),
+            scanners_differ_slightly=(
+                analysis.cross_validation == CrossValidationOutcome.MINOR_DIVERGENCE.value
+            ),
+            digest_resolved=analysis.image.digest_known,
+            registry_verified=analysis.hub_tag_verified,
+            hardening_coverage=analysis.hardening.coverage,
+        )
+    )
+    analysis.confidence = assessment.level
+    analysis.confidence_reasons = assessment.reasons
+
+    # Production readiness is decided here, not by the tier, and not before
+    # the evidence is in. `SecurityTier.production_ready` can only see the
+    # score, so a PARTIAL scan with no findings in the targets it managed to
+    # read produced tier A and "production ready" on the same analysis that
+    # reported UNVERIFIED. The policy below is the only thing that writes
+    # this field.
+    readiness = ProductionReadiness.evaluate(
+        ReadinessInputs(
+            tier=Tier(analysis.tier),
+            confidence=analysis.confidence,
+            scan_verified=analysis.scan.is_verified,
+            eol=analysis.eol_status,
+            critical_count=analysis.scan.critical_count,
+            high_count=analysis.scan.high_count,
+            unfixable_critical_count=(
+                analysis.scan.critical_count - analysis.scan.fixable_critical_count
+            ),
+            has_material_divergence=bool(analysis.scan_divergence),
+        )
+    )
+    analysis.production_ready = readiness.is_ready
+    analysis.readiness_blockers = readiness.codes
+    analysis.readiness_reasons = readiness.reasons
+
+    analysis.why = _why(analysis)
+    analysis.trade_offs = _trade_offs(analysis)
+
+
+def ranking_key(analysis: ImageAnalysis) -> tuple[float, ...]:
+    """Total ordering across sources, best first under `reverse=True`.
+
+    The order of the terms *is* the policy, so it is stated here once and
+    read the same way by `recommend`, `alternatives` and the advisor:
+
+    1. **confidence** -- an unverified candidate never outranks a measured
+       one, whatever its numbers say;
+    2. **security score** -- the measured vulnerability position, which is
+       what the whole exercise is about;
+    3. **hardening**, but only when enough of it was determined to mean
+       something; a thin-coverage 100 must not beat a fully-inspected 85;
+    4. **attack surface**, negated so less surface ranks higher;
+    5. **remediation score** -- between two equivalent images, prefer the
+       one whose findings can actually be fixed.
+
+    Hardening enters only after the vulnerability position, which is the
+    structural reason it can never mask a CRITICAL: no value of terms 3-5
+    can move a candidate past a difference in term 2.
+    """
+    return (
+        float(confidence_rank(analysis.confidence)),
+        analysis.security_score,
+        analysis.hardening.score if analysis.hardening.reportable else 0.0,
+        -(analysis.attack_surface.score if analysis.attack_surface.reportable else 0.0),
+        float(analysis.remediation_score),
+    )
+
+
+def rank(analyses: list[ImageAnalysis]) -> list[ImageAnalysis]:
+    """Order candidates from every source under one comparable policy."""
+    return sorted(analyses, key=lambda analysis: ranking_key(analysis), reverse=True)
+
+
+def _why(analysis: ImageAnalysis) -> list[str]:
+    """The case for this image, in facts a reader can check.
+
+    Only statements backed by something that was actually determined get in.
+    "No critical vulnerabilities" is earned by a completed scan; "runs as
+    non-root" is earned by a config that was read or a declaration that was
+    made, and the phrasing says which.
+    """
+    scan = analysis.scan
+    reasons: list[str] = []
+
+    if scan.critical_count == 0:
+        reasons.append("no CRITICAL vulnerabilities")
+    if scan.high_count == 0:
+        reasons.append("no HIGH vulnerabilities")
+    # "No known-exploited vulnerabilities" is the strongest claim this tool
+    # makes about real-world exploitation, and it may only be made when the
+    # KEV catalogue actually answered. With the feed unreachable every CVE
+    # comes back `exploit_known=False`, and stating the claim on that basis
+    # would be reporting a failed lookup as a security property.
+    #
+    # A CVE the catalogue *does* list is the mirror case, and it belongs in
+    # `_trade_offs`, not here: it used to land in this list, so a log4j RCE
+    # under active exploitation (CVE-2021-44228, CISA KEV) printed as a `+`
+    # reason to pick the image. Exploitation observed in the wild is never a
+    # point in an image's favour.
+    checked = [v for v in scan.vulnerabilities if v.kev_status.is_known]
+    if checked and not any(v.exploit_known for v in checked):
+        reasons.append(
+            f"no known-exploited (CISA KEV) vulnerabilities among the "
+            f"{len(checked)} finding(s) checked"
+        )
+    if analysis.eol_status.is_false:
+        reasons.append("not end-of-life")
+    if analysis.is_lts:
+        reasons.append("long-term-support release")
+
+    facts = analysis.facts
+    if facts.runs_as_non_root.is_true:
+        reasons.append(f"runs as a non-root account ({facts.source_of('runs_as_non_root').value})")
+    if analysis.hardening.reportable:
+        reasons.extend(analysis.hardening.positives)
+    if analysis.attack_surface.reportable and analysis.attack_surface.positives:
+        reasons.extend(analysis.attack_surface.positives)
+
+    if analysis.image.digest_known:
+        reasons.append("pinned to a resolved manifest digest")
+    if analysis.hub_tag_verified is True:
+        reasons.append("tag confirmed in its source registry")
+    if cross_validation_agreed(analysis):
+        reasons.append("two scanners agreed on the vulnerability counts")
+
+    return _deduplicate(reasons)
+
+
+def cross_validation_agreed(analysis: ImageAnalysis) -> bool:
+    """A second scanner ran and did not disagree materially.
+
+    Distinguished from "no second scanner ran": the evidence path for the
+    secondary scanner is what proves one did.
+    """
+    if analysis.cross_validation == CrossValidationOutcome.AGREEMENT.value:
+        return True
+    # Fall back to the older signal for analyses produced before the outcome
+    # was recorded (a cache entry, a hand-built DTO): two evidence files and
+    # no material dispute is what "agreed" used to mean.
+    scanners = set(analysis.evidence_paths)
+    return len(scanners) > 1 and not analysis.scan_divergence
+
+
+def _trade_offs(analysis: ImageAnalysis) -> list[str]:
+    """What this image costs, stated next to what it offers."""
+    costs: list[str] = []
+    scan = analysis.scan
+
+    if scan.critical_count:
+        costs.append(f"{scan.critical_count} CRITICAL vulnerability(ies) present")
+    if scan.high_count:
+        costs.append(f"{scan.high_count} HIGH vulnerability(ies) present")
+    if analysis.eol_status.is_true:
+        costs.append("this release is end-of-life and will not receive security fixes")
+    elif analysis.eol_status is Tristate.UNKNOWN:
+        costs.append(
+            "end-of-life status could not be determined: this is not a statement that "
+            "the release is supported"
+        )
+    if analysis.scan.total_count and not any(
+        v.kev_status.is_known for v in analysis.scan.vulnerabilities
+    ):
+        costs.append("exploitation status (CISA KEV) could not be determined for any finding")
+    exploited = sum(1 for v in scan.vulnerabilities if v.exploit_known)
+    if exploited:
+        costs.append(f"{exploited} known-exploited (CISA KEV) vulnerability(ies) present")
+    if analysis.scan_divergence:
+        costs.append(f"scanners disagree: {analysis.scan_divergence}")
+    if analysis.confidence is not Confidence.HIGH:
+        costs.extend(analysis.confidence_reasons)
+
+    facts = analysis.facts
+    if facts.runs_as_non_root.is_false:
+        costs.append("runs as root by default")
+    if analysis.hardening.reportable:
+        costs.extend(analysis.hardening.negatives)
+    if analysis.attack_surface.reportable:
+        costs.extend(analysis.attack_surface.negatives)
+    costs.extend(facts.conflicts)
+
+    if not analysis.image.digest_known:
+        costs.append("no manifest digest resolved: the tag may move under you")
+    declared = analysis.image.declared
+    if declared is not None and declared.is_dev_variant:
+        costs.append(
+            f"this is the '{declared.variant}' variant, which ships build tooling by design"
+        )
+    if facts.has_shell is Tristate.UNKNOWN and facts.has_package_manager is Tristate.UNKNOWN:
+        costs.append("image contents could not be inspected: shell and package manager unknown")
+
+    return _deduplicate(costs)
+
+
+def _deduplicate(items: list[str]) -> list[str]:
+    """Preserve order, drop repeats.
+
+    Reasons are gathered from several models that legitimately observe the
+    same property, and a list that says "no shell present" twice reads as
+    sloppy rather than thorough.
+    """
+    seen: set[str] = set()
+    unique: list[str] = []
+    for item in items:
+        if item and item not in seen:
+            seen.add(item)
+            unique.append(item)
+    return unique

dockerls/application/services/version_discovery.py

@@ -0,0 +1,108 @@
+"""The current stable versions of a runtime or OS, read from the registry.
+
+`RUNTIME_BASES` in `base_recipe.py` hardcodes one version per (runtime,
+family) -- Alpine 3.21, Node 22, Python 3.12 -- and that stays the default
+when nobody asks for anything else. This module answers a narrower
+question for `--os-version`/`--runtime-version`: what versions actually
+exist right now, so a menu can offer "the two latest" without a number
+baked into this file going stale the day a project ships its next release.
+
+Nothing here decides which version is *safer* -- that is still `recommend`
+and a real scan's job. This only says what is published.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from dockerls.domain.value_objects.base_recipe import OsFamily, Runtime
+from dockerls.integrations.dockerhub.client import DockerHubClient
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+#: Which Docker Hub repository names this (runtime, family), and the tag
+#: shape that names a *stable* release in that family -- one capture group,
+#: the version. `python:3.13-rc-alpine` and `node:22-alpine3.20-slim` do not
+#: match: a release candidate or a variant tag is not what "the latest
+#: stable version" means here.
+_SOURCES: dict[tuple[Runtime, OsFamily], tuple[str, re.Pattern[str]]] = {
+    (Runtime.NONE, OsFamily.ALPINE): ("alpine", re.compile(r"^(\d+\.\d+)$")),
+    (Runtime.NONE, OsFamily.DEBIAN): ("debian", re.compile(r"^(\d+)-slim$")),
+    (Runtime.NONE, OsFamily.UBUNTU): ("ubuntu", re.compile(r"^(\d+\.\d+)$")),
+    (Runtime.JAVA, OsFamily.ALPINE): ("eclipse-temurin", re.compile(r"^(\d+)-jre-alpine$")),
+    (Runtime.JAVA, OsFamily.DEBIAN): ("eclipse-temurin", re.compile(r"^(\d+)-jre$")),
+    (Runtime.JAVA, OsFamily.UBUNTU): ("eclipse-temurin", re.compile(r"^(\d+)-jre-noble$")),
+    (Runtime.NODE, OsFamily.ALPINE): ("node", re.compile(r"^(\d+)-alpine$")),
+    (Runtime.NODE, OsFamily.DEBIAN): ("node", re.compile(r"^(\d+)-slim$")),
+    (Runtime.PYTHON, OsFamily.ALPINE): ("python", re.compile(r"^(\d+\.\d+)-alpine$")),
+    (Runtime.PYTHON, OsFamily.DEBIAN): ("python", re.compile(r"^(\d+\.\d+)-slim-bookworm$")),
+    (Runtime.GO, OsFamily.ALPINE): ("golang", re.compile(r"^(\d+\.\d+)-alpine$")),
+    (Runtime.GO, OsFamily.DEBIAN): ("golang", re.compile(r"^(\d+\.\d+)-bookworm$")),
+    (Runtime.RUBY, OsFamily.ALPINE): ("ruby", re.compile(r"^(\d+\.\d+)-alpine$")),
+    (Runtime.RUBY, OsFamily.DEBIAN): ("ruby", re.compile(r"^(\d+\.\d+)-slim-bookworm$")),
+    (Runtime.PHP, OsFamily.ALPINE): ("php", re.compile(r"^(\d+\.\d+)-cli-alpine$")),
+    (Runtime.PHP, OsFamily.DEBIAN): ("php", re.compile(r"^(\d+\.\d+)-cli-bookworm$")),
+}
+
+
+@dataclass(frozen=True)
+class VersionChoice:
+    """One version this (runtime, family) can be pinned to, and the tag it
+    resolves to today."""
+
+    version: str
+    tag: str
+
+
+def supports_version_discovery(runtime: Runtime, family: OsFamily) -> bool:
+    return (runtime, family) in _SOURCES
+
+
+def _sort_key(version: str) -> tuple[int, ...]:
+    return tuple(int(part) for part in version.split("."))
+
+
+async def discover_versions(
+    runtime: Runtime,
+    family: OsFamily,
+    *,
+    count: int = 2,
+    client: DockerHubClient | None = None,
+) -> Sequence[VersionChoice]:
+    """The `count` newest stable versions published for this combination,
+    newest first.
+
+    Returns an empty sequence -- never raises -- when the registry cannot
+    be reached or this combination has no known tag shape: an empty result
+    is "could not measure this", and the caller falls back to the catalog
+    default rather than being handed a guess dressed up as one.
+    """
+    source = _SOURCES.get((runtime, family))
+    if source is None:
+        return ()
+    repository, pattern = source
+
+    owns_client = client is None
+    client = client or DockerHubClient()
+    try:
+        # `search_tags` already degrades to a partial (or empty) result on
+        # any HTTP error instead of raising -- there is nothing further to
+        # catch here.
+        tags = await client.search_tags(repository, limit=100)
+    finally:
+        if owns_client:
+            await client.close()
+
+    by_version: dict[str, str] = {}
+    for image in tags:
+        match = pattern.match(image.tag)
+        if not match:
+            continue
+        version = match.group(1)
+        by_version.setdefault(version, image.tag)
+
+    ordered = sorted(by_version, key=_sort_key, reverse=True)
+    return [VersionChoice(version=v, tag=by_version[v]) for v in ordered[:count]]

dockerls/application/use_cases/analyze_dockerfile.py

@@ -0,0 +1,103 @@
+"""Use case para análise de Dockerfiles."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from dockerls.domain.entities.dockerfile_analysis import (
+        DockerfileAnalysis,
+        DockerfileValidationResult,
+        HardeningRule,
+    )
+    from dockerls.domain.interfaces.dockerfile_validator import (
+        DockerfileValidatorInterface,
+        HardeningTemplateProvider,
+    )
+
+
+@dataclass
+class AnalyzeDockerfileRequest:
+    """Request para análise de Dockerfile."""
+
+    dockerfile_path: str | Path
+    include_suggestions: bool = True
+    validate_only: bool = False
+
+
+@dataclass
+class AnalyzeDockerfileResponse:
+    """Resposta da análise de Dockerfile."""
+
+    success: bool
+    analysis: DockerfileAnalysis | None = None
+    validation: DockerfileValidationResult | None = None
+    suggestions: list[HardeningRule] | None = None
+    error: str | None = None
+
+    def model_dump(self) -> dict[str, Any]:
+        """Retorna dicionário serializável."""
+        return {
+            "success": self.success,
+            "analysis": self.analysis.model_dump() if self.analysis else None,
+            "validation": self.validation.model_dump() if self.validation else None,
+            "suggestions": [s.model_dump() for s in self.suggestions] if self.suggestions else [],
+            "error": self.error,
+        }
+
+
+class AnalyzeDockerfileUseCase:
+    """Caso de uso para análise de Dockerfiles."""
+
+    def __init__(
+        self,
+        validator: DockerfileValidatorInterface,
+        template_provider: HardeningTemplateProvider | None = None,
+    ):
+        self._validator = validator
+        self._template_provider = template_provider
+
+    def execute(self, request: AnalyzeDockerfileRequest) -> AnalyzeDockerfileResponse:
+        """Executa a análise do Dockerfile."""
+        try:
+            path = Path(request.dockerfile_path)
+            if path.is_dir():
+                path = path / "Dockerfile"
+
+            if not path.exists():
+                return AnalyzeDockerfileResponse(
+                    success=False,
+                    error=f"Dockerfile not found at {path}",
+                )
+
+            # Validação sempre é executada
+            validation = self._validator.validate(path)
+
+            if request.validate_only:
+                return AnalyzeDockerfileResponse(
+                    success=True,
+                    validation=validation,
+                )
+
+            # Análise completa
+            analysis = self._validator.analyze(path)
+
+            # Sugestões se solicitado
+            suggestions = []
+            if request.include_suggestions:
+                suggestions = self._validator.suggest_hardening(path)
+
+            return AnalyzeDockerfileResponse(
+                success=True,
+                analysis=analysis,
+                validation=validation,
+                suggestions=suggestions,
+            )
+
+        except Exception as e:
+            return AnalyzeDockerfileResponse(
+                success=False,
+                error=str(e),
+            )