mokuyoaxis/agent-guard

AGENT-GUARD

CI
License
Python 3.9+
v0.2.0 源码

让 AI Agent 的破坏性操作默认可逆。 · English

Agent Guard 是给编码 Agent 用的可靠性工具：让受支持的高风险操作尽可能
可恢复，而不是一次失手就永久损失；日常工作则尽量不被打断。

- 删除文件：可先迁入 .agent-trash/，留下恢复清单，而非直接销毁。
- 破坏性 Git 操作：可先保存可恢复的状态，再覆盖工作树。
- 意外外发：合作式文本 CLI 可检查已知凭据和带本机标识的绝对路径；
持有载荷的调用方按判决应用脱敏计划、请求人工处理或阻断。

共享 Core 支持 Python 3.9+ 和 Git，不依附某个 harness。能否自动拦截，
仍取决于宿主有没有兼容 hook；仅安装 Skill 不会自动拦截工具调用。
Core、决策协议与 Skills 是产品本体，适配器只是可替换的接入桥。

能安全恢复的操作尽量自动完成；不能安全代办时再交给人。
Agent Guard 是可靠性基础设施，不是安全沙箱：它防范失误，
不承诺抵抗拥有相同系统权限的恶意 Agent。

它会怎样处理

rm -rf build/       → RELOCATE   # 工作区内目录先迁入隔离区
rm -rf .            → BLOCK      # 保护工作区根目录
git reset --hard    → SNAPSHOT   # Git 状态允许时先做快照
git push --force    → BLOCK      # 不自动改写远端历史

这是受支持输入的示意判决，不是让你执行这些命令，也不表示所有宿主都会
自动拦截。被忽略且可再生的目标可能判为 ALLOW；Git 快照无法建立时会
保守拒绝。能恢复或安全改写时，Agent 可以继续工作；否则交给人或阻断。

让编码 Agent 帮你接入

先把本仓库放在稳定的本地路径；如果已经有 checkout，跳过克隆：

git clone https://github.com/mokuyoaxis/agent-guard.git
cd agent-guard

Core 需要 Python 3.9+ 和 Git；是否能自动拦截取决于宿主是否提供相应 hook。
把下面这段交给编码 Agent，先替换为你的仓库路径：

请从 /absolute/path/to/agent-guard 为当前工作区接入 agent-guard。
先识别当前 harness 实际支持的 hook 与 Skill，阅读本 README 和对应 adapter
说明，并检查 Python、Git。安装适用的 Skills；只有宿主确实支持时才配置
原生 shell hook。保留现有设置；修改用户级配置或安装依赖前先展示差异并征求确认。
Claude Code 参考 adapters/claude/README.md，Kimi Code 参考
adapters/kimi-code/README.md，DSH 参考 adapters/dsh/README.md。
Codex 或没有已验证 hook 的宿主只接入 Skill/CLI，并明确说明没有自动拦截。
用无害命令和仅作为数据传给 check.py 的 BLOCK 样例验证；不要真正执行
破坏性测试命令。最后报告实际安装内容、宿主确实拦截的范围和未验证路径。

手动接入与证据边界见 harness 能力矩阵
及对应的 adapter README。

设计原则

| 原则 | 做法 |
|---|---|
| 守住边界 | 操作进入 Guard 时，阻断工作区根、.git 和外部路径的删除 |
| 先保留退路 | 受支持的删除先迁入 .agent-trash/ 并记 manifest；破坏性 Git 覆写先做快照 |
| 约束授权 | 授权只在会话内有效；否决会单向降权，只有人能恢复 |
| 留下记录 | 强制判决、补偿 intent、结果和恢复写入追加式 JSONL；intent 无法持久化时拒绝修改 |

贯穿四项原则的一条规则是：越不确定，限制越严格。

决策协议

每个进入 Guard 的操作都会按效果分类，再选择足以维持安全或恢复承诺的
最宽松判决。稳定的跨 harness 接口不是简单的 allow/block，而是一套
Decision Protocol：

