AgentShield（affaan-m 出品，MIT，约 1.1 千星，Everything Claude Code 生态）是 AI agent 配置的安全审计器：扫描你的 ~/.claude/（及 Cursor 等类似目录），检查硬编码密钥、权限配置错误、钩子注入、MCP 服务器风险和提示注入面，输出分级安全报告。有 CLI、GitHub Action、GitHub App 三种形态。

一句话：装任何社区技能/MCP/钩子之前，先跑一遍它——它是只读的，不改任何东西。

你给 Claude Code 装了一堆插件、技能、MCP 服务器，配置里到底有没有密钥泄露、危险权限、可疑钩子？AgentShield 就是干这个的：扫描 Claude Code 配置，检查密钥、权限、钩子（hooks）、MCP 服务器与提示注入面，输出分级安全报告。它最让人放心的一点是只读：扫描不改任何配置（实测零写面），所以你可以随时跑、放心跑。用法上有两条路：npx 免安装试跑（本环境实测），或全局安装长期用（官方推荐）。

什么时候用：

• 你刚装了一堆 Agent 插件/技能，想看看配置里有什么风险面；
• 你要在 CI 或提 PR 前做一次 Agent 配置安全检查；
• 你要把扫描结果交给 Agent/CI 决策（-f json 机器可读）。

什么时候别用：你需要的是修复而不是检查时——它只报告，不修。

note: 免安装形态（本环境实测）；国内用 npmmirror registry

# 来源: Trove 详细指南 · 验证于 2026-08-28
npm_config_registry=https://registry.npmmirror.com npx -y ecc-agentshield scan

预期输出: AgentShield Security Report（目标 = 自动发现的 ~/.claude/ 或当前目录；分级报告 + 发现清单）

一条命令 + 版本确认：

# 来源: Trove 详细指南 · 验证于 2026-08-28
npx -y ecc-agentshield --version

预期输出: 1.5.0（本环境实测）

# 来源: Trove 详细指南 · 验证于 2026-08-28
npx -y ecc-agentshield scan

预期输出: Security Report（分级 + 发现清单；扫描只读，跑多少次都不改配置）

• 版本号正常输出 = 包可拉取可执行；
• 扫描出报告（哪怕全是低危/无发现）= 扫描链路通。

npm 包 ecc-agentshield，CLI 命令 agentshield scan。扫描目标 = 自动发现的 ~/.claude/ 或当前目录（也可指定目录），输出分级报告 + 发现清单（Secrets / Permissions / Hooks / MCP Servers / Agents 分项 + 文件级发现）。

两种使用形态：

• 方式 A：npx 直接扫描（免安装，本环境实测）；
• 方式 B：全局安装（官方推荐长期使用）。

装完它动哪里：不动——扫描零写面；全局安装只写 npm 全局目录。

实测命令 = npx ecc-agentshield scan（2026-08-28 本环境验证，npm 包 ecc-agentshield 1.5.0，npmmirror）；GitHub release v1.4.0（2026-03-22）无资产，官方分发走 npm；扫描 = 只读（实测无写面）；无后台进程；npm 包内有全局安装形态（npm i -g ecc-agentshield）

第 1 步：跑第一次扫描

讲解：npx 形态不落地全局，一次扫描即用即走，适合先看结果再决定要不要长期装。国内 npm 直连慢，用 npmmirror registry 前缀。第一次扫描目标 = 自动发现的 ~/.claude/ 或当前目录。

# 来源: Trove 详细指南 · 验证于 2026-08-28
npm_config_registry=https://registry.npmmirror.com npx -y ecc-agentshield scan

预期输出: AgentShield Security Report（目标 = 自动发现的 ~/.claude/ 或当前目录；分级报告 + 发现清单）

装好确认：

• 输出 Security Report，有分级与发现清单；
• 确认版本：npx -y ecc-agentshield --version → 1.5.0。

卡住怎么办：

• npx 拉包慢/失败 → 确认命令带 npm_config_registry=https://registry.npmmirror.com 前缀；
• 报 Node 版本问题 → 确认 Node >= 18。

第 2 步：长期使用装全局

讲解：全局安装后直接用 agentshield，适合把扫描挂进日常流程（CI、提 PR 前）。

# 来源: Trove 详细指南 · 验证于 2026-08-28
npm_config_registry=https://registry.npmmirror.com npm install -g ecc-agentshield
agentshield scan

预期输出: 同上（Security Report）

装好确认：

• agentshield --version 可用；
• agentshield scan 输出报告。

卡住怎么办：

• 全局命令找不到 → 确认 npm 全局 bin 目录在 PATH；
• 扫描到一堆发现不知道怎么处理 → 报告是分级的，先处理高危项（Secrets / 权限），再逐项看 Hooks/MCP。

第 3 步：扫指定目录 + 给 Agent 用

讲解：指定目录扫描（如 /path/to/.claude）针对特定配置；-f json 输出机器可读报告（2026-08-30 实测：JSON 含 timestamp/targetPath/findings[]/score/summary），便于 Agent 后处理。

