@yottameta/yotta-guardian 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # 更新日志
 
+## 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 级分析的绕过路径。
+
+- 背景：此前 argv 级规则只看命令第一个词（`argv[0]`）。`bash -c "…"`、`cmd /c "…"`、
+  `powershell -Command "…"`、`sudo …`、`env …`、`nohup …`、`timeout 5 …` 这类包装会把真正的
+  动词藏在内层，导致包装后的危险命令被判为放行（例：裸 `rm -rf /` 拒绝，`bash -c "rm -rf /"` 却放行）。
+- 修复：新增受控解包层（`_unwrap_argv` / `_shell_inner` / `_strip_wrapper`）——
+  识别 shell（sh/bash/zsh/dash/ksh/ash/busybox/cmd/powershell/pwsh）、提权与环境包装
+  （sudo/doas/env/nohup/setsid/stdbuf/nice/ionice/time/xargs/timeout/command/builtin/exec/chroot），
+  剥离包装自身的选项与参数后，对内层命令跑同一套 argv 规则；解包深度上限 3 层，可嵌套（如 `sudo sh -c "…"`）。
+- 边界：解包只影响 argv 级动词分析，文本级规则与放行模式行为不变；解包失败时不产生新命中，
+  保持既有判定（不引入误报放大）。
+- 验证：测试 72/72（新增 `WrapperBypassTest` 12 项：9 项阻断回归 + 3 项安全侧不误报）。
+
 ## v0.1.4 (2026-09-19)
 
 版本对齐维护：修复历史发布元数据与包内版本不一致；无功能变更。

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-guardian
-version: 0.1.4
+version: 0.1.6
 description: 元盾 —— 跨智能体的危险调用拦截护栏：确定性规则引擎 + 可插拔意图验证（不绑模型），拦截危险 exec / write / edit / read / run / shell 工具调用，提供审计日志。触发：代理要执行高风险命令（递归删除、磁盘格式化、提权、防火墙改动、反向 shell、下载即执行等）、要写入系统敏感路径或修改系统配置、要在执行危险操作前做安全检查、或用户说 护栏/拦截/危险操作/安全检查 等。边界：默认只读评估，不自动执行也不放行危险操作；不替代用户决策；不隐藏审计记录；规则可配置。
 license: MIT
 ---

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.4",
+  "version": "0.1.6",
   "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/rules.md

@@ -8,7 +8,7 @@
 | 层 | 作用于 | 说明 |
 |---|---|---|
 | 文本模式 | exec 命令 / write 内容 | 正则匹配危险形态（下载即执行、编码执行、反向 shell、向系统文件追加内容等） |
-| argv 级 | exec / run / shell | 命令拆词后按「动词 + 标志 + 目标」分析（递归删除、格式化设备、提权、防火墙、服务、持久化等） |
+| argv 级 | exec / run / shell | 先做包装解包（shell `-c` / `cmd /c` / `powershell -Command` / sudo / env / nohup / timeout 等，深度上限 3），再按「动词 + 标志 + 目标」分析（递归删除、格式化设备、提权、防火墙、服务、持久化等） |
 | 敏感路径 | write / edit / read | 目标路径规范化后按系统核心 / 用户敏感 / 越界分级 |
 | 放行规则 | 命令 / 路径 | 命中则高危可降级为警告（critical 不受影响） |
 

package/scripts/yotta_guardian.py

@@ -51,7 +51,7 @@ _HERE = Path(__file__).resolve().parent
 sys.path.insert(0, str(_HERE))
 import guardian_rules as GR  # noqa: E402
 
-VERSION = "0.1.4"
+VERSION = "0.1.6"
 TOOL_NAME = "yotta-guardian"
 TOOL_CN = "元盾"
 
@@ -279,9 +279,18 @@ 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.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):
         verb = os.path.basename(argv[0]).lower()
         findings = []
         if verb in _RM_VERBS:
@@ -318,6 +327,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
@@ -335,6 +350,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)
@@ -444,6 +467,238 @@ def _tokenize(cmd):
         return cmd.split()
 
 
