dockerls 1.0.0__py3-none-any.whl

dockerls/cli/commands/cache_cmd.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from dockerls.cli.dependencies import build_cache
+from dockerls.exit_codes import EXIT_ERROR
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+console = Console()
+#: `no_args_is_help`: `dockerls cache` with no subcommand used to print a bare
+#: "Missing command." and nothing else, forcing anyone who typed it to know
+#: to add `--help` themselves. This lists the subcommands right there instead.
+cache_app = typer.Typer(help="Manage the scan cache", no_args_is_help=True)
+
+
+def _run(coro: Coroutine[Any, Any, None]) -> None:
+    """Run a cache operation, reporting storage failures as user errors.
+
+    A corrupt or unreadable cache database is a normal operational state --
+    it must not exit with a traceback, especially for `clear`, which is
+    exactly what a user reaches for when the cache is broken.
+    """
+    # Import tardio: `sqlalchemy.exc` arrasta o SQLAlchemy inteiro, e este
+    # módulo é importado no arranque de *toda* invocação do CLI para registrar
+    # o subcomando. Aqui dentro ele só é pago por quem realmente mexe no cache.
+    from sqlalchemy.exc import SQLAlchemyError
+
+    try:
+        asyncio.run(coro)
+    except (OSError, SQLAlchemyError) as e:
+        console.print(f"[red]Cache operation failed:[/red] {e}")
+        raise typer.Exit(EXIT_ERROR) from e
+
+
+@cache_app.command("clear")
+def cache_clear() -> None:
+    """Clear all cached scan results."""
+    _run(_clear())
+
+
+async def _clear() -> None:
+    cache = build_cache()
+    await cache.clear()
+    console.print("[green]Cache cleared.[/green]")
+
+
+@cache_app.command("cleanup")
+def cache_cleanup() -> None:
+    """Remove expired cache entries."""
+    _run(_cleanup())
+
+
+async def _cleanup() -> None:
+    cache = build_cache()
+    count = await cache.cleanup_expired()
+    console.print(f"[green]Removed {count} expired entries.[/green]")
+
+
+@cache_app.command("stats")
+def cache_stats() -> None:
+    """Show cache size, entry count, and how much is reclaimable."""
+    _run(_stats())
+
+
+async def _stats() -> None:
+    """Report what the cache is holding.
+
+    Entries expire lazily -- a stale row is dropped when it is next read --
+    so a cache can carry entries for tags nobody asks about again. Without a
+    way to see that, "why is this directory large" and "would cleanup help"
+    were both unanswerable.
+    """
+    cache = build_cache()
+    stats = await cache.stats()
+
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column("Field", style="bold")
+    table.add_column("Value")
+    table.add_row("Location", stats.path)
+    table.add_row("Entries", str(stats.total))
+    table.add_row("Expired (reclaimable)", str(stats.expired))
+    table.add_row("Size on disk", _human_bytes(stats.size_bytes))
+    console.print(table)
+
+    if stats.expired:
+        console.print(
+            f"\n[dim]Run `dockerls cache cleanup` to remove {stats.expired} expired entries.[/dim]"
+        )
+
+
+def _human_bytes(size: int) -> str:
+    value = float(size)
+    for unit in ("B", "KB", "MB", "GB"):
+        if value < 1024 or unit == "GB":
+            return f"{value:.1f} {unit}" if unit != "B" else f"{int(value)} B"
+        value /= 1024
+    return f"{value:.1f} GB"  # pragma: no cover - unreachable, loop returns first

