rapidfort/gh-action-security-audit
GitHub: rapidfort/gh-action-security-audit
针对 GitHub 组织的 Actions 工作流安全审计工具，可扫描 pull_request_target 滥用、权限配置不当等高风险模式并生成修复建议报告。
Stars: 2 | Forks: 0
# gh-actions-audit
一款针对整个 GitHub 组织的 GitHub Actions 工作流安全审计工具。
## 为什么开发此工具
2026 年 2 月，[hackerbot-claw](https://www.stepsecurity.io/blog/hacking-millions-of-repos-with-github-actions) 攻击活动演示了对配置错误的 GitHub Actions 工作流的大规模利用。该攻击利用了五个向量：
1. **Pwn requests** — 使用 `pull_request_target` 的工作流检出并执行 fork 代码，使攻击者能够利用目标仓库的 secrets 和写入 token 进行 RCE
2. **无防护的 `issue_comment` 触发器** — 任何 GitHub 用户都可以通过在公开仓库的 issue 下评论来调用的工作流
3. **Shell 注入** — 直接插入到 `run:` 块中的 `${{ github.event.* }}` 表达式（分支名称、PR 标题、提交消息）
4. **文件名注入** — 在 CI 的 bash 循环中处理的、文件名包含 base64 编码命令的文件
5. **AI 提示注入** — 在 `pull_request_target` 检出期间由 AI 编程代理执行的中毒配置文件（例如 `CLAUDE.md`）
此工具扫描组织的工作流以查找这些模式，并生成一份报告，重点标出需要审查的内容。
## 检查内容
### 按仓库
- 工作流是否有显式的 `permissions:` 块（没有该块的工作流会继承组织默认设置，可能是 `write`）
- `pull_request_target` 使用情况，按风险细分为：
- **仅 API** — 无检出，用于标记/自动合并（低风险）
- **检出，有防护** — 检出 fork 代码但限制了作者（例如 `dependabot[bot]`）
- **检出+执行，无防护** — 检出并运行 fork 代码且无限制（最高风险）
- `issue_comment` 触发器，注明是否存在 `author_association` 或 actor 检查
- 仓库级 secret 名称（而非值）
- Dependabot 误报标记 — 限制为 `dependabot[bot]` 的工作流会被标记，以便审查者跳过它们
### 组织级别
- 默认工作流 token 权限（`read` vs `write`）
- 工作流是否可以批准 pull request
- 允许的 actions 策略（所有、已验证的创建者或选定的）
- 所有带有可见性范围的组织 secrets，配置了访问权限的仓库，以及在其工作流文件中实际引用每个 secret 的仓库
- 对于范围过大的 secrets（`All repositories` 可见性）：提供一个可直接运行的 `gh secret set` 命令，将其限制为仅实际使用它们的仓库
## 系统要求
- [GitHub CLI (`gh`)](https://cli.github.com/) 已通过目标组织的 **admin** 身份认证
- `bash` (4.0+)、`python3`（用于 JSON 解析）、标准 Unix 工具（`grep`、`find`、`sort` 等）
- 所需管理员权限范围：`admin:org`（用于组织设置和 secrets）、repo 管理员访问权限（用于仓库 secrets）
验证你的访问权限：
```
gh auth status
gh api orgs//actions/permissions
```
## 用法
```
./gh-actions-audit.sh [OPTIONS]
```
### 选项
| 标志 | 描述 |
|------|-------------|
| `--out FILE` | Markdown 报告输出路径。默认值：`./-actions-audit.md` |
| `--csv FILE` | CSV 报告输出路径。省略则跳过 CSV 生成。 |
| `--local DIR` | 重用先前下载的工作流文件，而非重新从 API 获取。接受顶层审计目录或其 `workflows/` 子目录。 |
| `--cleanup` | 运行完成后删除缓存的工作流文件。 |
| `-h, --help` | 显示内置帮助信息并退出。 |
### 示例
```
# 完整扫描 — 下载所有 workflows，写入 markdown 报告
./gh-actions-audit.sh my-org
# 同时输出 markdown 和 CSV
./gh-actions-audit.sh my-org --out audit.md --csv audit.csv
# 复用之前的下载（可节省大型 orgs 的时间）
./gh-actions-audit.sh my-org --local /tmp/gh-actions-audit-my-org-20260301
# 扫描并清理缓存的文件
./gh-actions-audit.sh my-org --cleanup
```
### 工作原理
1. **下载** — 枚举组织中所有未归档的仓库，通过 GitHub API 下载 `.github/workflows/*.yml` 文件（使用 `--local` 时跳过）
2. **分析** — 使用基于 grep 的启发式方法扫描每个工作流的 `pull_request_target`、`issue_comment`、`permissions:` 块和 secret 引用
3. **组织 secrets** — 列出所有组织级别的 secrets，将每个 secret 映射到在工作流中引用它的仓库，并为范围过大的访问权限生成修复命令
4. **组织设置** — 检查默认工作流权限、PR 批准策略和允许的 actions
5. **报告** — 生成 markdown 报告（以及可选的 CSV），包含按仓库分类的表格、组织级别的发现和审查指南
对于大型组织（数百个仓库），初始下载可能需要几分钟。`--local` 标志允许你重新运行分析而无需重新下载。
## 输出
Markdown 报告包括：
- **组织级别设置** 表格，包含当前值和建议
- **按仓库审计** 表格，包含权限、`pull_request_target` 分类、`issue_comment` 触发器和仓库 secrets 列
- **组织级别 Secrets** 表格，显示可见性、配置的访问权限、实际工作流使用情况以及 `gh secret set` 修复命令
- **审查指南** 部分，解释优先事项、fork 批准设置能防护和不能防护的内容，以及需要寻找的缓解措施
## 许可证
Apache-2.0
标签：CI/CD 安全, DevSecOps, GitHub Actions, GITHUB_TOKEN, pull_request_target, RCE 风险, Shell 注入, 上游代理, 工作流安全, 应用安全, 数据投毒防御, 文档安全, 权限审查, 自动笔记