@yottameta/yotta-guardian 0.1.0

package/references/intent-verifier.md

@@ -0,0 +1,76 @@
+
+# 意图验证器协议（yotta-guardian）
+
+> 元盾默认纯确定性规则、不调用任何模型。需要语义级复核时，可通过本协议外接任意意图验证器（LLM 网关、本地模型、规则脚本均可），**不绑定任何固定模型**。
+
+## 一、启用方式
+
+1. 命令行外接：--verifier "命令 参数..."（字符串按 shell 规则拆分；Windows 下路径建议用配置文件列表形式避免反斜杠转义问题）
+2. 配置文件：{"verifier": {"command": ["python3", "/path/verifier.py"], "timeout": 30}}
+3. 内置启发式：--heuristic（本地确定性复核，不联网）
+
+## 二、请求（stdin，JSON）
+
+引擎对「允许」结论的调用发起验证，写入 stdin 的 JSON：
+
+`_BT_`json
+{
+  "tool": "exec",
+  "cmd": "npm install",
+  "path": "",
+  "content_preview": "",
+  "target": "",
+  "policy": "default",
+  "cwd": "/home/user/project",
+  "findings": []
+}
+`_BT_`
+
+字段说明：tool 为工具类型；cmd / path / content_preview（内容前 500 字符）/ target 为调用内容；policy 为当前策略；findings 为确定性规则已命中的条目（允许结论下通常为空或仅低危）。
+
+## 三、响应（stdout，JSON）
+
+`_BT_`json
+{
+  "verdict": "allow",
+  "severity": "low",
+  "reason": "安装依赖，无恶意信号"
+}
+`_BT_`
+
+- verdict：allow / deny / review 三选一（必须）。
+- severity：可选，deny 时默认 high；取值 info / low / medium / high / critical。
+- reason：可选，展示给用户的原因。
+
+## 四、判定语义
+
+| 验证器 verdict | 引擎处理 |
+|---|---|
+| allow | 维持确定性结论（允许） |
+| deny | 升级为拒绝，严重级取响应 severity（默认 high） |
+| review | 若当前为允许且低危，升级为「建议复核」（medium 警告，exit 1） |
+| 无响应 / 超时 / 输出非法 | 按 review 处理（复核，不静默放行也不误杀） |
+
+已拒绝的调用不会调用验证器（省成本，避免覆盖确定性结论）。
+
+## 五、内置启发式（--heuristic）
+
+本地确定性复核：扫描调用文本中的高影响动词（install / uninstall / delete / remove / overwrite / reset / drop / truncate / purge / cleanup / restart / reboot / shutdown / stop / disable / enable / start / upgrade / update / format / wipe 等），命中则升级为「建议复核」。不联网、可复现、适合作为轻量语义补充。
+
+## 六、示例验证器（Python 桩）
+
+`_BT_`python
+#!/usr/bin/env python3
+import json
+import sys
+
+req = json.load(sys.stdin)
+cmd = req.get("cmd", "")
+if cmd.startswith("danger"):
+    out = {"verdict": "deny", "severity": "high", "reason": "命中自定义策略"}
+else:
+    out = {"verdict": "allow", "severity": "low", "reason": "无风险信号"}
+json.dump(out, sys.stdout)
+`_BT_`
+
+真实场景可用该协议把调用摘要发给 LLM 网关做语义判断，返回同样的 JSON 即可接入。

package/references/policies.md