dockerls/cli/commands/compare.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from dockerls.cli.dependencies import build_compare_use_case
+from dockerls.cli.scan_failure import describe_scan_failure
+from dockerls.cli.text import safe
+from dockerls.exit_codes import EXIT_ERROR, EXIT_OK
+
+if TYPE_CHECKING:
+    from dockerls.application.dto.analysis import ComparisonResult
+
+console = Console()
+
+# Exit codes, em ordem de severidade:
+#   0 = comparação completa: toda imagem pedida foi escaneada
+#   1 = erro rígido: uso inválido, ou nenhuma imagem pôde ser escaneada
+#   2 = comparação parcial: 2+ escanearam, 1+ falharam
+#   3 = dado insuficiente: menos de duas imagens escaneadas, nada a comparar
+# 0 e 1 vêm do contrato compartilhado; 2 e 3 são próprios de `compare` --
+# a diferença entre "comparei tudo" e "comparei o que deu" é justamente o
+# que um portão de CI precisa poder distinguir.
+EXIT_COMPLETE = EXIT_OK
+EXIT_ERROR_CODE = EXIT_ERROR
+EXIT_PARTIAL = 2
+EXIT_INSUFFICIENT = 3
+
+
+def compare(
+    images: list[str] = typer.Argument(help="Two or more image references to compare"),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable colored output"),
+) -> None:
+    """Compare security posture of multiple Docker images.
+
+    Exit codes: 0 = every image was scanned and compared; 1 = invalid use, or
+    no image could be scanned at all; 2 = partial comparison, at least two
+    images were scanned and at least one failed; 3 = fewer than two images
+    could be scanned, so there is nothing to compare.
+
+    An image that could not be scanned is never given a score or a tier: it
+    is listed separately, with the classified reason.
+    """
+    if no_color:
+        console.no_color = True
+    if len(images) < 2:
+        console.print("[red]Provide at least two images to compare.[/red]")
+        raise typer.Exit(EXIT_ERROR_CODE)
+    asyncio.run(_compare(images))
+
+
+async def _compare(images: list[str]) -> None:
+    use_case = await build_compare_use_case()
+    try:
+        result = await use_case.execute(images)
+    except ValueError as e:
+        console.print(f"[red]Scan failed: {e}[/red]")
+        raise typer.Exit(EXIT_ERROR_CODE) from e
+
+    # `result.images` já chega filtrado pelo use case: só entra aqui quem
+    # tem scan verificado. A tabela abaixo, portanto, não tem como exibir
+    # um score que ninguém mediu.
+    measured = result.images
+
+    if not measured:
+        # Nada foi medido. Não é um veredito sobre as imagens -- é a
+        # ausência de um --, e o código 1 diz isso: falha de execução.
+        _print_failures(result)
+        console.print(
+            "\n[bold red]No image could be scanned.[/bold red]\n"
+            "[dim]This is a technical failure, not a security verdict: nothing was "
+            "measured, so nothing can be said about these images.[/dim]"
+        )
+        raise typer.Exit(EXIT_ERROR_CODE)
+
+    if len(measured) < 2:
+        # Uma imagem medida não é uma comparação. Mostrar a tabela com uma
+        # linha só sugeriria um vencedor onde não houve disputa.
+        _print_failures(result)
+        console.print(
+            f"\n[bold yellow]Not enough data to compare.[/bold yellow]\n"
+            f"[yellow]Only {safe(measured[0].image.full_reference)} could be scanned; "
+            f"a comparison needs at least two.[/yellow]"
+        )
+        raise typer.Exit(EXIT_INSUFFICIENT)
+
+    console.print(Panel("[bold]Image Comparison[/bold]", expand=False))
+
+    table = Table()
+    table.add_column("Image", style="cyan")
+    table.add_column("Score", justify="right", style="green")
+    table.add_column("Tier", justify="center")
+    table.add_column("Critical", justify="right", style="red")
+    table.add_column("High", justify="right", style="yellow")
+    table.add_column("Medium", justify="right")
+    table.add_column("Total Vulns", justify="right")
+    table.add_column("Fixable", justify="right")
+    table.add_column("Remediation", justify="right")
+
+    for a in measured:
+        table.add_row(
+            safe(a.image.full_reference),
+            str(a.security_score),
+            a.tier,
+            str(a.scan.critical_count),
+            str(a.scan.high_count),
+            str(a.scan.medium_count),
+            str(a.scan.total_count),
+            str(a.scan.fixable_count),
+            f"{a.remediation_score}/100",
+        )
+    console.print(table)
+
+    _print_verdict(result)
+    _print_failures(result)
+
+    if result.unverified:
+        console.print(
+            f"\n[dim]Partial comparison: {len(measured)} of "
+            f"{len(measured) + len(result.unverified)} image(s) were measured.[/dim]"
+        )
+        raise typer.Exit(EXIT_PARTIAL)
+    raise typer.Exit(EXIT_COMPLETE)
+
+
+def _print_failures(result: ComparisonResult) -> None:
+    """As imagens que não puderam ser medidas, com a causa classificada.
+
+    Seção própria, e nunca uma linha na tabela: o leitor precisa ver de
+    imediato que estas não foram comparadas com as outras, e sim deixadas
+    de fora por falta de medição.
+    """
+    if not result.unverified:
+        return
+    console.print("\n[bold yellow]Failed (not compared)[/bold yellow]")
+    console.print("[dim]  These images were never scored -- no successful scan.[/dim]")
+    for item in result.unverified:
+        console.print(
+            f"  {safe(item.image_reference)}  "
+            f"[dim]{safe(describe_scan_failure(item.kind, item.reason))}[/dim]"
+        )
+
+
+def _print_verdict(result: ComparisonResult) -> None:
+    """Vencedor primeiro, depois cada perdedor com o próprio delta.
+
+    A versão anterior juntava tudo numa linha -- vencedor, score absoluto e
+    diferença separados por ponto e vírgula --, e o `-36.0 points` do final
+    lia como um score negativo em vez de uma distância até o vencedor.
+    """
+    winner = next((a for a in result.images if a.image.full_reference == result.winner), None)
+    if winner is None:
+        return
+
+    console.print(
+        f"\n[bold green]Winner: {safe(winner.image.full_reference)}[/bold green] "
+        f"[dim](Score {winner.security_score}, Tier {winner.tier})[/dim]"
+    )
+    for a in result.images:
+        if a.image.full_reference == result.winner:
+            continue
+        delta = a.security_score - winner.security_score
+        console.print(
+            f"  {safe(a.image.full_reference)}  Score {a.security_score}, Tier {a.tier}  "
+            f"[dim]({delta:+.1f} vs. winner)[/dim]"
+        )
+
+    if result.common_vulns:
+        console.print(f"\n[bold]Shared vulnerabilities:[/bold] {len(result.common_vulns)}")
+    for reference, vulns in result.unique_vulns.items():
+        if vulns:
+            console.print(f"[dim]Unique to {safe(reference)}: {len(vulns)}[/dim]")

