@mokuyoaxis/agent-guard 0.2.3 → 0.2.5-rc1

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 (80) hide show
  1. package/README.md +158 -571
  2. package/README.zh-CN.md +133 -490
  3. package/SECURITY.md +53 -0
  4. package/adapters/INTEGRATION.md +8 -6
  5. package/adapters/claude/README.md +3 -3
  6. package/adapters/claude/harness/README.md +1 -1
  7. package/adapters/codex/harness/README.md +2 -2
  8. package/adapters/dsh/README.md +17 -6
  9. package/adapters/dsh/harness/README.md +8 -8
  10. package/adapters/dsh/harness/guard_lab.py +3 -3
  11. package/adapters/dsh/lib/index.js +1 -1
  12. package/adapters/kimi-code/README.md +7 -7
  13. package/adapters/kimi-code/harness/README.md +3 -3
  14. package/adapters/kimi-code/harness/guard_lab.py +1 -1
  15. package/assets/linux-do-community.svg +19 -0
  16. package/core/__init__.py +1 -1
  17. package/core/classifier.py +66 -17
  18. package/core/policy.py +28 -13
  19. package/core/recovery.py +261 -24
  20. package/core/redaction.py +122 -21
  21. package/core/trash_index.py +193 -0
  22. package/docs/README.md +113 -0
  23. package/docs/{architecture.md → design/architecture.md} +51 -12
  24. package/docs/{compatibility.md → design/compatibility.md} +124 -4
  25. package/docs/{threat-model.md → design/threat-model.md} +10 -8
  26. package/docs/guides/getting-started.md +104 -0
  27. package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +14 -9
  28. package/docs/guides/trash-index.md +106 -0
  29. package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +2 -2
  30. package/docs/{friction.md → history/friction.md} +123 -0
  31. package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +12 -12
  32. package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +2 -2
  33. package/docs/{secret-guard-design.md → history/secret-guard-design.md} +14 -14
  34. package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
  35. package/docs/{guard-lab.md → lab/guard-lab.md} +15 -13
  36. package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +3 -3
  37. package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +5 -5
  38. package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
  39. package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +2 -2
  40. package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +1 -1
  41. package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
  42. package/docs/{release-notes-0.2.3.md → releases/release-notes-0.2.3.md} +3 -3
  43. package/docs/releases/release-notes-0.2.4.md +89 -0
  44. package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
  45. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  46. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  47. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  48. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  49. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  50. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  51. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  52. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  53. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +3 -3
  54. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  55. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +1 -1
  56. package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
  57. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
  58. package/package.json +4 -2
  59. package/skills/delete-guard/SKILL.md +80 -7
  60. package/skills/delete-guard/references/policy.md +104 -8
  61. package/skills/delete-guard/scripts/check.py +22 -0
  62. package/skills/delete-guard/scripts/restore.py +34 -7
  63. package/skills/delete-guard/scripts/safe_delete.py +52 -29
  64. package/skills/delete-guard/scripts/status.py +52 -0
  65. package/skills/exfil-guard/SKILL.md +23 -11
  66. package/skills/exfil-guard/references/channels.md +9 -2
  67. package/skills/exfil-guard/references/rules.md +83 -6
  68. package/skills/exfil-guard/scripts/_payload.py +20 -0
  69. package/skills/exfil-guard/scripts/check_span.py +5 -1
  70. package/skills/exfil-guard/scripts/sanitize.py +6 -3
  71. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  72. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  73. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  74. /package/docs/{guard-lab-read-trial-task.md → lab/tasks/guard-lab-read-trial-task.md} +0 -0
  75. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  76. /package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +0 -0
  77. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  78. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  79. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  80. /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
package/README.zh-CN.md CHANGED
@@ -1,549 +1,192 @@
1
1
  # AGENT-GUARD
2
2
 
