agentshield
affaan-m/agentshield加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
图1：AgentShield 项目 Logo
你正在用 Claude Code 写核心业务代码，一切顺利。突然有一天，安全团队告诉你：你的代码库里有一条 API Key，正在暗网流通。或者更糟——MCP 服务器供应链被攻击，数百个开发环境的凭证被悄悄窃取。
这并非危言耸听。2026年1月，一个主流 AI Agent 技能市场上 12%（341/2857） 的社区技能是恶意的；某 CVE 评分 8.8 的漏洞导致 17500+ 互联网暴露实例面临一键 RCE 风险；Moltbook 数据泄露事件波及 77 万个 AI Agent 中的 150 万枚 API Token。
AgentShield 正是为解决这个痛点而诞生。它由 Affaan Mustafa 在 2026 年 2 月的 Claude Code Hackathon（Cerebral Valley × Anthropic 联合举办）上构建，是 Everything Claude Code 生态系统的核心组件（该系列累计 42000+ stars）。
Claude Code、OpenCode 等 AI 编程工具会读取用户目录下的配置文件（如 ~/.claude/、.claude/ 目录）来理解项目上下文、工具权限和行为规则。这些配置文件决定了 Agent 能做什么、不能做什么——但它们往往被开发者忽视。
常见的配置风险包括：
AgentShield 的核心思路是：在攻击发生之前，主动扫描并报告这些配置缺陷。
AgentShield 就是给 Claude Code 等 AI 编程工具用的「安全体检仪」——安装后一行命令 npx ecc-agentshield scan，就能对 Agent 配置进行全面审计，输出从 A（安全）到 F（极度危险）的评分报告。
AgentShield 内置 102 条检测规则，覆盖 5 大安全类别：
检测 10+ 类凭证泄露，包括：
sk-ant-)、OpenAI (sk-proj-)、xAI (xai-)、AWS (AKIA)、Google/Gemini (AIza)、Stripe (sk_test_/sk_live_)ghp_/github_pat_)、Linear (lin_api_)、Cloudflare (CF_API_TOKEN)、Slack (xox[bprs]-)、JWTs检查 settings.json 中的 allow/deny 规则：
Bash(*)、Write(*)、Edit(*) — 完全不受限制的工具访问--dangerously-skip-permissions 的使用git push --force、git reset --hard 在允许列表中curl *、wget、ssh * 在允许列表中无作用域限制这是 AgentShield 最复杂的检测模块，分析 .claude/hooks/ 目录下的 Hook 配置：
${file} 插值到 shell 命令——攻击者控制文件名就等于执行代码curl -X POST 向外部 URL 发送数据2>/dev/null、|| true ——安全 Hook 静默通过，骗过 AgentMCP（Model Context Protocol）允许 Agent 调用外部工具服务器，攻击面极大：
.env、.aws/credentials）被暴露给 AgentAgentShield 采用典型的「扫描器 + 规则引擎 + 报告器」三层架构：
src/
scanner/ # 文件发现：扫描 .claude/, settings.json, mcp.json, agents/, hooks/
rules/ # 10 个规则模块（secrets, permissions, hooks, mcp, agents...）
reporter/ # 评分引擎 + 多格式输出（terminal/JSON/HTML/Markdown/SARIF）
opus/ # Opus 4.6 三代理对抗分析管道（需 ANTHROPIC_API_KEY）
miniclaw/ # 安全沙箱路由（prompt 净化 + 输出过滤 + 工具白名单）
policy/ # 组织策略评估与导出
supply-chain/ # npm/git 包溯源验证
evidence-pack/ # 取证包生成（安全审计移交）
每个规则模块输出标准化的 Finding 对象，包含 severity、category、evidence、fix 建议。扫描结果通过 score.ts 计算加权评分，最终输出 A-F 等级和分项雷达图。
关键设计亮点：
settings.yml 等 YAML 格式配置文件--fix 自动修复（如将硬编码密钥替换为环境变量引用）AgentShield 支持四种部署形态：
| 形态 | 命令 | 适用场景 |
|---|---|---|
| npx 免安装 | npx ecc-agentshield scan | 临时扫描，快速验证 |
| 全局 CLI | npm install -g ecc-agentshield | 日常开发，永久可用 |
| GitHub Action | uses: affaan-m/agentshield | CI/CD 自动化，PR 门禁 |
| Node.js API | import {scan} from 'ecc-agentshield' | 程序化集成 |
最推荐方式是 npx ecc-agentshield scan，无需安装任何依赖，一行命令即可扫描本地 Claude Code 配置。扫描结果示例：
AgentShield Security Report
Grade: F (0/100)
Secrets ░░░░░░░░░░░░░░░░░░░░ 0
Permissions ░░░░░░░░░░░░░░░░░░░░ 0
Hooks ░░░░░░░░░░░░░░░░░░░░ 0
MCP Servers ░░░░░░░░░░░░░░░░░░░░ 0
Agents ░░░░░░░░░░░░░░░░░░░░ 0
● CRITICAL Hardcoded Anthropic API key
CLAUDE.md:13
Evidence: sk-ant-a...cdef
Fix: Replace with environment variable reference [auto-fixable]
● CRITICAL Overly permissive allow rule: Bash(*)
settings.json
Fix: Restrict to specific commands
AgentShield 内置基于 Claude Opus 4.6 的三代理对抗分析模式：Attacker（模拟攻击者）→ Defender（模拟防护者）→ Auditor（综合裁判）。运行 agentshield scan --opus --stream 即可启用，需要 ANTHROPIC_API_KEY 环境变量。
MiniClaw 是 AgentShield 的配套安全沙箱模块，提供：
MiniClaw 可通过 Node.js API 或 HTTP API（/api/*）集成到现有 Agent 工作流中。
npx ecc-agentshield scan 一行命令AgentShield 并非银弹，存在以下局限：
误报问题：规则检测基于静态模式匹配，合法代码（如测试文件中的假密钥）可能被误报。AgentShield 通过 runtimeConfidence 字段区分「活跃运行时配置」和「项目本地可选配置/模板缓存」，但仍需人工复核
覆盖范围：目前主要针对 Claude Code 生态（.claude/ 目录结构），对其他 Agent 框架（如 Cursor、Copilot）的支持有限
Hook 分析深度：对于复杂的非 Shell Hook（如 Python/Node.js Hook），检测能力相对较弱
Opus 分析成本：三代理对抗分析需要调用 Claude Opus 4.6，成本较高，不适合高频扫描
AgentShield 的出现填补了 AI Agent 安全工具链的关键空白。随着 Claude Code、OpenCode 等工具被大量团队引入生产开发环境，Agent 配置安全的紧迫性正在急剧上升。
从数据看：2026年1月的 Moltbook 事件波及 77 万个 Agent、150 万枚 Token，这个量级的安全事件足以让企业安全团队重新审视 AI 编程工具的引入策略。AgentShield 提供了自动化审计能力，让安全团队不用逐一审查每个开发者的 Agent 配置，将安全审计从手动变为自动。
该项目在 Hackathon 后短短几个月内积累了 879 stars、188 forks，GitHub Actions 集成和 npm 包分发使其传播门槛极低。随着 Everything Claude Code 生态（42000+ stars）持续增长，AgentShield 有望成为 Claude Code 安全配置的「标配」。