safe-agent 集成方案报告

Codex 核验（2026-10-09）：当前 safe-agent（最近推送 2026-06-15）除技能指令外已提供 Claude Code 确定性 hooks；需配置 hooks 且满足 jq 等依赖，README 明示 jq 缺失会 fail open。本文把5个 SKILL.md 复制到 Hermes 的历史记录不能证明这些 hooks 已移植、预算已强制阻断；自定义 auto_trigger 字段本身不注册运行时 hook。模型计价示例必须绑定具体型号与日期，不能把旧 Opus/Haiku 单价作为整个家族现价。Snyk 的 36.82%来自其分析的3,984个技能样本，不是全部技能的总体发生率；OWASP“一级攻击面”是项目作者概述，未核实为标准等级。

研究日期: 2026-05-28 项目: ArielSmoliar/safe-agent (MIT License) 目标: 将 safe-agent 的 5 个安全技能集成到 Hermes Agent

1. 项目概述

safe-agent 是一个为 AI 编码 agent 设计的安全技能套件，由 Flare（云审计日志异常检测）和 LOCO（多 agent 调度）的原作者创建。核心思路：不是让 agent 做安全，而是保护你免受 agent 的伤害——在安装恶意技能之前捕获它们，在危险命令执行之前拦截它们。

项目核心数据

行业背景

Snyk 的 ToxicSkills 研究发现 **其3,984个受测技能中36.82%**存在至少一个安全问题，包括 prompt 注入、凭证窃取和数据外泄。OWASP 已将 agentic skills 列为一级攻击面。

safe-agent 基于学术论文 Towards Secure Agent Skills: Architecture, Threat Taxonomy, and Security Analysis (Li et al., 2026, arXiv:2604.02837) 的威胁分类法构建。

2. 5 个核心技能详解

2.1 skill-verify — 技能安装前审计

核心功能：

• 静态文件分析：检查 SKILL.md 的 prompt 注入、隐蔽指令（Unicode 零宽字符、base64 载荷）、凭证窃取、权限过度申请
• 脚本分析：Shell 注入、网络调用、文件系统写入、混淆代码
• Hook/配置检查：Hook 劫持、MCP 服务器注入
• 行为分析：技能是否言行一致、最小权限原则、信任边界
• 输出结构化报告：VERDICT + Risk Score (0-100) + 发现列表

调用方式：

/safe-agent:skill-verify path/to/skill-directory
/safe-agent:skill-verify https://github.com/someone/cool-skills
/safe-agent:skill-verify  # 审计所有已安装技能

2.2 cost-guard — 会话费用和 Token 预算

三种模式：

• reject — 超限时停止工作
• alert — 超限时警告但继续（默认）
• downgrade — 接近限额时建议更便宜的做法

费率表（内置）：

调用方式：

/safe-agent:cost-guard $5
/safe-agent:cost-guard 200k tokens alert
/safe-agent:cost-guard $10 reject

2.3 tool-guard — 工具调用授权

权限级别：

• Allow — 自由使用
• Gate — 使用前需用户确认
• Deny — 完全禁止

预置配置文件：

调用方式：

/safe-agent:tool-guard profile readonly
/safe-agent:tool-guard deny Bash
/safe-agent:tool-guard gate Edit,Write
/safe-agent:tool-guard status

2.4 behavior-watch — 行为异常检测

异常信号（Flare 异常引擎适配）：

• 频率异常：工具调用过多/过少、突发活动
• 范围异常：访问工作目录外的文件、读取凭证文件
• 序列异常：读凭证 → 网络请求（外泄）、写 shell 配置 → 执行（持久化）
• 首次模式：首次访问目录、首次使用工具
• 任务漂移：偏离用户目标的行动

评分标准：

• 85-100 = 严重：立即关注
• 65-84 = 高：值得调查
• 40-64 = 中：注意并关联
• 0-39 = 低：仅供参考

调用方式：

/safe-agent:behavior-watch  # 生成会话活动异常报告

2.5 pre-exec-check — 执行前安全检查

风险级别：

• CRITICAL: 阻止并警告。如 rm -rf /、git push --force main、DROP TABLE、凭证暴露
• HIGH: 警告并建议更安全的替代方案。如 git push --force → 建议 --force-with-lease
• MEDIUM: 仅在异常上下文中提示。如全局安装包、sudo 命令、修改 dotfiles

自动触发场景：

• 破坏性文件操作（rm -rf）
• 不可逆 Git 操作（force push, reset —hard）
• 数据库破坏（DROP TABLE, DELETE without WHERE）
• 系统操作（chmod -R 777, kill -9）
• 秘密暴露（echo $API_KEY, curl 含凭证）

3. Hermes Agent 集成方案

3.1 架构集成方式

safe-agent 的 SKILL.md 文件格式与 Hermes Agent 完全兼容。两者都使用：

• YAML 前端元数据（name, description, triggers）
• Markdown 主体（行为指导和工作流程）

集成深度：

