Generate an execution report from Python

Use the report-aware Python API when an embedding needs the same versioned summary on Windows, Linux, or macOS. The Python API constructs and validates the report, but your application owns file publication.

Prepare the checkout

The checked-in example uses local test fixtures and makes no network requests. Run it from the repository root after installing the locked environment:

uv sync --frozen

The example imports only from vexcalibur.api. It handles SBOM, findings, rendering, package-metadata, and report-parse failures separately.

#!/usr/bin/env python3
"""Generate matching VEX and execution-report bytes with the Python API."""

import argparse
import os
from pathlib import Path

from vexcalibur.api import (
    GenerationExecutionReportParseError,
    GenerationReportMetadataError,
    LocalFindingsError,
    SbomError,
    VexRenderError,
    generate_vex_from_local_findings_result,
    parse_generation_execution_report,
)


def _write_new_file_exclusively(path: Path, content: bytes) -> None:
    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
    flags |= getattr(os, "O_BINARY", 0)
    flags |= getattr(os, "O_CLOEXEC", 0)
    flags |= getattr(os, "O_NOFOLLOW", 0)
    descriptor = os.open(path, flags, 0o600)
    try:
        if os.name != "nt":
            os.fchmod(descriptor, 0o600)
        with os.fdopen(descriptor, "wb", closefd=False) as stream:
            stream.write(content)
            stream.flush()
            os.fsync(stream.fileno())
    finally:
        os.close(descriptor)


def main(output_directory: Path) -> None:
    try:
        result = generate_vex_from_local_findings_result(
            input_file=Path("tests/fixtures/sbom/cyclonedx-json-simple.json"),
            findings_file=Path("tests/fixtures/findings/all-analysis-states.json"),
        )
    except GenerationReportMetadataError as exc:
        raise SystemExit(f"package metadata cannot identify the report: {exc}") from exc
    except (SbomError, LocalFindingsError, VexRenderError) as exc:
        raise SystemExit(f"generation failed: {exc}") from exc

    try:
        report = result.execution_report()
        serialized_report = report.to_json()
        if parse_generation_execution_report(serialized_report) != report:
            raise SystemExit("execution report did not round-trip through its parser")
    except GenerationReportMetadataError as exc:
        raise SystemExit(f"package metadata cannot identify the report: {exc}") from exc
    except GenerationExecutionReportParseError as exc:
        raise SystemExit(f"generated execution report is invalid: {exc}") from exc
    except ValueError as exc:
        raise SystemExit(f"generation facts cannot produce a report: {exc}") from exc

    if not output_directory.parent.is_dir():
        raise SystemExit("output parent directory must already exist")
    output_directory.mkdir(mode=0o700)
    if os.name != "nt":
        output_directory.chmod(0o700)
    document_path = output_directory / "vex.json"
    report_path = output_directory / "execution-report.json"
    _write_new_file_exclusively(document_path, result.rendered_bytes)
    _write_new_file_exclusively(
        report_path,
        serialized_report.encode("utf-8"),
    )
    print(f"wrote {document_path} and {report_path}")


def _output_directory() -> Path:
    parser = argparse.ArgumentParser()
    parser.add_argument("output_directory", type=Path)
    return parser.parse_args().output_directory


if __name__ == "__main__":
    main(_output_directory())

Generate and validate both files

Choose a new child of the repository root so the parent already exists. The example refuses to replace the directory or either output file.

On POSIX, the example creates the directory with mode 0700 and each file with mode 0600. On Windows, Python inherits access control lists (ACLs) from the parent; the example does not make an existing parent private. Run it only from a directory whose ACL already restricts access to the intended user.

The two final-path writes are independent and are not atomic. A write or fsync failure can leave a partial VEX file or execution report. Use the CLI instead when a POSIX embedding needs coordinated publication.

Run this one-line command from Bash or PowerShell:

uv run --frozen python docs/examples/generate_execution_report.py vexcalibur-python-report

A successful run prints both paths:

wrote vexcalibur-python-report/vex.json and vexcalibur-python-report/execution-report.json

The example parses the serialized report through parse_generation_execution_report() before either file is written. A parse failure stops the run.

Use result.rendered_bytes for the VEX file and serialize the report from the same GenerationResult. Don’t render again or calculate counts from the VEX document; either step can make the report describe different bytes.

Handle publication in the embedding

The example uses exclusive creation and refuses to replace existing paths. On Windows, privacy depends on the parent ACL described above. On every platform, a failed direct write can leave a partial file, and a report failure can leave the VEX file behind.

Applications that need coordinated replacement on Linux or macOS should invoke the CLI with --execution-report. The CLI publishes VEX first and the report last under its destination locks. The supported Python facade does not expose that filesystem transaction.

Catch GenerationReportMetadataError when installed package metadata cannot identify the loaded code. Catch GenerationExecutionReportParseError when validating report bytes received from another process. The Python API reference lists the complete report types and failure contracts; the execution report reference defines the JSON fields and security boundary.