Vigilant-LLC/runner-guard

# Runner Guard [](LICENSE) [](https://github.com/Vigilant-LLC/runner-guard/releases) [](https://go.dev) **CI/CD 供应链安全扫描器，用于 GitHub Actions** Runner Guard 检测流水线注入漏洞、未固定供应链依赖、AI 配置中毒以及 GitHub Actions 工作流中的隐形隐写负载。它会检查您已安装的软件包是否存在已知受损版本，并行扫描多个仓库，并自动修复发现的问题。 ``` ┌───────────────────────────┐ │ Workflow YAML / Repos │ │ Lock files / Remote URL │ └─────────────┬─────────────┘ │ ┌─────────────┬───────┼───────┬─────────────┐ ▼ ▼ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Workflow │ │ check │ │ audit │ │ Batch │ │ Scan │ │ -deps │ │ -deps │ │ Scan │ │ │ │ │ │ │ │ │ │ Taint │ │ Lock │ │ Resolve │ │ Multi- │ │ Perms │ │ files │ │ deps to │ │ repo │ │ IOCs │ │ Known │ │ repos │ │ Parallel │ │ │ │ bad vers │ │ Scan CI │ │ Scoring │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ └────────────┴─────┬──────┴────────────┘ ▼ ┌───────────────────────────┐ │ Runner Guard Score │ │ 0-100 / Letter grade │ │ Pinning / Permissions / │ │ Injection / Triggers / │ │ IOCs │ └─────────────┬─────────────┘ │ ┌─────────────┬───────┼───────┬─────────────┐ ▼ ▼ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Report │ │ Auto-Fix │ │ CI Gate │ │ Alerts │ │ │ │ │ │ │ │(optional)│ │ Console │ │ Pin to │ │ Pass / │ │ Slack │ │ JSON │ │ SHAs │ │ Fail │ │ PagerDuty│ │ SARIF │ │ Extract │ │ SARIF │ │ Webhook │ │ CSV │ │ envs │ │ upload │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ``` ## 安装 ``` # Homebrew (macOS/Linux) brew install Vigilant-LLC/tap/runner-guard # Docker docker pull ghcr.io/vigilant-llc/runner-guard:latest # One-liner (macOS/Linux) curl -sSfL https://raw.githubusercontent.com/Vigilant-LLC/runner-guard/main/install.sh | bash # 从源代码编译 go install github.com/Vigilant-LLC/runner-guard/v3/cmd/runner-guard@latest ``` 适用于 Linux、macOS 和 Windows（amd64/arm64）的预构建二进制文件位于 [发布页面](https://github.com/Vigilant-LLC/runner-guard/releases)。 ## 功能特性 - **18 条检测规则**：涵盖 Fork 检出漏洞、表达式注入、密钥外泄、未固定操作、AI 配置注入以及供应链隐写术（带权限感知严重级别） - **41 个受损软件包版本**：涉及 13 次已确认的供应链攻击活动（UNC1069/Axios、TeamPCP、npm debug/chalk、Solana web3.js 等） - **39 个威胁特征签名**：覆盖 7 个攻击文件——GlassWorm、TeamPCP、UNC1069/Axios、Telnyx、prt-scan 以及通用供应链 IOC - **上游流水线审计**：`audit-deps` 将依赖项解析到源仓库，并扫描每个仓库的 CI/CD 流水线，回答“我的依赖项构建流水线是否安全？” - **持续监控**：`monitor` 轮询 npm 和 PyPI 注册表，检测依赖项的新版本，通过控制台、Slack、PagerDuty 或通用 Webhook 提醒受损版本和 IOC 特征匹配 - **组织级扫描**：`scan --org myorg` 枚举 GitHub 组织中的所有公开仓库并行扫描 - **批量扫描**：通过 `--repos` 从文件或标准输入扫描多个仓库，支持 `--concurrency` 并行扫描，输出为控制台汇总表、JSON 或 CSV - **Runner Guard 评分**：CI/CD 安全评分（0-100），附带字母等级和类别细分（Pinning、Permissions、Injection、Triggers、IOCs） - **AI 配置注入检测**：覆盖 Claude、GitHub Copilot、Cursor 和 MCP 工具链——首个覆盖此攻击面的扫描器 - **自动修复**：将未固定第三方操作固定到不可变提交 SHA，提取 `run:` 块中的不安全表达式到 `env:` 映射 - **交互式 CLI 菜单**：直接运行 `runner-guard` 即可获得引导式体验 - **SARIF 输出**：原生支持 GitHub Code Scanning 集成 - **远程扫描**：无需克隆即可通过 URL 扫描任意公开 GitHub 仓库 - **Docker 镜像**：10MB 的 distroless 容器，位于 `ghcr.io/vigilant-llc/runner-guard` - **单一二进制文件**：零依赖，所有规则内嵌，支持任何可编译 Go 的平台 ## 快速开始 ### 扫描仓库  ``` runner-guard scan . # local repo runner-guard scan github.com/owner/repo # remote repo runner-guard scan . --format sarif --output r.sarif # SARIF for GitHub Security tab runner-guard scan . --fail-on high # CI gate ``` ### 审计上游依赖流水线  ``` runner-guard audit-deps . # scan upstream CI/CD pipelines runner-guard audit-deps . --format json # JSON output runner-guard audit-deps . --concurrency 10 # parallel scanning ``` ### 检查受损软件包  ``` runner-guard check-deps . # scan lock files runner-guard check-deps . --format json # JSON output ``` ### 批量扫描多个仓库  ``` runner-guard scan --repos repos.txt # from file runner-guard scan --repos repos.txt --concurrency 10 --format csv cat repos.txt | runner-guard scan --repos - # from stdin ``` ### 监控依赖  **告警的环境变量：** | 变量 | 说明 | |------|------| | `RUNNER_GUARD_WEBHOOK_URL` | Slack 或通用 Webhook 的 Webhook URL | | `RUNNER_GUARD_PAGERDUTY_KEY` | PagerDuty Events API v2 路由键 | | `GITHUB_TOKEN` | GitHub API 令牌（5,000 请求/小时，相比 60 有更高限制） | ### 扫描整个组织  ``` runner-guard scan --org myorg # all public repos in org runner-guard scan --org myorg --concurrency 10 --format csv ``` ### 自动修复 ``` runner-guard fix . # pin actions + extract expressions runner-guard fix . --dry-run # preview changes ``` ### Docker ``` # 扫描本地仓库 docker run -v $(pwd):/app ghcr.io/vigilant-llc/runner-guard scan /app # 远程扫描 docker run ghcr.io/vigilant-llc/runner-guard scan github.com/owner/repo # 使用 PagerDuty 警报监控 docker run -e RUNNER_GUARD_PAGERDUTY_KEY=R012345... \ -v $(pwd):/app ghcr.io/vigilant-llc/runner-guard monitor /app ``` ### 交互式菜单  ``` runner-guard # no args = guided menu ``` ## 检测内容 | ID | 名称 | 严重级别 | 说明 | |----|------|----------|------| | RGS-001 | pull_request_target 配合 Fork 代码检出 | 严重 | 在具有密钥访问权限的基仓库上下文中检出 Fork 代码 | | RGS-002 | 表达式注入（不可信输入） | 严重 | 攻击者控制的输入直接内联在 shell `run:` 块中 | | RGS-003 | 从步骤输出动态构造命令 | 高 | 步骤输出与 git diff/find/ls 结合构造 shell 命令 | | RGS-004 | 无授权检查的特权触发器 | 高 | `issue_comment` 触发器包含密钥且无授权检查 | | RGS-005 | 对不可信触发器的过度权限 | 中 | 对外部用户触发的流水线授予写入权限 | | RGS-006 | 运行块中的危险接收端 | 高 | 通过管道将远程脚本传入 shell（curl \| bash） | | RGS-007 | 未固定第三方操作 | 中/低 | 使用可变标签而非提交 SHA。作业为只读时风险较低。 | | RGS-008 | 运行块中的密钥泄露 | 中 | 在 `run:` 块中内联密钥而非使用 `env:` 映射 | | RGS-009 | 构建工具执行 Fork 代码 | 严重 | 构建工具从 Fork 检出中执行攻击者代码 | | RGS-010 | 通过 Fork PR 进行 AI 配置中毒 | 高 | CLAUDE.md 或 AI 配置文件从 Fork 检出加载 | | RGS-011 | 通过 Fork 检出进行 MCP 配置注入 | 高 | 从 Fork 控制的检出读取 .mcp.json | | RGS-012 | 携带密钥的外部网络访问 | 中 | 在特权上下文中进行出站 HTTP 请求 | | RGS-014 | 通过 workflow_dispatch 进行表达式注入 | 高 | 分发输入内联在 shell `run:` 块中 | | RGS-015 | 启用 Actions Runner 调试日志 | 中 | 调试环境变量在日志中泄露密钥 | | RGS-016 | 工作流文件中的 Unicode 隐写术 | 严重 | YAML 中的隐形 Unicode——活跃妥协指示器 | | RGS-017 | 引用脚本中的 Unicode 隐写术 | 高 | 被工作流执行的文件中存在隐形 Unicode | | RGS-018 | 可疑负载执行模式 | 高 | Eval+解码链、已知 IOC、C2 模式 | | RGS-019 | 步骤输出在 run 块中内联 | 中 | 步骤输出可能携带攻击者可控数据 | **RGS-010** 和 **RGS-011** 专属于 Runner Guard。其他 CI/CD 扫描器无法检测 AI 配置注入攻击。 ## GitHub Action ``` name: Runner Guard Security Scan on: pull_request: paths: - '.github/workflows/**' - 'CLAUDE.md' - '.claude/**' - '.mcp.json' permissions: contents: read security-events: write jobs: runner-guard: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: Vigilant-LLC/runner-guard@87e25387c26aeeb0a4247a0cad9c9dee8bfd76d4 # v3.1.4 with: fail-on: high sarif-upload: 'true' ``` 发现结果会在 GitHub 安全选项卡的“代码扫描”告警中显示。 ## 演示场景 ### Fork 检出杀伤链  `pull_request_target` 在具有完整密钥访问权限的上下文中检出 Fork 代码。检测到 RGS-001（检出）、RGS-007（未固定操作）、RGS-009（构建工具执行）、RGS-012（外泄）。 ``` runner-guard demo --scenario fork-checkout ``` ### 表达式注入（Microsoft/Akri 模式）  `issue_comment` 触发器将攻击者数据内联到 shell 中。检测到 RGS-002（注入）、RGS-004（无授权检查）、RGS-006（curl 管道 bash）、RGS-008（参数中的密钥）。 ``` runner-guard demo --scenario microsoft ``` ### AI 配置注入  隐形 Unicode 隐写术、已知 IOC 变量、eval+解码模式。检测到 RGS-016（Unicode）、RGS-018（IOC 模式）。 ``` runner-guard demo --scenario glassworm ``` ## 高级用法 ### 规则组与过滤器 ``` runner-guard scan . --group steganography # scan only steganography rules runner-guard scan . --rules RGS-016,RGS-018 # specific rules runner-guard scan . --group ai-config --rules RGS-001 # combine ``` **分组：** `injection`、`permissions`、`secrets`、`supply-chain`、`ai-config`、`steganography`、`debug` ### 自动修复细节 修复引擎： - **固定操作**：将操作固定到不可变提交 SHA 并添加版本注释 - **提取 Tier-1 表达式**：从 `run:` 块提取到 `env:` 映射 - **提取密钥**：从 `run:` 块提取到 `env:` 映射 - **Shell 感知**：`${VAR}`（Bash）、`$env:VAR`（PowerShell）、`%VAR%`（cmd） - **处理单引号上下文**并**跳过花括号展开** ### 基线管理 ``` runner-guard baseline create # generate baseline runner-guard scan . --baseline .runner-guard-baseline.json # suppress known runner-guard baseline update # update after triage ``` ### 行内抑制 ``` - uses: some-org/action@v1 # runner-guard:ignore ``` ## 威胁图景 ### 活跃的供应链攻击活动（2026 年 3 月） 一次多阶段协调攻击活动： - **阶段 1-2（3 月 12 日）**：reviewdog 和 tj-actions/changed-files 被攻破，从 23,000+ 仓库中收集 CI/CD 凭证 - **阶段 3（3 月 19-27 日）**：Trivy、Checkmarx、LiteLLM、Telnyx 被攻破，TeamPCP 导致 Cisco 丢失 300+ 源代码仓库 - **阶段 4（3 月 30 日）**：Axios（每周 1 亿下载）被植入 RAT。归因于北朝鲜威胁行为体 UNC1069。 Runner Guard 包含按活动组织的 `rules/signatures/` 中的所有已确认阶段 IOC 签名。 ### CI/CD 流水线注入 由 `pull_request_target` 触发的流水线使用基仓库的密钥运行。当与指向 Fork 代码的 `actions/checkout` 结合时，攻击者的构建脚本将以完整凭证执行。已有案例显示，攻击者在几分钟内窃取 PAT 并将恶意提交推送到主分支，完全由 AI 代理自动化。 ### 供应链隐写术 GlassWorm 攻击活动利用 433+ 个组件中的隐形 Unicode 字符编码不可见的有效载荷。Runner Guard 在字节级别检测此问题（RGS-016/017/018）。 ### AI 配置注入 当 `pull_request_target` 流水线检出 Fork 代码时，攻击者可以修改 CLAUDE.md、copilot-instructions.md、.cursorrules 或 .mcp.json 以劫持 AI 代码审查代理。Runner Guard 是首个检测此攻击面的扫描器（RGS-010/011）。 ## 贡献 Runner Guard 欢迎贡献，尤其是新的检测规则： 1. 在 `rules/` 中创建 YAML 规则文件（参考 `rules/RGS-001-prt-fork-checkout.yaml`） 2. 如有需要，在 `internal/rules/` 中添加检测逻辑 3. 在 `internal/taint/` 中添加测试用例 4. 提交描述真实世界攻击模式的 PR 若要添加威胁特征签名而无需编写 Go 代码，请将 YAML 文件添加到 `rules/signatures/` 并重新构建。请参考现有文件格式。 请报告误报。准确性至关重要——会“哭狼”的扫描器会被禁用。 ## 关于 Vigilant [Vigilant](https://vigilantdefense.com) 是一家网络安全公司，介于组织与企图摧毁它们的威胁之间。我们不相信被动防御——我们以作战思维运作，在威胁成为漏洞之前主动猎杀。 我们构建 Runner Guard 是因为我们已在红队演练中将这些攻击链武器化，针对银行、政府机构和关键基础设施。 - **[ThreatCert](https://vigilantdefense.com)**——攻击面情报平台，提供可审计证据的完整杀伤链映射 - **[CyberDNA](https://vigilantdefense.com)**——具备 Vigilant 零漏洞保证的分析工作区 Vigilant 将 25% 的利润捐赠给致力于打击人口贩卖和支持全球孤儿护理的组织。 如需企业支持、定制规则开发或安全评估，请访问 [vigilantdefense.com](https://vigilantdefense.com)。 ## 许可证 AGPL-3.0。详见 [LICENSE](LICENSE)。 Copyright 2026 Vigilant。

标签：AI配置中毒, EVTX分析, GitHub Actions, Go语言, SEO, 云安全监控, 依赖审计, 关键词优化, 安全扫描, 工作流安全, 并行扫描, 恶意包检测, 日志审计, 时序注入, 模块化设计, 注入检测, 程序破解, 自动化修复, 自动笔记, 隐写术, 静态分析