@@ -0,0 +1,96 @@
+
+# 策略 / 退出码 / 使用姿势（yotta-guardian）
+
+## 一、三档策略
+
+| 策略 | 行为 | 适用场景 |
+|---|---|---|
+| default（默认） | critical / high 拒绝；medium 警告（exit 1）；low 允许 | 通用默认，安全与可用平衡 |
+| strict | critical / high / medium 一律拒绝；low 提示 | 高风险环境、不可逆操作前置检查 |
+| loose | 仅 critical 拒绝；high 警告；medium / low 允许 | 需要高可用、仅拦最危险动作 |
+
+放行规则（--allow / --allow-path / ALLOW_PATTERNS / 配置文件 allow）可把 high 降级为警告、medium 降级为允许；**critical 不受放行规则影响**。
+
+## 二、退出码
+
+| 退出码 | 含义 | 对应 |
+|---|---|---|
+| 0 | 允许（无 finding 或仅 low） | allowed |
+| 1 | 允许但带警告 / 严格策略下拒绝 medium | 需人工复核 |
+| 2 | 拒绝（high） | denied |
+| 3 | 拒绝（critical） | denied |
+| 4 | 用法错误 / 致命异常 | error |
+
+AI 智能体判断：退出码非 0 时不要直接执行；2 / 3 一律停下并向用户报告原因。
+
+## 三、判定优先级
+
+1. 确定性规则引擎先跑（文本 + argv + 路径 + 内容）。
+2. 放行规则判定（allow 命中可降级，critical 除外）。
+3. 策略裁决（default / strict / loose）。
+4. 若配置了意图验证器且当前结论为「允许」，再跑验证器（外部或内置启发式），可把允许升级为复核 / 拒绝；已拒绝的调用不跑验证器。
+
+## 四、使用姿势（AI 智能体）
+
+### 执行前 gate
+
+`_BT_`bash
+python3 scripts/yotta_guardian.py check exec --cmd "<待执行命令>" --json
+`_BT_`
+
+- exit 0：执行。
+- exit 1：执行但提示用户「护栏给出中危警告」。
+- exit 2 / 3：不执行；向用户说明命中规则（rule_ids 与原因）。
+- exit 4：命令用法错误，检查参数。
+
+### 批量预检
+
+`_BT_`bash
+python3 scripts/yotta_guardian.py check --batch calls.json --json
+`_BT_`
+
+calls.json 为数组或 {"calls": [...]}，每项含 tool / cmd / path / content / old / new / target。任一被拒时整体退出码取最严重值。
+
+### 授权放行
+
+确有授权的操作（如正规重启、备份清理）用显式放行，而不是绕过检查：
+
+`_BT_`bash
+python3 scripts/yotta_guardian.py check exec --cmd "<命令>" --allow "<模式>"
+python3 scripts/yotta_guardian.py check write --path "<路径>" --allow-path "<前缀>"
+`_BT_`
+
+### 审计
+
+`_BT_`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
+{
+  "tool": "yotta-guardian",
+  "version": "0.1.0",
+  "policy": "default",
+  "summary": { "calls": 1, "allowed": 0, "denied": 1, "exit": 3 },
+  "results": [
+    {
+      "call": { "tool": "exec", "cmd": "..." },
+      "verdict": "deny",
+      "allowed": false,
+      "severity": "critical",
+      "reason": "拒绝：...",
+      "rule_ids": ["ARG-RM-SYSTEM"],
+      "findings": [ { "rule_id": "...", "severity": "critical", "category": "command", "reason": "...", "confidence": 95 } ],
+      "verifier": null,
+      "exit": 3
+    }
+  ]
+}
+`_BT_`

package/references/rules.md

@@ -0,0 +1,118 @@
+
+# 规则目录（yotta-guardian）
+
+> 本文件说明元盾的规则分层与内置规则清单。规则数据在 scripts/guardian_rules.py，匹配逻辑在 scripts/yotta_guardian.py。
+
+## 一、规则分层
+
+| 层 | 作用于 | 说明 |
+|---|---|---|
+| 文本模式 | exec 命令 / write 内容 | 正则匹配危险形态（下载即执行、编码执行、反向 shell、向系统文件追加内容等） |
+| argv 级 | exec / run / shell | 命令拆词后按「动词 + 标志 + 目标」分析（递归删除、格式化设备、提权、防火墙、服务、持久化等） |
+| 敏感路径 | write / edit / read | 目标路径规范化后按系统核心 / 用户敏感 / 越界分级 |
+| 放行规则 | 命令 / 路径 | 命中则高危可降级为警告（critical 不受影响） |
+
+## 二、文本模式规则（TEXT_PATTERNS）
+
+| 规则号 | 严重级 | 作用域 | 说明 |
+|---|---|---|---|
+| CMD-PIPE-SHELL | critical | both | curl 下载内容通过管道交给 shell 执行 |
+| CMD-PIPE-WGET | critical | both | wget 下载内容通过管道交给 shell 执行 |
+| CMD-PS-ENCODED | critical | both | PowerShell 编码命令执行 |
+| CMD-B64-EXEC | critical | both | 解码后执行编码内容 |
+| CMD-REV-BASH | critical | both | bash /dev/tcp 反向 shell |
+| CMD-REV-NC | critical | both | netcat 反向 shell（-e 参数） |
+| CMD-CHMOD-SETID | high | both | chmod 设置 setuid / setgid / sticky 权限位（4 位特殊位形态） |
+| CMD-CHMOD-777 | high | both | chmod 设置全权限位 |
+| CMD-SUDOERS-ECHO | critical | both | 向 sudoers 写入内容（提权持久化） |
+| CMD-PASSWD-FILE | critical | both | 向 passwd 写入内容（账户持久化） |
+| CMD-SSH-EXFIL | high | command | 读取 SSH 私钥后外传 |
+| CTX-PRIVKEY | high | content | 写入私钥材料 |
+| CTX-SECRET-TOKEN | medium | content | 写入疑似密钥 / 令牌 |
+
+作用域说明：both = 命令与内容都扫；command = 仅命令文本；content = 仅写入内容。
+
+## 三、argv 级规则（按动词分组，匹配逻辑在引擎）
+
+| 规则号 | 严重级 | 触发示例（动词形态） |
+|---|---|---|
+| ARG-RM-SYSTEM | critical | 递归删除系统关键路径（/、/etc、/usr、/home、/boot、/dev、/var、C: 等） |
+| ARG-RM-SYS-SUB | high | 递归删除系统目录下路径（如 /var 之下） |
+| ARG-RM-ABS | high | 递归删除项目外绝对路径 |
+| ARG-RM-REL | medium | 递归删除相对路径目标 |
+| ARG-FMT-DEVICE | critical | 格式化块设备 / 磁盘（/dev/sd*、C:） |
+| ARG-FMT-TARGET | high | 格式化其他目标 |
+| ARG-DD-DEVICE | critical | dd 直接写入块设备 / 磁盘 |
+| ARG-DD-FILE | high | dd 写入磁盘镜像目标 |
+| ARG-POWER | high | 系统电源 / 重启操作 |
+| ARG-CHMOD-777 | high/critical | chmod 设置全权限位（对系统关键路径为 critical） |
+| ARG-CHMOD-SETID | high | chmod 设置 setuid / setgid / sticky |
+| ARG-CHOWN-SYSTEM | critical | chown 修改系统关键路径属主 |
+| ARG-CHOWN-REC | medium | 递归修改文件属主 |
+| ARG-PRIV-ACCOUNT | high | 账户管理（useradd / userdel / groupadd 等） |
+| ARG-PRIV-GROUP | high | 把用户加入管理员组 |
+| ARG-PRIV-PASSWD | high | 修改账户口令 |
+| ARG-PRIV-SU | medium | 切换用户身份 |
+| ARG-PRIV-SUDOERS | high | 编辑 sudoers |
+| ARG-PRIV-NET | high | 把用户加入 Windows 管理员组 |
+| ARG-FW-FLUSH | high | 清空防火墙规则 |
+| ARG-FW-UFW | high | 禁用 / 重置防火墙 |
+| ARG-FW-NETSH | high | 关闭 Windows 防火墙 |
+| ARG-FW-CHANGE | medium | 修改防火墙规则 |
+| ARG-SVC-STOP | medium | 停止 / 禁用系统服务 |
+| ARG-SVC-START | medium | 启用系统服务 |
+| ARG-SVC-SC | high | 删除 / 停止 Windows 服务 |
+| ARG-CRON | high | 修改 / 删除 crontab（持久化） |
+| ARG-REG-RUN | high | 修改注册表启动项 |
+| ARG-REG | medium | 修改注册表 |
+| ARG-SCHTASKS | high | 创建 / 修改计划任务（持久化） |
+| ARG-REV-NC | critical | netcat 反向 shell |
+| ARG-REV-SOCAT | critical | socat 执行远程命令（反向 shell） |
+| ARG-PS-ENCODED | critical | PowerShell 编码命令执行 |
+
+## 四、敏感路径规则（PATH_PATTERNS）
+
+| 规则号 | 严重级 | 说明 |
+|---|---|---|
+| PATH-ETC-CORE | critical | 写入系统核心配置文件（passwd / shadow / sudoers / group / fstab / hosts 等） |
+| PATH-ETC-ADMIN | critical | 写入系统管理目录（sudoers.d / cron.d / systemd / init.d / rc.d） |
+| PATH-BOOT | critical | 写入 /boot 启动分区 |
+| PATH-DEVICE | critical | 直接写入块设备 |
+| PATH-PROC-SYS | critical | 写入 /proc 或 /sys 内核接口 |
+| PATH-WIN-CONFIG | critical | 写入 Windows 注册表配置库（system32\\config） |
+| PATH-WIN-HOSTS | critical | 写入 Windows hosts 文件 |
+| PATH-WIN-BOOT | critical | 写入 Windows 启动文件 |
+| PATH-ETC-ANY | high | 写入 /etc 任意位置 |
+| PATH-SSH-AUTH | high | 写入 SSH 授权 / 私钥文件 |
+| PATH-RC-FILES | high | 写入 shell / 凭据配置文件（bashrc / zshrc / profile / netrc / gitconfig / npmrc 等） |
+| PATH-AWS-CRED | high | 写入云服务凭据文件 |
+| PATH-CRON-SPOOL | high | 写入 cron 任务队列 |
+| PATH-WIN-SYS32 | high | 写入 Windows 系统目录 |
+| PATH-STARTUP | high | 写入系统启动项目录 |
+| PATH-SECRET-FILE | medium | 写入疑似凭据 / 密钥文件（.env / pem / key 等） |
+
+引擎另有一条通用规则 OUT-001（medium）：写入当前工作目录之外的目标。
+
+## 五、放行规则
+
+- 默认放行模式（ALLOW_PATTERNS）：明确安全的只读 / 查询命令前缀（ls / git status / 版本查询等），命中后高危可降级为警告。
+- 命令行放行：--allow "模式"（命令正则，可重复）、--allow-path "路径"（写路径前缀，可重复）。
+- critical 规则**不可**被放行规则覆盖（需人工确认后换用更低风险方案或 loose 策略仍会拒绝）。
+
+## 六、自定义规则文件（--config）
+
+`_BT_`json
+{
+  "policy": "default",
+  "allow": ["^git "],
+  "allow_paths": ["./tmp"],
+  "deny": ["^evil"],
+  "verifier": { "command": ["python3", "/path/verifier.py"], "timeout": 30 }
+}
+`_BT_`
+
+- policy: default / strict / loose
+- allow: 命令正则放行模式
+- allow_paths: 写路径放行前缀
+- deny: 自定义拒绝模式（命中记 CFG-DENY，严重级 high）
+- verifier: 意图验证器配置（heuristic: true 或 command 数组），见 intent-verifier.md

package/scripts/guardian_rules.py

@@ -0,0 +1,175 @@
+# -*- coding: utf-8 -*-
+"""guardian_rules.py — YottaMeta 元盾（yotta-guardian）内置规则表（数据，不含匹配逻辑）。
+
+本文件只声明规则数据，与 yotta-security-audit（元安）/ yotta-vetter（元审）的
+「源码静态扫描」规则不同：这里是「工具调用护栏」规则，面向 exec / write / edit 等
+动作本身（命令文本 / 目标路径 / 写入内容）。
+
+结构：
+  TEXT_PATTERNS   文本模式规则（按 scope 作用于命令文本 / 写入内容 / 两者）
+  PATH_PATTERNS   敏感路径规则（作用于 write / edit / read 的目标路径）
+  ALLOW_PATTERNS  默认放行模式（作用域宽、明确安全的动作）
+
+规则撰写约束（防 ReDoS / 防误报 / 自扫不误报，与元安规则表同一纪律）：
+- 不使用嵌套量词；量词作用于字符类或固定串。
+- 危险词之间用 \s、\b、[\\/] 等转义隔开，避免把本文件自身的字面量误报为命中。
+"""
+import re
+from collections import namedtuple
+
+# 单条文本规则：规则号 / 严重级 / 类别 / 作用域 / 正则源码 / 描述 / 置信度(0-100)
+# scope: "command"=仅命令文本， "content"=仅写入内容， "both"=两者
+TextRule = namedtuple(
+    "TextRule", ["id", "severity", "category", "scope", "pattern", "reason", "confidence"]
+)
+
+SEVERITY_ORDER = ("info", "low", "medium", "high", "critical")
+SEVERITY_VALUE = {"info": 0, "low": 0, "medium": 1, "high": 2, "critical": 3}
+
+TEXT_PATTERNS = [
+    # ── 下载即执行 / 编码执行 ─────────────────────────────────────────────
+    TextRule("CMD-PIPE-SHELL", "critical", "command", "both",
+             r"(?i)\bcurl\b[^\n|;]{0,120}\|\s*(?:ba)?sh\b",
+             "curl 下载内容通过管道交给 shell 执行", 95),
+    TextRule("CMD-PIPE-WGET", "critical", "command", "both",
+             r"(?i)\bwget\b[^\n|;]{0,120}\|\s*(?:ba)?sh\b",
+             "wget 下载内容通过管道交给 shell 执行", 95),
+    TextRule("CMD-PS-ENCODED", "critical", "command", "both",
+             r"(?i)\b(?:powershell|pwsh)\b[^\n|;]{0,120}(?:-e\s*n\s*c|-encodedcommand)\b",
+             "PowerShell 编码命令执行", 85),
+    TextRule("CMD-B64-EXEC", "critical", "command", "both",
+             r"(?i)(?:b64decode|base64)\s*\([^)]{0,120}\)\s*[^\n;]{0,60}\b(?:exec|eval|system)\b",
+             "解码后执行编码内容", 85),
+
+    # ── 反向 shell / 反弹连接 ────────────────────────────────────────────
+    TextRule("CMD-REV-BASH", "critical", "command", "both",
+             r"(?i)\bbash\s+-i\s*>\s*&?\s*/dev/tcp/",
+             "bash /dev/tcp 反向 shell", 95),
+    TextRule("CMD-REV-NC", "critical", "command", "both",
+             r"(?i)\bnc\b\s+[-A-Za-z0-9. ]{0,40}-e\b",
+             "netcat 反向 shell（-e 参数）", 95),
+
+    # ── 高危系统改动（文本形态，argv 级另有更细规则）─────────────────────
+    TextRule("CMD-CHMOD-SETUID", "high", "command", "both",
+             r"(?i)\bchmod\s+[1-7][0-7]{3}\b",
+             "chmod 设置 setuid / setgid / sticky 权限位", 85),
+    TextRule("CMD-CHMOD-777", "high", "command", "both",
+             r"(?i)\bchmod\s+777\b",
+             "chmod 设置全权限位", 75),
+    TextRule("CMD-SUDOERS-ECHO", "critical", "command", "both",
+             r"(?i)(?:>>|>)\s*[^\n;]{0,60}/etc/sudoers",
+             "向 sudoers 写入内容（提权持久化）", 92),
+    TextRule("CMD-PASSWD-FILE", "critical", "command", "both",
+             r"(?i)(?:>>|>)\s*[^\n;]{0,60}/etc/passwd",
+             "向 passwd 写入内容（账户持久化）", 92),
+
+    # ── 凭据外传 / 危险读取 ──────────────────────────────────────────────
+    TextRule("CMD-SSH-EXFIL", "high", "command", "command",
+             r"(?i)(?:id_[a-z0-9]+|\.ssh)[^\n;]{0,80}(?:\bcurl\b|\bwget\b|scp\b|rsync\b)",
+             "读取 SSH 私钥后外传", 90),
+    TextRule("CTX-PRIVKEY", "high", "content", "content",
+             r"-{5}BEGIN\s+(?:[A-Z ]+\s+)?PRIVATE\s+KEY-{5}",
+             "写入私钥材料", 90),
+    TextRule("CTX-SECRET-TOKEN", "medium", "content", "content",
+             r"(?i)\b(?:AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{30,}|xox[baprs]-[A-Za-z0-9-]{10,})\b",
+             "写入疑似密钥/令牌", 70),
+]
+
+PATH_PATTERNS = [
+    # ── critical：系统核心 / 设备 / 启动链 ────────────────────────────────
+    TextRule("PATH-ETC-CORE", "critical", "path", "write",
+             r"(?i)[\\/]etc[\\/](?:passwd|shadow|sudoers|group|fstab|hosts|ld\.so\.preload|rc\.local)$",
+             "写入系统核心配置文件", 95),
+    TextRule("PATH-ETC-ADMIN", "critical", "path", "write",
+             r"(?i)[\\/]etc[\\/](?:sudoers\.d|cron\.d|cron\b|systemd[\\/]system|init\.d|rc\.d)[\\/]",
+             "写入系统管理目录（sudoers / cron / systemd / init）", 95),
+    TextRule("PATH-BOOT", "critical", "path", "write",
+             r"(?i)[\\/]boot(?:[\\/]|$)",
+             "写入 /boot 启动分区", 92),
+    TextRule("PATH-DEVICE", "critical", "path", "write",
+             r"(?i)[\\/]dev[\\/]sd[a-z]+\d*$",
+             "直接写入块设备（磁盘）", 95),
+    TextRule("PATH-PROC-SYS", "critical", "path", "write",
+             r"(?i)[\\/](?:proc|sys)[\\/]",
+             "写入 /proc 或 /sys 内核接口", 92),
+    TextRule("PATH-WIN-CONFIG", "critical", "path", "write",
+             r"(?i)^[a-z]:[\\/]windows[\\/]system32[\\/]config[\\/]",
+             "写入 Windows 注册表配置库", 95),
+    TextRule("PATH-WIN-HOSTS", "critical", "path", "write",
+             r"(?i)^[a-z]:[\\/]windows[\\/]system32[\\/]drivers[\\/]etc[\\/]hosts$",
+             "写入 Windows hosts 文件", 92),
+    TextRule("PATH-WIN-BOOT", "critical", "path", "write",
+             r"(?i)^[a-z]:[\\/]boot(?:mgr|\.ini)?$",
+             "写入 Windows 启动文件", 92),
+
+    # ── high：用户级敏感 / 系统管理区域 / 启动持久化点 ────────────────────
+    TextRule("PATH-ETC-ANY", "high", "path", "write",
+             r"(?i)[\\/]etc[\\/]",
+             "写入 /etc 系统配置目录", 85),
+    TextRule("PATH-SSH-AUTH", "high", "path", "write",
+             r"(?i)\.ssh[\\/](?:authorized_keys|config|id_[a-z0-9]+)$",
+             "写入 SSH 授权 / 私钥文件", 92),
+    TextRule("PATH-RC-FILES", "high", "path", "write",
+             r"(?i)[\\/]\.?(?:bashrc|zshrc|profile|bash_profile|netrc|gitconfig|npmrc|pypirc)$",
+             "写入 shell / 凭据配置文件（持久化或泄密点）", 85),
+    TextRule("PATH-AWS-CRED", "high", "path", "write",
+             r"(?i)\.aws[\\/](?:credentials|config)$",
+             "写入云服务凭据文件", 90),
+    TextRule("PATH-CRON-SPOOL", "high", "path", "write",
+             r"(?i)[\\/]var[\\/]spool[\\/]cron[\\/]",
+             "写入 cron 任务队列", 88),
+    TextRule("PATH-WIN-SYS32", "high", "path", "write",
+             r"(?i)^[a-z]:[\\/]windows[\\/]",
+             "写入 Windows 系统目录", 85),
+    TextRule("PATH-STARTUP", "high", "path", "write",
+             r"(?i)(?:start\s*menu[\\/]programs[\\/]startup|启动|\\startup[\\/])",
+             "写入系统启动项目录（持久化）", 85),
+
+    # ── medium：项目内敏感文件名 / 越界写入（引擎另加 OUT-001）────────────
+    TextRule("PATH-SECRET-FILE", "medium", "path", "write",
+             r"(?i)(?:^|[\\/])\.env(?:$|[\\/])|\.(?:pem|key|p12|pfx)$|(?:credential|secret|token)[^\\/]*$",
+             "写入疑似凭据 / 密钥文件", 70),
+]
+
+# 默认放行模式（仅作用于命令文本，命中则高危可降级为警告；critical 不受影响）
+ALLOW_PATTERNS = [
+    r"(?i)^\s*(?:ls|dir|pwd|whoami|date|echo|cat|type|head|tail|grep|find|which|where|env|printenv)\b",
+    r"(?i)^\s*git\s+(?:status|diff|log|branch|remote|show)\b",
+    r"(?i)^\s*(?:python3?|node|npm|pip3?|uv|npx)\s+(-{1,2}\S+\s+)*(-[vV]\b|--version\b|version)",
+]
+
+
+def severity_value(sev):
+    """严重级 → 数值（0=干净/仅 low，1=medium，2=high，3=critical）。"""
+    return SEVERITY_VALUE.get(sev, 0)
+
+
+def severity_rank(sev):
+    """严重级 → 排序权重（越大越严重）。"""
+    try:
+        return SEVERITY_ORDER.index(sev)
+    except ValueError:
+        return 0
+
+
+_COMPILED = {}
+
+
+def compile_rules():
+    """预编译全部文本规则与路径规则，返回 {rule_id: compiled}。"""
+    if _COMPILED:
+        return _COMPILED
+    for r in list(TEXT_PATTERNS) + list(PATH_PATTERNS):
+        try:
+            _COMPILED[r.id] = re.compile(r.pattern)
+        except re.error as e:
+            raise ValueError("规则 %s 正则编译失败: %s" % (r.id, e))
+    return _COMPILED
+
+
+def get_rule(rule_id):
+    """按规则号取规则（文本/路径/放行）。"""
+    for r in list(TEXT_PATTERNS) + list(PATH_PATTERNS):
+        if r.id == rule_id:
+            return r
+    return None