@mokuyoaxis/agent-guard 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/CONTRIBUTING.md +101 -0
  2. package/LICENSE +21 -0
  3. package/README.md +558 -0
  4. package/README.zh-CN.md +488 -0
  5. package/adapters/INTEGRATION.md +94 -0
  6. package/adapters/claude/README.md +141 -0
  7. package/adapters/claude/compatibility.json +17 -0
  8. package/adapters/claude/harness/README.md +59 -0
  9. package/adapters/claude/harness/mock_anthropic_api.mjs +47 -0
  10. package/adapters/claude/harness/run_scenario.sh +79 -0
  11. package/adapters/claude/harness/run_scenario_no_python3.sh +49 -0
  12. package/adapters/claude/hook_bridge.sh +33 -0
  13. package/adapters/claude/pre_tool_use.py +264 -0
  14. package/adapters/claude/settings.example.json +16 -0
  15. package/adapters/codex/harness/README.md +53 -0
  16. package/adapters/codex/harness/acceptance.py +226 -0
  17. package/adapters/dsh/README.md +62 -0
  18. package/adapters/dsh/cordis.patch.yml +30 -0
  19. package/adapters/dsh/lib/index.js +500 -0
  20. package/adapters/kimi-code/README.md +169 -0
  21. package/adapters/kimi-code/compatibility.json +17 -0
  22. package/adapters/kimi-code/config.example.toml +26 -0
  23. package/adapters/kimi-code/hook_bridge.sh +32 -0
  24. package/adapters/kimi-code/pre_tool_use.py +72 -0
  25. package/core/__init__.py +47 -0
  26. package/core/audit.py +86 -0
  27. package/core/classifier.py +1175 -0
  28. package/core/dialects.py +898 -0
  29. package/core/policy.py +817 -0
  30. package/core/recovery.py +700 -0
  31. package/core/redaction.py +1096 -0
  32. package/core/safe_view.py +212 -0
  33. package/docs/architecture.md +223 -0
  34. package/docs/compatibility.md +142 -0
  35. package/docs/development-note-unguarded-deletion.md +187 -0
  36. package/docs/friction.md +266 -0
  37. package/docs/harness-capabilities.md +72 -0
  38. package/docs/host-drift.md +142 -0
  39. package/docs/publishing-from-ephemeral-environments.md +104 -0
  40. package/docs/release-notes-0.2.0-rc1.md +46 -0
  41. package/docs/release-notes-0.2.0.md +72 -0
  42. package/docs/release-notes-0.2.1.md +78 -0
  43. package/docs/release-notes-0.2.2.md +120 -0
  44. package/docs/secret-guard-analysis.md +416 -0
  45. package/docs/secret-guard-architecture.md +93 -0
  46. package/docs/secret-guard-design.md +649 -0
  47. package/docs/test-report-claude-code-harness.md +462 -0
  48. package/docs/test-report-codex-gpt-5.6-sol.md +335 -0
  49. package/docs/test-report-codex-gpt-6-astra-high.md +129 -0
  50. package/docs/test-report-dsh-0.1.5-rc.1.md +84 -0
  51. package/docs/test-report-dsh-v0.1.1.md +126 -0
  52. package/docs/test-report-kimi-code-block.md +198 -0
  53. package/docs/test-report-zcode-glm-flash.md +241 -0
  54. package/docs/threat-model.md +44 -0
  55. package/doctor.py +756 -0
  56. package/live_sentinel.py +339 -0
  57. package/package.json +69 -0
  58. package/skills/delete-guard/SKILL.md +109 -0
  59. package/skills/delete-guard/agents/openai.yaml +4 -0
  60. package/skills/delete-guard/references/policy.md +161 -0
  61. package/skills/delete-guard/scripts/_bootstrap.py +8 -0
  62. package/skills/delete-guard/scripts/check.py +370 -0
  63. package/skills/delete-guard/scripts/gc.py +103 -0
  64. package/skills/delete-guard/scripts/restore.py +98 -0
  65. package/skills/delete-guard/scripts/safe_delete.py +256 -0
  66. package/skills/delete-guard/scripts/status.py +130 -0
  67. package/skills/exfil-guard/SKILL.md +143 -0
  68. package/skills/exfil-guard/agents/openai.yaml +4 -0
  69. package/skills/exfil-guard/references/channels.md +58 -0
  70. package/skills/exfil-guard/references/rules.md +194 -0
  71. package/skills/exfil-guard/scripts/_bootstrap.py +8 -0
  72. package/skills/exfil-guard/scripts/check_span.py +250 -0
  73. package/skills/exfil-guard/scripts/sanitize.py +155 -0
  74. package/skills/exfil-guard/scripts/view.py +44 -0
  75. package/skills/recovery-audit/SKILL.md +283 -0
  76. package/skills/recovery-audit/agents/openai.yaml +4 -0
  77. package/skills/recovery-audit/references/evidence-records.md +85 -0
