vexpath 0.1.0__py3-none-any.whl

vexpath/__init__.py

@@ -0,0 +1,12 @@
+"""The ``vexpath`` command-line tool."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:  # pragma: no cover - depends on install mode
+    __version__ = version("vexpath")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

vexpath/commands/__init__.py

@@ -0,0 +1,3 @@
+"""Command implementations, one module per command group."""
+
+from __future__ import annotations

vexpath/commands/advisory.py

@@ -0,0 +1,305 @@
+"""The ``vexpath advisory`` command group: sync a corpus and inspect records."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from vexpath.output import OutputFormat, emit, emit_json, fail, note
+from vexpath.sources import SNAPSHOT_ENV
+from vexpath_core.advisory.coverage import FixReferenceTier, measure
+from vexpath_core.advisory.sync import DEFAULT_ECOSYSTEMS, AdvisorySyncError
+from vexpath_core.advisory.sync import sync as run_sync
+from vexpath_core.enums import canonical_ecosystem
+from vexpath_core.snapshot import SnapshotIntegrityError, read_snapshot
+
+app = typer.Typer(help="Download and inspect the advisory corpus.", no_args_is_help=True)
+
+
+@app.command("sync")
+def sync(
+    directory: Annotated[
+        Path,
+        typer.Argument(help="Where to write the snapshot."),
+    ] = Path("advisories"),
+    ecosystems: Annotated[
+        str,
+        typer.Option(
+            "--ecosystem",
+            "-e",
+            help="Comma-separated OSV ecosystem names to download.",
+        ),
+    ] = ",".join(DEFAULT_ECOSYSTEMS),
+) -> None:
+    """Download advisories and write a local snapshot.
+
+    A snapshot makes scans reproducible and lets them run with no network
+    access at all, which is what an air-gapped environment needs and what makes
+    a verdict auditable months later.
+    """
+    names = [canonical_ecosystem(name) for name in ecosystems.split(",") if name.strip()]
+    if not names:
+        fail("no ecosystems given; pass --ecosystem PyPI for example")
+
+    note(f"downloading {', '.join(names)} from OSV; this takes a few minutes")
+    try:
+        report = run_sync(directory, ecosystems=names)
+    except AdvisorySyncError as exc:
+        fail(str(exc))
+
+    lines = [
+        f"Wrote snapshot {report.snapshot.id} to {directory}",
+        f"  advisories {report.advisories}",
+    ]
+    for ecosystem, share in sorted(report.symbol_coverage.items()):
+        counts = report.snapshot.counts.get(ecosystem, {})
+        lines.append(
+            f"  {ecosystem:<10} {counts.get('advisories', 0):>6} advisories, "
+            f"{counts.get('with_symbols', 0):>6} with vulnerable symbols ({share:.1%})"
+        )
+    if report.skipped:
+        lines.append(f"  skipped    {len(report.skipped)} malformed record(s)")
+    lines.append("")
+    lines.append(f"Set {SNAPSHOT_ENV}={directory} so scans use it by default.")
+    emit("\n".join(lines) + "\n")
+
+
+@app.command("show")
+def show(
+    advisory_id: Annotated[
+        str, typer.Argument(help="Advisory identifier, such as CVE-2024-35195.")
+    ],
+    snapshot: Annotated[
+        Path | None,
+        typer.Option(
+            "--snapshot",
+            exists=True,
+            file_okay=False,
+            help=f"Snapshot directory to read. Defaults to ${SNAPSHOT_ENV}.",
+        ),
+    ] = None,
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TABLE,
+) -> None:
+    """Show one advisory: affected ranges, severity and vulnerable symbols.
+
+    The vulnerable symbols are what reachability analysis searches for, so this
+    is the command for understanding why a finding was or was not reachable.
+    """
+    directory = snapshot or _snapshot_from_environment()
+    if directory is None:
+        fail(
+            f"no snapshot given. Pass --snapshot, or set ${SNAPSHOT_ENV}, "
+            "or download one with 'vexpath advisory sync'."
+        )
+
+    try:
+        _, advisories = read_snapshot(directory)
+    except FileNotFoundError as exc:
+        fail(str(exc))
+    except SnapshotIntegrityError as exc:
+        fail(f"advisory snapshot is not trustworthy: {exc}")
+
+    wanted = advisory_id.strip().upper()
+    found = next(
+        (
+            advisory
+            for advisory in advisories
+            if any(identifier.upper() == wanted for identifier in advisory.all_ids)
+        ),
+        None,
+    )
+    if found is None:
+        fail(f"{advisory_id} is not in the snapshot at {directory}")
+
+    if output_format is OutputFormat.JSON:
+        emit_json(found.model_dump(mode="json"))
+        return
+
+    lines = [f"{found.id}  {found.severity.value}"]
+    if found.aliases:
+        lines.append(f"  also known as   {', '.join(found.aliases)}")
+    if found.summary:
+        lines.append(f"  summary         {found.summary}")
+    if found.cvss_v3:
+        lines.append(f"  CVSS v3         {found.cvss_v3.base_score}  {found.cvss_v3.vector}")
+    if found.cvss_v4:
+        lines.append(f"  CVSS v4         {found.cvss_v4.vector}")
+    if found.epss_score is not None:
+        lines.append(f"  EPSS            {found.epss_score:.5f}")
+    if found.kev:
+        lines.append("  CISA KEV        yes, known to be exploited")
+    if found.cwe_ids:
+        lines.append(f"  weaknesses      {', '.join(found.cwe_ids)}")
+    if found.repo_url:
+        lines.append(f"  repository      {found.repo_url}")
+    if found.is_withdrawn:
+        lines.append("  withdrawn       yes, this advisory produces no findings")
+
+    lines.append("")
+    lines.append("Affected packages")
+    for package in found.affected:
+        lines.append(f"  {package.ecosystem} {package.name}")
+        for affected_range in package.ranges:
+            events = " ".join(
+                f"{field}={value}"
+                for event in affected_range.events
+                for field, value in event.model_dump(exclude_none=True).items()
+            )
+            lines.append(f"    {affected_range.type.value}: {events}")
+        if package.versions:
+            shown = ", ".join(package.versions[:8])
+            more = "" if len(package.versions) <= 8 else f" and {len(package.versions) - 8} more"
+            lines.append(f"    explicit versions: {shown}{more}")
+        if package.fixed_versions:
+            lines.append(f"    fixed in: {', '.join(package.fixed_versions)}")
+
+    lines.append("")
+    if found.symbols:
+        lines.append(f"Vulnerable symbols ({found.symbols_status.value})")
+        for symbol in found.symbols:
+            lines.append(
+                f"  {symbol.symbol}  [{symbol.kind.value}, {symbol.source.value}, "
+                f"{symbol.confidence.value} confidence]"
+            )
+    else:
+        lines.append(
+            f"No vulnerable symbols ({found.symbols_status.value}), so reachability "
+            "cannot be determined for this advisory and findings stay under "
+            "investigation."
+        )
+
+    emit("\n".join(lines) + "\n")
+
+
+@app.command("coverage")
+def coverage(
+    snapshot: Annotated[
+        Path | None,
+        typer.Option(
+            "--snapshot",
+            exists=True,
+            file_okay=False,
+            help=f"Snapshot directory to read. Defaults to ${SNAPSHOT_ENV}.",
+        ),
+    ] = None,
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TABLE,
+) -> None:
+    """Report what share of advisories reachability analysis could ever decide.
+
+    Two different numbers, and conflating them would mislead:
+
+    *Symbols* is the share of advisories that already name their vulnerable
+    functions. Only Go advisories do. For PyPI this is zero and will stay zero,
+    because OSV carries no such field for it.
+
+    *Fix* is the share whose fix commit can be recovered, which is what symbol
+    extraction needs. This is the ceiling on what reachability can ever speak
+    to, and the number that decides whether the call-graph engine is worth
+    building.
+    """
+    directory = snapshot or _snapshot_from_environment()
+    if directory is None:
+        fail(f"no snapshot given. Pass --snapshot or set ${SNAPSHOT_ENV}.")
+
+    try:
+        metadata, advisories = read_snapshot(directory)
+    except FileNotFoundError as exc:
+        fail(str(exc))
+    except SnapshotIntegrityError as exc:
+        fail(f"advisory snapshot is not trustworthy: {exc}")
+
+    report = measure(advisories, snapshot_id=metadata.id)
+
+    if output_format is OutputFormat.JSON:
+        emit_json(
+            {
+                "snapshot": report.snapshot_id,
+                "advisories": report.advisories,
+                "withdrawn": report.withdrawn,
+                "malicious": report.malicious,
+                "ecosystems": [
+                    {
+                        "ecosystem": entry.ecosystem,
+                        "advisories": entry.advisories,
+                        "withdrawn": entry.withdrawn,
+                        "malicious": entry.malicious,
+                        "total_records": entry.total_records,
+                        "with_symbols": entry.with_symbols,
+                        "symbol_coverage": round(entry.symbol_coverage, 4),
+                        "fix_reference_coverage": round(entry.fix_reference_coverage, 4),
+                        "high_confidence_coverage": round(entry.high_confidence_coverage, 4),
+                        "tiers": {
+                            tier.value: entry.tiers.get(tier, 0) for tier in FixReferenceTier
+                        },
+                    }
+                    for entry in report.ecosystems
+                ],
+            }
+        )
+        return
+
+    lines = [
+        f"Snapshot {report.snapshot_id}",
+        "",
+        f"{report.advisories} advisories that reachability analysis could apply to.",
+        f"Excluded: {report.malicious} malicious-package records, {report.withdrawn} withdrawn.",
+        "",
+        f"{'ECOSYSTEM':<12} {'ANALYSABLE':>11} {'MALICIOUS':>10} {'SYMBOLS':>9} "
+        f"{'FIX':>7} {'EXACT':>7}",
+        "-" * 62,
+    ]
+    for entry in report.ecosystems:
+        lines.append(
+            f"{entry.ecosystem:<12} {entry.advisories:>11} {entry.malicious:>10} "
+            f"{entry.symbol_coverage:>8.1%} "
+            f"{entry.fix_reference_coverage:>6.1%} "
+            f"{entry.high_confidence_coverage:>6.1%}"
+        )
+
+    lines.append("")
+    lines.append("How a fix commit would be recovered")
+    lines.append("")
+    header = f"{'ECOSYSTEM':<12}" + "".join(f"{tier.value:>15}" for tier in FixReferenceTier)
+    lines.append(header)
+    lines.append("-" * len(header))
+    for entry in report.ecosystems:
+        row = f"{entry.ecosystem:<12}"
+        for tier in FixReferenceTier:
+            count = entry.tiers.get(tier, 0)
+            share = count / entry.advisories if entry.advisories else 0.0
+            row += f"{count:>8} {share:>5.0%} "
+        lines.append(row.rstrip())
+
+    lines.append("")
+    lines.append(
+        "ANALYSABLE excludes MALICIOUS records: malware has no fix to diff, and "
+        "installing it runs it, so its presence alone is the finding."
+    )
+    lines.append(
+        "SYMBOLS: advisories that already name their vulnerable functions. Only Go "
+        "publishes these, and only in its own export."
+    )
+    lines.append(
+        "FIX: advisories whose fix commit can be recovered, which is the ceiling "
+        "on what reachability can decide."
+    )
+    lines.append("EXACT: of those, the ones resolving to a precise commit rather than a tag diff.")
+    emit("\n".join(lines) + "\n")
+
+
+def _snapshot_from_environment() -> Path | None:
+    raw = os.environ.get(SNAPSHOT_ENV, "").strip()
+    if not raw:
+        return None
+    candidate = Path(raw)
+    return candidate if candidate.is_dir() else None
+
+
+__all__ = ["app"]

