vexcalibur-dev/vexcalibur-orb
GitHub: vexcalibur-dev/vexcalibur-orb
该项目是一个 CircleCI Orb 插件，用于在 CI 流水线中运行 Vexcalibur，实现基于 SBOM 的 VEX 文档自动生成与 OSV 漏洞查询。
Stars: 0 | Forks: 0
# Vexcalibur CircleCI orb
[](https://github.com/vexcalibur-dev/vexcalibur-orb/actions/workflows/ci.yml)
Vexcalibur orb 在 CircleCI pipeline 中运行 [Vexcalibur](https://github.com/vexcalibur-dev/vexcalibur)。它为 CircleCI 用户提供了可重用的 job、command 和 Python executor，用于 Vulnerability Exploitability eXchange (VEX) 工作流。
该 orb 在每次调用时，会将特定的 Vexcalibur 发行版安装到一个临时的虚拟环境中。它可以运行任何 Vexcalibur 命令。常见用途包括根据软件物料清单 (SBOM) 生成 VEX 文档，以及查询开源漏洞 (OSV) 服务。
## 项目状态
该 orb 尚未发布到 CircleCI registry。此仓库中的配置示例预览了预期的首个发行版。在该发行版存在之前，无法解析 `vexcalibur-dev/vexcalibur@0.1.0`。
[Issue #1](https://github.com/vexcalibur-dev/vexcalibur-orb/issues/1) 跟踪了剩余的账号和发布设置。
公开发布的版本将是一个社区 orb。CircleCI 组织管理员必须先[允许使用未认证的 orb](https://circleci.com/docs/orbs/use/orb-intro/#orb-designation)，然后该组织才能导入它。
源码目前具有以下默认值：
| 接口 | 默认值 |
| --- | --- |
| Vexcalibur package | `vexcalibur==0.3.0` |
| Python image | `cimg/python:3.14` |
| 在可重用 job 中 checkout 仓库 | 启用 |
| 公共 OSV 访问 | 除非调用方传递 `--allow-public-osv`，否则禁用 |
如需目前可用的 Vexcalibur 集成，请参见 [Vexcalibur GitHub Action](https://github.com/vexcalibur-dev/vexcalibur-action)。
## 预览 orb 接口
在首次发布到 registry 后，此工作流将安装默认的 Vexcalibur package 并打印其命令帮助信息：
```
version: 2.1
orbs:
vexcalibur: vexcalibur-dev/vexcalibur@0.1.0
workflows:
inspect-vexcalibur:
jobs:
- vexcalibur/run:
checkout: false
args: --help
```
当 Vexcalibur 安装并退出且状态为 `0` 时，job 即为成功。
该 orb 还包含四个工作流模板：
- [根据 SBOM 生成并保留 CycloneDX VEX](src/examples/generate_vex_from_sbom.yml)
- [根据本地发现生成并保留 OpenVEX](src/examples/generate_openvex.yml)
- [根据本地发现生成并保留 CSAF 2.0 VEX](src/examples/generate_csaf.yml)
- [使用已批准的 package 清单查询公共 OSV](src/examples/query_public_osv.yml)
`args` 中的每个非空行都会成为一个命令行参数。请将标志及其值写在不同行中。该 orb 不会按空格拆分行，也不会将其作为 shell 代码进行评估。
除非命令包含 `--allow-public-osv`，否则 Vexcalibur 会拒绝将 package URL、版本或 SBOM 清单发送到公共 OSV。仅当允许工作流与 `https://api.osv.dev` 共享这些值时，才使用该标志。
所有三个生成示例都传递了 `--offline`，因此 Vexcalibur 会读取已 checkout 的 SBOM 和本地发现，而不是查询 OSV。该 orb 仍会在运行时从 pip 安装 Vexcalibur。每个示例都将生成的文档存储为 artifact。OpenVEX 发现必须至少产生一个有效的声明。
当 `--output` 指定一个 CSAF 文件时，Vexcalibur 会将其 basename 与文档跟踪 ID 绑定。该示例使用 `EXAMPLE-CSAF-VEX-2026-001`，因此它会写入 `artifacts/example-csaf-vex-2026-001.json`。CSAF 支持仅用于输出；该 orb 不添加 CSAF 输入、转换、签名或发布功能。
## 开发 orb
您需要 Bash、Git、带有 `pip` 和 `venv` 的 Python 3.10 或更高版本、ShellCheck 以及 [CircleCI CLI](https://circleci.com/docs/guides/toolkit/local-cli/)。请从仓库根目录运行以下命令：
```
python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txt
bash -n scripts/*.sh
bash -n src/scripts/*.sh
shellcheck scripts/*.sh
shellcheck src/scripts/*.sh
git ls-files -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline --
python -m unittest discover -s tests
scripts/validate-circleci.sh
```
各项检查应以状态 `0` 退出。最后一条命令会打包 orb 并验证打包后的 orb、设置配置以及 continuation 配置。
## 文档
- [Orb 接口参考](docs/reference/orb.md) 描述了每个公开参数以及 runner 的失败行为。
- [运行时与信任边界](docs/explanation/runtime-and-trust.md) 说明了安装隔离、网络访问和凭据处理。
- [发布 orb](docs/how-to/publish-orb.md) 涵盖了维护者设置、开发发布、正式发布和恢复。
- [贡献](CONTRIBUTING.md) 说明了源码布局和 pull request 检查。
- [安全政策](SECURITY.md) 说明了私有漏洞报告和 secret 处理。
- [行为准则](https://github.com/vexcalibur-dev/.github/blob/main/CODE_OF_CONDUCT.md) 设定了参与预期。
- [Apache-2.0 license](LICENSE) 包含项目 license。
请使用 [GitHub issues](https://github.com/vexcalibur-dev/vexcalibur-orb/issues) 提问和反馈非敏感缺陷。请通过安全政策中的私密渠道报告漏洞。
标签：CircleCI, DevSecOps, SBOM, VEX, 上游代理, 应用安全, 开源漏洞管理, 硬件无关, 逆向工具