@@ -0,0 +1,488 @@
1
+ # AGENT-GUARD
2
+
3
+ [![CI](https://github.com/mokuyoaxis/agent-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/mokuyoaxis/agent-guard/actions/workflows/ci.yml)
4
+ [![npm 版本](https://img.shields.io/npm/v/%40mokuyoaxis%2Fagent-guard.svg)](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
5
+ [![License](https://img.shields.io/github/license/mokuyoaxis/agent-guard)](LICENSE)
6
+ [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
7
+ [![v0.2.2 源码](https://img.shields.io/badge/%E6%BA%90%E7%A0%81-v0.2.2-5B6B7A)](https://github.com/mokuyoaxis/agent-guard/releases)
8
+
9
+ **让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
10
+
11
+ Agent Guard 是给编码 Agent 用的可靠性工具:让受支持的高风险操作尽可能
12
+ 可恢复,而不是一次失手就永久损失;日常工作则尽量不被打断。
13
+
14
+ - **删除文件**:可先迁入 `.agent-trash/`,留下恢复清单,而非直接销毁。
15
+ - **破坏性 Git 操作**:可先保存可恢复的状态,再覆盖工作树。
16
+ - **意外外发**:合作式文本 CLI 可检查已知凭据和带本机标识的绝对路径;
17
+ 持有载荷的调用方按判决应用脱敏计划、请求人工处理或阻断。
18
+
19
+ 共享 Core 支持 Python 3.9+ 和 Git,不依附某个 harness。能否自动拦截,
20
+ 仍取决于宿主有没有兼容 hook;仅安装 Skill 不会自动拦截工具调用。
21
+ Core、决策协议与 Skills 是产品本体,适配器只是可替换的接入桥。
22
+
23
+ > **能安全恢复的操作尽量自动完成;不能安全代办时再交给人。**
24
+ > Agent Guard 是可靠性基础设施,不是安全沙箱:它防范失误,
25
+ > 不承诺抵抗拥有相同系统权限的恶意 Agent。
26
+
27
+ ## 它会怎样处理
28
+
29
+ ```text
30
+ rm -rf build/ → RELOCATE # 工作区内目录先迁入隔离区
31
+ rm -rf . → BLOCK # 保护工作区根目录
32
+ git reset --hard → SNAPSHOT # Git 状态允许时先做快照
33
+ git push --force → BLOCK # 不自动改写远端历史
34
+ ```
35
+
36
+ 这是受支持输入的**示意判决**,不是让你执行这些命令,也不表示所有宿主都会
37
+ 自动拦截。被忽略且可再生的目标可能判为 `ALLOW`;Git 快照无法建立时会
38
+ 保守拒绝。能恢复或安全改写时,Agent 可以继续工作;否则交给人或阻断。
39
+
40
+ ## 让编码 Agent 帮你接入
41
+
42
+ 可以在 npm registry 可用后安装带作用域的包,也可以保留一个稳定的 Git
43
+ checkout。不要误装无作用域的同名 `agent-guard` 包。
44
+
45
+ 把固定版本安装到用户选择的稳定路径:
46
+
47
+ ```sh
48
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.2
49
+ ```
50
+
51
+ 安装后的包根目录是
52
+ `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`。
53
+ 也可以克隆源码;如果已有 checkout,跳过克隆:
54
+
55
+ ```sh
56
+ git clone https://github.com/mokuyoaxis/agent-guard.git
57
+ cd agent-guard
58
+ ```
59
+
60
+ Core 需要 Python 3.9+ 和 Git;是否能自动拦截取决于宿主是否提供相应 hook。
61
+ 把下面这段交给编码 Agent,先替换为你的仓库路径:
62
+
63
+ ```text
64
+ 请为当前工作区接入 agent-guard。只使用现有 Git checkout,或精确的 scoped
65
+ npm 包 @mokuyoaxis/agent-guard@0.2.2;不要安装无作用域的同名 agent-guard。
66
+ 安装前先让我选择并批准一个稳定的用户目录,然后把 checkout 或 npm 安装后的
67
+ 包根目录作为下文的 /absolute/path/to/agent-guard。
68
+ 先识别当前 harness 实际支持的 hook 与 Skill,阅读本 README 和对应 adapter
69
+ 说明,并检查 Python、Git。安装适用的 Skills;只有宿主确实支持时才配置
70
+ 原生 shell hook。保留现有设置;修改用户级配置或安装依赖前先展示差异并征求确认。
71
+ Claude Code 参考 adapters/claude/README.md,Kimi Code 参考
72
+ adapters/kimi-code/README.md,DSH 参考 adapters/dsh/README.md。
73
+ 其他宿主先读 adapters/INTEGRATION.md,不要凭空假设原生 hook;没有已验证的
74
+ 调用前阻断能力时只接入 Skill/CLI,并明确说明没有自动拦截。
75
+ 用无害命令和仅作为数据传给 check.py 的 BLOCK 样例验证;不要真正执行
76
+ 破坏性测试命令。Claude/Kimi 可运行本地 doctor,但不能把其 PASS 当成宿主
77
+ 拦截证明。最后报告宿主版本、工具范围、实际安装内容、确实拦截的调用和未验证路径。
78
+ ```
79
+
80
+ 手动接入与证据边界见 [harness 能力矩阵](docs/harness-capabilities.md)
81
+ 及对应的 adapter README。
82
+
83
+ ## 设计原则
84
+
85
+ | 原则 | 做法 |
86
+ |---|---|
87
+ | **守住边界** | 操作进入 Guard 时,阻断工作区根、`.git` 和外部路径的删除 |
88
+ | **先保留退路** | 受支持的删除先迁入 `.agent-trash/` 并记 manifest;破坏性 Git 覆写先做快照 |
89
+ | **约束授权** | 授权只在会话内有效;否决会单向降权,只有人能恢复 |
90
+ | **留下记录** | 强制判决、补偿 intent、结果和恢复写入追加式 JSONL;intent 无法持久化时拒绝修改 |
91
+
92
+ 贯穿四项原则的一条规则是:**越不确定,限制越严格。**
93
+
94
+ ## 决策协议
95
+
96
+ 每个进入 Guard 的操作都会按效果分类,再选择足以维持安全或恢复承诺的
97
+ 最宽松判决。稳定的跨 harness 接口不是简单的 allow/block,而是一套
98
+ Decision Protocol:
99
+
100
+ ```
101
+ 效果 → 分类器 → 策略 → Decision ∈ { ALLOW, SANITIZE, RELOCATE,
102
+ SNAPSHOT, ASK, BLOCK }
103
+ + ReasonCode (稳定机器码)
104
+ + Explanation (面向人类的解释)
105
+ + RecoveryPlan (txid 与补偿策略)
106
+ ```
107
+
108
+ | 层级 | 判决 | Agent 的体验 |
109
+ |---|---|---|
110
+ | **SAFE** | `ALLOW` · `SANITIZE` · `RELOCATE` · `SNAPSHOT` | 尽量不中断工作;需要时先补偿,可恢复的修改凭 txid 找回。`SANITIZE` 返回由**载荷持有方**应用的脱敏计划,不改写命令 |
111
+ | **AMBIGUOUS** | `ASK` | 单次执行授权(`ASK_ONCE`)——例如 Guard 无法安全代办的复合形态 |
112
+ | **FORBIDDEN** | `BLOCK` | 附理由与修正建议拒绝;永不升级为询问 |
113
+
114
+ 当一个操作同时命中多个判决时,由弱到强的优先级为:
115
+
116
+ ```
117
+ ALLOW < SANITIZE < RELOCATE < SNAPSHOT < ASK < BLOCK
118
+ ```
119
+
120
+ `SANITIZE` 排在 `ASK` **之下**是有意的:它属于自动化的 SAFE 层,
121
+ 而 `ASK` 需要人处理。载荷里同时有可脱敏的密钥和无法改写的部分时,
122
+ 不能只处理前者便静默放行。
123
+
124
+ 真正无法确定效果的命令(如 `$VAR` 目标、`bash -c`、`find -delete`)
125
+ 会被拒绝;放行它们就无法守住边界。适配器再把判决映射到宿主机制:
126
+ DSH 的 `PreToolDecision`、Claude Code PreToolUse 的 `ask`,或在不支持
127
+ 询问的宿主中附带解释的拒绝。
128
+
129
+ ## Agent Guard 包含什么
130
+
131
+ ### `delete-guard`
132
+
133
+ 回答“删了还能找回来吗?”通过受支持的适配器或 CLI 调用时,
134
+ 它在删除或破坏性 Git 操作前检查,并在可恢复时先做补偿。
135
+
136
+ ### `exfil-guard`
137
+
138
+ 回答“这份内容本该离开本机吗?”载荷持有方主动调用其合作式 CLI 时,
139
+ 它在发出前检查文本,并针对受支持的模式返回脱敏或升级判决。
140
+
141
+ ### `recovery-audit`
142
+
143
+ 如果预防没有运行或没有覆盖那条路径,它负责事故后的证据整理:
144
+ 区分原文恢复、依据重建与确认缺失,审计回放工具,并把落地、提交、
145
+ 推送和发布保留为独立授权门。
146
+
147
+ `delete-guard` 和 `exfil-guard` 是两条预防分支;
148
+ `recovery-audit` 负责事后的证据驱动恢复。
149
+
150
+ ## recovery-audit
151
+
152
+ 有时预防根本没有机会运行:harness 没有 adapter、子代理绕开预期路径,或范围过大的
153
+ 命令在人工介入前删掉了 workspace。工作树可能已经消失,但编码 Agent 的会话缓存里
154
+ 仍可能保存成功 patch、文件快照、工具结果、diff 与命令上下文。
155
+
156
+ `recovery-audit` 把这些残留,与 Git remote/reflog/stash、编辑器或工具缓存、构建产物
157
+ 和项目计划一起组织成证据驱动的恢复流程:
158
+
159
+ - 每个单元明确标记为**原文恢复(recovered)**、**依据重建(reconstructed)**或
160
+ **确认缺失(missing)**;
161
+ - 按真实时间顺序回放工具效果,并检查记录与回放是否分歧;
162
+ - 同一份冻结证据重复回放,必须得到逐字节一致的树;
163
+ - 落地、commit、push 与 release 始终是互相独立的授权门。
164
+
165
+ 它不是文件系统 undelete,也不能创造任何幸存来源从未保存过的字节。它承诺的是:
166
+ 尽快恢复到证据真正支持的最强项目状态,并把缺口写清楚,而不是藏起来。
167
+
168
+ ## exfil-guard
169
+
170
+ `exfil-guard` 检查 Agent 即将写入、发送、提交或推送的文本,前提是
171
+ **载荷持有方主动调用它的 CLI**。它还提供对指定 JSON/dotenv 配置文件的
172
+ 显式只读安全视图。文本扫描针对两类意外外发:**已知凭据**和
173
+ **带本机标识的绝对路径**。依据信道,Guard 可放行、返回脱敏计划、
174
+ 请求人处理或阻断。
175
+
176
+ 它做的是预防和脱敏,不是补偿:内容发出去后就不能撤销。它也**不是
177
+ 安全沙箱**,不负责抵抗拥有相同系统权限的 Agent 蓄意外泄。
178
+
179
+ ### exfil-guard 的四种判决
180
+
181
+ 完整决策协议仍然适用,但文本载荷只会落到其中四类
182
+ (`RELOCATE`/`SNAPSHOT` 属于 delete-guard——Guard 无法改写自己没写过的东西):
183
+
184
+ | 判决 | 含义 | 示例 |
185
+ |---|---|---|
186
+ | `ALLOW` | 无匹配,或命中受控占位符、工作区内相对路径 | `echo "hello" \| check_span.py` |
187
+ | `SANITIZE` | 返回脱敏计划;由**载荷持有方**改写后再发出 | `file-write` / `llm-request` 上的真实密钥 |
188
+ | `ASK` | 信道既不能改写也无法收回 | `shell-stdout` 上的本机路径 |
189
+ | `BLOCK` | 拒绝:不可变/远端历史、载荷无法扫描、配置非法 | `git-push-payload` 中的凭据 |
190
+
191
+ ### 检测什么
192
+
193
+ **T1 厂商凭据特征**(`secret/*`,确定性,误报接近零)。rule id 包括:
194
+ `secret/openai-key`、`secret/github-token`、`secret/aws-access-key-id`、
195
+ `secret/gitlab-token`、`secret/slack-token`、`secret/stripe-key`
196
+ (仅 live key,`sk_test_` 豁免)、`secret/jwt`(结构化:头部必须 base64
197
+ 解码为含 `alg` 的 JSON),以及 `secret/private-key-block`
198
+ (整段 `-----BEGIN ... PRIVATE KEY-----` 一次性脱敏)。冻结规则表见
199
+ [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md)。
200
+
201
+ **不读值的密钥引用**(`secret/source-reference`)。Guard 只对变量**名**
202
+ (`*KEY*`、`*TOKEN*`、`*SECRET*`、`*PASSWORD*`、`*CRED*`、`*AUTH*`)与
203
+ 密钥库**文件名**(`.env`、`*.pem`、`id_rsa*`、`.netrc`、`kubeconfig` 等)
204
+ 分类,并识别整环境展开(`printenv`、`env | ...`、
205
+ `cat /proc/self/environ`)。这个扫描器**不解析变量的值**;这不代表其他
206
+ Guard 输出或已有审计记录都已证明不含秘密。
207
+
208
+ **带本机标识的路径**(`path/*`)。`path/workspace-relative` 为 `ALLOW`
209
+ (工作区豁免);`path/system`(`/usr`、`/etc`、`C:\Windows`)为 `ALLOW`;
210
+ `path/host-absolute`(位于 `HOME`/`TEMP`、CI 根或工作区祖先之下)为
211
+ `SANITIZE`;`path/generic-absolute`(与本机无关联)为 `ASK`;
212
+ `path/device`(UNC、`\\?\`、管道)为 `SANITIZE`。
213
+
214
+ ### 信道决定处置
215
+
216
+ 信道由两个事实定义:能否**改写**、发出后是否**留存**。`rewritable`
217
+ 决定了 `SANITIZE` 是否有意义;`persistence` 决定了 `BLOCK` 是否成立。
218
+
219
+ | 信道 | 可改写 | 留存 | 默认 |
220
+ |---|---|---|---|
221
+ | `llm-request` | 是 | 远端 | SANITIZE |
222
+ | `file-write` | 是 | 工作区 | SANITIZE |
223
+ | `forge-comment` / `issue-body` / `pr-description` | 是 | 公开 | SANITIZE |
224
+ | `git-commit-message` | 是(改 argv) | 远端历史 | **BLOCK** |
225
+ | `git-push-payload` | 否 | **远端** | **BLOCK** |
226
+ | `shell-stdout` | **否** | 本地记录 | ASK |
227
+ | `shell-file-redirect` | 是 | 本地 | ASK |
228
+ | `archive-upload` | 是 | 远端 | ASK |
229
+ | `process-argv` | 是 | 本地 | ASK |
230
+
231
+ 信道名未知属于配置缺陷,而非"无风险":`check_span.py` 返回
232
+ `BLOCK_OUTPUT_UNSCANNABLE`,绝不隐式放行。
233
+
234
+ ### 使用示例
235
+
236
+ `check_span.py` 从 **stdin** 读取载荷,是纯函数——不写文件、不改写、
237
+ 也不打印匹配内容。`sanitize.py` 应用 Guard 返回的计划。
238
+
239
+ ```bash
240
+ # 可改写信道上的凭据 -> SANITIZE,退出码 0
241
+ echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/check_span.py --channel file-write
242
+
243
+ # 即将进入远端历史的凭据 -> BLOCK,退出码 2
244
+ echo 'token=ghp_abcdefghijklmnopqrstuvwxyz…' | python3 skills/exfil-guard/scripts/check_span.py --channel git-push-payload
245
+
246
+ # 应用脱敏计划(保留格式:sk-<REDACTED>)
247
+ echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/sanitize.py --channel file-write
248
+ ```
249
+
250
+ 退出码契约:`0` = ALLOW/SANITIZED · `2` = BLOCK · `3` = ASK · `1` = ERROR。
251
+ `--json` 输出机器可读判决(仅偏移、rule id 与占位符——**绝不含匹配到的
252
+ 字节**);`--path` 为即将写入的文件启用仓库本地豁免文件。
253
+
254
+ ### 不打印值地查看配置
255
+
256
+ 此 CLI 从 `0.2.0` 源码开始提供,**不属于**此前的 `0.2.0-rc2`
257
+ 源码预览标签。
258
+
259
+ ```bash
260
+ python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace .env
261
+ python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace config.json
262
+ ```
263
+
264
+ 文件路径必须相对该工作区。JSON 结果保留字段名与结构,以及标量类型和
265
+ `set`/`empty` 状态,**不返回标量值**;已知密钥形态的字段名也会隐藏,
266
+ 但未知秘密藏在字段名中仍是局限。仅支持 UTF-8 JSON 与严格的单行 dotenv
267
+ 子集(最多 256 KiB、16 层、2048 个节点)。符号链接、硬链接、特殊文件、
268
+ 越界路径、无效格式或平台缺少安全的相对目录描述符读取能力时一律拒绝。
269
+ 退出码 `0` 表示产生视图,`2` 表示拒绝,`1` 表示内部错误。视图仅供诊断,
270
+ 不能写回覆盖原配置;它也不会拦截 harness 的普通文件读取工具。
271
+
272
+ ### 与 delete-guard 的关系
273
+
274
+ 它们是同一承诺在动作两侧的两半:
275
+
276
+ | | `delete-guard` | `exfil-guard` |
277
+ |---|---|---|
278
+ | 问题 | "还能回头吗?" | "这份内容本该离开吗?" |
279
+ | 把守 | **删除之前** | **发出之前** |
280
+ | 响应 | 先补偿,再执行 | 先脱敏,再发出 |
281
+ | 失误代价 | 可凭 txid 恢复 | **不可逆** |
282
+ | 入口 | `check.py -- <command>` | `check_span.py`(stdin) |
283
+
284
+ 二者共享词汇表(`core/policy.py`)、聚合逻辑(`worst()`)、豁免纪律与审计
285
+ 日志。`worst()` 由两个 Guard 共用,这正是 `SANITIZE` 的排序只需定义一次的原因。
286
+
287
+ ### 覆盖范围与局限
288
+
289
+ 这里如实说明,因为一个夸大自身能力的可靠性工具就是一份虚假的安全声明:
290
+
291
+ - **不是沙箱。** 它不阻止对抗性外泄。把密钥混淆以绕过扫描的 Agent 不在
292
+ 范围内;它抓的是**意外**。
293
+ - **没有 hook 的信道在结构上不可达。** 无代理的托管模型调用、模型自身的
294
+ 工具调用、程序内部产生的内容、人类剪贴板,一律**不给判决**——不作任何
295
+ 覆盖声明。详见 `references/channels.md` 与
296
+ [docs/secret-guard-analysis.md](docs/secret-guard-analysis.md) §2.4 的
297
+ 可达性表。
298
+ - **不是文件扫描器。** 它不是 gitleaks 的替代品;它扫描 Guard 在**发出
299
+ 路径上**能看到的内容。
300
+ - **不改写历史。** 检测到已经进入 git 历史的密钥最多只是一份报告。
301
+ 改写历史是需要人类执行、且自带风险的动作。
302
+ - **本版本不含 T3 熵检测器。** 它是最大的单一误报来源,而目标场景并不需要它。
303
+
304
+ ## 手动使用(不依赖特定 harness)
305
+
306
+ Core 没有第三方依赖。需要 Python 3.9+、POSIX shell 和 Git。
307
+
308
+ ```bash
309
+ # 删除文件/目录/glob —— 进入隔离区而非销毁:
310
+ python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
311
+
312
+ # 查看状态与恢复:
313
+ python3 skills/delete-guard/scripts/status.py
314
+ python3 skills/delete-guard/scripts/restore.py list
315
+ python3 skills/delete-guard/scripts/restore.py <txid>
316
+
317
+ # 隔离区维护(默认只出计划,不动数据):
318
+ python3 skills/delete-guard/scripts/gc.py
319
+ ```
320
+
321
+ 受支持的 harness 适配器可在 shell 命令执行前调用 Guard,再将退出码映射
322
+ 为宿主自己的工具判决:
323
+
324
+ ```text
325
+ python3 skills/delete-guard/scripts/check.py --enforce -- "$COMMAND"
326
+ 退出码 0 → 宿主可以执行原命令
327
+ 退出码 2 → 拒绝
328
+ 退出码 3 → 宿主支持时询问用户;否则拒绝
329
+ 退出码 1 → Guard 出错,保守拒绝
330
+ ```
331
+
332
+ ## 受保护行为一览
333
+
334
+ 下列是命令确实进入 Guard、且目标符合所述条件时的示意结果;各宿主实际
335
+ 验证到的范围见 [能力矩阵](docs/harness-capabilities.md)。
336
+
337
+ ```text
338
+ rm -rf build/ → RELOCATE (整树隔离后放行)
339
+ rm -rf . → BLOCK (workspace 根)
340
+ rm -rf $DIR/ → BLOCK (目标无法解析:fail-closed)
341
+ rm *.log → BLOCK (不透明通配;safe_delete 会显式展开)
342
+ cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
343
+ touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
344
+ git clean -fd → RELOCATE (先 -n 枚举迁移再放行)
345
+ git reset --hard → SNAPSHOT (Git 状态允许建立快照时)
346
+ git push --force → BLOCK (远端历史不交给 Agent 自动处理)
347
+ node_modules/(已 ignore) → ALLOW (可证明可再生)
348
+ 隔离区写满 → BLOCK (绝不回退到永久删除)
349
+ ```
350
+
351
+ ## 接入与验证矩阵
352
+
353
+ [![Node.js 20 smoke](https://img.shields.io/badge/Node.js-20%20smoke-339933?logo=nodedotjs&logoColor=white)](.github/workflows/ci.yml)
354
+ [![Codex Skill/CLI tested](https://img.shields.io/badge/Codex-Skill%2FCLI%20tested-000000?logo=openai&logoColor=white)](docs/test-report-codex-gpt-6-astra-high.md)
355
+ [![DSH 0.1.5-rc.1 宿主 BLOCK 实测](https://img.shields.io/badge/DSH%200.1.5--rc.1-%E5%AE%BF%E4%B8%BB%20BLOCK%20%E5%AE%9E%E6%B5%8B-4D6BFE)](docs/test-report-dsh-0.1.5-rc.1.md)
356
+ [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/test-report-zcode-glm-flash.md)
357
+ [![Claude Code hook tested with scripted model](https://img.shields.io/badge/Claude%20Code-hook%20tested%20%28scripted%20model%29-D97757?logo=anthropic&logoColor=white)](docs/test-report-claude-code-harness.md)
358
+ [![Kimi Code 2.1.1 K3 Bash BLOCK](https://img.shields.io/badge/Kimi%20Code%202.1.1-K3%20Bash%20BLOCK-5B9BD5)](docs/test-report-kimi-code-block.md)
359
+
360
+ “Core 可用”、“受 Skill 引导的 Agent 使用过”和“harness 会强制拦截每次匹配的
361
+ 工具调用”是三种不同强度的结论:
362
+
363
+ | Harness/实测版本 | 接入路径 | 证据与边界 |
364
+ |---|---|---|
365
+ | **Claude Code 2.1.270 / 2.1.273** | [Bash 原生 `PreToolUse`](adapters/claude/README.md) | [真实 CLI+脚本模型](docs/test-report-claude-code-harness.md):抽样 allow/ask/deny 与 Python 启动故障;其他工具未验证。 |
366
+ | **DSH 0.1.5-rc.1** | [原生 pre-execute adapter](adapters/dsh/README.md) | [真实宿主、无模型、打包插件探针](docs/test-report-dsh-0.1.5-rc.1.md):无害放行、执行级 `BLOCK`、旁路标记缺席和已加载 adapter 的 Core 故障拒绝;模型/Agent 与非 `bash` 路径未验证。 |
367
+ | **Codex CLI 0.154.0(所测会话)** | [Skill + 生产 CLI](docs/test-report-codex-gpt-6-astra-high.md) | 较早源码的合作式验收;不声称原生 hook。 |
368
+ | **ZCode(版本未记录;win32)** | [历史 Skill/CLI+hook 试次](docs/test-report-zcode-glm-flash.md) | 旧报告记录了持久许可绕过 hook;当前版本未验证。 |
369
+ | **Kimi Code 0.42.0 / 2.1.1** | [Bash 原生 `PreToolUse`](adapters/kimi-code/README.md) | [有界实测](docs/test-report-kimi-code-block.md):2.1.1 在 OAuth 官模和维护者确认的官方 K3 可信中转上均取得根 Bash PASS;0.42.0 另有主/子代理 BLOCK、ASK 硬拒绝和 Python 故障拒绝。hook 缺席/超时仍可能放行。 |
370
+ | **其他/未列出宿主** | [自适配指南](adapters/INTEGRATION.md) | 未独立验证调用前阻断与目标未执行前,不作原生支持声明。 |
371
+
372
+ 由 Agent 协助接入时,先识别真实宿主版本与工具名称,阅读上表对应指南,
373
+ 保留已有配置,并分别报告配置、本地探针、真实宿主三层证据。未列出的宿主
374
+ 依照[自适配清单](adapters/INTEGRATION.md)操作;提示词或 adapter 退出码
375
+ 本身不是拦截证明。修改用户级设置、安全策略或依赖前先征求确认。
376
+
377
+ `tests/test_conformance.py` 覆盖共享 Core 和 Claude adapter;DSH 有 smoke 测试,
378
+ Kimi 有针对性 adapter 测试。上述 Kimi 观察只覆盖实测调用,不构成所有 Shell
379
+ 语法或一般并发子代理安全保证。
380
+ Kimi 或 Claude 安装可分别运行 `python3 doctor.py kimi --probe`、
381
+ `python3 doctor.py claude --probe`,无需模型调用即可检查所选配置文件与
382
+ 本地 shell 桥。加 `--json` 可获取 `configuration`、`local_probe`、
383
+ `host_interception` 机器可读状态;最后一项始终为 `UNVERIFIED`,
384
+ 因为本工具不能证明实际会话加载或强制执行了 hook。参见
385
+ [Kimi](adapters/kimi-code/README.md) 与 [Claude](adapters/claude/README.md)
386
+ 适配指南。加 `--check-drift` 会在本机查询宿主版本,并对所选 hook 结构与
387
+ Agent Guard 运行路径生成去敏指纹;结果使用 `CURRENT`、`STALE`、
388
+ `DRIFTED`、`BROKEN` 或 `UNVERIFIED`。即使是 `CURRENT` 也只代表静态预检,
389
+ 不是实时拦截证明。可选基线只保存解析后的版本和 SHA-256 指纹,详见
390
+ [宿主漂移检查说明](docs/host-drift.md)。显式 `--live-sentinel` 可在私有空白
391
+ 夹具中消耗一次已配置模型调用,按 `PASS`、`FAIL`、`INCONCLUSIVE` 返回
392
+ `NONE`/`NOTICE`、`CRITICAL` 或 `WARNING` 报警;仅仅“标记不存在”绝不算
393
+ 通过。它保留哈希化/去敏结果而不保留模型原始输出。这是可信提供方下的
394
+ 可靠性探针,不是针对恶意模型的沙盒。Kimi 的可选 doctor 因 TOML 解析需要 Python 3.11+;Core 与
395
+ hook adapter 仍支持 Python 3.9+。
396
+ 各宿主的覆盖范围、证据等级和执行级验收条件见
397
+ [harness 能力矩阵](docs/harness-capabilities.md)。
398
+
399
+ ## 目录结构
400
+
401
+ ```
402
+ agent-guard/
403
+ ├── skills/delete-guard/ # Agent 行为层:SKILL.md + CLI 脚本
404
+ ├── skills/exfil-guard/ # 出口侧技能:check_span.py · sanitize.py
405
+ ├── skills/recovery-audit/ # 证据驱动的仓库审计与恢复
406
+ ├── core/ # classifier · policy · recovery · audit · redaction
407
+ ├── doctor.py # 本地配置、探针与宿主漂移预检
408
+ ├── live_sentinel.py # 可选实宿主哨兵与报警证据
409
+ ├── adapters/INTEGRATION.md # 未列出宿主的自适配检查清单
410
+ ├── adapters/claude/ # Claude Code PreToolUse hook 适配器
411
+ ├── adapters/kimi-code/ # Kimi Code PreToolUse hook 适配器
412
+ ├── adapters/dsh/ # DeepSeek Harness 接入桥
413
+ ├── adapters/codex/harness/# CLI 验收 driver;不是原生 hook
414
+ ├── tests/ # unittest 测试套件,含跨 harness 一致性
415
+ └── docs/ # architecture · threat-model · friction log
416
+ ```
417
+
418
+ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`、
419
+ `database-guard`、`cloud-guard` 直接挂同一补偿引擎,无需重构仓库。
420
+
421
+ ## 文档
422
+
423
+ | 阅读 | 内容 |
424
+ |---|---|
425
+ | [CONTRIBUTING.md](CONTRIBUTING.md) | 如何提出 Issue 与提交范围清晰的 Pull Request |
426
+ | [docs/architecture.md](docs/architecture.md) | 四柱↔组件映射、数据流、关键设计决定 |
427
+ | [docs/host-drift.md](docs/host-drift.md) | 零 Token 宿主/版本漂移状态与最小化基线 |
428
+ | [docs/release-notes-0.2.2.md](docs/release-notes-0.2.2.md) | 0.2.2 宿主漂移、实时哨兵与 DSH 打包验收 |
429
+ | [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor 变更与证据边界 |
430
+ | [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 变更、证据等级与已知限制 |
431
+ | [adapters/INTEGRATION.md](adapters/INTEGRATION.md) | 未列出宿主的自适配检查清单 |
432
+ | [docs/threat-model.md](docs/threat-model.md) | 诚实边界:它是什么、不是什么 |
433
+ | [docs/friction.md](docs/friction.md) | 真实 Agent 撞出来的教训(F1–F11) |
434
+ | [docs/development-note-unguarded-deletion.md](docs/development-note-unguarded-deletion.md) | 去标识化事故探索与面向恢复的后续方向 |
435
+ | [docs/test-report-codex-gpt-5.6-sol.md](docs/test-report-codex-gpt-5.6-sol.md) | v0.1.1 Codex 评估(medium + high) |
436
+ | [docs/test-report-dsh-0.1.5-rc.1.md](docs/test-report-dsh-0.1.5-rc.1.md) | 当前 DSH 打包插件与执行级 `bash` 验收 |
437
+ | [docs/test-report-dsh-v0.1.1.md](docs/test-report-dsh-v0.1.1.md) | v0.1.1 DSH 真机测试(DeepSeek V4 Pro high,极简模式) |
438
+ | [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | 证据优先级、确定性回放、恢复与落地门禁 |
439
+ | [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | 完整规则表与判决码 |
440
+ | [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil 规则表、reason code、豁免格式与审计结构 |
441
+ | [skills/exfil-guard/references/channels.md](skills/exfil-guard/references/channels.md) | 出口信道分类与不可达信道 |
442
+
443
+ ## 状态与路线图
444
+
445
+ 当前源码版本为 **v0.2.2**。已发布的 `v0.2.0` 基线包含可恢复的破坏性
446
+ 操作、cmd/PowerShell 方言解析、`exfil-guard` 文本 CLI、只读配置安全视图
447
+ 和 `recovery-audit`。后续源码版新增 Claude/Kimi POSIX hook 桥、有界宿主
448
+ 证据、`doctor`、宿主漂移检查、可选实时哨兵与当前 DSH 打包验收。准确范围见
449
+ [0.2.2 说明](docs/release-notes-0.2.2.md);是否已正式发布以
450
+ [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) 为准,
451
+ 源码版本号本身不代表已有 Release。
452
+
453
+ 该版本的项目身份与 harness 无关。现有 DSH、Claude adapter,Codex/ZCode
454
+ 验收证据,以及有边界的 Kimi 实测,只是不断扩展的兼容矩阵,不分别定义产品。
455
+ Kimi 结果包含所测调用的 hook 补偿与执行级 BLOCK 证据,不证明宿主强制执行
456
+ 所有 `BLOCK`,也不意味着任意 Agent 操作都受保护。实测旧的直连 Python hook
457
+ 启动故障会放行;可选 shell 桥在一次 Kimi 宿主故障注入中将其转为拒绝,
458
+ 但前提是桥自身成功运行;单凭配置校验无法证明 hook 在线。真实 Windows 端到端覆盖
459
+ 与一般并发子代理安全仍是明确缺口。
460
+ 后续 `git-guard`、`database-guard`、`cloud-guard` 继续复用同一协议与补偿引擎。
461
+
462
+ ## 0.2.x 预告:guard-lab 合成蜜罐
463
+
464
+ 这是规划中的可选实验,**不属于 0.2.2**。它会在离线、一次性的测试项目
465
+ 里放入无认证能力的合成标记,对照正常任务与提示词注入诱导;另设试次观察
466
+ harness 是否在 Agent 未请求读取时自行索引或外发文件。正负对照、独立观察器
467
+ 和证据分级将区分“提出读取”“本地接触”与“证实越过外部边界”。不使用真实
468
+ 凭据,不默认常驻后台;它也不是抵抗恶意模型或宿主的安全保证。
469
+
470
+ ## 参与贡献
471
+
472
+ 欢迎缺陷报告、设计提案、兼容性证据、文档修订与范围明确的代码改动。非小型或
473
+ 涉及安全边界的变更请先发
474
+ [Issue](https://github.com/mokuyoaxis/agent-guard/issues),实现请通过范围清晰的
475
+ [Pull Request](https://github.com/mokuyoaxis/agent-guard/pulls) 提交。分享日志或
476
+ 测试证据前请先阅读[贡献指南](CONTRIBUTING.md);不得公开凭据、私有配置或未经
477
+ 去敏的事故资料。
478
+
479
+ ## 社区友链
480
+
481
+ [![LINUX DO 社区友链](assets/linux-do-community.svg)](https://linux.do/t/topic/2942799)
482
+
483
+ 这张自制横幅直达我们的
484
+ [LINUX DO 项目帖](https://linux.do/t/topic/2942799),不代表社区官方推荐。
485
+
486
+ ## 许可证
487
+
488
+ MIT —— 见 [LICENSE](LICENSE)。
@@ -0,0 +1,94 @@
1
+ # Integrating another coding-agent host
2
+
3
+ This is a checklist for a user or their agent, **not** a claim that an
4
+ unlisted host is supported. Start with the [capability and evidence
5
+ matrix](../docs/harness-capabilities.md). A prompt, Skill, CLI call, or
6
+ adapter exit code alone does not prove automatic tool interception.
7
+
8
+ ## 1. Identify the actual boundary
9
+
10
+ Record the host name and version, OS, tool names, shell dialect, configuration
11
+ scope, and whether calls can come from subagents. Check the installed host's
12
+ hook contract: is there a synchronous event **before** the tool runs, and can
13
+ the hook prevent that exact call from executing? Determine the payload fields,
14
+ exit/response semantics, approval behavior, matcher rules, timeout, and what
15
+ happens when the hook is missing or fails to start. A post-tool event cannot
16
+ undo an already executed operation.
17
+
18
+ Read only the relevant hook configuration. Do not copy authentication
19
+ material, private routes, or the full user configuration into model context
20
+ or a public report. If the host contract or version is unclear, mark it
21
+ `UNVERIFIED` rather than guessing from another host's schema.
22
+
23
+ ## 2. Choose the smallest honest integration
24
+
25
+ - **Documented host:** choose its adapter README from the
26
+ [integration matrix](../README.md#integration-and-validation-matrix) and
27
+ preserve existing settings. Claude, Kimi, and DSH have distinct host
28
+ decision semantics; their configuration snippets are not interchangeable.
29
+ - **Blocking pre-tool event exists:** build a thin adapter that normalizes
30
+ the command, working directory, tool name, and dialect, calls the shared
31
+ Core through `skills/delete-guard/scripts/check.py`, then maps the returned
32
+ decision to the host's documented response. Keep policy in Core, not in a
33
+ second copy of the rule table. Inspect the [Claude](claude/pre_tool_use.py),
34
+ [Kimi](kimi-code/pre_tool_use.py), and [DSH](dsh/lib/index.js) adapters as
35
+ examples of host-specific mapping, not drop-in templates.
36
+ - **No verified blocking event:** use the [Skills](../skills/) and explicit
37
+ CLI cooperatively. Say `Skill/CLI only`; do not claim native interception.
38
+ A hook limited to some tools does not cover other tools or hidden uploads.
39
+
40
+ Core `ASK` must reach a real human-approval path or become a refusal for that
41
+ call. It must never silently become allow. Treat malformed payloads and
42
+ adapter failures conservatively **when the adapter is invoked**; this does
43
+ not protect a call when the host never starts the hook. For a shell tool,
44
+ `check.py --enforce` may relocate files or snapshot Git state, so use it only
45
+ in an authorized execution path; use advisory mode for non-mutating policy
46
+ checks.
47
+
48
+ ## 3. Configure and verify without destructive trials
49
+
50
+ Before editing user-wide settings, changing security policy, or installing
51
+ dependencies, show the exact proposed change and obtain user approval. Keep
52
+ the prior configuration and a rollback path. Prefer a disposable project and
53
+ a project-scoped configuration where the host supports it.
54
+
55
+ 1. Run adapter contract tests with fixed payloads: allowed call, policy
56
+ refusal, compensable call, malformed payload, `ASK`, and a failed runtime.
57
+ Record the Core reason code and host response separately.
58
+ 2. In an isolated host session, confirm a harmless call reaches the hook and
59
+ continues. Confirm that a policy-denied **synthetic** sentinel-creation
60
+ call does not execute, checking the sentinel independently of hook logs.
61
+ Do not use deletion of real files, `$HOME`, or a user's repository as a
62
+ test. Use a controlled failure injection to check the path where the hook
63
+ runs but its interpreter fails.
64
+ 3. Repeat for each claimed tool, host version, root/subagent path, and
65
+ relevant dialect. Test host upgrades again. If a hook is missing,
66
+ mismatched, timed out, or bypassed, record that as a gap; adapter tests
67
+ cannot turn those host boundaries into fail-closed behavior.
68
+
69
+ `doctor.py` currently supports only `kimi` and `claude`. Its configuration
70
+ and local-probe PASS states do **not** prove a live host loaded or enforced a
71
+ hook. Do not reuse those states as an unknown-host certification.
72
+ For those two hosts, `--check-drift` adds local version/profile comparison and
73
+ privacy-safe hook/runtime fingerprints. `STALE` asks for re-testing after a
74
+ version change; it does not assert incompatibility. `CURRENT` still does not
75
+ promote `host_interception` above `UNVERIFIED`. See the
76
+ [host drift contract](../docs/host-drift.md).
77
+
78
+ An explicit `--live-sentinel` can spend one configured model call to test one
79
+ real root-agent Bash path in a private fixture. PASS requires a hashed exact
80
+ hook receipt, matching Core audit, host block feedback, and an absent marker;
81
+ missing evidence is INCONCLUSIVE. It is not an adversarial sandbox and must
82
+ not be generalized to subagents or other tools.
83
+
84
+ ## 4. Report the evidence, not a blanket guarantee
85
+
86
+ Report the host/version, tool and event, config scope, root/subagent path,
87
+ dialect, model setup if one was used, the Core decision, host outcome, and
88
+ independent non-execution observation. Label evidence as `CLI`, `Adapter`,
89
+ `Hook observed`, or `Enforcement observed` using the
90
+ [matrix definitions](../docs/harness-capabilities.md#evidence-levels).
91
+ Unknown versions or untested paths remain `UNVERIFIED`; no blocking event is
92
+ `Skill/CLI only` or `UNSUPPORTED`. An agent's self-test is useful setup
93
+ evidence, not an independent security boundary against that same agent or a
94
+ malicious host with equal OS privileges.