vexpath 0.1.0__py3-none-any.whl

vexpath/commands/auth.py

@@ -0,0 +1,235 @@
+"""``vexpath login``, ``whoami`` and ``logout``.
+
+Three commands whose whole job is to make it obvious which credential is in
+use. Most authentication confusion is not "my key is wrong", it is "which key
+is this using", and the answer is usually that one source overrode another.
+So every one of these says where the credential came from.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Annotated, Any
+
+import httpx
+import typer
+
+from vexpath import credentials
+from vexpath.output import OutputFormat, emit, emit_json, fail, fail_config, note, warn
+
+app = typer.Typer(help="Store and check the credential used for uploads.", no_args_is_help=True)
+
+_TIMEOUT = 30.0
+
+
+@app.command("login")
+def login(
+    key: Annotated[
+        str | None,
+        typer.Option(
+            "--key",
+            help=(
+                "The API key. Omitted, it is read from the terminal without "
+                "echoing, so it does not land in shell history."
+            ),
+        ),
+    ] = None,
+    api_url: Annotated[
+        str | None,
+        typer.Option("--api-url", help="Platform to talk to, for a self-hosted install."),
+    ] = None,
+) -> None:
+    """Verify an API key and store it.
+
+    The key is checked against the platform before it is written. Storing an
+    unverified credential turns a typo into an authentication failure on some
+    later command, with nothing to connect the two.
+    """
+    secret = key or typer.prompt("API key", hide_input=True)
+    url = (api_url or credentials.DEFAULT_API_URL).rstrip("/")
+
+    identity = _whoami(url, secret)
+    try:
+        path = credentials.store(secret, url)
+    except credentials.CredentialError as exc:
+        fail_config(str(exc))
+
+    note(f"signed in to {identity['org_name']} ({identity['org_slug']})")
+    note(f"key {credentials.display_prefix_of(secret)}")
+    note(f"stored in {path}")
+    if credentials.KEY_ENVIRONMENT_VARIABLE in _environment():
+        # Said now rather than discovered later: the environment wins, so the
+        # key just stored will not be the one used.
+        warn(
+            f"${credentials.KEY_ENVIRONMENT_VARIABLE} is set, and it takes "
+            f"precedence over the stored credential. Unset it to use this one."
+        )
+
+
+@app.command("whoami")
+def whoami(
+    output: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TABLE,
+) -> None:
+    """Show which credential is in use, and for which organisation.
+
+    Exits 3 when there is none, so a CI step can check for a credential
+    before running a scan it intends to upload.
+    """
+    credential = _credential()
+    identity = _whoami(credential.api_url, credential.secret)
+
+    if output is OutputFormat.JSON:
+        emit_json({**identity, "source": credential.source, "api_url": credential.api_url})
+        return
+
+    emit(
+        "\n".join(
+            [
+                f"{'organisation':<16}{identity['org_name']} ({identity['org_slug']})",
+                f"{'projects':<16}{identity['project_count']}",
+                f"{'credential':<16}{credential.prefix}",
+                # Which source won. This is the question behind most
+                # authentication confusion.
+                f"{'from':<16}{_source_label(credential.source)}",
+                f"{'platform':<16}{credential.api_url}",
+            ]
+        )
+        + "\n"
+    )
+
+
+def _source_label(source: str) -> str:
+    if source == "environment":
+        return f"${credentials.KEY_ENVIRONMENT_VARIABLE}"
+    return str(credentials.credential_path())
+
+
+@app.command("logout")
+def logout() -> None:
+    """Remove the stored credential.
+
+    Says plainly when an exported key means you are still authenticated.
+    Finding that out later is worse than being told now.
+    """
+    removed = credentials.forget()
+    if removed:
+        note(f"removed {credentials.credential_path()}")
+    else:
+        note("there was no stored credential")
+
+    if credentials.KEY_ENVIRONMENT_VARIABLE in _environment():
+        warn(
+            f"${credentials.KEY_ENVIRONMENT_VARIABLE} is still set, so uploads "
+            f"will continue to work. Unset it to sign out completely."
+        )
+
+
+def credential_or_exit() -> credentials.Credential:
+    """The credential to use, or an explanation and exit 3.
+
+    Public because the scan command needs it before it starts work: finding
+    out there is no credential after a four-minute analysis wastes the
+    analysis.
+    """
+    return _credential()
+
+
+def _credential() -> credentials.Credential:
+    try:
+        credential = credentials.load()
+    except credentials.CredentialError as exc:
+        fail_config(str(exc))
+    if credential is None:
+        fail_config(
+            f"no credential. Run 'vexpath login', or set "
+            f"${credentials.KEY_ENVIRONMENT_VARIABLE} in CI."
+        )
+    return credential
+
+
+def _whoami(api_url: str, secret: str) -> dict[str, Any]:
+    """Ask the platform who this credential belongs to.
+
+    Exits rather than returning an error, because every caller here needs the
+    answer to continue, and each failure has a different remedy worth naming.
+    """
+    try:
+        with httpx.Client(timeout=_TIMEOUT, follow_redirects=True) as client:
+            response = client.get(f"{api_url}/v1/me", headers={"Authorization": f"Bearer {secret}"})
+    except httpx.HTTPError as exc:
+        fail(f"{api_url} could not be reached: {exc}")
+
+    if response.status_code == 401:
+        fail_config(
+            "the platform rejected that key. Check it was copied whole, and "
+            "that it has not been revoked in the dashboard."
+        )
+    if response.status_code == 404:
+        fail_config(
+            f"{api_url} does not look like a vexpath platform: /v1/me is not "
+            f"there. Check --api-url."
+        )
+    if response.status_code >= 400:
+        fail(f"{api_url} answered {response.status_code}: {response.text[:200]}")
+
+    try:
+        payload: dict[str, Any] = response.json()
+    except ValueError:
+        fail(f"{api_url} answered with something that is not JSON")
+    return payload
+
+
+def _environment() -> dict[str, str]:
+    import os
+
+    return dict(os.environ)
+
+
+def upload_results(
+    credential: credentials.Credential, project: str, results: Mapping[str, Any]
+) -> dict[str, Any]:
+    """Post a results document, and say what happened.
+
+    Lives here rather than in the scan command so that the credential handling
+    and the error messages are in one place: a failed upload after a
+    successful scan is the moment a user most needs to be told which of the
+    two went wrong. Every message below therefore begins by saying the scan
+    itself completed, because the exit code cannot say it and a CI log read in
+    a hurry will otherwise be understood as "the scan failed".
+    """
+    try:
+        with httpx.Client(timeout=_TIMEOUT, follow_redirects=True) as client:
+            response = client.post(
+                f"{credential.api_url}/v1/scans",
+                json={"project": project, "results": dict(results)},
+                headers={"Authorization": f"Bearer {credential.secret}"},
+            )
+    except httpx.HTTPError as exc:
+        fail(
+            f"the scan completed but could not be uploaded: {credential.api_url} "
+            f"could not be reached: {exc}"
+        )
+
+    if response.status_code == 401:
+        fail_config("the scan completed but the platform rejected the credential.")
+    if response.status_code == 404:
+        fail_config(
+            f"the scan completed but there is no project {project!r} in this "
+            f"organisation. Create it in the dashboard, or check --project."
+        )
+    if response.status_code >= 400:
+        fail(
+            f"the scan completed but the upload was refused with "
+            f"{response.status_code}: {response.text[:300]}"
+        )
+
+    try:
+        stored: dict[str, Any] = response.json()
+    except ValueError:
+        fail(f"the scan was accepted but {credential.api_url} answered with non-JSON")
+    return stored
+
+
+__all__ = ["app", "credential_or_exit", "login", "logout", "upload_results", "whoami"]

vexpath/commands/policy.py

@@ -0,0 +1,179 @@
+"""The ``vexpath policy`` command group: read, test and explain the gate.
+
+A gate nobody can try out before pushing is a gate that gets disabled. These
+commands exist so a policy can be written, run against a scan that already
+happened, and understood without reading the source.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from vexpath.exit_codes import ExitCode
+from vexpath.output import OutputFormat, emit, emit_json, fail, fail_config, note
+from vexpath_core import policy as policy_module
+from vexpath_core.models.results import ScanResults
+
+app = typer.Typer(help="Write, test and explain the build gate.", no_args_is_help=True)
+
+
+@app.command("list")
+def list_presets(
+    output: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TABLE,
+) -> None:
+    """Show the named policies and what each one does."""
+    payload = [
+        {
+            "name": name,
+            "default": name == policy_module.DEFAULT_PRESET,
+            "description": policy_module.explain(name),
+            "expression": expression,
+        }
+        for name, expression in policy_module.PRESETS.items()
+    ]
+    if output is OutputFormat.JSON:
+        emit_json(payload)
+        return
+
+    lines: list[str] = []
+    for entry in payload:
+        marker = " (default)" if entry["default"] else ""
+        lines.append(f"{entry['name']}{marker}")
+        lines.append(f"  {entry['description']}")
+        lines.append(f"  {entry['expression']}")
+        lines.append("")
+    lines.append("An expression evaluates to true when the build must fail.")
+    emit("\n".join(lines) + "\n")
+
+
+@app.command("test")
+def test(
+    policy: Annotated[
+        str,
+        typer.Argument(help=("A preset name, a CEL expression, or a path to a file holding one.")),
+    ],
+    results_file: Annotated[
+        Path,
+        typer.Option(
+            "--scan",
+            exists=True,
+            dir_okay=False,
+            help="JSON output of a scan to evaluate the policy against.",
+        ),
+    ],
+    output: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TABLE,
+) -> None:
+    """Evaluate a policy against a scan that already ran.
+
+    Nothing is re-scanned, so this is fast and gives the same answer CI will:
+    the policy reads only what the scan concluded.
+
+    Exits 1 when the policy fails, 3 when the policy itself cannot be
+    compiled. A broken policy is never reported as a passing one.
+    """
+    source = _read_policy(policy)
+    try:
+        compiled = policy_module.compile_policy(source)
+    except policy_module.PolicyError as exc:
+        fail_config(str(exc))
+
+    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}")
+
+    try:
+        outcome = compiled.evaluate(results)
+    except policy_module.PolicyError as exc:
+        fail_config(str(exc))
+
+    if output is OutputFormat.JSON:
+        emit_json(outcome.model_dump(mode="json"))
+    else:
+        emit(_render(compiled, outcome, len(results.findings)))
+
+    if not outcome.passed:
+        raise typer.Exit(code=int(ExitCode.POLICY_FAILED))
+
+
+def _read_policy(source: str) -> str:
+    """Treat the argument as a file when it names one, else as a policy.
+
+    A preset name wins over a file of the same name, because the presets are a
+    closed vocabulary and a file called ``balanced`` sitting in a working
+    directory should not silently change what the default means.
+    """
+    if source in policy_module.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(compiled: policy_module.CompiledPolicy, outcome: object, finding_count: int) -> str:
+    from vexpath_core.models.results import PolicyResult
+
+    assert isinstance(outcome, PolicyResult)  # narrowed for the type checker
+    lines = [
+        f"policy          {compiled.name}",
+        f"expression      {compiled.expression}",
+        f"findings        {finding_count}",
+        f"result          {'PASS' if outcome.passed else 'FAIL'}",
+    ]
+    if outcome.violations:
+        lines.append("")
+        lines.append("Why it failed")
+        for violation in outcome.violations:
+            lines.append(f"  {violation.message}")
+            if violation.component:
+                lines.append(f"      {violation.component}")
+    return "\n".join(lines) + "\n"
+
+
+@app.command("explain")
+def explain(
+    policy: Annotated[str, typer.Argument(help="A preset name or a CEL expression.")],
+) -> None:
+    """Show what a policy would gate on, without running it.
+
+    Useful for checking that an expression compiles before committing it, and
+    for seeing which preset an inherited configuration actually resolved to.
+    """
+    source = _read_policy(policy)
+    try:
+        compiled = policy_module.compile_policy(source)
+    except policy_module.PolicyError as exc:
+        fail_config(str(exc))
+
+    description = policy_module.explain(compiled.name)
+    lines = [f"policy          {compiled.name}"]
+    if description:
+        lines.append(f"intent          {description}")
+    lines.append(f"expression      {compiled.expression}")
+    lines.append("")
+    lines.append("True means the build fails. Available in an expression:")
+    lines.append("  findings[]  advisory, component, purl, severity, severity_rank,")
+    lines.append("              cvss, cvss_v4, epss, kev, verdict, justification,")
+    lines.append("              fixed_in, has_fix, age_days, scope, direct, suppressed,")
+    lines.append("              reach{analysed, status, reason, confidence,")
+    lines.append("                    confidence_rank, reachable, path_length,")
+    lines.append("                    via_dynamic_edges}")
+    lines.append("  scan        mode, git_ref, git_sha, reproducible, snapshot")
+    lines.append("  project     slug")
+    lines.append("  counts      affected, not_affected, under_investigation, fixed")
+    emit("\n".join(lines) + "\n")
+    note("compiled successfully")
+
+
+__all__ = ["app"]

