Skip to content

About

Hermes plugin (alpha, experimental): require a 3-line audit note - purpose / write target / failure impact - on risky terminal commands, by bouncing the call back to the model. Behavior may change.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 

Repository files navigation

command-note-guard

Alpha — 实验阶段。 行为、配置键与退回提示可能随时变化,尚未稳定,暂不建议在生产或个人关键流程上依赖。欢迎测试与反馈。

Hermes pre_tool_call 插件。执行 terminal 前检查命令是否带有审计摘要:

  • 不会进入 Hermes 审批/密码流程的命令:直接放行。
  • 会进入审批/密码流程且摘要完整:放行,不改写命令。
  • 会进入审批/密码流程但摘要缺失或不完整:退回该次调用(action: block,命令未执行),提示模型补齐摘要后,在同一轮里原样重发同一条命令。

execute_code 同样受管:先检查脚本级摘要(code 开头的三行 Python 注释),通过后再逐个检查 terminal() 的命令级摘要。详见「execute_code 覆盖」。

默认模式是 strict。插件不会代写摘要,摘要必须由当时的模型自己写。

三行摘要格式

摘要必须是命令开头连续的 # 注释行(遇到第一个非注释行即停止),固定三行:

# 【新改动|回滚|只读】用途=一句话说明这条命令要做什么
# 写入=写到哪里:文件/目录/服务/远端主机;只读则写 无
# 失败影响=失败时会怎样,一句话

规则:

  • 第一行必须以 # 开头,并带 【新改动】、【回滚】、【只读】 三选一标签。
  • 第二、三行也必须以 # 开头。
  • 三个键名容错:用途= / 用途: / 用途:;写入= / 写入: / 写入:;失败影响= / 失败影响: / 失败影响:,也接受 失败=。
  • 摘要行之后必须紧跟原命令本身,插件不会修改、移动或重新拼接命令。
  • 摘要只用于审批卡片展示,不参与执行。

完整示例:

# 【回滚】用途=清理临时目录
# 写入=/tmp/cng
# 失败影响=不可恢复
rm -rf /tmp/x

退回后的流程

  1. 第一次调用会进入审批但缺少摘要,插件返回 block,命令不会执行。
  2. 审批卡片显示命中项、缺少项(label / 用途 / 写入 / 失败影响)和三行格式示例。
  3. 模型按格式补写摘要,在同一轮里原样重发同一条命令(命令本身不要改)。
  4. 摘要完整后插件放行;后续命令照常执行。

退回提示固定为:

这条命令缺少审计摘要,已退回(未执行)。命中形态:recursive delete
缺:label、用途、写入、失败影响

请补成三行注释后,原样重发同一条命令(命令本身不要改):
# 【新改动|回滚|只读】用途=做什么
# 写入=写到哪(只读写 无)
# 失败影响=失败会怎样

示例:
# 【新改动】用途=重启示例服务加载新版插件
# 写入=launchctl gui/<uid> 域
# 失败影响=服务短暂中断,随后自动重连

execute_code 覆盖

execute_code 在子代理/injected 上下文里会走整脚本审批,审批卡片把整段 code 渲染成:

execute_code <<'PY'
<code 原文>
PY

这段 execute_code <<'PY' ... PY 包装文本由 Hermes 生成,模型无法在里面加注释,所以摘要只能写在 code 开头的 Python 注释里。execute_code 因此是两层检查,按顺序执行。

第一层:脚本级摘要

每次 execute_code 的 code 最前面必须是一段连续的三行 Python 注释(遇到第一个非注释行即停止,空行也会截断):

# 【只读】用途=查看 /tmp 下的大文件
# 写入=无
# 失败影响=无