效果 → 分类器 → 策略 → Decision   ∈ { ALLOW, SANITIZE, RELOCATE,
SNAPSHOT, ASK, BLOCK }
+ ReasonCode   (稳定机器码)
+ Explanation  (面向人类的解释)
+ RecoveryPlan (txid 与补偿策略)

| 层级 | 判决 | Agent 的体验 |
|---|---|---|
| SAFE | ALLOW · SANITIZE · RELOCATE · SNAPSHOT | 尽量不中断工作；需要时先补偿，可恢复的修改凭 txid 找回。SANITIZE 返回由载荷持有方应用的脱敏计划，不改写命令 |
| AMBIGUOUS | ASK | 单次执行授权(ASK_ONCE)——例如 Guard 无法安全代办的复合形态 |
| FORBIDDEN | BLOCK | 附理由与修正建议拒绝;永不升级为询问 |

当一个操作同时命中多个判决时，由弱到强的优先级为：

ALLOW  SANITIZE,退出码 0
echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/check_span.py --channel file-write

即将进入远端历史的凭据 -> BLOCK,退出码 2
echo 'token=ghp_abcdefghijklmnopqrstuvwxyz…' | python3 skills/exfil-guard/scripts/check_span.py --channel git-push-payload

应用脱敏计划(保留格式:sk-)
echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/sanitize.py --channel file-write

退出码契约:0 = ALLOW/SANITIZED · 2 = BLOCK · 3 = ASK · 1 = ERROR。
--json 输出机器可读判决(仅偏移、rule id 与占位符——*绝不含匹配到的
字节);--path 为即将写入的文件启用仓库本地豁免文件。

不打印值地查看配置

此 CLI 从 0.2.0 源码开始提供，不属于此前的 0.2.0-rc2
源码预览标签。

python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace .env
python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace config.json

文件路径必须相对该工作区。JSON 结果保留字段名与结构，以及标量类型和
set/empty 状态，不返回标量值；已知密钥形态的字段名也会隐藏，
但未知秘密藏在字段名中仍是局限。仅支持 UTF-8 JSON 与严格的单行 dotenv
子集（最多 256 KiB、16 层、2048 个节点）。符号链接、硬链接、特殊文件、
越界路径、无效格式或平台缺少安全的相对目录描述符读取能力时一律拒绝。
退出码 0 表示产生视图，2 表示拒绝，1 表示内部错误。视图仅供诊断，
不能写回覆盖原配置；它也不会拦截 harness 的普通文件读取工具。

与 delete-guard 的关系

它们是同一承诺在动作两侧的两半:

| | delete-guard | exfil-guard |
|---|---|---|
| 问题 | "还能回头吗?" | "这份内容本该离开吗?" |
| 把守 | 删除之前 | 发出之前 |
| 响应 | 先补偿,再执行 | 先脱敏,再发出 |
| 失误代价 | 可凭 txid 恢复 | 不可逆 |
| 入口 | check.py --  | check_span.py(stdin) |

二者共享词汇表(core/policy.py)、聚合逻辑(worst())、豁免纪律与审计
日志。worst() 由两个 Guard 共用,这正是 SANITIZE 的排序只需定义一次的原因。

覆盖范围与局限

这里如实说明,因为一个夸大自身能力的可靠性工具就是一份虚假的安全声明:

- 不是沙箱。 它不阻止对抗性外泄。把密钥混淆以绕过扫描的 Agent 不在
范围内;它抓的是意外。
- 没有 hook 的信道在结构上不可达。 无代理的托管模型调用、模型自身的
工具调用、程序内部产生的内容、人类剪贴板,一律不给判决——不作任何
覆盖声明。详见 references/channels.md 与
docs/secret-guard-analysis.md §2.4 的
可达性表。
- 不是文件扫描器。 它不是 gitleaks 的替代品;它扫描 Guard 在发出
路径上能看到的内容。
- 不改写历史。 检测到已经进入 git 历史的密钥最多只是一份报告。
改写历史是需要人类执行、且自带风险的动作。
- 本版本不含 T3 熵检测器。 它是最大的单一误报来源,而目标场景并不需要它。