+# ── 包装命令解包（v0.1.5）─────────────────────────────────────────────────
+# 危险动作常被包装：sh -c "…"、bash -lc "…"、cmd /c "…"、powershell -Command "…"、
+# sudo …、env …、nohup …、timeout 5 …。只分析 argv[0] 会漏掉内层动词，
+# 因此先按已知包装表做受控解包（深度上限），再对内层命令跑同一套 argv 规则。
+_UNWRAP_MAX_DEPTH = 3
+
+_SHELL_WRAPPERS = {
+    "sh", "bash", "zsh", "dash", "ksh", "ash", "busybox",
+    "cmd", "cmd.exe", "powershell", "powershell.exe", "pwsh", "pwsh.exe",
+}
+# shell 的「执行字符串」开关：-c / -lc / -ic / /c / /k / -Command
+_SHELL_EXEC_FLAGS = {"/c", "/k", "-command", "-cmd"}
+_SHELL_EXEC_FLAG_RE = re.compile(r"^-[a-z]*c$")
+
+_WRAPPER_SPECS = {
+    "sudo": {"value_opts": {"-u", "-g", "-p", "-C", "-h", "-r", "-t", "-U",
+                            "--user", "--group", "--prompt", "--chdir", "--host",
+                            "--role", "--type", "--other-user", "--close-from"}},
+    "doas": {"value_opts": {"-u", "-C"}},
+    "env": {"value_opts": {"-u", "-S", "-C", "--unset", "--split-string", "--chdir"},
+            "assignments": True},
+    "nohup": {"value_opts": {}},
+    "setsid": {"value_opts": {}},
+    "stdbuf": {"value_opts": {"-i", "-o", "-e", "--input", "--output", "--error"}},
+    "nice": {"value_opts": {"-n", "--adjustment"}},
+    "ionice": {"value_opts": {"-c", "-n", "-p", "--class", "--classdata", "--pid"}},
+    "time": {"value_opts": {"-o", "-f", "--output", "--format"}},
+    "xargs": {"value_opts": {"-I", "-n", "-P", "-d", "-a", "-E", "-s", "-L",
+                             "--max-args", "--max-procs", "--delimiter", "--arg-file",
+                             "--eof", "--max-chars", "--max-lines"}},
+    "timeout": {"value_opts": {"-s", "-k", "--signal", "--kill-after"},
+                "skip_positional": 1},
+    "command": {"value_opts": {}},
+    "builtin": {"value_opts": {}},
+    "exec": {"value_opts": {}},
+    "chroot": {"value_opts": {"--userspec", "--groups"}},
+    "busybox": {"value_opts": {}},
+}
+
+
+def _shell_inner(argv):
+    """从 shell 包装 argv 中取出执行开关后的内层命令文本（无则返回 None）。"""
+    for i, tok in enumerate(argv[1:], start=1):
+        low = tok.lower()
+        if low in _SHELL_EXEC_FLAGS or _SHELL_EXEC_FLAG_RE.match(low):
+            rest = argv[i + 1:]
+            if not rest:
+                return None
+            parts = []
+            for item in rest:
+                # Windows 下 shlex(posix=False) 会保留外层引号，剥掉后再拼内层命令
+                if len(item) >= 2 and item[0] == item[-1] and item[0] in ("'", '"'):
+                    item = item[1:-1]
+                parts.append(item)
+            return " ".join(parts)
+    return None
+
+
+def _strip_wrapper(argv, spec):
+    """跳过包装命令自身的选项/参数，返回内层命令 argv（找不到则空列表）。"""
+    value_opts = spec.get("value_opts", set())
+    i = 1
+    n = len(argv)
+    while i < n:
+        tok = argv[i]
+        if spec.get("assignments") and "=" in tok and not tok.startswith("-"):
+            i += 1
+            continue
+        if tok == "--":
+            i += 1
+            break
+        if tok.startswith("-") and tok != "-":
+            i += 2 if tok in value_opts else 1
+            continue
+        break
+    i += int(spec.get("skip_positional", 0) or 0)
+    return argv[i:] if i < n else []
+
+
+def _unwrap_argv(argv, depth=0):
+    """返回需要做 argv 级分析的命令列表（含解包出的内层命令）。"""
+    if not argv or depth > _UNWRAP_MAX_DEPTH:
+        return []
+    verb = os.path.basename(argv[0]).lower()
+    if verb in _SHELL_WRAPPERS:
+        inner = _shell_inner(argv)
+        return _unwrap_argv(_tokenize(inner), depth + 1) if inner else []
+    spec = _WRAPPER_SPECS.get(verb)
+    if spec:
+        rest = _strip_wrapper(argv, spec)
+        return _unwrap_argv(rest, depth + 1) if rest else []
+    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"}

package/skill-manifest.json

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