from hermes_tools import terminal
print(terminal("du -sh /tmp/* | sort -h | tail"))
  • 即使脚本里一个 terminal() 都没有(例如纯 print(1)),也要求这三行。

  • 缺失或不完整时直接退回,不执行脚本。退回提示:

    execute_code 脚本缺少审计摘要,已退回(未执行)。缺:label、用途、写入、失败影响
    
    请在 code 最前面写三行 Python 注释后重发(代码本身不要改):
    # 【新改动|回滚|只读】用途=这段脚本要做什么
    # 写入=写到哪(只读写 无)
    # 失败影响=失败会怎样
    
    注意:这三行必须是 code 的第一段内容(Python 注释),不是 shell 命令里的注释。
    
  • 日志:command-note-guard: blocked execute_code script missing=<missing>,只记录缺失项,不记录 code 正文。

  • lenient 模式只要求 code 的第一个非空行以 # 开头。

  • annotate 模式不改 code,只记一条日志后放行。

第二层:命令级摘要

脚本级摘要通过后,插件再对 code 做静态分析,取出其中每个 terminal(...) 调用的 command,套用同一套审批判据与三行摘要规则。命令级摘要必须写在 command 字符串开头,脚本级摘要不能替代它。

覆盖范围:

  • 直接字符串字面量:terminal("rm -rf /tmp/x")。
  • command= 关键字:terminal(command="kill 123")。
  • 同一函数体或模块级、调用之前最近一次 ast.Constant(str) 赋值:cmd = "rm -rf /tmp/x"; terminal(cmd)。只回溯一层,不做控制流分析。
  • f-string 的静态部分:terminal(f"rm -rf {p}") 按 rm -rf {} 近似文本判断审批命中项与摘要。
  • 函数别名与属性调用:from hermes_tools import terminal as t 之后的 t(...),以及 hermes_tools.terminal(...)。

不覆盖(静态取不到 command 时直接放行,不会代写摘要):

  • 动态拼接、函数返回值、下标、join 等非字面量或非单层 Name 的 command。
  • 通过 subprocess、os.system 等自行调起的命令。
  • 多层变量传递:a = "rm ..."; b = a; terminal(b)。

两层都齐全的完整示例:

# 【只读】用途=查看目录内容
# 写入=无
# 失败影响=无

from hermes_tools import terminal
terminal(
    "# 【只读】用途=查看目录\n"
    "# 写入=无\n"
    "# 失败影响=无\n"
    "ls -la"
)

多个 terminal() 调用都不合格时,退回提示只报第一个,并给出不合格总数。

注意:这要求每一次 execute_code 都写脚本级摘要,没有「脚本很安全就免写」的例外。这是用户已知并接受的成本,换取审批卡片上始终能看到脚本用途、写入点与失败影响。

模式开关

环境变量在插件导入时读取一次,修改后需重载 Hermes。

# 默认(都不设):strict,会进入审批就要求三行摘要,缺失即退回
unset COMMAND_NOTE_GUARD COMMAND_NOTE_GUARD_DRY

# 完全关闭:不注册、不生效;0 / false 等价
export COMMAND_NOTE_GUARD=off

# 宽松:会进入审批的 terminal 命令、以及 execute_code 脚本,都只要求首行是 #,不检查三键
export COMMAND_NOTE_GUARD=lenient

# 旧行为回退:不拦截,terminal 命令自动补一行摘要后放行;execute_code 只记日志、不改 code
export COMMAND_NOTE_GUARD=annotate

# 灰测:只 logger.info 记录缺少项,不改命令、不拦截
export COMMAND_NOTE_GUARD_DRY=1

COMMAND_NOTE_GUARD_DRY=1 优先级最高:只记录、不改、不拦。

annotate 旧行为

# 【自动补注】recursive delete | 对象:/tmp/x | 后果:recursive delete
rm -rf /tmp/x
  • 摘要固定为单行,≤140 字符。
  • 原命令逐字保留在第二行,缩进、换行都不变。
  • 首行(第一个非空行)已经是 # 注释时不补注。
  • 摘要只用于审批卡片展示,不参与执行;命令照常运行。
  • 日志只记录命中项,不记录命令正文或对象内容。

判据来源:Hermes 审批模块

插件不再维护自己的风险形态清单。判据只有一个问题:这条命令会不会进入 Hermes 的审批/密码流程。

命中检测直接调用 Hermes 源码里的两个纯函数(延迟 import,避免插件加载期失败):