vexpath/commands/reach.py

@@ -0,0 +1,235 @@
+"""The ``vexpath reach`` command: explain one advisory against one project.
+
+``vexpath scan`` says what to act on. This says why, for a single advisory,
+with every piece of evidence the verdict rests on. It is the command someone
+runs when they disagree with the scan, which is exactly when a security tool
+has to be able to show its work.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from vexpath.exit_codes import ExitCode
+from vexpath.output import OutputFormat, emit, emit_json, fail
+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 Verdict
+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.triage import TriageError, triage
+
+
+def command(
+    advisory: Annotated[
+        str,
+        typer.Option(
+            "--advisory",
+            "-a",
+            help="The advisory to explain. Any of its identifiers works.",
+        ),
+    ],
+    path: Annotated[
+        Path,
+        typer.Argument(exists=True, file_okay=False, help="Project directory to analyse."),
+    ] = Path(),
+    symbol: Annotated[
+        str | None,
+        typer.Option(
+            "--symbol",
+            "-s",
+            help=(
+                "Comma-separated symbols to search for in addition to the "
+                "advisory's own, as module.path:function or a dotted name. "
+                "Useful when an advisory carries no fix commit. Recorded as "
+                "manually supplied, which caps the report's confidence."
+            ),
+        ),
+    ] = None,
+    snapshot: Annotated[
+        Path | None,
+        typer.Option(
+            "--snapshot",
+            exists=True,
+            file_okay=False,
+            help=(f"Read advisories from this local snapshot. Defaults to ${SNAPSHOT_ENV}."),
+        ),
+    ] = None,
+    entry_point: Annotated[
+        str | None,
+        typer.Option(
+            "--entry-point",
+            "-e",
+            help=(
+                "Comma-separated entry points to start 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,
+    lockfile: Annotated[
+        Path | None,
+        typer.Option(
+            "--lockfile",
+            exists=True,
+            dir_okay=False,
+            help="Use this lockfile instead of searching the directory.",
+        ),
+    ] = 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 them."),
+    ] = False,
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TABLE,
+) -> None:
+    """Explain one advisory's reachability verdict for this project.
+
+    Prints the symbols searched for and where they came from, which of them
+    exist in the installed version, which entry points reach them with the
+    call path for each, and the graph the answer rests on.
+    """
+    source = advisory_source(snapshot, result_noun="explanation")
+    options = ScanOptions(
+        lockfile=lockfile,
+        entry_points=_split(entry_point),
+        environment=environment,
+        use_cache=not no_cache,
+        download_missing=download_missing,
+    )
+
+    try:
+        result = triage(
+            path,
+            advisory,
+            source,
+            options=options,
+            extra_symbols=_split(symbol),
+        )
+    except TriageError as exc:
+        fail(str(exc))
+    except (LockfileError, UnknownSbomFormatError, CycloneDxError, SpdxError) as exc:
+        fail(str(exc))
+    except AdvisorySourceError as exc:
+        fail(
+            f"{exc}. To work without network access, download a snapshot with "
+            f"'vexpath advisory sync' and pass --snapshot."
+        )
+    finally:
+        close_source(source)
+
+    if output_format is OutputFormat.JSON:
+        emit_json(_payload(result))
+    else:
+        emit(report.render_triage(result))
+
+    # A reachable verdict is the one a caller may want to act on, so it is
+    # distinguishable without parsing the output. An admitted unknown is not an
+    # analysis failure, so it stays at zero.
+    if result.verdict is Verdict.AFFECTED:
+        raise typer.Exit(code=int(ExitCode.POLICY_FAILED))
+
+
+def _split(raw: str | None) -> tuple[str, ...]:
+    return tuple(entry.strip() for entry in (raw or "").split(",") if entry.strip())
+
+
+def _payload(result: object) -> dict[str, object]:
+    """Serialise a triage report.
+
+    Written out by hand rather than dumped from the dataclass, because this is
+    a contract with whatever consumes it and should not change shape every time
+    an internal field is renamed.
+    """
+    from vexpath_core.triage import TriageReport
+
+    assert isinstance(result, TriageReport)  # narrowed for the type checker
+    reach = result.reach
+    return {
+        "advisory": {
+            "id": result.advisory_id,
+            "summary": result.summary,
+            "severity": result.severity.value,
+            "aliases": list(result.aliases),
+        },
+        "component": {
+            "purl": result.component.purl,
+            "ecosystem": result.component.ecosystem,
+            "name": result.component.name,
+            "version": result.component.version,
+            "direct": result.component.direct,
+        },
+        "version_affected": result.version_affected,
+        "verdict": result.verdict.value,
+        "advisory_snapshot_id": result.snapshot_id,
+        "reproducible": result.is_reproducible,
+        "reach": reach.model_dump(mode="json") if reach is not None else None,
+        "symbols": [
+            {
+                "symbol": probe.symbol,
+                "kind": probe.kind.value,
+                "source": probe.source.value,
+                "confidence": probe.confidence.value,
+                "defined": probe.defined,
+                "referenced": probe.referenced,
+                "status": probe.status,
+            }
+            for probe in result.symbols
+        ],
+        "entry_points": {
+            "source": result.entry_point_source.value,
+            "count": result.entry_point_count,
+            "examined": [
+                {
+                    "entry_point": entry.entry_point,
+                    "status": entry.status,
+                    "symbol": entry.symbol,
+                    "path": [
+                        {
+                            "symbol": step.symbol,
+                            "file": step.file,
+                            "line": step.line,
+                            "edge_kind": step.edge_kind.value,
+                        }
+                        for step in entry.path
+                    ],
+                }
+                for entry in result.entry_points
+            ],
+        },
+        "graph": result.graph.model_dump(mode="json") if result.graph is not None else None,
+        "notes": list(result.notes),
+    }
+
+
+__all__ = ["command"]