affaan-m/agentshield

## 为什么需要 AI Agent 生态系统的增长速度超过了其安全工具的发展。仅在 2026 年 1 月： - 某主要 Agent 技能市场中有 **12%** 为恶意内容（2,857 个社区技能中的 341 个） - 一个 **CVSS 8.8** 级别的 CVE 漏洞导致 17,500+ 个面向互联网的实例暴露于一键 RCE 攻击 - Moltbook 泄露事件导致 770,000 个 Agent 的 **150 万个 API Token** 被盗 开发者安装社区技能、连接 MCP 服务器并配置 Hook，却没有任何自动化的方式来审计其设置的安全性。AgentShield 扫描您的 `.claude/` 目录，并在漏洞被利用之前标记出来。 构建于 [Claude Code Hackathon](https://cerebralvalley.ai/e/claude-code-hackathon)（Cerebral Valley x Anthropic，2026 年 2 月）。[Everything Claude Code](https://github.com/affaan-m/everything-claude-code) 生态系统（42K+ Stars）的一部分。 ## 快速开始 ``` # 扫描您的 Claude Code 配置（无需安装） npx ecc-agentshield scan # 或全局安装 npm install -g ecc-agentshield agentshield scan ``` 就是这样。AgentShield 自动发现您的 `~/.claude/` 目录，扫描所有配置文件，并打印一份分级安全报告。 ``` AgentShield Security Report Grade: F (0/100) Score Breakdown 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 Evidence: Bash(*) Fix: Restrict to specific commands: Bash(git *), Bash(npm *), Bash(node *) Summary Files scanned: 6 Findings: 73 total — 19 critical, 29 high, 15 medium, 4 low, 6 info Auto-fixable: 8 (use --fix) ``` ### 更多命令 ``` # 扫描特定目录 agentshield scan --path /path/to/.claude # 自动修复安全问题（用环境变量引用替换硬编码的 secrets） agentshield scan --fix # 用于 CI 流水线的 JSON 输出 agentshield scan --format json # 生成 HTML 安全报告 agentshield scan --format html > report.html # 三智能体 Opus 4.6 对抗性分析（需要 ANTHROPIC_API_KEY） agentshield scan --opus --stream # 生成安全基线配置 agentshield init ``` ## 检测范围 涵盖 5 大类别的 **102 条规则**，按 A–F 分级并给出 0–100 的数值评分。 ### 机密检测 (10 条规则，14 种模式) | 内容 | 示例 | |------|----------| | API keys | Anthropic (`sk-ant-`)、OpenAI (`sk-proj-`)、AWS (`AKIA`)、Google (`AIza`)、Stripe (`sk_test_`/`sk_live_`) | | Tokens | GitHub PAT (`ghp_`/`github_pat_`)、Slack (`xox[bprs]-`)、JWT (`eyJ...`)、Bearer Token | | 凭证 | 硬编码密码、数据库连接字符串 (postgres/mongo/mysql/redis)、私钥材料 | | Env 泄露 | 配置中通过环境变量传递的机密、Hook 中的 `echo $SECRET` | ### 权限审计 (10 条规则) | 内容 | 示例 | |------|----------| | 通配符访问 | `Bash(*)`、`Write(*)`、`Edit(*)` — 无限制的工具权限 | | 缺少拒绝列表 | 没有 `rm -rf`、`sudo`、`chmod 777` 的拒绝规则 | | 危险标志 | 使用了 `--dangerously-skip-permissions` | | 可变工具暴露 | 所有可变工具 在没有作用域限制的情况下被允许 | | 破坏性 Git | 允许的命令中包含 `git push --force`、`git reset --hard` | | 无限制网络 | 允许列表中包含无作用域限制的 `curl *`、`wget`、`ssh *`、`scp *` | ### Hook 分析 (34 条规则) | 内容 | 示例 | |------|----------| | 命令注入 | Shell 命令中的 `${file}` 插值 — 攻击者控制的文件名变成了代码 | | 数据渗出 | 带有变量插值的 `curl -X POST` 将数据发送到外部 URL | | 静默错误 | `2>/dev/null`、`\|\| true` — 失败的安全 Hook 静默通过 | | 缺少 Hook | 没有 PreToolUse Hook，没有用于会话结束验证的 Stop Hook | | 网络暴露 | Hook 中未限制速率的网络请求、未过滤的敏感文件访问 | | 会话启动 | 下载并执行远程脚本的 SessionStart Hook | | 包安装 | Hook 中的全局 `npm install -g`、`pip install`、`gem install`、`cargo install` | | 容器逃逸 | Docker `--privileged`、`--pid=host`、`--network=host`、Root 卷挂载 | | 凭证访问 | macOS Keychain、GNOME Keyring、/etc/shadow 读取 | | 反向 Shell | `/dev/tcp`、`mkfifo + nc`、Python/Perl Socket Shell | | 剪贴板访问 | `pbcopy`、`xclip`、`xsel`、`wl-copy` — 通过剪贴板渗出数据 | | 日志篡改 | `journalctl --vacuum`、`rm /var/log`、`history -c` — 反取证 | ### MCP 服务器安全 (23 条规则) | 内容 | 示例 | |------|----------| | 高风险服务器 | Shell/命令类 MCP、具有 Root 访问权限的文件系统、数据库 MCP、浏览器自动化 | | 供应链 | `npx -y` 未经确认自动安装 — 域名抢注攻击向量 | | 硬编码机密 | MCP 环境配置中的 API Token，而非环境变量引用 | | 远程传输 | 连接到远程 URL 的 MCP 服务器 (SSE/streamable HTTP) | | Shell 元字符 | MCP 服务器命令参数中的 `&&`、`\|`、`;` | | 缺少元数据 | 无版本锁定、无描述、服务器数量过多 | | 敏感文件参数 | `.env`、`.pem`、`credentials.json` 作为服务器参数传递 | | 网络暴露 | 绑定到 `0.0.0.0` 而非 localhost | | 自动批准 | 跳过工具调用用户确认的 `autoApprove` 设置 | | 缺少超时 | 高风险服务器无超时设置 — 资源耗尽风险 | ### Agent 配置审查 (25 条规则) | 内容 | 示例 | |------|----------| | 无限制工具 | 拥有 Bash 访问权限、无 `allowedTools` 限制的 Agent | | 提示注入面 | 处理外部/用户提供内容且无防御措施的 Agent | | 自动运行指令 | `CLAUDE.md` 包含“Always run”、“without asking”、“automatically install” | | 隐藏指令 | Unicode 零宽字符、HTML 注释、Base64 编码的指令 | | URL 执行 | `CLAUDE.md` 指示 Agent 获取并执行远程 URL | | 定时炸弹 | 由时间或缺失条件触发的延迟执行指令 | | 数据收集 | 批量收集密码、凭证或数据库转储 | | 提示反射 | `ignore previous instructions`、`you are now`、DAN 越狱、伪造系统提示 | | 输出操纵 | `always report ok`、`remove warnings from output`、抑制安全发现 | ## 功能特性 ### 自动修复引擎 (`--fix`) 自动应用安全修复： - 将硬编码机密替换为 `${ENV_VAR}` 引用 - 收紧通配符权限（`Bash(*)` → 限定范围的 `Bash(git *)`、`Bash(npm *)`） 仅应用标记为 `auto: true` 的修复。权限更改需要人工审查。 ### 安全初始化 (`agentshield init`) 生成一个加固的 `.claude/` 目录，包含限定范围的权限、安全 Hook 和安全最佳实践。现有文件永不被覆盖。 ### Opus 4.6 深度分析 (`--opus`) 由 Claude Opus 4.6 驱动的三 Agent 对抗 Pipeline： 1. **红队 (攻击者)** — 寻找可利用的攻击向量和多步骤攻击链 2. **蓝队 (防御者)** — 评估现有防护并推荐加固措施 3. **审计员** — 将双方观点综合为优先级风险评估 攻击者发现带有 `${file}` 插值的 `curl` Hook + `Bash(*)` = 命令注入 Pivot。防御者指出不存在 PreToolUse Hook 来阻止它。审计员将它们整合为优先行动列表。 ``` agentshield scan --opus # Red + Blue run in parallel agentshield scan --opus --stream # Sequential with real-time output agentshield scan --opus --stream -v # Verbose — see full agent reasoning ``` ``` ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Phase 1a: ATTACKER (Red Team) ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ✓ Attacker analysis complete (4521 tokens) ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Phase 1b: DEFENDER (Blue Team) ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ✓ Defender analysis complete (3892 tokens) ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Phase 2: AUDITOR ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ Risk Level: CRITICAL Opus Score: █████░░░░░░░░░░░░░░░ 15/100 ``` 需要 `ANTHROPIC_API_KEY` 环境变量。 ### 输出格式 | 格式 | 标志 | 用例 | |--------|------|----------| | Terminal | `--format terminal` (默认) | 交互式使用 | | JSON | `--format json` | CI Pipeline、编程访问 | | Markdown | `--format markdown` | 文档、PR | | HTML | `--format html` | 自包含的可分享报告（深色主题，所有 CSS 内联） | ## GitHub Action ``` - name: AgentShield Security Scan uses: affaan-m/agentshield@v1 with: path: "." min-severity: "medium" fail-on-findings: "true" ``` **输入参数：** | 输入 | 默认值 | 描述 | |-------|---------|-------------| | `path` | `.` | 扫描路径 | | `min-severity` | `medium` | 最低严重级别：critical、high、medium、low、info | | `fail-on-findings` | `true` | 如果发现达到严重级别阈值则使 Action 失败 | | `format` | `terminal` | 输出格式 | **输出：** `score` (0–100)、`grade` (A–F)、`total-findings`、`critical-count` 该 Action 会写入 Markdown Job Summary，并在受影响文件上以内联方式发出 GitHub Annotations。 ## CLI 参考 ``` agentshield scan [options] Scan configuration directory -p, --path Path to scan (default: ~/.claude or cwd) -f, --format Output: terminal, json, markdown, html --fix Auto-apply safe fixes --opus Enable Opus 4.6 multi-agent analysis --stream Stream Opus analysis in real-time --min-severity Filter: critical, high, medium, low, info -v, --verbose Show detailed output agentshield init Generate secure baseline config agentshield miniclaw start [opts] Launch MiniClaw secure agent server -p, --port Port (default: 3847) -H, --hostname Hostname (default: localhost) --network Network: none, localhost, allowlist --rate-limit Max req/min per IP (default: 10) --sandbox-root Root path for sandboxes --max-duration Max session duration (default: 300000) ``` ## 安全规则摘要 | 类别 | 规则数 | 模式数 | 严重级别范围 | |----------|-------|----------|----------------| | Secrets | 10 | 14 | Critical -- Medium | | Permissions | 10 | -- | Critical -- Medium | | Hooks | 34 | -- | Critical -- Low | | MCP Servers | 23 | -- | Critical -- Info | | Agents | 25 | -- | Critical -- Info | | **总计** | **102** | **14** | | ## 架构 ``` src/ ├── index.ts CLI entry point (commander) ├── action.ts GitHub Action entry point ├── types.ts Type system + Zod schemas ├── scanner/ │ ├── discovery.ts Config file discovery │ └── index.ts Scan orchestrator ├── rules/ │ ├── index.ts Rule registry │ ├── secrets.ts Secret detection (10 rules, 14 patterns) │ ├── permissions.ts Permission audit (10 rules) │ ├── mcp.ts MCP server security (23 rules) │ ├── hooks.ts Hook analysis (34 rules) │ └── agents.ts Agent config review (25 rules) ├── reporter/ │ ├── score.ts Scoring engine (A-F grades) │ ├── terminal.ts Color terminal output │ ├── json.ts JSON + Markdown output │ └── html.ts Self-contained HTML report ├── fixer/ │ ├── transforms.ts Fix transforms (secret, permission, generic) │ └── index.ts Fix engine orchestrator ├── init/ │ └── index.ts Secure config generator ├── opus/ │ ├── prompts.ts Attacker/Defender/Auditor system prompts │ ├── pipeline.ts Three-agent Opus 4.6 pipeline │ └── render.ts Opus analysis rendering └── miniclaw/ ├── types.ts Core type system (immutable, readonly) ├── sandbox.ts Sandbox lifecycle + path validation ├── router.ts Prompt sanitization + output filtering ├── tools.ts Whitelist-based tool authorization ├── server.ts HTTP server with rate limiting + CORS ├── dashboard.tsx React dashboard component └── index.ts Entry point and re-exports ``` ## MiniClaw MiniClaw 是与 AgentShield 捆绑的极简、沙箱化 AI Agent 运行时。典型的 Agent 平台暴露许多攻击面（Telegram、Discord、电子邮件、社区插件），而 MiniClaw 仅提供**单一 HTTP Endpoint**，由**隔离沙箱**支持。 ``` # 从安全默认值开始（localhost:3847，无网络，仅限安全工具） npx ecc-agentshield miniclaw start # 自定义配置 npx ecc-agentshield miniclaw start --port 4000 --network localhost --rate-limit 20 ``` 或作为库使用： ``` import { startMiniClaw } from 'ecc-agentshield/miniclaw'; const { server, stop } = startMiniClaw(); // Listening on http://localhost:3847 ``` ### 安全模型 四个独立执行的层级： ``` Request → [Rate Limit] → [CORS] → [Size Cap] → [Sanitize Prompt] ↓ [Tool Whitelist] ↓ [Sandbox FS] ↓ [Filter Output] → Response ``` - **服务器** — 速率限制 (10 req/min/IP)、CORS、10KB 请求上限、仅限 localhost 绑定 - **Prompt Router** — 过滤 12+ 类注入模式（系统提示覆盖、身份重分配、越狱、数据渗出 URL、零宽 Unicode、Base64 Payload） - **工具白名单** — 三个层级：Safe (read/search/list)、Guarded (write/edit)、Restricted (bash/network — 默认禁用) - **Sandbox** — 每会话隔离文件系统、路径遍历阻断、符号链接逃逸检测、扩展名白名单、10MB 文件上限、5 分钟超时、默认无网络 ### API | 方法 | 端点 | 描述 | |--------|----------|-------------| | `POST` | `/api/prompt` | 发送 Prompt | | `POST` | `/api/session` | 创建沙箱会话 | | `GET` | `/api/session` | 会话信息 | | `DELETE` | `/api/session/:id` | 销毁会话 + 清理 | | `GET` | `/api/events/:sessionId` | 安全审计事件 | | `GET` | `/api/health` | 健康检查 | MiniClaw 具有**零外部运行时依赖** — 仅使用 Node.js 内置模块 (`http`、`fs`、`path`、`crypto`)。可选的 React 仪表盘需要 React 18+ 作为 Peer Dependency。 ## 开发 ``` npm install # Install dependencies npm run dev # Development mode npm test # Run tests (912 tests) npm run test:coverage # Coverage report npm run typecheck # Type check npm run build # Build npm run scan:demo # Demo scan against vulnerable examples ``` ## 发布渠道 AgentShield 可通过多种渠道获取： | 渠道 | 用例 | 安装方式 | |---------|----------|---------| | **Standalone CLI** | 从终端直接扫描 | `npm install -g ecc-agentshield` 或 `npx ecc-agentshield scan` | | **GitHub Action** | CI/CD 中对 PR 进行自动化安全检查 | `uses: affaan-m/agentshield@v1` | | **ECC Plugin** | 通过 ECC 技能生态系统的 Claude Code 用户 | 通过 [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) 安装 | | **ECC Tools GitHub App** | 跨 GitHub 组织的集成扫描 | 在 [github.com/apps/ecc-tools](https://github.com/apps/ecc-tools) 安装 | ## 许可证 MIT