vexpath 0.1.0__py3-none-any.whl

vexpath/commands/upload.py

@@ -0,0 +1,104 @@
+"""``vexpath upload``: send a result document that already exists.
+
+``vexpath scan --upload`` covers the ordinary case. This covers the one that
+turns up in real pipelines: the scan ran in one job and the upload has to
+happen in another, because the first job had no credential, or because the
+result is an artefact several steps consume.
+
+Re-running the scan to upload it would be the wrong answer. The analysis is
+the expensive part and its result is a document; a second run against a
+different advisory snapshot would not even produce the same verdicts, so what
+got uploaded would not be what the earlier job reported.
+
+The document is validated here, against the same model the analysis produced,
+before anything is sent. A hand-edited or truncated artefact then fails with a
+message about the file, rather than as a 422 from the platform describing a
+field nobody chose.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import ValidationError
+
+from vexpath.commands import auth
+from vexpath.output import OutputFormat, emit_json, fail, fail_config, note
+from vexpath_core.models.results import ScanResults
+
+
+def command(
+    results: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            dir_okay=False,
+            help="A document written by 'vexpath scan --format json'.",
+        ),
+    ],
+    project: Annotated[
+        str,
+        typer.Option("--project", help="Slug of the project to upload to."),
+    ],
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TABLE,
+) -> None:
+    """Upload a scan result produced earlier.
+
+    Validates the document before sending it, so a broken artefact is
+    described in terms of the file rather than as a rejection from the server.
+    """
+    credential = auth.credential_or_exit()
+    document = _load(results)
+    stored = auth.upload_results(credential, project, document)
+
+    if output_format is OutputFormat.JSON:
+        emit_json(stored)
+        return
+    note(f"uploaded {results} to {credential.api_url} as scan {stored.get('id', 'unknown')}")
+
+
+def _load(path: Path) -> dict[str, object]:
+    """Read and validate the result document.
+
+    Validated through ``ScanResults`` rather than merely parsed as JSON: the
+    platform validates with the same model, so anything accepted here is
+    accepted there, and the mismatch cannot show up as a confusing 422 after
+    the upload has been attempted.
+    """
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        fail(f"{path} could not be read: {exc}")
+
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        fail_config(
+            f"{path} is not readable JSON: {exc}. It should be the output of "
+            f"'vexpath scan --format json'."
+        )
+
+    if not isinstance(parsed, dict):
+        fail_config(f"{path} holds {type(parsed).__name__}, not a scan result document.")
+
+    try:
+        ScanResults.model_validate(parsed)
+    except ValidationError as exc:
+        fields = ", ".join(
+            ".".join(str(part) for part in error["loc"]) for error in exc.errors()[:5]
+        )
+        fail_config(
+            f"{path} is not a scan result this build understands. Problem "
+            f"fields: {fields or 'unknown'}. Re-run the scan with this version "
+            f"of vexpath."
+        )
+
+    return parsed
+
+
+__all__ = ["command"]

vexpath/commands/vex.py

@@ -0,0 +1,249 @@
+"""The ``vexpath vex`` command group: publish the analysis as OpenVEX.
+
+A scan's verdicts are an opinion until they are in a form someone else's tools
+read. This is that form.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from vexpath.exit_codes import ExitCode
+from vexpath.output import emit, fail, fail_config, note
+from vexpath.sources import advisory_source, close_source
+from vexpath_core import cdxvex, vex
+from vexpath_core.advisory.source import AdvisorySourceError
+from vexpath_core.enums import ComponentScope
+from vexpath_core.models.results import ScanResults
+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
+from vexpath_core.scan import scan as run_scan
+
+app = typer.Typer(help="Publish scan conclusions as VEX.", no_args_is_help=True)
+
+
+@app.command("export")
+def export(
+    path: Annotated[
+        Path,
+        typer.Argument(exists=True, file_okay=False, help="Project directory to scan."),
+    ] = Path(),
+    author: Annotated[
+        str | None,
+        typer.Option(
+            "--author",
+            "-a",
+            help=(
+                "Who is making these statements, as an organisation or a person. "
+                "Required: a VEX document nobody can attribute is one nobody can "
+                "decide whether to believe."
+            ),
+        ),
+    ] = None,
+    product: Annotated[
+        str | None,
+        typer.Option(
+            "--product",
+            "-p",
+            help=(
+                "Identifier of the product these statements are about, ideally a "
+                "purl. Defaults to the project slug. This is your product, not "
+                "the vulnerable dependency: the dependency is recorded as a "
+                "subcomponent."
+            ),
+        ),
+    ] = None,
+    results_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--results",
+            exists=True,
+            dir_okay=False,
+            help=(
+                "Use the JSON output of an earlier scan instead of scanning "
+                "again. The verdicts are the scan's, so re-deriving them would "
+                "risk a document that disagrees with the report it came from."
+            ),
+        ),
+    ] = None,
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", dir_okay=False, help="Write here instead of stdout."),
+    ] = None,
+    snapshot: Annotated[
+        Path | None,
+        typer.Option("--snapshot", exists=True, file_okay=False, help="Advisory snapshot to use."),
+    ] = None,
+    environment: Annotated[
+        Path | None,
+        typer.Option(
+            "--environment",
+            exists=True,
+            file_okay=False,
+            help="Virtual environment holding the installed dependencies.",
+        ),
+    ] = None,
+    download_missing: Annotated[
+        bool,
+        typer.Option(
+            "--download-missing",
+            help="Fetch a dependency's source from the index when it is not installed.",
+        ),
+    ] = False,
+    vex_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            "-f",
+            help=(
+                "'openvex' or 'cyclonedx'. The choice is the consumer's: a "
+                "conclusion in a format their toolchain cannot load is one they "
+                "do not have."
+            ),
+        ),
+    ] = "openvex",
+    document_version: Annotated[
+        int,
+        typer.Option(
+            "--document-version",
+            min=1,
+            help=(
+                "Version of this document for this product. Increment it when "
+                "publishing a document that supersedes an earlier one."
+            ),
+        ),
+    ] = 1,
+    skip_open: Annotated[
+        bool,
+        typer.Option(
+            "--skip-under-investigation",
+            help=(
+                "Leave out findings still being analysed. Off by default: the "
+                "absence of a statement reads as 'not an issue', and that is not "
+                "what under investigation means."
+            ),
+        ),
+    ] = False,
+    ignore_dev: Annotated[
+        bool,
+        typer.Option("--ignore-dev", help="Exclude development dependencies."),
+    ] = False,
+) -> None:
+    """Write an OpenVEX 0.2.0 document for this project.
+
+    The document states, for every advisory that matches a dependency, whether
+    the vulnerable code can run in your product, with the evidence for each
+    answer. A finding is stated as not affected only where reachability proved
+    the code is not in the execute path, which is the one justification this
+    analysis earns.
+
+    Byte-identical for identical results, so the document can be diffed between
+    scans and its hash is worth attesting.
+    """
+    if author is None or not author.strip():
+        fail(
+            "--author is required. A VEX document is believed on the strength of "
+            "who stands behind it, so it cannot be published anonymously."
+        )
+
+    results = (
+        _load_results(results_file)
+        if results_file is not None
+        else _scan(
+            path, snapshot, environment, download_missing=download_missing, ignore_dev=ignore_dev
+        )
+    )
+
+    if vex_format not in {"openvex", "cyclonedx"}:
+        fail_config(f"--format {vex_format!r} is not 'openvex' or 'cyclonedx'")
+
+    try:
+        if vex_format == "cyclonedx":
+            rendered = cdxvex.render_json(
+                results, cdxvex.VexMetadata(author=author.strip(), product_id=product)
+            )
+            # Validated against the official schema before it leaves, because a
+            # document a consumer's tooling rejects is worse than none: they
+            # have to work out whether the rejection or the content is wrong.
+            cdxvex.validate(rendered)
+        else:
+            rendered = vex.render_json(
+                results,
+                vex.VexIdentity(author=author.strip(), product_id=product),
+                version=document_version,
+                include_under_investigation=not skip_open,
+            )
+    except (vex.VexError, cdxvex.CycloneDxVexError) as exc:
+        fail(str(exc))
+
+    document = json.loads(rendered)
+    if vex_format == "cyclonedx":
+        counts = cdxvex.state_counts(document)
+        note(
+            f"{len(document['vulnerabilities'])} vulnerability record(s): "
+            + ", ".join(f"{count} {state}" for state, count in counts.items())
+        )
+        note(f"serial {document['serialNumber']}")
+        note("validated against the official CycloneDX 1.6 schema")
+    else:
+        counts = vex.statement_counts(document)
+        note(
+            f"{len(document['statements'])} statement(s): "
+            + ", ".join(f"{count} {status}" for status, count in counts.items())
+        )
+        note(f"document {document['@id']}")
+    note(f"sha256 {vex.document_sha256(rendered)}")
+
+    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 _load_results(path: Path) -> ScanResults:
+    try:
+        return ScanResults.model_validate_json(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        fail(f"{path} is not a vexpath scan result: {exc}")
+        raise  # unreachable; fail exits
+
+
+def _scan(
+    path: Path,
+    snapshot: Path | None,
+    environment: Path | None,
+    *,
+    download_missing: bool,
+    ignore_dev: bool,
+) -> ScanResults:
+    source = advisory_source(snapshot, result_noun="VEX document")
+    scopes = (
+        frozenset({ComponentScope.RUNTIME, ComponentScope.OPTIONAL})
+        if ignore_dev
+        else frozenset(ComponentScope)
+    )
+    options = ScanOptions(
+        include_scopes=scopes,
+        environment=environment,
+        download_missing=download_missing,
+    )
+    try:
+        return run_scan(path, source, options=options)
+    except (LockfileError, UnknownSbomFormatError, CycloneDxError, SpdxError) as exc:
+        fail(str(exc))
+    except AdvisorySourceError as exc:
+        fail(f"{exc}. Download a snapshot with 'vexpath advisory sync' and pass --snapshot.")
+    finally:
+        close_source(source)
+    raise typer.Exit(code=int(ExitCode.ANALYSIS_ERROR))  # unreachable
+
+
+__all__ = ["app"]

vexpath/credentials.py

@@ -0,0 +1,213 @@
+"""Where the command-line tool keeps an API key, and how it finds one.
+
+A key is a bearer credential: whoever holds it is the organisation. So the two
+decisions here are about not leaking it and not surprising anyone about which
+one is in use.
+
+**The environment wins over the stored file.** CI sets ``VEXPATH_API_KEY`` from
+a secret, and a stored file on a shared build machine must not silently
+override it. A developer who has logged in locally and then exports a key for a
+one-off command gets the exported one, which is what they asked for.
+
+**The file is written with no permissions for anybody else**, and the tool says
+where it is. A credential whose location is a mystery is one nobody rotates.
+
+**Nothing prints the key.** Not in a confirmation, not in a log line, not in an
+error. The visible prefix is enough to say which key is in use, and is what
+gets shown instead.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+from vexpath_core.keyformat import KEY_PREFIX, display_prefix, looks_like_key
+
+#: Read before the stored file. CI sets this from a secret, and a stored file
+#: must not override it.
+KEY_ENVIRONMENT_VARIABLE = "VEXPATH_API_KEY"
+
+#: Where the platform lives, overridable for a self-hosted install.
+URL_ENVIRONMENT_VARIABLE = "VEXPATH_API_URL"
+
+DEFAULT_API_URL = "https://api.vexpath.dev"
+
+#: Overrides the whole configuration directory, which is what a test needs and
+#: what a container with a read-only home directory needs too.
+HOME_ENVIRONMENT_VARIABLE = "VEXPATH_CONFIG_DIR"
+
+
+class CredentialError(Exception):
+    """Raised when a credential cannot be stored or read."""
+
+
+@dataclass(frozen=True, slots=True)
+class Credential:
+    """A key and where it came from.
+
+    The source is carried because "which key am I using" is the question
+    behind most authentication confusion, and the answer is usually that one
+    place overrode another.
+    """
+
+    secret: str
+    api_url: str
+    #: ``environment`` or ``file``.
+    source: str
+
+    @property
+    def prefix(self) -> str:
+        """What is safe to print."""
+        return display_prefix(self.secret)
+
+    def __repr__(self) -> str:
+        """Never render the secret.
+
+        A credential that appears in a traceback has leaked, and tracebacks
+        are produced exactly when attention is elsewhere.
+        """
+        return f"Credential(prefix={self.prefix!r}, source={self.source!r})"
+
+
+def config_directory() -> Path:
+    """Where the credential file lives.
+
+    Follows the platform convention, and respects an override so a container
+    with a read-only home directory, or a test, can point it elsewhere.
+    """
+    override = os.environ.get(HOME_ENVIRONMENT_VARIABLE)
+    if override:
+        return Path(override)
+    if os.name == "nt":
+        base = os.environ.get("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+        return Path(base) / "vexpath"
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "vexpath"
+
+
+def credential_path() -> Path:
+    return config_directory() / "credentials.json"
+
+
+def load() -> Credential | None:
+    """The credential to use, or None when there is none.
+
+    The environment is checked first and deliberately: a stored file on a
+    shared build machine must not override a key CI supplied from a secret.
+    """
+    from_environment = os.environ.get(KEY_ENVIRONMENT_VARIABLE, "").strip()
+    if from_environment:
+        return Credential(secret=from_environment, api_url=_api_url(None), source="environment")
+
+    path = credential_path()
+    if not path.is_file():
+        return None
+    try:
+        stored = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        msg = (
+            f"{path} is not readable as a credential file: {exc}. Delete it and "
+            f"run 'vexpath login' again."
+        )
+        raise CredentialError(msg) from exc
+
+    secret = str(stored.get("api_key") or "").strip()
+    if not secret:
+        return None
+    return Credential(secret=secret, api_url=_api_url(stored.get("api_url")), source="file")
+
+
+def _api_url(stored: object) -> str:
+    """Which platform to talk to.
+
+    The environment wins here too, so a one-off command against a staging
+    deployment does not require editing a file and remembering to change it
+    back.
+    """
+    from_environment = os.environ.get(URL_ENVIRONMENT_VARIABLE, "").strip()
+    if from_environment:
+        return from_environment.rstrip("/")
+    if isinstance(stored, str) and stored.strip():
+        return stored.strip().rstrip("/")
+    return DEFAULT_API_URL
+
+
+def store(secret: str, api_url: str) -> Path:
+    """Write a credential, readable only by its owner.
+
+    Raises:
+        CredentialError: if the key is not shaped like one, or the file cannot
+            be written. Storing something that is not a key would turn a
+            typo into an authentication failure on the next command, with
+            nothing to connect the two.
+    """
+    candidate = secret.strip()
+    if not looks_like_key(candidate):
+        msg = (
+            f"that does not look like an API key: one starts with "
+            f"{KEY_PREFIX!r} and is created in the dashboard"
+        )
+        raise CredentialError(msg)
+
+    directory = config_directory()
+    path = credential_path()
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+        # Written through a temporary file with restrictive permissions set
+        # before any content, so the secret is never briefly world-readable.
+        temporary = path.with_suffix(".partial")
+        temporary.write_text(
+            json.dumps({"api_key": candidate, "api_url": api_url.rstrip("/")}, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        temporary.chmod(stat.S_IRUSR | stat.S_IWUSR)
+        temporary.replace(path)
+    except OSError as exc:
+        msg = f"the credential could not be written to {path}: {exc}"
+        raise CredentialError(msg) from exc
+
+    return path
+
+
+def display_prefix_of(secret: str) -> str:
+    """What is safe to print for a key not yet stored.
+
+    Exists so no caller is tempted to slice the secret itself and get the
+    boundary wrong.
+    """
+    return display_prefix(secret)
+
+
+def forget() -> bool:
+    """Remove a stored credential.
+
+    Returns True when there was one. Does not touch the environment variable,
+    and the caller says so: a user who logs out and still has a key exported
+    is still authenticated, and finding that out later is worse than being
+    told now.
+    """
+    path = credential_path()
+    if not path.is_file():
+        return False
+    path.unlink()
+    return True
+
+
+__all__ = [
+    "DEFAULT_API_URL",
+    "HOME_ENVIRONMENT_VARIABLE",
+    "KEY_ENVIRONMENT_VARIABLE",
+    "URL_ENVIRONMENT_VARIABLE",
+    "Credential",
+    "CredentialError",
+    "config_directory",
+    "credential_path",
+    "display_prefix_of",
+    "forget",
+    "load",
+    "store",
+]

vexpath/exit_codes.py

@@ -0,0 +1,28 @@
+"""Process exit codes.
+
+These are a published contract with CI systems, so they are defined in one
+place and must not be reused for new meanings. The important distinction is
+between code 1 and code 2: a build that fails because the code is vulnerable
+must never look like a build that fails because the scanner broke.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    """Exit status of the ``vexpath`` process."""
+
+    #: Analysis completed and the policy passed.
+    OK = 0
+    #: Analysis completed and the policy failed.
+    POLICY_FAILED = 1
+    #: Analysis could not complete: parse failure, missing lockfile, upstream
+    #: outage. The verdicts are unknown, not clean.
+    ANALYSIS_ERROR = 2
+    #: Bad configuration: unparsable policy, malformed .vexpath.yml, invalid flags.
+    CONFIG_ERROR = 3
+
+
+__all__ = ["ExitCode"]