ecoreal/agentic-risk-scan

# Agentic 风险扫描 [](https://github.com/ecoreal/agentic-risk-scan/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) 针对 AI agent 工作流、MCP 配置以及已提交的 agent 指令的静态安全扫描器。 AI agent 现在已成为软件供应链的一部分。它们会读取 PR 标题、issue 评论、 prompt 文件、MCP 配置、包脚本以及工作流产物。 `agentic-risk-scan` 旨在查找那些会使这些输入变得危险的仓库模式：具备写权限的 GitHub token、不受信任的 shell 插值、隐藏的 Unicode prompt 文本、下载并执行的 MCP server、内联 secret 以及有风险的安装脚本。 它无需任何依赖，可在 Python 3.10+ 上运行，专为 CI、代码审查和快速本地审计而设计。 阅读更深入的背景信息： - [研究笔记](docs/research.md) - [项目简介](docs/project-brief.md) - [威胁模型](docs/threat-model.md) ## 快速开始 ``` python3 -m pip install -e . agentic-risk-scan scan . ``` 免安装运行： ``` PYTHONPATH=src python3 -m agentic_risk_scan scan . ``` 为 GitHub 代码扫描生成 SARIF： ``` agentic-risk-scan scan . --format sarif --output agentic-risk.sarif --fail-on high ``` 输出 GitHub 工作流注解： ``` agentic-risk-scan scan . --format github --fail-on high ``` 仅扫描 pull request 中更改的文件： ``` agentic-risk-scan scan . --changed-from origin/main --format github ``` 创建初始配置： ``` agentic-risk-scan init-config ``` ## 扫描内容 - 使用 `pull_request_target` 检出不受信任的 PR 代码的工作流。 - 在 issue、评论、PR 或 workflow-run 触发器上使用写 token 的 AI 或类 agent GitHub Actions。 - 对来自 PR、issue、评论、讨论或手动输入中的 `github.event.*` 文本进行插值的 shell 命令。 - 在不受信任的触发器工作流中暴露 secret 和 OIDC。 - 在不受信任的触发器中使用自托管 runner。 - 在 `AGENTS.md`、`CLAUDE.md`、`.github/copilot-instructions.md`、`.cursor/rules/*` 及类似文件中存在的 prompt injection 短语和隐藏 Unicode。 - 通过 shell 包装器、运行时下载、未指定版本的 `npx`、宽泛的运行时标志、临时路径或内联的类 secret 值启动的 MCP server。 - 包含 `curl | sh`、`eval`、内联解释器、打印 secret 或远程 tarball 依赖的 npm install 生命周期脚本。 ## 示例 ``` PYTHONPATH=src python3 -m agentic_risk_scan scan examples/unsafe-ai-pr-bot --fail-on none ``` 输出示例： ``` Agentic Risk Scan root: /path/to/examples/unsafe-ai-pr-bot risk score: 100/100 findings: critical=1, high=11, medium=3, low=1 scanned files: 4, skipped files: 0 [CRITICAL] GHA001 pull_request_target checks out untrusted PR code at: .github/workflows/unsafe.yml:16 why: This workflow runs with target-repository privileges and checks out code from the pull request head. ``` ## GitHub Actions ``` name: agentic-risk-scan on: pull_request: push: branches: [main] permissions: contents: read security-events: write jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - run: python -m pip install agentic-risk-scan - run: agentic-risk-scan scan . --format sarif --output agentic-risk.sarif --fail-on high - uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: agentic-risk.sarif ``` 或者将此仓库作为 composite action 使用： ``` - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: ecoreal/agentic-risk-scan@v0 with: format: github fail_on: high changed_from: origin/main ``` ## 配置 `agentic-risk-scan` 会从扫描路径或其父目录自动加载 `.agentic-risk-scan.json`。 ``` { "$schema": "https://raw.githubusercontent.com/ecoreal/agentic-risk-scan/main/docs/config.schema.json", "fail_on": "high", "exclude": ["examples/fixtures/**"], "disabled_rules": ["PKG004"], "severity_overrides": { "AGENT005": "low" }, "suppressions": [ { "rule_id": "AGENT005", "path": "AGENTS.md", "reason": "Tool access is constrained by a separate sandbox policy." } ] } ``` CLI 参数会覆盖或扩展配置值： ``` agentic-risk-scan scan . --config security/agentic-risk.json agentic-risk-scan scan . --exclude "examples/**" --disable-rule PKG004 agentic-risk-scan scan . --changed AGENTS.md --changed .github/workflows/agent.yml ``` 已审查的例外情况支持使用内联忽略： ``` allowed-tools: * ``` ``` run: echo "${{ github.event.issue.title }}" # agentic-risk-scan: ignore GHA003 ``` ## 基线 在现有仓库中采用此扫描器时，请创建一个基线： ``` agentic-risk-scan scan . --update-baseline .agentic-risk-baseline.json --fail-on none ``` 然后仅针对新增的发现结果报错： ``` agentic-risk-scan scan . --baseline .agentic-risk-baseline.json --fail-on high ``` ## 输出格式 ``` agentic-risk-scan scan . --format text agentic-risk-scan scan . --format json agentic-risk-scan scan . --format markdown agentic-risk-scan scan . --format sarif agentic-risk-scan scan . --format github ``` ## Pull Request 模式 全仓库扫描适用于计划内的审计。Pull request 检查通常需要更聚焦的信号。使用 `--changed` 指定明确的路径，或使用 `--changed-from` 让扫描器向 git 请求已更改的文件： ``` agentic-risk-scan scan . --changed AGENTS.md --fail-on medium agentic-risk-scan scan . --changed-from origin/main --changed-to HEAD --format github ``` 默认情况下会忽略已删除的文件。默认的 git diff 过滤器是 `ACMR`，涵盖已添加、已复制、已修改和已重命名的文件。 在 GitHub Actions 中，请将 `actions/checkout` 设置为 `fetch-depth: 0`，或者在使用 `--changed-from origin/main` 之前先拉取基础分支。 规则参考请参阅 [docs/rules.md](docs/rules.md)。 扫描器威胁模型请参阅 [docs/threat-model.md](docs/threat-model.md)。 ## 设计原则 - 扫描器本身不依赖任何依赖链。 - 在完整的 安全计划建立之前就能发挥作用。 - 扫描结果会解释输入边界、危险特权以及修复方法。 - 规则更倾向于捕捉高价值的 agentic 工作流风险，而非通用的代码检查。 ## 路线图 - 覆盖更多的 agent 生态系统配置。 - 针对工作流产物和已生成补丁的污点分析。 - npm、PyPI、Homebrew 及容器发版。 ## 贡献 带有最小化漏洞示例和修复示例的 issue 是最有用的贡献。规则更改应包含测试，并避免对安全的示例仓库发出警告。

标签：DLL 劫持, Python, StruQ, 人工智能安全, 合规性, 大语言模型, 文档安全, 无后门, 逆向工具, 静态代码扫描