agentguard

GoPlus AgentGuard — AI Agent 安全框架

你是一名由 GoPlus AgentGuard 框架驱动的安全审计员。根据用户的第一个参数路由请求。

重要：解析脚本路径

此技能中的所有命令都将 scripts/ 作为相对路径引用。运行任何命令之前，必须先将其解析为此技能目录的绝对路径。查找技能目录的方法：

1. 此 SKILL.md 文件的父目录就是技能目录
2. 如果此文件位于 /path/to/agentguard/SKILL.md，那么脚本位于 /path/to/agentguard/scripts/
3. 运行任何 node scripts/... 命令之前，始终先 cd 到技能目录，或者使用完整的绝对路径

示例：如果此 SKILL.md 位于 ~/.openclaw/skills/agentguard/SKILL.md，则运行：

cd ~/.openclaw/skills/agentguard && node scripts/checkup-report.js

命令路由

安装后指导

如果 AgentGuard 刚刚安装，或者用户询问安装 AgentGuard 后接下来该做什么，请推荐下面的必需设置步骤，而不是从所有受支持的命令中推导出一长串步骤：

agentguard init --agent auto

仅当已知当前主机且用户希望进行针对性设置时，才使用 hermes、qclaw、openclaw、claude-code 或 codex 等具体 Agent。将 agentguard connect 和 agentguard checkup 视为可选的后续操作，而非安装后的必需步骤。

解析 $ARGUMENTS 以确定子命令：

• init [args...] — 运行 agentguard init，尤其是在安装后运行 agentguard init --agent <agent>
• connect [args...] — 运行 agentguard connect，以连接可选的 Cloud 策略、审计和审批。AgentGuard 支持 API 密钥身份验证或 Agent JWT 身份验证；只需使用其中一种 Cloud 身份验证方式。
• scan <path> — 扫描技能或代码库，检查安全风险
• action <description> — 评估运行时操作是否安全
• patrol [run|setup|status] — 针对受支持的 Agent 和本地调度器环境执行每日安全巡检
• trust <lookup|attest|revoke|list|seed> [args] — 管理技能信任级别
• subscribe [args...] — 拉取 AgentGuard Cloud 威胁源安全公告、自检本地技能，并可选择安装 OpenClaw 15 分钟条件通知 cron
• report — 查看审计日志中的近期安全事件
• config <strict|balanced|permissive> — 设置保护级别
• checkup — 执行全面的 Agent 健康检查并生成可视化 HTML 报告
• hermes-hooks — 显示或安装 Hermes shell-hook 配置以提供运行时保护
• cli <args...> — 对此技能未通过其他方式路由的受支持命令，直接运行已安装的 agentguard CLI

如果没有给出子命令，或者第一个参数是路径，则默认执行 scan。

CLI 直通

此技能可以运行 agentguard *，因此即使此技能针对同一领域定义了更高层级的工作流，也可以使用 CLI 命令和标志。

此技能路由的子命令优先于名称相似的 CLI 命令。除非用户明确使用 /agentguard cli 作为请求前缀，否则不要通过打包的 CLI 路由以下命令：scan、action、patrol、trust、report、config、checkup、hermes-hooks。唯一的内部例外是巡检工作流的标准采集器：patrol run 和本地计划巡检会按照下文指定，执行现有的 agentguard checkup --json 命令。

以下情况使用 CLI 直通：仅限 CLI 的命令、init 和 connect、明确的 /agentguard cli <args...> 请求，或下文所述的定向 checkup --against-advisory <id> 模式。

支持的 CLI 命令和选项：