vexpath/commands/attest.py

@@ -0,0 +1,348 @@
+"""The ``vexpath attest`` command group: sign a document, and check a signature.
+
+A VEX document that says "this does not apply to us" is worth something only
+if a consumer can establish who said it. These commands are the two halves of
+that: producing a signature somebody else can check, and checking one.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from vexpath.output import OutputFormat, emit, emit_json, fail, fail_config, note, warn
+from vexpath_core import attest
+from vexpath_core.vex import OPENVEX_PREDICATE_TYPE
+
+app = typer.Typer(
+    help="Sign documents so their conclusions can be attributed, and verify signatures.",
+    no_args_is_help=True,
+)
+
+#: What each document type's predicate is called. A verifier matches on this,
+#: so guessing wrongly produces an attestation nothing will accept.
+PREDICATE_TYPES = {
+    "vex": OPENVEX_PREDICATE_TYPE,
+    "results": attest.RESULTS_PREDICATE_TYPE,
+}
+
+
+@app.command("keygen")
+def keygen(
+    private_out: Annotated[
+        Path,
+        typer.Option("--private", dir_okay=False, help="Where to write the private key."),
+    ] = Path("vexpath-signing.key"),
+    public_out: Annotated[
+        Path,
+        typer.Option("--public", dir_okay=False, help="Where to write the public key."),
+    ] = Path("vexpath-signing.pub"),
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite an existing key."),
+    ] = False,
+) -> None:
+    """Generate an ed25519 keypair for static signing.
+
+    Prefer keyless signing in CI: it binds the signature to the workflow that
+    produced it, and there is no long-lived secret to leak. A static key is
+    the right tool for an air-gapped pipeline, and for verifying an
+    attestation with nothing but this tool.
+    """
+    for path in (private_out, public_out):
+        if path.exists() and not force:
+            fail_config(
+                f"{path} already exists. Overwriting a signing key invalidates every "
+                f"signature made with it, so pass --force if that is what you want."
+            )
+
+    private_pem, public_pem = attest.generate_key()
+    private_out.parent.mkdir(parents=True, exist_ok=True)
+    private_out.write_bytes(private_pem)
+    public_out.write_bytes(public_pem)
+    # Best effort: on Windows this is a no-op, and the warning below covers it.
+    with contextlib.suppress(OSError):
+        private_out.chmod(0o600)
+
+    note(f"private key {private_out}")
+    note(f"public key  {public_out}")
+    note(f"key id      {attest.key_id(public_pem)}")
+    warn(
+        "The private key is unencrypted. Keep it out of version control and out "
+        "of anything that logs file contents."
+    )
+
+
+@app.command("sign")
+def sign(
+    document: Annotated[
+        Path,
+        typer.Argument(exists=True, dir_okay=False, help="The document to sign."),
+    ],
+    document_type: Annotated[
+        str,
+        typer.Option(
+            "--type",
+            help="What kind of document this is: 'vex' or 'results'.",
+        ),
+    ] = "vex",
+    key: Annotated[
+        Path | None,
+        typer.Option(
+            "--key",
+            exists=True,
+            dir_okay=False,
+            help=(
+                "Sign with this ed25519 private key. Without it, signing is "
+                "keyless through Sigstore and needs an OIDC credential, which "
+                "CI has and a laptop usually does not."
+            ),
+        ),
+    ] = None,
+    subject: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--subject",
+            help=(
+                "What the attestation is about, as name=sha256. Repeatable. "
+                "Defaults to the document itself, which is the honest subject "
+                "when nothing else is named."
+            ),
+        ),
+    ] = None,
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", dir_okay=False, help="Write here instead of stdout."),
+    ] = None,
+) -> None:
+    """Wrap a document in a signed in-toto attestation.
+
+    The result is a DSSE envelope holding an in-toto Statement v1, which is
+    what `cosign verify-attestation` and the in-toto tooling read.
+
+    A failure to sign is always reported and never produces an unsigned
+    envelope. A pipeline that believes it is signing and is not is worse off
+    than one that knows it is not.
+    """
+    predicate_type = PREDICATE_TYPES.get(document_type)
+    if predicate_type is None:
+        fail_config(f"--type {document_type!r} is not one of: {', '.join(sorted(PREDICATE_TYPES))}")
+
+    raw = document.read_bytes()
+    try:
+        predicate = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        fail(f"{document} is not readable JSON, so it cannot be attested: {exc}")
+
+    try:
+        subjects = _subjects(subject, document, raw)
+        statement = attest.build_statement(predicate, predicate_type, subjects)
+        envelope = (
+            attest.sign_with_key(statement, key.read_bytes())
+            if key is not None
+            else attest.sign_keyless(statement)
+        )
+    except attest.AttestationError as exc:
+        fail(str(exc))
+
+    note(f"predicate   {predicate_type}")
+    for entry in subjects:
+        note(f"subject     {entry.name} sha256:{entry.sha256[:16]}...")
+    note("signing     " + ("static key" if key is not None else "keyless (Sigstore)"))
+    if key is not None:
+        warn(
+            "Signed with a static key, so a consumer learns only that whoever "
+            "holds that key made the claim. Keyless signing in CI names the "
+            "workflow instead."
+        )
+
+    rendered = envelope.to_json()
+    if output is None:
+        emit(rendered)
+        return
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(rendered, encoding="utf-8", newline="\n")
+    note(f"written to {output}")
+
+
+def _subjects(
+    raw_subjects: list[str] | None, document: Path, payload: bytes
+) -> list[attest.Subject]:
+    """Work out what the attestation is about.
+
+    Defaults to the document itself. That is the honest subject when nothing
+    else is named: it says "this exact document is what I signed", which is
+    weaker than naming a built artefact but is true, and inventing a subject
+    would not be.
+    """
+    if not raw_subjects:
+        return [attest.subject_for_bytes(payload, document.name)]
+
+    subjects: list[attest.Subject] = []
+    for entry in raw_subjects:
+        name, separator, digest = entry.partition("=")
+        if not separator:
+            fail_config(
+                f"--subject {entry!r} is not name=sha256. A subject needs a digest "
+                f"a verifier can match against the artefact in front of them."
+            )
+        try:
+            subjects.append(attest.Subject(name=name.strip(), sha256=digest.strip()))
+        except attest.AttestationError as exc:
+            fail_config(str(exc))
+    return subjects
+
+
+@app.command("verify")
+def verify(
+    envelope_path: Annotated[
+        Path,
+        typer.Argument(exists=True, dir_okay=False, help="The attestation to check."),
+    ],
+    key: Annotated[
+        Path | None,
+        typer.Option(
+            "--key",
+            exists=True,
+            dir_okay=False,
+            help="Public key to verify a static-key signature against.",
+        ),
+    ] = None,
+    expect_type: Annotated[
+        str | None,
+        typer.Option(
+            "--expect-type",
+            help=(
+                "Require this predicate type: 'vex', 'results', or a URI. An "
+                "attestation about something else is not an answer to what you "
+                "asked."
+            ),
+        ),
+    ] = None,
+    expect_subject: Annotated[
+        str | None,
+        typer.Option(
+            "--expect-subject",
+            help=(
+                "Require that the attestation covers this sha256 digest. Without "
+                "it, a valid signature over someone else's artefact passes."
+            ),
+        ),
+    ] = None,
+    expect_identity: Annotated[
+        str | None,
+        typer.Option(
+            "--expect-identity",
+            help="Require this signer identity, such as a workflow URL.",
+        ),
+    ] = None,
+    expect_issuer: Annotated[
+        str | None,
+        typer.Option("--expect-issuer", help="Require this OIDC issuer."),
+    ] = None,
+    output: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TABLE,
+) -> None:
+    """Check an attestation, and that it says what you asked about.
+
+    Exits 1 when verification fails. A signature that merely verifies is a
+    weaker fact than it sounds: it may cover a different artefact, a different
+    kind of claim, or come from a different signer. The ``--expect`` options
+    are how that gap is closed, and the output says which of them were applied.
+    """
+    try:
+        envelope = attest.parse_envelope(envelope_path.read_text(encoding="utf-8"))
+    except attest.AttestationError as exc:
+        fail(str(exc))
+
+    if key is None:
+        fail_config(
+            "--key is required. Verifying a keyless signature means checking a "
+            "certificate and a transparency-log entry against an identity, which "
+            "is what 'cosign verify-attestation' does; this command verifies "
+            "static-key signatures."
+        )
+
+    try:
+        result = attest.verify_with_key(envelope, key.read_bytes())
+    except attest.AttestationError as exc:
+        fail(str(exc))
+
+    wanted_type = PREDICATE_TYPES.get(expect_type or "", expect_type)
+    result = result.requires(
+        predicate_type=wanted_type,
+        subject_sha256=expect_subject,
+        identity=expect_identity,
+        issuer=expect_issuer,
+    )
+
+    applied = [
+        name
+        for name, value in (
+            ("predicate type", wanted_type),
+            ("subject digest", expect_subject),
+            ("identity", expect_identity),
+            ("issuer", expect_issuer),
+        )
+        if value
+    ]
+
+    if output is OutputFormat.JSON:
+        emit_json(
+            {
+                "verified": result.verified,
+                "reason": result.reason,
+                "method": result.method,
+                "key_id": result.key_id,
+                "identity": result.identity,
+                "issuer": result.issuer,
+                "predicate_type": result.predicate_type,
+                "subjects": [entry.as_json() for entry in result.subjects],
+                "constraints_applied": applied,
+            }
+        )
+    else:
+        lines = [result.summary_line()]
+        lines.append("constraints     " + (", ".join(applied) if applied else "none applied"))
+        if not applied and result.verified:
+            lines.append("")
+            lines.append(
+                "A signature with no constraints applied says only that someone "
+                "holding that key signed something. Pass --expect-type and "
+                "--expect-subject to make it say more."
+            )
+        emit("\n".join(lines) + "\n")
+
+    if not result.verified:
+        raise typer.Exit(code=1)
+
+
+@app.command("inspect")
+def inspect(
+    envelope_path: Annotated[
+        Path,
+        typer.Argument(exists=True, dir_okay=False, help="The attestation to describe."),
+    ],
+) -> None:
+    """Describe an attestation without verifying it.
+
+    Deliberately a separate command. Describing an envelope and believing it
+    are different operations, and a tool that blurs them teaches people that a
+    signature's presence is the same as its validity.
+    """
+    try:
+        envelope = attest.parse_envelope(envelope_path.read_text(encoding="utf-8"))
+        metadata = attest.attestation_metadata(envelope)
+    except attest.AttestationError as exc:
+        fail(str(exc))
+
+    emit_json(metadata)
+    warn("Nothing here was verified. Use 'vexpath attest verify' for that.")
+
+
+__all__ = ["PREDICATE_TYPES", "app"]