AI Agent 安全体检 / Audit & Harden Your AI Agent

给你的 AI agent 做一次安全体检并加一层实时护盾：装第三方 skill / plugin / MCP 之前先静态扫一遍（24 条规则查后门、密钥窃取、混淆代码、数据外泄、Web3 钱包风险），运行时自动拦截危险动作，并产出一份可分享的可视化安全体检报告。

Audit and harden your AI agent: statically scan any third-party skill / plugin / MCP before you install it (24 rules for backdoors, secret theft, obfuscation, data exfiltration, Web3 wallet drains), block dangerous actions at runtime, and produce a shareable visual security checkup report.

底层工具是开源 CLI @goplus/agentguard（MIT，公开 npm 包）。核心 scan / guard / checkup 全部本地运行、零 API key、无需任何 Clawvard 后端、不需要 clone 任何私有仓库。本课只走本地扫描、体检和运行时护盾，不使用任何云同步或账号能力。

The skill behind this course is the open-source CLI @goplus/agentguard (MIT). Its scan / guard / checkup core runs entirely locally with no API key, no Clawvard backend, and no private repo. This course uses only the local scan, checkup, and runtime guard — never any cloud sync or account features.

1. 前置条件 / Prerequisites

本地 Node ≥ 18（包 engines 声明 node >=18.0.0），随附 npm。
任意一款带 agent 能力的工具（Claude Code / Codex / Cursor / OpenClaw …），用来接入运行时护盾和触发 /agentguard checkup。
完全离线可跑：零商业 API key、零 Clawvard key。任何云同步、账号登录或第三方威胁情报订阅本课一律不需要。
不需要访问任何私有仓库。下文用到的脆弱样例来自公开 GitHub 仓库 GoPlusSecurity/agentguard。

2. 安装与接入 / Install & wire it in

# 1) 全局安装护盾（公开 npm 包，MIT）
npm install -g @goplus/agentguard

# 2) 接入你当前的 agent（自动识别 Claude Code / Codex / OpenClaw …）
agentguard init --agent auto      # 也可显式 --agent claude-code

# 3) 确认就绪（本地配置、协议级别、审计日志路径；本地模式下没有任何云会话也是正常的）
agentguard status

要在 agent 里用 /agentguard checkup 这种斜杠命令，把官方 skill 装进你的 skills 目录（来自已安装的公开 npm 包，不是任何私有仓库）：

cp -r "$(npm root -g)/@goplus/agentguard/skills/agentguard" ~/.claude/skills/agentguard

3. 用法一：装第三方 skill 前先扫一遍 / Scan before you install

agentguard scan <dir> 用 24 条规则静态深扫一个 skill / plugin 目录，给出整体风险等级和命中清单。先用官方公开脆弱样例验证工具有效：

# 取公开样例（公开仓库，零凭据；npm 包本身不含该样例，所以从 GitHub 取）
git clone https://github.com/GoPlusSecurity/agentguard.git

# 扫官方脆弱样例 —— 稳定复现 CRITICAL
agentguard scan ./agentguard/examples/vulnerable-skill
# => CRITICAL: Found 40 findings: code execution, hardcoded secrets, dangerous Web3 patterns, data exfiltration
#    Tags: SHELL_EXEC, READ_SSH_KEYS, PRIVATE_KEY_PATTERN, MNEMONIC_PATTERN, WEBHOOK_EXFIL, WALLET_DRAINING, ...

# 再扫你真正想装的目标，给出同样格式的结论
agentguard scan /path/to/the-skill-you-want-to-install

读结论：整体等级（CRITICAL / HIGH / MEDIUM / LOW）+ 命中规则（如 SHELL_EXEC / READ_ENV_SECRETS / WEBHOOK_EXFIL / WALLET_DRAINING）+ 所在文件，最后给「可装 / 不可装 / 需修复后再装」的判断。需要机器可读时加 --json。

4. 用法二：给 agent 做安全体检 + 可分享报告 / Health checkup → shareable report

体检跨 6 个安全维度评估你的 agent（Skill & Code Safety / Credential & Secrets / Network & System / Runtime Protection / Web3 Safety / Trust），按 S/A/B/F 四档给出龙虾健康分，并生成自包含 HTML 报告——评分仪表 + 龙虾吉祥物（分数越低龙虾越虚弱）+ 6 维度卡片 + 可展开的 findings 与修复建议。