3
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)
4
+ [![npm 稳定版](https://img.shields.io/npm/v/%40mokuyoaxis%2Fagent-guard.svg)](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
5
5
  [![License](https://img.shields.io/github/license/mokuyoaxis/agent-guard)](LICENSE)
6
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.3 源码](https://img.shields.io/badge/%E6%BA%90%E7%A0%81-v0.2.3-5B6B7A)](docs/release-notes-0.2.3.md)
7
+ [![0.2.5-rc1](https://img.shields.io/badge/RC-0.2.5--rc1-5B6B7A)](docs/releases/release-notes-0.2.5-rc1.md)
8
8
 
9
9
  **让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
10
10
 
11
- Agent Guard 是给编码 Agent 用的可靠性工具:让受支持的高风险操作尽可能
12
- 可恢复,而不是一次失手就永久损失;日常工作则尽量不被打断。
11
+ Agent Guard 是给编码 Agent 用的可靠性工具:在受支持的破坏性操作前建立
12
+ 恢复路径,在文本外发前检查泄露风险,并让用户通过 Lab 验测实际观察到的
13
+ Agent/宿主行为。共享 Python Core 可通过显式 CLI 或可选宿主适配器使用。
13
14
 
14
- - **删除文件**:可先迁入 `.agent-trash/`,留下恢复清单,而非直接销毁。
15
- - **破坏性 Git 操作**:可先保存可恢复的状态,再覆盖工作树。
16
- - **意外外发**:合作式文本 CLI 可检查已知凭据和带本机标识的绝对路径;
17
- 持有载荷的调用方按判决应用脱敏计划、请求人工处理或阻断。
18
- - **合成蜜罐验测**:用零 Token 正负对照检查明确列出的本地信道;证据健康
19
- 不足时只报 `INCONCLUSIVE`,不猜测通过。
20
-
21
- 共享 Core 支持 Python 3.9+ 和 Git,不依附某个 harness。能否自动拦截,
22
- 仍取决于宿主有没有兼容 hook;仅安装 Skill 不会自动拦截工具调用。
23
- Core、决策协议与 Skills 是产品本体,适配器只是可替换的接入桥。
15
+ | 能力 | 能帮助你做什么 | 入口 |
16
+ |---|---|---|
17
+ | **恢复保护** | 删除前迁移有价值的文件;受支持的 Git 覆盖前快照 tracked 状态;查询和恢复事务 | [delete-guard](skills/delete-guard/SKILL.md) |
18
+ | **外发检测** | 检测受支持的凭据和本机标识路径;应用脱敏计划或拒绝输出 | [exfil-guard](skills/exfil-guard/SKILL.md) |
19
+ | **行为验测** | 校准观察器,验证声明信道的暴露,再比较匹配的关闭/开启防护试次 | [guard-lab](docs/lab/guard-lab.md) |
24
20
 
25
- > **能安全恢复的操作尽量自动完成;不能安全代办时再交给人。**
26
- > Agent Guard 是可靠性基础设施,不是安全沙箱:它防范失误,
27
- > 不承诺抵抗拥有相同系统权限的恶意 Agent。
21
+ Skill 提供操作纪律,不会自行拦截工具调用。自动保护依赖宿主实际加载了
22
+ 兼容 hook,且调用位于其覆盖范围内。Agent Guard 不是抵抗同权限恶意进程的
23
+ OS 沙箱;实际接入证据和缺口见[能力矩阵](docs/guides/harness-capabilities.md)。
28
24
 
29
- ## 它会怎样处理
25
+ <a id="guard-lab-合成蜜罐"></a>
30
26
 
31
- ```text
32
- rm -rf build/ → RELOCATE # 工作区内目录先迁入隔离区
33
- rm -rf . → BLOCK # 保护工作区根目录
34
- git reset --hard → SNAPSHOT # Git 状态允许时先做快照
35
- git push --force → BLOCK # 不自动改写远端历史
36
- ```
27
+ ## guard-lab:用证据验测行为
37
28
 
38
- 这是受支持输入的**示意判决**,不是让你执行这些命令,也不表示所有宿主都会
39
- 自动拦截。被忽略且可再生的目标可能判为 `ALLOW`;Git 快照无法建立时会
40
- 保守拒绝。能恢复或安全改写时,Agent 可以继续工作;否则交给人或阻断。
29
+ guard-lab 是**用户控制的实验工具**。它在一次性项目中放入非秘密合成标记和
30
+ 无害诱饵,只观察明确声明的信道。真正的控制器与证据保存在交给受测 Agent 的
31
+ 夹具之外。
41
32
 
42
- ## 让编码 Agent 帮你接入
33
+ 流程分别回答三个问题:
43
34
 
44
- 可以安装带作用域的 npm 包,也可以保留一个稳定的 Git checkout。
45
- 无作用域的同名 `agent-guard` 包与本项目无关。
35
+ 1. **校准**:观察器、标记、扫描和证据链是否正常?内建对照不调用模型,
36
+ 不访问外网。
37
+ 2. **观察暴露**:关闭防护的真实宿主试次是否触发了选定信道?
38
+ 3. **比较防护**:有效基线成立后,匹配的开启防护试次是否减少或阻止了该暴露?
46
39
 
47
- 把固定版本安装到用户选择的稳定路径:
40
+ 在安装包或源码根目录,从一项零模型对照开始:
48
41
 
49
42
  ```sh
50
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.3
43
+ lab_run="$(mktemp -d)"
44
+ python3 guard_lab.py run --case clean --output-dir "$lab_run/clean" --json
51
45
  ```
52
46
 
53
- **0.2.3** 合并 Windows/Core 修复、信息保护增强和离线 guard-lab MVP。
54
- 本次范围与证据边界见 [发布说明](docs/release-notes-0.2.3.md);
55
- npm 徽章和 [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
56
- 展示实际可用的发布工件。
47
+ 另三项对照是 `mock-positive`、`mock-injection` 和 `snapshot-positive`。
48
+ 真实宿主实验前应按 [Lab 指南](docs/lab/guard-lab.md)跑齐四项对照;
49
+ 安装包也提供 `agent-guard-lab` 命令。
57
50
 
58
- 安装后的包根目录是
59
- `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`。
60
- 也可以克隆源码;如果已有 checkout,跳过克隆:
51
+ 对照 PASS 只表示**仪器校准**,不表示模型安全。观察器不健康或证据缺失时为
52
+ `INCONCLUSIVE`;未防护基线安静,不能证明防护有效。配对比较需要匹配相关的
53
+ harness/版本/模型、任务、协议及非防护配置。结果只覆盖声明信道,不能扩展
54
+ 到所有文件读取、外网传输或模型请求。已有
55
+ [Kimi](docs/reports/test-report-kimi-guard-lab.md) 与
56
+ [DSH](docs/reports/test-report-dsh-guard-lab.md) 报告保留各自的有限结论、
57
+ 失败和待审状态。
61
58
 
62
- ```sh
63
- git clone https://github.com/mokuyoaxis/agent-guard.git
64
- cd agent-guard
65
- ```
59
+ ## 安装与版本选择
66
60
 
67
- Core 需要 Python 3.9+ 和 Git;是否能自动拦截取决于宿主是否提供相应 hook。
68
- 把下面这段交给编码 Agent,先替换为你的仓库路径:
69
-
70
- ```text
71
- 请为当前工作区接入 agent-guard。只使用现有 Git checkout,或精确的 scoped
72
- npm 包 @mokuyoaxis/agent-guard@0.2.3;不要安装无作用域的同名
73
- agent-guard。若 0.2.3 尚不可用,说明情况,使用现有 checkout 或让我选择已发布版本。
74
- 安装前先让我选择并批准一个稳定的用户目录,然后把 checkout 或 npm 安装后的
75
- 包根目录作为下文的 /absolute/path/to/agent-guard。
76
- 先识别当前 harness 实际支持的 hook 与 Skill,阅读本 README 和对应 adapter
77
- 说明,并检查 Python、Git。安装适用的 Skills;只有宿主确实支持时才配置
78
- 原生 shell hook。保留现有设置;修改用户级配置或安装依赖前先展示差异并征求确认。
79
- Claude Code 参考 adapters/claude/README.md,Kimi Code 参考
80
- adapters/kimi-code/README.md,DSH 参考 adapters/dsh/README.md。
81
- 其他宿主先读 adapters/INTEGRATION.md,不要凭空假设原生 hook;没有已验证的
82
- 调用前阻断能力时只接入 Skill/CLI,并明确说明没有自动拦截。
83
- 用无害命令和仅作为数据传给 check.py 的 BLOCK 样例验证;不要真正执行
84
- 破坏性测试命令。Claude/Kimi 可运行本地 doctor,但不能把其 PASS 当成宿主
85
- 拦截证明。最后报告宿主版本、工具范围、实际安装内容、确实拦截的调用和未验证路径。
86
- ```
87
-
88
- 手动接入与证据边界见 [harness 能力矩阵](docs/harness-capabilities.md)
89
- 及对应的 adapter README。
61
+ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可选采集
62
+ 工具另有运行要求。
90
63
 
91
- ## 设计原则
92
-
93
- | 原则 | 做法 |
64
+ | 版本 | 状态 |
94
65
  |---|---|
95
- | **守住边界** | 操作进入 Guard 时,阻断工作区根、`.git` 和外部路径的删除 |
96
- | **先保留退路** | 受支持的删除先迁入 `.agent-trash/` 并记 manifest;破坏性 Git 覆写先做快照 |
97
- | **约束授权** | 授权只在会话内有效;否决会单向降权,只有人能恢复 |
98
- | **留下记录** | 强制判决、补偿 intent、结果和恢复写入追加式 JSONL;intent 无法持久化时拒绝修改 |
99
-
100
- 贯穿四项原则的一条规则是:**越不确定,限制越严格。**
66
+ | [0.2.4](docs/releases/release-notes-0.2.4.md) | 已发布的稳定基线 |
67
+ | [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | 维护预发布;显式选择准确 RC 版本 |
101
68
 
102
- ## 决策协议
69
+ 稳定包可安装到用户选定的长期目录:
103
70
 
104
- 每个进入 Guard 的操作都会按效果分类,再选择足以维持安全或恢复承诺的
105
- 最宽松判决。稳定的跨 harness 接口不是简单的 allow/block,而是一套
106
- Decision Protocol:
107
-
108
- ```
109
- 效果 → 分类器 → 策略 → Decision ∈ { ALLOW, SANITIZE, RELOCATE,
110
- SNAPSHOT, ASK, BLOCK }
111
- + ReasonCode (稳定机器码)
112
- + Explanation (面向人类的解释)
113
- + RecoveryPlan (txid 与补偿策略)
71
+ ```sh
72
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
114
73
  ```
115
74
 
116
- | 层级 | 判决 | Agent 的体验 |
117
- |---|---|---|
118
- | **SAFE** | `ALLOW` · `SANITIZE` · `RELOCATE` · `SNAPSHOT` | 尽量不中断工作;需要时先补偿,可恢复的修改凭 txid 找回。`SANITIZE` 返回由**载荷持有方**应用的脱敏计划,不改写命令 |
119
- | **AMBIGUOUS** | `ASK` | 单次执行授权(`ASK_ONCE`)——例如 Guard 无法安全代办的复合形态 |
120
- | **FORBIDDEN** | `BLOCK` | 附理由与修正建议拒绝;永不升级为询问 |
121
-
122
- 当一个操作同时命中多个判决时,由弱到强的优先级为:
75
+ 包根目录是
76
+ `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`。
77
+ 必须使用这个带作用域的包名,也可以使用源码 checkout:
123
78
 
79
+ ```sh
80
+ git clone https://github.com/mokuyoaxis/agent-guard.git
81
+ cd agent-guard
124
82
  ```
125
- ALLOW < SANITIZE < RELOCATE < SNAPSHOT < ASK < BLOCK
126
- ```
127
-
128
- `SANITIZE` 排在 `ASK` **之下**是有意的:它属于自动化的 SAFE 层,
129
- 而 `ASK` 需要人处理。载荷里同时有可脱敏的密钥和无法改写的部分时,
130
- 不能只处理前者便静默放行。
131
-
132
- 真正无法确定效果的命令(如 `$VAR` 目标、`bash -c`、`find -delete`)
133
- 会被拒绝;放行它们就无法守住边界。适配器再把判决映射到宿主机制:
134
- DSH 的 `PreToolDecision`、Claude Code PreToolUse 的 `ask`,或在不支持
135
- 询问的宿主中附带解释的拒绝。
136
-
137
- ## Agent Guard 包含什么
138
-
139
- ### `delete-guard`
140
-
141
- 回答“删了还能找回来吗?”通过受支持的适配器或 CLI 调用时,
142
- 它在删除或破坏性 Git 操作前检查,并在可恢复时先做补偿。
143
-
144
- ### `exfil-guard`
145
-
146
- 回答“这份内容本该离开本机吗?”载荷持有方主动调用其合作式 CLI 时,
147
- 它在发出前检查文本,并针对受支持的模式返回脱敏或升级判决。
148
-
149
- ### `recovery-audit`
150
83
 
151
- 如果预防没有运行或没有覆盖那条路径,它负责事故后的证据整理:
152
- 区分原文恢复、依据重建与确认缺失,审计回放工具,并把落地、提交、
153
- 推送和发布保留为独立授权门。
84
+ RC 显式选择 `@mokuyoaxis/agent-guard@0.2.5-rc1`;RC 通道不替换稳定版 `latest`。
85
+ 发布状态以 [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc1)
86
+ 和 [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc1)为准,
87
+ 也可使用已核查的 checkout 或本地提供的 tarball。
88
+ 接入步骤与 Agent 提示词见[入门指南](docs/guides/getting-started.md)。
154
89
 
155
- `delete-guard` 和 `exfil-guard` 是两条预防分支;
156
- `recovery-audit` 负责事后的证据驱动恢复。
90
+ ## 恢复一次受支持的删除
157
91
 
158
- ## recovery-audit
92
+ 从要保护的工作区调用你的安装包/源码路径:
159
93
 
160
- 有时预防根本没有机会运行:harness 没有 adapter、子代理绕开预期路径,或范围过大的
161
- 命令在人工介入前删掉了 workspace。工作树可能已经消失,但编码 Agent 的会话缓存里
162
- 仍可能保存成功 patch、文件快照、工具结果、diff 与命令上下文。
163
-
164
- `recovery-audit` 把这些残留,与 Git remote/reflog/stash、编辑器或工具缓存、构建产物
165
- 和项目计划一起组织成证据驱动的恢复流程:
166
-
167
- - 每个单元明确标记为**原文恢复(recovered)**、**依据重建(reconstructed)**或
168
- **确认缺失(missing)**;
169
- - 按真实时间顺序回放工具效果,并检查记录与回放是否分歧;
170
- - 同一份冻结证据重复回放,必须得到逐字节一致的树;
171
- - 落地、commit、push 与 release 始终是互相独立的授权门。
172
-
173
- 它不是文件系统 undelete,也不能创造任何幸存来源从未保存过的字节。它承诺的是:
174
- 尽快恢复到证据真正支持的最强项目状态,并把缺口写清楚,而不是藏起来。
175
-
176
- ## exfil-guard
177
-
178
- `exfil-guard` 检查 Agent 即将写入、发送、提交或推送的文本,前提是
179
- **载荷持有方主动调用它的 CLI**。它还提供对指定 JSON/dotenv 配置文件的
180
- 显式只读安全视图。文本扫描针对两类意外外发:**已知凭据**和
181
- **带本机标识的绝对路径**。依据信道,Guard 可放行、返回脱敏计划、
182
- 请求人处理或阻断。
183
-
184
- DSH 另有[默认关闭的文本 `read` 脱敏原型](adapters/dsh/README.md#experimental-text-read-redaction),
185
- 仅覆盖版本门控下的完整原生读取。它复用同一 Core,并让 DSH 同时重新生成
186
- 返回文本和展示元数据;零模型原生验证已覆盖下一次请求和 JSONL 落盘。
187
- 另一次[官方 Flash 真实直接读取对照](docs/test-report-dsh-real-followup.md)
188
- 观察到支持规则的合成秘密被脱敏,同时保留有用配置;这不是提示注入 L2 结论。
189
-
190
- 它做的是预防和脱敏,不是补偿:内容发出去后就不能撤销。它也**不是
191
- 安全沙箱**,不负责抵抗拥有相同系统权限的 Agent 蓄意外泄。
192
-
193
- ### exfil-guard 的四种判决
194
-
195
- 完整决策协议仍然适用,但文本载荷只会落到其中四类
196
- (`RELOCATE`/`SNAPSHOT` 属于 delete-guard——Guard 无法改写自己没写过的东西):
197
-
198
- | 判决 | 含义 | 示例 |
199
- |---|---|---|
200
- | `ALLOW` | 无匹配,或命中受控占位符、工作区内相对路径 | `echo "hello" \| check_span.py` |
201
- | `SANITIZE` | 返回脱敏计划;由**载荷持有方**改写后再发出 | `file-write` / `llm-request` 上的真实密钥 |
202
- | `ASK` | 信道既不能改写也无法收回 | `shell-stdout` 上的本机路径 |
203
- | `BLOCK` | 拒绝:不可变/远端历史、载荷无法扫描、配置非法 | `git-push-payload` 中的凭据 |
204
-
205
- ### 检测什么
206
-
207
- **T1 厂商凭据特征**(`secret/*`)。按已知格式识别,用文档化占位符和反例
208
- 约束误伤。rule id 包括:
209
- `secret/openai-key`、`secret/github-token`、`secret/aws-access-key-id`、
210
- `secret/gitlab-token`、`secret/slack-token`、`secret/stripe-key`
211
- (仅 live key,`sk_test_` 豁免)、`secret/pypi-token`、`secret/jwt`(结构化:
212
- 头部须解码为 JSON,且 `alg` 是非空 ASCII 字符串),以及 `secret/private-key-block`
213
- (整段 `-----BEGIN ... PRIVATE KEY-----` 一次性脱敏)。规则表与保留边界见
214
- [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md)。
215
-
216
- `secret/connection-password` 另检测 URI 用户信息中的非空口令,只遮口令,
217
- 保留协议、账号与主机以便排错。支持百分号编码口令和 JSON 转义的协议斜杠;
218
- 这不等于隐藏网络拓扑,也不覆盖所有 DSN 格式。
219
-
220
- **不读值的密钥引用**(`secret/source-reference`)。Guard 按变量名中的完整
221
- 组成部分(如 `KEY`、`TOKEN`、`SECRET`、`PASSWORD`、`PASSWD`、`CRED`、`AUTH`)与
222
- 密钥库**文件名**(`.env`、`*.pem`、`id_rsa*`、`.netrc`、`kubeconfig` 等)
223
- 分类,并识别整环境展开(`printenv`、`env | ...`、
224
- `cat /proc/self/environ`)。这个扫描器**不解析变量的值**;这不代表其他
225
- Guard 输出或已有审计记录都已证明不含秘密。
226
-
227
- **带本机标识的路径**(`path/*`)。`path/workspace-relative` 为 `ALLOW`
228
- (工作区豁免);`path/system`(`/usr`、`/etc`、`C:\Windows`)为 `ALLOW`;
229
- `path/host-absolute`(位于 `HOME`/`TEMP`、CI 根或工作区祖先之下)为
230
- `SANITIZE`;`path/generic-absolute`(与本机无关联)为 `ASK`;
231
- `path/device`(UNC、`\\?\`、管道)为 `SANITIZE`。
232
-
233
- ### 信道决定处置
234
-
235
- 信道由两个事实定义:能否**改写**、发出后是否**留存**。`rewritable`
236
- 决定了 `SANITIZE` 是否有意义;`persistence` 决定了 `BLOCK` 是否成立。
237
-
238
- | 信道 | 可改写 | 留存 | 默认 |
239
- |---|---|---|---|
240
- | `llm-request` | 是 | 远端 | SANITIZE |
241
- | `file-write` | 是 | 工作区 | SANITIZE |
242
- | `forge-comment` / `issue-body` / `pr-description` | 是 | 公开 | SANITIZE |
243
- | `git-commit-message` | 是(改 argv) | 远端历史 | **BLOCK** |
244
- | `git-push-payload` | 否 | **远端** | **BLOCK** |
245
- | `shell-stdout` | **否** | 本地记录 | ASK |
246
- | `shell-file-redirect` | 是 | 本地 | ASK |
247
- | `archive-upload` | 是 | 远端 | ASK |
248
- | `process-argv` | 是 | 本地 | ASK |
249
-
250
- 信道名未知属于配置缺陷,而非"无风险":`check_span.py` 返回
251
- `BLOCK_OUTPUT_UNSCANNABLE`,绝不隐式放行。
252
-
253
- ### 使用示例
254
-
255
- `check_span.py` 从 **stdin** 读取载荷,是纯函数——不写文件、不改写、
256
- 也不打印匹配内容。`sanitize.py` 应用 Guard 返回的计划。
257
-
258
- ```bash
259
- # 可改写信道上的凭据 -> SANITIZE,退出码 0
260
- echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/check_span.py --channel file-write
261
-
262
- # 即将进入远端历史的凭据 -> BLOCK,退出码 2
263
- echo 'token=ghp_abcdefghijklmnopqrstuvwxyz…' | python3 skills/exfil-guard/scripts/check_span.py --channel git-push-payload
264
-
265
- # 应用脱敏计划(保留格式:sk-<REDACTED>)
266
- echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/sanitize.py --channel file-write
94
+ ```sh
95
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
96
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
97
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
98
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py <txid>
267
99
  ```
268
100
 
269
- 退出码契约:`0` = ALLOW/SANITIZED · `2` = BLOCK · `3` = ASK · `1` = ERROR。
270
- `--json` 输出机器可读判决(仅偏移、rule id 与占位符——**绝不含匹配到的
271
- 字节**);`--path` 为即将写入的文件启用仓库本地豁免文件。
272
-
273
- `sanitize.py` 同样落实上述退出码:ASK/BLOCK 和错误时 stdout 不输出正文。
274
- 外部 `--plan` 必须与当前扫描一致,改写后复扫通过才输出。两个 CLI 共用默认
275
- 工作区和宿主模式;stdin 在读取时即受到扫描上限限制(默认 4 MiB),外部计划文件
276
- 也受同一上限约束。checker 使用显式模式或路径豁免产生的计划,仍须满足 sanitizer
277
- 当前策略;计划本身不是发送授权。
278
-
279
- 凭据检测支持经典和 `ghs_APPID_JWT` GitHub 安装令牌,完整遮挡长签名,并能识别
280
- 紧贴中文的凭据。占位符豁免要求完整形状,token 内偶然出现示例词不会整段放行。
281
- 秘密变量引用按名称组成部分判断,保留 `MONKEY` 等普通标识符和 `TOKEN_COUNT`
282
- 等元数据名称。支持的形式和限制见[规则说明](skills/exfil-guard/references/rules.md)。
283
-
284
- 新增 PyPI 发布令牌识别,按官方前缀与最小 body 形状完整遮挡长令牌。AWS 组/
285
- 用户/角色/策略 ID 与访问密钥 ID 分开处理;JWT header 的 `alg` 须为非空
286
- ASCII 字符串。公钥变量名称与通用 `sk-` 形状仍保留已说明的保守边界。
101
+ 有价值的目标迁入隔离区,manifest 保留准确恢复路径。可证明能够再生成且被
102
+ Git 忽略的产物可直接删除。受支持的 Git 覆盖操作先快照 tracked 状态;
103
+ hard reset 与 untracked/ignored 内容发生碰撞时拒绝执行。force restore
104
+ 先保全当前占位版本,再恢复旧版本。错误可能留下部分操作,应先核查返回的
105
+ 事务 ID、现场文件和状态,再决定后续动作。
287
106
 
288
- ### 不打印值地查看配置
107
+ advisory `check.py` 和 `safe_delete.py --dry-run` 保持命令目标不变,但可能写入
108
+ 隔离区/审计元数据及 Git 本地 exclude。advisory 退出码 0 不代表 BLOCK/ASK
109
+ 操作获准执行。详见[策略与评估契约](skills/delete-guard/references/policy.md)。
289
110
 
290
- 此 CLI 从 `0.2.0` 源码开始提供,**不属于**此前的 `0.2.0-rc2`
291
- 源码预览标签。
111
+ 本 RC 增加隔离区控制路径保护、从活跃 GC 计划排除 PURGED 事务,并最小化
112
+ restore/safe_delete 审计字段;CLI/manifest 仍保留准确恢复路径。
113
+ 这些维护不属于已发布的 0.2.4 包,见 [RC 说明](docs/releases/release-notes-0.2.5-rc1.md)。
292
114
 
293
- ```bash
294
- python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace .env
295
- python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace config.json
296
- ```
297
-
298
- 文件路径必须相对该工作区。JSON 结果保留字段名与结构,以及标量类型和
299
- `set`/`empty` 状态,**不返回标量值**;已知密钥形态的字段名也会隐藏,
300
- 但未知秘密藏在字段名中仍是局限。仅支持 UTF-8 JSON 与严格的单行 dotenv
301
- 子集(最多 256 KiB、16 层、2048 个节点)。符号链接、硬链接、特殊文件、
302
- 越界路径、无效格式或平台缺少安全的相对目录描述符读取能力时一律拒绝。
303
- 退出码 `0` 表示产生视图,`2` 表示拒绝,`1` 表示内部错误。视图仅供诊断,
304
- 不能写回覆盖原配置;它也不会拦截 harness 的普通文件读取工具。
115
+ ## 外发前检查文本
305
116
 
306
- ### 与 delete-guard 的关系
117
+ 持有载荷的调用方主动运行扫描器,并按判决处理文本:
307
118
 
308
- 它们是同一承诺在动作两侧的两半:
309
-
310
- | | `delete-guard` | `exfil-guard` |
311
- |---|---|---|
312
- | 问题 | "还能回头吗?" | "这份内容本该离开吗?" |
313
- | 把守 | **删除之前** | **发出之前** |
314
- | 响应 | 先补偿,再执行 | 先脱敏,再发出 |
315
- | 失误代价 | 可凭 txid 恢复 | **不可逆** |
316
- | 入口 | `check.py -- <command>` | `check_span.py`(stdin) |
317
-
318
- 二者共享词汇表(`core/policy.py`)、聚合逻辑(`worst()`)、豁免纪律与审计
319
- 日志。`worst()` 由两个 Guard 共用,这正是 `SANITIZE` 的排序只需定义一次的原因。
320
-
321
- ### 覆盖范围与局限
322
-
323
- 这里如实说明,因为一个夸大自身能力的可靠性工具就是一份虚假的安全声明:
324
-
325
- - **不是沙箱。** 它不阻止对抗性外泄。把密钥混淆以绕过扫描的 Agent 不在
326
- 范围内;它抓的是**意外**。
327
- - **没有 hook 的信道在结构上不可达。** 无代理的托管模型调用、模型自身的
328
- 工具调用、程序内部产生的内容、人类剪贴板,一律**不给判决**——不作任何
329
- 覆盖声明。详见 `references/channels.md` 与
330
- [docs/secret-guard-analysis.md](docs/secret-guard-analysis.md) §2.4 的
331
- 可达性表。
332
- - **不是文件扫描器。** 它不是 gitleaks 的替代品;它扫描 Guard 在**发出
333
- 路径上**能看到的内容。
334
- - **不改写历史。** 检测到已经进入 git 历史的密钥最多只是一份报告。
335
- 改写历史是需要人类执行、且自带风险的动作。
336
- - **本版本不含 T3 熵检测器。** 不把看起来随机的字符串直接当作凭据,减少
337
- 对普通标识符的干扰。
338
-
339
- ## 手动使用(不依赖特定 harness)
340
-
341
- Core 没有第三方依赖。需要 Python 3.9+、POSIX shell 和 Git。
342
-
343
- ```bash
344
- # 删除文件/目录/glob —— 进入隔离区而非销毁:
345
- python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
346
-
347
- # 查看状态与恢复:
348
- python3 skills/delete-guard/scripts/status.py
349
- python3 skills/delete-guard/scripts/restore.py list
350
- python3 skills/delete-guard/scripts/restore.py <txid>
351
-
352
- # 隔离区维护(默认只出计划,不动数据):
353
- python3 skills/delete-guard/scripts/gc.py
119
+ ```sh
120
+ python3 skills/exfil-guard/scripts/check_span.py --channel file-write --json < draft.md
121
+ python3 skills/exfil-guard/scripts/sanitize.py --channel file-write < draft.md
354
122
  ```
355
123
 
356
- 受支持的 harness 适配器可在 shell 命令执行前调用 Guard,再将退出码映射
357
- 为宿主自己的工具判决:
124
+ 在运行时生成完整的合成凭据示例:
358
125
 
359
- ```text
360
- python3 skills/delete-guard/scripts/check.py --enforce -- "$COMMAND"
361
- 退出码 0 → 宿主可以执行原命令
362
- 退出码 2 → 拒绝
363
- 退出码 3 → 宿主支持时询问用户;否则拒绝
364
- 退出码 1 → Guard 出错,保守拒绝
126
+ ```sh
127
+ python3 -c 'print("config: sk-proj-" + "AbCdEf0123456789GhIjKl")' |
128
+ python3 skills/exfil-guard/scripts/sanitize.py --channel file-write
365
129
  ```
366
130
 
367
- ## 受保护行为一览
368
-
369
- 下列是命令确实进入 Guard、且目标符合所述条件时的示意结果;各宿主实际
370
- 验证到的范围见 [能力矩阵](docs/harness-capabilities.md)。
371
-
372
- ```text
373
- rm -rf build/ → RELOCATE (整树隔离后放行)
374
- rm -rf . → BLOCK (workspace 根)
375
- rm -rf $DIR/ → BLOCK (目标无法解析:fail-closed)
376
- rm *.log → BLOCK (不透明通配;safe_delete 会显式展开)
377
- cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
378
- touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
379
- git clean -fd → RELOCATE (先 -n 枚举迁移再放行)
380
- git reset --hard → SNAPSHOT (Git 状态允许建立快照时)
381
- git push --force → BLOCK (远端历史不交给 Agent 自动处理)
382
- node_modules/(已 ignore) → ALLOW (可证明可再生)
383
- 隔离区写满 → BLOCK (绝不回退到永久删除)
384
- ```
131
+ 预期输出是 `config: sk-<REDACTED>`。检查器返回判决和计划,不改写载荷;
132
+ 其退出码 0 表示 ALLOW/SANITIZE 评估成功,sanitizer 成功输出的 stdout 才是
133
+ 允许或已改写的文本。ASK/BLOCK/错误时 sanitizer 不输出载荷。
385
134
 
386
- ## 接入与验证矩阵
135
+ 检测覆盖文档列明的凭据形状、无需读值的秘密引用和特定本机路径。它不是通用
136
+ 仓库扫描器,也不能抵抗刻意编码绕过。文本 CLI 不自动追加外发审计;
137
+ 可信接入方负责实际外发和需要的审计存储。检查配置时,可用显式安全视图查看
138
+ 支持的 JSON/dotenv 结构及状态;它不是可编辑副本,也不自动拦截普通读取。
387
139
 
388
- [![Node.js 22 smoke](https://img.shields.io/badge/Node.js-22%20smoke-339933?logo=nodedotjs&logoColor=white)](.github/workflows/ci.yml)
389
- [![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)
390
- [![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)
391
- [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/test-report-zcode-glm-flash.md)
392
- [![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)
393
- [![Kimi Code 2.1.1 root Bash BLOCK](https://img.shields.io/badge/Kimi%20Code%202.1.1-root%20Bash%20BLOCK-5B9BD5)](docs/test-report-kimi-code-block.md)
394
- [![WorkBuddy Windows Core/CLI evaluated](https://img.shields.io/badge/WorkBuddy-Windows%20Core%2FCLI%20evaluated-5B6B7A)](docs/test-report-workbuddy-windows-core.md)
395
- [![Windows Core CI](https://img.shields.io/badge/Windows-Core%20CI-0078D4)](docs/release-notes-0.2.3-rc1.md#focused-windows-ci)
396
- [![DSH native text-read checked](https://img.shields.io/badge/DSH-native%20text--read%20checked-4D6BFE)](docs/test-report-release-readiness-0.2.3.md)
140
+ 详见 [Skill](skills/exfil-guard/SKILL.md)、
141
+ [规则与豁免诊断](skills/exfil-guard/references/rules.md)、
142
+ [信道契约](skills/exfil-guard/references/channels.md)。
397
143
 
398
- 徽章链接到各自范围内的证据,不代表所有工具和模型均已通过。
399
- DSH 文本读取脱敏是可选功能,默认关闭。
144
+ ## 接入你的编码 Agent
400
145
 
401
- “Core 可用”、“受 Skill 引导的 Agent 使用过”和“harness 会强制拦截每次匹配的
402
- 工具调用”是三种不同强度的结论:
146
+ 下列为按版本保留的历史观察,不代表新候选源码、所有工具或所有子代理路径
147
+ 都已验收。
403
148
 
404
- | Harness/实测版本 | 接入路径 | 证据与边界 |
405
- |---|---|---|
406
- | **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 启动故障;其他工具未验证。 |
407
- | **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 故障拒绝。另一次[真实模型 Lab 基线](docs/test-report-dsh-guard-lab.md)在 guard-off 下未触发诱饵,故没有 L2 缓解结论;模型主动提出破坏性 `bash` 时的强制执行仍未验证。单独开启的读取脱敏路径见下一行。 |
408
- | **DSH CLI rc.1/工具与 FS rc.2/Node 22** | [实验性文本读取脱敏](adapters/dsh/README.md#experimental-text-read-redaction),默认关闭 | [零模型原生验证](docs/test-report-dsh-read-redaction.md):下一次请求和 JSONL 落盘。[官方 Flash 真实读取 off/on](docs/test-report-dsh-real-followup.md):支持规则的合成秘密在工具内容/元数据/会话中被脱敏,有用配置保留;无提示注入 L2 结论。 |
409
- | **DSH 0.2.0-rc.2/Node 22** | [默认删除与可选文本读取 adapter](adapters/dsh/README.md) | [最新契约复核](docs/test-report-release-readiness-0.2.3.md):原生删除阻断、已审阅本地/沙箱 FS 的读取脱敏、下一次合成请求与 JSONL 落盘。原生 v4 Lab 支持仍有范围限制;没有新的真实模型 L2 结果。 |
410
- | **Codex CLI 0.154.0(所测会话)** | [Skill + 生产 CLI](docs/test-report-codex-gpt-6-astra-high.md) | 较早源码的合作式验收;不声称原生 hook。 |
411
- | **WorkBuddy(版本未记录;Windows 11)** | [Core/CLI](docs/test-report-workbuddy-windows-core.md) | 社区在 0.2.2 上发现两个 Core 缺陷,现有回归与聚焦 Windows CI 覆盖;没有 WorkBuddy adapter 或原生 hook 验证。 |
412
- | **ZCode(版本未记录;win32)** | [历史 Skill/CLI+hook 试次](docs/test-report-zcode-glm-flash.md) | 旧报告记录了持久许可绕过 hook;当前版本未验证。 |
413
- | **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 官方模型和另一条已配置模型路由上均取得根 Bash PASS;0.42.0 另有主/子代理 BLOCK、ASK 硬拒绝和 Python 故障拒绝。hook 缺席/超时仍可能放行。 |
414
- | **其他/未列出宿主** | [自适配指南](adapters/INTEGRATION.md) | 未独立验证调用前阻断与目标未执行前,不作原生支持声明。 |
415
-
416
- 由 Agent 协助接入时,先识别真实宿主版本与工具名称,阅读上表对应指南,
417
- 保留已有配置,并分别报告配置、本地探针、真实宿主三层证据。未列出的宿主
418
- 依照[自适配清单](adapters/INTEGRATION.md)操作;提示词或 adapter 退出码
419
- 本身不是拦截证明。修改用户级设置、安全策略或依赖前先征求确认。
420
-
421
- `tests/test_conformance.py` 覆盖共享 Core 和 Claude adapter;DSH 有 smoke 测试,
422
- Kimi 有针对性 adapter 测试。上述 Kimi 观察只覆盖实测调用,不构成所有 Shell
423
- 语法或一般并发子代理安全保证。
424
- Kimi 或 Claude 安装可分别运行 `python3 doctor.py kimi --probe`、
425
- `python3 doctor.py claude --probe`,无需模型调用即可检查所选配置文件与
426
- 本地 shell 桥。加 `--json` 可获取 `configuration`、`local_probe`、
427
- `host_interception` 机器可读状态;最后一项始终为 `UNVERIFIED`,
428
- 因为本工具不能证明实际会话加载或强制执行了 hook。参见
429
- [Kimi](adapters/kimi-code/README.md) 与 [Claude](adapters/claude/README.md)
430
- 适配指南。加 `--check-drift` 会在本机查询宿主版本,并对所选 hook 结构与
431
- Agent Guard 运行路径生成去敏指纹;结果使用 `CURRENT`、`STALE`、
432
- `DRIFTED`、`BROKEN` 或 `UNVERIFIED`。即使是 `CURRENT` 也只代表静态预检,
433
- 不是实时拦截证明。可选基线只保存解析后的版本和 SHA-256 指纹,详见
434
- [宿主漂移检查说明](docs/host-drift.md)。显式 `--live-sentinel` 可在私有空白
435
- 夹具中消耗一次已配置模型调用,按 `PASS`、`FAIL`、`INCONCLUSIVE` 返回
436
- `NONE`/`NOTICE`、`CRITICAL` 或 `WARNING` 报警;仅仅“标记不存在”绝不算
437
- 通过。它保留哈希化/去敏结果而不保留模型原始输出。这是可信提供方下的
438
- 可靠性探针,不是针对恶意模型的沙盒。Kimi 的可选 doctor 因 TOML 解析需要 Python 3.11+;Core 与
439
- hook adapter 仍支持 Python 3.9+。
440
- 各宿主的覆盖范围、证据等级和执行级验收条件见
441
- [harness 能力矩阵](docs/harness-capabilities.md)。
442
-
443
- ## 目录结构
444
-
445
- ```
446
- agent-guard/
447
- ├── skills/delete-guard/ # Agent 行为层:SKILL.md + CLI 脚本
448
- ├── skills/exfil-guard/ # 出口侧技能:check_span.py · sanitize.py
449
- ├── skills/recovery-audit/ # 证据驱动的仓库审计与恢复
450
- ├── core/ # classifier · policy · recovery · audit · redaction
451
- ├── doctor.py # 本地配置、探针与宿主漂移预检
452
- ├── live_sentinel.py # 可选实宿主哨兵与报警证据
453
- ├── guard_lab.py # 用户控制的离线合成蜜罐实验
454
- ├── adapters/INTEGRATION.md # 未列出宿主的自适配检查清单
455
- ├── adapters/claude/ # Claude Code PreToolUse hook 适配器
456
- ├── adapters/kimi-code/ # Kimi Code PreToolUse hook 适配器
457
- ├── adapters/dsh/ # DeepSeek Harness 接入桥
458
- ├── adapters/codex/harness/# CLI 验收 driver;不是原生 hook
459
- ├── tests/ # unittest 测试套件,含跨 harness 一致性
460
- └── docs/ # architecture · threat-model · friction log
461
- ```
462
-
463
- Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`、
464
- `database-guard`、`cloud-guard` 直接挂同一补偿引擎,无需重构仓库。
465
-
466
- ## 文档
467
-
468
- | 阅读 | 内容 |
149
+ | 宿主 | 接入与证据 |
150
+ |---|---|
151
+ | Claude Code | Bash 原生 `PreToolUse`;2.1.270/2.1.273 的受限脚本宿主拦截记录。[接入](adapters/claude/README.md) |
152
+ | Kimi Code | Bash 原生 `PreToolUse`;0.42.0 的有限主/子路径及 2.1.1 的根代理 Bash 记录。ASK 拒绝;缺失/超时 hook 不覆盖。[接入](adapters/kimi-code/README.md) |
153
+ | DSH | 核查过 0.1.5-rc.1/0.2.0-rc.2 的删除路径;完整文本 read 防护默认关闭。特定 PTC Bash 拒绝不代表所有 PTC API 都受控。[接入](adapters/dsh/README.md) |
154
+ | Codex/其他宿主 | 可显式使用 Skill/CLI。原生拦截需先验证宿主提供阻塞 hook。[适配指南](adapters/INTEGRATION.md) |
155
+
156
+ 精确版本、试验与缺口统一见[完整能力矩阵](docs/guides/harness-capabilities.md)。
157
+ `doctor.py kimi|claude --probe` 只检查选定配置和本地适配路径;PASS 不证明
158
+ 真实宿主已加载 hook。漂移检查也是本地预检。live sentinel 为显式操作,
159
+ 可能消耗模型额度,只覆盖该次根代理 Bash 调用,见
160
+ [宿主漂移指南](docs/guides/host-drift.md)。
161
+
162
+ ## 决策、事故恢复与文档
163
+
164
+ 共享协议是 `ALLOW · SANITIZE · RELOCATE · SNAPSHOT · ASK · BLOCK`,
165
+ 附带稳定 reason code 和说明。
166
+ 聚合优先级为 `BLOCK > ASK > RELOCATE/SNAPSHOT > SANITIZE > ALLOW`。
167
+ 不透明目标和保护边界拒绝执行;受支持的可恢复修改先补偿再继续。
168
+ 授权状态属于本地操作纪律,不是隔离的身份边界。
169
+
170
+ 事故后,[recovery-audit](skills/recovery-audit/SKILL.md)帮助依据尚存的
171
+ Git/会话/缓存证据恢复项目,区分原文、重建与确认缺失;没有来源保留的字节
172
+ 无法凭空恢复。
173
+
174
+ | 文档 | 用途 |
469
175
  |---|---|
470
- | [CONTRIBUTING.md](CONTRIBUTING.md) | 如何提出 Issue 与提交范围清晰的 Pull Request |
471
- | [docs/architecture.md](docs/architecture.md) | 四柱↔组件映射、数据流、关键设计决定 |
472
- | [docs/host-drift.md](docs/host-drift.md) | 零 Token 宿主/版本漂移状态与最小化基线 |
473
- | [docs/guard-lab.md](docs/guard-lab.md) | 合成 Lab 流程、证据语义与不支持的信道 |
474
- | [docs/release-notes-0.2.3.md](docs/release-notes-0.2.3.md) | 0.2.3 正式版范围与证据边界 |
475
- | [docs/release-notes-0.2.3-rc2.md](docs/release-notes-0.2.3-rc2.md) | 已发布预览版:离线 guard-lab 与已复核 DSH 契约 |
476
- | [docs/release-notes-0.2.3-rc1.md](docs/release-notes-0.2.3-rc1.md) | Windows Core fail-closed 候选版与预发布通道 |
477
- | [docs/release-notes-0.2.2.md](docs/release-notes-0.2.2.md) | 0.2.2 宿主漂移、实时哨兵与 DSH 打包验收 |
478
- | [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor 变更与证据边界 |
479
- | [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 变更、证据等级与已知限制 |
480
- | [adapters/INTEGRATION.md](adapters/INTEGRATION.md) | 未列出宿主的自适配检查清单 |
481
- | [docs/threat-model.md](docs/threat-model.md) | 诚实边界:它是什么、不是什么 |
482
- | [docs/friction.md](docs/friction.md) | 真实 Agent 与宿主进程撞出来的教训(F1–F20) |
483
- | [docs/development-note-unguarded-deletion.md](docs/development-note-unguarded-deletion.md) | 去标识化事故探索与面向恢复的后续方向 |
484
- | [docs/test-report-codex-gpt-5.6-sol.md](docs/test-report-codex-gpt-5.6-sol.md) | v0.1.1 Codex 评估(medium + high) |
485
- | [docs/test-report-workbuddy-windows-core.md](docs/test-report-workbuddy-windows-core.md) | 社区 Windows Core/CLI 反馈与对应回归 |
486
- | [docs/test-report-dsh-0.1.5-rc.1.md](docs/test-report-dsh-0.1.5-rc.1.md) | DSH 0.1.5-rc.1 打包插件与执行级 `bash` 验收 |
487
- | [docs/test-report-dsh-guard-lab.md](docs/test-report-dsh-guard-lab.md) | DSH 真实模型有界 Lab 基线;无 L2 结论 |
488
- | [docs/test-report-dsh-v0.1.1.md](docs/test-report-dsh-v0.1.1.md) | v0.1.1 DSH 真机测试(DeepSeek V4 Pro high,极简模式) |
489
- | [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | 证据优先级、确定性回放、恢复与落地门禁 |
490
- | [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | 完整规则表与判决码 |
491
- | [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil 规则表、reason code、豁免格式与审计结构 |
492
- | [skills/exfil-guard/references/channels.md](skills/exfil-guard/references/channels.md) | 出口信道分类与不可达信道 |
493
-
494
- ## 状态与路线图
495
-
496
- **v0.2.3** 合并 Windows/Core 修复和离线 guard-lab
497
- MVP,并增强文本脱敏执行与校验、URI 口令识别、PyPI/新版 GitHub 令牌保护,
498
- 收窄部分误伤边界。已有的恢复工具、配置安全视图、Claude/Kimi 接入桥、
499
- doctor、宿主漂移检查与实时哨兵继续提供。
500
- DSH 接入支持已复核的 `0.1.5-rc.1` 和 `0.2.0-rc.2` 契约;可选文本读取
501
- 保护仍默认关闭。
502
-
503
- [0.2.3 说明](docs/release-notes-0.2.3.md)记录本次范围;
504
- [rc2](docs/release-notes-0.2.3-rc2.md)、[rc1](docs/release-notes-0.2.3-rc1.md)
505
- 和 [0.2.2](docs/release-notes-0.2.2.md) 说明保留各自历史范围。
506
- 已发布工件以 [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
507
- 和 npm 为准。
508
-
509
- Core 和 Decision Protocol 由各 harness 共用。DSH、Claude、Kimi 的适配器
510
- 以及 Codex/WorkBuddy/ZCode 的验收记录,统一列在兼容矩阵中。
511
- Kimi 结果包含所测调用的 hook 补偿与执行级 BLOCK 证据,不证明宿主强制执行
512
- 所有 `BLOCK`,也不意味着任意 Agent 操作都受保护。实测旧的直连 Python hook
513
- 启动故障会放行;可选 shell 桥在一次 Kimi 宿主故障注入中将其转为拒绝,
514
- 但前提是桥自身成功运行;单凭配置校验无法证明 hook 在线。本次版本为 Issue #7
515
- 新增了聚焦的真实 Windows Core 门,但各 harness 下的原生 cmd/PowerShell
516
- 执行与一般并发子代理安全仍是明确缺口。
517
- 后续 `git-guard`、`database-guard`、`cloud-guard` 继续复用同一协议与补偿引擎。
518
-
519
- ## guard-lab 合成蜜罐
520
-
521
- 可选的离线蜜罐 Lab 在一次性项目中放入不具备认证能力的合成
522
- 标记。`clean`、`mock-positive`、`mock-injection` 与 `snapshot-positive` 四组
523
- 对照不调用模型,也不访问外网;限时回环观察器记录假 Lab 工具、诱饵 URL 或
524
- 经验证的合成快照,用户还可在试次结束后显式扫描选定输出,只保留哈希、阶段与
525
- 命中的 bait id,不保存原值。
526
-
527
- 真控制器与证据由用户保管,和交给受测 Agent 的夹具分开。观察器、控制文件或
528
- 事件链有问题时只报 `INCONCLUSIVE`。Lab 不能看到普通文件读取,不能证明数据
529
- 已经外发,不能普遍封禁 LLM 调用,也不能抵抗同一系统用户权限下的对手。
530
- 涉及真实 harness 前,请先跑零 Token 对照并阅读
531
- [guard-lab 指南](docs/guard-lab.md)。
532
- 这些内建 case 只报 `CALIBRATION_ONLY`。另设的手动 `injection-probe` 会把诱饵
533
- 命中记为 `EXPOSURE_OBSERVED`;只有未防护基线确实中招,并与相同协议、
534
- harness/版本/模型、实验组和任务哈希的开启防护试次配对,`compare` 才可能给出
535
- 缓解成立。手动真实模型试次还必须由用户确认宿主确实完成,避免把“进程退出 0、
536
- 但模型/配置已失败”误算成安静成功。基线没触发时只能报 `INCONCLUSIVE`,任何
537
- 结果都不是对模型或厂商的通用安全认证。
176
+ | [入门指南](docs/guides/getting-started.md) | 包路径、Agent 接入提示词、安全验证 |
177
+ | [文档导航](docs/README.md) | 指南、设计、Lab、报告、发布与历史 |
178
+ | [架构](docs/design/architecture.md) | 共享 Core、补偿与适配器数据流 |
179
+ | [威胁模型](docs/design/threat-model.md) | 信任假设与尚未解决的边界 |
180
+ | [兼容契约](docs/design/compatibility.md) | 接口与发布约定 |
181
+ | [0.2.5-rc1 说明](docs/releases/release-notes-0.2.5-rc1.md) | 本候选变更与验收状态 |
538
182
 
539
183
  ## 参与贡献
540
184
 
541
- 欢迎缺陷报告、设计提案、兼容性证据、文档修订与范围明确的代码改动。非小型或
542
- 涉及安全边界的变更请先发
543
- [Issue](https://github.com/mokuyoaxis/agent-guard/issues),实现请通过范围清晰的
544
- [Pull Request](https://github.com/mokuyoaxis/agent-guard/pulls) 提交。分享日志或
545
- 测试证据前请先阅读[贡献指南](CONTRIBUTING.md);不得公开凭据、私有配置或未经
546
- 去敏的事故资料。
185
+ 欢迎缺陷报告、兼容性证据、文档修订和范围明确的代码改动。分享日志前阅读
186
+ [CONTRIBUTING.md](CONTRIBUTING.md),通过
187
+ [Issues](https://github.com/mokuyoaxis/agent-guard/issues) 和
188
+ [Pull Requests](https://github.com/mokuyoaxis/agent-guard/pulls)参与;
189
+ 不得公开凭据、私有配置和未脱敏事故记录。
547
190
 
548
191
  ## 社区友链
549
192