@yottameta/yotta-guardian 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 更新日志
 
+## v0.1.7 (2026-09-28)
+
+文档格式修复 + 两处引擎健壮性修复（规则判定行为不变）。
+
+- **修复代码围栏**：`SKILL.md` 与 `references/`（intent-verifier / policies / rules）中被写作管线占位符顶替的代码围栏，全部还原为标准三个反引号，共 20 处；此前自 0.1.0 起一直未还原，Markdown 渲染异常（命令与配置示例无法按代码块显示）。
+- **修复非法转义（0.1.0 起既有）**：`scripts/guardian_rules.py` 的模块 docstring 里 `\s`、`\b` 属非法转义 —— Python 3.12+ 每次调用都向 stderr 报 2 行 SyntaxWarning，严格告警（`PYTHONWARNINGS=error`）下引擎直接加载失败。该 docstring 改为 raw 字符串（与规则表内 `r"…"` 写法一致），告警消失。
+- **修复致命异常退出码（fail-closed，0.1.0 起既有）**：此前未捕获异常走 Python 默认退出码 1，而契约里 1 = 允许但带警告 —— 按退出码判定的宿主会把「引擎崩溃」读成放行（fail-open）。现在规则表加载失败与运行期未预期异常统一以**退出码 4**（用法错误 / 致命异常）结束并在 stderr 写明原因；新增 3 项回归用例（导入失败 → 4、运行期异常 → 4、严格告警下仍正常判定，共 86 项）。
+- **修复彩色输出必崩（0.1.6 起既有）**：`check` 的彩色分支 `c()` 格式串只有 1 个 `%s` 却喂 2 个参数 —— 真人终端（`sys.stdout.isatty()` 为真）必抛 `TypeError`，以退出码 4 结束且**判定与命中规则完全不输出**；`--json` / `--no-color` / 管道不受影响（故此前测试未覆盖）。已修正格式串，并新增「假 TTY」回归用例（共 88 项）。
+- **文档**：`SKILL.md` 新增「宿主接入」一节（放行不代批 / 用文件接引擎输出 / stdin 按 UTF-8 读），并把退出码 4 的语义写成「用法错误 / 致命异常（绝不要当作放行）」。
+- **发布门禁联动**：`validate-skill` 与 `preflight-publish` 的交付面检查扩到 Python 一侧（语法错误 / 非法转义等编译期告警），与 Markdown 检查共用同一入口，命中即拦。
+- 规则判定、策略档位、CLI 输出结构与审计格式不变；版本四处对齐 0.1.7。
+
+## v0.1.6 (2026-09-25)
+
+安全修复：复合命令拆分，堵住分隔符后的危险段绕过。
+
+- 背景：v0.1.5 只解决了包装命令（`sh -c` / `sudo` / `env` …）绕过，整条命令仍只按第一个词做 argv 分析——`echo ok && rm -rf /`、`ls; rm -rf /`、`true || rm -rf /` 里的危险段藏在分隔符之后，整条命令被判放行（本轮复现）。
+- 修复：新增受控复合命令拆分（`;` `&&` `||` `|` `&` 换行，引号 / 转义内不拆）+ 命令替换展开（`$(...)` / 反引号），逐段跑同一套文本 / argv 规则；放行规则只对单一简单命令生效；引号未闭合时出 `CMD-UNPARSED`（medium，fail-closed）。
+- 安装器加固：拒绝对符号链接目标写入、目标不是目录时拒绝、不做整目录删除。
+- 回归：新增 11 项复合命令用例，测试 83/83 通过。
+
 ## v0.1.5 (2026-09-19)
 
 安全修复：包装命令解包，堵住 argv 级分析的绕过路径。
@@ -41,7 +62,7 @@
 
 - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 命令 / 快速使用 / 安装 / 使用示例 / 边界 / 开发校验全流程）。
 - **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。