Hermes Agent 系统提示
    │
    ├── safe-agent/skill-verify/     ← 按需调用（安装前审计）
    ├── safe-agent/cost-guard/       ← 按需调用（预算管理）
    ├── safe-agent/tool-guard/       ← 按需调用（权限控制）
    ├── safe-agent/behavior-watch/   ← 按需调用（异常检测）
    └── safe-agent/pre-exec-check/   ← 自动触发（命令安全检查）

3.2 已完成的集成工作

1. ✅ 克隆仓库到 ${HOME}/safe-agent-repo/
2. ✅ 安装 5 个技能到 ~/.hermes/skills/safe-agent/ 目录
3. ✅ 适配 YAML 前端添加 Hermes 兼容的 triggers: 数组和 metadata.category
4. ✅ 添加中文触发词（安全审计、预算、工具限制、行为审计、命令安全等）
5. ✅ 复制测试夹具（safe-skill + 3 个恶意示例）用于验证 skill-verify
6. ✅ 复制威胁模式参考 skill-verify/references/threat-patterns.md

3.3 文件结构

~/.hermes/skills/safe-agent/
├── _README.md                              # 总体文档（来自 CLAUDE.md）
├── skill-verify/
│   ├── SKILL.md                           # 技能审计（106 行）
│   └── references/
│       └── threat-patterns.md             # 威胁模式参考
├── cost-guard/
│   └── SKILL.md                           # 预算管理（127 行）
├── tool-guard/
│   └── SKILL.md                           # 工具权限（148 行）
├── behavior-watch/
│   └── SKILL.md                           # 行为异常检测（171 行）
├── pre-exec-check/
│   └── SKILL.md                           # 执行前检查（115 行）
└── test-fixtures/
    ├── safe-skill/SKILL.md                # 安全技能测试
    ├── malicious-injection/SKILL.md       # Prompt 注入测试
    ├── malicious-exfiltration/SKILL.md    # 数据外泄测试
    └── malicious-credential-harvest/SKILL.md # 凭证窃取测试

3.4 Hermes 路由集成

已为每个 skill 添加以下 YAML frontmatter 以实现 Hermes 的路由匹配：

metadata:
  category: security
  source: safe-agent
triggers:
  - "verify this skill"
  - "is this skill safe"
  - ...
  - "安全审计"       # 中文触发词
  - "技能安全"

pre-exec-check 额外添加了 auto_trigger: on_destructive_command 作为触发意图元数据；是否自动执行仍须 Hermes loader/hook 实现与测试。

3.5 推荐使用流程

1. 安装新技能前:
   /safe-agent:skill-verify <path-or-url>

2. 会话开始时:
   /safe-agent:tool-guard profile careful
   /safe-agent:cost-guard $5 reject

3. 工作中:
   pre-exec-check 自动检查破坏性命令

4. 会话中/结束前:
   /safe-agent:behavior-watch

3.6 防御纵深层次

Layer 1: 安装前 ▸ skill-verify (审计)
Layer 2: 权限   ▸ tool-guard (门控)
Layer 3: 财务   ▸ cost-guard (预算)
Layer 4: 运行时 ▸ pre-exec-check (命令安全)
Layer 5: 审计   ▸ behavior-watch (异常检测)

4. 与 Hermes 现有安全机制的对比

5. 局限性与注意事项

1. 行为指导，非强制执行：safe-agent 是 agent 的行为指导（instruction-based），不是运行时的强制拦截系统。有决心的攻击者可以绕过。这与代码审查不能阻止所有 bug 是同样的道理。
2. 仅当前会话：behavior-watch 目前只分析当前会话，没有跨会话记忆。未来版本（v0.4）将支持。
3. 费用估计：cost-guard 的费用估计基于近似值，实际计费可能不同。
4. 新项目：safe-agent 是 2026-05-24 创建的新项目（v0.1.0），生态尚未成熟。
5. 无 MCP 集成：当前版本不涵盖 MCP 服务器审计（v0.3 路线图）。

6. 路线图 & 待办

Hermes 特定待办

• 测试 skill-verify 在 Hermes 环境中对测试夹具的审计效果
• 测试 pre-exec-check 自动触发的可靠性
• 验证 cost-guard 在 Hermes 不同模型间的兼容性
• 添加 Hermes 特有工具的 tool-guard 配置（如 Agent 工具）
• 考虑将 safe-agent 设为 Hermes 默认启用的安全层

7. 结论

safe-agent 提供的 5 个技能（skill-verify、cost-guard、tool-guard、behavior-watch、pre-exec-check）构成了从安装前审计到运行时保护的完整防御纵深体系。由于其使用标准 SKILL.md 格式，直接与 Hermes Agent 兼容，可以无代码侵入地集成。

集成状态：已完成 — 所有 5 个技能已安装到 ~/.hermes/skills/safe-agent/，适应了 Hermes 的 YAML frontmatter 格式，添加了中文触发词，并包含了测试夹具用于验证。

建议：对于安全敏感的工作场景（生产环境操作、处理凭证、安装第三方技能），建议在 Hermes 系统提示中加入 safe-agent 的推荐使用指导，使其成为 Hermes 的默认安全层。