@mokuyoaxis/agent-guard 0.2.4 → 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.
- package/README.md +158 -574
- package/README.zh-CN.md +133 -490
- package/SECURITY.md +53 -0
- package/adapters/INTEGRATION.md +4 -2
- package/adapters/dsh/README.md +7 -0
- package/assets/linux-do-community.svg +19 -0
- package/core/classifier.py +25 -1
- package/core/policy.py +17 -9
- package/core/recovery.py +5 -1
- package/core/redaction.py +122 -21
- package/docs/README.md +14 -5
- package/docs/design/architecture.md +20 -6
- package/docs/design/compatibility.md +71 -1
- package/docs/design/threat-model.md +6 -4
- package/docs/guides/getting-started.md +104 -0
- package/docs/guides/harness-capabilities.md +5 -0
- package/docs/history/friction.md +84 -0
- package/docs/lab/guard-lab.md +3 -1
- package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
- package/package.json +4 -2
- package/skills/delete-guard/SKILL.md +42 -7
- package/skills/delete-guard/references/policy.md +86 -3
- package/skills/delete-guard/scripts/check.py +3 -0
- package/skills/delete-guard/scripts/restore.py +22 -7
- package/skills/delete-guard/scripts/safe_delete.py +52 -29
- package/skills/exfil-guard/SKILL.md +23 -11
- package/skills/exfil-guard/references/channels.md +8 -1
- package/skills/exfil-guard/references/rules.md +83 -6
- package/skills/exfil-guard/scripts/_payload.py +20 -0
- package/skills/exfil-guard/scripts/check_span.py +5 -1
- package/skills/exfil-guard/scripts/sanitize.py +6 -3
package/README.md
CHANGED
|
@@ -1,632 +1,216 @@
|
|
|
1
1
|
# AGENT-GUARD
|
|
2
2
|
|
|
3
3
|
[](https://github.com/mokuyoaxis/agent-guard/actions/workflows/ci.yml)
|
|
4
|
-
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](docs/releases/release-notes-0.2.5-rc1.md)
|
|
8
8
|
|
|
9
9
|
**Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
|
|
10
10
|
|
|
11
|
-
Agent Guard is
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
- **Destructive file operations** can be relocated to `.agent-trash/` with a
|
|
16
|
-
recovery manifest instead of being permanently deleted.
|
|
17
|
-
- **Destructive Git operations** can snapshot recoverable state before they
|
|
18
|
-
overwrite the working tree.
|
|
19
|
-
- **Accidental outbound disclosure** of known credentials or host-identifying
|
|
20
|
-
absolute paths can be checked through a cooperative text CLI. A caller that
|
|
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.
|
|
24
|
-
|
|
25
|
-
The Core is harness-neutral and supports Python 3.9+ and Git. Automatic
|
|
26
|
-
interception still depends on whether the host exposes a compatible hook; a
|
|
27
|
-
Skill by itself does not intercept tool calls. The shared Core, Decision
|
|
28
|
-
Protocol, and Skills define the product; harness adapters are replaceable
|
|
29
|
-
integration bridges rather than the product boundary.
|
|
30
|
-
|
|
31
|
-
> **Agent Guard keeps reversible actions automatic and escalates only when it
|
|
32
|
-
> cannot safely automate them.** It is reliability infrastructure, not a
|
|
33
|
-
> security sandbox: it protects against mistakes, not a malicious agent with
|
|
34
|
-
> equal OS privileges.
|
|
35
|
-
|
|
36
|
-
## What it looks like
|
|
37
|
-
|
|
38
|
-
```text
|
|
39
|
-
rm -rf build/ → RELOCATE # an in-scope tree moves to quarantine
|
|
40
|
-
rm -rf . → BLOCK # the workspace root is protected
|
|
41
|
-
git reset --hard → SNAPSHOT # after collision preflight, snapshot tracked changes
|
|
42
|
-
git push --force → BLOCK # remote history is not automated
|
|
43
|
-
```
|
|
11
|
+
Agent Guard is reliability infrastructure for coding agents. It provides
|
|
12
|
+
recovery before supported destructive actions, checks text before disclosure,
|
|
13
|
+
and gives users a Lab for testing observed agent and harness behaviour.
|
|
14
|
+
The shared Python Core works through explicit CLIs and optional host adapters.
|
|
44
15
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
the guard asks the human or blocks the operation.
|
|
16
|
+
| Capability | What it helps you do | Entry |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| **Recovery protection** | Relocate valuable files before deletion; snapshot tracked state before supported Git overwrites; inspect and restore transactions | [delete-guard](skills/delete-guard/SKILL.md) |
|
|
19
|
+
| **Disclosure checks** | Detect supported credentials and host-identifying paths; apply a redaction plan or withhold a payload | [exfil-guard](skills/exfil-guard/SKILL.md) |
|
|
20
|
+
| **Behaviour experiments** | Calibrate an observer, test a declared exposure channel, then compare matched guard-off/on trials | [guard-lab](docs/lab/guard-lab.md) |
|
|
51
21
|
|
|
52
|
-
|
|
22
|
+
A Skill supplies instructions; it does not intercept tool calls. Automatic
|
|
23
|
+
protection depends on an active, compatible host hook and its covered tools.
|
|
24
|
+
Agent Guard is not an OS sandbox against a malicious process with equal
|
|
25
|
+
privileges. The [capability matrix](docs/guides/harness-capabilities.md)
|
|
26
|
+
states the observed coverage and gaps.
|
|
53
27
|
|
|
54
|
-
|
|
55
|
-
`agent-guard` package is unrelated to this project.
|
|
28
|
+
<a id="guard-lab"></a>
|
|
56
29
|
|
|
57
|
-
|
|
30
|
+
## guard-lab: test with evidence
|
|
58
31
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
32
|
+
guard-lab is a **user-controlled experiment tool**. It puts non-secret,
|
|
33
|
+
synthetic markers and harmless bait into a disposable project and observes
|
|
34
|
+
only declared channels. The real controller and evidence stay outside the
|
|
35
|
+
fixture given to the tested agent.
|
|
62
36
|
|
|
63
|
-
|
|
64
|
-
restore path validation, current-version preservation on forced restore, and
|
|
65
|
-
a read-only trash location query. See the [release notes](docs/releases/release-notes-0.2.4.md)
|
|
66
|
-
for behavior changes and evidence limits. The npm badge and
|
|
67
|
-
[GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) show
|
|
68
|
-
which artifacts are available.
|
|
37
|
+
Its workflow separates three questions:
|
|
69
38
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
39
|
+
1. **Calibrate:** do the observer, markers, scans and evidence chain work?
|
|
40
|
+
Built-in controls call no model and make no external-network request.
|
|
41
|
+
2. **Observe exposure:** does an unguarded real-harness trial trigger the
|
|
42
|
+
selected channel?
|
|
43
|
+
3. **Compare protection:** after an effective baseline, does a matched
|
|
44
|
+
guarded trial reduce or block that exposure?
|
|
45
|
+
|
|
46
|
+
Start with one zero-model control from the package or checkout root:
|
|
73
47
|
|
|
74
48
|
```sh
|
|
75
|
-
|
|
76
|
-
|
|
49
|
+
lab_run="$(mktemp -d)"
|
|
50
|
+
python3 guard_lab.py run --case clean --output-dir "$lab_run/clean" --json
|
|
77
51
|
```
|
|
78
52
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
(
|
|
82
|
-
|
|
83
|
-
```text
|
|
84
|
-
Set up agent-guard for this workspace. Use either an existing Git checkout or
|
|
85
|
-
the exact scoped npm package @mokuyoaxis/agent-guard@0.2.4;
|
|
86
|
-
never install the unscoped package named agent-guard. If 0.2.4 is unavailable,
|
|
87
|
-
report that and use the existing checkout or ask me to choose a published
|
|
88
|
-
version. Before installing, ask me to choose and
|
|
89
|
-
approve a stable user-owned prefix. Treat the checkout or installed package
|
|
90
|
-
root as /absolute/path/to/agent-guard below.
|
|
91
|
-
First identify the current harness and its actual hook/skill capabilities;
|
|
92
|
-
read this README and the matching adapter README. Check Python and Git.
|
|
93
|
-
Install the relevant Skills, then configure a native shell hook only if this
|
|
94
|
-
harness supports one. Preserve existing settings and show me the proposed
|
|
95
|
-
diff before editing user-wide configuration or installing dependencies.
|
|
96
|
-
For Claude Code use adapters/claude/README.md; for Kimi Code use
|
|
97
|
-
adapters/kimi-code/README.md; for DSH use adapters/dsh/README.md.
|
|
98
|
-
For another host, read adapters/INTEGRATION.md and do not invent a native
|
|
99
|
-
hook. If no blocking pre-tool hook is verified, use only Skill/CLI and say
|
|
100
|
-
plainly that automatic interception is not enabled.
|
|
101
|
-
Verify a harmless command and pass a BLOCK-shaped command only as data to
|
|
102
|
-
check.py; never execute a destructive test command. For Claude/Kimi, run the
|
|
103
|
-
local doctor but do not treat its PASS as proof of host interception. Report
|
|
104
|
-
the host version, tool coverage, what was installed, what the host actually
|
|
105
|
-
intercepted, and any unverified paths.
|
|
106
|
-
```
|
|
53
|
+
The other controls are `mock-positive`, `mock-injection` and
|
|
54
|
+
`snapshot-positive`. Run all four before a real-harness experiment, following
|
|
55
|
+
the [Lab guide](docs/lab/guard-lab.md). Installed packages also expose
|
|
56
|
+
`agent-guard-lab`.
|
|
107
57
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
58
|
+
A control PASS means **instrument calibration**, not model safety.
|
|
59
|
+
An unhealthy observer or missing evidence is `INCONCLUSIVE`; a quiet
|
|
60
|
+
guard-off baseline cannot establish mitigation. Matched comparisons require
|
|
61
|
+
the same relevant harness/version/model, task, protocol and non-guard
|
|
62
|
+
configuration. Lab results cover the declared channels, not every file read,
|
|
63
|
+
external transfer or model request. Existing
|
|
64
|
+
[Kimi](docs/reports/test-report-kimi-guard-lab.md) and
|
|
65
|
+
[DSH](docs/reports/test-report-dsh-guard-lab.md) reports retain their bounded
|
|
66
|
+
results, failures and review states.
|
|
111
67
|
|
|
112
|
-
|
|
68
|
+
<a id="quick-start-with-your-coding-agent"></a>
|
|
113
69
|
|
|
114
|
-
|
|
115
|
-
|---|---|
|
|
116
|
-
| **Stay in scope** | The guard blocks deletion of the workspace root, `.git`, and outside paths when the operation reaches it |
|
|
117
|
-
| **Make it recoverable** | Supported deletions relocate to `.agent-trash/` with a manifest; destructive Git overwrites snapshot first |
|
|
118
|
-
| **Constrain authorization** | Authorization is session-scoped; a veto downgrades one-way, and only a human restores it |
|
|
119
|
-
| **Leave a durable trail** | Enforced verdicts, compensation intents, outcomes, and restores use append-only JSONL; mutation fails closed if its intent cannot be stored |
|
|
70
|
+
## Install and choose a version
|
|
120
71
|
|
|
121
|
-
|
|
72
|
+
Python 3.9+ and Git are required for the Core. The examples use a POSIX shell;
|
|
73
|
+
native bridges and optional capture helpers have their own requirements.
|
|
122
74
|
|
|
123
|
-
|
|
75
|
+
| Version | Status |
|
|
76
|
+
|---|---|
|
|
77
|
+
| [0.2.4](docs/releases/release-notes-0.2.4.md) | Published stable baseline |
|
|
78
|
+
| [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | Maintenance release candidate; select the exact RC version |
|
|
124
79
|
|
|
125
|
-
|
|
126
|
-
least restrictive decision that preserves the relevant safety or recovery
|
|
127
|
-
guarantee. The stable interface is a Decision Protocol, not a binary
|
|
128
|
-
allow/block check:
|
|
80
|
+
For the published stable package, use a chosen, stable user-owned prefix:
|
|
129
81
|
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
SNAPSHOT, ASK, BLOCK }
|
|
133
|
-
+ ReasonCode (stable, machine-readable)
|
|
134
|
-
+ Explanation (human-facing)
|
|
135
|
-
+ RecoveryPlan (txids, strategy)
|
|
82
|
+
```sh
|
|
83
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
|
|
136
84
|
```
|
|
137
85
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
| **AMBIGUOUS** | `ASK` | Single-execution authorization (`ASK_ONCE`) — e.g. compound shapes the guard cannot safely automate |
|
|
142
|
-
| **FORBIDDEN** | `BLOCK` | Refused with reason and remediation; never askable |
|
|
143
|
-
|
|
144
|
-
Precedence when several decisions meet in one operation, weakest to strongest:
|
|
86
|
+
The package root is
|
|
87
|
+
`/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
|
|
88
|
+
The exact scoped package name matters. A source checkout is also usable:
|
|
145
89
|
|
|
90
|
+
```sh
|
|
91
|
+
git clone https://github.com/mokuyoaxis/agent-guard.git
|
|
92
|
+
cd agent-guard
|
|
146
93
|
```
|
|
147
|
-
ALLOW < SANITIZE < RELOCATE < SNAPSHOT < ASK < BLOCK
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
`SANITIZE` ranks *below* `ASK` deliberately: it is automatic (SAFE tier),
|
|
151
|
-
while `ASK` forfeits automation. A payload carrying both a sanitizable secret
|
|
152
|
-
and a shape that cannot be rewritten must `ASK` — you cannot silently proceed
|
|
153
|
-
when part of the emission is uninspectable.
|
|
154
|
-
|
|
155
|
-
True effect uncertainty (`$VAR` targets, `bash -c`, `find -delete`, stdin-fed
|
|
156
|
-
lists) stays on the BLOCK path: allowing it would forfeit the core guarantee.
|
|
157
|
-
Adapters map decisions onto their harness natively — DSH `PreToolDecision`,
|
|
158
|
-
Claude Code PreToolUse `ask`, or a deny carrying the explanation where no ask
|
|
159
|
-
exists.
|
|
160
|
-
|
|
161
|
-
## What Agent Guard includes
|
|
162
|
-
|
|
163
|
-
### `delete-guard`
|
|
164
|
-
|
|
165
|
-
Answers *"if this destroys something, can we come back?"* It runs before a
|
|
166
|
-
delete or destructive Git action when invoked through a supported adapter or
|
|
167
|
-
CLI, and compensates first when recovery is possible.
|
|
168
|
-
|
|
169
|
-
### `exfil-guard`
|
|
170
|
-
|
|
171
|
-
Answers *"if this leaves the machine, was it supposed to?"* Its cooperative
|
|
172
|
-
CLI checks text before an emission when the payload owner invokes it, returning
|
|
173
|
-
a redaction or escalation decision for supported patterns.
|
|
174
94
|
|
|
175
|
-
|
|
95
|
+
For the RC, select `@mokuyoaxis/agent-guard@0.2.5-rc1` explicitly; the RC
|
|
96
|
+
channel does not replace stable `latest`. Check the
|
|
97
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc1)
|
|
98
|
+
or [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc1)
|
|
99
|
+
for publication. A reviewed checkout or locally supplied tarball is also usable. See
|
|
100
|
+
[setup and the agent setup prompt](docs/guides/getting-started.md).
|
|
176
101
|
|
|
177
|
-
|
|
178
|
-
cover the path. It establishes source precedence, distinguishes recovered bytes
|
|
179
|
-
from reconstructed behavior and known gaps, audits replay tooling, and keeps
|
|
180
|
-
landing, commit, push, and release as separate authorization gates.
|
|
102
|
+
## Recover a supported deletion
|
|
181
103
|
|
|
182
|
-
|
|
183
|
-
`recovery-audit` handles evidence-led recovery after the fact.
|
|
104
|
+
From the workspace being protected, point at your package/checkout root:
|
|
184
105
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
cache still preserves successful patches, file snapshots, tool results, diffs,
|
|
191
|
-
and command context.
|
|
192
|
-
|
|
193
|
-
`recovery-audit` turns those remnants, Git remotes/reflogs/stashes, editor or
|
|
194
|
-
tool caches, build artifacts, and project plans into an evidence-led recovery:
|
|
195
|
-
|
|
196
|
-
- every unit is labelled **recovered**, **reconstructed**, or **missing**;
|
|
197
|
-
- recorded tool effects are replayed in chronology and checked for divergence;
|
|
198
|
-
- repeated replay must produce a byte-identical tree;
|
|
199
|
-
- landing, commit, push, and release remain separate authorization gates.
|
|
200
|
-
|
|
201
|
-
It is not filesystem undelete and cannot recreate bytes no surviving source
|
|
202
|
-
captured. Its promise is a fast, auditable path to the strongest project state
|
|
203
|
-
the evidence actually supports, with gaps reported instead of hidden.
|
|
204
|
-
|
|
205
|
-
## exfil-guard
|
|
206
|
-
|
|
207
|
-
`exfil-guard` checks text before an agent writes, sends, commits, or pushes it
|
|
208
|
-
**when the payload owner calls its CLI**. It also offers an explicit, read-only
|
|
209
|
-
safe view of selected JSON/dotenv configuration files. The text scanner is
|
|
210
|
-
designed to catch two accidental disclosure classes: **known credentials**
|
|
211
|
-
and **host-identifying absolute paths**. Depending on the channel, it can
|
|
212
|
-
allow the payload, return a redaction plan, ask for a human decision, or block
|
|
213
|
-
the emission.
|
|
214
|
-
|
|
215
|
-
DSH also offers a [default-off text-read redaction prototype](adapters/dsh/README.md#experimental-text-read-redaction)
|
|
216
|
-
for complete native reads in a pinned composition. It reuses Core and
|
|
217
|
-
regenerates both rendered text and presentation metadata; a zero-model native
|
|
218
|
-
probe covers the next request and durable JSONL log. A separate
|
|
219
|
-
[official Flash direct-read trial](docs/reports/test-report-dsh-real-followup.md)
|
|
220
|
-
observed supported synthetic-secret redaction while useful config stayed readable.
|
|
221
|
-
|
|
222
|
-
It is a prevention and redaction guard, not a compensation engine: after an
|
|
223
|
-
emission there is nothing to recover. It is also **not a security sandbox** and
|
|
224
|
-
does not attempt to stop adversarial exfiltration by an agent with equal OS
|
|
225
|
-
privileges.
|
|
226
|
-
|
|
227
|
-
### Decisions exfil-guard can return
|
|
228
|
-
|
|
229
|
-
The full Decision Protocol applies, but only four classes are reachable for
|
|
230
|
-
a text payload (`RELOCATE`/`SNAPSHOT` belong to delete-guard — the guard
|
|
231
|
-
cannot rewrite what it did not write):
|
|
232
|
-
|
|
233
|
-
| Decision | Meaning | Example |
|
|
234
|
-
|---|---|---|
|
|
235
|
-
| `ALLOW` | nothing matched, a documented placeholder, or a workspace-relative path | `echo "hello" \| check_span.py` |
|
|
236
|
-
| `SANITIZE` | a redaction plan is returned; the *payload owner* rewrites and emits | a real key on `file-write` / `llm-request` |
|
|
237
|
-
| `ASK` | the channel cannot be rewritten and cannot be taken back | a host path on `shell-stdout` |
|
|
238
|
-
| `BLOCK` | refuse: immutable/remote history, an un-scannable payload, invalid config | a credential in `git-push-payload` |
|
|
239
|
-
|
|
240
|
-
### What is detected
|
|
241
|
-
|
|
242
|
-
**T1 vendor credential patterns** (`secret/*`). These rules use known formats;
|
|
243
|
-
documented placeholders and negative examples constrain false positives.
|
|
244
|
-
Rule ids: `secret/openai-key`, `secret/github-token`,
|
|
245
|
-
`secret/aws-access-key-id`, `secret/gitlab-token`, `secret/slack-token`,
|
|
246
|
-
`secret/stripe-key` (live keys only — `sk_test_` is exempt),
|
|
247
|
-
`secret/pypi-token`, `secret/jwt` (structural: the header must decode to JSON
|
|
248
|
-
with a nonempty ASCII string `alg`), and
|
|
249
|
-
`secret/private-key-block` (whole `-----BEGIN ... PRIVATE KEY-----` block,
|
|
250
|
-
redacted in one piece). See
|
|
251
|
-
[skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md)
|
|
252
|
-
for the rule table and remaining ambiguities.
|
|
253
|
-
|
|
254
|
-
`secret/connection-password` also detects nonempty passwords in URI userinfo.
|
|
255
|
-
It redacts only the password, preserving the scheme, account and host for
|
|
256
|
-
diagnostics. Percent-encoded passwords and JSON-escaped scheme slashes are
|
|
257
|
-
supported; this does not hide network topology or scan every DSN format.
|
|
258
|
-
|
|
259
|
-
**Value-free secret references** (`secret/source-reference`). The guard
|
|
260
|
-
classifies complete components in an environment variable's *name* (such as
|
|
261
|
-
`KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD`, `CRED`, or `AUTH`) and a
|
|
262
|
-
secret-store *file name*
|
|
263
|
-
(`.env`, `*.pem`, `id_rsa*`, `.netrc`, `kubeconfig`, ...), and detects
|
|
264
|
-
whole-environment expansions (`printenv`, `env | ...`, `cat
|
|
265
|
-
/proc/self/environ`). This scanner **does not resolve the variable value**;
|
|
266
|
-
that does not certify unrelated Guard output or existing audit records as
|
|
267
|
-
secret-free.
|
|
268
|
-
|
|
269
|
-
**Host-identifying paths** (`path/*`). `path/workspace-relative` is `ALLOW`
|
|
270
|
-
(the workspace is exempt); `path/system` (`/usr`, `/etc`, `C:\Windows`) is
|
|
271
|
-
`ALLOW`; `path/host-absolute` (under `HOME`/`TEMP`, a CI root, or a
|
|
272
|
-
workspace ancestor) is `SANITIZE`; `path/generic-absolute` (no host
|
|
273
|
-
correlation) is `ASK`; `path/device` (UNC, `\\?\`, pipes) is `SANITIZE`.
|
|
274
|
-
|
|
275
|
-
### Channels determine the disposition
|
|
276
|
-
|
|
277
|
-
A channel is defined by two facts: can it be **rewritten**, and does the
|
|
278
|
-
emission **persist**? `rewritable` is what makes `SANITIZE` meaningful;
|
|
279
|
-
`persistence` is what justifies `BLOCK`.
|
|
280
|
-
|
|
281
|
-
| Channel | Rewritable | Persistence | Default |
|
|
282
|
-
|---|---|---|---|
|
|
283
|
-
| `llm-request` | yes | remote | SANITIZE |
|
|
284
|
-
| `file-write` | yes | workspace | SANITIZE |
|
|
285
|
-
| `forge-comment` / `issue-body` / `pr-description` | yes | public | SANITIZE |
|
|
286
|
-
| `git-commit-message` | yes (rewrite argv) | remote history | **BLOCK** |
|
|
287
|
-
| `git-push-payload` | no | **remote** | **BLOCK** |
|
|
288
|
-
| `shell-stdout` | **no** | local transcript | ASK |
|
|
289
|
-
| `shell-file-redirect` | yes | local | ASK |
|
|
290
|
-
| `archive-upload` | yes | remote | ASK |
|
|
291
|
-
| `process-argv` | yes | local | ASK |
|
|
292
|
-
|
|
293
|
-
An unknown channel name is a configuration defect, not "no risk":
|
|
294
|
-
`check_span.py` returns `BLOCK_OUTPUT_UNSCANNABLE`, never an implicit ALLOW.
|
|
295
|
-
|
|
296
|
-
### Usage
|
|
297
|
-
|
|
298
|
-
`check_span.py` reads the payload on **stdin** and is a pure function — it
|
|
299
|
-
never writes, never rewrites, and never prints the match. `sanitize.py`
|
|
300
|
-
applies the plan the guard returned.
|
|
301
|
-
|
|
302
|
-
```bash
|
|
303
|
-
# a credential on a rewritable channel -> SANITIZE, exit 0
|
|
304
|
-
echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/check_span.py --channel file-write
|
|
305
|
-
|
|
306
|
-
# a credential bound for remote history -> BLOCK, exit 2
|
|
307
|
-
echo 'token=ghp_abcdefghijklmnopqrstuvwxyz…' | python3 skills/exfil-guard/scripts/check_span.py --channel git-push-payload
|
|
308
|
-
|
|
309
|
-
# apply the redaction plan (format preserved: sk-<REDACTED>)
|
|
310
|
-
echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/sanitize.py --channel file-write
|
|
311
|
-
```
|
|
312
|
-
|
|
313
|
-
Exit code contract: `0` = ALLOW/SANITIZED · `2` = BLOCK · `3` = ASK ·
|
|
314
|
-
`1` = ERROR. Use `--json` for the machine-readable verdict (offsets, rule ids
|
|
315
|
-
and placeholders only — **never the matched bytes**), and `--path` to enable
|
|
316
|
-
the repo-local exemption file for the file being written.
|
|
317
|
-
|
|
318
|
-
`sanitize.py` enforces the same exit codes: ASK/BLOCK and errors emit no
|
|
319
|
-
payload on stdout. It validates an external `--plan` against the current scan
|
|
320
|
-
and rescans the rewritten text before emitting. Both CLIs use the same default
|
|
321
|
-
workspace and host-side mode; stdin is bounded to the scan cap (4 MiB by default)
|
|
322
|
-
during reading, as is an external plan file. A checker plan produced with an
|
|
323
|
-
explicit mode or path exemption must still satisfy the sanitizer's current
|
|
324
|
-
policy; the plan itself does not authorize emission.
|
|
325
|
-
|
|
326
|
-
Credential detection covers classic and stateless `ghs_APPID_JWT` GitHub
|
|
327
|
-
installation tokens, including long signatures and credentials next to CJK
|
|
328
|
-
prose. Placeholder exemptions require whole shapes; incidental example words
|
|
329
|
-
inside a token do not exempt it. Secret variable references are classified by
|
|
330
|
-
complete name components, preserving ordinary identifiers such as `MONKEY`
|
|
331
|
-
and metadata such as `TOKEN_COUNT`. See the [rule reference](skills/exfil-guard/references/rules.md)
|
|
332
|
-
for supported forms and limitations.
|
|
333
|
-
|
|
334
|
-
PyPI publishing tokens are also detected with their documented prefix and
|
|
335
|
-
minimum body shape, with complete redaction of long tokens. AWS group/user/
|
|
336
|
-
role/policy IDs are kept distinct from access-key IDs; JWT headers require
|
|
337
|
-
the declared nonempty ASCII string `alg`. Public-key variable names and the
|
|
338
|
-
broad legacy `sk-` shape retain their documented conservative boundaries.
|
|
339
|
-
|
|
340
|
-
### Read a config without printing its values
|
|
341
|
-
|
|
342
|
-
Introduced in the `0.2.0` source; this CLI is **not** in the earlier
|
|
343
|
-
`0.2.0-rc2` preview tag.
|
|
344
|
-
|
|
345
|
-
```bash
|
|
346
|
-
python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace .env
|
|
347
|
-
python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace config.json
|
|
106
|
+
```sh
|
|
107
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
|
|
108
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
|
|
109
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
|
|
110
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py <txid>
|
|
348
111
|
```
|
|
349
112
|
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
and platforms without safe descriptor-relative reads. Exit `0` means a view
|
|
357
|
-
was produced, `2` means refused, and `1` means an internal error. This view
|
|
358
|
-
is for diagnosis only: do not write it back over the original config. It
|
|
359
|
-
does not intercept ordinary file reads made by a harness.
|
|
360
|
-
|
|
361
|
-
### Relationship to delete-guard
|
|
113
|
+
Valuable targets are relocated with exact recovery paths in a manifest.
|
|
114
|
+
Provably regenerable, Git-ignored artifacts may be deleted directly.
|
|
115
|
+
Supported Git overwrites snapshot tracked state; hard-reset collisions with
|
|
116
|
+
untracked/ignored content are refused. Force restore preserves the current
|
|
117
|
+
occupant before replacement. Errors can leave partial work: inspect the
|
|
118
|
+
reported transaction IDs, filesystem and state before retrying.
|
|
362
119
|
|
|
363
|
-
|
|
120
|
+
Advisory `check.py` and `safe_delete.py --dry-run` preserve command targets but
|
|
121
|
+
may write quarantine/audit metadata and a Git local exclude entry. Advisory
|
|
122
|
+
exit 0 is not permission to execute a BLOCK or ASK.
|
|
123
|
+
See the [policy and assessment contract](skills/delete-guard/references/policy.md).
|
|
364
124
|
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
| Response | compensate, then proceed | redact, then emit |
|
|
370
|
-
| Failure cost | recoverable via txid | **irreversible** |
|
|
371
|
-
| Entry point | `check.py -- <command>` | `check_span.py` (stdin) |
|
|
372
|
-
|
|
373
|
-
They share the vocabulary (`core/policy.py`), the aggregation (`worst()`),
|
|
374
|
-
the exemption discipline, and the audit log. `worst()` is shared by both
|
|
375
|
-
guards, which is why `SANITIZE` had to be ranked once, not twice.
|
|
376
|
-
|
|
377
|
-
### Coverage and limitations
|
|
378
|
-
|
|
379
|
-
This is stated plainly, because a reliability tool that overstates its reach
|
|
380
|
-
is a false security claim:
|
|
381
|
-
|
|
382
|
-
- **Not a sandbox.** It does not prevent adversarial exfiltration. An agent
|
|
383
|
-
that obfuscates a secret to evade the scanner is out of scope; this
|
|
384
|
-
catches *accidents*.
|
|
385
|
-
- **Channels with no hook are unreachable by construction.** A hosted model
|
|
386
|
-
call with no proxy, the model's own tool calls, content produced *inside* a
|
|
387
|
-
program, and the human clipboard get **no verdict at all** — no coverage is
|
|
388
|
-
claimed there. See `references/channels.md` and
|
|
389
|
-
[docs/history/secret-guard-analysis.md](docs/history/secret-guard-analysis.md) §2.4 for
|
|
390
|
-
the reachability table this claim is traceable to.
|
|
391
|
-
- **Not a file scanner.** It is not a gitleaks replacement; it scans what the
|
|
392
|
-
guard can see *on the way out*.
|
|
393
|
-
- **No history rewriting.** Detecting a secret already in Git history is a
|
|
394
|
-
report at most. Rewriting history is a human action with its own risks.
|
|
395
|
-
- **No T3 entropy detector in this release.** Random-looking text alone is
|
|
396
|
-
insufficient evidence of a credential; ordinary identifiers stay readable.
|
|
397
|
-
|
|
398
|
-
## Manual, harness-neutral usage
|
|
399
|
-
|
|
400
|
-
The Core has zero third-party dependencies. Requirements: Python 3.9+, POSIX
|
|
401
|
-
shell, and Git.
|
|
402
|
-
|
|
403
|
-
```bash
|
|
404
|
-
# delete something - it is quarantined, not destroyed:
|
|
405
|
-
python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
|
|
406
|
-
|
|
407
|
-
# inspect and undo:
|
|
408
|
-
python3 skills/delete-guard/scripts/status.py
|
|
409
|
-
python3 skills/delete-guard/scripts/status.py --trash-index --root <projects> --json
|
|
410
|
-
python3 skills/delete-guard/scripts/restore.py list
|
|
411
|
-
python3 skills/delete-guard/scripts/restore.py <txid>
|
|
412
|
-
|
|
413
|
-
# quarantine maintenance (dry plan by default):
|
|
414
|
-
python3 skills/delete-guard/scripts/gc.py
|
|
415
|
-
```
|
|
125
|
+
The RC adds quarantine control-path protection, excludes PURGED transactions
|
|
126
|
+
from active GC planning, and minimizes restore/safe_delete audit fields.
|
|
127
|
+
Exact CLI/manifest recovery paths remain available. These changes are not in
|
|
128
|
+
the published 0.2.4 package; see the [RC notes](docs/releases/release-notes-0.2.5-rc1.md).
|
|
416
129
|
|
|
417
|
-
|
|
418
|
-
read-only JSON interface for agents and future UI callers. It reports scoped
|
|
419
|
-
location candidates and layout hints; it neither scans recovery contents nor
|
|
420
|
-
grants cleanup permission. It is included in 0.2.4.
|
|
130
|
+
## Check text before emission
|
|
421
131
|
|
|
422
|
-
|
|
423
|
-
|
|
132
|
+
The payload owner invokes the scanner and applies its decision.
|
|
133
|
+
For a text file:
|
|
424
134
|
|
|
425
|
-
```
|
|
426
|
-
python3 skills/
|
|
427
|
-
|
|
428
|
-
exit 2 → deny
|
|
429
|
-
exit 3 → ask the human if supported; otherwise deny
|
|
430
|
-
exit 1 → guard error; fail closed
|
|
431
|
-
```
|
|
432
|
-
|
|
433
|
-
## What gets protected
|
|
434
|
-
|
|
435
|
-
These examples assume the command reaches the guard and its targets meet the
|
|
436
|
-
stated conditions; see the [capability matrix](docs/guides/harness-capabilities.md)
|
|
437
|
-
for what each host has actually demonstrated.
|
|
438
|
-
|
|
439
|
-
```text
|
|
440
|
-
rm -rf build/ → RELOCATE (tree quarantined, command proceeds)
|
|
441
|
-
rm -rf . → BLOCK (workspace root)
|
|
442
|
-
rm -rf $DIR/ → BLOCK (unresolvable target: fail closed)
|
|
443
|
-
rm *.log → BLOCK (opaque glob; safe_delete expands it)
|
|
444
|
-
cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
|
|
445
|
-
touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
|
|
446
|
-
git clean -fd → RELOCATE (enumerate via -n, relocate, proceed)
|
|
447
|
-
git reset --hard → SNAPSHOT (collision preflight + tracked snapshot)
|
|
448
|
-
reset with collisions → BLOCK (preserve untracked/ignored paths first)
|
|
449
|
-
git push --force → BLOCK (remote history is never automated)
|
|
450
|
-
node_modules/ (ignored) → ALLOW (provably regenerable)
|
|
451
|
-
quarantine full → BLOCK (never fall back to permanent delete)
|
|
135
|
+
```sh
|
|
136
|
+
python3 skills/exfil-guard/scripts/check_span.py --channel file-write --json < draft.md
|
|
137
|
+
python3 skills/exfil-guard/scripts/sanitize.py --channel file-write < draft.md
|
|
452
138
|
```
|
|
453
139
|
|
|
454
|
-
|
|
140
|
+
A complete synthetic credential example is generated at runtime:
|
|
455
141
|
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
[](docs/reports/test-report-claude-code-harness.md)
|
|
461
|
-
[](docs/reports/test-report-kimi-code-block.md)
|
|
462
|
-
[](docs/reports/test-report-workbuddy-windows-core.md)
|
|
463
|
-
[](docs/releases/release-notes-0.2.3-rc1.md#focused-windows-ci)
|
|
464
|
-
[](docs/reports/test-report-release-readiness-0.2.3.md)
|
|
142
|
+
```sh
|
|
143
|
+
python3 -c 'print("config: sk-proj-" + "AbCdEf0123456789GhIjKl")' |
|
|
144
|
+
python3 skills/exfil-guard/scripts/sanitize.py --channel file-write
|
|
145
|
+
```
|
|
465
146
|
|
|
466
|
-
|
|
467
|
-
|
|
147
|
+
The expected output is `config: sk-<REDACTED>`. The checker returns a
|
|
148
|
+
decision and plan; it never rewrites the payload. Its exit 0 means
|
|
149
|
+
ALLOW/SANITIZE assessment, while the sanitizer's successful stdout is the
|
|
150
|
+
allowed or rewritten text. ASK/BLOCK/error withholds sanitizer payload output.
|
|
468
151
|
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
152
|
+
Detection covers documented credential shapes, value-free secret references
|
|
153
|
+
and selected host paths. It is not a general repository scanner or protection
|
|
154
|
+
against deliberate obfuscation. The text CLIs do not automatically append
|
|
155
|
+
egress audit events; a trusted integration owns emission and any audit storage.
|
|
156
|
+
For configuration inspection, an explicit safe view reports supported
|
|
157
|
+
JSON/dotenv structure without scalar values; it is not an editable copy or
|
|
158
|
+
automatic read interception.
|
|
472
159
|
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
| **DSH 0.1.5-rc.1** | [Native pre-execute adapter](adapters/dsh/README.md) | [Real-host packaged-plugin probe](docs/reports/test-report-dsh-0.1.5-rc.1.md): execution-level `BLOCK` and loaded-adapter Core failure. A [real-model Lab baseline](docs/reports/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. |
|
|
477
|
-
| **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/reports/test-report-dsh-read-redaction.md): next request and durable JSONL. [Official Flash direct-read off/on](docs/reports/test-report-dsh-real-followup.md): supported synthetic secrets redacted in tool content/meta/session, useful config preserved; no injection L2 claim. |
|
|
478
|
-
| **DSH 0.2.0-rc.2 / Node 22** | [Default deletion and optional text-read adapter](adapters/dsh/README.md) | [Fresh contract review](docs/reports/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. |
|
|
479
|
-
| **Codex CLI 0.154.0 (tested session)** | [Skill + production CLI](docs/reports/test-report-codex-gpt-6-astra-high.md) | Older-source cooperative acceptance; no native hook claim. |
|
|
480
|
-
| **WorkBuddy (version not recorded; Windows 11)** | [Core / CLI](docs/reports/test-report-workbuddy-windows-core.md) | Community feedback on 0.2.2 found two Core defects now covered by regressions and focused Windows CI; no WorkBuddy adapter or native-hook validation. |
|
|
481
|
-
| **ZCode (version unrecorded; win32)** | [Historical Skill/CLI + hook trial](docs/reports/test-report-zcode-glm-flash.md) | Older hook observation includes a persistent-permission bypass; current version unverified. |
|
|
482
|
-
| **Kimi Code 0.42.0 / 2.1.1** | [Native `PreToolUse` for Bash](adapters/kimi-code/README.md) | [Bounded tests](docs/reports/test-report-kimi-code-block.md): authenticated 2.1.1 root-Bash PASS on an OAuth official model and a second configured model route; older 0.42.0 root/child BLOCK, ASK denial and Python-failure refusal. Hook absence/timeout remains fail-open. |
|
|
483
|
-
| **Other / unlisted hosts** | [Self-adaptation guide](adapters/INTEGRATION.md) | No native claim without a blocking pre-tool event and independent non-execution check. |
|
|
484
|
-
|
|
485
|
-
For agent-led setup: identify the actual host version and tool names, follow
|
|
486
|
-
the matching guide above, preserve existing settings, then report separate
|
|
487
|
-
configuration, local-probe, and real-host evidence. For an unlisted host,
|
|
488
|
-
follow the [self-adaptation checklist](adapters/INTEGRATION.md); a prompt or
|
|
489
|
-
adapter exit code alone is not proof of interception. Ask before changing
|
|
490
|
-
user-wide settings, security policy, or dependencies.
|
|
491
|
-
|
|
492
|
-
`tests/test_conformance.py` checks the shared Core and Claude adapter; DSH
|
|
493
|
-
has a smoke test and Kimi has targeted adapter tests. The Kimi observations
|
|
494
|
-
above cover only the tested calls, not every shell construct or a general
|
|
495
|
-
concurrent-agent safety guarantee.
|
|
496
|
-
Run `python3 doctor.py kimi --probe` or `python3 doctor.py claude --probe`
|
|
497
|
-
to check a selected configuration file and the local shell bridge without a
|
|
498
|
-
model call. Add `--json` for machine-readable `configuration`, `local_probe`,
|
|
499
|
-
and `host_interception` statuses. The last status is always `UNVERIFIED`:
|
|
500
|
-
this doctor cannot prove that a live session loaded or enforced the hook.
|
|
501
|
-
Add `--check-drift` to query the local host version and compute privacy-safe
|
|
502
|
-
configuration/runtime fingerprints. It reports `CURRENT`, `STALE`,
|
|
503
|
-
`DRIFTED`, `BROKEN`, or `UNVERIFIED`; even `CURRENT` is static preflight
|
|
504
|
-
evidence, not interception proof. Optional create-new baselines contain only
|
|
505
|
-
the parsed version and SHA-256 fingerprints. See the
|
|
506
|
-
[host drift guide](docs/guides/host-drift.md) for the status and baseline contract.
|
|
507
|
-
An explicit `--live-sentinel` can then spend one configured model call in a
|
|
508
|
-
private blank fixture. It reports `PASS`, `FAIL`, or `INCONCLUSIVE` with
|
|
509
|
-
`NONE`/`NOTICE`, `CRITICAL`, or `WARNING`; marker absence alone never passes.
|
|
510
|
-
It retains a hashed/redacted result but not raw model output. This is a
|
|
511
|
-
reliability probe for a trusted provider, not a sandbox for a malicious model.
|
|
512
|
-
The optional Kimi doctor needs Python 3.11+ for TOML parsing; the Core and
|
|
513
|
-
hook adapter continue to support Python 3.9+.
|
|
514
|
-
See the [Kimi](adapters/kimi-code/README.md) and
|
|
515
|
-
[Claude](adapters/claude/README.md) adapter guides.
|
|
516
|
-
See [harness capabilities and evidence levels](docs/guides/harness-capabilities.md)
|
|
517
|
-
for the per-host scope and execution-level acceptance criteria.
|
|
518
|
-
|
|
519
|
-
## Repository layout
|
|
160
|
+
Read the [Skill](skills/exfil-guard/SKILL.md),
|
|
161
|
+
[rules and exemption diagnostics](skills/exfil-guard/references/rules.md), and
|
|
162
|
+
[channel contract](skills/exfil-guard/references/channels.md).
|
|
520
163
|
|
|
521
|
-
|
|
522
|
-
agent-guard/
|
|
523
|
-
├── skills/delete-guard/ # agent-facing skill: SKILL.md + CLI scripts
|
|
524
|
-
├── skills/exfil-guard/ # egress skill: check_span.py · sanitize.py
|
|
525
|
-
├── skills/recovery-audit/ # evidence-led repository audit and recovery
|
|
526
|
-
├── core/ # classifier · policy · recovery · audit · redaction
|
|
527
|
-
├── doctor.py # local configuration, probes, and drift preflight
|
|
528
|
-
├── live_sentinel.py # opt-in real-host sentinel and alarm evidence
|
|
529
|
-
├── guard_lab.py # user-controlled offline synthetic honeytoken lab
|
|
530
|
-
├── adapters/INTEGRATION.md # checklist for an unlisted host
|
|
531
|
-
├── adapters/claude/ # Claude Code PreToolUse hook adapter
|
|
532
|
-
├── adapters/kimi-code/ # Kimi Code PreToolUse hook adapter
|
|
533
|
-
├── adapters/dsh/ # DeepSeek Harness integration bridge
|
|
534
|
-
├── adapters/codex/harness/# CLI acceptance driver; not a native hook
|
|
535
|
-
├── tests/ # unittest suites incl. cross-harness conformance
|
|
536
|
-
└── docs/ # guides · design · Lab · reports · releases · history
|
|
537
|
-
```
|
|
538
|
-
|
|
539
|
-
Skills guide agent behavior; constraints live in Core. Future
|
|
540
|
-
`git-guard`, `database-guard`, `cloud-guard` skills plug into the same
|
|
541
|
-
compensation engine without restructuring.
|
|
164
|
+
<a id="integration-and-validation-matrix"></a>
|
|
542
165
|
|
|
543
|
-
##
|
|
166
|
+
## Connect your coding agent
|
|
544
167
|
|
|
545
|
-
|
|
546
|
-
|
|
168
|
+
These are version-specific historical observations. They do not certify a
|
|
169
|
+
new source candidate, every tool or every subagent path.
|
|
547
170
|
|
|
548
|
-
|
|
|
171
|
+
| Host | Integration and evidence |
|
|
172
|
+
|---|---|
|
|
173
|
+
| Claude Code | Native Bash `PreToolUse`; sampled 2.1.270/2.1.273 scripted-host enforcement. [Setup](adapters/claude/README.md) |
|
|
174
|
+
| Kimi Code | Native Bash `PreToolUse`; bounded 0.42.0 root/child and 2.1.1 root-Bash observations. ASK is denied; missing/timed-out hooks remain uncovered. [Setup](adapters/kimi-code/README.md) |
|
|
175
|
+
| DSH | Reviewed 0.1.5-rc.1/0.2.0-rc.2 deletion paths; optional complete text-read protection is default off. Sampled PTC Bash refusal does not imply universal PTC mediation. [Setup](adapters/dsh/README.md) |
|
|
176
|
+
| Codex / other hosts | Explicit Skill/CLI is usable. Native interception needs a verified blocking hook. [Adaptation guide](adapters/INTEGRATION.md) |
|
|
177
|
+
|
|
178
|
+
Use the [full capability and evidence matrix](docs/guides/harness-capabilities.md)
|
|
179
|
+
for precise versions, tests and gaps. `doctor.py kimi|claude --probe` checks a
|
|
180
|
+
selected configuration and local adapter path; PASS does not prove a live
|
|
181
|
+
host loaded the hook. Drift checks are local preflight. A live sentinel is
|
|
182
|
+
explicit, may consume provider quota, and covers only its sampled root Bash
|
|
183
|
+
call. See the [host drift guide](docs/guides/host-drift.md).
|
|
184
|
+
|
|
185
|
+
## Decisions, recovery and documentation
|
|
186
|
+
|
|
187
|
+
The shared protocol is `ALLOW · SANITIZE · RELOCATE · SNAPSHOT · ASK · BLOCK`,
|
|
188
|
+
with stable reason codes and explanations.
|
|
189
|
+
Aggregation is `BLOCK > ASK > RELOCATE/SNAPSHOT > SANITIZE > ALLOW`.
|
|
190
|
+
Opaque targets and protected boundaries are refused; supported recoverable
|
|
191
|
+
mutations compensate before proceeding. Authorization state remains a local
|
|
192
|
+
discipline, not an isolated identity boundary.
|
|
193
|
+
|
|
194
|
+
After an incident, [recovery-audit](skills/recovery-audit/SKILL.md) helps recover
|
|
195
|
+
from surviving Git/session/cache evidence, distinguishing original bytes,
|
|
196
|
+
reconstruction and known gaps. It cannot recreate bytes that no source kept.
|
|
197
|
+
|
|
198
|
+
| Document | Purpose |
|
|
549
199
|
|---|---|
|
|
550
|
-
| [
|
|
551
|
-
| [
|
|
552
|
-
| [
|
|
553
|
-
| [
|
|
554
|
-
| [
|
|
555
|
-
| [
|
|
556
|
-
| [Historical design and findings](docs/README.md#history) | early proposals, friction log and incident exploration |
|
|
557
|
-
| [adapters/INTEGRATION.md](adapters/INTEGRATION.md) | self-adaptation checklist for an unlisted host |
|
|
558
|
-
| [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | evidence hierarchy, deterministic replay, recovery and landing gates |
|
|
559
|
-
| [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | full rule table and decision codes |
|
|
560
|
-
| [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil rule table, reason codes, exemption format, audit shape |
|
|
561
|
-
| [skills/exfil-guard/references/channels.md](skills/exfil-guard/references/channels.md) | egress-channel taxonomy and the unreachable channels |
|
|
562
|
-
|
|
563
|
-
## Status & roadmap
|
|
564
|
-
|
|
565
|
-
**v0.2.4** adds focused recovery maintenance and the trash query
|
|
566
|
-
to 0.2.3. It refuses hard-reset collisions with untracked/ignored content,
|
|
567
|
-
checks restore sources and destinations, and preserves an occupied destination
|
|
568
|
-
before a forced restore. The query supplies a shared CLI/agent/future UI
|
|
569
|
-
contract. Existing text redaction, safe config inspection, offline Lab,
|
|
570
|
-
Claude/Kimi bridges, doctor, host-drift checks and live sentinel remain available.
|
|
571
|
-
The DSH bridge supports the reviewed `0.1.5-rc.1` and `0.2.0-rc.2` contracts;
|
|
572
|
-
its optional text-read protection remains off by default.
|
|
573
|
-
|
|
574
|
-
The [0.2.4 notes](docs/releases/release-notes-0.2.4.md) describe this release's scope.
|
|
575
|
-
The [0.2.3](docs/releases/release-notes-0.2.3.md),
|
|
576
|
-
[rc2](docs/releases/release-notes-0.2.3-rc2.md),
|
|
577
|
-
[rc1](docs/releases/release-notes-0.2.3-rc1.md), and
|
|
578
|
-
[0.2.2](docs/releases/release-notes-0.2.2.md) notes retain their historical scope.
|
|
579
|
-
Check [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
|
|
580
|
-
and npm for published artifacts.
|
|
581
|
-
|
|
582
|
-
The Core and Decision Protocol are shared across harnesses. DSH, Claude and
|
|
583
|
-
Kimi adapters, together with Codex/WorkBuddy/ZCode acceptance records, are documented in
|
|
584
|
-
one compatibility matrix.
|
|
585
|
-
The Kimi result includes sampled hook-compensation and execution-level BLOCK
|
|
586
|
-
paths, not proof that its host enforces every BLOCK or that arbitrary agent
|
|
587
|
-
actions are protected. A tested direct-Python hook startup failure was
|
|
588
|
-
fail-open. The optional shell bridge blocked a sampled Python startup failure
|
|
589
|
-
in a real Kimi host session, but only when the bridge itself ran; config
|
|
590
|
-
validation alone cannot prove that the hook is live.
|
|
591
|
-
The release adds a focused real-Windows Core gate for Issue #7, but native
|
|
592
|
-
cmd/PowerShell execution through every harness and general concurrent-subagent
|
|
593
|
-
safety remain explicit gaps. Later Guard branches (`git-guard`, `database-guard`,
|
|
594
|
-
`cloud-guard`) reuse the same protocol and compensation engine.
|
|
595
|
-
|
|
596
|
-
## guard-lab
|
|
597
|
-
|
|
598
|
-
The opt-in, offline honeytoken Lab uses disposable
|
|
599
|
-
projects and synthetic, non-secret markers. Its `clean`, `mock-positive`,
|
|
600
|
-
`mock-injection`, and `snapshot-positive` controls call no model and make no
|
|
601
|
-
external request. A bounded loopback observer records the fake Lab stub, bait
|
|
602
|
-
URL, or a validated synthetic snapshot; an explicit post-run scan can detect a
|
|
603
|
-
canary in selected output without retaining the raw value.
|
|
604
|
-
|
|
605
|
-
The user keeps the true controller and evidence outside the fixture shown to
|
|
606
|
-
the tested agent. Broken controls or changed evidence produce `INCONCLUSIVE`,
|
|
607
|
-
never an optimistic pass. The Lab cannot observe ordinary file
|
|
608
|
-
reads, prove remote transfer, universally block LLM calls, or resist a same-UID
|
|
609
|
-
adversary. Start with the zero-token controls and read the
|
|
610
|
-
[guard-lab guide](docs/lab/guard-lab.md) before involving a real harness.
|
|
611
|
-
The built-in cases report `CALIBRATION_ONLY`. A separate manual
|
|
612
|
-
`injection-probe` treats bait contact as `EXPOSURE_OBSERVED`, and `compare`
|
|
613
|
-
accepts a mitigation result only after an effective unguarded baseline and a
|
|
614
|
-
matched guarded trial with the same protocol, harness/version/model, group,
|
|
615
|
-
and task hash. Manual real-model runs also require a user-verified completed
|
|
616
|
-
host result, so an exit-0 startup/model failure cannot count as a quiet win.
|
|
617
|
-
A quiet baseline stays `INCONCLUSIVE`; no result is a general model or vendor
|
|
618
|
-
safety rating.
|
|
200
|
+
| [Getting started](docs/guides/getting-started.md) | Package paths, agent setup prompt and safe verification |
|
|
201
|
+
| [Documentation index](docs/README.md) | Guides, design, Lab, reports, releases and history |
|
|
202
|
+
| [Architecture](docs/design/architecture.md) | Shared Core, compensation and adapter flow |
|
|
203
|
+
| [Threat model](docs/design/threat-model.md) | Trust assumptions and unresolved boundaries |
|
|
204
|
+
| [Compatibility](docs/design/compatibility.md) | Interface and release contracts |
|
|
205
|
+
| [0.2.5-rc1 notes](docs/releases/release-notes-0.2.5-rc1.md) | This candidate's changes and validation status |
|
|
619
206
|
|
|
620
207
|
## Contributing
|
|
621
208
|
|
|
622
|
-
Bug reports,
|
|
623
|
-
|
|
624
|
-
[
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
[contribution guide](CONTRIBUTING.md) before sharing logs or test evidence;
|
|
628
|
-
credentials, private configuration, and unredacted incident data must not be
|
|
629
|
-
posted publicly.
|
|
209
|
+
Bug reports, compatibility evidence, documentation fixes and focused code
|
|
210
|
+
changes are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before sharing
|
|
211
|
+
logs. Use [Issues](https://github.com/mokuyoaxis/agent-guard/issues) and
|
|
212
|
+
[Pull Requests](https://github.com/mokuyoaxis/agent-guard/pulls); keep credentials,
|
|
213
|
+
private configuration and unredacted incident records out of public reports.
|
|
630
214
|
|
|
631
215
|
## Community
|
|
632
216
|
|