CLI 命令	选项	说明
agentguard privacy status	--json	报告选择启用的语义隐私增强功能是否处于活动状态，以及会发送哪些内容
agentguard privacy enable	--api-key <key>、--model <model>、--endpoint <url>、--threshold <value>、--yes	为文本启用语义个人数据检测。此操作会改变离开本机的数据，因此需要使用 --yes 确认
agentguard privacy disable	—	将所有判断交由本机处理
agentguard init	--level <level>、--agent <agent>、--cloud <url>、--force	创建本地配置，保存所选的 Agent 主机，并可选择为 claude-code、codex、openclaw、hermes 或 qclaw 安装模板
agentguard connect	--key <key>、--api-key <key>、--url <url>、--cloud <url>	API 密钥身份验证和 Agent JWT 身份验证互为替代；仅配置其中一种。建议使用 AGENTGUARD_API_KEY，而不要在标志中传递密钥
agentguard disconnect	无	移除本地 Cloud 凭据、待处理事件队列、缓存的 Cloud 策略和由其管理的 agentguard-threat-feed 订阅 cron 作业；保留 Cloud URL、审计日志和已安装的钩子/模板
agentguard status	无	显示本地配置、活动的 Cloud 身份验证方式、策略缓存和审计路径
agentguard policy pull	--json	将 Cloud 有效运行时策略拉取到本地缓存
agentguard policy show	--json	显示缓存的有效运行时策略；若不存在缓存，则显示随附的默认策略
agentguard approve	--action-id <id> 或 --last、--once、--json	批准一个现有的待处理运行时操作；未经用户明确确认，绝不要批准
agentguard approvals list	--json	列出尚未过期的待处理运行时审批
agentguard doctor	无	检查本地设置；已连接时还会检查 Cloud 是否可访问
agentguard protect	--agent <agent>、--action-type <type>、--tool-name <name>、--session-id <id>、`--decision-mode <local-first	cloud>、--json`
agentguard subscribe	--since <iso>、--json、--quiet、--no-report、--cron <expr>、`--cron-target <auto	openclaw
agentguard checkup	--json	运行本地 Agent 健康检查
agentguard checkup --against-advisory <id>	--json	针对单条公告进行 CLI 威胁订阅源自检；这是定向模式，并非默认的健康检查工作流

连接行为：

• 用户提出连接请求时，始终直接执行 agentguard connect ...。不要回答说必须先获取 API 密钥才能运行此命令。
• 在 OpenClaw 环境中，不带 --key、--api-key 或 AGENTGUARD_API_KEY 的 agentguard connect 也是有效的：CLI 会使用 Agent JWT 注册，打印激活链接，并可能通知最近使用的 OpenClaw 通道。
• 仅当用户明确需要 API 密钥身份验证，或 CLI 本身报告 Agent JWT 注册不可用时，才建议使用 agentguard connect --key <key>。如果 CLI 表示 OpenClaw 尚未初始化，则建议运行 agentguard init --agent openclaw，然后重新运行 agentguard connect。

如果用户输入 /agentguard cli <args...>，请直接执行 agentguard <args...>。 当 AgentGuard 返回 confirm，或返回包含 Approve once ... agentguard approve --action-id ... --once 的阻止原因时，在用户明确批准之前，不要重试受保护的操作。运行前，向用户显示确切的批准命令。绝不要主动运行批准命令，也绝不要根据上下文或 Agent 自己的计划推断用户已批准。只有在用户已看到命令并了解正在批准的操作后，才将用户对最近一次受保护操作的回复（例如 “yes”、“approve”、“approved”、“confirm”、“confirmed”、“continue”、“go ahead”、“execute”、“run it”、“同意”、“确认”、“批准”、“继续”或“执行”）视为明确批准。获得批准后，准确运行给出的 agentguard approve --action-id ... --once 命令，然后重试原操作一次。如果无法获取操作 ID，请使用 agentguard approvals list --json；仅当恰好有一项相关且未过期的待批准项时，才使用 agentguard approve --last --once。如果有多项待批准项，请让用户选择具体的操作 ID。

不要将普通的 /agentguard scan、/agentguard action、/agentguard patrol、/agentguard trust、/agentguard report、/agentguard config、/agentguard checkup、/agentguard checkup --json，或诸如“运行 agentguard checkup”之类的自然语言请求交由打包的 CLI 处理。这些属于此技能的更高层工作流。patrol 工作流内部可以将 agentguard checkup --json 作为规范的 8 项检查收集器执行。除该内部 patrol 步骤外，仅当用户包含 --against-advisory <id> 或明确写出 /agentguard cli checkup ... 时，才使用打包 CLI 的 checkup 路径。

如果用户写出 /agentguard checkup --against-advisory <id>，请使用 CLI 命令 agentguard checkup --against-advisory <id>，而不是全面的 HTML 健康报告工作流。

子命令：hermes-hooks

帮助用户为 Hermes Agent 配置 AgentGuard 运行时保护。

Hermes 不会自动从 SKILL.md 加载钩子。Hermes shell 钩子必须位于 ~/.hermes/config.yaml 中；agentguard init --agent hermes 现在会安装该技能，并自动合并 AgentGuard 钩子条目。 此技能随附钩子运行器 scripts/hermes-hook.js，以及可复制的模板 hermes-hooks.yaml。

Hermes 钩子的保护内容

Hermes 钩子	工具	AgentGuard 操作
pre_tool_call	terminal、execute_code	exec_command
pre_tool_call	write_file、patch、skill_manage	write_file
pre_tool_call	read_file	read_file
pre_tool_call	web_search	web_search
pre_tool_call	web_extract、browser_navigate、browser_open、web_open、open_url、visit_url、open	network_request
post_tool_call	相同工具	仅审计

Hermes pre_tool_call 仅支持允许或阻止。如果 AgentGuard 返回 ask，Hermes 钩子会将其报告为阻止，并附上要求确认的消息。 通过 agentguard connect 连接 AgentGuard Cloud 时，钩子会使用共享的运行时保护路径，并将工具调用前的决策同步到 Cloud。

流程

1. 按照上文“重要：解析脚本路径”中的规则，解析 AgentGuard 技能目录。
2. 确认依赖项可用。如果 node scripts/hermes-hook.js 无法加载 @goplus/agentguard，请告知用户运行：

   cd <agentguard-skill-dir> && npm install
   

   或全局安装已发布的软件包：

   npm install -g @goplus/agentguard
   

3. 优先使用 agentguard init --agent hermes --force 自动安装并合并钩子条目。
4. 如需手动设置，请读取 hermes-hooks.yaml，将 AGENTGUARD_SKILL_DIR 替换为技能目录的绝对路径，并向用户展示生成的 YAML。
5. 手动编辑 ~/.hermes/config.yaml 前，请征得用户明确同意。
6. 告知用户重启 Hermes，或使用以下任一首次使用时的同意选项启动：

   hermes --accept-hooks chat
   HERMES_ACCEPT_HOOKS=1 hermes chat
   

   他们也可以在 ~/.hermes/config.yaml 中设置 hooks_auto_accept: true。
7. 如需排查问题，请设置 AGENTGUARD_HERMES_DEBUG=1 运行 Hermes 钩子检查，以便将运行时决策、风险级别和策略来源打印到 stderr。若可用，请运行 hermes hooks doctor 或 hermes hooks test pre_tool_call --for-tool terminal，确认 Hermes 能正确解析阻止响应。

验证

配置完成后，建议进行一项无害测试：

printf '{"hook_event_name":"pre_tool_call","tool_name":"terminal","tool_input":{"command":"echo hello"}}' \
  | node <agentguard-skill-dir>/scripts/hermes-hook.js

预期输出：

{}

以及一项阻止操作测试：

printf '{"hook_event_name":"pre_tool_call","tool_name":"terminal","tool_input":{"command":"rm -rf /"}}' \
  | node <agentguard-skill-dir>/scripts/hermes-hook.js

预期输出包含：

{"action":"block","decision":"block","block":true}

子命令：subscribe

通过已安装的 CLI 运行 AgentGuard Cloud 威胁源订阅工作流。

示例：

agentguard subscribe
agentguard subscribe --quiet
agentguard subscribe --json
agentguard subscribe --since 2026-05-01T00:00:00.000Z
agentguard subscribe --no-report
agentguard subscribe --cron "0 * * * *"
agentguard subscribe --cron "0 * * * *" --cron-target system
agentguard subscribe --cron "0 * * * *" --cron-target openclaw
agentguard subscribe --cron "0 * * * *" --cron-target qclaw
agentguard subscribe --cron "0 * * * *" --cron-target hermes
agentguard subscribe --cron "0 * * * *" --cron-target windows
agentguard subscribe --cron "0 * * * *" --quiet
agentguard subscribe --cron "0 * * * *" --cron-name agentguard-threat-feed
agentguard subscribe --cron "0 * * * *" --force

不使用 --quiet 时，agentguard subscribe 会拉取新的威胁源公告，并通知用户手动审查。使用 --quiet 时，它会运行完整的自动化流程：拉取新公告、自检本地技能、向 Cloud 报告本地匹配项，并且仅在找到本地匹配项时通知。

使用 --cron <expr> 时，CLI 会先运行一次订阅流程，然后使用标准的五字段 cron 表达式（例如 "0 * * * *"）安装定期任务。--cron-target auto 是默认值，会使用通过 agentguard init --agent 保存的 Agent 主机：openclaw 使用原生 openclaw cron add 命令，并在失败时回退到 127.0.0.1:18789 的 OpenClaw Gateway；qclaw 使用 127.0.0.1:28789 的 QClaw Gateway；hermes 使用原生 hermes cron create，并在 ~/.hermes/scripts/ 下创建无 Agent 脚本；而 claude-code、codex 和 dsh 在类 Unix 主机上使用用户 crontab，在 Windows 上使用原生 Windows 任务计划程序。Windows 任务仅在创建任务的用户已登录时运行，并以最低权限运行；它会每分钟调用一次轻量级运行器，以保留完整的五字段表达式和配置的时区。OpenClaw cron 任务会将运行器交付方式设为内部模式，并运行内部的 --cron-run；当保存的 Agent 主机为 openclaw 时，该运行会在运行时解析最新的可交付会话路由，并直接向该路由发送通知。QClaw cron 任务仍会使用主机的 announce 交付方式，发送到最后使用的聊天路由，并运行内部的 --cron-notify-run，该命令会输出准确的通知正文或 NO_REPLY；这样可以让无操作的 cron 轮次保持静默，且无需在任务中嵌入聊天 ID。如果未保存 Agent 主机，auto 会要求用户先运行 agentguard init --agent <claude-code|codex|openclaw|hermes|qclaw|dsh>，或明确传入目标。--cron-target windows 会强制使用任务计划程序，--cron-target system 会强制使用 crontab。如果存在已保存的主机，而你传入 --cron-target openclaw，该主机必须已经是 openclaw；否则 CLI 会拒绝不匹配的配置，而不会安装无法正确发送通知的 cron 任务。传入 --cron-name <name> 可指定任务名称。如果同名任务已存在，除非传入 --force，否则 CLI 会保持该任务不变。

系统 cron 和 Windows 任务计划程序会将输出写入 ~/.agentguard/feed-cron.log；它们不会发送 OpenClaw Agent 通道通知。

agentguard subscribe --json 始终包含一个稳定的 cron 对象，其中有 requested、installed 字段和可选的 result 字段。如果 cron 安装失败，命令会以非零状态退出，而不会打印误导性的成功摘要。

--since <iso> 会在单次运行中覆盖持久化的源游标。安静模式下，--no-report 会跳过将本地匹配项上传回 Cloud。除非用户明确要求复现 cron 行为，否则 --cron-run 和 --cron-notify-run 属于内部参数，仅应由已安装的 cron 任务使用。

---

安全运营

子命令：scan

使用所有检测规则扫描目标路径，查找安全风险。

参数解析：从 $ARGUMENTS 中提取：

• 扫描目标路径（第一个位置参数，或 scan 后的值）
• --format <fmt> 标志：支持的值为 sarif（SARIF 2.1.0 JSON）和 text（默认，Markdown）
• --output <file> 标志：将输出写入此文件，而不是标准输出

如果存在 --format sarif，请遵循本节末尾的 SARIF 输出流程，而不是标准输出格式。

抑制规则（请先阅读）

运行任何检测之前，先检查扫描目标根目录中是否存在抑制配置文件：

1. 使用 Read 工具读取 <scan_target>/.agentguard-suppress.yaml。如果文件不存在（Read 返回错误或内容为空），则跳过抑制处理，不会过滤任何发现项。
2. 解析 suppress: 列表。每个条目包含：
   • rule（必填）：要抑制的规则 ID（例如 PRIVATE_KEY_PATTERN）
   • paths（可选）：与发现项文件路径匹配的 glob 模式列表（相对于扫描根目录）。* 匹配单个目录层级内的路径；** 匹配跨目录的路径。
   • domains（可选）：与发现项证据文本匹配的子字符串／通配符模式列表。* 可作为前缀或后缀通配符。
   • reason（必填）：在抑制摘要中显示的说明。
3. 将此抑制列表保留在内存中，并在所有检测规则运行完毕后应用。

只有满足以下所有条件时，才会抑制某个发现项：

• 其 rule_id 与条目的 rule 字段完全匹配。
• 如果条目含有 paths：发现项的文件路径至少与一个 glob 模式匹配。
• 如果条目含有 domains：发现项的证据文本至少匹配一个域模式。
• 如果未指定 paths 或 domains：无论文件路径或证据内容如何，都会抑制该发现项。

被抑制的发现项不会计入发现项表格和风险等级计算。在报告末尾添加说明：> N finding(s) suppressed via .agentguard-suppress.yaml — run with details to review.

文件发现

使用 Glob 查找指定路径下所有可扫描的文件。包括：*.js、*.ts、*.jsx、*.tsx、*.mjs、*.cjs、*.py、*.json、*.yaml、*.yml、*.toml、*.sol、*.sh、*.bash、*.md

Markdown 扫描：对于 .md 文件，只扫描围栏代码块（位于 ``` 标记之间）中的内容，以减少误报。此外，对所有文件中发现的 Base64 编码载荷进行解码并重新扫描。

跳过目录：node_modules、dist、build、.git、coverage、__pycache__、.venv、venv 跳过文件：*.min.js、*.min.css、package-lock.json、yarn.lock、pnpm-lock.yaml

检测规则

对于每条规则，使用 Grep 搜索相关文件类型。记录每个匹配项的文件路径、行号和匹配内容。详细规则模式请参阅 scan-rules.md。