-- **修复代码围栏**：README 中 `_BT_`bash / `_BT_` 占位符全部改为标准 ```bash / ```（Markdown 渲染修复）。
+- **修复代码围栏**：README 中的围栏占位符（写作管线留下的标记）全部改为标准 ```bash / ```（Markdown 渲染修复）。
 - **package.json**：description 改英文；files 加 README.zh-CN.md；版本 0.1.0 → 0.1.1。
 - 版本四处对齐：package.json / SKILL frontmatter / 引擎 VERSION / 文档。
 - 边界（B 方案）：references / CHANGELOG / 测试注释不翻译；SKILL 触发描述保持中文。

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-guardian
-version: 0.1.5
+version: 0.1.7
 description: 元盾 —— 跨智能体的危险调用拦截护栏：确定性规则引擎 + 可插拔意图验证（不绑模型），拦截危险 exec / write / edit / read / run / shell 工具调用，提供审计日志。触发：代理要执行高风险命令（递归删除、磁盘格式化、提权、防火墙改动、反向 shell、下载即执行等）、要写入系统敏感路径或修改系统配置、要在执行危险操作前做安全检查、或用户说 护栏/拦截/危险操作/安全检查 等。边界：默认只读评估，不自动执行也不放行危险操作；不替代用户决策；不隐藏审计记录；规则可配置。
 license: MIT
 ---
@@ -27,7 +27,7 @@ license: MIT
 
 Windows 用 python，Linux/macOS 用 python3。
 
-`_BT_`bash
+```bash
 # 检查一条 exec（0 = 允许）
 python3 scripts/yotta_guardian.py check exec --cmd "git status"
 
@@ -43,15 +43,25 @@ python3 scripts/yotta_guardian.py check --batch calls.json --json
 # 审计
 python3 scripts/yotta_guardian.py check exec --cmd "..." --audit-log .yotta-guardian/audit.jsonl
 python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --tail 20
-`_BT_`
+```
 
 ## 工作流程（AI 智能体执行危险操作前）
 
 1. **先检查**：把将要执行的工具调用交给护栏 `check`（单条或 `--batch` 批量）。
-2. **看退出码**：0 = 允许；1 = 允许但带警告（建议人工复核）；2 / 3 = 拒绝（high / critical，不要执行）；4 = 用法错误。
+2. **看退出码**：0 = 允许；1 = 允许但带警告（建议人工复核）；2 / 3 = 拒绝（high / critical，不要执行）；4 = 用法错误 / 致命异常（引擎没跑起来 —— 绝不要当作放行）。
 3. **被拒绝怎么办**：如实向用户报告原因与命中规则；确有授权的操作，用 `--allow` / `--allow-path` / 自定义规则文件放行并留审计记录；**不要绕过检查**。
 4. **留痕**：高风险场景用 `--audit-log` 落审计日志，供追溯。
 
+## 宿主接入（把护栏挂到「工具调用前」事件时）
+
+`skill-manifest.json` 声明 `before_tool` + `fallback: explicit-unverified`。接入方按下面三条做，可避开实测踩过的坑：
+
+1. **放行不要回「允许」**：只在拦截时输出拒绝判定（如 `permissionDecision: "deny"`）；放行时**不输出任何判定**，把决定权交回宿主。若放行时回「allow」，会覆盖宿主自身的权限流程，护栏就变成自动放行器 —— 护栏只该「拦」，不该「代批」。
+2. **用文件接引擎输出**：部分 hook 进程环境里，用管道捕获子进程 stdout 会拿到空值（同一写法跑 `python -c "print(1)"` 却正常）；把引擎 stdout / stderr 重定向到临时文件再读回，判定即稳定（引擎自身的 stdout 是纯净的，`--json` 可直接解析）。
+3. **stdin 先按 UTF-8 读**：hook 载荷里的命令文本常含中文，按本机默认码页解码会乱码；读 stdin 前先 `sys.stdin.reconfigure(encoding="utf-8")`（引擎已对自身 stdout / stderr 做 UTF-8 处理，stdin 由接入方负责）。
+
+另外：引擎对「没跑起来」是 fail-closed 的 —— 规则表加载失败或运行期未预期异常一律以退出码 4 结束并在 stderr 写「致命异常: …」。接入方应把 4 当作**不放行 + 报告**处理，而不是放行。
+
 ## 策略（policy）
 
 | 策略 | 行为 |