手动使用（不依赖特定 harness）

Core 没有第三方依赖。需要 Python 3.9+、POSIX shell 和 Git。

删除文件/目录/glob —— 进入隔离区而非销毁:
python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"

查看状态与恢复:
python3 skills/delete-guard/scripts/status.py
python3 skills/delete-guard/scripts/restore.py list
python3 skills/delete-guard/scripts/restore.py

隔离区维护(默认只出计划,不动数据):
python3 skills/delete-guard/scripts/gc.py

受支持的 harness 适配器可在 shell 命令执行前调用 Guard，再将退出码映射
为宿主自己的工具判决：

python3 skills/delete-guard/scripts/check.py --enforce -- "$COMMAND"
退出码 0 → 宿主可以执行原命令
退出码 2 → 拒绝
退出码 3 → 宿主支持时询问用户；否则拒绝
退出码 1 → Guard 出错，保守拒绝

受保护行为一览

下列是命令确实进入 Guard、且目标符合所述条件时的示意结果；各宿主实际
验证到的范围见 能力矩阵。

rm -rf build/            → RELOCATE  (整树隔离后放行)
rm -rf .                 → BLOCK     (workspace 根)
rm -rf $DIR/             → BLOCK     (目标无法解析:fail-closed)
rm .log                 → BLOCK     (不透明通配;safe_delete 会显式展开)
cd X && rm -rf build     → ASK_ONCE  (COMPOUND_CWD_DELETE)
touch f && rm f          → ASK_ONCE  (COMPOUND_CREATE_DELETE)
git clean -fd            → RELOCATE  (先 -n 枚举迁移再放行)
git reset --hard         → SNAPSHOT  (Git 状态允许建立快照时)
git push --force         → BLOCK     (远端历史不交给 Agent 自动处理)
node_modules/(已 ignore) → ALLOW     (可证明可再生)
隔离区写满               → BLOCK     (绝不回退到永久删除)

接入与验证矩阵

Node.js 20 smoke
Codex Skill/CLI tested
DSH v0.1.1 live-tested
ZCode win32 CLI evaluated
Claude Code hook tested with scripted model
Kimi Code K3 hook observed

“Core 可用”、“受 Skill 引导的 Agent 使用过”和“harness 会强制拦截每次匹配的
工具调用”是三种不同强度的结论：

| Harness | 接入层级 | 证据与边界 |
|---|---|---|
| Claude Code | 原生 PreToolUse adapter | 使用真实 CLI 与 hook、模拟模型端点完成真机测试；映射 allow/ask/deny |
| DSH（DeepSeek Harness） | 原生 adapter | v0.1.1 真机测试；提供瀑布拦截、模型工具与提示层。安装：dsh plugin --profile  add github:mokuyoaxis/agent-guard |
| Codex | Skill + 生产 CLI 验收 | 已主审及前向测试；本仓库不声称存在 Codex 原生透明拦截 hook |
| ZCode | Windows 上的 Skill/CLI 评估 | 已用 GLM-Flash 在 win32 真机测试；证明可移植路径，不等于通用 hook 保证 |
| Kimi Code 0.42.0 | 原生 PreToolUse adapter（Bash） | 两个独立沙盒使用同一 local/kimi-k3 模型，观察到 root、单子代理、并发双子代理的可恢复操作进入 hook；Core ASK 在适配器处被拒绝，不会提示确认。宿主对 BLOCK 判决的执行级拦截仍未证实。 |
| OpenCode / MCP | 规划中 | 尚无支持声明 |

tests/test_conformance.py 覆盖共享 Core 和 Claude adapter；DSH 有 smoke 测试，
Kimi 有针对性 adapter 测试。上述 Kimi 观察只覆盖实测调用，不构成所有 Shell
语法或一般并发子代理安全保证。
各宿主的覆盖范围、证据等级和执行级验收条件见
harness 能力矩阵。

