vexcalibur-dev/vexcalibur

# Vexcalibur  [](https://github.com/vexcalibur-dev/vexcalibur/actions/workflows/ci.yml) [](https://github.com/vexcalibur-dev/vexcalibur/actions/workflows/codeql.yml) [](https://github.com/vexcalibur-dev/vexcalibur/actions/workflows/scorecard.yml) [](https://github.com/vexcalibur-dev/vexcalibur/actions/workflows/dependency-review.yml) Vexcalibur 将软件物料清单和漏洞检测结果转化为 VEX 文档。它可以读取 CycloneDX SBOM 或 GitHub Dependency Graph SBOM。检测结果来源于兼容 OSV 的服务或本地文件。 0.3.0 版本输出 CycloneDX 1.6、OpenVEX 0.2.0 和 CSAF 2.0 JSON。CSAF 输出使用 `csaf_vex` profile。 该项目已可使用，但仍处于 1.0 版本之前。请固定使用确切的发布版本，因为命令 flags、Python API 和详细输出可能会发生变更。 ## 目前可用的功能 | 领域 | 支持 | | --- | --- | | SBOM 输入 | CycloneDX JSON 和 XML 1.4–1.6；GitHub Dependency Graph SPDX 2.3 JSON | | 检测结果来源 | 需明确同意的公共 OSV；兼容 OSV 的私有 endpoint；本地检测结果文件 | | VEX 输出 | CycloneDX 1.6 JSON；OpenVEX 0.2.0 JSON；使用 `csaf_vex` profile 的 CSAF 2.0 JSON | | 自动化 | 配套的 [GitHub Action](https://github.com/vexcalibur-dev/vexcalibur-action) | | 迁移 | 小范围的 `vexy` 命令行兼容层 | | Python | 3.10–3.14 | ## 安装发布版本 创建环境并固定 package 版本： ``` python -m venv .venv .venv/bin/python -m pip install "vexcalibur==0.3.0" .venv/bin/vexcalibur --help ``` 在 Windows 上，请使用 `.venv\Scripts\python` 和 `.venv\Scripts\vexcalibur`。 ## 尝试本地生成 克隆仓库，然后安装其锁定的依赖： ``` uv sync ``` 安装依赖时可能会联系配置的 package index。下面的生成命令仅使用本地输入，不会联系漏洞服务。 根据已提交的示例文件生成 VEX 文档： ``` uv run --frozen vexcalibur generate \ tests/fixtures/sbom/cyclonedx-json-simple.json \ --offline \ --findings-file tests/fixtures/findings/all-analysis-states.json \ --timestamp 2026-06-23T00:00:00Z \ --output /tmp/vexcalibur-vex.json ``` 检查结果： ``` python - <<'PY' import json from pathlib import Path vex = json.loads(Path("/tmp/vexcalibur-vex.json").read_text()) assert vex["bomFormat"] == "CycloneDX" assert vex["specVersion"] == "1.6" assert len(vex["vulnerabilities"]) == 5 print("generated CycloneDX VEX") PY ``` 有关此示例的引导式操作，请参阅[快速入门](https://vexcalibur-dev.github.io/vexcalibur/tutorials/quickstart.html)。 CycloneDX 仍是默认输出格式。添加 `--format openvex` 并指定 文档作者以创建 OpenVEX。添加 `--format csaf` 以及必需的 文档和发布者元数据，以创建 CSAF 2.0 VEX 文档。请按照 [OpenVEX 指南](https://vexcalibur-dev.github.io/vexcalibur/how-to/generate-openvex.html) 或 [CSAF 指南](https://vexcalibur-dev.github.io/vexcalibur/how-to/generate-csaf.html) 获取可运行的示例以及该格式的证据规则。 ## 选择检测结果来源 Vexcalibur 在每次生成运行时需要一个检测结果来源。 | 资产清单与信任边界 | 用法 | | --- | --- | | 检测结果已存在于本地 | 使用 `--findings-file findings.json`。为本地 SBOM 添加 `--offline`。 | | 资产清单可能会发送至内部服务 | `--osv-url https://osv.internal.example` | | 资产清单已获批准使用公共 OSV | `--allow-public-osv` | 如果没有该 flag，默认的公共 endpoint 将会安全关闭。从 GitHub 获取 SBOM 属于独立的网络边界，并不代表允许将生成的资产清单发送至公共 OSV。 ## 文档 - 从[快速入门](https://vexcalibur-dev.github.io/vexcalibur/tutorials/quickstart.html)开始。 - 按照 [CycloneDX](https://vexcalibur-dev.github.io/vexcalibur/how-to/generate-cyclonedx-vex.html)、[OpenVEX](https://vexcalibur-dev.github.io/vexcalibur/how-to/generate-openvex.html) 或 [CSAF](https://vexcalibur-dev.github.io/vexcalibur/how-to/generate-csaf.html) 生成指南操作。 - 使用 [CLI 参考](https://vexcalibur-dev.github.io/vexcalibur/reference/cli.html)了解 flags 和失败行为。 - 在使用生成的文件之前，请阅读 [CycloneDX](https://vexcalibur-dev.github.io/vexcalibur/reference/cyclonedx-vex-output.html)、[OpenVEX](https://vexcalibur-dev.github.io/vexcalibur/reference/openvex-output.html) 或 [CSAF](https://vexcalibur-dev.github.io/vexcalibur/reference/csaf-output.html) 输出契约。 - 在添加数据源或输出格式之前，请阅读[架构文档](https://vexcalibur-dev.github.io/vexcalibur/explanation/architecture.html)。 - 查看[项目状态](https://vexcalibur-dev.github.io/vexcalibur/explanation/project-status.html)以了解当前的限制。 完整手册位于 [vexcalibur-dev.github.io/vexcalibur][vexcalibur-docs]。

标签：DevSecOps, GPT, Python, SBOM, VEX, 上游代理, 无后门, 漏洞管理, 硬件无关, 逆向工具