package/install.sh

@@ -61,10 +61,29 @@ resolve_user() {
 }
 
 install_to() {
-  mkdir -p "$1/$SKILL_NAME"
-  cp -r "$SOURCE_DIR/." "$1/$SKILL_NAME/"
-  rm -rf "$1/$SKILL_NAME/.git"
-  echo "installed -> $1/$SKILL_NAME"
+  local base="$1"
+  local dest
+  case "$base" in
+    ""|"/") echo "安装失败：拒绝不安全的目标目录：'$base'" >&2; return 1 ;;
+  esac
+  if [ -L "$base" ]; then
+    echo "安装失败：目标目录是符号链接，拒绝跟随：$base" >&2; return 1
+  fi
+  mkdir -p "$base"
+  dest="$base/$SKILL_NAME"
+  if [ -L "$dest" ]; then
+    echo "安装失败：技能目录是符号链接，拒绝跟随：$dest" >&2; return 1
+  fi
+  if [ -e "$dest" ] && [ ! -d "$dest" ]; then
+    echo "安装失败：技能路径已存在且不是目录：$dest" >&2; return 1
+  fi
+  mkdir -p "$dest"
+  cp -RP "$SOURCE_DIR/." "$dest/"
+  # 只清理副本内部的开发残留（固定子路径），不做整目录删除、不跟随符号链接
+  if [ -d "$dest/.git" ] && [ ! -L "$dest/.git" ]; then rm -rf "$dest/.git"; fi
+  find "$dest" -type d -name '__pycache__' -prune -exec rm -rf {} + 2>/dev/null || true
+  find "$dest" -type f -name '*.pyc' -delete 2>/dev/null || true
+  echo "installed -> $dest"
 }
 
 list() {
@@ -129,4 +148,4 @@ main() {
   fi
 }
 
-main "$@"
+main "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-guardian",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Yuandun (元盾) — cross-agent dangerous tool-call guardrail: a deterministic rule engine + pluggable intent verifier (model-agnostic) that evaluates exec/write/edit/read/run/shell calls and provides audit logs. Triggers when an agent is about to run a high-risk command, write sensitive paths, or change system config. Boundaries: read-only evaluation by default, configurable allowances.",
   "license": "MIT",
   "keywords": [

package/references/intent-verifier.md

@@ -13,7 +13,7 @@
 
 引擎对「允许」结论的调用发起验证，写入 stdin 的 JSON：
 
-`_BT_`json
+```json
 {
   "tool": "exec",
   "cmd": "npm install",
@@ -24,19 +24,19 @@
   "cwd": "/home/user/project",
   "findings": []
 }
-`_BT_`
+```
 
 字段说明：tool 为工具类型；cmd / path / content_preview（内容前 500 字符）/ target 为调用内容；policy 为当前策略；findings 为确定性规则已命中的条目（允许结论下通常为空或仅低危）。
 
 ## 三、响应（stdout，JSON）
 
-`_BT_`json
+```json
 {
   "verdict": "allow",
   "severity": "low",
   "reason": "安装依赖，无恶意信号"
 }
-`_BT_`
+```
 
 - verdict：allow / deny / review 三选一（必须）。
 - severity：可选，deny 时默认 high；取值 info / low / medium / high / critical。
@@ -59,7 +59,7 @@
 
 ## 六、示例验证器（Python 桩）
 
-`_BT_`python
+```python
 #!/usr/bin/env python3
 import json
 import sys
@@ -71,6 +71,6 @@ if cmd.startswith("danger"):
 else:
     out = {"verdict": "allow", "severity": "low", "reason": "无风险信号"}
 json.dump(out, sys.stdout)
-`_BT_`
+```
 
 真实场景可用该协议把调用摘要发给 LLM 网关做语义判断，返回同样的 JSON 即可接入。

package/references/policies.md

@@ -34,9 +34,9 @@ AI 智能体判断：退出码非 0 时不要直接执行；2 / 3 一律停下
 
 ### 执行前 gate
 
-`_BT_`bash
+```bash
 python3 scripts/yotta_guardian.py check exec --cmd "<待执行命令>" --json
-`_BT_`
+```
 
 - exit 0：执行。
 - exit 1：执行但提示用户「护栏给出中危警告」。
@@ -45,9 +45,9 @@ python3 scripts/yotta_guardian.py check exec --cmd "<待执行命令>" --json
 
 ### 批量预检
 
-`_BT_`bash
+```bash
 python3 scripts/yotta_guardian.py check --batch calls.json --json
-`_BT_`
+```
 
 calls.json 为数组或 {"calls": [...]}，每项含 tool / cmd / path / content / old / new / target。任一被拒时整体退出码取最严重值。
 
@@ -55,25 +55,25 @@ calls.json 为数组或 {"calls": [...]}，每项含 tool / cmd / path / content
 
 确有授权的操作（如正规重启、备份清理）用显式放行，而不是绕过检查：
 
-`_BT_`bash
+```bash
 python3 scripts/yotta_guardian.py check exec --cmd "<命令>" --allow "<模式>"
 python3 scripts/yotta_guardian.py check write --path "<路径>" --allow-path "<前缀>"
-`_BT_`
+```
 
 ### 审计
 
-`_BT_`bash
+```bash
 # 检查时落审计
 python3 scripts/yotta_guardian.py check exec --cmd "<命令>" --audit-log .yotta-guardian/audit.jsonl
 
 # 查询
 python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --tail 20
 python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --denied --json
-`_BT_`
+```
 
 ## 五、JSON 输出结构（check --json）
 
-`_BT_`json
+```json
 {
   "tool": "yotta-guardian",
   "version": "0.1.0",
@@ -93,4 +93,4 @@ python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --den
     }
   ]
 }
-`_BT_`
+```

package/references/rules.md

@@ -101,7 +101,7 @@
 
 ## 六、自定义规则文件（--config）
 
-`_BT_`json
+```json
 {
   "policy": "default",
   "allow": ["^git "],
@@ -109,7 +109,7 @@
   "deny": ["^evil"],
   "verifier": { "command": ["python3", "/path/verifier.py"], "timeout": 30 }
 }
-`_BT_`
+```
 
 - policy: default / strict / loose
 - allow: 命令正则放行模式

package/scripts/guardian_rules.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""guardian_rules.py — YottaMeta 元盾（yotta-guardian）内置规则表（数据，不含匹配逻辑）。
+r"""guardian_rules.py — YottaMeta 元盾（yotta-guardian）内置规则表（数据，不含匹配逻辑）。
 
 本文件只声明规则数据，与 yotta-security-audit（元安）/ yotta-vetter（元审）的
 「源码静态扫描」规则不同：这里是「工具调用护栏」规则，面向 exec / write / edit 等

package/scripts/yotta_guardian.py

@@ -49,9 +49,15 @@ except Exception:
 
 _HERE = Path(__file__).resolve().parent
 sys.path.insert(0, str(_HERE))
-import guardian_rules as GR  # noqa: E402
+try:
+    import guardian_rules as GR  # noqa: E402
+except BaseException as _import_exc:  # 规则表加载失败 = 引擎没跑起来 → 致命异常（4）
+    sys.stderr.write(
+        "致命异常: 规则表加载失败: %s: %s\n" % (type(_import_exc).__name__, _import_exc)
+    )
+    raise SystemExit(4)
 
-VERSION = "0.1.5"
+VERSION = "0.1.7"
 TOOL_NAME = "yotta-guardian"
 TOOL_CN = "元盾"
 
@@ -279,14 +285,15 @@ class RuleEngine:
     def _argv_findings(self, call):
         if call.tool not in ("exec", "run", "shell"):
             return []
-        argv = _tokenize(call.cmd)
-        if not argv:
-            return []
         findings = []
-        # v0.1.5：先做包装解包（sh -c / cmd /c / powershell -Command / sudo / env …），
-        # 否则只看 argv[0] 会漏掉内层真正的危险动词。
-        for sub in _unwrap_argv(argv):
-            findings += self._argv_findings_one(sub)
+        # v0.1.6：先拆复合命令（; && || | & 换行）与命令替换，再逐段解包 +
+        # 跑同一套 argv 规则；v0.1.5 的包装解包对每段继续生效。
+        for seg in _command_segments(call.cmd):
+            argv = _tokenize(seg)
+            if not argv:
+                continue
+            for sub in _unwrap_argv(argv):
+                findings += self._argv_findings_one(sub)
         return findings
 
     def _argv_findings_one(self, argv):
@@ -326,6 +333,12 @@ class RuleEngine:
 
     def _allow_hit(self, call):
         if call.tool in ("exec", "run", "shell"):
+            # v0.1.6：放行规则只覆盖「单一简单命令」。复合命令或命令替换不允许被
+            # 整条放行——否则 `echo ok && <危险命令>` 会借放行规则绕过风险判定。
+            if (len(_split_compound(call.cmd)) > 1
+                    or _extract_substitutions(call.cmd)
+                    or _scan_quotes(call.cmd)):
+                return False
             for rx in self.allow_text + self.allow_patterns:
                 if rx.search(call.cmd):
                     return True
@@ -343,6 +356,14 @@ class RuleEngine:
         findings = []
         if call.tool in ("exec", "run", "shell"):
             findings += self._text_findings(call.cmd, "command")
+            if _scan_quotes(call.cmd):
+                findings.append(Finding("CMD-UNPARSED", "medium", "command",
+                                        "命令引号未闭合，无法可靠拆分，按未知风险处理",
+                                        80))
+            segments = _command_segments(call.cmd)
+            if len(segments) > 1:
+                for seg in segments:
+                    findings += self._text_findings(seg, "command")
             findings += self._argv_findings(call)
         elif call.tool in ("write", "edit"):
             findings += self._path_findings(call.path)
@@ -546,6 +567,144 @@ def _unwrap_argv(argv, depth=0):
     return [argv]
 
 
+# ── 复合命令拆分（v0.1.6）─────────────────────────────────────────────────
+# v0.1.5 解决了包装命令（sh -c / sudo / env …）绕过，但整条命令仍然只按第一个词
+# 做 argv 分析：`echo ok && rm -rf /`、`ls; rm -rf /`、`true || rm -rf /` 里的
+# 危险段藏在分隔符之后，整条命令因此被判放行。现在先按顶层分隔符拆分、再逐段跑
+# 同一套文本 / argv 规则；命令替换（$(...) / `...`）同样展开；拆分不安全时 fail-closed。
+_COMPOUND_SEPARATORS = (";", "|", "&", "\n", "\r")
+_SEGMENT_MAX = 32
+_SEGMENT_DEPTH = 3
+_SUBST_MAX = 16
+_QUOTES = ("'", '"', "`")
+
+
+def _scan_quotes(cmd):
+    """扫描引号闭合情况，返回未闭合的引号字符（全部闭合返回 None）。"""
+    quote = None
+    i = 0
+    n = len(cmd)
+    while i < n:
+        ch = cmd[i]
+        if quote:
+            if quote != "'" and ch == "\\" and i + 1 < n:
+                i += 2
+                continue
+            if ch == quote:
+                quote = None
+            i += 1
+            continue
+        if ch in _QUOTES:
+            quote = ch
+        elif ch == "\\" and i + 1 < n:
+            i += 2
+            continue
+        i += 1
+    return quote
+
+
+def _split_compound(cmd):
+    """按顶层分隔符（; && || | & 换行）拆分命令，引号 / 转义内不拆。"""
+    segs = []
+    cur = []
+    quote = None
+    i = 0
+    n = len(cmd)
+    while i < n:
+        ch = cmd[i]
+        if quote:
+            cur.append(ch)
+            if quote != "'" and ch == "\\" and i + 1 < n:
+                cur.append(cmd[i + 1])
+                i += 2
+                continue
+            if ch == quote:
+                quote = None
+            i += 1
+            continue
+        if ch in _QUOTES:
+            quote = ch
+            cur.append(ch)
+            i += 1
+            continue
+        if ch == "\\" and i + 1 < n:
+            cur.append(ch)
+            cur.append(cmd[i + 1])
+            i += 2
+            continue
+        if ch in _COMPOUND_SEPARATORS:
+            seg = "".join(cur).strip()
+            if seg:
+                segs.append(seg)
+            cur = []
+            i += 1
+            continue
+        cur.append(ch)
+        i += 1
+    seg = "".join(cur).strip()
+    if seg:
+        segs.append(seg)
+    return segs
+
+
+def _extract_substitutions(text):
+    """取出 $(...) 与 `...` 里的内层命令文本（数量上限，防构造爆炸）。"""
+    out = []
+    i = 0
+    n = len(text)
+    while i < n and len(out) < _SUBST_MAX:
+        ch = text[i]
+        if ch == "\\" and i + 1 < n:
+            i += 2
+            continue
+        if ch == "$" and i + 1 < n and text[i + 1] == "(":
+            depth = 0
+            j = i + 1
+            while j < n:
+                if text[j] == "(":
+                    depth += 1
+                elif text[j] == ")":
+                    depth -= 1
+                    if depth == 0:
+                        break
+                j += 1
+            if j < n:
+                out.append(text[i + 2:j])
+                i = j + 1
+                continue
+            break
+        if ch == "`":
+            j = i + 1
+            while j < n and text[j] != "`":
+                if text[j] == "\\":
+                    j += 1
+                j += 1
+            if j < n:
+                out.append(text[i + 1:j])
+                i = j + 1
+                continue
+            break
+        i += 1
+    return out
+
+
+def _command_segments(cmd, depth=0):
+    """展开复合命令与命令替换，返回需要逐段分析的命令文本（去重、保序）。"""
+    segs = _split_compound(cmd)
+    expanded = list(segs)
+    if depth < _SEGMENT_DEPTH:
+        for seg in segs:
+            for sub in _extract_substitutions(seg):
+                expanded += _command_segments(sub, depth + 1)
+    out = []
+    for seg in expanded:
+        if seg and seg not in out:
+            out.append(seg)
+        if len(out) >= _SEGMENT_MAX:
+            break
+    return out
+
+
 # ── argv 级规则（按动词分组）───────────────────────────────────────────────
 
 _RM_VERBS = {"rm", "rmdir", "del", "erase", "unlink", "shred", "remove-item"}
@@ -985,7 +1144,8 @@ def _build_verifier(args):
 
 def _print_check_text(call, verdict, color):
     def c(s, code):
-        return "\033[%sm\033[0m" % (code, s) if color else s
+        # 2026-09-28：原写法只有 1 个 %s 却喂了 2 个参数 → 彩色路径（真人终端）必崩 TypeError。
+        return "\033[%sm%s\033[0m" % (code, s) if color else s
     kind = c("DENY", "31;1") if not verdict.allowed else c("ALLOW", "32;1")
     sev = verdict.severity.upper()
     print("[检查]  %s" % call.describe(300))
@@ -1214,4 +1374,16 @@ def main(argv=None):
 
 
 if __name__ == "__main__":
-    main()
+    # 顶层兜底（2026-09-28）：未捕获异常一律按「致命异常」退出码 4 结束。
+    # 绝不能让引擎崩溃落到 1 —— 契约里 1 = 允许但带警告，按退出码判定的宿主会把
+    # 「护栏没跑起来」读成放行（fail-open）。SystemExit / KeyboardInterrupt 原样透传。
+    try:
+        main()
+    except (SystemExit, KeyboardInterrupt):
+        raise
+    except BaseException as exc:  # 兜底就是要 catch-all
+        try:
+            sys.stderr.write("致命异常: %s: %s\n" % (type(exc).__name__, exc))
+        except Exception:
+            pass
+        raise SystemExit(4)

package/skill-manifest.json

@@ -3,7 +3,7 @@
   "slug": "yotta-guardian",
   "name": "元盾",
   "package": "@yottameta/yotta-guardian",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "trust": "yottameta",
   "install": {
     "idempotent": true