David-Wu1119/agentci-guard

# AgentCI Guard AgentCI Guard 是一个 CLI 和 GitHub Action，用于检测 CI/CD 工作流中不安全的 AI 编码代理使用行为。 它专注于一种高风险模式：不受信任的 GitHub 事件内容触达了具有密钥、写入权限、shell 访问权限或安全 checkout 行为的 AI 代理。 ## 它能检测什么 - 在 `.github/workflows/*.yml` 中 AI 代理的使用 - `pull_request_target` 与 AI 代理的结合 - 被传递到 prompt 或 shell 命令中的 PR/issue/评论/审查/分支/提交内容 - 在 AI 使用附近出现的 `contents: write`、`pull-requests: write` 或其他宽泛的写入权限范围 - 代理任务中的 `secrets.*`、`GITHUB_TOKEN` 以及类似 token 的环境变量 - shell 访问权限与 AI 使用的结合 - 未固定版本的第三方 AI action - 在特权上下文中 checkout 不受信任的 PR head 代码 ## CLI 快速开始 ``` # 免安装运行 npx agentci-guard scan . # 或者全局安装 npm install -g agentci-guard agentci scan . agentci scan . --json agentci scan . --sarif agentci-results.sarif agentci explain agentci/untrusted-ai-write-token ``` 退出代码： - `0`：没有达到或高于 `--fail-on` 级别的发现 - `2`：至少有一个达到或高于 `--fail-on` 级别的发现 - `1`：扫描器错误 默认失败阈值为 `high`。 ## GitHub Action ``` name: agentci-guard on: [pull_request, push] permissions: contents: read security-events: write jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: David-Wu1119/agentci-guard@main with: path: . sarif: agentci-results.sarif fail-on: high - uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: agentci-results.sarif ``` ## 发现示例 ``` CRITICAL agentci/untrusted-ai-write-token File: .github/workflows/ai-agent.yml / job: claude Evidence: untrusted trigger + AI usage + write permissions + untrusted GitHub event context Why: An attacker can place prompt-injection text in a PR, issue, or comment. If that text reaches an AI agent with repository write permissions, the agent can be induced to modify code, comments, workflows, or releases. Fix: - Do not run privileged AI agents on untrusted triggers. - Use read-only GITHUB_TOKEN permissions for untrusted events. - Require maintainer approval before running the agent. - Sanitize and summarize untrusted content before passing it to an agent. ``` ## 开发说明 ``` corepack enable pnpm install pnpm typecheck pnpm test pnpm build npm pack --dry-run ``` ## 安全边界 AgentCI Guard 是一个静态扫描器。它不会对工作流进行沙盒处理，也不会证明代理是安全的。它识别的是高风险模式，在允许 AI 代理在特权 CI/CD 上下文中运行之前，这些模式应该接受人工审查。 请参阅[威胁模型](docs/threat-model.md)。 ## 许可证 MIT

标签：AI安全, Chat Copilot, CI/CD安全, DevSecOps, GitHub Actions, Llama, MITM代理, StruQ, 上游代理, 暗色界面, 自动化攻击, 自动笔记, 错误基检测, 静态代码分析