dockerls 1.0.0__py3-none-any.whl

dockerls/cli/app.py

@@ -0,0 +1,294 @@
+"""O ponto de entrada da CLI, com os subcomandos carregados sob demanda.
+
+Este módulo importava os 24 comandos no topo, e cada um deles puxa a
+árvore inteira da aplicação: o pipeline de scan, os clientes HTTP, o
+pydantic-settings, o SQLAlchemy. Como o `import` é o que registra o
+comando no Typer, `dockerls version` -- que só imprime uma string --
+pagava os mesmos ~390ms de arranque que `dockerls advisor`.
+
+Aqui o registro deixa de depender do import. `_LazyGroup` conhece os
+comandos por uma tabela estática (nome, módulo, resumo) e só importa o
+módulo quando o comando é de fato invocado. O `--help` do grupo é
+desenhado a partir da tabela, sem importar nada.
+
+O preço é a tabela precisar acompanhar as docstrings, e é por isso que
+`tests/unit/cli/test_lazy_command_table.py` compara as duas: um comando
+novo, renomeado ou com o resumo alterado quebra o teste antes de chegar
+na CLI.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+import typer
+from typer.core import TyperCommand, TyperGroup
+from typer.main import get_command_from_info, get_group
+from typer.models import CommandInfo
+
+if TYPE_CHECKING:
+    from collections.abc import MutableMapping
+
+    from typer import _click
+
+#: O click que o Typer usa. A partir do Typer 0.27 ele é vendorizado em
+#: `typer._click`, e não há mais um `click` de topo garantido no ambiente;
+#: `typer.core.TyperCommand`/`TyperGroup` são as classes públicas
+#: correspondentes, e é delas que herdamos.
+
+
+@dataclass(frozen=True)
+class _Lazy:
+    """Um subcomando e onde encontrá-lo, sem importá-lo."""
+
+    #: Nome na linha de comando.
+    name: str
+    #: Módulo em `dockerls.cli.commands`.
+    module: str
+    #: Nome do objeto dentro do módulo.
+    attr: str
+    #: Primeiro parágrafo da docstring, que é o que o `--help` do grupo
+    #: mostra. Duplicado aqui de propósito: é o único jeito de listar os
+    #: comandos sem importar todos eles.
+    summary: str
+    #: `True` quando o objeto é um `typer.Typer` (um subgrupo) em vez de
+    #: uma função de comando.
+    is_group: bool = False
+
+    def load(self, *, rich_markup_mode: Any) -> _click.Command:
+        """Importa o módulo e monta o comando click de verdade."""
+        target = getattr(import_module(f"dockerls.cli.commands.{self.module}"), self.attr)
+        if self.is_group:
+            group = get_group(target)
+            group.name = self.name
+            group.help = self.summary
+            return group
+        command = get_command_from_info(
+            CommandInfo(name=self.name, callback=target),
+            pretty_exceptions_short=False,
+            rich_markup_mode=rich_markup_mode,
+        )
+        return command
+
+
+#: Os subcomandos, na ordem em que aparecem no `--help`.
+COMMANDS: tuple[_Lazy, ...] = (
+    _Lazy(
+        "search",
+        "search",
+        "search",
+        "Search for available tags of an image, on Docker Hub or any configured source.",
+    ),
+    _Lazy("recommend", "recommend", "recommend", "Recommend the most secure Docker image tags."),
+    _Lazy(
+        "advisor",
+        "advisor",
+        "advisor",
+        "Security advisor: analyze and provide actionable remediation plan.",
+    ),
+    _Lazy(
+        "alternatives",
+        "alternatives",
+        "alternatives",
+        "Find safer alternatives to an image you already run, with trade-offs.",
+    ),
+    _Lazy("analyze", "analyze", "analyze", "Deep-analyze a specific Docker image tag."),
+    _Lazy(
+        "analyze-dockerfile",
+        "analyze_dockerfile",
+        "analyze",
+        "Analyze a Dockerfile for security problems.",
+    ),
+    _Lazy(
+        "base",
+        "base_cmd",
+        "base",
+        "Check the Dockerfile bases against the registry and refresh their digests.",
+    ),
+    _Lazy(
+        "base-image",
+        "base_image",
+        "base_image",
+        "Generate the Dockerfile for a base image from a menu of choices.",
+    ),
+    _Lazy(
+        "build",
+        "build",
+        "build",
+        "Build secure Docker images with validation, scanning and auto-remediation.",
+    ),
+    _Lazy("compare", "compare", "compare", "Compare security posture of multiple Docker images."),
+    _Lazy(
+        "controls",
+        "controls",
+        "controls",
+        "Show the security controls each Dockerfile rule implements.",
+    ),
+    _Lazy(
+        "fleet",
+        "fleet",
+        "fleet",
+        "Scan a tree of repositories and summarise the state of its Dockerfiles.",
+    ),
+    _Lazy(
+        "policy",
+        "policy_cmd",
+        "policy",
+        "Show and validate the policy declared in `.dockerls-policy.yaml`.",
+    ),
+    _Lazy(
+        "provenance",
+        "provenance_cmd",
+        "provenance",
+        "Check a provenance document and prepare the attestation.",
+    ),
+    _Lazy(
+        "registry-audit",
+        "registry_audit_cmd",
+        "registry_audit",
+        "Establish, through the registry, what is known about a published image.",
+    ),
+    _Lazy("verify", "verify", "verify", "Check an image signature with cosign."),
+    _Lazy("export", "export", "export", "Export analysis results in various formats."),
+    _Lazy(
+        "login",
+        "login",
+        "login",
+        "Authenticate with Docker Hub. Credentials are stored in your system keyring.",
+    ),
+    _Lazy("logout", "login", "logout", "Remove stored Docker Hub credentials."),
+    _Lazy("version", "version", "version", "Show DockerLs version."),
+    _Lazy("doctor", "doctor", "doctor", "Check system dependencies and configuration."),
+    _Lazy("health", "health", "health", "Check connectivity to external services."),
+    _Lazy(
+        "sbom",
+        "sbom",
+        "sbom",
+        "Generate a Software Bill of Materials (SBOM) for an image via Trivy.",
+    ),
+    _Lazy(
+        "vex",
+        "vex_cmd",
+        "vex",
+        "Emit this repository's exemptions as an OpenVEX document.",
+    ),
+    _Lazy("cache", "cache_cmd", "cache_app", "Manage scan cache", is_group=True),
+)
+
+_BY_NAME: dict[str, _Lazy] = {spec.name: spec for spec in COMMANDS}
+
+
+class _Stub(TyperCommand):
+    """O comando como o `--help` do grupo o vê: nome e resumo, mais nada.
+
+    Existe para que listar os comandos não importe nenhum deles. Tudo que
+    precisa do comando de verdade -- executar, mostrar o próprio `--help`,
+    completar argumentos -- passa por `make_context`/`shell_complete`, e
+    esses resolvem o módulo antes de responder.
+    """
+
+    def __init__(self, spec: _Lazy, rich_markup_mode: Any) -> None:
+        super().__init__(name=spec.name, short_help=spec.summary)
+        self._spec = spec
+        self._rich_markup_mode = rich_markup_mode
+
+    def _real(self) -> _click.Command:
+        return self._spec.load(rich_markup_mode=self._rich_markup_mode)
+
+    def make_context(
+        self,
+        info_name: str | None,
+        args: list[str],
+        parent: _click.Context | None = None,
+        **extra: Any,
+    ) -> _click.Context:
+        # O contexto devolvido carrega o comando de verdade, e é dele que
+        # o click tira o `invoke`: o stub some da execução aqui.
+        return self._real().make_context(info_name, args, parent=parent, **extra)
+
+    def shell_complete(self, ctx: _click.Context, incomplete: str) -> list[Any]:
+        return self._real().shell_complete(ctx, incomplete)
+
+
+class _LazyGroup(TyperGroup):
+    """O grupo raiz: conhece os nomes sempre, os módulos só quando preciso."""
+
+    def list_commands(self, ctx: _click.Context) -> list[str]:
+        return [spec.name for spec in COMMANDS]
+
+    def get_command(self, ctx: _click.Context, cmd_name: str) -> _click.Command | None:
+        spec = _BY_NAME.get(cmd_name)
+        if spec is None:
+            return None
+        return _Stub(spec, self.rich_markup_mode)
+
+    @property
+    def commands(self) -> MutableMapping[str, _click.Command]:
+        """Compatibilidade: click e typer leem `.commands` em alguns
+        caminhos (completação, `to_info_dict`). Devolver os stubs mantém
+        esses caminhos funcionando sem importar nada."""
+        return {spec.name: _Stub(spec, self.rich_markup_mode) for spec in COMMANDS}
+
+    @commands.setter
+    def commands(self, value: MutableMapping[str, _click.Command]) -> None:
+        # `TyperGroup.__init__` atribui o dicionário (vazio) de comandos
+        # registrados; a tabela estática é a fonte da verdade, então a
+        # atribuição é descartada.
+        return
+
+
+app = typer.Typer(
+    name="dockerls",
+    cls=_LazyGroup,
+    help="DockerLs -- Enterprise Docker Image Security Advisor. "
+    "Discover the most secure Docker images available on Docker Hub.",
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+)
+
+
+def configure_logging() -> None:
+    """Detach loguru's default sink, importing the container only now.
+
+    Indireção de propósito: nem `cli.runtime` pode ser importado no topo,
+    ou `dockerls --help` -- que não configura sink nenhum, porque nem chega
+    a invocar um subcomando -- pagaria o pydantic-settings junto. Manter o
+    nome aqui, em vez de esconder o import dentro de `_bootstrap`, preserva
+    o ponto de substituição que os testes de bootstrap usam.
+    """
+    from dockerls.cli import runtime
+
+    runtime.configure_logging()
+
+
+@app.callback()
+def _bootstrap() -> None:
+    """Runs before every subcommand, so no command can start with loguru's
+    default DEBUG-to-stderr sink still attached."""
+    configure_logging()
+
+
+def main() -> None:
+    try:
+        app()
+    finally:
+        _dispose_cache_if_loaded()
+
+
+def _dispose_cache_if_loaded() -> None:
+    """Close the shared SQLite engine, without paying to import the module
+    that owns it when the command never touched it.
+
+    `cli.dependencies` pulls in SQLAlchemy and the rest of the application
+    stack, which is exactly what the lazy command table above exists to
+    keep `dockerls --help`/`version` from paying for. Checking
+    `sys.modules` instead of importing unconditionally means a command that
+    never built a cache -- which never imports `cli.dependencies` at all --
+    still doesn't, even after it finishes.
+    """
+    dependencies = sys.modules.get("dockerls.cli.dependencies")
+    if dependencies is not None:
+        dependencies.close_cache()

dockerls/cli/commands/advisor.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import TYPE_CHECKING
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from dockerls.application.services.ecosystems import get_ecosystem_insights
+from dockerls.application.services.migration import MigrationPlan, plan_migration
+from dockerls.application.use_cases.recommend_images import build_recommendation
+from dockerls.cli.dependencies import build_analyze_use_case, build_recommend_use_case
+from dockerls.cli.image_names import split_repository_and_tag
+from dockerls.cli.options import OutputFormat, parse_output_format
+from dockerls.cli.scan_failure import describe_scan_failure
+from dockerls.cli.text import safe
+from dockerls.cli.validators import check_workers
+from dockerls.exit_codes import EXIT_ERROR
+
+if TYPE_CHECKING:
+    from dockerls.application.dto.analysis import ImageAnalysis
+
+console = Console()
+# Diagnostics go to stderr, results to stdout. Printing a warning to stdout
+# put a human sentence in front of the JSON document and made `--format json`
+# unparseable -- a machine-readable format is only machine-readable if
+# nothing else can land in the stream.
+diagnostics = Console(stderr=True)
+
+
+def advisor(
+    image: str = typer.Argument(help="Docker image name (e.g., node, python, nginx)"),
+    workers: int | None = typer.Option(
+        None,
+        "--workers",
+        "-w",
+        help="Concurrent scanner processes; 0 sizes it to this machine [config: workers]",
+    ),
+    output_format: str = typer.Option(
+        OutputFormat.TABLE.value, "--format", "-f", help="Output format: table or json"
+    ),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable colored output"),
+) -> None:
+    """Security advisor: analyze and provide actionable remediation plan."""
+    if no_color:
+        console.no_color = True
+    fmt = parse_output_format(output_format)
+    # `0` means "size it to this machine", so it is passed through rather
+    # than validated: the resolver, not the flag, decides what it becomes.
+    if workers:
+        workers = check_workers(workers)
+    try:
+        asyncio.run(_advisor(image, workers, fmt))
+    except ValueError as e:
+        console.print(f"[red]Invalid configuration:[/red] {e}")
+        raise typer.Exit(EXIT_ERROR) from e
+
+
+async def _advisor(image: str, workers: int | None, output_format: OutputFormat) -> None:
+    # A tagged argument names an image the user runs *today*, so the advice
+    # can be a migration rather than a standalone suggestion. A bare name
+    # ("node") has no current image to move away from, and the command
+    # behaves exactly as it always has.
+    # O `rsplit(":", 1)` que morava aqui lia a porta do registry como tag:
+    # `advisor registry.internal:5000/app` procurava o repositório
+    # "registry.internal". A regra compartilhada só aceita dois-pontos no
+    # último segmento do caminho.
+    repository, current_tag = split_repository_and_tag(image)
+    current = await _analyze_current(image) if current_tag else None
+
+    use_case = await build_recommend_use_case(workers=workers)
+    result = await use_case.execute(repository)
+
+    items = result.recommendations or result.alternatives
+    if not items:
+        if output_format == OutputFormat.JSON:
+            error_payload = {"error": "No images found to advise on", "errors": result.errors}
+            console.print(json.dumps(error_payload), soft_wrap=True)
+        else:
+            console.print("[red]No images found to advise on.[/red]")
+        raise typer.Exit(EXIT_ERROR)
+
+    best = items[0]
+    # O plano de remediação é sobre a imagem que o usuário roda **hoje**,
+    # sempre que ele nomeou uma. Montá-lo sobre `best` -- a candidata que a
+    # busca elegeu -- descrevia as CVEs de outra imagem sob o título da que
+    # foi pedida: `advisor eclipse-temurin:21-jre-alpine` respondia com
+    # "Update stdlib (go1.26.5 -> 1.25.13)" e IDs `GO-...`, que não existem
+    # dentro de um JRE. Corrigir a saída não bastaria: os passos precisam
+    # nascer das vulnerabilidades que o scanner devolveu para *aquela*
+    # imagem, e é isso que a escolha do alvo aqui garante.
+    #
+    # Sem tag na linha de comando não há imagem atual, e o plano sobre a
+    # melhor candidata é o comportamento correto (e o original).
+    target = current if current is not None else best
+    rec = target.recommendation or build_recommendation(target)
+    insights = get_ecosystem_insights(target.image.full_reference or image)
+    # Only when the target is genuinely a different image: a "migration"
+    # from an image to itself is noise, and printing a checklist for it
+    # would suggest work that does not exist.
+    plan = (
+        plan_migration(current, best)
+        if current is not None and current.image.full_reference != best.image.full_reference
+        else None
+    )
+
+    if output_format == OutputFormat.JSON:
+        payload = best.model_dump()
+        payload["remediation"] = rec.model_dump()
+        # Qual imagem o plano endereça, dito explicitamente: o documento
+        # carrega `best` na raiz, e sem este campo um consumidor não teria
+        # como saber que a remediação é sobre outra imagem.
+        payload["remediation_target"] = target.image.full_reference
+        payload["ecosystem_insights"] = {
+            # As particularidades seguem o mesmo alvo do plano, e não a raiz
+            # do documento (que carrega `best`). Sem este campo um consumidor
+            # leria conselho sobre Debian ao lado de uma candidata Alpine sem
+            # nada dizendo que são imagens diferentes.
+            "for": target.image.full_reference,
+            "ecosystem": insights.ecosystem,
+            "version": insights.version,
+            "runtime_features": insights.runtime_features,
+            "base_distro_advice": insights.base_distro_advice,
+            "security_guidelines": insights.security_guidelines,
+            "common_pitfalls": insights.common_pitfalls,
+            "snippets": insights.recommended_dockerfile_snippets,
+        }
+        if plan is not None:
+            payload["migration"] = plan.model_dump()
+        if current is not None:
+            payload["current"] = current.model_dump()
+        console.print(json.dumps(payload, indent=2, default=str), soft_wrap=True)
+        return
+
+    console.print(Panel(f"[bold cyan]DockerLs Security Advisor: {image}[/bold cyan]", expand=False))
+    console.print()
+
+    info = Table(show_header=False, box=None, padding=(0, 2))
+    info.add_column("Key", style="bold")
+    info.add_column("Value")
+    info.add_row("Current Best Image", f"[cyan]{safe(best.image.full_reference)}[/cyan]")
+    info.add_row("Ecosystem / Runtime", f"{insights.ecosystem} ({insights.version})")
+    info.add_row("Security Score", f"[green]{best.security_score}[/green]")
+    info.add_row("Tier", best.tier)
+    info.add_row("Critical", f"[red]{best.scan.critical_count}[/red]")
+    info.add_row("High", f"[yellow]{best.scan.high_count}[/yellow]")
+    info.add_row("Medium", str(best.scan.medium_count))
+    info.add_row("Fixable High", str(best.scan.fixable_high_count))
+    info.add_row("Remediation Score", f"{best.remediation_score}%")
+    info.add_row("EOL", "Yes" if best.is_eol else "No")
+    info.add_row("LTS", "Yes" if best.is_lts else "No")
+    console.print(info)
+
+    if insights.base_distro_advice or insights.security_guidelines:
+        console.print()
+        console.print(
+            Panel(
+                "[bold magenta]Ecosystem Particularities & Hardening[/bold magenta]",
+                expand=False,
+            )
+        )
+        if insights.base_distro_advice:
+            console.print("\n[bold]Base Image & Distribution Notes:[/bold]")
+            for advice in insights.base_distro_advice:
+                console.print(f"  - {advice}")
+        if insights.security_guidelines:
+            console.print("\n[bold]Production & Security Guidelines:[/bold]")
+            for item in insights.security_guidelines:
+                console.print(f"  - {item}")
+        if insights.common_pitfalls:
+            console.print("\n[bold red]Common Pitfalls to Avoid:[/bold red]")
+            for pit in insights.common_pitfalls:
+                console.print(f"  [yellow]![/yellow] {pit}")
+
+    if plan is not None:
+        _print_migration(plan)
+
+    if rec.steps:
+        console.print()
+        # A imagem nomeada no cabeçalho: um plano cujos passos citam versões
+        # de pacote precisa dizer de qual imagem essas versões vieram.
+        console.print(
+            f"[bold]Remediation Plan[/bold] [dim]for {safe(target.image.full_reference)}[/dim]"
+        )
+        console.print()
+        for step in rec.steps:
+            desc = step.description
+            if step.from_value and step.to_value:
+                desc += f" [dim]({step.from_value} -> {step.to_value})[/dim]"
+            console.print(f"  STEP {step.step_number}: {desc}")
+            if step.expected_impact:
+                console.print(f"         [dim]{step.expected_impact}[/dim]")
+
+    if rec.summary:
+        console.print()
+        console.print(f"[bold]Summary:[/bold] {rec.summary}")
+
+
+async def _analyze_current(reference: str) -> ImageAnalysis | None:
+    """Scan the image named on the command line, or give up quietly.
+
+    Failing to measure the current image costs the migration section, not
+    the command: the advice about the best available image is still valid,
+    and claiming an improvement over something never measured would not be.
+    """
+    use_case = await build_analyze_use_case()
+    try:
+        analysis = await use_case.execute(reference)
+    except (ValueError, RuntimeError) as e:
+        diagnostics.print(f"[yellow]Could not analyze {reference} for comparison: {e}[/yellow]")
+        return None
+    finally:
+        # O scanner e o pool de conexões do repositório ficam abertos até
+        # alguém fechá-los, e este comando abre um segundo conjunto logo
+        # abaixo para a busca. `analyze` fecha no mesmo ponto; não fechar
+        # aqui era o único caminho que vazava.
+        await use_case.close()
+
+    # Um scan que não completou devolve score 0.0 e tier F por construção.
+    # Aceitá-lo como medição faria o plano de migração afirmar uma melhora
+    # sobre um número que não mede nada.
+    if not analysis.scan.is_verified:
+        cause = describe_scan_failure(analysis.scan.error_kind, analysis.scan.error_message)
+        diagnostics.print(
+            f"[yellow]Could not analyze {safe(reference)} for comparison: {safe(cause)}[/yellow]"
+        )
+        return None
+    return analysis
+
+
+def _print_migration(plan: MigrationPlan) -> None:
+    """The move from what the user runs to what was measured as better."""
+    console.print()
+    console.print(Panel("[bold green]Migration[/bold green]", expand=False))
+    console.print(f"  CURRENT      [cyan]{plan.from_reference}[/cyan]")
+    console.print(f"  RECOMMENDED  [green]{plan.to_reference}[/green]")
+    if plan.to_pinned_reference != plan.to_reference:
+        console.print(f"  PIN TO       [dim]{plan.to_pinned_reference}[/dim]")
+
+    delta = plan.score_delta
+    colour = "green" if delta > 0 else "red"
+    console.print(f"\n  SECURITY IMPROVEMENT  [{colour}]{delta:+.1f} points[/{colour}]")
+
+    if plan.improvements:
+        console.print("\n[bold]WHY[/bold]")
+        for reason in plan.improvements:
+            console.print(f"  [green]OK[/green] {safe(reason)}")
+    if plan.trade_offs:
+        console.print("\n[bold]TRADE-OFFS[/bold]")
+        for cost in plan.trade_offs:
+            console.print(f"  [yellow]![/yellow] {safe(cost)}")
+    if plan.checklist:
+        console.print("\n[bold]MIGRATION CHECKLIST[/bold]")
+        for i, step in enumerate(plan.checklist, 1):
+            console.print(f"  {i}. {safe(step)}")
+    console.print(
+        "\n[dim]Compatibility is never assumed: nothing here can tell you your "
+        "application still runs. That is what the checklist is for.[/dim]"
+    )