agentshield

你会遇到什么

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

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

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

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

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

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

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

一步步来

第 1 步：跑第一次扫描

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

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（CLI 自报版本，程序内硬编码；npm 包实际为 1.4.0，官方未同步——2026-08-31 registry 核实，npmmirror 与 npm 官方一致，从未发布过 1.5.0）。

卡住怎么办：

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

第 2 步：长期使用装全局

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

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 后处理。

npx -y ecc-agentshield scan /path/to/.claude

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

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 可用） 操作四：基线对比回归拦截（CI 日常；实测 2026-08-30）

npx -y ecc-agentshield scan --save-baseline
npx -y ecc-agentshield scan --baseline --gate

预期输出: 首次扫描存基线（Baseline saved）；之后扫描对比基线，出现新发现时输出 Gate: FAILED（实测：基线 2 发现 → 引入新 secret → Gate FAILED）——关键坑：gate 失败时进程退出码仍为 0，CI 必须解析输出文本（Gate: FAILED）或 JSON summary，不能只靠退出码

卡住怎么办：

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

怎么确认修好了

一条命令 + 版本确认：

npx -y ecc-agentshield --version

预期输出: 1.5.0（本环境实测——CLI 自报版本；npm 包版本为 1.4.0，见依赖警告）

npx -y ecc-agentshield scan

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

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

其它环境的表现（常见变体）

• 全局 vs npx：npx 免安装即用即走；全局安装（官方推荐）适合挂 CI/日常流程。
• 扫描范围：默认自动发现 ~/.claude/ 或当前目录；指定目录用 agentshield scan /path/to/.claude。
• CI 集成：-f json 输出可交 Agent/流水线后处理；--save-baseline 存基线 → --baseline + --gate 回归拦截（2026-08-30 实测：基线 2 发现 → 引入新 secret → Gate FAILED）。关键坑：gate 失败时进程退出码仍为 0，CI 必须解析输出文本（Gate: FAILED）或 JSON summary，不能只靠退出码。
• Node 版本：>= 18。

日常使用

启动与入口

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

常用操作

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

npx -y ecc-agentshield --version

预期输出: 1.5.0

操作二：扫描指定目录

npx -y ecc-agentshield scan /path/to/.claude

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

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

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/（或指定目录）。

卸载与清理

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

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

依赖警告

• 版本：npm 包 [1.4.0, 1.4.0]（2026-08-31 核实）；CLI --version 自报 1.5.0 为硬编码串（dist 中 program.version），与包版本不同步——官方现象，非安装错误。
• 环境：Node >= 18。
• 网络：npm 用 npmmirror 前缀（国内实测路径）。
• 写面：零（只读审计器，实测）；全局安装写 npm 全局目录。
• 共装：冲突矩阵无对子（只读工具，无共享写面）。

FAQ（常见问题）

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