dockerls 1.0.0__py3-none-any.whl

dockerls/cli/commands/registry_audit_cmd.py

@@ -0,0 +1,103 @@
+"""`dockerls registry-audit` -- o que o registry conta sobre uma imagem.
+
+Auditar a configuração de um registry -- retenção, IAM, content trust -- exige
+credencial de nuvem e uma API diferente para cada provedor. Este comando não
+faz isso, e a saída diz que não faz: ele usa o protocolo OCI e mais nada. A
+troca é deliberada. Um relatório que precisa de acesso administrativo para
+existir é um relatório que ninguém roda, e o que dá para medir sem credencial
+é menos do que parece e mais do que se costuma olhar.
+
+Cada achado é tri-estado. `UNKNOWN` não é enfeite de formato: sem ele, "o
+registry não respondeu sobre a assinatura" viraria "não há assinatura", e as
+duas frases levam a decisões opostas.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import TYPE_CHECKING
+
+import typer
+from rich.console import Console
+
+from dockerls.cli.dependencies import build_host_guard, build_registry_credentials
+from dockerls.cli.options import OutputFormat, parse_output_format
+from dockerls.cli.text import safe
+from dockerls.exit_codes import EXIT_ERROR, EXIT_OK, EXIT_POLICY
+
+if TYPE_CHECKING:
+    from dockerls.domain.value_objects.registry_audit import RegistryAudit
+
+console = Console()
+
+
+def registry_audit(
+    reference: str = typer.Argument(..., help="Published image (`ghcr.io/org/app:1.0`)"),
+    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:
+    """Establish, through the registry, what is known about a published image."""
+    if no_color:
+        console.no_color = True
+    fmt = parse_output_format(output_format)
+    asyncio.run(_audit(reference, output_format=fmt))
+
+
+async def _audit(reference: str, *, output_format: OutputFormat) -> None:
+    from dockerls.application.services.tag_history_store import TagHistoryStore
+    from dockerls.application.use_cases.registry_audit import RegistryAuditUseCase
+    from dockerls.cli.dependencies import build_cache
+    from dockerls.integrations.registry.inspector import RegistryInspector
+
+    inspector = RegistryInspector(
+        guard=build_host_guard(), credentials=build_registry_credentials()
+    )
+    try:
+        history = TagHistoryStore(build_cache())
+    except Exception:  # pragma: no cover - abrir o cache é o caminho instável
+        history = TagHistoryStore(None)
+
+    try:
+        audit = await RegistryAuditUseCase(inspector, history).execute(reference)
+    finally:
+        await inspector.close()
+
+    if output_format == OutputFormat.JSON:
+        console.print(json.dumps(audit.to_dict(), indent=2, ensure_ascii=False), soft_wrap=True)
+    else:
+        _render(audit)
+
+    if not audit.findings:
+        raise typer.Exit(EXIT_ERROR)
+    raise typer.Exit(EXIT_POLICY if audit.alerts else EXIT_OK)
+
+
+def _render(audit: RegistryAudit) -> None:
+    console.print(f"\n[bold]{safe(audit.reference)}[/bold]")
+    if audit.digest:
+        console.print(f"[dim]{safe(audit.digest)}[/dim]")
+    console.print()
+
+    if not audit.findings:
+        console.print("[red]Invalid reference: nothing could be established.[/red]")
+        return
+
+    for finding in audit.findings:
+        if finding.is_unmeasured:
+            marca, cor = "?", "yellow"
+        elif finding.is_alert:
+            marca, cor = "x", "red"
+        elif finding.is_informational:
+            # Fato relatado sem juízo: se ser público é problema depende de
+            # para que a imagem existe, e isso a ferramenta não sabe.
+            marca, cor = "i", "cyan"
+        else:
+            marca, cor = "v", "green"
+        console.print(f"  [{cor}]{marca}[/{cor}] [bold]{finding.check}[/bold]")
+        console.print(f"      [dim]{safe(finding.explain())}[/dim]")
+
+    console.print(f"\n[bold]{safe(audit.summary())}[/bold]")
+    console.print(f"[dim]{safe(audit.caveat())}[/dim]\n")

dockerls/cli/commands/sbom.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import tempfile
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from dockerls.cli.dependencies import build_host_guard
+from dockerls.cli.text import safe
+from dockerls.exit_codes import EXIT_ERROR
+from dockerls.integrations.trivy.scanner import TrivyScanner
+
+console = Console()
+
+_FORMAT_ALIASES = {"cyclonedx": "cyclonedx", "spdx": "spdx-json", "spdx-json": "spdx-json"}
+
+
+def sbom(
+    image: str = typer.Argument(help="Full image reference (e.g., node:22-alpine)"),
+    output_format: str = typer.Option("cyclonedx", "--format", "-f", help="cyclonedx or spdx"),
+    output: str = typer.Option("", "--output", "-o", help="Output file path (default: stdout)"),
+    attest: bool = typer.Option(
+        False,
+        "--attest",
+        help="Publish the SBOM to the registry as a signed cosign attestation. Requires "
+        "cosign and a reference by digest",
+    ),
+) -> None:
+    """Generate a Software Bill of Materials (SBOM) for an image via Trivy.
+
+    `--attest` publishes it: the SBOM is signed with cosign and attached to
+    the image manifest, which is what `dockerls registry-audit` looks for
+    when it asks whether an attestation exists. Without it the SBOM is a
+    file on your disk -- useful, and invisible to anyone pulling the image.
+
+    Attestation is by **digest** only. A tag can move, and an attestation
+    that outlives the move would go on describing an image it never saw.
+    """
+    fmt = _FORMAT_ALIASES.get(output_format.lower())
+    if fmt is None:
+        console.print(
+            f"[red]Unsupported SBOM format: {output_format}. Use cyclonedx or spdx.[/red]"
+        )
+        raise typer.Exit(EXIT_ERROR)
+    if attest and "@sha256:" not in image:
+        # Recusado aqui, antes de gerar: descobrir isso depois de escanear
+        # a imagem inteira desperdiça o trabalho, e a correção é uma linha
+        # de comando diferente e não uma flag a mais.
+        console.print(
+            "[red]Error:[/red] --attest needs a digest reference "
+            "(name@sha256:...), not a tag.\n"
+            "[dim]A tag can move, and the attestation would go on describing an image "
+            "it never saw. `docker inspect --format='{{index .RepoDigests 0}}' "
+            "<image>` gives you the digest.[/dim]"
+        )
+        raise typer.Exit(EXIT_ERROR)
+
+    try:
+        asyncio.run(_sbom(image, fmt, output, attest=attest))
+    except ValueError as e:
+        # A malformed image reference is rejected by `sanitize_image_name`
+        # inside the scanner; surfacing it as a message keeps `sbom` in line
+        # with every other command.
+        console.print(f"[red]Invalid image reference:[/red] {e}")
+        raise typer.Exit(EXIT_ERROR) from e
+
+
+async def _sbom(image: str, fmt: str, output: str, *, attest: bool = False) -> None:
+    scanner = TrivyScanner(guard=build_host_guard())
+    if not await scanner.is_available():
+        console.print("[red]Trivy is required for SBOM generation. Run `dockerls doctor`.[/red]")
+        raise typer.Exit(EXIT_ERROR)
+
+    content = await scanner.generate_sbom(image, fmt=fmt)
+    if content is None:
+        console.print(f"[red]Failed to generate SBOM for {image}[/red]")
+        raise typer.Exit(EXIT_ERROR)
+
+    if output:
+        path = Path(output)
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+        except OSError as e:
+            # An unwritable destination is user error, not a traceback.
+            console.print(f"[red]Could not write {path}:[/red] {e}")
+            raise typer.Exit(EXIT_ERROR) from e
+        console.print(f"[green]SBOM written to {output}[/green]")
+    elif not attest:
+        console.print(content, soft_wrap=True)
+
+    if attest:
+        await _attest(image, content, fmt)
+
+
+#: O tipo de predicado que o cosign espera para cada formato de SBOM. Sem
+#: isto, o documento é anexado como um predicado genérico e quem consome não
+#: sabe que é um SBOM -- o que é quase o mesmo que não ter anexado.
+_PREDICATE_TYPES = {"cyclonedx": "cyclonedx", "spdx-json": "spdxjson"}
+
+
+async def _attest(image: str, content: str, fmt: str) -> None:
+    """Publica o SBOM como atestação assinada, ou diz por que não publicou.
+
+    O documento vai para um arquivo temporário e sai dele em qualquer
+    caminho: é o inventário completo da imagem, e deixá-lo para trás em
+    `/tmp` seria vazar por descuido o que o comando existe para publicar de
+    forma controlada.
+    """
+    from dockerls.integrations.signing.cosign import CosignClient, SignatureStatus
+
+    with tempfile.NamedTemporaryFile("w", suffix=".json", encoding="utf-8", delete=False) as handle:
+        handle.write(content)
+        predicate = Path(handle.name)
+
+    try:
+        result = await CosignClient().attest(
+            image, predicate=str(predicate), predicate_type=_PREDICATE_TYPES[fmt]
+        )
+    finally:
+        with contextlib.suppress(OSError):
+            predicate.unlink()
+
+    if result.status is SignatureStatus.SIGNED:
+        console.print(f"[green]SBOM attested to {safe(image)}[/green]")
+        console.print(
+            "[dim]`dockerls registry-audit` will now find it, and so will anyone "
+            "running `cosign verify-attestation`.[/dim]"
+        )
+        return
+
+    if result.status is SignatureStatus.SIGNER_MISSING:
+        # Ausência de ferramenta, não falha da imagem. O SBOM foi gerado e
+        # continua válido; o que não aconteceu foi a publicação.
+        console.print(
+            "[yellow]The SBOM was generated but not attested:[/yellow] cosign is not installed."
+        )
+        raise typer.Exit(EXIT_ERROR)
+
+    console.print(f"[red]Attestation failed:[/red] {safe(result.detail or result.explain())}")
+    raise typer.Exit(EXIT_ERROR)

dockerls/cli/commands/search.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import asyncio
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from dockerls.application.services.source_registry import UnknownSourceError
+from dockerls.cli.dependencies import build_search_use_case
+from dockerls.cli.image_names import reject_tagged_reference
+from dockerls.cli.validators import check_limit
+from dockerls.exit_codes import EXIT_ERROR
+
+console = Console()
+
+
+def search(
+    image: str = typer.Argument(
+        help=(
+            "Docker image name only, without a tag (e.g. 'node', not 'node:18'). "
+            "Use 'analyze' or 'advisor' for a specific tag."
+        )
+    ),
+    limit: int = typer.Option(100, "--limit", "-l", help="Maximum tags to retrieve"),
+    source: list[str] = typer.Option(
+        [],
+        "--source",
+        "-s",
+        help=(
+            "Image source to search; repeatable. "
+            "One of: dockerhub, chainguard, distroless, dhi, private (if configured), all"
+        ),
+    ),
+    all_sources: bool = typer.Option(
+        False, "--all-sources", help="Search every configured source, including opt-in ones"
+    ),
+) -> None:
+    """Search for available tags of an image, on Docker Hub or any configured source."""
+    limit = check_limit(limit)
+    error = reject_tagged_reference(image, "search")
+    if error:
+        console.print(f"[red]{error}[/red]")
+        raise typer.Exit(EXIT_ERROR)
+    try:
+        asyncio.run(_search(image, limit, list(source) or None, all_sources))
+    except UnknownSourceError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(EXIT_ERROR) from e
+    except ValueError as e:
+        # `sanitize_image_name` rejects a malformed reference inside the
+        # client; surfacing it as a message keeps `search` in line with
+        # every other command instead of answering with a stack trace.
+        console.print(f"[red]Invalid image reference:[/red] {e}")
+        raise typer.Exit(EXIT_ERROR) from e
+
+
+async def _search(
+    image: str,
+    limit: int,
+    sources: list[str] | None = None,
+    all_sources: bool = False,
+) -> None:
+    use_case = await build_search_use_case(sources, all_sources=all_sources)
+    tags = await use_case.execute(image, limit=limit)
+
+    if not tags:
+        console.print(f"[red]No tags found for '{image}'[/red]")
+        raise typer.Exit(EXIT_ERROR)
+
+    table = Table(title=f"Tags for {image}")
+    table.add_column("Tag", style="cyan")
+    table.add_column("Source", style="magenta")
+    table.add_column("Size (MB)", justify="right")
+    table.add_column("Architecture")
+    table.add_column("Last Updated")
+    table.add_column("Official", justify="center")
+
+    for tag in tags:
+        size_mb = f"{tag.size_bytes / (1024 * 1024):.1f}" if tag.size_bytes else "-"
+        updated = tag.last_updated.strftime("%Y-%m-%d") if tag.last_updated else "-"
+        official = "Yes" if tag.is_official else "No"
+        table.add_row(tag.tag, tag.source, size_mb, tag.architecture, updated, official)
+
+    console.print(table)
+    console.print(f"\n[dim]Total: {len(tags)} tags[/dim]")

dockerls/cli/commands/verify.py

@@ -0,0 +1,115 @@
+"""`dockerls verify` -- quem publicou estes bytes?
+
+O `scan` diz o que há dentro de uma imagem e o `provenance` diz de onde ela
+veio. Nenhum dos dois impede alguém com acesso de escrita ao registry de
+sobrescrever a tag com outra coisa: os dois falam sobre o artefato que
+mediram, e a tag deixou de apontar para ele. A assinatura é o elo que fecha
+isso.
+
+O comando tem uma regra acima de todas: **`cosign` ausente nunca vira "não
+assinado"**. Confundir os dois acusaria alguém de não assinar por causa de uma
+ferramenta que faltava na máquina -- e, na direção oposta, uma verificação que
+falha em silêncio produz confiança sem base, que é pior do que desconfiança.
+
+Verificar sem restringir identidade e emissor responde "alguém assinou", e não
+"quem você espera assinou". O comando aceita rodar assim porque é útil num
+diagnóstico rápido, e **diz na saída** que foi isso que aconteceu.
+"""
+
+from __future__ import annotations
+
+import asyncio
+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.exit_codes import EXIT_ERROR, EXIT_OK, EXIT_POLICY
+from dockerls.integrations.signing.cosign import CosignClient, SignatureStatus
+
+console = Console()
+
+_COLORS = {
+    SignatureStatus.VERIFIED: "green",
+    SignatureStatus.SIGNED: "green",
+    SignatureStatus.UNSIGNED: "red",
+    # Vermelho e em negrito: é o desfecho mais grave que este comando tem.
+    SignatureStatus.VERIFICATION_FAILED: "bold red",
+    SignatureStatus.SIGNER_MISSING: "yellow",
+    SignatureStatus.FAILED: "yellow",
+}
+
+
+def verify(
+    reference: str = typer.Argument(..., help="Image to verify (ideally by digest)"),
+    identity: str = typer.Option(
+        "",
+        "--identity",
+        help="Regex for the identity that must have signed (e.g. 'https://github.com/org/.*')",
+    ),
+    issuer: str = typer.Option(
+        "",
+        "--issuer",
+        help="Expected OIDC issuer (e.g. https://token.actions.githubusercontent.com)",
+    ),
+    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:
+    """Check an image signature with cosign."""
+    if no_color:
+        console.no_color = True
+    fmt = parse_output_format(output_format)
+
+    result = asyncio.run(
+        CosignClient().verify(
+            reference,
+            certificate_identity_regexp=identity,
+            certificate_oidc_issuer=issuer,
+        )
+    )
+
+    if fmt == OutputFormat.JSON:
+        console.print(json.dumps(result.to_dict(), indent=2, ensure_ascii=False), soft_wrap=True)
+    else:
+        color = _COLORS.get(result.status, "white")
+        console.print(f"\n[bold]{safe(result.reference)}[/bold]")
+        console.print(f"  [{color}]{result.status}[/{color}]  [dim]{safe(result.explain())}[/dim]")
+        for who in result.identities:
+            console.print(f"    [dim]signed by {safe(who)}[/dim]")
+        if result.detail and result.status is SignatureStatus.VERIFIED:
+            console.print(f"  [yellow]![/yellow] [dim]{safe(result.detail)}[/dim]")
+        if result.status is SignatureStatus.VERIFICATION_FAILED:
+            # O motivo que o cosign deu é a parte acionável, e antes só
+            # aparecia para o caso VERIFIED. Uma verificação que falha sem
+            # dizer por quê é indistinguível de uma que não rodou.
+            if result.detail:
+                console.print(f"  [red]![/red] [dim]{safe(result.detail)}[/dim]")
+            console.print(
+                "  [dim]Do not treat this as an unsigned image: signing material is "
+                "published for this reference and it did not check out.[/dim]"
+            )
+        if "@sha256:" not in reference:
+            console.print(
+                "\n[dim]This reference is not a digest: the signature checked is the "
+                "one for what the tag points at now, and the tag can move.[/dim]"
+            )
+        console.print()
+
+    # Três saídas distintas de propósito. Sem isso, um pipeline não conseguiria
+    # diferenciar "esta imagem não está assinada" de "não deu para conferir",
+    # e trataria as duas do mesmo jeito -- que é exatamente o erro.
+    if result.trustworthy:
+        raise typer.Exit(EXIT_OK)
+    if result.status.is_conclusive:
+        # O cosign rodou e respondeu, e a resposta reprova: ou não há
+        # assinatura, ou há e ela não confere. As duas são veredito sobre a
+        # imagem -- e por isso as duas saem por EXIT_POLICY, e não pelo
+        # EXIT_ERROR reservado a "não deu para conferir".
+        raise typer.Exit(EXIT_POLICY)
+    # O cosign não rodou, ou rodou e falhou. Isso é falha do medidor, e sai
+    # como erro técnico -- nunca como "não assinado".
+    raise typer.Exit(EXIT_ERROR)

dockerls/cli/commands/version.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from rich.console import Console
+
+from dockerls import __version__
+
+console = Console()
+
+
+def version() -> None:
+    """Show DockerLs version."""
+    console.print(f"DockerLs v{__version__}")

dockerls/cli/commands/vex_cmd.py

@@ -0,0 +1,117 @@
+"""Emite as isenções deste repositório como um documento OpenVEX.
+
+O `.dockerls-ignore.yaml` já é um VEX em tudo menos no formato: tem o CVE,
+tem a justificativa e tem o prazo. O que faltava era escrevê-lo num formato
+que o resto do mundo lê -- Trivy e Grype consomem OpenVEX nativamente --,
+para que uma exceção decidida uma vez valha no pipeline inteiro em vez de
+só dentro desta ferramenta.
+
+O que este comando **não** faz é transformar risco aceito em alegação
+técnica. Ver `domain/value_objects/vex.py`: `not_affected` só sai quando a
+regra declara uma das cinco justificativas do padrão.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from dockerls.cli.text import safe
+from dockerls.domain.value_objects.image_reference import split_repository_and_tag
+from dockerls.domain.value_objects.vex import ExemptionInput, build_document
+from dockerls.exit_codes import EXIT_ERROR, EXIT_OK
+from dockerls.utils.ignore_file import DEFAULT_IGNORE_FILENAME, load_ignore_rules
+
+console = Console()
+diagnostics = Console(stderr=True)
+
+
+def vex(
+    image: str = typer.Argument(
+        help="Image the statements are about (e.g. ghcr.io/org/app:1.0, or a digest)"
+    ),
+    ignore_file: str | None = typer.Option(
+        None,
+        "--ignore-file",
+        help=f"Exemptions to translate (default: {DEFAULT_IGNORE_FILENAME} in this directory)",
+    ),
+    author: str = typer.Option(
+        "",
+        "--author",
+        help="Who is making these statements. Required: a VEX with no author "
+        "names nobody, and nobody is not accountable",
+    ),
+    output: str | None = typer.Option(
+        None, "--output", "-o", help="Write to a file instead of stdout"
+    ),
+) -> None:
+    """Emit this repository's exemptions as an OpenVEX document."""
+    if not author.strip():
+        console.print(
+            "[red]Error:[/red] --author is required.\n"
+            "[dim]A VEX statement is an assertion someone makes. Without an author it "
+            "asserts nothing anyone can be held to, and consumers have no way to decide "
+            "whether to trust it.[/dim]"
+        )
+        raise typer.Exit(EXIT_ERROR)
+
+    path = Path(ignore_file) if ignore_file else Path.cwd() / DEFAULT_IGNORE_FILENAME
+    if ignore_file and not path.exists():
+        # Um caminho explícito que não existe é erro de configuração. Cair
+        # no silêncio de "nenhuma regra" produziria um documento vazio que
+        # parece uma resposta.
+        console.print(f"[red]Error:[/red] {safe(str(path))} does not exist")
+        raise typer.Exit(EXIT_ERROR)
+
+    rules = load_ignore_rules(path)
+    document = build_document(
+        [
+            ExemptionInput(
+                cve=rule.cve,
+                justification=rule.justification,
+                expires=rule.expires,
+                vex_justification=rule.vex_justification,
+            )
+            for rule in rules
+        ],
+        products=[_product_id(image)],
+        author=author.strip(),
+    )
+
+    rendered = document.to_json()
+    if output:
+        Path(output).write_text(rendered + "\n", encoding="utf-8")
+        diagnostics.print(f"[green]Wrote {len(rules)} statement(s) to {safe(output)}[/green]")
+    else:
+        console.print(rendered, soft_wrap=True)
+
+    if not rules:
+        # Documento vazio é uma resposta válida -- "nada foi isentado" --,
+        # mas quem rodou o comando quase sempre esperava statements, e o
+        # silêncio faria parecer que o arquivo foi lido e ignorado.
+        diagnostics.print(
+            f"[yellow]No active exemptions in {safe(str(path))}: the document is empty.[/yellow]\n"
+            "[dim]Expired rules are dropped on read, so an exemption that lapsed no longer "
+            "appears here -- which is the point of the expiry date.[/dim]"
+        )
+    raise typer.Exit(EXIT_OK)
+
+
+def _product_id(image: str) -> str:
+    """A referência como um purl OCI, que é o que o padrão espera.
+
+    Um digest sobrevive intacto: ele já aponta para bytes específicos, que
+    é exatamente o que uma afirmação VEX deveria cobrir. Uma tag entra como
+    versão porque é o que existe -- e é o consumidor que decide o quanto
+    confia numa afirmação sobre um ponteiro móvel.
+    """
+    reference = image.strip()
+    if "@" in reference:
+        name, _, digest = reference.partition("@")
+        return f"pkg:oci/{name.rsplit('/', 1)[-1]}@{digest}?repository_url={name}"
+    repository, tag = split_repository_and_tag(reference)
+    short = repository.rsplit("/", 1)[-1]
+    version = f"?tag={tag}" if tag else ""
+    return f"pkg:oci/{short}{version}&repository_url={repository}" if tag else f"pkg:oci/{short}"