体检的「Code Safety」维度会扫描你已安装的 skill（~/.claude/skills/*/、~/.openclaw/skills/*/ 等带 SKILL.md 的目录）。要复现一个「装到了恶意 skill」的体检，把公开脆弱样例当作一个已安装 skill 放进来：

# 把公开脆弱样例装成一个 agent skill（给它一个最小 SKILL.md 清单即可被发现）
mkdir -p ~/.claude/skills/vulnerable-skill
cp ./agentguard/examples/vulnerable-skill/* ~/.claude/skills/vulnerable-skill/
printf -- '---\nname: vulnerable-skill\ndescription: intentionally vulnerable demo skill for AgentGuard testing\n---\n# Vulnerable Skill Demo\n' \
  > ~/.claude/skills/vulnerable-skill/SKILL.md

然后生成报告。两种零 key 路径都跑得通：

在 agent 内（推荐，报告最完整）：在 Claude Code 里运行 /agentguard checkup。skill 会逐个扫描已安装 skill，把每条命中喂给打分脚本，再渲染出可视化 HTML 报告（每条 CRITICAL 命中都会拉低 Code Safety 分，体检直接掉到低档）。这正是本课 showcase 报告的生成方式。
纯命令行：agentguard checkup —— 终端会打印 Full visual report: <path>.html，浏览器自动打开同一份报告。

收尾确认事件已被记录：

agentguard report     # 查看安全事件日志，落在 ~/.agentguard/audit.jsonl

体检产出：HTML 报告路径 + 总分/档位 + 最该先修的一条建议。

复现本课 showcase 报告（可选，零 LLM、确定性）/ Reproduce the showcase report

showcase 里的 security-checkup-report.html 由 /agentguard checkup 背后的两个公开脚本生成 —— 把对公开脆弱样例的真实扫描结果喂给打分器，再渲染（checkup CLI 会用自己的文件名打印报告路径，本课把它另存为 security-checkup-report.html 作为 showcase）：

SKILL_DIR="$(npm root -g)/@goplus/agentguard/skills/agentguard"
# raw-facts.json：每个已安装 skill 的扫描命中（rule/severity/file/line）+ 凭据/网络/运行时/Web3 事实
node "$SKILL_DIR/scripts/checkup-score.js"  --file raw-facts.json > checkup.json   # 确定性打分 → 53/100, Tier B
node "$SKILL_DIR/scripts/checkup-report.js" --file checkup.json                    # → 打印自包含 HTML 报告路径

5. 调试 tips / Troubleshooting

agentguard: command not found：确认全局 npm bin 在 PATH（npm bin -g 看路径），或用 npx @goplus/agentguard ...。
体检显示 0 installed skill(s)：说明没扫到带 SKILL.md 的已安装 skill —— 体检只发现含 SKILL.md 的目录；按用法二把样例装成带清单的 skill。
想要更严格的运行时拦截：agentguard config strict（默认 balanced）。被拦的动作会提示 agentguard approve --action-id ... --once，确认安全后再放行。
agentguard checkup 在无图形界面的机器上无法自动开浏览器是正常的 —— 报告 HTML 已写到打印出来的路径，手动打开即可。
看本地配置和审计路径：agentguard status；自检环境：agentguard doctor。

6. 你会拿到 / What you get

扫描结论：对任一 skill / plugin / MCP 目录的风险等级 + 命中规则 + 文件定位 +「能不能装」判断。
security-checkup-report.html：自包含、深色主题的安全体检报告（评分仪表 + 龙虾档位 + 6 维度卡片 + findings）。对应本课 showcase。
~/.agentguard/audit.jsonl：运行时安全事件日志（扫描命中、被拦动作）。
运行时护盾：接入后，agent 跑危险命令 / 读敏感文件 / 外泄数据时会被实时拦截或要求确认。

学习完成后

告诉用户：

我已经学会了 agentguard。给我一个想装的第三方 skill / plugin / MCP 目录，我先用 agentguard scan 扫一遍，给出风险等级 + 命中规则 + 能不能装的结论；需要的话再跑一次 /agentguard checkup，产出一份可分享的可视化 agent 安全体检报告（security-checkup-report.html）。全程本地、零 API key。