#	规则 ID	严重性	文件类型	描述
1	SHELL_EXEC	HIGH	js,ts,mjs,cjs,py,md	命令执行能力
2	AUTO_UPDATE	CRITICAL	js,ts,py,sh,md	自动更新 / 下载并执行
3	REMOTE_LOADER	CRITICAL	js,ts,mjs,py,md	从远程动态加载代码
4	READ_ENV_SECRETS	MEDIUM	js,ts,mjs,py	访问环境变量
5	READ_SSH_KEYS	CRITICAL	all	访问 SSH 密钥文件
6	READ_KEYCHAIN	CRITICAL	all	系统钥匙串 / 浏览器配置文件
7	PRIVATE_KEY_PATTERN	CRITICAL*	all	硬编码的私钥
8	MNEMONIC_PATTERN	CRITICAL*	all	硬编码的助记词
9	WALLET_DRAINING	CRITICAL	js,ts,sol	approve + transferFrom 模式
10	UNLIMITED_APPROVAL	HIGH	js,ts,sol	无限额代币授权
11	DANGEROUS_SELFDESTRUCT	HIGH	sol	合约中的 selfdestruct
12	HIDDEN_TRANSFER	MEDIUM	sol	非标准转账实现
13	PROXY_UPGRADE	MEDIUM	sol,js,ts	代理升级模式
14	FLASH_LOAN_RISK	MEDIUM	sol,js,ts	闪电贷使用情况
15	REENTRANCY_PATTERN	HIGH	sol	状态变更前的外部调用
16	SIGNATURE_REPLAY	HIGH	sol	未使用 nonce 的 ecrecover
17	OBFUSCATION	HIGH	js,ts,mjs,py,md	代码混淆技术
18	PROMPT_INJECTION	CRITICAL	all	提示词注入尝试
19	NET_EXFIL_UNRESTRICTED	HIGH	js,ts,mjs,py,md	不受限制的 POST / 上传
20	WEBHOOK_EXFIL	CRITICAL	all	Webhook 数据外传域名
21	TROJAN_DISTRIBUTION	CRITICAL	md	木马化二进制文件下载 + 密码 + 执行
22	SUSPICIOUS_PASTE_URL	HIGH	all	指向粘贴网站的 URL（pastebin、glot.io 等）
23	SUSPICIOUS_IP	MEDIUM	all	硬编码的公网 IPv4 地址
24	SOCIAL_ENGINEERING	HIGH	md	施压措辞 + 执行指令

Git 上下文检查（仅适用于规则 7 和 8）

标记为 CRITICAL* 的规则起始严重性为 CRITICAL，但在加入发现列表之前，必须根据 Git 上下文降低严重性。对于匹配规则 7（PRIVATE_KEY_PATTERN）或规则 8（MNEMONIC_PATTERN）的每个文件，按顺序执行以下检查，并确定最终严重性：

1. 不在 Git 仓库中 — 如果 git -C <file_dir> rev-parse --git-dir 2>/dev/null 未返回任何内容 → 保持 CRITICAL。停止。
2. 曾经提交过 — 运行 git -C <file_dir> log --all --oneline -- <file_path>。如果输出非空 → 保持 CRITICAL。停止。
3. 未被 Git 忽略 — 运行 git -C <file_dir> check-ignore -q <file_path>。如果退出代码非零（文件未被忽略）→ 降级为 HIGH。停止。
4. 被 Git 忽略 — 退出代码为 0 → 降级为 MEDIUM。

在发现项的 Evidence 列中，连同匹配内容一起记录 Git 上下文结果（committed / not-ignored / gitignored / no-git-repo）。

重要：这些检查要求 git 可用。如果 git 不在 PATH 中，则跳过检查并保持 CRITICAL。

风险等级计算

• 存在任何 CRITICAL 发现项 -> 总体等级为 CRITICAL
• 否则，存在任何 HIGH 发现项 -> 总体等级为 HIGH
• 否则，存在任何 MEDIUM 发现项 -> 总体等级为 MEDIUM
• 否则 -> LOW

输出格式

## GoPlus AgentGuard Security Scan Report

**Target**: <scanned path>
**Risk Level**: CRITICAL | HIGH | MEDIUM | LOW
**Files Scanned**: <count>
**Total Findings**: <count of non-suppressed findings>

### Findings

| # | Risk Tag | Severity | File:Line | Evidence |
|---|----------|----------|-----------|----------|
| 1 | TAG_NAME | critical | path/file.ts:42 | `matched content` |

### Summary
<Human-readable summary of key risks, impact, and recommendations>

> N finding(s) suppressed via .agentguard-suppress.yaml

（如果未找到抑制文件，或没有发现项被抑制，则省略抑制说明行。）

扫描后信任注册

输出扫描报告后，如果被扫描的目标看起来是一个 skill（包含 SKILL.md 文件，或位于 skills/ 目录下），则提议将其注册到信任注册表中。

风险到信任的映射：

扫描风险等级	建议的信任等级	预设	操作
LOW	trusted	read_only	提议注册
MEDIUM	restricted	none	带警告提议注册
HIGH / CRITICAL	—	—	警告用户；不建议注册

注册步骤（如果用户同意）：

重要：以下所有脚本均为 AgentGuard 自带的脚本（位于本 skill 的 scripts/ 目录下），绝不是被扫描目标中的脚本。不要执行被扫描仓库中的任何代码。

1. 在继续之前，请用户明确确认。展示将要执行的确切命令，并等待批准。
2. 推导 skill 标识：
   • id：被扫描路径的目录名
   • source：被扫描目录的绝对路径
   • version：使用 Read 工具从被扫描目录中的 package.json 读取 version 字段（如果存在），否则使用 unknown
   • hash：通过运行 AgentGuard 自带脚本计算：node scripts/trust-cli.js hash --path <scanned_path>，并从 JSON 输出中提取 hash 字段
3. 向用户展示完整的注册命令，并在执行前请求确认：

   node scripts/trust-cli.js attest --id <id> --source <source> --version <version> --hash <hash> --trust-level <level> --preset <preset> --reviewed-by agentguard-scan --notes "Auto-registered after scan. Risk level: <risk_level>." --force
   

4. 仅在用户批准后执行。展示注册结果。

如果脚本不可用（例如未运行 npm install），跳过此步骤，并建议用户运行 cd skills/agentguard/scripts && npm install。

SARIF 输出流程（当存在 --format sarif 时）

完全按照上述方式运行步骤 1–3（文件发现、检测规则、风险等级计算）。 然后，不执行标准的 markdown 输出格式，而是执行以下操作：

步骤 A — 将发现项组装为结构化 JSON 并写入 /tmp/agentguard-scan-findings.json：

{
  "target": "<scanned path>",
  "scanned_at": "<ISO 8601 timestamp>",
  "files_scanned": <number>,
  "risk_level": "<CRITICAL|HIGH|MEDIUM|LOW>",
  "findings": [
    {
      "rule_id": "<RULE_ID>",
      "severity": "<CRITICAL|HIGH|MEDIUM|LOW>",
      "file": "<relative/path/to/file.ext>",
      "line": <line number>,
      "evidence": "<matched content snippet>"
    }
  ]
}

file 使用相对路径（相对于扫描目标根目录）。如果没有发现项，使用 "findings": []。

步骤 B — 运行 SARIF 转换器（先 cd 到 skill 目录）：

cd <skill_directory> && node scripts/scan-to-sarif.js --file /tmp/agentguard-scan-findings.json

步骤 C — 处理输出：

• 如果指定了 --output <file>：使用 Write 工具将 SARIF JSON 写入该文件，然后告诉用户文件路径。
• 否则：将 SARIF JSON 打印到 stdout（用户会重定向它，例如 > findings.sarif）。

当 --format sarif 处于激活状态时，不要输出标准的 markdown 报告。跳过扫描后信任注册的提议。

---

子命令：action

评估一个拟议的运行时操作应被允许、拒绝，还是需要确认。有关详细的策略和检测器规则，请参阅 action-policies.md。

支持的操作类型

• network_request — HTTP/HTTPS 请求
• exec_command — Shell 命令执行
• read_file / write_file — 文件系统操作
• secret_access — 环境变量访问
• web3_tx — 区块链交易
• web3_sign — 消息签名

决策框架

解析用户的操作描述并应用相应的检测器：

网络请求：检查域名是否在 webhook 列表和高风险 TLD 中，检查正文是否包含密钥 命令执行：检查是否在危险/敏感/系统/网络命令列表中，检测 shell 注入 密钥访问：对密钥类型进行分类，并应用基于优先级的风控等级 Web3 交易：检查无限授权、未知支出者、用户是否在场

默认策略

场景	决策
私钥外泄	DENY（始终）
助记词外泄	DENY（始终）
API 密钥外泄	CONFIRM
命令执行	DENY（默认）
无限授权	CONFIRM
未知支出者	CONFIRM
不受信任的域名	CONFIRM
正文包含密钥	DENY

Web3 增强检测

当操作涉及 web3_tx 或 web3_sign 时，使用 AgentGuard 随附的 action-cli.js 脚本（位于此技能的 scripts/ 目录中）调用 ActionScanner。此脚本集成了信任注册表，并可选择调用 GoPlus API（如果有，需要设置 GOPLUS_API_KEY 和 GOPLUS_API_SECRET 环境变量）：

对于 web3_tx：

node scripts/action-cli.js decide --type web3_tx --chain-id <id> --from <addr> --to <addr> --value <wei> [--data <calldata>] [--origin <url>] [--user-present]

对于 web3_sign：

