iDogRoag/gha-bom

# gha-bom -> gha-bom [](https://github.com/iDogRoag/gha-bom/actions/workflows/ci.yml) [](https://www.npmjs.com/package/gha-bom) [](https://www.npmjs.com/package/gha-bom) [](LICENSE) [](package.json) 为您的GitHub Actions工作流程提供SBOM。 为您的GitHub Actions工作流程生成离线物料清单。  gha-bom显示了您的CI/CD所依赖的每个操作、权限、秘密引用、触发器、运行者、工件、缓存和发布路径。它还比较报告，以便拉取请求可以显示您的流程攻击表面中确切发生了什么变化。 快速入门： ``` npx gha-bom scan . ``` 演示： ``` npx gha-bom demo ``` ``` gha-bom Risk score 42 out of 100 Workflows scanned 1 Third party actions 1 Unpinned third party actions 1 Secrets referenced 1 Write permission jobs 1 High findings 5 Top risks pull_request_target with write-all Secret passed to unpinned third party action Self-hosted runner used on pull_request_target Release path uses mutable action ref Workflow publishes packages with broad permissions ``` ``` npx gha-bom demo --format html --output gha-bom-demo.html ``` 预览演示输出： - 终端输出：[docs/assets/demo-output.txt](docs/assets/demo-output.txt) - Markdown报告：[docs/assets/demo-output.md](docs/assets/demo-output.md) - HTML报告：[docs/assets/demo-report.html](docs/assets/demo-report.html) 更多适合截图的示例： - [风险报告示例](docs/sample-report.md) - [攻击表面差异示例](docs/sample-diff.md) - [HTML报告示例](docs/sample-report.html) ## 什么是gha-bom gha-bom显示了您的GitHub Actions工作流程所依赖的、可以访问的以及发生变化的。 它不仅仅是一个安全扫描器。它是您供应链CI/CD层的本地工作流程清单、风险图和差异工具。 ## 为什么存在这个 SBOM通常涵盖应用程序依赖项，但不涵盖构建和发布它们的流程。GitHub Actions工作流程可以拉取第三方操作、创建OIDC令牌、发布包、上传工件、使用自托管运行者以及接收秘密或`GITHUB_TOKEN`访问权限。 gha-bom帮助团队在它悄然变化之前查看和审查该工作流程攻击表面。 ## 快速入门 ``` npx gha-bom scan . ``` 对于简短别名： ``` npx gha-bom scan . gbom scan . ``` ## 演示 演示在您有存储库扫描之前就可以工作。 ``` npx gha-bom demo npx gha-bom demo --format markdown npx gha-bom demo --format json npx gha-bom demo --format html --output gha-bom-demo.html npx gha-bom demo --badge ``` ## 示例输出 ``` gha-bom Status fail Risk score 0 out of 100 (critical risk) Workflows 1 workflows, 1 jobs Actions 2 total, 1 third party, 1 unpinned third party Access 1 secrets, 1 jobs with write permissions, 1 release paths Findings 12 high, 4 medium, 10 low Top risks - [high] Workflow uses write-all permissions - [high] pull_request_target has write permissions - [high] Secret passed to unpinned third-party action - [high] Self-hosted runner used on pull request trigger - [high] Release path uses unpinned third-party action Showing top 5 findings. Use --show-workflows or --format markdown for details. ``` ## 它检测的内容 - 工作流程触发器、权限、作业、步骤和运行者 - 操作引用、所有者、refs、ref类型和可变refs - 本地操作和本地可重用工作流程 - 远程可重用工作流程和`secrets: inherit` - 秘密引用和类似秘密的env键 - `GITHUB_TOKEN`和通过权限隐式令牌暴露 - OIDC权限和常见云认证操作 - 工件上传/下载路径 - 缓存键和缓存路径 - 包、容器、GitHub发布、Pages和部署路径 - 具有严重性和置信度的风险模式 ## 差异模式 ``` gha-bom scan . --format json --output current.json gha-bom diff .gha-bom/baseline.json current.json --format markdown ``` 差异模式检测新工作流程、作业、操作、更改的refs、未固定操作更改、新的秘密引用、扩大的权限、新的`pull_request_target`触发器、自托管运行者、OIDC使用、发布路径、工件路径、缓存路径、分数变化和新高发现。 ## 解释模式 ``` gha-bom explain .github/workflows/release.yml gha-bom explain .github/workflows/ci.yml --format markdown ``` 解释模式将报告集中在单个工作流程上，以便更容易审查或在一个问题中共享。 ## GitHub Actions使用 为了可读性，此示例使用主要标签。为了最强的可重现性，将第三方操作固定到完整的提交SHA。 ``` name: gha-bom on: pull_request: push: branches: - main permissions: contents: read jobs: gha-bom: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: actions/setup-node@v6 with: node-version: 24.x - run: npx gha-bom scan . --ci --format markdown --output gha-bom-report.md --fail-on high - uses: actions/upload-artifact@v5 if: always() with: name: gha-bom-report path: gha-bom-report.md ``` ## gha-bom的不同之处 zizmor是一个GitHub Actions安全lint。 abom映射递归操作依赖项和已知受损操作。 gha-bom是本地工作流程清单和攻击表面差异工具。 将它们一起使用。 ## 安装 gha-bom需要Node.js 24。 ``` npm install -g gha-bom gha-bom scan . ``` 本地开发： ``` npm install npm test npm run build node dist/cli.js demo ``` ## 配置 创建一个启动配置： ``` gha-bom init ``` gha-bom查找`gha-bom.yml`、`gha-bom.yaml`、`.gha-bom.yml`或`.gha-bom.yaml`。 ``` version: 1 minScore: 80 failOn: - high include: - ".github/workflows/*.{yml,yaml}" exclude: [] risk: allowPullRequestTarget: false requireExplicitPermissions: true requireShaPinnedThirdPartyActions: true allowSecretsInPullRequestTarget: false allowWriteAll: false allowSecretsInThirdPartyActions: false ``` ## 报告格式 - `table`：紧凑的终端输出 - `json`：稳定的机器可读模式 - `markdown`：PR评论就绪的报告 - `html`：包含无外部资源的单个自包含报告 gha-bom可以使用`--badge`打印徽章Markdown，但v1版本不托管徽章。 ``` gha-bom scan . --badge ``` ## 风险分数 风险分数从100开始，并减去具有风险模式的启发式惩罚，例如具有写入权限的`pull_request_target`、`write-all`、秘密流向未固定的第三方操作、在拉取请求触发器上的自托管运行者、具有`secrets: inherit`的远程可重用工作流程、具有可变第三方操作的发布路径、广泛的工件路径和不需要的OIDC权限。 该分数是一个优先级辅助工具，不是工作流程安全的证明。 ## 安全模型 gha-bom是静态离线分析。 默认扫描、演示、解释、差异和报告生成默认不调用GitHub API，不进行网络调用，不使用咨询数据库，不发送遥测数据，也不调用AI服务。 gha-bom命令默认不调用GitHub API。 gha-bom在引用时读取工作流程YAML、可选的gha-bom配置文件和`.github/actions`下的本地复合操作元数据。它记录在工作流程文件中可见的秘密名称，永远不会记录秘密值。 ## 局限性 gha-bom不能证明工作流程是安全的。它不能验证操作是否恶意，验证GitHub所有者身份，验证远程ref是否真的是分支或标签，验证秘密是否存在于存储库设置中，或查询分支保护、规则集、环境保护或操作允许策略。 它补充了zizmor、abom和GitHub安全功能等工具。它不能替代它们。 ## 路线图 - 递归远程操作元数据解析 - 可选的GitHub API丰富 - 已知受损操作咨询检查 - CycloneDX输出 - SPDX输出 - SARIF输出 - PR评论模式 - GitHub App - 组织范围扫描 - 基准管理 - 徽章托管 - 与zizmor和abom输出的集成 - 单一仓库工作流程图 - VS Code扩展 ## 贡献 查看[CONTRIBUTING.md](CONTRIBUTING.md). ### 适合初学者的贡献 - 添加更多工作流程风险模式。 - 改进报告格式。 - 添加更多测试固定装置。 - 改进操作引用解析。 - 添加新的发布路径检测器。 - 从真实工作流程添加文档示例。 ## 许可证 MIT

标签：Attack Surface, Bill of Materials, Cilium, Code Analysis, Dependency Management, Diff Tool, GitHub Actions, GNU通用公共许可证, MITM代理, Node.js, NPM, Offline Analysis, Pull Request Security, Risk Assessment, SBOM, Secrets Management, Security Tools, Third-Party Libraries, Workflow Monitoring, 日志审计, 硬件无关, 自动化攻击, 自动笔记