dockerls 1.0.0__py3-none-any.whl

dockerls/cli/commands/fleet.py

@@ -0,0 +1,159 @@
+"""`dockerls fleet` -- o retrato de todos os Dockerfiles de uma vez.
+
+Cada comando desta ferramenta olha para um artefato. Isso resolve a pergunta
+de quem está com o arquivo aberto e não resolve nenhuma das perguntas de quem
+responde por trinta repositórios: "quantos ainda rodam como root?", "quantos
+fixam a base?", "por onde eu começo?". Sem resposta, a resposta na prática vira
+"por onde alguém reclamar".
+
+A saída é uma fila de trabalho, ordenada por violações e desempatada pelo
+caminho -- para que duas varreduras da mesma frota sejam comparáveis.
+
+O que este comando não faz está dito na própria saída, e não é modéstia: ele
+lê Dockerfiles, não constrói imagem nem chama scanner. Um "relatório de
+segurança da frota" que na verdade leu arquivos seria exatamente a promessa
+que o resto desta ferramenta existe para não fazer.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+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.value_objects.tristate import Tristate
+from dockerls.exit_codes import EXIT_ERROR, EXIT_OK, EXIT_POLICY
+
+if TYPE_CHECKING:
+    from dockerls.domain.value_objects.fleet import FleetReport
+
+console = Console()
+
+_USER_LABEL = {
+    Tristate.TRUE: "[green]non-root[/green]",
+    Tristate.FALSE: "[red]root[/red]",
+    Tristate.UNKNOWN: "[yellow]undetermined[/yellow]",
+}
+
+
+def fleet(
+    root: str = typer.Argument(".", help="Root of the tree to scan"),
+    policy_path: str | None = typer.Option(
+        None,
+        "--policy",
+        help=(
+            "Policy to check every Dockerfile against (default: .dockerls-policy.yaml "
+            "at the root, when present). Only rules decidable without a build apply"
+        ),
+    ),
+    output_format: str = typer.Option(
+        OutputFormat.TABLE.value, "--format", "-f", help="Output format: table or json"
+    ),
+    limit: int = typer.Option(0, "--limit", help="Show only the first N in the queue (0 = all)"),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable colored output"),
+) -> None:
+    """Scan a tree of repositories and summarise the state of its Dockerfiles."""
+    if no_color:
+        console.no_color = True
+    fmt = parse_output_format(output_format)
+
+    from dockerls.application.use_cases.fleet_scan import FleetScanRequest, FleetScanUseCase
+    from dockerls.infrastructure.config.policy_file import (
+        PolicyFileError,
+        find_policy_file,
+        load_policy,
+    )
+    from dockerls.infrastructure.dockerfile_validator import DockerfileValidator
+
+    target = Path(root)
+    if not target.is_dir():
+        console.print(f"[red]Error:[/red] {safe(root)} is not a directory")
+        raise typer.Exit(EXIT_ERROR)
+
+    policy_file = Path(policy_path) if policy_path else find_policy_file(target)
+    declared = None
+    if policy_file is not None:
+        if not policy_file.is_file():
+            console.print(f"[red]Error:[/red] policy not found: {safe(str(policy_file))}")
+            raise typer.Exit(EXIT_ERROR)
+        try:
+            declared = load_policy(policy_file)
+        except PolicyFileError as e:
+            console.print(f"[red]Error:[/red] {safe(str(e))}")
+            raise typer.Exit(EXIT_ERROR) from e
+
+    report = FleetScanUseCase(DockerfileValidator()).execute(
+        FleetScanRequest(root=str(target), policy=declared)
+    )
+
+    if fmt == OutputFormat.JSON:
+        console.print(json.dumps(report.to_dict(), indent=2, ensure_ascii=False), soft_wrap=True)
+    else:
+        _render(report, limit=limit)
+
+    # Reprova quando há violação: é o que torna a varredura utilizável como
+    # portão de um repositório-guarda-chuva. Sem política declarada não há o
+    # que reprovar, e o silêncio aqui não é conformidade.
+    raise typer.Exit(EXIT_POLICY if report.total_violations else EXIT_OK)
+
+
+def _render(report: FleetReport, *, limit: int) -> None:
+    console.print(f"\n[bold]{safe(report.root)}[/bold]")
+    console.print(f"[dim]{safe(report.summary())}[/dim]\n")
+
+    if not report.total:
+        console.print("[yellow]No Dockerfile found under this root.[/yellow]")
+        return
+
+    fila = report.worst_first()
+    mostrados = fila[:limit] if limit > 0 else fila
+    for entry in mostrados:
+        if not entry.readable:
+            console.print(f"  [red]![/red] {safe(entry.path)}  [dim]{safe(entry.error)}[/dim]")
+            continue
+
+        fixadas = (
+            f"{entry.pinned_bases}/{entry.total_bases} pinned"
+            if entry.total_bases
+            else "no readable FROM"
+        )
+        cor = "green" if entry.fully_pinned else "yellow"
+        console.print(
+            f"  {safe(entry.path)}\n"
+            f"    [{cor}]{fixadas}[/{cor}]  {_USER_LABEL[entry.nonroot]}  "
+            f"[dim]{entry.stages} stage(s)[/dim]"
+        )
+        for violation in entry.violations:
+            console.print(
+                f"    [red]x[/red] {violation.rule}  [dim]{safe(violation.message)}[/dim]"
+            )
+
+    if limit > 0 and len(fila) > limit:
+        console.print(f"\n[dim]... and {len(fila) - limit} more (use --limit 0 for all).[/dim]")
+
+    console.print()
+    if report.truncated:
+        console.print(
+            "[yellow]The scan hit the file or depth ceiling: this picture is incomplete.[/yellow]"
+        )
+    for path in report.unreadable_paths:
+        console.print(f"[yellow]Directory not walked: {safe(path)}[/yellow]")
+
+    if report.policy_applied:
+        console.print(
+            f"[bold]{report.with_violations} file(s) with violations, "
+            f"{report.total_violations} in total.[/bold]\n"
+            "[dim]Only rules decidable without a build were applied; the ones that "
+            "need a scan still hold in `dockerls build`.[/dim]"
+        )
+    else:
+        console.print(
+            "[dim]No policy declared: nothing was checked against any rule, and that "
+            "is not the same as being compliant.[/dim]"
+        )
+    console.print(f"[dim]{safe(report.caveat())}[/dim]")

dockerls/cli/commands/health.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from dockerls.cli.dependencies import build_host_guard
+from dockerls.exit_codes import EXIT_ERROR, EXIT_OK
+from dockerls.infrastructure.network.guarded_client import guarded_async_client
+from dockerls.integrations.exploitdb.client import EXPLOITDB_CSV_URL
+
+console = Console()
+
+# Exit codes so `health` is usable as a CI gate. They come from the shared
+# contract rather than from literals re-declared here: a probe that cannot
+# reach a dependency is "não sei" (EXIT_ERROR), not a policy verdict.
+EXIT_HEALTHY = EXIT_OK
+EXIT_DEGRADED = EXIT_ERROR
+
+# Each probe must be an endpoint the tool actually depends on *and* one that
+# answers 2xx when healthy. `https://hub.docker.com/v2/` was neither: it
+# returns 404 by design, so every single run reported the Hub as degraded.
+# The list tracks the real dependencies -- the image catalogues that feed
+# the scan pipeline and the threat-intel feeds that weight the score.
+ENDPOINTS = {
+    "Docker Hub API": "https://hub.docker.com/v2/repositories/library/node/",
+    "Chainguard (cgr.dev)": "https://cgr.dev/token?scope=repository:chainguard/node:pull&service=cgr.dev",
+    "Distroless (gcr.io)": "https://gcr.io/v2/distroless/base/tags/list",
+    "endoflife.date": "https://endoflife.date/api/python.json",
+    "CISA KEV": "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json",
+    "EPSS (FIRST)": "https://api.first.org/data/v1/epss?cve=CVE-2021-44228",
+    "Exploit-DB catalogue": EXPLOITDB_CSV_URL,
+}
+
+#: Endpoints grandes demais para baixar num probe de saúde. O CSV do
+#: Exploit-DB tem cerca de 10 MB, e `health` pergunta se a fonte responde --
+#: não quer o conteúdo dela. Um HEAD responde exatamente isso.
+_HEAD_ONLY = frozenset({EXPLOITDB_CSV_URL})
+
+
+def health() -> None:
+    """Check connectivity to external services."""
+    raise typer.Exit(asyncio.run(_health()))
+
+
+async def _health() -> int:
+    console.print("[bold]Service Health Check[/bold]\n")
+
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column("Service", style="bold")
+    table.add_column("Status")
+
+    degraded = False
+    # The URLs above are constants, but the redirects they may answer with
+    # are not, and this client follows them. Same policy, same reason as
+    # every other client in the tool.
+    async with guarded_async_client(
+        build_host_guard(), timeout=10, follow_redirects=True
+    ) as client:
+        for name, url in ENDPOINTS.items():
+            try:
+                resp = await client.head(url) if url in _HEAD_ONLY else await client.get(url)
+            except httpx.HTTPError as e:
+                # Unreachable is a failure, not a curiosity: DNS, TLS,
+                # proxy and timeout errors all land here.
+                table.add_row(name, f"[red]Unreachable: {type(e).__name__}[/red]")
+                degraded = True
+                continue
+
+            if resp.status_code < 400:
+                table.add_row(name, f"[green]OK ({resp.status_code})[/green]")
+            else:
+                table.add_row(name, f"[red]HTTP {resp.status_code}[/red]")
+                degraded = True
+
+    console.print(table)
+    if degraded:
+        console.print("\n[yellow]One or more services are degraded.[/yellow]")
+        return EXIT_DEGRADED
+    console.print("\n[green]All services reachable.[/green]")
+    return EXIT_HEALTHY

dockerls/cli/commands/login.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import asyncio
+
+import typer
+from rich.console import Console
+
+from dockerls.exit_codes import EXIT_ERROR
+from dockerls.integrations.dockerhub.client import DockerHubClient
+from dockerls.utils.auth import clear_credentials, store_credentials
+
+console = Console()
+
+
+def login(
+    username: str = typer.Option("", "--username", "-u", prompt="Docker Hub username"),
+    token: str = typer.Option("", "--token", "-t", prompt="Docker Hub token", hide_input=True),
+) -> None:
+    """Authenticate with Docker Hub. Credentials are stored in your system keyring."""
+    if not username or not token:
+        console.print("[red]Username and token are required.[/red]")
+        raise typer.Exit(EXIT_ERROR)
+
+    asyncio.run(_login(username, token))
+
+
+async def _login(username: str, token: str) -> None:
+    client = DockerHubClient(username=username, token=token)
+    if not await client.authenticate():
+        console.print("[red]Authentication failed. Check your username and token.[/red]")
+        raise typer.Exit(EXIT_ERROR)
+
+    if store_credentials(username, token):
+        console.print("[green]Authenticated. Credentials stored securely in keyring.[/green]")
+    else:
+        console.print(
+            "[yellow]Authenticated, but keyring is not available. Set "
+            "DOCKERHUB_USERNAME and DOCKERHUB_TOKEN environment variables "
+            "to persist credentials instead.[/yellow]"
+        )
+
+
+def logout() -> None:
+    """Remove stored Docker Hub credentials.
+
+    `login` could store credentials with no supported way to remove them,
+    which left `clear_credentials` implemented and unreachable.
+    """
+    if clear_credentials():
+        console.print("[green]Stored credentials removed.[/green]")
+        return
+    console.print("[yellow]No stored credentials to remove.[/yellow]")
+    raise typer.Exit(EXIT_ERROR)

dockerls/cli/commands/policy_cmd.py

@@ -0,0 +1,111 @@
+"""`dockerls policy` -- ler o regulamento sem precisar de um build para isso.
+
+Uma política que só se manifesta quando um build reprova é uma política que
+ninguém revisa. Este comando existe para as duas perguntas que aparecem antes
+disso: "o que este repositório exige?" e "este arquivo que acabei de escrever
+está válido?".
+
+A segunda importa mais do que parece. O carregador recusa chave desconhecida,
+tipo errado e severidade inexistente -- e recusa com razão, porque uma regra
+que não carrega deixa de exigir alguma coisa. Mas descobrir isso no meio de um
+build de dez minutos é caro; descobrir aqui custa um segundo.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from dockerls.cli.options import OutputFormat, parse_output_format
+from dockerls.cli.text import safe
+from dockerls.exit_codes import EXIT_ERROR, EXIT_OK
+from dockerls.infrastructure.config.policy_file import (
+    DEFAULT_POLICY_FILENAME,
+    PolicyFileError,
+    find_policy_file,
+    load_policy,
+)
+
+console = Console()
+
+#: O que cada regra exige, em uma linha, para a saída de tabela.
+_DESCRIPTIONS = {
+    "fail_on": "fails the build from this severity upwards",
+    "max_vulnerabilities": "ceiling on findings per severity",
+    "require_scan": "requires that a scanner has run",
+    "require_pinned_bases": "requires every FROM pinned by digest",
+    "require_nonroot": "requires the image to run without privilege",
+    "required_labels": "labels the image must carry",
+    "allowed_base_registries": "where bases may come from",
+    "require_provenance": "requires verified provenance",
+}
+
+
+def policy(
+    path: str = typer.Argument(
+        ".", help="Directory containing the policy file, or the file itself"
+    ),
+    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 and validate the policy declared in `.dockerls-policy.yaml`."""
+    if no_color:
+        console.no_color = True
+    fmt = parse_output_format(output_format)
+
+    target = Path(path)
+    if target.is_dir():
+        found = find_policy_file(target)
+        if found is None:
+            if fmt == OutputFormat.JSON:
+                console.print(json.dumps({"policy": None}, indent=2), soft_wrap=True)
+            else:
+                console.print(
+                    f"[yellow]No {DEFAULT_POLICY_FILENAME} in {safe(str(target))}.[/yellow]\n"
+                    "[dim]With no declared policy, only the gates the command line "
+                    "asks for apply -- and a rule that lives on the command line is a "
+                    "rule every pipeline rewrites by hand.[/dim]"
+                )
+            raise typer.Exit(EXIT_OK)
+        target = found
+
+    try:
+        declared = load_policy(target)
+    except PolicyFileError as e:
+        console.print(f"[red]Error:[/red] {safe(str(e))}")
+        raise typer.Exit(EXIT_ERROR) from e
+
+    if fmt == OutputFormat.JSON:
+        console.print(
+            json.dumps({"file": str(target), "policy": declared.to_dict()}, indent=2),
+            soft_wrap=True,
+        )
+        raise typer.Exit(EXIT_OK)
+
+    console.print(f"\n[bold]{safe(str(target))}[/bold]\n")
+    for key, value in declared.to_dict().items():
+        if not value:
+            continue
+        console.print(
+            f"  [cyan]{key}[/cyan]  [dim]{_DESCRIPTIONS.get(key, '')}[/dim]\n"
+            f"    {safe(_format(value))}"
+        )
+    console.print(
+        "\n[dim]Checked on every `dockerls build` in this context. Between the "
+        "threshold here and the one on the command line, the stricter wins: a file in "
+        "the repository cannot switch off a gate the pipeline asked for.[/dim]"
+    )
+    raise typer.Exit(EXIT_OK)
+
+
+def _format(value: object) -> str:
+    if isinstance(value, dict):
+        return ", ".join(f"{k}: {v}" for k, v in value.items())
+    if isinstance(value, list):
+        return ", ".join(str(v) for v in value)
+    return str(value)

dockerls/cli/commands/provenance_cmd.py

@@ -0,0 +1,162 @@
+"""`dockerls provenance` -- conferir um documento de procedência, e atestá-lo.
+
+O `build --provenance` arquiva um JSON dizendo o que entrou no build e o que
+saiu. Arquivar é metade do controle; a outra metade é alguém conferir antes de
+o artefato seguir adiante -- e era exatamente essa metade que faltava. Um
+documento que ninguém lê descreve com precisão uma imagem que ninguém sabe se
+deveria ter sido publicada.
+
+Este comando é essa leitura, e ele faz duas coisas que só fazem sentido juntas:
+
+* **Recalcula o veredito** em vez de acreditar no que está escrito. O campo
+  `"status": "VERIFIED"` de um arquivo JSON é editável por qualquer pessoa com
+  um editor de texto; a comparação entre os digests de antes e depois do build
+  não é. Ler o status gravado seria pedir ao documento que se auto-aprovasse.
+* **Recusa por código de saída** quando a procedência não fecha. É o que
+  transforma o documento em portão: num workflow, o passo de atestação só roda
+  se este comando passar, e uma imagem cuja entrada mudou durante o build nunca
+  chega a receber uma assinatura dizendo que veio dali.
+
+`--github-output` existe para o último elo: `actions/attest-build-provenance`
+precisa do nome e do digest do artefato, e tirá-los do documento (em vez de
+redigitá-los no YAML) garante que a atestação fala da mesma imagem que o scan
+mediu. Redigitar é onde a cadeia arrebenta sem ninguém perceber.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+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.value_objects.provenance import BuildProvenance, ProvenanceStatus
+from dockerls.exit_codes import EXIT_ERROR, EXIT_OK, EXIT_POLICY
+
+console = Console()
+
+_COLORS = {
+    ProvenanceStatus.VERIFIED: "green",
+    ProvenanceStatus.INCOMPLETE: "yellow",
+    ProvenanceStatus.INPUT_CHANGED: "red",
+}
+
+
+def provenance(
+    document: str = typer.Argument(..., help="JSON file written by `build --provenance`"),
+    output_format: str = typer.Option(
+        OutputFormat.TABLE.value, "--format", "-f", help="Output format: table or json"
+    ),
+    github_output: bool = typer.Option(
+        False,
+        "--github-output",
+        help=(
+            "Write subject-name and subject-digest to $GITHUB_OUTPUT for "
+            "actions/attest-build-provenance to consume"
+        ),
+    ),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable colored output"),
+) -> None:
+    """Check a provenance document and prepare the attestation."""
+    if no_color:
+        console.no_color = True
+    fmt = parse_output_format(output_format)
+
+    path = Path(document)
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except OSError as e:
+        console.print(f"[red]Error:[/red] could not read {safe(str(path))}: {safe(str(e))}")
+        raise typer.Exit(EXIT_ERROR) from e
+    except json.JSONDecodeError as e:
+        console.print(f"[red]Error:[/red] {safe(str(path))} is not valid JSON: {safe(str(e))}")
+        raise typer.Exit(EXIT_ERROR) from e
+
+    record = BuildProvenance.from_dict(raw)
+    subject_name, subject_digest = _subject(record)
+
+    if fmt == OutputFormat.JSON:
+        payload = record.to_dict()
+        payload["subject_name"] = subject_name
+        payload["subject_digest"] = subject_digest
+        payload["attestable"] = record.is_verified and bool(subject_digest)
+        console.print(json.dumps(payload, indent=2, ensure_ascii=False), soft_wrap=True)
+    else:
+        _render(record, subject_name, subject_digest)
+
+    if github_output:
+        _write_github_output(subject_name, subject_digest, record)
+
+    if not record.is_verified:
+        raise typer.Exit(EXIT_POLICY)
+    if not subject_digest:
+        # Sem digest não há o que atestar: uma assinatura precisa apontar para
+        # bytes específicos, e "a imagem com esta tag" não são bytes.
+        console.print(
+            "[yellow]The document carries no artifact digest: there is no subject to "
+            "attest.[/yellow]\n[dim]Publish the image (`build --push`) so the registry "
+            "returns the manifest digest.[/dim]"
+        )
+        raise typer.Exit(EXIT_POLICY)
+    raise typer.Exit(EXIT_OK)
+
+
+def _subject(record: BuildProvenance) -> tuple[str, str]:
+    """Nome e digest do que será atestado.
+
+    O digest do manifesto no registry vem primeiro: é o único identificador
+    que outra máquina consegue usar para puxar exatamente estes bytes. O id
+    local serve de segundo melhor, e é rotulado como tal na saída.
+    """
+    name = record.artifact.published_reference or record.tag
+    digest = record.artifact.repo_digest or record.artifact.image_id
+    return name, digest
+
+
+def _render(record: BuildProvenance, subject_name: str, subject_digest: str) -> None:
+    color = _COLORS.get(record.status, "white")
+    console.print(f"\n[bold]{safe(record.tag or '(no tag)')}[/bold]")
+    console.print(f"  [{color}]{record.status}[/{color}]  [dim]{safe(record.explain())}[/dim]\n")
+
+    console.print("  [bold]input[/bold]")
+    console.print(f"    Dockerfile  {safe(record.source.dockerfile or '(not measured)')}")
+    console.print(
+        f"    context     {safe(record.source.context or '(not measured)')}"
+        f"  [dim]({record.source.context_files} file(s))[/dim]"
+    )
+    if record.source.git_revision:
+        sujo = " [yellow](with uncommitted changes)[/yellow]" if record.source.git_dirty else ""
+        console.print(f"    revision    {safe(record.source.git_revision)}{sujo}")
+    for reference, digest in record.source.base_images.items():
+        console.print(f"    base        {safe(reference)} -> {safe(digest or '(moving tag)')}")
+
+    console.print("\n  [bold]output[/bold]")
+    console.print(f"    subject     {safe(subject_name or '(no name)')}")
+    origem = "registry manifest" if record.artifact.repo_digest else "local image id"
+    console.print(f"    digest      {safe(subject_digest or '(no digest)')}  [dim]({origem})[/dim]")
+    console.print(f"    scanner     {safe(record.artifact.scanner or '(not recorded)')}\n")
+
+
+def _write_github_output(name: str, digest: str, record: BuildProvenance) -> None:
+    """Publica o sujeito da atestação para o próximo passo do workflow.
+
+    Fora do Actions a variável não existe, e escrever num caminho arbitrário
+    seria efeito colateral fora de contexto: o comando avisa e segue.
+    """
+    destination = os.environ.get("GITHUB_OUTPUT", "")
+    if not destination:
+        console.print(
+            "[yellow]$GITHUB_OUTPUT is not set: --github-output only has an effect "
+            "inside a GitHub Actions workflow.[/yellow]"
+        )
+        return
+    linhas = f"subject-name={name}\nsubject-digest={digest}\nprovenance-status={record.status}\n"
+    try:
+        with Path(destination).open("a", encoding="utf-8") as handle:
+            handle.write(linhas)
+    except OSError as e:
+        console.print(f"[yellow]Could not write to $GITHUB_OUTPUT: {safe(str(e))}[/yellow]")