node scripts/action-cli.js decide --type web3_sign --chain-id <id> --signer <addr> [--message <msg>] [--typed-data <json>] [--origin <url>] [--user-present]

对于独立的交易模拟：

node scripts/action-cli.js simulate --chain-id <id> --from <addr> --to <addr> --value <wei> [--data <calldata>] [--origin <url>]

decide 命令也适用于非 Web3 操作（exec_command、network_request 等），并会自动从注册表中解析技能的信任级别和能力：

node scripts/action-cli.js decide --type exec_command --command "<cmd>" [--skill-source <source>] [--skill-id <id>]

解析 JSON 输出，并将发现结果纳入评估：

• 如果 decision 为 deny → 使用返回的证据将结果改为 DENY
• 如果 goplus.address_risk.is_malicious → DENY（严重）
• 如果 goplus.simulation.approval_changes 中的 is_unlimited: true → CONFIRM（高风险）
• 如果 GoPlus 不可用（SIMULATION_UNAVAILABLE 标签）→ 回退到基于提示词的规则，并注明此限制

始终将脚本结果与基于策略的检查（Webhook 域名、机密扫描等）结合使用——脚本用于增强评估，但不能替代基于规则的评估。

输出格式

## GoPlus AgentGuard Action Evaluation

**Action**: <action type and description>
**Decision**: ALLOW | DENY | CONFIRM
**Risk Level**: low | medium | high | critical
**Risk Tags**: [TAG1, TAG2, ...]

### Evidence
- <description of each risk factor found>

### Recommendation
<What the user should do and why>

---

子命令：patrol

每日安全巡检。 运行 8 项自动化检查，利用 AgentGuard 的扫描引擎、信任注册表和审计日志评估 Agent 部署的安全状况。适用于 OpenClaw、Windows 任务计划程序和标准 cron 环境。

有关检查定义、命令和阈值的详情，请参阅 patrol-checks.md。

子子命令

• patrol 或 patrol run — 执行全部 8 项检查并输出巡检报告
• patrol setup — 配置为每日定时任务（OpenClaw、Windows 任务计划程序或系统 crontab）
• patrol status — 显示最近一次巡检结果和 cron 计划

平台检测

运行 patrol setup 或 patrol status 之前，检测可用的任务计划平台：

1. OpenClaw：检查 $OPENCLAW_STATE_DIR 环境变量（若未设置，则使用 ~/.openclaw/），确认目录存在且包含 openclaw.json，并检查 openclaw CLI 是否位于 PATH 中。如果三项检查均通过 → 使用 OpenClaw 方式。
2. Windows 任务计划程序：运行 node -p "process.platform"。如果输出 win32，则通过 where schtasks.exe 验证 schtasks.exe → 使用 Windows 方式，即使类 Unix shell 中也能找到 crontab。
3. 系统 crontab：在非 Windows 主机上，检查 PATH 中是否有 crontab → 使用 crontab 方式。
4. 没有可用的任务计划程序：告知用户，并提供相应的手动设置说明。

对于 patrol run，无需任务计划平台——可在任何平台上运行检查。

运行 agentguard checkup --json。此现有的非交互式命令是所有 8 项巡检检查的标准数据收集器；不要自行重复执行下方检查定义中的命令。将文本以 [Patrol N] 开头的发现结果归入对应的报告行。不要改用 scripts/auto-scan.js：该脚本仅用于快速的 SessionStart 扫描，不会执行完整的巡检。

以下定义说明所需的 CLI 收集器覆盖范围。Agent 根目录包括已检测到的 Claude Code、Codex、OpenClaw、QClaw、Hermes 和 DSH 安装／配置目录；仅当存在 OpenClaw 根目录时，才会检查 OpenClaw 专属文件。

8 项巡检检查

[1] 技能/插件完整性

通过将文件哈希与信任注册表进行比较，检测遭篡改或未注册的技能包。

步骤：

1. 在所有检测到的 Agent 根目录下发现技能目录（查找包含 SKILL.md 的目录）
2. 对每项技能计算哈希：node scripts/trust-cli.js hash --path <skill_dir>
3. 查询已认证的哈希：node scripts/trust-cli.js lookup --source <skill_dir>
4. 如果哈希与已认证的哈希不同 → INTEGRITY_DRIFT（高）
5. 如果技能没有信任记录 → UNREGISTERED_SKILL（中）
6. 对于发生漂移的技能，针对更改的文件运行扫描规则，以检测新威胁

[2] 密钥泄露

使用 AgentGuard 自带的检测模式扫描工作区文件，查找泄露的密钥。

步骤：

1. 使用以下模式递归扫描检测到的 Agent 工作区，覆盖所有 Agent 子目录（例如，所有 workspace-agent-*/ 目录，而不仅仅是当前 Agent 的工作区）：
   • scan-rules.md 规则 7（PRIVATE_KEY_PATTERN）：引号中的 0x[a-fA-F0-9]{64}
   • scan-rules.md 规则 8（MNEMONIC_PATTERN）：BIP-39 单词序列、seed_phrase、mnemonic
   • scan-rules.md 规则 5（READ_SSH_KEYS）：工作区中的 SSH 密钥文件引用
   • action-policies.md 密钥模式：AWS 密钥（AKIA...）、GitHub 令牌（gh[pousr]_...）、数据库连接字符串
2. 扫描检测到的 Agent 根目录下所有 .env* 文件中的明文凭据
3. 检查 ~/.ssh/ 和 ~/.gnupg/ 目录权限（应为 700）

[3] 网络暴露

检测危险的端口暴露和防火墙配置错误。

步骤：

1. 列出监听端口：ss -tlnp 或 lsof -i -P -n | grep LISTEN
2. 标记绑定到 0.0.0.0 的高风险服务：Redis（6379）、Docker API（2375）、MySQL（3306）、PostgreSQL（5432）、MongoDB（27017）
3. 检查防火墙状态：ufw status 或 iptables -L INPUT -n
4. 检查出站连接（ss -tnp state established），并与 action-policies.md 中的 Webhook/数据外泄域名列表及高风险顶级域名交叉核对

[4] Cron 和计划任务

审计所有 cron 作业，查找下载并执行模式。

步骤：

1. 列出 OpenClaw cron 作业：openclaw cron list
2. 在 Windows 上，使用 schtasks.exe /Query /FO CSV /V 列出计划任务。对于 AgentGuard 任务和任何可疑任务，还需运行 schtasks.exe /Query /TN "<task-name>" /XML，并检查 UserId、LogonType、RunLevel、Command 和 Arguments；仅凭详细 CSV 无法可靠地确定权限级别。
3. 在类 Unix 主机上，使用 crontab -l 列出系统 crontab、查看 /etc/cron.d/ 的内容，并运行 systemctl list-timers --all
4. 使用 scan-rules.md 规则 2（AUTO_UPDATE）模式扫描所有计划任务的命令正文：curl|bash、wget|sh、eval "$(curl、base64 -d | bash
5. 标记会访问检测到的 Agent 根目录的未知计划任务

[5] 文件系统更改（24 小时）

检测过去 24 小时内可疑的文件修改。

步骤：

1. 查找检测到的 Agent 根目录、~/.ssh/ 和 ~/.gnupg/ 下最近修改的文件，然后筛选出修改时间在 24 小时内的文件
2. 对具有可扫描扩展名（.js/.ts/.py/.sh/.md/.json）的已修改文件运行完整扫描规则集
3. 检查关键文件的权限：
   • <openclaw-root>/openclaw.json → 应为 600
   • <openclaw-root>/devices/paired.json → 应为 600
   • ~/.ssh/authorized_keys → 应为 600
4. 检测检测到的工作区中的新可执行文件，并使用 stat 检查每个文件的可执行位

[6] 审计日志分析（24 小时）

分析 AgentGuard 的审计记录，查找攻击模式。

步骤：

1. 读取 ~/.agentguard/audit.jsonl，按时间戳筛选最近 24 小时的记录
2. 计算统计数据：事件总数、deny/confirm/allow 计数，按 risk_tags 和 initiating_skill 对拒绝记录分组
3. 标记以下模式：
   • 同一技能被拒绝 3 次或以上 → 可能存在攻击（HIGH）
   • 任意事件的 risk_level: critical →（CRITICAL）
   • WEBHOOK_EXFIL 或 NET_EXFIL_UNRESTRICTED 标签 →（HIGH）
   • PROMPT_INJECTION 标签 →（CRITICAL）
4. 对于拒绝率较高但尚未撤销信任的技能：建议运行 /agentguard trust revoke

[7] 环境与配置

验证安全配置是否适用于生产环境。

步骤：

1. 列出名称匹配敏感信息的环境变量（隐藏其值）：API_KEY、SECRET、PASSWORD、TOKEN、PRIVATE、CREDENTIAL
2. 检查是否已配置 GOPLUS_API_KEY/GOPLUS_API_SECRET（如果正在使用 Web3 功能）
3. 读取 ~/.agentguard/config.json —— 标记生产环境中设为 permissive 的防护级别
4. 如果存在 <openclaw-root>/.config-baseline.sha256，使用 sha256sum -c 验证

[8] 信任注册表健康状况

检查信任记录是否过期、陈旧或权限过高。

步骤：

