vexpath 0.1.0__py3-none-any.whl

vexpath/commands/report.py

@@ -0,0 +1,189 @@
+"""``vexpath report``: render a scan that already ran, in another format.
+
+The analysis is the expensive part. A cold scan of a real project takes minutes
+because it downloads and parses every dependency's source; the result is a
+document. Re-running it to get the same conclusions as SARIF rather than as a
+table is pure waste, and worse than waste: a second run against a corpus that
+has moved on produces *different* verdicts, so the SARIF a pipeline uploads
+would not match the table a developer read.
+
+So this reads the document and re-renders it. Nothing is re-analysed, nothing
+can disagree. It exists because the GitHub Action needs the same scan three
+ways -- a table in the log, markdown in the step summary, SARIF for code
+scanning -- and three scans would be three answers.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from vexpath.output import OutputFormat, emit, fail, note
+from vexpath_core import report as renderers
+from vexpath_core.models.results import ScanResults
+
+
+def command(
+    results_file: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            dir_okay=False,
+            help="A document written by 'vexpath scan --format json'.",
+        ),
+    ],
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TABLE,
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            dir_okay=False,
+            help="Write here instead of to standard output.",
+        ),
+    ] = None,
+    show_cleared: Annotated[
+        bool,
+        typer.Option("--show-cleared", help="List findings that were cleared, too."),
+    ] = False,
+    summary: Annotated[
+        bool,
+        typer.Option(
+            "--summary",
+            help=(
+                "Print the counts as key=value lines instead of a report, for "
+                "a CI step to read. The counts are computed by the same code "
+                "that renders every other format, so a workflow cannot "
+                "disagree with the report beside it."
+            ),
+        ),
+    ] = False,
+    lockfile: Annotated[
+        str | None,
+        typer.Option(
+            "--lockfile",
+            help=(
+                "Path to record as the location of each SARIF result. Code "
+                "scanning anchors an alert to a file, and a lockfile is the "
+                "file a dependency finding is actually about."
+            ),
+        ),
+    ] = None,
+) -> None:
+    """Re-render a scan result without re-running the analysis.
+
+    Exits 2 if the document is not one this build understands. It is validated
+    through the same model the analysis produced, so a hand-edited file is
+    refused here rather than rendering into a report that looks authoritative.
+    """
+    try:
+        results = ScanResults.model_validate_json(results_file.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        fail(f"{results_file} is not a vexpath scan result: {exc}")
+
+    if summary:
+        emit(_summary(results))
+        return
+
+    rendered = _render(
+        results,
+        output_format,
+        show_cleared=show_cleared,
+        lockfile=lockfile or _lockfile_of(results),
+    )
+
+    if output is None:
+        emit(rendered)
+        return
+
+    try:
+        output.write_text(rendered, encoding="utf-8")
+    except OSError as exc:
+        fail(f"{output} could not be written: {exc}")
+    # To standard error, so a caller redirecting standard output into a file
+    # does not find this line in it.
+    note(f"wrote {output}")
+
+
+def _render(
+    results: ScanResults,
+    output_format: OutputFormat,
+    *,
+    show_cleared: bool,
+    lockfile: str,
+) -> str:
+    if output_format is OutputFormat.JSON:
+        # Re-serialised through the model rather than copied byte for byte: a
+        # document that round-trips is one this build genuinely understood.
+        import json
+
+        return json.dumps(results.model_dump(mode="json", by_alias=True), indent=2)
+    if output_format is OutputFormat.SARIF:
+        return renderers.render_sarif_json(results, lockfile_path=lockfile)
+    if output_format is OutputFormat.MARKDOWN:
+        return renderers.render_markdown(results, show_cleared=show_cleared)
+    return renderers.render_text(results, show_cleared=show_cleared)
+
+
+def _summary(results: ScanResults) -> str:
+    """The counts a CI step needs, as ``key=value`` lines.
+
+    This shape so a GitHub Actions step can append it straight to
+    ``$GITHUB_OUTPUT``, and any other shell can ``eval`` it. Computed here
+    rather than in YAML by whoever writes the workflow: the definitions of
+    "needs attention" and "reachable" are decisions this project has already
+    made, and a second implementation in a shell script would eventually
+    disagree with the report printed beside it.
+    """
+    from vexpath_core.enums import Verdict
+
+    by_verdict = results.counts_by_verdict()
+    lines = [
+        f"total={len(results.findings)}",
+        f"needs_attention={len(results.findings_needing_attention())}",
+        f"cleared={by_verdict[Verdict.NOT_AFFECTED]}",
+        f"reachable={len(results.reachable_findings())}",
+        f"under_investigation={by_verdict[Verdict.UNDER_INVESTIGATION]}",
+        # Empty rather than "true" when no policy ran: a workflow must be able
+        # to tell "the gate passed" from "there was no gate".
+        f"policy_passed={'' if results.policy is None else str(results.policy.passed).lower()}",
+        f"reproducible={str(results.is_reproducible).lower()}",
+        # Whether reachability ran at all. A cleared count means nothing
+        # without it: zero cleared because everything is reachable is a
+        # different situation from zero cleared because nobody looked.
+        f"reachability_analysed={str(_analysed(results)).lower()}",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def _analysed(results: ScanResults) -> bool:
+    """Whether the reachability search ran at all.
+
+    True when the scan recorded the entry points it started from, or when any
+    finding carries a reachability result. Derived rather than stored, because
+    the document already says both of those things and a third field could
+    contradict them.
+    """
+    if results.entry_points is not None:
+        return True
+    return any(finding.reach is not None for finding in results.findings)
+
+
+def _lockfile_of(results: ScanResults) -> str:
+    """What the scan said it read, for the SARIF location.
+
+    Taken from the document rather than guessed from the working directory,
+    because this command may run in a different checkout from the scan -- a
+    release job rendering a scan an earlier job produced, for instance. A
+    document written by an older build carries no such field, which is why
+    ``--lockfile`` exists and why "unknown" is the last resort rather than an
+    error.
+    """
+    return results.project.lockfile or "unknown"
+
+
+__all__ = ["command"]

vexpath/commands/sbom.py

@@ -0,0 +1,173 @@
+"""The ``vexpath sbom`` command group: generate and validate bills of materials."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+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.sbom import (
+    LockfileError,
+    UnknownSbomFormatError,
+    cyclonedx,
+    find_lockfiles,
+    generate_sbom,
+    load,
+    minimum_elements,
+    spdx,
+)
+from vexpath_core.sbom.cyclonedx import CycloneDxError
+from vexpath_core.sbom.spdx import SpdxError
+
+app = typer.Typer(help="Generate and validate software bills of materials.", no_args_is_help=True)
+
+
+class SbomFormatChoice(StrEnum):
+    """Output format for a generated document."""
+
+    CYCLONEDX = "cyclonedx"
+    SPDX = "spdx"
+
+
+@app.command("generate")
+def generate(
+    path: Annotated[
+        Path,
+        typer.Argument(exists=True, file_okay=False, help="Project directory to inventory."),
+    ] = Path(),
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Write the document here instead of stdout."),
+    ] = None,
+    document_format: Annotated[
+        SbomFormatChoice,
+        typer.Option("--format", "-f", help="Document format to write."),
+    ] = SbomFormatChoice.CYCLONEDX,
+    lockfile: Annotated[
+        Path | None,
+        typer.Option(
+            "--lockfile",
+            exists=True,
+            dir_okay=False,
+            help="Use this lockfile instead of searching the directory.",
+        ),
+    ] = None,
+) -> None:
+    """Generate an SBOM from a project's lockfile.
+
+    The document is deterministic: an unchanged project produces byte-identical
+    output, including its serial number, so two runs can be compared.
+    """
+    try:
+        sbom = generate_sbom(path, lockfile=lockfile)
+    except LockfileError as exc:
+        fail(str(exc))
+
+    gaps = minimum_elements.check(sbom)
+    sbom = sbom.model_copy(update={"minimum_element_gaps": gaps})
+
+    text = (
+        cyclonedx.to_json(sbom)
+        if document_format is SbomFormatChoice.CYCLONEDX
+        else spdx.to_json(sbom)
+    )
+
+    for item in sbom.notes:
+        note(item)
+
+    if output is None:
+        emit(text)
+    else:
+        output.write_text(text, encoding="utf-8", newline="\n")
+        note(f"wrote {sbom.component_count} components to {output}")
+
+
+@app.command("validate")
+def validate(
+    file: Annotated[
+        Path,
+        typer.Argument(exists=True, dir_okay=False, help="SBOM document to validate."),
+    ],
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TABLE,
+) -> None:
+    """Validate a document and report its minimum-element gaps.
+
+    Schema problems are errors. Minimum-element gaps are reported but do not
+    fail the command: an incomplete document is still analysable, and whether
+    the gaps matter is the reader's call, not this tool's.
+    """
+    try:
+        sbom = load(file)
+    except (UnknownSbomFormatError, CycloneDxError, SpdxError) as exc:
+        fail(str(exc))
+
+    gaps = minimum_elements.check(sbom)
+
+    if output_format is OutputFormat.JSON:
+        emit_json(
+            {
+                "file": str(file),
+                "format": sbom.format.value,
+                "spec_version": sbom.spec_version,
+                "valid": True,
+                "component_count": sbom.component_count,
+                "dependency_edges": len(sbom.edges),
+                "generated_by": sbom.generated_by.value,
+                "minimum_element_gaps": list(gaps),
+                "notes": list(sbom.notes),
+            }
+        )
+        return
+
+    lines = [
+        f"{file.name} is a valid {sbom.format.value} document.",
+        f"  components       {sbom.component_count}",
+        f"  dependency edges {len(sbom.edges)}",
+        f"  generated by     {sbom.generated_by.value}",
+    ]
+    if gaps:
+        lines.append("")
+        lines.append(f"Minimum-element gaps ({len(gaps)}):")
+        lines.extend(f"  - {gap}" for gap in gaps)
+    else:
+        lines.append("")
+        lines.append("No minimum-element gaps.")
+    emit("\n".join(lines) + "\n")
+
+
+@app.command("lockfiles")
+def lockfiles(
+    path: Annotated[
+        Path,
+        typer.Argument(exists=True, file_okay=False, help="Project directory to inspect."),
+    ] = Path(),
+) -> None:
+    """List the lockfiles found in a project, best first.
+
+    Useful when a repository holds several and you want to know which one a
+    scan would use, before running one.
+    """
+    found = find_lockfiles(path)
+    if not found:
+        fail_config(
+            f"no supported lockfile in {path}. Generate one with 'uv lock', "
+            "'poetry lock' or 'npm install', or pass an SBOM with --sbom."
+        )
+    lines = [f"Lockfiles in {path}, in the order a scan would prefer them:"]
+    for index, candidate in enumerate(found, start=1):
+        marker = " (would be used)" if index == 1 else ""
+        lines.append(f"  {index}. {candidate.name}{marker}")
+    if len(found) > 1:
+        warn(
+            "More than one lockfile is present. Pass --lockfile to choose "
+            "explicitly if the first is not the one that ships."
+        )
+    emit("\n".join(lines) + "\n")
+
+
+__all__ = ["app"]

