r12habh/ActionScope

# ActionScope [](https://pypi.org/project/actionscope/) [](https://pypi.org/project/actionscope/) [](https://github.com/r12habh/ActionScope/actions/workflows/ci.yml) [](https://codecov.io/gh/r12habh/ActionScope) [](LICENSE) [](https://github.com/marketplace/actions/actionscope) [](https://r12habh.github.io/ActionScope/) 📖 **完整文档：**  ·  🛡️ **受损 Actions 数据库：** **你的 GitHub Actions 工作流中包含 AWS 凭据。你知道它们能做什么吗？** ActionScope 会读取你的 `.github/workflows/` 文件、Terraform IAM 资源和 JSON IAM 策略，然后以通俗易懂的英语告诉你，如果 CI/CD 流水道遭到入侵，它能在 AWS 中做什么。 它还能检测： - 🚨 **已知的受损 Actions**（`actions-cool`、`tj-actions`、`trivy-action`） - 🔓 **OIDC 信任策略配置错误**（通配符组织 subject，缺少 sub/aud） - 💉 **脚本注入**（`run:` 块中的 PR 标题、issue 正文） - 🎭 **Artifact 投毒**（`workflow_run` + 执行不受信任的 artifact） - 🤖 **AI agent 提示词注入面**（CI 中的 Claude Code、Copilot） - 📌 **未固定的 Actions** 及 SHA 解析  工作流只会说明它*假设了一个角色*。ActionScope 会将其与背后的 IAM 关联，并展示如果 CI 遭到入侵，该角色实际上能做什么 —— 比如：传递任何 IAM 角色（权限提升）、清空 S3 以及终止 EC2。 **[亲自重现此扫描 »](examples/aws-blast-radius-demo/)** ## 在 30 秒内于你的 repo 中试用 ``` pip install actionscope cd /path/to/your/repo-with-github-actions actionscope scan . ``` 就这么简单。不需要 AWS 凭据，没有遥测，也不需要注册。静态分析在一个典型的 repo 上运行通常不到一秒钟。如果没有相关内容，你会得到 `Overall Risk: ℹ️ INFO`。如果发现了什么，你会确切地看到是什么以及为什么。 **想要一次引导式的首次扫描体验？** 请参阅 [**你的首次扫描**](https://r12habh.github.io/ActionScope/tutorials/first-scan/) —— 从安装到理解输出只需 5 分钟。 ## 常用参数 ``` actionscope scan . --aws-verify # fetch live IAM policies (read-only) actionscope scan . --resolve-pins # suggest full-SHA pins for unpinned actions actionscope scan . --fail-on high # exit 1 if any finding is HIGH or above actionscope scan . --output-format sarif --output-file results.sarif actionscope scan . --save-state # save state for PR delta comparison ``` ## 输出示例 ``` ActionScope — Blast Radius Report Path: /my-repo | Workflows: 2 | Overall Risk: 🔴 CRITICAL ⛔ KNOWN COMPROMISED ACTIONS (1 found) ────────────────────────────────────────────────────────────── ⛔ CRITICAL: actions-cool/issues-helper@v3 (issue-triage.yml) Compromised 2026-05-18 — mutable tags may run credential-stealing code Fix: Remove this action or pin to a verified pre-compromise SHA ───────────────────────────────────────────────────────────── deploy.yml → deploy → Configure AWS credentials AWS Role: arn:aws:iam::123456789012:role/github-deploy-role Auth: OIDC ✓ ┌─────────────────────────────┬────────────────────┬──────────┐ │ iam:PassRole │ Permissions mgmt │ 🔴 CRIT │ │ ec2:TerminateInstances │ Write │ 🟠 HIGH │ │ s3:GetObject │ Read │ 🟢 LOW │ └─────────────────────────────┴────────────────────┴──────────┘ 🔴 Privilege Escalation Path: iam:PassRole on * — can escalate to any role ``` ## 作为 GitHub Action 使用 ``` name: ActionScope Security Scan on: [push, pull_request] permissions: contents: read security-events: write # for SARIF upload pull-requests: write # for PR comments jobs: actionscope: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: r12habh/ActionScope@v0 with: fail-on: high # fail CI if HIGH or above comment-pr: true # post findings as PR comment upload-sarif: true # show in GitHub Security tab resolve-pins: true # suggest SHA pins for unpinned actions ``` ## ActionScope 的独特之处 ActionScope 回答了一个其他工具都无法回答的问题： | 功能 | actionlint | zizmor | Scorecard | ActionScope | |---|---|---|---|---| | 工作流语法验证 | ✅ | 部分 | ❌ | 部分 | | 安全模式检测 | ❌ | ✅ | ✅ | ✅ | | GITHUB_TOKEN 权限审查 | ❌ | ✅ | ✅ | ✅ | | 未固定 Action 检测 | ❌ | ✅ | ✅ | ✅ | | **已知受损 Action 检测** | ❌ | ❌ | ❌ | **✅** | | **AWS 凭据来源检测** | ❌ | ❌ | ❌ | **✅** | | **工作流 → IAM 角色关联** | ❌ | ❌ | ❌ | **✅** | | **实时 AWS IAM 策略验证** | ❌ | ❌ | ❌ | **✅** | | **通俗易懂的影响范围说明** | ❌ | ❌ | ❌ | **✅** | | **OIDC 信任策略分析** | ❌ | ❌ | ❌ | **✅** | | **脚本注入检测** | ❌ | 部分 | ❌ | **✅** | | SARIF / GitHub Security 标签页 | ❌ | ✅ | ✅ | **✅** | ## 工作原理 ActionScope 默认执行**纯静态分析**。它永远不会将你的代码发送到外部服务，除非你明确启用实时 AWS 验证，否则不需要 AWS 凭据。 ``` .github/workflows/*.yml terraform/**/*.tf → ActionScope → Blast Radius Report policies/**/*.json + PR Comment + SARIF → GitHub Security Tab ``` 1. 在工作流中查找 `aws-actions/configure-aws-credentials` 2. 提取角色 ARN 和凭据模式 3. 将角色与 Terraform 或 JSON 文件中的 IAM 策略进行匹配 4. 使用 `policy-sentry` action 数据库对 IAM 操作进行分类 5. 检测权限提升路径 6. 在内置数据库中检查已知的受损 Actions 7. 输出通俗易懂的影响范围报告 ### 实时 AWS 验证 (`--aws-verify`) ``` pip install actionscope[aws] actionscope scan . --aws-verify ``` 需要只读 IAM 权限： `iam:GetRole`、`iam:ListAttachedRolePolicies`、`iam:GetPolicy`、 `iam:GetPolicyVersion`、`iam:ListRolePolicies`、`iam:GetRolePolicy`。 有关所需的最小策略，请参阅 [docs/aws-verify-permissions.md](docs/aws-verify-permissions.md)。 ## 安全检测器 ### 🚨 已知的受损 Actions 根据有记录的供应链受损事件策划的 GitHub Actions 数据库对工作流进行检查。该数据库会随每次 ActionScope 发布进行更新。 当前条目包括：`actions-cool/issues-helper` (2026-05-18)、 `actions-cool/maintain-one-comment` (2026-05-18)、 `tj-actions/changed-files` (2025-03-19) 和 `aquasecurity/trivy-action` (2026-03-19)。 ### 🔓 OIDC 信任策略分析 检测 GitHub OIDC 信任策略中的通配符组织 subject、缺失的 `sub`/`aud` 条件，以及不充分的分支/环境作用域限制。 ### 💉 脚本注入检测 查找直接将攻击者可控的 GitHub context 值（如 `github.event.pull_request.title`、`github.event.issue.body` 等）插入到 `run:` shell 块中的行为：即“Pwn Request”攻击类别。 ### 🎭 Artifact 投毒检测 识别那些会下载并执行来自可能不受信任的 fork PR 工作流（具有密钥访问权限）的 artifact 的 `workflow_run` 工作流。 ### 🤖 AI Agent 提示词注入面 检测在不受信任的 PR context 中配置了写入权限的 Claude Code、GitHub Copilot Agent、Gemini CLI 及类似 AI 编码 agent。 ### 📌 Action 固定及 SHA 解析 检测未固定的 Actions，并通过 GitHub API 将 tag 解析为当前的 SHA。区分完整的 SHA（安全）、短 SHA（仍可变）以及 tag。 ### ⚡ IAM 权限提升路径 检测有记录的权限提升路径，包括 PassRole、CreatePolicyVersion、AttachRolePolicy、CreateAccessKey、Lambda+PassRole、EC2+PassRole、CloudFormation+PassRole 等。 ## 研究 ActionScope 基于一项针对 493 个公开 GitHub repo 以及 3,981 个使用 AWS 的 GitHub Actions 工作流文件的实证研究。 | 发现 | 结果 | |---------|--------| | 使用静态 AWS 密钥（非 OIDC） | 58.2% 的 repo | | 使用未固定的外部 Actions | 95.5% 的 repo | | `pull_request_target` + 写入权限 | 8.1% 的 repo | | 直接在工作流中暴露角色 ARN | 44.0% 的 repo | → [完整研究发现](research/FINDINGS.md) | [扫描器和匿名化数据集](research/) ## 输出格式 ``` actionscope scan . --output-format terminal # default: colored Rich output actionscope scan . --output-format json # for CI integration actionscope scan . --output-format markdown # for PR comments actionscope scan . --output-format sarif # for GitHub Security tab ``` ## 常见问题解答 ### 如何检测像 tj-actions 或 actions-cool 这样受损的 GitHub Actions？ ActionScope 内置了一个精心策划的已知受损 Actions 数据库（tj-actions、actions-cool/issues-helper、actions-cool/maintain-one-comment、trivy-action），并根据它扫描工作流中的每一个 `uses:` 引用。运行 `actionscope scan .`，任何受损的引用都会作为带有建议链接的 CRITICAL（严重）发现显示出来。 ### 我的 GitHub Actions 工作流能在我的 AWS 账户中做什么？ ActionScope 会从你的工作流中提取每一个 `aws-actions/configure-aws-credentials` 步骤，跟踪角色 ARN，并将其与同一 repo 中的 Terraform 或 JSON IAM 策略文件相关联。输出结果是一份通俗易懂的影响范围报告 —— 列出工作流可以执行的每一个 IAM 操作，并按风险进行分类。添加 `--aws-verify` 可通过只读 IAM 调用从 AWS 获取实时策略。 ### 如何在没有 AWS 凭据的情况下扫描 GitHub Actions 工作流的安全问题？ `actionscope scan .` 默认作为纯静态分析运行。它不需要 AWS 凭据，不需要 GitHub token（`--resolve-pins` 除外），并且绝不会将你的代码发送到外部服务。 ### 如何发现脚本注入或 `pull_request_target` 风险？ ActionScope 会检测直接将攻击者可控的 GitHub 事件字段（PR 标题、issue 正文、分支名称等）注入到 `run:` 块中的行为，并标记那些将不受信任的事件数据与具有写入权限的 `GITHUB_TOKEN` 相结合的 `pull_request_target` 作业 —— 这是 2026 年 4 月 prt-scan 攻击背后的模式。 ### 如何为我的工作流获取 GitHub Code Scanning 告警？ 运行 `actionscope scan . --output-format sarif --output-file results.sarif`，然后通过 `github/codeql-action/upload-sarif` action 将 `results.sarif` 上传到 GitHub Security 标签页。ActionScope 输出的 SARIF 规则 AS001–AS014 涵盖了 AWS 暴露、OIDC 信任、未固定的 Actions、受损的 Actions、脚本注入以及环境强化。 ### 如何将 GitHub Actions 固定到完整的 commit SHA？ `actionscope scan . --resolve-pins` 使用 GitHub API 为工作流中每一个可变的 `uses: owner/repo@vX` 引用查找当前的完整 SHA 值，并打印出建议的固定版本，同时将 tag 作为注释保留。 ### ActionScope 与 actionlint、zizmor 或 Checkov 有什么区别？ actionlint 验证工作流的 YAML 语法。zizmor 和 Scorecard 检测工作流的安全模式。Checkov 独立扫描 IAM 策略。ActionScope 是唯一能够**跨越边界**的工具 —— 它将特定的工作流、特定的 IAM 角色以及特定的影响范围联系在一起。 ### ActionScope 需要 AWS 凭据吗？ 只有当你选择启用 `--aws-verify` 时才需要，该功能会进行只读 IAM API 调用以获取实时附加的策略。有关所需的确切权限集，请参阅 [`docs/aws-verify-permissions.md`](docs/aws-verify-permissions.md)。 ## 文档 📖 **完整文档站点：** - **[首次扫描教程](https://r12habh.github.io/ActionScope/tutorials/first-scan/)** —— 安装 → 首次扫描 → 阅读输出，只需 5 分钟 - **[常见问题解答](https://r12habh.github.io/ActionScope/faq/)** —— 空扫描、`policy_source: not_found`、`--aws-verify` 的安全性、数据库刷新频率、工具对比 - [受损 Actions 数据库](https://r12habh.github.io/ActionScope/compromised-actions-database/) —— ActionScope 标记的每一个 Action，均带有永久链接 - [CLI 参考](docs/cli-reference.md) - [OIDC 信任策略分析](docs/oidc-trust.md) - [已知受损 Actions 检测器](docs/compromised-actions.md) - [SARIF 与 GitHub Security 标签页](docs/sarif.md) - [AWS 验证权限](docs/aws-verify-permissions.md) - [发布手册](docs/release-runbook.md) ## 作者 Rishabh Singh. [GitHub](https://github.com/r12habh) *ActionScope 默认执行静态分析。它不会将你的代码或凭据传输到任何外部服务。*

标签：AWS IAM, DevSecOps, GitHub Actions, StruQ, TShark, 上游代理, 协议分析, 攻击面映射, 权限提升, 自动笔记, 逆向工具, 错误基检测, 静态代码分析