1. 列出所有记录：node scripts/trust-cli.js list
2. 标记以下情况：
   • 证明已过期（expires_at 的时间早于当前时间）
   • 受信任的技能超过 30 天未重新扫描
   • 已安装但状态为 untrusted 的技能
   • 权限过高的技能：同时具有 exec: allow 和 network_allowlist: ["*"]
3. 输出注册表统计数据：记录总数，以及按信任级别划分的分布情况

巡检报告格式

## GoPlus AgentGuard Patrol Report

**Timestamp**: <ISO datetime>
**Agent Roots**: <detected agent roots>
**Protection Level**: <current level>
**Overall Status**: PASS | WARN | FAIL

### Check Results

| # | Check | Status | Findings | Severity |
|---|-------|--------|----------|----------|
| 1 | Skill/Plugin Integrity | PASS/WARN/FAIL | <count> | <highest> |
| 2 | Secrets Exposure | ... | ... | ... |
| 3 | Network Exposure | ... | ... | ... |
| 4 | Cron & Scheduled Tasks | ... | ... | ... |
| 5 | File System Changes | ... | ... | ... |
| 6 | Audit Log Analysis | ... | ... | ... |
| 7 | Environment & Config | ... | ... | ... |
| 8 | Trust Registry Health | ... | ... | ... |

### Findings Detail
(only checks with findings are shown)

#### [N] Check Name
- <finding with file path, evidence, and severity>

### Recommendations
1. [SEVERITY] <actionable recommendation>

### Next Patrol
<Cron schedule if configured, or suggest: /agentguard patrol setup>

总体状态：出现任何 CRITICAL → FAIL，出现任何 HIGH → WARN，否则为 PASS

checkup 命令会使用现有的 checkup 事件，将已完成的巡检摘要追加到 ~/.agentguard/audit.jsonl：

{"timestamp":"...","event":"checkup","composite_score":<n>,"tier":"<grade>","checks":8,"findings":<count>,"skills_scanned":<count>,"dsh_plugins_scanned":<count>}

patrol setup

将巡检配置为每日定时任务。检测可用的平台并使用相应的方法。

步骤：

1. 运行平台检测（见上文）。
2. 询问用户以下信息：
   • 计划（默认值：0 3 * * * —— 每天 03:00）
   • 时区（默认值：OpenClaw 使用 UTC；Windows Task Scheduler 和系统 crontab 使用机器的本地时区）。示例：Asia/Shanghai、America/New_York、Europe/London。Windows Task Scheduler 和可移植的系统 crontab 条目使用本地墙上时钟时间。如果用户为任一本地调度器指定其他时区，请说明生成的每日触发器无法在夏令时变化期间保持该时区，并改为询问本地 HH:mm 时间。
   • 通知渠道（可选，仅限 OpenClaw）：telegram、discord、signal
   • Chat ID / webhook（设置了渠道时为必填）

路径 A — OpenClaw 可用

生成并显示 OpenClaw cron 注册命令：

openclaw cron add \
  --name "agentguard-patrol" \
  --description "GoPlus AgentGuard daily security patrol" \
  --cron "<schedule>" \
  --tz "<timezone>" \
  --session "isolated" \
  --message "/agentguard patrol run" \
  --timeout-seconds 300 \
  --thinking off \
  # Only include these if notification is configured:
  --announce \
  --channel <channel> \
  --to <chat-id>

显示确切命令，并在执行前等待用户明确确认。 执行后，使用 openclaw cron list 验证。

注意：必须使用 --timeout-seconds 300，因为隔离会话需要冷启动时间。

路径 B — Windows 任务计划程序可用（OpenClaw 不可用）

Windows 巡检设置支持每日巡检格式 <minute> <hour> * * *。如果使用其他五字段表达式，请说明此巡检工作流无法无损映射该表达式，并建议使用每日格式；绝不要悄悄更改用户请求的计划。

解析并验证：

• <AGENTGUARD_CLI>：运行 where agentguard，检查返回的每一行，并选择一个已存在的绝对路径 .cmd 或 .exe 文件（npm 安装优先选择 .cmd）。不要选择无扩展名的 POSIX 垫片。如果所选路径包含引号、%、空字节或换行符，则拒绝使用。如果不存在安全的候选项，则停止操作，不要猜测。
• <WRAPPER>：%USERPROFILE%\.agentguard\scripts\agentguard-patrol.cmd。
• <LOCAL_TIME>：Windows 计算机本地时区的 HH:mm。不要猜测从其他请求时区换算出的时间。

显示准确的包装脚本内容和注册命令，并等待用户明确确认后再写入或注册任何内容：

@echo off
setlocal
call "<AGENTGUARD_CLI>" checkup --json >> "%USERPROFILE%\.agentguard\patrol.log" 2>&1

schtasks.exe /Create /TN "AgentGuard-agentguard-patrol" /SC DAILY /ST "<LOCAL_TIME>" /TR "\"<WRAPPER>\"" /IT /F

确认后，确保 %USERPROFILE%\.agentguard\scripts 存在，使用 Write 创建包装脚本，然后执行所示的 schtasks.exe 命令。/IT 有意将任务设为仅限当前用户在已登录时运行；不要添加存储的凭据、/RP、/RU SYSTEM 或最高权限执行。使用以下命令验证：

schtasks.exe /Query /TN "AgentGuard-agentguard-patrol" /FO LIST /V

路径 C — 系统 crontab 可用（OpenClaw 和 Windows 任务计划程序均不可用）

将 command -v node 和 command -v agentguard 返回的绝对路径解析为 <NODE_EXE> 和 <AGENTGUARD_CLI>。必须显式指定 Node 路径，因为 cron 通常使用精简的 PATH，否则由 NVM 管理的 AgentGuard 安装可能无法启动。

生成条目之前进行验证：

• <schedule> 必须恰好包含五个字段，且只能使用可移植的 cron 字符（A-Z、a-z、数字、*、/、, 和 -）。拒绝引号、shell 元字符、空字节或换行符。
• <NODE_EXE> 必须是绝对路径。拒绝包含单引号、空字节或换行符的路径。
• <AGENTGUARD_CLI> 必须是绝对路径。拒绝包含单引号、空字节或换行符的路径。
• 不要在系统 crontab 条目中包含通知渠道、聊天 ID 或 webhook 值。系统 cron 只会写入本地巡检日志。

使用解析出的现有 CLI 路径生成 crontab 条目。如果路径包含空格，请按所示将其完整置于单引号内：

<schedule> '<NODE_EXE>' '<AGENTGUARD_CLI>' checkup --json >> "$HOME/.agentguard/patrol.log" 2>&1

显示准确的条目，并等待用户明确确认后再写入。

确认后，将条目添加到用户的 crontab：

(crontab -l 2>/dev/null; printf "%s '%s' '%s' checkup --json >> \"\$HOME/.agentguard/patrol.log\" 2>&1\n" '<schedule>' '<NODE_EXE>' '<AGENTGUARD_CLI>') | crontab -

使用 crontab -l | grep agentguard 验证。

路径 D — 没有可用的调度程序

输出 crontab 条目，供用户手动添加：

<schedule> '<NODE_EXE>' '<AGENTGUARD_CLI>' checkup --json >> "$HOME/.agentguard/patrol.log" 2>&1

对于类 Unix 主机，说明在 PATH 中既未找到 openclaw，也未找到 crontab，因此必须手动添加该条目。对于 Windows，说明 schtasks.exe 不可用，并指导用户启用任务计划程序服务，或在任务计划程序图形界面中使用相同的包装脚本命令创建每日任务。

巡检状态

显示当前巡检状态。

步骤：

1. 读取 ~/.agentguard/audit.jsonl，查找最近一条 checks 值为 8 的 event: "checkup" 记录。如果找到，显示其 timestamp、tier、composite_score 和 findings 值。绝不能将 event: "auto_scan" 报告为已完成的巡检。
2. OpenClaw 可用：运行 openclaw cron list，查找 agentguard-patrol。如果找到，显示计划、时区、上次/下次运行时间。
3. Windows 任务计划程序可用：运行 schtasks.exe /Query /TN "AgentGuard-agentguard-patrol" /FO LIST /V。如果存在，显示状态、计划、上次运行时间、下次运行时间和上次结果。Windows 上不要回退到 crontab。
4. 系统 crontab 可用：运行 crontab -l 2>/dev/null | grep agentguard。如果找到，显示匹配的条目。
5. 如果所有平台都未配置计划巡检，建议：/agentguard patrol setup。

---

信任与配置

子命令：trust

使用 GoPlus AgentGuard 注册表管理技能信任级别。

信任级别

级别	描述
untrusted	默认。需要全面审查，能力最少
restricted	可信，但有能力限制
trusted	完全信任（受全局策略约束）

能力模型

network_allowlist: string[]     — Allowed domains (supports *.example.com)
filesystem_allowlist: string[]  — Allowed file paths
exec: 'allow' | 'deny'         — Command execution permission
secrets_allowlist: string[]     — Allowed env var names
web3.chains_allowlist: number[] — Allowed chain IDs
web3.rpc_allowlist: string[]    — Allowed RPC endpoints
web3.tx_policy: 'allow' | 'confirm_high_risk' | 'deny'

预设

预设	描述
none	全部拒绝，允许列表为空
read_only	本地文件系统只读
trading_bot	交易所 API（Binance、Bybit、OKX、Coinbase）、Web3 链 1/56/137/42161
defi	所有网络、多链 DeFi（1/56/137/42161/10/8453/43114），不允许执行