vexpath/commands/scan.py

@@ -0,0 +1,309 @@
+"""The ``vexpath scan`` command: the default way the tool is used."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from vexpath import credentials
+from vexpath.commands import auth
+from vexpath.exit_codes import ExitCode
+from vexpath.output import OutputFormat, emit, emit_json, fail, fail_config, note
+from vexpath.sources import SNAPSHOT_ENV, advisory_source, close_source
+from vexpath_core import report
+from vexpath_core.advisory.source import AdvisorySourceError
+from vexpath_core.enums import ComponentScope
+from vexpath_core.policy import PRESETS, PolicyError
+from vexpath_core.sbom import LockfileError, UnknownSbomFormatError
+from vexpath_core.sbom.cyclonedx import CycloneDxError
+from vexpath_core.sbom.spdx import SpdxError
+from vexpath_core.scan import ScanOptions, scanned_lockfile
+from vexpath_core.scan import scan as run_scan
+
+
+def command(
+    path: Annotated[
+        Path,
+        typer.Argument(exists=True, file_okay=False, help="Project directory to scan."),
+    ] = Path(),
+    sbom: Annotated[
+        Path | None,
+        typer.Option(
+            "--sbom",
+            exists=True,
+            dir_okay=False,
+            help="Analyse this SBOM instead of generating one from a lockfile.",
+        ),
+    ] = None,
+    lockfile: Annotated[
+        Path | None,
+        typer.Option(
+            "--lockfile",
+            exists=True,
+            dir_okay=False,
+            help="Use this lockfile instead of searching the directory.",
+        ),
+    ] = None,
+    snapshot: Annotated[
+        Path | None,
+        typer.Option(
+            "--snapshot",
+            exists=True,
+            file_okay=False,
+            help=(
+                "Read advisories from this local snapshot, making the scan "
+                f"reproducible and offline. Defaults to ${SNAPSHOT_ENV}."
+            ),
+        ),
+    ] = None,
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TABLE,
+    no_reach: Annotated[
+        bool,
+        typer.Option(
+            "--no-reach",
+            help="Skip reachability analysis and report matching only.",
+        ),
+    ] = False,
+    ignore_dev: Annotated[
+        bool,
+        typer.Option(
+            "--ignore-dev",
+            help="Exclude development dependencies from analysis.",
+        ),
+    ] = False,
+    show_cleared: Annotated[
+        bool,
+        typer.Option("--show-cleared", help="List findings that were cleared, too."),
+    ] = False,
+    entry_point: Annotated[
+        str | None,
+        typer.Option(
+            "--entry-point",
+            "-e",
+            help=(
+                "Comma-separated entry points to start the reachability search "
+                "from, as module.path:function. Nothing beats being told how the "
+                "application starts."
+            ),
+        ),
+    ] = None,
+    environment: Annotated[
+        Path | None,
+        typer.Option(
+            "--environment",
+            exists=True,
+            file_okay=False,
+            help=(
+                "Virtual environment holding the installed dependencies. "
+                "Defaults to the one this command is running in."
+            ),
+        ),
+    ] = None,
+    download_missing: Annotated[
+        bool,
+        typer.Option(
+            "--download-missing",
+            help=(
+                "Fetch a dependency's source from the package index when it is "
+                "not installed. Reaches the network. Without it, a scan of a "
+                "lockfile alone can confirm findings but never clear them."
+            ),
+        ),
+    ] = False,
+    no_cache: Annotated[
+        bool,
+        typer.Option(
+            "--no-cache", help="Rebuild dependency graphs instead of reusing cached ones."
+        ),
+    ] = False,
+    policy: Annotated[
+        str | None,
+        typer.Option(
+            "--policy",
+            help=(
+                "The gate: a preset name, a CEL expression, or a path to a file "
+                "holding one. Exits 1 when it fails. Run 'vexpath policy list' to "
+                "see the presets. Without this, nothing is gated and the scan "
+                "only reports."
+            ),
+        ),
+    ] = None,
+    upload: Annotated[
+        bool,
+        typer.Option(
+            "--upload",
+            help=(
+                "Send the result to the platform after the scan. Needs a "
+                "credential from 'vexpath login' or "
+                f"${credentials.KEY_ENVIRONMENT_VARIABLE}, and --project."
+            ),
+        ),
+    ] = False,
+    project: Annotated[
+        str | None,
+        typer.Option(
+            "--project",
+            help="Slug of the project to upload to. Required with --upload.",
+        ),
+    ] = None,
+    fail_on_findings: Annotated[
+        bool,
+        typer.Option(
+            "--fail-on-findings/--no-fail-on-findings",
+            help=(
+                "Exit with code 1 when anything needs attention at all. A blunt "
+                "alternative to --policy, kept because it needs no expression "
+                "written and sometimes that is the right trade."
+            ),
+        ),
+    ] = False,
+) -> None:
+    """Scan a project for vulnerable dependencies.
+
+    Reachability analysis runs by default and is what makes the report short:
+    a finding is cleared only when the vulnerable code provably cannot run.
+    Pass ``--no-reach`` to report matching alone, in which case nothing is
+    cleared and the output says so.
+    """
+    if no_reach:
+        note(
+            "Reachability analysis is off, so this reports matching only. No "
+            "finding will be cleared."
+        )
+
+    # Resolved before any analysis runs. A missing credential or a forgotten
+    # --project discovered after a four-minute scan has thrown the scan away,
+    # and the person who sees that message is already in a hurry.
+    credential = _upload_credential(upload=upload, project=project)
+
+    source = advisory_source(snapshot, result_noun="scan")
+    scopes = (
+        frozenset({ComponentScope.RUNTIME, ComponentScope.OPTIONAL})
+        if ignore_dev
+        else frozenset(ComponentScope)
+    )
+    options = ScanOptions(
+        sbom_path=sbom,
+        lockfile=lockfile,
+        include_scopes=scopes,
+        policy=_resolve_policy(policy),
+        reachability=not no_reach,
+        entry_points=tuple(
+            entry.strip() for entry in (entry_point or "").split(",") if entry.strip()
+        ),
+        environment=environment,
+        use_cache=not no_cache,
+        download_missing=download_missing,
+    )
+
+    try:
+        results = run_scan(path, source, options=options)
+    except PolicyError as exc:
+        # A gate that cannot be evaluated is a configuration problem, and must
+        # never be reported as a gate that passed.
+        fail_config(str(exc))
+    except (LockfileError, UnknownSbomFormatError, CycloneDxError, SpdxError) as exc:
+        fail(str(exc))
+    except AdvisorySourceError as exc:
+        fail(
+            f"{exc}. To scan without network access, download a snapshot with "
+            f"'vexpath advisory sync' and pass --snapshot."
+        )
+    finally:
+        close_source(source)
+
+    _render(results, output_format, path, options, show_cleared=show_cleared)
+
+    if credential is not None:
+        # Uploaded before the policy decides the exit code, deliberately: the
+        # scan the platform most needs is the one that just failed a gate, and
+        # exiting first would mean the record of the failure never arrives.
+        assert project is not None  # guaranteed by _upload_credential
+        _upload(credential, project, results)
+
+    if results.policy is not None and not results.policy.passed:
+        raise typer.Exit(code=int(ExitCode.POLICY_FAILED))
+
+    needs_attention = len(results.findings_needing_attention())
+    if fail_on_findings and needs_attention:
+        raise typer.Exit(code=int(ExitCode.POLICY_FAILED))
+
+
+def _upload_credential(*, upload: bool, project: str | None) -> credentials.Credential | None:
+    """The credential to upload with, or None when no upload was asked for.
+
+    Resolved up front so the two mistakes that waste a whole scan -- no
+    credential, and --upload without --project -- are reported before the
+    analysis starts rather than after it.
+    """
+    if not upload:
+        if project is not None:
+            # Saying nothing would silently discard the flag, and the person
+            # would wait for a result that never appears on the platform.
+            fail_config("--project only means something with --upload.")
+        return None
+    if not project:
+        fail_config("--upload needs --project to say where the result goes.")
+    return auth.credential_or_exit()
+
+
+def _upload(credential: credentials.Credential, project: str, results: object) -> None:
+    from vexpath_core.models.results import ScanResults
+
+    assert isinstance(results, ScanResults)
+    stored = auth.upload_results(
+        credential, project, results.model_dump(mode="json", by_alias=True)
+    )
+    scan_id = stored.get("id", "unknown")
+    note(f"uploaded to {credential.api_url} as scan {scan_id}")
+
+
+def _resolve_policy(source: str | None) -> str | None:
+    """Turn the flag into something the core can compile.
+
+    A preset name wins over a file of the same name: the presets are a closed
+    vocabulary, and a file called ``balanced`` in a working directory must not
+    silently change what the default means.
+    """
+    if source is None:
+        return None
+    if source in PRESETS:
+        return source
+    candidate = Path(source)
+    if candidate.is_file():
+        try:
+            return candidate.read_text(encoding="utf-8").strip()
+        except OSError as exc:
+            fail_config(f"{candidate} could not be read: {exc}")
+    return source
+
+
+def _render(
+    results: object,
+    output_format: OutputFormat,
+    path: Path,
+    options: ScanOptions,
+    *,
+    show_cleared: bool,
+) -> None:
+    from vexpath_core.models.results import ScanResults
+
+    assert isinstance(results, ScanResults)  # narrowed for the type checker
+
+    if output_format is OutputFormat.JSON:
+        emit_json(results.model_dump(mode="json", by_alias=True))
+        return
+    if output_format is OutputFormat.SARIF:
+        emit(report.render_sarif_json(results, lockfile_path=scanned_lockfile(path, options)))
+        return
+    if output_format is OutputFormat.MARKDOWN:
+        emit(report.render_markdown(results, show_cleared=show_cleared))
+        return
+    emit(report.render_text(results, show_cleared=show_cleared))
+
+
+__all__ = ["SNAPSHOT_ENV", "command"]