目录结构

agent-guard/
├── skills/delete-guard/   # Agent 行为层:SKILL.md + CLI 脚本
├── skills/exfil-guard/    # 出口侧技能:check_span.py · sanitize.py
├── skills/recovery-audit/ # 证据驱动的仓库审计与恢复
├── core/                  # classifier · policy · recovery · audit · redaction
├── adapters/claude/       # Claude Code PreToolUse hook 适配器
├── adapters/kimi-code/   # Kimi Code PreToolUse hook 适配器
├── adapters/dsh/          # DeepSeek Harness 接入桥
├── adapters/codex/harness/# CLI 验收 driver；不是原生 hook
├── tests/                 # unittest 测试套件,含跨 harness 一致性
└── docs/                  # architecture · threat-model · friction log

Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 git-guard、
database-guard、cloud-guard 直接挂同一补偿引擎,无需重构仓库。

文档

| 阅读 | 内容 |
|---|---|
| docs/architecture.md | 四柱↔组件映射、数据流、关键设计决定 |
| docs/release-notes-0.2.0.md | 0.2.0 变更、证据等级与已知限制 |
| docs/threat-model.md | 诚实边界:它是什么、不是什么 |
| docs/friction.md | 真实 Agent 撞出来的教训(F1–F11) |
| docs/development-note-unguarded-deletion.md | 去标识化事故探索与面向恢复的后续方向 |
| docs/test-report-codex-gpt-5.6-sol.md | v0.1.1 Codex 评估(medium + high) |
| docs/test-report-dsh-v0.1.1.md | v0.1.1 DSH 真机测试(DeepSeek V4 Pro high,极简模式) |
| skills/recovery-audit/SKILL.md | 证据优先级、确定性回放、恢复与落地门禁 |
| skills/delete-guard/references/policy.md | 完整规则表与判决码 |
| skills/exfil-guard/references/rules.md | exfil 规则表、reason code、豁免格式与审计结构 |
| skills/exfil-guard/references/channels.md | 出口信道分类与不可达信道 |

状态与路线图

当前源码版本为 v0.2.0。它保留 v0.1.1 已加固的恢复路径（预写式迁移
intent、Git 快照安全、干净的审计预检和明确的 RESTORABLE / RESTORED
生命周期），并新增 cmd/PowerShell 方言解析、SANITIZE 判决、exfil-guard
以及证据驱动的 recovery-audit Skill。

相较 v0.2.0-rc2 源码预览，本工作树还加入显式只读配置安全视图，并减少
新 check.py 结果与本地记录中的原始命令副本；历史追加式记录不会自动
改写。已发布产物及状态请以
GitHub Releases 为准。

该版本的项目身份与 harness 无关。现有 DSH、Claude adapter，Codex/ZCode
验收证据，以及有边界的 Kimi 实测，只是不断扩展的兼容矩阵，不分别定义产品。
Kimi 结果证明所测调用走通了 hook 补偿路径，不证明宿主强制执行所有 BLOCK，
也不意味着任意 Agent 操作都受保护。真实 Windows 端到端覆盖与一般并发子代理
安全仍是明确缺口。
后续 git-guard、database-guard、cloud-guard 继续复用同一协议与补偿引擎。

0.2.x 预告：guard-lab 合成蜜罐

这是规划中的可选实验，不属于 0.2.0。它会在离线、一次性的测试项目
里放入无认证能力的合成标记，对照正常任务与提示词注入诱导；另设试次观察
harness 是否在 Agent 未请求读取时自行索引或外发文件。正负对照、独立观察器
和证据分级将区分“提出读取”“本地接触”与“证实越过外部边界”。不使用真实
凭据，不默认常驻后台；它也不是抵抗恶意模型或宿主的安全保证。

社区友链

LINUX DO 社区友链

这张自制横幅直达我们的
LINUX DO 项目帖，不代表社区官方推荐。

许可证

MIT —— 见 LICENSE。