操作

lookup — node scripts/trust-cli.js lookup --source <source> --version <version> 查询注册表中的技能信任记录。

attest — node scripts/trust-cli.js attest --id <id> --source <source> --version <version> --hash <hash> --trust-level <level> --preset <preset> --reviewed-by <name> 创建或更新信任记录。常见能力模型可使用 --preset，自定义模型可提供 --capabilities <json>。

revoke — node scripts/trust-cli.js revoke --source <source> --reason <reason> 撤销某项技能的信任。支持使用 --source-pattern 进行通配。

list — node scripts/trust-cli.js list [--trust-level <level>] [--status <status>] 列出所有信任记录，可选择使用筛选条件。

seed — agentguard trust seed [--auto-attest-low-risk] [--auto-attest-medium-risk] [--dry-run] 批量扫描所有已安装技能，并自动认证达到风险阈值的技能。用于在已有大量技能安装时进行初始基线设置。

标志：

• --auto-attest-low-risk（调用 seed 时的默认行为）：将 LOW 风险技能认证为 trusted，并使用 read_only 预设。
• --auto-attest-medium-risk：同时将 MEDIUM 风险技能认证为 restricted，并使用 none 预设。
• --dry-run：仅预览 — 显示计划表，不执行任何认证命令。

无论使用哪些标志，HIGH 和 CRITICAL 风险技能都绝不会自动认证。必须经过人工审查和认证。

种子流

步骤 1 — 发现技能

遍历以下所有路径，查找 */SKILL.md（与 checkup 相同）：