from tools.approval_detection import (
    detect_dangerous_command,
    detect_hardline_command,
)
  • detect_hardline_command(command) 返回 (True, description):追加 hardline:<description>。这是 Hermes 的硬拦截底线,--yolo 也不能绕过。
  • detect_dangerous_command(command) 返回 (True, key, description):追加 description or key。这与 terminal_tool 的审批守卫使用同一张 DANGEROUS_PATTERNS 表。
  • 非注释行里出现 \bsudo\b:追加 sudo。sudo 会单独触发密码框,不包含在上面两个函数里。

也就是说,这里的命中集合与 Hermes 审批守卫同源;Hermes 不要求审批的命令,本插件也不要求摘要。

相比旧清单的行为变化

旧版按自建形态表判断,会对一些实际不进入审批的命令要求摘要。以下命令现在不再要求摘要:

  • scp / rsync:分类器不 flag(除非同时命中真正的危险模式);旧清单的 remote-copy 命中已不再要求摘要。
  • chmod / chown 的普通权限修改(例如 chmod 700 ~/x.sh):只有 777 / 666 / other-writable、递归 chown root 等危险写法才命中;旧清单的 permissions 命中已不再要求摘要。
  • launchctl print 等只读子命令:分类器不 flag,因此不要求摘要(旧清单本来也只匹配操作类子命令)。普通服务的 launchctl bootout gui/501/local.foo 则从旧清单的 launchd 命中变为不要求摘要;分类器只对 ai.hermes / hermes 网关标签的 stop / kickstart / bootout / unload / kill / disable / remove 报审批。
  • 普通重定向到非敏感目标(例如 echo hi > /dev/null 2>&1):不命中(旧清单也排除了 /dev/null 与 2>&1);> /etc/... 等敏感路径仍会命中。
  • 普通 kill -9 <pid>:分类器只 flag kill -9 -1、pkill -9 等宽范围终止;旧清单的 kill-process 命中已不再要求摘要。

反过来,旧清单未覆盖但 Hermes 会审批的命令(例如 SQL DELETE 无 WHERE、git reset --hard、敏感路径写入等)现在也会要求摘要。python3 -c 'print(1)' 也仍会命中 script execution via -e/-c flag,因为分类器本身就会 flag 内联脚本。

同一命令可能命中多个项,日志与退回提示会列出全部命中项。

日志

  • 退回:command-note-guard: blocked <hits> missing=<missing>,只记录命中项和缺失项,不记录命令正文。
  • execute_code 脚本级退回:command-note-guard: blocked execute_code script missing=<missing>,不记录 code 正文。
  • execute_code 命令级退回:command-note-guard: blocked execute_code #<n> <hits> missing=<missing>。
  • annotate:command-note-guard: annotated <hits>;execute_code 为 command-note-guard: execute_code annotate pass ...。
  • 灰测:command-note-guard: dry-run missing=<missing> hits=<hits>。
  • 关闭:command-note-guard: disabled by COMMAND_NOTE_GUARD。

已知局限

  1. execute_code 只做静态分析:动态拼接、函数返回值、下标、join、多层变量传递等取不到字面量的 command 会直接放行。例如 cmd = "rm " + "-rf /tmp/x"。
  2. 通过 subprocess、os.system 等自行调起的命令不在 terminal 的审批路径上,插件也看不到。
  3. 插件跑在 host 隔离模式、无法 import tools.approval_detection 时,启用一份五条兜底规则(fallback:recursive-delete、fallback:sql-drop、fallback:inline-script、fallback:heredoc、fallback:sudo),仍要求摘要,只记一次 warning。此时覆盖率明显低于正常路径,其余命令会放行。
  4. 判据与 Hermes 审批守卫同源:Hermes 分类器不 flag 的命令,本插件也不会要求摘要;这不是「命令一定安全」的保证。
  5. 两层摘要都只认开头连续的 # 行;摘要与代码之间插入空行,或把摘要写到后面,都会被判为缺失。脚本级摘要必须是 code 的第一段内容,命令级摘要必须是 command 字符串的第一段内容。
  6. 插件内部异常一律放行;任何解析失败都不会阻止命令执行。

About

Hermes plugin (alpha, experimental): require a 3-line audit note - purpose / write target / failure impact - on risky terminal commands, by bouncing the call back to the model. Behavior may change.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages