ARG Agent Runtime Guard v1.1.6 · local-first runtime guard Trace · Rule · Policy · Fail-open — endpoint first HOOK OBS

Agent Runtime Guard v1.1.6

本地优先 · 零外部依赖 · 把 Agent 动作记成执行链，再做可回滚的轻量强制
Local-First / Tracing-First / Fail-Open Python 3.10+ · pure stdlib Claude Code Hook · Tool Broker observe / alert / redact / deny

1一句话:它是什么

ARG 是一个面向 AI Agent 的 本地运行时安全护栏。 它不是完整 EDR，也不是企业 IAM 平台，而是： 把 Agent 的每一次动作记录成执行链，用本地规则做动态判定，并在可回滚的前提下做轻量强制。

一句话给技术人: 在「模型已经决定调用工具、真实副作用还没发生」的边界上， 挂一层纯 Python 标准库的判定器。默认可以只观察；高置信风险再 deny； Guard 自己挂了，业务不能一起挂。

定位坐标

不是什么

不是模型对齐、不是 prompt 防火墙、不是中心化网关全家桶、不是 eBPF/内核隔离。

是什么

端侧 / 进程内的 trace + rule + policy 闭环：可观测、可灰度、可解释、可回滚。

类比

= 本机 Agent 的“轻量 WAF + auditd + 一键 dry-run”，坐在 tool dispatch 点上。

2它要解决的真实痛点

端侧 Agent（Claude Code / Cursor / Qoder / Electron 产品）已经能读写文件、跑 shell、装依赖、读密钥、出网。 风险不再只是「服务端 API 是否越权」，而是：

① 动作发生在本机

curl | bash、npm install、读 ~/.ssh、打 metadata endpoint—— 中心网关经常看不见，或来不及看见。

② 二阶注入最后落成 tool call

网页 / 邮件 / 商品详情里的指令，最终都要变成一次 tool 调用。 prompt 里“请忽略”没用；dispatcher 前判一次有用。

③ 强制太早会被卸掉

端侧 fail-closed 一误伤开发流，用户就关 Guard。 关了等于裸奔。所以 ARG 先把 精确率 / 体验 / 降级通道 当最高优先级。

核心判断: 你不能让概率模型自己当警察。 必须把动作抽成结构（tool / args / resource / actor），再用确定性规则判。 ARG 做的就是这件事——而且默认允许灰度，不当单点故障。

3核心链路:一条事件怎么走完

Runtime Event JSONL / Hook JSON Normalize models.py Rule Engine recommended mode Policy Layer enforce / dry-run Decision: observe · alert · redact · deny mode / recommended_mode / enforced / rule_id / reason / latency_ms 检测与强制解耦：规则只推荐，策略决定是否真正拦 Redact secrets 落库前掩码密钥 SQLite Trace trace_id 可还原执行链
运行时事件 → 规范化 → 规则引擎(推荐决策) → 策略层(强制/dry-run/allowlist) → 脱敏 → 本地 SQLite → CLI 查询 / Hook 回写

决策结构（可解释）

{
  "mode": "observe",            // 实际生效
  "recommended_mode": "deny",   // 规则推荐
  "enforced": false,           // dry-run / allowlist 时为 false
  "rule_id": "block-metadata-access",
  "reason": "Agent network request targets cloud metadata endpoint"
}

4设计原则（差异化来源）

  1. Local-First — 零外部依赖
    纯标准库，单机可跑。中心不可用时，本机 Guard 仍可工作； 这是端侧 Agent 场景的硬要求。
  2. Tracing-First — 先看见再强制
    先完整记录 context → action → object → decision， 再谈拦截。很多事故不是“没拦住”，而是“说不清谁干的”。
  3. Fail-Open — 安全组件不当 SPOF
    规则异常 / 判定超时 → 默认放行并记账。 宁可短暂漏，也不因 Guard 把自己变成全员停摆。
  4. 检测 / 强制解耦 — Policy as Code
    规则只出推荐；policy.json 决定 enforce / dry-run / allowlist。 一键 --observe 全局回滚，便于推广灰度。
企业落地纪律: 高 TP（true positive）与零噪音优先于“看起来很严”。 先 observe 证明 precision，再对高置信规则开 deny。 没有精确率，就没有强制权。

5规则与策略

默认规则覆盖（节选）

rule_idmode说明
block-metadata-accessdeny拦截 cloud metadata endpoint
deny-dangerous-shelldeny破坏性 / 远程执行 shell（含常见混淆）
deny-package-install-shelldeny拦截 npm/pip/apt 等依赖安装
deny-sensitive-file-readdeny拦截 ~/.ssh、.env、kubeconfig 等
redact-secret-logredact日志落库前掩码密钥
alert-identity-collapsealert用户身份塌缩成 service account
alert-external-context-shellalert外部上下文触发 shell
deny-cross-tenant-oss-writedenyOSS 跨租户命名空间越界