# 来源: Trove 详细指南 · 验证于 2026-08-28
npx -y ecc-agentshield scan /path/to/.claude

预期输出: 安全报告（Secrets/Permissions/Hooks/MCP Servers/Agents 分项 + 文件级发现）

# 来源: Trove 详细指南 · 验证于 2026-08-28
npx -y ecc-agentshield scan -f json

预期输出: JSON 报告（实测字段：timestamp / targetPath / findings[]（id/severity/category/title/file/fix）/ score（grade/numericScore/breakdown）/ summary（totalFindings/critical/high/medium/low/info/filesScanned））

（2026-08-30 实测：-f json 可用）

卡住怎么办：

• -f json 输出异常 → 确认开关为 -f json（不是 --json）；
• 指定目录不存在/无权限 → 先确认路径存在且可读，再扫描。

启动与入口

无后台进程；入口 = agentshield scan（或 npx 形态）。

常用操作

操作一：查看版本（本环境实测）

# 来源: Trove 详细指南 · 验证于 2026-08-28
npx -y ecc-agentshield --version

预期输出: 1.5.0

操作二：扫描指定目录

# 来源: Trove 详细指南 · 验证于 2026-08-28
npx -y ecc-agentshield scan /path/to/.claude

预期输出: 安全报告（Secrets/Permissions/Hooks/MCP Servers/Agents 分项 + 文件级发现）

操作三：与 Agent 流程集成（扫描后把报告交给 Agent 决策）

# 来源: Trove 详细指南 · 验证于 2026-08-28
npx -y ecc-agentshield scan -f json

预期输出: JSON 报告（实测字段：timestamp / targetPath / findings[]（id/severity/category/title/file/fix）/ score（grade/numericScore/breakdown）/ summary（totalFindings/critical/high/medium/low/info/filesScanned））

（2026-08-30 实测：-f json 可用）

数据与目录

• 无专属数据目录；扫描只读 ~/.claude/（或指定目录）。

与工具页矩阵同源，共 19 对（3 实测兼容 / 16 推断可能兼容 / 0 推断可能冲突）；完整对子、状态与证据见 冲突对子（共装矩阵）。

• 暂无独立排障手册；安装/卸载问题先看 Agent 执行版 guide 注意事项

# 来源: Trove 详细指南 · 验证于 2026-08-28
npm rm -g ecc-agentshield 2>/dev/null || true; npm cache clean --force 2>/dev/null || true

note: npx 方式无全局残留（幂等）；全局安装需显式卸载；扫描零写面

# 来源: Trove 详细指南 · 验证于 2026-08-28
npm rm -g ecc-agentshield 2>/dev/null || true
npm ls -g ecc-agentshield 2>/dev/null | grep -q ecc-agentshield && echo '残留: ecc-agentshield 仍存在' || echo 'agentshield removed: OK'

预期输出: agentshield removed: OK

• 运行环境预检（需 Node >= 18）
• 官方 npm 路径（本环境实测）；国内推荐 npmmirror registry
• 每条操作 = 一个命令块 + 预期输出
• npx 方式无全局残留（幂等）；全局安装需显式卸载；扫描零写面
• 只读：扫描不写任何文件（实测零写面），可放心放进 Agent 流程

• 问：扫描会改我的配置吗？答：不会。只读审计器，实测零写面。
• 问：npx 和全局安装选哪个？答：先用 npx 试跑（免安装）；长期用装全局（官方推荐）。
• 问：报告发现高危项怎么办？答：报告分级，先处理 Secrets 与权限类高危项；Hooks/MCP 按需逐项评估。本工具只报告不修复。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。

• 版本：[1.5.0, 1.5.0] 锁定（收录实测版本）。
• 环境：Node >= 18。
• 网络：npm 用 npmmirror 前缀（国内实测路径）。
• 写面：零（只读审计器，实测）；全局安装写 npm 全局目录。
• 共装：冲突矩阵无对子（只读工具，无共享写面）。

• 条目签名：affaan-m/agentshield（MIT，原样收录 npm 包 ecc-agentshield 1.5.0）

本站实测记录（2026-08-28）

• 未实测：-p 指定目录扫描（命令形态同默认扫描，--help 已确认开关）；--fix 自动修复（会写配置，本环境不跑）。

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

• 官方 README（npm 包内同源，v1.4.0）：AgentShield 完整用法 [官方文档 · AgentShield 官方 · 2026-08-31（包 1.4.0）]
  官方用法全解——Quick Start（npx 免安装扫描 / 全局安装）、扫描指定目录、--fix 自动修复（硬编码密钥→env 引用）、-f json CI 输出、HTML 报告、--opus 多模型对抗分析（需 API key）、init 生成安全基线配置、检测面（密钥 10 规则 14 模式 / 权限 10 规则 / hooks 34 规则 / MCP 23 规则 / Agent 配置 25 规则）、GitHub Action 形态、CLI 参考