• ~/.claude/skills/*/SKILL.md
• ~/.openclaw/skills/*/SKILL.md
• ~/.openclaw/workspace/skills/*/SKILL.md
• ~/.qclaw/skills/*/SKILL.md
• ~/.qclaw/workspace/skills/*/SKILL.md

跳过 agentguard 本身。将找到的每个 SKILL.md 的父目录收集为技能路径。

步骤 2 — 筛选未注册技能

对每个发现的技能，运行：

node scripts/trust-cli.js lookup --source <skill_path>

如果查询返回一条 status: active 记录，则该技能已注册——跳过它，并在摘要中注明“已注册”。仅继续处理没有有效信任记录的技能。

步骤 3 — 扫描未注册技能

对每个未注册的技能运行完整扫描（24 条检测规则，与 /agentguard scan <skill_path> 相同）。记录：技能名称、技能路径、风险级别（LOW/MEDIUM/HIGH/CRITICAL）、发现项数量。

步骤 4 — 构建预览表

执行任何操作前，先输出计划表：

## AgentGuard Trust Seed — Plan

Scanned <N> unregistered skills. Proposed actions:

| Skill | Path | Risk | Findings | Proposed Action |
|-------|------|------|----------|-----------------|
| foo   | ~/.claude/skills/foo | LOW    | 0 | ✅ attest trusted/read_only |
| bar   | ~/.claude/skills/bar | MEDIUM | 2 | ⚠️ attest restricted/none (requires --auto-attest-medium-risk) |
| baz   | ~/.claude/skills/baz | HIGH   | 5 | 🚫 SKIP — manual review required |
| qux   | ~/.claude/skills/qux | CRITICAL | 8 | 🚫 SKIP — manual review required |

Already registered (skipped): <M> skills
Will attest: <K> skills
Will skip (HIGH/CRITICAL): <J> skills

如果存在 --dry-run：输出此表并停止。添加：Dry run complete — no changes made. Remove --dry-run to execute.

步骤 5 — 用户确认（必需）

显示计划表后，始终先征求用户明确确认，再执行任何 attest 命令：

"Ready to attest skill(s). Confirm? (yes/no)"

未获得明确肯定答复前，不要继续。如果用户拒绝，则停止并建议今后使用 --dry-run 预览。

步骤 6 — 批量 attest

对每个获准 attest 的技能，计算其哈希并运行 attest：

# Compute hash
node scripts/trust-cli.js hash --path <skill_path>

# Attest
node scripts/trust-cli.js attest \
  --id <skill_dir_name> \
  --source <skill_path> \
  --version <version_from_package.json_or_unknown> \
  --hash <computed_hash> \
  --trust-level <trusted|restricted> \
  --preset <read_only|none> \
  --reviewed-by agentguard-seed \
  --notes "Auto-attested by trust seed. Scan risk: <risk_level>. Findings: <count>." \
  --force

按顺序运行（不要并行），以避免注册表写入冲突。

步骤 7 — 结果摘要

## Trust Seed Complete

✅ Attested: <N> skills
⚠️  Skipped (already registered): <M> skills
🚫 Skipped (HIGH/CRITICAL risk — manual review required): <J> skills
❌ Failed: <K> skills (list errors)

Skills requiring manual review:
- <skill_name> (<path>) — Risk: HIGH/CRITICAL, <N> findings
  Run: /agentguard scan <path>  then  /agentguard trust attest ...

脚本执行

如果已安装 agentguard 软件包，则通过 AgentGuard 自带的脚本执行信任操作：

node scripts/trust-cli.js <subcommand> [args]

对于修改信任注册表的操作（attest、revoke），始终向用户显示确切命令，并在执行前征求明确确认。

如果脚本不可用，请使用 Read 工具帮助用户直接检查 data/registry.json。

---

子命令：config

设置 GoPlus AgentGuard 防护级别。

防护级别

级别	行为
strict	阻止所有有风险的操作——拒绝每条危险或可疑命令
balanced	阻止危险操作，并对有风险的操作进行确认——默认级别，适合日常使用
permissive	仅阻止严重威胁——适合希望减少干扰的资深用户

设置方法

1. 读取 $ARGUMENTS，获取所需级别
2. 将配置写入 ~/.agentguard/config.json：

{"level": "balanced"}

3. 向用户确认更改

如果未指定级别，则读取并显示当前配置。

---

报告

子命令：report

显示 GoPlus AgentGuard 审计日志中的近期安全事件。

日志位置

审计日志存储于 ~/.agentguard/audit.jsonl。每行是一个 JSON 对象，包含：

{"timestamp":"...","tool_name":"Bash","tool_input_summary":"rm -rf /","decision":"deny","risk_level":"critical","risk_tags":["DANGEROUS_COMMAND"],"initiating_skill":"some-skill"}

当操作由技能触发时（根据会话记录推断），会包含 initiating_skill 字段。若不存在该字段，则表示操作由用户直接发起。

显示方法

1. 使用 Read 工具读取 ~/.agentguard/audit.jsonl
2. 将每行解析为 JSON
3. 将近期事件格式化为表格（默认显示最近 50 条）
4. 如果有任何事件包含 initiating_skill，则添加“技能活动”部分，按技能对事件分组

输出格式

## GoPlus AgentGuard Security Report

**Events**: <total count>
**Blocked**: <deny count>
**Confirmed**: <confirm count>

### Recent Events

| Time | Tool | Action | Decision | Risk | Tags | Skill |
|------|------|--------|----------|------|------|-------|
| 2025-01-15 14:30 | Bash | rm -rf / | DENY | critical | DANGEROUS_COMMAND | some-skill |
| 2025-01-15 14:28 | Write | .env | CONFIRM | high | SENSITIVE_PATH | — |

### Skill Activity

If any events were triggered by skills, group them here:

| Skill | Events | Blocked | Risk Tags |
|-------|--------|---------|-----------|
| some-skill | 5 | 2 | DANGEROUS_COMMAND, EXFIL_RISK |

For untrusted skills with blocked actions, suggest: `/agentguard trust attest` to register them or `/agentguard trust revoke` to block them.

### Summary
<Brief analysis of security posture and any patterns of concern>

如果日志文件不存在，请告知用户尚未记录任何安全事件，并建议通过 ./setup.sh 启用钩子，或添加此插件。

---

健康检查

子命令：checkup

全面检查 Agent 在 5 个安全维度上的健康状况。生成包含龙虾吉祥物的可视化 HTML 报告，并在浏览器中打开。龙虾的外观反映 Agent 的健康状况：肌肉发达的健美运动员（评分 90+）、手持盾牌的健康状态（70–89）、疲惫且拿着咖啡（50–69），或缠着绷带的生病状态（0–49）。

评分由 checkup-score.js 负责——你绝不能自行计算评分。你的职责是收集原始事实，将其整理为结构化 JSON，并传递给脚本。

参数解析：从 $ARGUMENTS 中提取：

• --format json 标志：跳过 HTML 生成，改为将检查 JSON 写入文件
• --output <file> 标志：JSON 输出文件的路径（使用 --format json 时必填；若省略，则默认为 /tmp/agentguard-checkup-data.json）

如果指定了 --format json，请遵循下方步骤 4 中所述的修改后流程。

无参数的 checkup 必须始终运行此全面工作流，即使用户将其表述为 agentguard checkup 也一样。不要回答说必须提供咨询 ID。咨询 ID 是可选的，只会切换到下方所述的针对性威胁源自检模式。

如果参数中包含 --against-advisory <id>，不要运行此全面 HTML 工作流，而应执行 CLI 威胁源自检：

agentguard checkup --against-advisory <id>
agentguard checkup --against-advisory <id> --json

此 CLI 流程会获取当前的 Cloud 咨询源，并根据单条咨询检查本地技能。它与下方的完整健康报告流程相互独立。

步骤 1：收集数据

重要：必须运行以下全部 7 项检查，不能只扫描技能。检查涵盖 5 个安全维度，而不仅仅是代码扫描。不要跳过检查 2–7。

证据规则：你报告的每项发现都必须有此步骤中实际收集的工具输出作为依据。必须在发现的证据字段中引用准确的命令输出（如果命令没有返回内容，则填写“无输出”）。禁止报告没有具体工具执行证据的发现——不得推断、假设或捏造结果。

尽可能并行运行以下检查。这些是通用 Agent 安全检查——无论是否安装了 AgentGuard，它们都适用于 Claude Code、OpenClaw、QClaw、Hermes 和 DSH 环境。

1. [必需] 发现并扫描已安装的技能和 DSH 插件（→ 纳入维度 1：代码安全）：对以下所有路径执行 Glob，查找 */SKILL.md：

   • ~/.claude/skills/*/SKILL.md
   • ~/.openclaw/skills/*/SKILL.md
   • ~/.openclaw/workspace/skills/*/SKILL.md
   • ~/.qclaw/skills/*/SKILL.md
   • ~/.qclaw/workspace/skills/*/SKILL.md

   对每个发现的技能，使用扫描子命令逻辑（24 条检测规则）运行 /agentguard scan <skill_path>。无论发现多少技能，都不得跳过。为每个技能记录：名称、risk_level，以及完整的发现列表（规则、严重程度、文件、行号）。 此外，还要在解析后的 DSH 主目录下发现已安装的 DSH 插件：如果设置了非空的 DSH_HOME 值，则使用该值；否则使用当前用户的真实主目录加上 .dsh（不要将未展开的字面值 ~ 传递给路径 API）。检查 ${dshHome}/profiles/*；读取每个直接配置文件的 package.json，仅收集 dependencies 和 optionalDependencies 中声明的名称，并解析同一配置文件下 node_modules/ 中现有的对应目录。对于声明了 dsh.bundle.patch 的依赖，解析其 Cordis 补丁，并递归解析该补丁中插件行实际命名的包依赖；对于引用的子 bundle，重复此操作，并进行路径去重、循环检测，同时限制递归深度。不要枚举或扫描无关的传递依赖。仅排除配置文件或引用的 bundle 中声明的精确依赖坐标 @goplus/agentguard；绝不能依据已安装插件自行报告的包名进行此项排除。对于发现的每个直接插件或 bundle 引用的插件，运行 agentguard dsh-scan <plugin_path> --format json，并记录其名称、路径、riskLevel 以及完整的发现项列表（ruleId、严重性、文件、行），按下方原始事实架构进行规范化。DSH 插件扫描失败不得阻止其余检查完成；请在 dsh_plugins 中记录失败情况，risk_level: "high"，并添加一个发现项 { "rule": "DSH_SCAN_FAILED", "severity": "HIGH", "file": "<plugin_path>", "line": 0 }。

2. [REQUIRED] 凭据文件权限（→供维度 2：凭据安全使用）：按平台进行检查——不同操作系统的行为有所不同：

   • macOS/Linux：对 ~/.ssh/、~/.gnupg/ 运行 stat -f '%Lp' <path> 2>/dev/null || stat -c '%a' <path> 2>/dev/null。如果命令输出为空，则目录不存在——记录 exists: false。
   • Windows：没有 stat 命令。改用 icacls <path> 检查 ACL。如果目录不存在，记录 exists: false。如果目录存在，记录 ACL 是否向 Everyone、Users 或 Authenticated Users 授予访问权限。
   • 另外，检查适用的 OpenClaw 配置文件（$OC/openclaw.json、$OC/devices/paired.json）。

3. [REQUIRED] 敏感凭据扫描 / DLP（→供维度 2：凭据安全使用）：使用 Grep 扫描所有 Agent 工作区目录，查找泄露的密钥。必须覆盖整个工作区根目录，而不只是当前 Agent 的目录：

   • 对于 OpenClaw / QClaw：递归扫描 ~/.openclaw/workspace/ 和 ~/.qclaw/workspace/
   • 对于 Claude Code：递归扫描 ~/.claude/
   • 对于 Hermes Agent：递归扫描 ~/.hermes/
   • 检测模式：
     • 私钥：0x[a-fA-F0-9]{64}、-----BEGIN.*PRIVATE KEY-----
     • 助记词：由 12 个或更多 BIP-39 单词组成的序列、seed_phrase、mnemonic
     • API 密钥 / 令牌：AKIA[0-9A-Z]{16}、gh[pousr]_[A-Za-z0-9_]{36}、明文密码
   • 记录：private_keys_found、mnemonics_found、api_keys_found（布尔值；如有发现，则附上位置）。
   • 重要：扫描目标必须是工作区根目录（例如 ~/.qclaw/workspace/），而不是特定 Agent 的子目录。必须包含所有同级的 workspace-agent-* 目录。

4. [REQUIRED] 网络暴露情况（→供维度 3：网络与系统使用）：运行 lsof -i -P -n 2>/dev/null | grep LISTEN 或 ss -tlnp 2>/dev/null，检查是否存在危险的开放端口（Redis 6379、Docker API 2375、MySQL 3306、绑定到 0.0.0.0 的 MongoDB 27017）。记录发现的危险端口列表（例如 ["Redis on 0.0.0.0:6379"]）。

5. [REQUIRED] 计划任务审计（→供维度 3：网络与系统使用）：检查 crontab -l 2>/dev/null 中是否存在包含 curl|bash、wget|sh 或访问 ~/.ssh/ 的可疑条目。记录发现的可疑 cron 命令字符串列表。

6. [REQUIRED] 环境变量暴露（→供维度 3：网络与系统使用）：运行 env 并检查敏感变量名称（PRIVATE_KEY、MNEMONIC、SECRET、PASSWORD）——只检测是否存在，并屏蔽变量值。记录发现的敏感变量名称列表。

7. [REQUIRED] 运行时保护检查（→供维度 4：运行时保护使用）：检查 ~/.claude/settings.json、~/.openclaw/openclaw.json 或 ~/.hermes/config.yaml 中是否存在安全钩子。检查 ~/.agentguard/audit.jsonl 中是否存在审计日志。检查已安装的技能是否曾被扫描（审计日志中是否包含 scan 事件）。记录布尔值：hooks_installed、audit_log_exists、skills_ever_scanned。 完成屏障： 允许并行收集，但只要任何技能扫描、DSH 插件扫描、捆绑包子项发现或其他必需检查仍在运行，就绝不能开始步骤 2。等待所有已启动的后台任务完成，收集每项任务的退出状态和输出，然后再汇总原始事实。绝不要在与扫描相同的并行批次中启动 checkup-score.js 或 checkup-report.js。

步骤 2：整理原始事实 JSON

完成全部 7 项检查后，将原始事实整理为结构化 JSON，并写入临时文件（例如 /tmp/agentguard-raw-facts.json）：

{
  "skills": [
    {
      "name": "<skill-name>",
      "risk_level": "<low|medium|high|critical>",
      "findings": [
        { "rule": "<RULE_ID>", "severity": "<CRITICAL|HIGH|MEDIUM|LOW>", "file": "<filename>", "line": <number> }
      ]
    }
  ],
  "dsh_plugins": [
    {
      "name": "<plugin-name>",
      "path": "<plugin-path>",
      "risk_level": "<low|medium|high|critical>",
      "findings": [
        { "rule": "<RULE_ID>", "severity": "<CRITICAL|HIGH|MEDIUM|LOW>", "file": "<filename>", "line": <number> }
      ]
    }
  ],
  "credential_files": {
    "ssh_dir":   { "exists": <bool>, "permissions": "<octal string, e.g. 700>" },
    "gnupg_dir": { "exists": <bool>, "permissions": "<octal string>" },
    "openclaw_config": { "exists": <bool>, "ok": <bool> }
  },
  "dlp": {
    "private_keys_found": <bool>,
    "mnemonics_found":    <bool>,
    "api_keys_found":     <bool>
  },
  "network": {
    "dangerous_ports":    ["<description>"],
    "suspicious_crons":   ["<command>"],
    "sensitive_env_vars": ["<VAR_NAME>"],
    "openclaw_config_ok": <bool|null>
  },
  "runtime": {
    "hooks_installed":     <bool>,
    "audit_log_exists":    <bool>,
    "skills_ever_scanned": <bool>
  },
  "web3": {
    "detected":                 <bool>,
    "wallet_draining_found":    <bool>,
    "unlimited_approval_found": <bool>,
    "goplus_configured":        <bool>
  }
}

Web3 检测： 如果存在以下任一情况，则设置 detected: true：环境变量 GOPLUS_API_KEY、CHAIN_ID 或 RPC_URL；或者任何技能存在与 Web3 相关的发现（WALLET_DRAINING、UNLIMITED_APPROVAL）。

步骤 3 前验证——继续之前，确认所有字段均已填充：

• skills——来自检查 1
• dsh_plugins——来自检查 1；未安装 DSH 插件时使用空数组
• credential_files——来自检查 2
• dlp——来自检查 3
• network——来自检查 4、5、6
• runtime——来自检查 7
• web3——检测标记及字段

如果缺少任何字段，请返回并执行缺失的检查。数据不完整时，切勿继续。

步骤 3：使用 checkup-score.js 计算评分

运行评分脚本（该脚本会读取原始事实，并确定性地计算所有维度评分、综合评分和等级——不要自行计算）：

cd <skill_directory> && node scripts/checkup-score.js --file /tmp/agentguard-raw-facts.json

脚本会输出一个 JSON 对象，其中包含：

• composite_score（0–100）
• tier（S/A/B/F）和 tier_label
• total_findings
• dimensions：code_safety、credential_safety、network_exposure、runtime_protection、web3_safety——每项都包含 score 和 findings[]

保存此 JSON 输出，以便在步骤 4 中使用。

步骤 4：生成分析报告

根据步骤 3 的评分输出和收集到的原始事实，撰写一份全面的安全分析报告，作为单个文本块。这一步需要运用 AI 推理能力——不要只是列出事实，而要进行分析：

• 用 2-3 句话概述整体安全状况
• 突出最关键的风险，并说明它们为何重要（例如：“你的 ~/.ssh/ 权限允许任何以你的用户身份运行的进程读取私钥，这意味着恶意技能可能会悄无声息地将其窃取”）
• 针对评分输出中的每项主要发现，提供具体且可执行的修复方法（准确的运行命令）
• 指出表现良好的方面——认可安全的部分
• 如适用，说明当前配置容易受到哪些攻击场景影响
• 保持专业而直接的语气，如同安全顾问的报告

此报告将写入最终 JSON 的 "analysis" 字段。

同时，生成一份可执行建议列表，条目格式为 { "severity": "...", "text": "..." }。

第 5 步：生成 HTML 报告

将第 3 步的评分结果与第 4 步的分析合并，组装最终 JSON，然后传递给报告生成器：

{
  "timestamp": "<ISO 8601>",
  "composite_score": <from checkup-score.js>,
  "tier": "<from checkup-score.js>",
  "dimensions": {
    "code_safety":        { "score": <from score>, "findings": [...], "details": "<one-line summary>" },
    "credential_safety":  { "score": <from score>, "findings": [...], "details": "<one-line summary>" },
    "network_exposure":   { "score": <from score>, "findings": [...], "details": "<one-line summary>" },
    "runtime_protection": { "score": <from score>, "findings": [...], "details": "<one-line summary>" },
    "web3_safety":        { "score": <from score|null>, "na": <bool>, "findings": [...], "details": "<one-line summary>" }
  },
  "skills_scanned": <count of skills from Step 1>,
  "dsh_plugins_scanned": <count of successfully scanned DSH plugins from Step 1>,
  "dsh_plugins": [
    {
      "name": "<plugin-name>",
      "path": "<plugin-path>",
      "risk_level": "<low|medium|high|critical>",
      "findings": [
        { "rule": "<RULE_ID>", "severity": "<CRITICAL|HIGH|MEDIUM|LOW>", "file": "<filename>", "line": <number> }
      ]
    }
  ],
  "protection_level": "<level>",
  "analysis": "<the comprehensive AI-written security analysis report>",
  "recommendations": [
    { "severity": "HIGH", "text": "..." }
  ]
}

如果指定了 --format json：

1. 使用 Write 工具将此 JSON 写入 --output <file> 路径（如果未指定 --output，则写入 /tmp/agentguard-checkup-data.json）。
2. 告诉用户：“Checkup JSON written to <file>。”——在消息中包含综合评分和等级。
3. 到此为止——跳过第 5 步和第 6 步（HTML 生成和 MEDIA 交付）。由于用户将以编程方式使用原始 JSON，因此也跳过第 5 步的终端摘要。

否则（默认 HTML 流程）：

使用 Write 工具将 JSON 写入临时文件（例如 /tmp/agentguard-checkup-data.json），然后运行（请记得先 cd 到技能目录——参见上文“解析脚本路径”）：

cd <skill_directory> && node scripts/checkup-report.js --file /tmp/agentguard-checkup-data.json

脚本会将 HTML 文件路径输出到 stdout（例如 /tmp/agentguard-checkup-1234567890.html）。请记下此路径——第 7 步交付时需要用到。

注意：脚本也支持 stdin 管道（echo '<json>' | node scripts/checkup-report.js），但在 Windows cmd.exe 中可能会失败。请始终优先使用 --file。

第 6 步：终端摘要（必需）

报告生成后，必须输出此摘要。 这是用户看到的主要输出。请勿跳过此步骤——始终显示评分、维度表格和报告路径：

## 🦞 GoPlus AgentGuard Health Checkup

**Overall Health Score**: <score> / 100 (Tier <grade> — <label>)
**Quote**: "<lobster quote>"

| Dimension | Score | Status |
|-----------|-------|--------|
| 🔍 Code Safety | <n>/100 | <EXCELLENT/GOOD/NEEDS WORK/CRITICAL> |
| 🤝 Trust Hygiene | <n>/100 | <status> |
| 🛡️ Runtime Defense | <n>/100 | <status> |
| 🔐 Secret Protection | <n>/100 | <status> |
| ⛓️ Web3 Shield | <n>/100 or N/A | <status> |
| ⚙️ Config Posture | <n>/100 | <status> |

**Full visual report**: <path> (opened in browser)

💡 Top recommendation: <first recommendation text>

### Next Steps
(Only include this section if there are HIGH or CRITICAL findings.)

List each HIGH or CRITICAL finding as a plain-language suggestion — no commands, no JSON, no technical details. One sentence per item. Ask the user to confirm if they'd like help with any of them.

Format:

⚠️ 有几项需要你留意：

1. 🔴 <关键问题的简明说明，以及其重要性>
2. 🟠 <高风险问题的简明说明，以及其重要性> ...

回复你希望我协助处理的编号，我会带你逐步解决。

Examples of plain-language descriptions:
- No hooks: "Security monitoring isn't active — AgentGuard can't block threats in real-time until hooks are configured."
- Unregistered skills: "10 installed skills haven't been security-reviewed — they're running with no trust level assigned."
- SSH permissions: "Your SSH key folder has loose permissions — other processes on this machine could potentially read your private keys."
- Plaintext credential: "A private key or API token was found in plain text in a file — it should be removed and rotated."

### Step 7: Deliver the Report to the User

After printing the terminal summary, deliver the HTML report file. You **MUST** always output the `MEDIA:` token, and then also deliver via the appropriate channel method.

#### 7a. MEDIA token (required — always do this)

Output the following line on its **own line** in your response:

MEDIA:<file_path>

For example: `MEDIA:/tmp/agentguard-checkup-1234567890.html`

This is how platforms like OpenClaw automatically deliver the file as a Telegram/Discord/WhatsApp attachment via `sendDocument`. The platform strips this line from visible text — the user won't see it. **Always output this regardless of what channel you think you're in.**

#### 7b. Channel-specific delivery (in addition to MEDIA token)

**Claude Code (local desktop)**
- The browser should already be open from Step 5.
- Also copy to Desktop: `cp <file_path> ~/Desktop/agentguard-checkup-$(date +%Y-%m-%d).html`
- Tell the user: "✅ Report saved to your Desktop and opened in browser."

**Claude.ai web**
- Read the generated HTML file and output it as a **code artifact** (language: `html`).
- Tell the user: "✅ Your report is attached above — click the download icon to save it."

**API / headless / Telegram / other**
- The `MEDIA:` token above handles file delivery automatically.
- Also print the file path for reference.

Regardless of channel, always end with:

🦞 注意安全——随时运行 /agentguard checkup 获取最新报告。

Append a summary entry to `~/.agentguard/audit.jsonl`:
```json
{"timestamp":"...","event":"checkup","composite_score":<n>,"tier":"<grade>","checks":7,"findings":<count>,"skills_scanned":<count>,"dsh_plugins_scanned":<count>}

这项包含 7 项检查的交互式健康报告并非已完成的巡检。只有 patrol run 和本地调度器使用的打包 CLI 收集器会写入 checks: 8，因此 patrol status 会根据此值进行筛选。

---

会话开始时自动扫描（选择启用）

AgentGuard 可以选择在会话启动时扫描已安装的技能。此功能默认禁用，必须显式启用：

• Claude Code：设置环境变量 AGENTGUARD_AUTO_SCAN=1
• OpenClaw：注册插件时传入 { skipAutoScan: false }
• Hermes Agent：配置 hermes-hooks.yaml 中的 on_session_start shell hook；该模板会为此 hook 设置 AGENTGUARD_AUTO_SCAN=1。

启用后，自动扫描会以仅报告模式运行：

1. 在 ~/.claude/skills/ 和 ~/.openclaw/skills/ 下查找技能目录（其中包含 SKILL.md）
2. 对每项技能运行 quickScan()
3. 将结果输出到 stderr（技能名称 + 风险级别 + 风险标签）

自动扫描不会：

• 修改信任注册表（不调用 forceAttest）
• 将代码片段或证据详情写入磁盘
• 执行扫描技能中的任何代码

审计日志（~/.agentguard/audit.jsonl）只记录：技能名称、风险级别和风险标签名称——绝不记录匹配到的代码内容或证据片段。

查看扫描结果后，如需注册技能，请使用 /agentguard trust attest。