@mokuyoaxis/agent-guard 0.2.2 → 0.2.3-rc2
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.
- package/README.md +58 -19
- package/README.zh-CN.md +52 -15
- package/adapters/claude/README.md +5 -5
- package/adapters/dsh/README.md +81 -4
- package/adapters/dsh/harness/README.md +328 -0
- package/adapters/dsh/harness/baseline.patch.yml +8 -0
- package/adapters/dsh/harness/guard_lab.py +609 -0
- package/adapters/dsh/harness/native_session.py +482 -0
- package/adapters/dsh/harness/profiles.py +160 -0
- package/adapters/dsh/harness/read_fixture.py +60 -0
- package/adapters/dsh/harness/retry_stream.py +171 -0
- package/adapters/dsh/harness/session_decode.mjs +117 -0
- package/adapters/dsh/lib/index.js +46 -5
- package/adapters/dsh/lib/read_result_guard.js +207 -0
- package/adapters/dsh/lib/read_result_guard.py +139 -0
- package/adapters/harness_support.py +109 -0
- package/adapters/kimi-code/README.md +7 -0
- package/adapters/kimi-code/harness/README.md +126 -0
- package/adapters/kimi-code/harness/guard_lab.py +430 -0
- package/core/classifier.py +90 -23
- package/core/dialects.py +6 -5
- package/core/lab.py +2373 -0
- package/docs/architecture.md +102 -12
- package/docs/compatibility.md +10 -5
- package/docs/friction.md +95 -0
- package/docs/guard-lab-clean-task.md +4 -0
- package/docs/guard-lab-trial-task.md +5 -0
- package/docs/guard-lab.md +391 -0
- package/docs/harness-capabilities.md +7 -4
- package/docs/release-notes-0.2.3-rc1.md +92 -0
- package/docs/release-notes-0.2.3-rc2.md +189 -0
- package/docs/release-notes-0.2.3.md +45 -0
- package/docs/test-report-dsh-0.2-upgrade.md +142 -0
- package/docs/test-report-dsh-guard-lab.md +154 -0
- package/docs/test-report-dsh-native-session.md +118 -0
- package/docs/test-report-dsh-paired-lab.md +183 -0
- package/docs/test-report-dsh-read-redaction.md +114 -0
- package/docs/test-report-dsh-real-followup.md +170 -0
- package/docs/test-report-dsh-retry-evidence.md +134 -0
- package/docs/test-report-kimi-guard-lab.md +117 -0
- package/docs/test-report-release-readiness-0.2.3.md +161 -0
- package/docs/test-report-zcode-glm-flash.md +8 -1
- package/docs/threat-model.md +42 -0
- package/guard_lab.py +14 -0
- package/package.json +8 -5
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](docs/release-notes-0.2.3-rc2.md)
|
|
8
8
|
|
|
9
9
|
**Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
|
|
10
10
|
|
|
@@ -19,6 +19,8 @@ keeping routine work automatic.
|
|
|
19
19
|
- **Accidental outbound disclosure** of known credentials or host-identifying
|
|
20
20
|
absolute paths can be checked through a cooperative text CLI. A caller that
|
|
21
21
|
owns the emission can apply its redaction plan, escalate, or block.
|
|
22
|
+
- **Synthetic honeytoken experiments** can exercise declared local channels
|
|
23
|
+
with zero-token controls and fail-inconclusive evidence health checks.
|
|
22
24
|
|
|
23
25
|
The Core is harness-neutral and supports Python 3.9+ and Git. Automatic
|
|
24
26
|
interception still depends on whether the host exposes a compatible hook; a
|
|
@@ -58,6 +60,12 @@ Pinned npm installation into a stable, user-owned prefix:
|
|
|
58
60
|
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.2
|
|
59
61
|
```
|
|
60
62
|
|
|
63
|
+
`0.2.2` remains the stable recommendation. The published prerelease
|
|
64
|
+
`@mokuyoaxis/agent-guard@0.2.3-rc1` is also available through npm `@rc`, but
|
|
65
|
+
does not contain guard-lab. This checkout is the `0.2.3-rc2` source candidate;
|
|
66
|
+
check Releases and npm before assuming rc2 is published. Prereleases do not
|
|
67
|
+
replace npm `latest`.
|
|
68
|
+
|
|
61
69
|
The package root is then
|
|
62
70
|
`/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
|
|
63
71
|
Alternatively, clone the source (skip this if you already have a checkout):
|
|
@@ -201,6 +209,13 @@ and **host-identifying absolute paths**. Depending on the channel, it can
|
|
|
201
209
|
allow the payload, return a redaction plan, ask for a human decision, or block
|
|
202
210
|
the emission.
|
|
203
211
|
|
|
212
|
+
DSH also offers a [default-off text-read redaction prototype](adapters/dsh/README.md#experimental-text-read-redaction)
|
|
213
|
+
for complete native reads in a pinned composition. It reuses Core and
|
|
214
|
+
regenerates both rendered text and presentation metadata; a zero-model native
|
|
215
|
+
probe covers the next request and durable JSONL log. A separate
|
|
216
|
+
[official Flash direct-read trial](docs/test-report-dsh-real-followup.md)
|
|
217
|
+
observed supported synthetic-secret redaction while useful config stayed readable.
|
|
218
|
+
|
|
204
219
|
It is a prevention and redaction guard, not a compensation engine: after an
|
|
205
220
|
emission there is nothing to recover. It is also **not a security sandbox** and
|
|
206
221
|
does not attempt to stop adversarial exfiltration by an agent with equal OS
|
|
@@ -412,7 +427,9 @@ those evidence levels explicit:
|
|
|
412
427
|
| Harness / tested version | Integration path | Evidence and limit |
|
|
413
428
|
|---|---|---|
|
|
414
429
|
| **Claude Code 2.1.270 / 2.1.273** | [Native `PreToolUse` for Bash](adapters/claude/README.md) | [Real CLI + scripted model](docs/test-report-claude-code-harness.md): sampled allow/ask/deny and Python-startup failure; other tools unverified. |
|
|
415
|
-
| **DSH 0.1.5-rc.1** | [Native pre-execute adapter](adapters/dsh/README.md) | [Real-host
|
|
430
|
+
| **DSH 0.1.5-rc.1** | [Native pre-execute adapter](adapters/dsh/README.md) | [Real-host packaged-plugin probe](docs/test-report-dsh-0.1.5-rc.1.md): execution-level `BLOCK` and loaded-adapter Core failure. A [real-model Lab baseline](docs/test-report-dsh-guard-lab.md) stayed quiet with guard off, so no L2 mitigation claim exists; model-proposed destructive `bash` enforcement remains unverified. The separate opt-in read path is listed below. |
|
|
431
|
+
| **DSH CLI rc.1 / tools and FS rc.2 / Node 22** | [Experimental text-read redaction](adapters/dsh/README.md#experimental-text-read-redaction), default off | [Zero-model native probe](docs/test-report-dsh-read-redaction.md): next request and durable JSONL. [Official Flash direct-read off/on](docs/test-report-dsh-real-followup.md): supported synthetic secrets redacted in tool content/meta/session, useful config preserved; no injection L2 claim. |
|
|
432
|
+
| **DSH 0.2.0-rc.2 / Node 22** | [Default deletion and optional text-read adapter](adapters/dsh/README.md) | [Fresh contract review](docs/test-report-release-readiness-0.2.3.md): native deletion blocking, read redaction on reviewed local/sandbox FS, next synthetic request and durable JSONL. Native v4 Lab support remains bounded; no new real-model L2 result. |
|
|
416
433
|
| **Codex CLI 0.154.0 (tested session)** | [Skill + production CLI](docs/test-report-codex-gpt-6-astra-high.md) | Older-source cooperative acceptance; no native hook claim. |
|
|
417
434
|
| **ZCode (version unrecorded; win32)** | [Historical Skill/CLI + hook trial](docs/test-report-zcode-glm-flash.md) | Older hook observation includes a persistent-permission bypass; current version unverified. |
|
|
418
435
|
| **Kimi Code 0.42.0 / 2.1.1** | [Native `PreToolUse` for Bash](adapters/kimi-code/README.md) | [Bounded tests](docs/test-report-kimi-code-block.md): authenticated 2.1.1 root-Bash PASS on an OAuth official model and maintainer-confirmed official K3 relay; older 0.42.0 root/child BLOCK, ASK denial and Python-failure refusal. Hook absence/timeout remains fail-open. |
|
|
@@ -462,6 +479,7 @@ agent-guard/
|
|
|
462
479
|
├── core/ # classifier · policy · recovery · audit · redaction
|
|
463
480
|
├── doctor.py # local configuration, probes, and drift preflight
|
|
464
481
|
├── live_sentinel.py # opt-in real-host sentinel and alarm evidence
|
|
482
|
+
├── guard_lab.py # user-controlled offline synthetic honeytoken lab
|
|
465
483
|
├── adapters/INTEGRATION.md # checklist for an unlisted host
|
|
466
484
|
├── adapters/claude/ # Claude Code PreToolUse hook adapter
|
|
467
485
|
├── adapters/kimi-code/ # Kimi Code PreToolUse hook adapter
|
|
@@ -482,15 +500,19 @@ compensation engine without restructuring.
|
|
|
482
500
|
| [CONTRIBUTING.md](CONTRIBUTING.md) | how to propose an Issue and submit a focused Pull Request |
|
|
483
501
|
| [docs/architecture.md](docs/architecture.md) | pillars ↔ components, data flow, design decisions |
|
|
484
502
|
| [docs/host-drift.md](docs/host-drift.md) | zero-token host/version drift states and privacy-minimal baselines |
|
|
503
|
+
| [docs/guard-lab.md](docs/guard-lab.md) | synthetic Lab workflow, evidence semantics, and unsupported channels |
|
|
504
|
+
| [docs/release-notes-0.2.3-rc2.md](docs/release-notes-0.2.3-rc2.md) | offline guard-lab source candidate |
|
|
505
|
+
| [docs/release-notes-0.2.3-rc1.md](docs/release-notes-0.2.3-rc1.md) | Windows Core fail-closed candidate and prerelease channel |
|
|
485
506
|
| [docs/release-notes-0.2.2.md](docs/release-notes-0.2.2.md) | 0.2.2 host drift, live sentinel and DSH package acceptance |
|
|
486
507
|
| [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor changes and bounded evidence |
|
|
487
508
|
| [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 changes, evidence levels, and known limits |
|
|
488
509
|
| [adapters/INTEGRATION.md](adapters/INTEGRATION.md) | self-adaptation checklist for an unlisted host |
|
|
489
510
|
| [docs/threat-model.md](docs/threat-model.md) | honest limits: what this is and is not |
|
|
490
|
-
| [docs/friction.md](docs/friction.md) | what real agents taught us (F1–
|
|
511
|
+
| [docs/friction.md](docs/friction.md) | what real agents and host processes taught us (F1–F20) |
|
|
491
512
|
| [docs/development-note-unguarded-deletion.md](docs/development-note-unguarded-deletion.md) | de-identified incident exploration and the recovery-aware direction |
|
|
492
513
|
| [docs/test-report-codex-gpt-5.6-sol.md](docs/test-report-codex-gpt-5.6-sol.md) | v0.1.1 Codex evaluation (medium + high) |
|
|
493
514
|
| [docs/test-report-dsh-0.1.5-rc.1.md](docs/test-report-dsh-0.1.5-rc.1.md) | current DSH packaged-plugin and execution-level `bash` acceptance |
|
|
515
|
+
| [docs/test-report-dsh-guard-lab.md](docs/test-report-dsh-guard-lab.md) | bounded DSH real-model Lab baseline; no L2 claim |
|
|
494
516
|
| [docs/test-report-dsh-v0.1.1.md](docs/test-report-dsh-v0.1.1.md) | v0.1.1 DSH live test (DeepSeek V4 Pro high, minimal mode) |
|
|
495
517
|
| [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | evidence hierarchy, deterministic replay, recovery and landing gates |
|
|
496
518
|
| [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | full rule table and decision codes |
|
|
@@ -499,13 +521,17 @@ compensation engine without restructuring.
|
|
|
499
521
|
|
|
500
522
|
## Status & roadmap
|
|
501
523
|
|
|
502
|
-
The source version is **v0.2.
|
|
524
|
+
The source version is **v0.2.3-rc2**; the latest stable release remains
|
|
525
|
+
**v0.2.2**. The published `v0.2.0` baseline includes
|
|
503
526
|
recoverable destructive actions, cmd/PowerShell dialect parsing, the
|
|
504
527
|
`exfil-guard` text CLI, a read-only config view, and `recovery-audit`.
|
|
505
528
|
Later source releases add Claude/Kimi POSIX hook bridges, bounded host
|
|
506
529
|
evidence, a local `doctor`, host-drift checks, an opt-in live sentinel and
|
|
507
|
-
current DSH package acceptance.
|
|
508
|
-
|
|
530
|
+
current DSH package acceptance. The rc2 source additionally contains the
|
|
531
|
+
offline guard-lab MVP described below. See the
|
|
532
|
+
[0.2.3-rc2 notes](docs/release-notes-0.2.3-rc2.md) for its source scope,
|
|
533
|
+
[0.2.3-rc1 notes](docs/release-notes-0.2.3-rc1.md) for the published candidate,
|
|
534
|
+
[0.2.2 notes](docs/release-notes-0.2.2.md) for the stable scope, and
|
|
509
535
|
[GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) for
|
|
510
536
|
publication status; a source version is not itself a published Release.
|
|
511
537
|
|
|
@@ -518,21 +544,34 @@ actions are protected. A tested direct-Python hook startup failure was
|
|
|
518
544
|
fail-open. The optional shell bridge blocked a sampled Python startup failure
|
|
519
545
|
in a real Kimi host session, but only when the bridge itself ran; config
|
|
520
546
|
validation alone cannot prove that the hook is live.
|
|
521
|
-
|
|
522
|
-
|
|
547
|
+
The candidate adds a focused real-Windows Core gate for Issue #7, but native
|
|
548
|
+
cmd/PowerShell execution through every harness and general concurrent-subagent
|
|
549
|
+
safety remain explicit gaps. Later Guard branches (`git-guard`, `database-guard`,
|
|
523
550
|
`cloud-guard`) reuse the same protocol and compensation engine.
|
|
524
551
|
|
|
525
|
-
## 0.2.
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
or
|
|
552
|
+
## 0.2.3-rc2 source candidate: guard-lab
|
|
553
|
+
|
|
554
|
+
The current source adds an opt-in, offline honeytoken MVP using disposable
|
|
555
|
+
projects and synthetic, non-secret markers. Its `clean`, `mock-positive`,
|
|
556
|
+
`mock-injection`, and `snapshot-positive` controls call no model and make no
|
|
557
|
+
external request. A bounded loopback observer records the fake Lab stub, bait
|
|
558
|
+
URL, or a validated synthetic snapshot; an explicit post-run scan can detect a
|
|
559
|
+
canary in selected output without retaining the raw value.
|
|
560
|
+
|
|
561
|
+
The user keeps the true controller and evidence outside the fixture shown to
|
|
562
|
+
the tested agent. Broken controls or changed evidence produce `INCONCLUSIVE`,
|
|
563
|
+
never an optimistic pass. This first candidate cannot observe ordinary file
|
|
564
|
+
reads, prove remote transfer, universally block LLM calls, or resist a same-UID
|
|
565
|
+
adversary. Start with the zero-token controls and read the
|
|
566
|
+
[guard-lab guide](docs/guard-lab.md) before involving a real harness.
|
|
567
|
+
The built-in cases report `CALIBRATION_ONLY`. A separate manual
|
|
568
|
+
`injection-probe` treats bait contact as `EXPOSURE_OBSERVED`, and `compare`
|
|
569
|
+
accepts a mitigation result only after an effective unguarded baseline and a
|
|
570
|
+
matched guarded trial with the same protocol, harness/version/model, group,
|
|
571
|
+
and task hash. Manual real-model runs also require a user-verified completed
|
|
572
|
+
host result, so an exit-0 startup/model failure cannot count as a quiet win.
|
|
573
|
+
A quiet baseline stays `INCONCLUSIVE`; no result is a general model or vendor
|
|
574
|
+
safety rating.
|
|
536
575
|
|
|
537
576
|
## Contributing
|
|
538
577
|
|
package/README.zh-CN.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](docs/release-notes-0.2.3-rc2.md)
|
|
8
8
|
|
|
9
9
|
**让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
|
|
10
10
|
|
|
@@ -15,6 +15,8 @@ Agent Guard 是给编码 Agent 用的可靠性工具:让受支持的高风险
|
|
|
15
15
|
- **破坏性 Git 操作**:可先保存可恢复的状态,再覆盖工作树。
|
|
16
16
|
- **意外外发**:合作式文本 CLI 可检查已知凭据和带本机标识的绝对路径;
|
|
17
17
|
持有载荷的调用方按判决应用脱敏计划、请求人工处理或阻断。
|
|
18
|
+
- **合成蜜罐验测**:用零 Token 正负对照检查明确列出的本地信道;证据健康
|
|
19
|
+
不足时只报 `INCONCLUSIVE`,不猜测通过。
|
|
18
20
|
|
|
19
21
|
共享 Core 支持 Python 3.9+ 和 Git,不依附某个 harness。能否自动拦截,
|
|
20
22
|
仍取决于宿主有没有兼容 hook;仅安装 Skill 不会自动拦截工具调用。
|
|
@@ -48,6 +50,11 @@ checkout。不要误装无作用域的同名 `agent-guard` 包。
|
|
|
48
50
|
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.2
|
|
49
51
|
```
|
|
50
52
|
|
|
53
|
+
`0.2.2` 仍是稳定版推荐。已发布的预览版
|
|
54
|
+
`@mokuyoaxis/agent-guard@0.2.3-rc1` 也可通过 npm `@rc` 安装,但它不含
|
|
55
|
+
guard-lab。当前 checkout 是 `0.2.3-rc2` 源码候选;是否已经发布,请以
|
|
56
|
+
Releases 与 npm 为准。预发布不会替换 npm `latest`。
|
|
57
|
+
|
|
51
58
|
安装后的包根目录是
|
|
52
59
|
`/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`。
|
|
53
60
|
也可以克隆源码;如果已有 checkout,跳过克隆:
|
|
@@ -173,6 +180,12 @@ DSH 的 `PreToolDecision`、Claude Code PreToolUse 的 `ask`,或在不支持
|
|
|
173
180
|
**带本机标识的绝对路径**。依据信道,Guard 可放行、返回脱敏计划、
|
|
174
181
|
请求人处理或阻断。
|
|
175
182
|
|
|
183
|
+
DSH 另有[默认关闭的文本 `read` 脱敏原型](adapters/dsh/README.md#experimental-text-read-redaction),
|
|
184
|
+
仅覆盖版本门控下的完整原生读取。它复用同一 Core,并让 DSH 同时重新生成
|
|
185
|
+
返回文本和展示元数据;零模型原生验证已覆盖下一次请求和 JSONL 落盘。
|
|
186
|
+
另一次[官方 Flash 真实直接读取对照](docs/test-report-dsh-real-followup.md)
|
|
187
|
+
观察到支持规则的合成秘密被脱敏,同时保留有用配置;这不是提示注入 L2 结论。
|
|
188
|
+
|
|
176
189
|
它做的是预防和脱敏,不是补偿:内容发出去后就不能撤销。它也**不是
|
|
177
190
|
安全沙箱**,不负责抵抗拥有相同系统权限的 Agent 蓄意外泄。
|
|
178
191
|
|
|
@@ -363,7 +376,9 @@ node_modules/(已 ignore) → ALLOW (可证明可再生)
|
|
|
363
376
|
| Harness/实测版本 | 接入路径 | 证据与边界 |
|
|
364
377
|
|---|---|---|
|
|
365
378
|
| **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) | [
|
|
379
|
+
| **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` 时的强制执行仍未验证。单独开启的读取脱敏路径见下一行。 |
|
|
380
|
+
| **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 结论。 |
|
|
381
|
+
| **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 结果。 |
|
|
367
382
|
| **Codex CLI 0.154.0(所测会话)** | [Skill + 生产 CLI](docs/test-report-codex-gpt-6-astra-high.md) | 较早源码的合作式验收;不声称原生 hook。 |
|
|
368
383
|
| **ZCode(版本未记录;win32)** | [历史 Skill/CLI+hook 试次](docs/test-report-zcode-glm-flash.md) | 旧报告记录了持久许可绕过 hook;当前版本未验证。 |
|
|
369
384
|
| **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 缺席/超时仍可能放行。 |
|
|
@@ -406,6 +421,7 @@ agent-guard/
|
|
|
406
421
|
├── core/ # classifier · policy · recovery · audit · redaction
|
|
407
422
|
├── doctor.py # 本地配置、探针与宿主漂移预检
|
|
408
423
|
├── live_sentinel.py # 可选实宿主哨兵与报警证据
|
|
424
|
+
├── guard_lab.py # 用户控制的离线合成蜜罐实验
|
|
409
425
|
├── adapters/INTEGRATION.md # 未列出宿主的自适配检查清单
|
|
410
426
|
├── adapters/claude/ # Claude Code PreToolUse hook 适配器
|
|
411
427
|
├── adapters/kimi-code/ # Kimi Code PreToolUse hook 适配器
|
|
@@ -425,15 +441,19 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
|
|
|
425
441
|
| [CONTRIBUTING.md](CONTRIBUTING.md) | 如何提出 Issue 与提交范围清晰的 Pull Request |
|
|
426
442
|
| [docs/architecture.md](docs/architecture.md) | 四柱↔组件映射、数据流、关键设计决定 |
|
|
427
443
|
| [docs/host-drift.md](docs/host-drift.md) | 零 Token 宿主/版本漂移状态与最小化基线 |
|
|
444
|
+
| [docs/guard-lab.md](docs/guard-lab.md) | 合成 Lab 流程、证据语义与不支持的信道 |
|
|
445
|
+
| [docs/release-notes-0.2.3-rc2.md](docs/release-notes-0.2.3-rc2.md) | 离线 guard-lab 源码候选 |
|
|
446
|
+
| [docs/release-notes-0.2.3-rc1.md](docs/release-notes-0.2.3-rc1.md) | Windows Core fail-closed 候选版与预发布通道 |
|
|
428
447
|
| [docs/release-notes-0.2.2.md](docs/release-notes-0.2.2.md) | 0.2.2 宿主漂移、实时哨兵与 DSH 打包验收 |
|
|
429
448
|
| [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor 变更与证据边界 |
|
|
430
449
|
| [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 变更、证据等级与已知限制 |
|
|
431
450
|
| [adapters/INTEGRATION.md](adapters/INTEGRATION.md) | 未列出宿主的自适配检查清单 |
|
|
432
451
|
| [docs/threat-model.md](docs/threat-model.md) | 诚实边界:它是什么、不是什么 |
|
|
433
|
-
| [docs/friction.md](docs/friction.md) | 真实 Agent
|
|
452
|
+
| [docs/friction.md](docs/friction.md) | 真实 Agent 与宿主进程撞出来的教训(F1–F20) |
|
|
434
453
|
| [docs/development-note-unguarded-deletion.md](docs/development-note-unguarded-deletion.md) | 去标识化事故探索与面向恢复的后续方向 |
|
|
435
454
|
| [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
455
|
| [docs/test-report-dsh-0.1.5-rc.1.md](docs/test-report-dsh-0.1.5-rc.1.md) | 当前 DSH 打包插件与执行级 `bash` 验收 |
|
|
456
|
+
| [docs/test-report-dsh-guard-lab.md](docs/test-report-dsh-guard-lab.md) | DSH 真实模型有界 Lab 基线;无 L2 结论 |
|
|
437
457
|
| [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
458
|
| [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | 证据优先级、确定性回放、恢复与落地门禁 |
|
|
439
459
|
| [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | 完整规则表与判决码 |
|
|
@@ -442,11 +462,15 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
|
|
|
442
462
|
|
|
443
463
|
## 状态与路线图
|
|
444
464
|
|
|
445
|
-
当前源码版本为 **v0.2.
|
|
465
|
+
当前源码版本为 **v0.2.3-rc2**,最新稳定版仍为 **v0.2.2**。已发布的
|
|
466
|
+
`v0.2.0` 基线包含可恢复的破坏性
|
|
446
467
|
操作、cmd/PowerShell 方言解析、`exfil-guard` 文本 CLI、只读配置安全视图
|
|
447
468
|
和 `recovery-audit`。后续源码版新增 Claude/Kimi POSIX hook 桥、有界宿主
|
|
448
|
-
证据、`doctor`、宿主漂移检查、可选实时哨兵与当前 DSH
|
|
449
|
-
|
|
469
|
+
证据、`doctor`、宿主漂移检查、可选实时哨兵与当前 DSH 打包验收;rc2 源码另含
|
|
470
|
+
下述离线 guard-lab MVP。准确范围见
|
|
471
|
+
[0.2.3-rc2 说明](docs/release-notes-0.2.3-rc2.md)记录源码候选范围,
|
|
472
|
+
[0.2.3-rc1 说明](docs/release-notes-0.2.3-rc1.md)记录已发布候选范围,
|
|
473
|
+
[0.2.2 说明](docs/release-notes-0.2.2.md)记录稳定版范围;是否已正式发布以
|
|
450
474
|
[GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) 为准,
|
|
451
475
|
源码版本号本身不代表已有 Release。
|
|
452
476
|
|
|
@@ -455,17 +479,30 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
|
|
|
455
479
|
Kimi 结果包含所测调用的 hook 补偿与执行级 BLOCK 证据,不证明宿主强制执行
|
|
456
480
|
所有 `BLOCK`,也不意味着任意 Agent 操作都受保护。实测旧的直连 Python hook
|
|
457
481
|
启动故障会放行;可选 shell 桥在一次 Kimi 宿主故障注入中将其转为拒绝,
|
|
458
|
-
但前提是桥自身成功运行;单凭配置校验无法证明 hook
|
|
459
|
-
|
|
482
|
+
但前提是桥自身成功运行;单凭配置校验无法证明 hook 在线。候选版为 Issue #7
|
|
483
|
+
新增了聚焦的真实 Windows Core 门,但各 harness 下的原生 cmd/PowerShell
|
|
484
|
+
执行与一般并发子代理安全仍是明确缺口。
|
|
460
485
|
后续 `git-guard`、`database-guard`、`cloud-guard` 继续复用同一协议与补偿引擎。
|
|
461
486
|
|
|
462
|
-
## 0.2.
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
487
|
+
## 0.2.3-rc2 源码候选:guard-lab 合成蜜罐
|
|
488
|
+
|
|
489
|
+
当前源码加入了可选的离线蜜罐 MVP:在一次性项目中放入不具备认证能力的合成
|
|
490
|
+
标记。`clean`、`mock-positive`、`mock-injection` 与 `snapshot-positive` 四组
|
|
491
|
+
对照不调用模型,也不访问外网;限时回环观察器记录假 Lab 工具、诱饵 URL 或
|
|
492
|
+
经验证的合成快照,用户还可在试次结束后显式扫描选定输出,只保留哈希、阶段与
|
|
493
|
+
命中的 bait id,不保存原值。
|
|
494
|
+
|
|
495
|
+
真控制器与证据由用户保管,和交给受测 Agent 的夹具分开。观察器、控制文件或
|
|
496
|
+
事件链有问题时只报 `INCONCLUSIVE`。首版不能看到普通文件读取,不能证明数据
|
|
497
|
+
已经外发,不能普遍封禁 LLM 调用,也不能抵抗同一系统用户权限下的对手。
|
|
498
|
+
涉及真实 harness 前,请先跑零 Token 对照并阅读
|
|
499
|
+
[guard-lab 指南](docs/guard-lab.md)。
|
|
500
|
+
这些内建 case 只报 `CALIBRATION_ONLY`。另设的手动 `injection-probe` 会把诱饵
|
|
501
|
+
命中记为 `EXPOSURE_OBSERVED`;只有未防护基线确实中招,并与相同协议、
|
|
502
|
+
harness/版本/模型、实验组和任务哈希的开启防护试次配对,`compare` 才可能给出
|
|
503
|
+
缓解成立。手动真实模型试次还必须由用户确认宿主确实完成,避免把“进程退出 0、
|
|
504
|
+
但模型/配置已失败”误算成安静成功。基线没触发时只能报 `INCONCLUSIVE`,任何
|
|
505
|
+
结果都不是对模型或厂商的通用安全认证。
|
|
469
506
|
|
|
470
507
|
## 参与贡献
|
|
471
508
|
|
|
@@ -115,11 +115,11 @@ lines are lexed with the right rules. Precedence:
|
|
|
115
115
|
| environment | `AGENT_GUARD_DIALECT=powershell` |
|
|
116
116
|
| default | `posix` |
|
|
117
117
|
|
|
118
|
-
The prefilter
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
118
|
+
The prefilter screens both POSIX and Windows destructive vocabularies. The
|
|
119
|
+
dialect chooses the lexer, not whether a suspicious command reaches Core;
|
|
120
|
+
this lets Core turn a known vocabulary mismatch into a fail-closed verdict.
|
|
121
|
+
An unrecognised dialect selector is **not** swapped for POSIX - `check.py`
|
|
122
|
+
returns `BLOCK_DIALECT_UNKNOWN` and the hook exits 2.
|
|
123
123
|
|
|
124
124
|
## Live-tested
|
|
125
125
|
|
package/adapters/dsh/README.md
CHANGED
|
@@ -2,9 +2,19 @@
|
|
|
2
2
|
|
|
3
3
|
Official DSH integration, shipped as a first-class `dsh-plugin` bundle.
|
|
4
4
|
The decision rules are NOT implemented here - this adapter translates the
|
|
5
|
-
Decision Protocol onto DSH's native mechanisms and delegates
|
|
6
|
-
to the shared Python core (`skills/delete-guard/scripts/check.py`)
|
|
7
|
-
|
|
5
|
+
Decision Protocol onto DSH's native mechanisms and delegates deletion
|
|
6
|
+
verdicts to the shared Python core (`skills/delete-guard/scripts/check.py`).
|
|
7
|
+
The opt-in text-read prototype reuses the existing Core exfil policy through
|
|
8
|
+
a bounded local worker. Both ship inside this package.
|
|
9
|
+
|
|
10
|
+
The [current contract review](../../docs/test-report-release-readiness-0.2.3.md)
|
|
11
|
+
verifies the default deletion path on `0.2.0-rc.2` and `0.1.5-rc.1`, and
|
|
12
|
+
the opt-in read path on the reviewed new local and sandbox filesystem providers.
|
|
13
|
+
The package admits both exact host versions. Lab preflight accepts both and
|
|
14
|
+
binds their native formats separately; unsupported session shapes remain
|
|
15
|
+
inconclusive. A running Web service's plugin inventory does not validate this
|
|
16
|
+
checkout or its agent scope. The [initial upgrade check](../../docs/test-report-dsh-0.2-upgrade.md)
|
|
17
|
+
retains the earlier failures and correction history.
|
|
8
18
|
|
|
9
19
|
## Install
|
|
10
20
|
|
|
@@ -21,6 +31,7 @@ dsh plugin --profile <your-profile> add @mokuyoaxis/agent-guard
|
|
|
21
31
|
| `agent_guard_restore` | model tool | list / non-overwriting restore of quarantine transactions; forced overwrite remains human-only CLI functionality |
|
|
22
32
|
| `agent_guard_status` | model tool | mode, usage, retention view, recent decisions |
|
|
23
33
|
| Prompt section | system prompt (order 105) | deletion discipline for the model |
|
|
34
|
+
| Experimental text `read` redaction | opt-in `tools/post-execute` value replacement | shared Core scans a complete read and DSH regenerates content and presentation metadata; unsupported or unscannable results are withheld |
|
|
24
35
|
|
|
25
36
|
## Configuration (cordis.patch.yml row)
|
|
26
37
|
|
|
@@ -31,6 +42,67 @@ dsh plugin --profile <your-profile> add @mokuyoaxis/agent-guard
|
|
|
31
42
|
| `promptSection` | `true` | register the deletion-discipline section |
|
|
32
43
|
| `sectionOrder` | `105` | system-prompt section order |
|
|
33
44
|
| `dialect` | `""` (posix) | shell dialect for guard invocations: `posix`, `cmd`, or `powershell` |
|
|
45
|
+
| `readResultGuard` | `false` | enable the bounded native text-read prototype described below |
|
|
46
|
+
| `readGuardDshRoot` | `""` | absolute installed DSH npm package root; required when the prototype is enabled |
|
|
47
|
+
|
|
48
|
+
## Experimental text-read redaction
|
|
49
|
+
|
|
50
|
+
The default bundle keeps this feature off. Enable it explicitly in a private
|
|
51
|
+
composition **after** the native filesystem tool suite has registered `read`:
|
|
52
|
+
|
|
53
|
+
```yaml
|
|
54
|
+
config:
|
|
55
|
+
repoRoot: '/absolute/agent-guard-checkout'
|
|
56
|
+
defaultCwd: '/absolute/fixture-workspace'
|
|
57
|
+
readResultGuard: true
|
|
58
|
+
readGuardDshRoot: '/absolute/installed/@deepseek-ai/dsh'
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
This prototype pins Node 22 and exact runtime entry-file SHA-256 values.
|
|
62
|
+
CLI `0.1.5-rc.1` uses the reviewed `0.1.5-rc.2` tool/local-FS artifacts;
|
|
63
|
+
CLI `0.2.0-rc.2` uses reviewed `0.2.0-rc.2` tools and local or sandbox FS.
|
|
64
|
+
The current local legacy installation has a different filesystem-tool hash
|
|
65
|
+
and is correctly refused for this optional feature; its default deletion path
|
|
66
|
+
still passes. Wrong versions/artifacts, missing services, an
|
|
67
|
+
unsupported read schema/finalizer, or an unavailable Core worker refuse
|
|
68
|
+
initialization with `READ_GUARD_STARTUP_REFUSED`. The worker and Core must
|
|
69
|
+
belong to the same package/checkout; `repoRoot` cannot redirect this feature
|
|
70
|
+
to another Core. The workspace must match the agent session workspace.
|
|
71
|
+
|
|
72
|
+
A refused plugin does not guarantee that the Cordis host stops other tools.
|
|
73
|
+
On `0.2.0-rc.2`, an isolated composition continued executing tools after this
|
|
74
|
+
plugin failed initialization, with no deletion or read guard contributed by
|
|
75
|
+
that row. Verify successful plugin activation before using a guarded profile;
|
|
76
|
+
the enable flag and a running host alone do not establish protection.
|
|
77
|
+
|
|
78
|
+
Coverage is complete native text reads only: first line 1, all file lines
|
|
79
|
+
returned, at most 20,000 lines, no native line truncation, and a one MiB IPC
|
|
80
|
+
input cap including JSON overhead. Pagination and truncation return
|
|
81
|
+
`READ_RESULT_INCOMPLETE`; oversized IPC returns `READ_RESULT_SIZE`. Scanner
|
|
82
|
+
failure, timeout, cancellation, failed reads and nonempty additional contexts
|
|
83
|
+
are withheld with fixed reason codes. Core `ASK`/`BLOCK` are withheld too.
|
|
84
|
+
Existing Core detection limits still apply; an arbitrary Lab marker has no
|
|
85
|
+
secret semantics merely because it appears in a config field.
|
|
86
|
+
|
|
87
|
+
The worker receives structured text over stdin using a fixed Python command.
|
|
88
|
+
It runs as the trusted local plugin controller, outside the shell executor;
|
|
89
|
+
it reads no target file and performs no model/network call. Native `read`
|
|
90
|
+
continues to own filesystem access. The shell-policy inheritance note below
|
|
91
|
+
applies to the existing deletion commands, not this controller worker.
|
|
92
|
+
|
|
93
|
+
The [zero-model native report](../../docs/test-report-dsh-read-redaction.md)
|
|
94
|
+
verifies the actual returned value/content/meta, next request, and full durable
|
|
95
|
+
JSONL log through the real AgentLoop with a synthetic stream. It does not
|
|
96
|
+
establish real-model injection mitigation or universal emission protection.
|
|
97
|
+
The separate [official Flash real-model follow-up](../../docs/test-report-dsh-real-followup.md)
|
|
98
|
+
observed supported synthetic-secret redaction in tool content, presentation
|
|
99
|
+
metadata and the decoded session during a direct-read off/on experiment. It
|
|
100
|
+
preserved useful configuration and remains outside the Lab injection L2 protocol.
|
|
101
|
+
Custom/later finalizers, unreviewed tool providers, PTC, other tool results,
|
|
102
|
+
early events, tool-call arguments and preexisting session data are outside
|
|
103
|
+
this prototype. Plugin composition is trusted; the binding check is not
|
|
104
|
+
authentication of arbitrary plugins. Existing reviewed Lab pair profiles
|
|
105
|
+
remain deletion-only and do not enable this flag.
|
|
34
106
|
|
|
35
107
|
## Shell dialect
|
|
36
108
|
|
|
@@ -47,7 +119,8 @@ is forwarded verbatim rather than swapped for POSIX, so `check.py` returns
|
|
|
47
119
|
|
|
48
120
|
## Notes
|
|
49
121
|
|
|
50
|
-
-
|
|
122
|
+
- Deletion commands inherit the caller's sandbox policy per invocation
|
|
123
|
+
(`exec.agent.session`) through the native shell executor.
|
|
51
124
|
- Once the adapter has registered its pre-execute listener, Core process and
|
|
52
125
|
output failures fail closed (deny). An absent/disabled bundle, a changed host
|
|
53
126
|
event contract, or failure before listener registration cannot deny a call
|
|
@@ -60,3 +133,7 @@ is forwarded verbatim rather than swapped for POSIX, so `check.py` returns
|
|
|
60
133
|
block are independently verified in the
|
|
61
134
|
[bounded host report](../../docs/test-report-dsh-0.1.5-rc.1.md). Model,
|
|
62
135
|
subagent, concurrency, ASK UI and non-`bash` paths remain separate tests.
|
|
136
|
+
- For repeatable baselines and reviewed guard-off/on Lab pairs, use the
|
|
137
|
+
[headless capture/review runner](harness/README.md). Its separate `check`
|
|
138
|
+
command is zero-model; a captured trial remains inconclusive until the user
|
|
139
|
+
verifies host completion and finalizes it.
|