dockerls/cli/commands/controls.py

@@ -0,0 +1,110 @@
+"""`dockerls controls` -- the published controls behind each Dockerfile rule.
+
+`analyze-dockerfile` cites a control next to every finding it reports, which
+answers "why is this a problem" at the moment the reader has to act. It does
+not answer the question that comes before that one: *what does this tool
+check, and on whose authority*. Somebody deciding whether to put DockerLs in
+front of a build has to be able to read the whole rulebook without first
+producing a Dockerfile that fails.
+
+This command is that rulebook. It also states, per rule, whether the
+citation exists at all: a rule backed by CIS or NIST and a rule backed by
+this project's own judgement are both legitimate, but they are not the same
+claim, and collapsing them would be the same kind of overstatement as
+reporting an unmeasured image as clean.
+"""
+
+from __future__ import annotations
+
+import json
+
+import typer
+from rich.console import Console
+
+from dockerls.cli.options import OutputFormat, parse_output_format
+from dockerls.cli.text import safe
+from dockerls.domain.security_controls import RULE_MAPPINGS, RuleMapping, mapping_for
+from dockerls.exit_codes import EXIT_ERROR, EXIT_OK
+
+console = Console()
+
+#: Shown when a rule carries no published control. Spelled out rather than
+#: left blank, because a blank reads as "citation omitted".
+UNDOCUMENTED_NOTE = "DockerLs guidance; no published control in the catalogue covers this rule"
+
+
+def controls(
+    rule: str = typer.Argument(
+        "", help="Rule to explain (e.g. DF002). Omit to list the whole catalogue."
+    ),
+    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:
+    """Show the security controls each Dockerfile rule implements."""
+    if no_color:
+        console.no_color = True
+    fmt = parse_output_format(output_format)
+
+    if rule:
+        mapping = mapping_for(rule)
+        if mapping is None:
+            _report_unknown(rule, fmt)
+            raise typer.Exit(EXIT_ERROR)
+        selected: tuple[RuleMapping, ...] = (mapping,)
+    else:
+        selected = RULE_MAPPINGS
+
+    if fmt == OutputFormat.JSON:
+        console.print(json.dumps([_as_dict(m) for m in selected], indent=2), soft_wrap=True)
+    else:
+        _render(selected, detailed=bool(rule))
+    raise typer.Exit(EXIT_OK)
+
+
+def _as_dict(mapping: RuleMapping) -> dict[str, object]:
+    return {
+        "rule_id": mapping.rule_id,
+        "summary": mapping.summary,
+        "rationale": mapping.rationale,
+        "documented": mapping.is_documented,
+        "controls": [
+            {
+                "source": control.source.value,
+                "identifier": control.identifier,
+                "title": control.title,
+                "reference": str(control),
+            }
+            for control in mapping.controls
+        ],
+    }
+
+
+def _report_unknown(rule: str, output_format: OutputFormat) -> None:
+    known = ", ".join(mapping.rule_id for mapping in RULE_MAPPINGS)
+    message = f"regra desconhecida: {rule}"
+    if output_format == OutputFormat.JSON:
+        console.print(json.dumps({"error": message, "known_rules": known.split(", ")}))
+        return
+    console.print(f"[red]Error:[/red] {safe(message)}")
+    console.print(f"[dim]Regras catalogadas: {known}[/dim]")
+
+
+def _render(mappings: tuple[RuleMapping, ...], *, detailed: bool) -> None:
+    for mapping in mappings:
+        console.print(f"[cyan bold]{mapping.rule_id}[/cyan bold]  {safe(mapping.summary)}")
+        if detailed:
+            console.print(f"  [dim]{safe(mapping.rationale)}[/dim]")
+        for control in mapping.controls:
+            console.print(f"  [green]->[/green] {safe(str(control))}")
+        if not mapping.is_documented:
+            console.print(f"  [dim]-> {UNDOCUMENTED_NOTE}[/dim]")
+        console.print()
+
+    if not detailed:
+        documented = sum(1 for mapping in mappings if mapping.is_documented)
+        console.print(
+            f"[dim]{documented} of {len(mappings)} rules cite a published control. "
+            "Run `dockerls controls DF002` to see the rationale for one rule.[/dim]"
+        )