策略层（强制开关）

{
  "default_mode": "enforce",
  "dry_run": false,
  "apps": { "demo-agent": "enforce" },
  "allowlist": [
    {
      "rule_id": "deny-sensitive-file-read",
      "app_id": "demo-agent",
      "reason": "known safe probe"
    }
  ]
}

dry_run: true 或 CLI --observe：推荐仍是 deny，实际 mode 降为 observe， 但命中率继续统计——这是推广时最关键的“先证明再拦截”。

事件类型

context_received · tool_call · network_request · oss_operation · log_write · shell_exec · file_read

6端侧接入路线

ARG 优先面向 端侧 Agent Runtime：Claude Code、Cursor、Qoder、Electron + LLM 产品。 不同客户端只写 Adapter；规则、策略、trace、benchmark 复用。

Endpoint Agent Claude / Cursor / Electron Hook / Broker PreToolUse / Tool Broker Guard Core rules + policy + SQLite Decision allow/alert/deny 副作用发生前判定 · Hook 失败时 fail-open

Claude Code

关键点 PreToolUse。危险 Bash / 装依赖 / 读密钥可 deny； 普通测试命令只 observe，不抢宿主权限系统。 提供 Node wrapper：异常 exit fail-open，避免 Guard 阻断开发。

Electron / function-call

外部商品信息、网页、附件一旦影响工具调用，先经 Main Process Tool Broker 转成 ARG event，再决定 observe / ask / deny。 模型输出绝不能直通原始 command runner。

建议观测链路: SessionStart → UserPromptSubmit（intent anchor）→ PreToolUse（主判定）→ PostToolUse → Stop/SessionEnd。

7Agentic 威胁模型（工程分类）

类别含义ARG 现状
过度主动理解了任务，但越过授权边界高危 shell / 安装 / 敏感文件 deny；其余 alert
诚实误判无恶意，但误判环境/归属/影响面租户 OSS 前缀、私网访问、metadata 拦截
Prompt Injection外部上下文劫持目标外部 context 触发网络/shell 告警；dispatcher 前硬拦高危后果
模型失配行为持续无法用用户目标解释靠 trace 还原；不做完整行为基线（边界内）
诚实边界: ARG 不保证阻断所有 prompt injection； 它优先阻断高置信危险后果，并留下可复盘的执行链。 不做 eBPF；不做完整沙箱；不把服务端业务 API 鉴权当第一优先级。

8对比 AGT：互补，不是替代

ARG微软 AGT
默认姿态fail-open 灰度fail-closed 默认拒绝
依赖零外部依赖 / 纯 stdlib多语言 SDK + 可选 Rust/OPA/Cedar
重心端侧 Runtime / Hook / Tool Broker企业应用中间件 / 身份 / 沙箱 / 合规
审计本地 SQLite + trace_idMerkle / 签名 TRACE / Decision Record
卖点灰度不可能停摆结构上不可能作恶
上手一条 CLI demo概念面厚，生产配置成本高

什么时候选 ARG 思路

端侧 Agent、开发者本机、试点推广、需要 dry-run 证明 precision、 安全组件不能成为 SPOF。

什么时候选 AGT 思路

强合规生产、多 Agent 身份归因、防篡改审计、 需要 fail-closed 的“宁可全停，不可裸奔”。
落地建议: 企业统一入口可走大模型安全网关（低侵入）； 端侧真实副作用仍要 Tool Call / Hook / Broker 兜底。 ARG 与 AGT 是不同 blast radius 上的纵深，不是二选一。

95 分钟上手

# 需要 Python 3.10+，无第三方依赖
# 1. 内置 demo（覆盖主要风险类别）
python3 -m agent_runtime_guard.cli demo

# 2. 一键全局观察模式（推荐决策仍记，强制降级）
python3 -m agent_runtime_guard.cli demo --observe

# 3. 处理自己的 JSONL
python3 -m agent_runtime_guard.cli ingest \
  --events examples/demo_events.jsonl \
  --rules  rules/default_rules.json \
  --policy config/policy.json \
  --db     .arg/trace.db

# 4. 按 trace 还原执行链
python3 -m agent_runtime_guard.cli trace demo-ssrf --timeline

# 5. Claude Code PreToolUse demo
python3 -m agent_runtime_guard.cli hook claude-code \
  --input examples/claude_code_pretooluse_bash_danger.json

# 6. labeled benchmark / 对抗样本
python3 -m agent_runtime_guard.cli bench
python3 -m agent_runtime_guard.cli bench --events examples/evasion_events.jsonl --strict

验收时看什么

  • precision：deny/alert 有多少是真风险（人工核验）
  • dry_run_hits：灰度期间“若 enforce 会拦什么”
  • latency_ms：端侧可接受的判定延迟
  • bypass_rate：对抗样本（混淆 shell / 编码 IP / MCP 边界）漏报率