@mokuyoaxis/agent-guard 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +101 -0
- package/LICENSE +21 -0
- package/README.md +558 -0
- package/README.zh-CN.md +488 -0
- package/adapters/INTEGRATION.md +94 -0
- package/adapters/claude/README.md +141 -0
- package/adapters/claude/compatibility.json +17 -0
- package/adapters/claude/harness/README.md +59 -0
- package/adapters/claude/harness/mock_anthropic_api.mjs +47 -0
- package/adapters/claude/harness/run_scenario.sh +79 -0
- package/adapters/claude/harness/run_scenario_no_python3.sh +49 -0
- package/adapters/claude/hook_bridge.sh +33 -0
- package/adapters/claude/pre_tool_use.py +264 -0
- package/adapters/claude/settings.example.json +16 -0
- package/adapters/codex/harness/README.md +53 -0
- package/adapters/codex/harness/acceptance.py +226 -0
- package/adapters/dsh/README.md +62 -0
- package/adapters/dsh/cordis.patch.yml +30 -0
- package/adapters/dsh/lib/index.js +500 -0
- package/adapters/kimi-code/README.md +169 -0
- package/adapters/kimi-code/compatibility.json +17 -0
- package/adapters/kimi-code/config.example.toml +26 -0
- package/adapters/kimi-code/hook_bridge.sh +32 -0
- package/adapters/kimi-code/pre_tool_use.py +72 -0
- package/core/__init__.py +47 -0
- package/core/audit.py +86 -0
- package/core/classifier.py +1175 -0
- package/core/dialects.py +898 -0
- package/core/policy.py +817 -0
- package/core/recovery.py +700 -0
- package/core/redaction.py +1096 -0
- package/core/safe_view.py +212 -0
- package/docs/architecture.md +223 -0
- package/docs/compatibility.md +142 -0
- package/docs/development-note-unguarded-deletion.md +187 -0
- package/docs/friction.md +266 -0
- package/docs/harness-capabilities.md +72 -0
- package/docs/host-drift.md +142 -0
- package/docs/publishing-from-ephemeral-environments.md +104 -0
- package/docs/release-notes-0.2.0-rc1.md +46 -0
- package/docs/release-notes-0.2.0.md +72 -0
- package/docs/release-notes-0.2.1.md +78 -0
- package/docs/release-notes-0.2.2.md +120 -0
- package/docs/secret-guard-analysis.md +416 -0
- package/docs/secret-guard-architecture.md +93 -0
- package/docs/secret-guard-design.md +649 -0
- package/docs/test-report-claude-code-harness.md +462 -0
- package/docs/test-report-codex-gpt-5.6-sol.md +335 -0
- package/docs/test-report-codex-gpt-6-astra-high.md +129 -0
- package/docs/test-report-dsh-0.1.5-rc.1.md +84 -0
- package/docs/test-report-dsh-v0.1.1.md +126 -0
- package/docs/test-report-kimi-code-block.md +198 -0
- package/docs/test-report-zcode-glm-flash.md +241 -0
- package/docs/threat-model.md +44 -0
- package/doctor.py +756 -0
- package/live_sentinel.py +339 -0
- package/package.json +69 -0
- package/skills/delete-guard/SKILL.md +109 -0
- package/skills/delete-guard/agents/openai.yaml +4 -0
- package/skills/delete-guard/references/policy.md +161 -0
- package/skills/delete-guard/scripts/_bootstrap.py +8 -0
- package/skills/delete-guard/scripts/check.py +370 -0
- package/skills/delete-guard/scripts/gc.py +103 -0
- package/skills/delete-guard/scripts/restore.py +98 -0
- package/skills/delete-guard/scripts/safe_delete.py +256 -0
- package/skills/delete-guard/scripts/status.py +130 -0
- package/skills/exfil-guard/SKILL.md +143 -0
- package/skills/exfil-guard/agents/openai.yaml +4 -0
- package/skills/exfil-guard/references/channels.md +58 -0
- package/skills/exfil-guard/references/rules.md +194 -0
- package/skills/exfil-guard/scripts/_bootstrap.py +8 -0
- package/skills/exfil-guard/scripts/check_span.py +250 -0
- package/skills/exfil-guard/scripts/sanitize.py +155 -0
- package/skills/exfil-guard/scripts/view.py +44 -0
- package/skills/recovery-audit/SKILL.md +283 -0
- package/skills/recovery-audit/agents/openai.yaml +4 -0
- package/skills/recovery-audit/references/evidence-records.md +85 -0
package/README.md
ADDED
|
@@ -0,0 +1,558 @@
|
|
|
1
|
+
# AGENT-GUARD
|
|
2
|
+
|
|
3
|
+
[](https://github.com/mokuyoaxis/agent-guard/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](https://www.python.org/)
|
|
7
|
+
[](https://github.com/mokuyoaxis/agent-guard/releases)
|
|
8
|
+
|
|
9
|
+
**Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
|
|
10
|
+
|
|
11
|
+
Agent Guard is a reliability layer for coding agents. It makes supported
|
|
12
|
+
high-impact actions recoverable instead of permanently destructive, while
|
|
13
|
+
keeping routine work automatic.
|
|
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
|
+
|
|
23
|
+
The Core is harness-neutral and supports Python 3.9+ and Git. Automatic
|
|
24
|
+
interception still depends on whether the host exposes a compatible hook; a
|
|
25
|
+
Skill by itself does not intercept tool calls. The shared Core, Decision
|
|
26
|
+
Protocol, and Skills define the product; harness adapters are replaceable
|
|
27
|
+
integration bridges rather than the product boundary.
|
|
28
|
+
|
|
29
|
+
> **Agent Guard keeps reversible actions automatic and escalates only when it
|
|
30
|
+
> cannot safely automate them.** It is reliability infrastructure, not a
|
|
31
|
+
> security sandbox: it protects against mistakes, not a malicious agent with
|
|
32
|
+
> equal OS privileges.
|
|
33
|
+
|
|
34
|
+
## What it looks like
|
|
35
|
+
|
|
36
|
+
```text
|
|
37
|
+
rm -rf build/ → RELOCATE # an in-scope tree moves to quarantine
|
|
38
|
+
rm -rf . → BLOCK # the workspace root is protected
|
|
39
|
+
git reset --hard → SNAPSHOT # snapshot first when Git state supports it
|
|
40
|
+
git push --force → BLOCK # remote history is not automated
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
These are illustrative verdicts for supported inputs, not commands to run or
|
|
44
|
+
proof that every harness intercepts them. Ignored, regenerable targets may be
|
|
45
|
+
`ALLOW`; a Git snapshot that cannot be made fails closed. When recovery or safe
|
|
46
|
+
rewriting is possible, the agent can keep working. Otherwise, the guard asks
|
|
47
|
+
the human or blocks the operation.
|
|
48
|
+
|
|
49
|
+
## Quick start with your coding agent
|
|
50
|
+
|
|
51
|
+
Use the scoped npm package after it is available in the registry, or keep a
|
|
52
|
+
stable Git checkout. Never substitute the unrelated unscoped `agent-guard`
|
|
53
|
+
package.
|
|
54
|
+
|
|
55
|
+
Pinned npm installation into a stable, user-owned prefix:
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.2
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The package root is then
|
|
62
|
+
`/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
|
|
63
|
+
Alternatively, clone the source (skip this if you already have a checkout):
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
git clone https://github.com/mokuyoaxis/agent-guard.git
|
|
67
|
+
cd agent-guard
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Python 3.9+ and Git are required for the Core; native interception depends on
|
|
71
|
+
the host's hook support. Then give your coding agent the following setup prompt
|
|
72
|
+
(replace the path with your checkout):
|
|
73
|
+
|
|
74
|
+
```text
|
|
75
|
+
Set up agent-guard for this workspace. Use either an existing Git checkout or
|
|
76
|
+
the exact scoped npm package @mokuyoaxis/agent-guard@0.2.2; never install the
|
|
77
|
+
unscoped package named agent-guard. Before installing, ask me to choose and
|
|
78
|
+
approve a stable user-owned prefix. Treat the checkout or installed package
|
|
79
|
+
root as /absolute/path/to/agent-guard below.
|
|
80
|
+
First identify the current harness and its actual hook/skill capabilities;
|
|
81
|
+
read this README and the matching adapter README. Check Python and Git.
|
|
82
|
+
Install the relevant Skills, then configure a native shell hook only if this
|
|
83
|
+
harness supports one. Preserve existing settings and show me the proposed
|
|
84
|
+
diff before editing user-wide configuration or installing dependencies.
|
|
85
|
+
For Claude Code use adapters/claude/README.md; for Kimi Code use
|
|
86
|
+
adapters/kimi-code/README.md; for DSH use adapters/dsh/README.md.
|
|
87
|
+
For another host, read adapters/INTEGRATION.md and do not invent a native
|
|
88
|
+
hook. If no blocking pre-tool hook is verified, use only Skill/CLI and say
|
|
89
|
+
plainly that automatic interception is not enabled.
|
|
90
|
+
Verify a harmless command and pass a BLOCK-shaped command only as data to
|
|
91
|
+
check.py; never execute a destructive test command. For Claude/Kimi, run the
|
|
92
|
+
local doctor but do not treat its PASS as proof of host interception. Report
|
|
93
|
+
the host version, tool coverage, what was installed, what the host actually
|
|
94
|
+
intercepted, and any unverified paths.
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
For manual setup and evidence limits, see the
|
|
98
|
+
[adapter matrix](docs/harness-capabilities.md) and the adapter README for your
|
|
99
|
+
host.
|
|
100
|
+
|
|
101
|
+
## Design principles
|
|
102
|
+
|
|
103
|
+
| Principle | Guarantee |
|
|
104
|
+
|---|---|
|
|
105
|
+
| **Stay in scope** | The guard blocks deletion of the workspace root, `.git`, and outside paths when the operation reaches it |
|
|
106
|
+
| **Make it recoverable** | Supported deletions relocate to `.agent-trash/` with a manifest; destructive Git overwrites snapshot first |
|
|
107
|
+
| **Constrain authorization** | Authorization is session-scoped; a veto downgrades one-way, and only a human restores it |
|
|
108
|
+
| **Leave a durable trail** | Enforced verdicts, compensation intents, outcomes, and restores use append-only JSONL; mutation fails closed if its intent cannot be stored |
|
|
109
|
+
|
|
110
|
+
One rule runs through all four: **uncertainty increases restriction.**
|
|
111
|
+
|
|
112
|
+
## How it decides
|
|
113
|
+
|
|
114
|
+
Each inspected operation is classified by its effect and then mapped to the
|
|
115
|
+
least restrictive decision that preserves the relevant safety or recovery
|
|
116
|
+
guarantee. The stable interface is a Decision Protocol, not a binary
|
|
117
|
+
allow/block check:
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
Effect → Classifier → Policy → Decision ∈ { ALLOW, SANITIZE, RELOCATE,
|
|
121
|
+
SNAPSHOT, ASK, BLOCK }
|
|
122
|
+
+ ReasonCode (stable, machine-readable)
|
|
123
|
+
+ Explanation (human-facing)
|
|
124
|
+
+ RecoveryPlan (txids, strategy)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
| Tier | Decisions | What the agent experiences |
|
|
128
|
+
|---|---|---|
|
|
129
|
+
| **SAFE** | `ALLOW` · `SANITIZE` · `RELOCATE` · `SNAPSHOT` | Runs silently; compensation is applied first where needed; recoverable mutations are restorable via txid. `SANITIZE` returns a plan for the *payload owner* to rewrite (not a command rewrite) |
|
|
130
|
+
| **AMBIGUOUS** | `ASK` | Single-execution authorization (`ASK_ONCE`) — e.g. compound shapes the guard cannot safely automate |
|
|
131
|
+
| **FORBIDDEN** | `BLOCK` | Refused with reason and remediation; never askable |
|
|
132
|
+
|
|
133
|
+
Precedence when several decisions meet in one operation, weakest to strongest:
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
ALLOW < SANITIZE < RELOCATE < SNAPSHOT < ASK < BLOCK
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
`SANITIZE` ranks *below* `ASK` deliberately: it is automatic (SAFE tier),
|
|
140
|
+
while `ASK` forfeits automation. A payload carrying both a sanitizable secret
|
|
141
|
+
and a shape that cannot be rewritten must `ASK` — you cannot silently proceed
|
|
142
|
+
when part of the emission is uninspectable.
|
|
143
|
+
|
|
144
|
+
True effect uncertainty (`$VAR` targets, `bash -c`, `find -delete`, stdin-fed
|
|
145
|
+
lists) stays on the BLOCK path: allowing it would forfeit the core guarantee.
|
|
146
|
+
Adapters map decisions onto their harness natively — DSH `PreToolDecision`,
|
|
147
|
+
Claude Code PreToolUse `ask`, or a deny carrying the explanation where no ask
|
|
148
|
+
exists.
|
|
149
|
+
|
|
150
|
+
## What Agent Guard includes
|
|
151
|
+
|
|
152
|
+
### `delete-guard`
|
|
153
|
+
|
|
154
|
+
Answers *"if this destroys something, can we come back?"* It runs before a
|
|
155
|
+
delete or destructive Git action when invoked through a supported adapter or
|
|
156
|
+
CLI, and compensates first when recovery is possible.
|
|
157
|
+
|
|
158
|
+
### `exfil-guard`
|
|
159
|
+
|
|
160
|
+
Answers *"if this leaves the machine, was it supposed to?"* Its cooperative
|
|
161
|
+
CLI checks text before an emission when the payload owner invokes it, returning
|
|
162
|
+
a redaction or escalation decision for supported patterns.
|
|
163
|
+
|
|
164
|
+
### `recovery-audit`
|
|
165
|
+
|
|
166
|
+
The incident-response companion for cases where prevention never ran or did not
|
|
167
|
+
cover the path. It establishes source precedence, distinguishes recovered bytes
|
|
168
|
+
from reconstructed behavior and known gaps, audits replay tooling, and keeps
|
|
169
|
+
landing, commit, push, and release as separate authorization gates.
|
|
170
|
+
|
|
171
|
+
`delete-guard` and `exfil-guard` are the two preventive guard branches;
|
|
172
|
+
`recovery-audit` handles evidence-led recovery after the fact.
|
|
173
|
+
|
|
174
|
+
## recovery-audit
|
|
175
|
+
|
|
176
|
+
Sometimes prevention never ran: a harness had no adapter, a subagent bypassed
|
|
177
|
+
the expected path, or an over-broad command removed the workspace before anyone
|
|
178
|
+
could intervene. The working tree may be gone while the coding agent's session
|
|
179
|
+
cache still preserves successful patches, file snapshots, tool results, diffs,
|
|
180
|
+
and command context.
|
|
181
|
+
|
|
182
|
+
`recovery-audit` turns those remnants, Git remotes/reflogs/stashes, editor or
|
|
183
|
+
tool caches, build artifacts, and project plans into an evidence-led recovery:
|
|
184
|
+
|
|
185
|
+
- every unit is labelled **recovered**, **reconstructed**, or **missing**;
|
|
186
|
+
- recorded tool effects are replayed in chronology and checked for divergence;
|
|
187
|
+
- repeated replay must produce a byte-identical tree;
|
|
188
|
+
- landing, commit, push, and release remain separate authorization gates.
|
|
189
|
+
|
|
190
|
+
It is not filesystem undelete and cannot recreate bytes no surviving source
|
|
191
|
+
captured. Its promise is a fast, auditable path to the strongest project state
|
|
192
|
+
the evidence actually supports, with gaps reported instead of hidden.
|
|
193
|
+
|
|
194
|
+
## exfil-guard
|
|
195
|
+
|
|
196
|
+
`exfil-guard` checks text before an agent writes, sends, commits, or pushes it
|
|
197
|
+
**when the payload owner calls its CLI**. It also offers an explicit, read-only
|
|
198
|
+
safe view of selected JSON/dotenv configuration files. The text scanner is
|
|
199
|
+
designed to catch two accidental disclosure classes: **known credentials**
|
|
200
|
+
and **host-identifying absolute paths**. Depending on the channel, it can
|
|
201
|
+
allow the payload, return a redaction plan, ask for a human decision, or block
|
|
202
|
+
the emission.
|
|
203
|
+
|
|
204
|
+
It is a prevention and redaction guard, not a compensation engine: after an
|
|
205
|
+
emission there is nothing to recover. It is also **not a security sandbox** and
|
|
206
|
+
does not attempt to stop adversarial exfiltration by an agent with equal OS
|
|
207
|
+
privileges.
|
|
208
|
+
|
|
209
|
+
### Decisions exfil-guard can return
|
|
210
|
+
|
|
211
|
+
The full Decision Protocol applies, but only four classes are reachable for
|
|
212
|
+
a text payload (`RELOCATE`/`SNAPSHOT` belong to delete-guard — the guard
|
|
213
|
+
cannot rewrite what it did not write):
|
|
214
|
+
|
|
215
|
+
| Decision | Meaning | Example |
|
|
216
|
+
|---|---|---|
|
|
217
|
+
| `ALLOW` | nothing matched, a documented placeholder, or a workspace-relative path | `echo "hello" \| check_span.py` |
|
|
218
|
+
| `SANITIZE` | a redaction plan is returned; the *payload owner* rewrites and emits | a real key on `file-write` / `llm-request` |
|
|
219
|
+
| `ASK` | the channel cannot be rewritten and cannot be taken back | a host path on `shell-stdout` |
|
|
220
|
+
| `BLOCK` | refuse: immutable/remote history, an un-scannable payload, invalid config | a credential in `git-push-payload` |
|
|
221
|
+
|
|
222
|
+
### What is detected
|
|
223
|
+
|
|
224
|
+
**T1 vendor credential patterns** (`secret/*`, deterministic, near-zero
|
|
225
|
+
false positives). Rule ids: `secret/openai-key`, `secret/github-token`,
|
|
226
|
+
`secret/aws-access-key-id`, `secret/gitlab-token`, `secret/slack-token`,
|
|
227
|
+
`secret/stripe-key` (live keys only — `sk_test_` is exempt), `secret/jwt`
|
|
228
|
+
(structural: the header must base64-decode to JSON containing `alg`), and
|
|
229
|
+
`secret/private-key-block` (whole `-----BEGIN ... PRIVATE KEY-----` block,
|
|
230
|
+
redacted in one piece). See
|
|
231
|
+
[skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md)
|
|
232
|
+
for the frozen table.
|
|
233
|
+
|
|
234
|
+
**Value-free secret references** (`secret/source-reference`). The guard
|
|
235
|
+
classifies an environment variable's *name* (`*KEY*`, `*TOKEN*`,
|
|
236
|
+
`*SECRET*`, `*PASSWORD*`, `*CRED*`, `*AUTH*`) and a secret-store *file name*
|
|
237
|
+
(`.env`, `*.pem`, `id_rsa*`, `.netrc`, `kubeconfig`, ...), and detects
|
|
238
|
+
whole-environment expansions (`printenv`, `env | ...`, `cat
|
|
239
|
+
/proc/self/environ`). This scanner **does not resolve the variable value**;
|
|
240
|
+
that does not certify unrelated Guard output or existing audit records as
|
|
241
|
+
secret-free.
|
|
242
|
+
|
|
243
|
+
**Host-identifying paths** (`path/*`). `path/workspace-relative` is `ALLOW`
|
|
244
|
+
(the workspace is exempt); `path/system` (`/usr`, `/etc`, `C:\Windows`) is
|
|
245
|
+
`ALLOW`; `path/host-absolute` (under `HOME`/`TEMP`, a CI root, or a
|
|
246
|
+
workspace ancestor) is `SANITIZE`; `path/generic-absolute` (no host
|
|
247
|
+
correlation) is `ASK`; `path/device` (UNC, `\\?\`, pipes) is `SANITIZE`.
|
|
248
|
+
|
|
249
|
+
### Channels determine the disposition
|
|
250
|
+
|
|
251
|
+
A channel is defined by two facts: can it be **rewritten**, and does the
|
|
252
|
+
emission **persist**? `rewritable` is what makes `SANITIZE` meaningful;
|
|
253
|
+
`persistence` is what justifies `BLOCK`.
|
|
254
|
+
|
|
255
|
+
| Channel | Rewritable | Persistence | Default |
|
|
256
|
+
|---|---|---|---|
|
|
257
|
+
| `llm-request` | yes | remote | SANITIZE |
|
|
258
|
+
| `file-write` | yes | workspace | SANITIZE |
|
|
259
|
+
| `forge-comment` / `issue-body` / `pr-description` | yes | public | SANITIZE |
|
|
260
|
+
| `git-commit-message` | yes (rewrite argv) | remote history | **BLOCK** |
|
|
261
|
+
| `git-push-payload` | no | **remote** | **BLOCK** |
|
|
262
|
+
| `shell-stdout` | **no** | local transcript | ASK |
|
|
263
|
+
| `shell-file-redirect` | yes | local | ASK |
|
|
264
|
+
| `archive-upload` | yes | remote | ASK |
|
|
265
|
+
| `process-argv` | yes | local | ASK |
|
|
266
|
+
|
|
267
|
+
An unknown channel name is a configuration defect, not "no risk":
|
|
268
|
+
`check_span.py` returns `BLOCK_OUTPUT_UNSCANNABLE`, never an implicit ALLOW.
|
|
269
|
+
|
|
270
|
+
### Usage
|
|
271
|
+
|
|
272
|
+
`check_span.py` reads the payload on **stdin** and is a pure function — it
|
|
273
|
+
never writes, never rewrites, and never prints the match. `sanitize.py`
|
|
274
|
+
applies the plan the guard returned.
|
|
275
|
+
|
|
276
|
+
```bash
|
|
277
|
+
# a credential on a rewritable channel -> SANITIZE, exit 0
|
|
278
|
+
echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/check_span.py --channel file-write
|
|
279
|
+
|
|
280
|
+
# a credential bound for remote history -> BLOCK, exit 2
|
|
281
|
+
echo 'token=ghp_abcdefghijklmnopqrstuvwxyz…' | python3 skills/exfil-guard/scripts/check_span.py --channel git-push-payload
|
|
282
|
+
|
|
283
|
+
# apply the redaction plan (format preserved: sk-<REDACTED>)
|
|
284
|
+
echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/sanitize.py --channel file-write
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
Exit code contract: `0` = ALLOW/SANITIZED · `2` = BLOCK · `3` = ASK ·
|
|
288
|
+
`1` = ERROR. Use `--json` for the machine-readable verdict (offsets, rule ids
|
|
289
|
+
and placeholders only — **never the matched bytes**), and `--path` to enable
|
|
290
|
+
the repo-local exemption file for the file being written.
|
|
291
|
+
|
|
292
|
+
### Read a config without printing its values
|
|
293
|
+
|
|
294
|
+
Introduced in the `0.2.0` source; this CLI is **not** in the earlier
|
|
295
|
+
`0.2.0-rc2` preview tag.
|
|
296
|
+
|
|
297
|
+
```bash
|
|
298
|
+
python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace .env
|
|
299
|
+
python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace config.json
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
The path must be relative to that workspace. The JSON output preserves field
|
|
303
|
+
names and structure, plus scalar types and `set`/`empty` states, but **never
|
|
304
|
+
scalar values**. Known secret-shaped field names are hidden; unknown secrets
|
|
305
|
+
in field names remain a limitation. Only UTF-8 JSON and a strict, single-line
|
|
306
|
+
dotenv subset are supported (256 KiB maximum, 16 levels, 2048 nodes). The
|
|
307
|
+
CLI refuses symlinks, hardlinks, special files, unsafe paths, malformed input,
|
|
308
|
+
and platforms without safe descriptor-relative reads. Exit `0` means a view
|
|
309
|
+
was produced, `2` means refused, and `1` means an internal error. This view
|
|
310
|
+
is for diagnosis only: do not write it back over the original config. It
|
|
311
|
+
does not intercept ordinary file reads made by a harness.
|
|
312
|
+
|
|
313
|
+
### Relationship to delete-guard
|
|
314
|
+
|
|
315
|
+
They are two halves of the same promise, on opposite sides of the action:
|
|
316
|
+
|
|
317
|
+
| | `delete-guard` | `exfil-guard` |
|
|
318
|
+
|---|---|---|
|
|
319
|
+
| Question | "can we come back?" | "was this supposed to leave?" |
|
|
320
|
+
| Guards | *before a delete* | *before an emission* |
|
|
321
|
+
| Response | compensate, then proceed | redact, then emit |
|
|
322
|
+
| Failure cost | recoverable via txid | **irreversible** |
|
|
323
|
+
| Entry point | `check.py -- <command>` | `check_span.py` (stdin) |
|
|
324
|
+
|
|
325
|
+
They share the vocabulary (`core/policy.py`), the aggregation (`worst()`),
|
|
326
|
+
the exemption discipline, and the audit log. `worst()` is shared by both
|
|
327
|
+
guards, which is why `SANITIZE` had to be ranked once, not twice.
|
|
328
|
+
|
|
329
|
+
### Coverage and limitations
|
|
330
|
+
|
|
331
|
+
This is stated plainly, because a reliability tool that overstates its reach
|
|
332
|
+
is a false security claim:
|
|
333
|
+
|
|
334
|
+
- **Not a sandbox.** It does not prevent adversarial exfiltration. An agent
|
|
335
|
+
that obfuscates a secret to evade the scanner is out of scope; this
|
|
336
|
+
catches *accidents*.
|
|
337
|
+
- **Channels with no hook are unreachable by construction.** A hosted model
|
|
338
|
+
call with no proxy, the model's own tool calls, content produced *inside* a
|
|
339
|
+
program, and the human clipboard get **no verdict at all** — no coverage is
|
|
340
|
+
claimed there. See `references/channels.md` and
|
|
341
|
+
[docs/secret-guard-analysis.md](docs/secret-guard-analysis.md) §2.4 for
|
|
342
|
+
the reachability table this claim is traceable to.
|
|
343
|
+
- **Not a file scanner.** It is not a gitleaks replacement; it scans what the
|
|
344
|
+
guard can see *on the way out*.
|
|
345
|
+
- **No history rewriting.** Detecting a secret already in Git history is a
|
|
346
|
+
report at most. Rewriting history is a human action with its own risks.
|
|
347
|
+
- **No T3 entropy detector in this release.** It is the single largest
|
|
348
|
+
false-positive source, and the named scenarios do not require it.
|
|
349
|
+
|
|
350
|
+
## Manual, harness-neutral usage
|
|
351
|
+
|
|
352
|
+
The Core has zero third-party dependencies. Requirements: Python 3.9+, POSIX
|
|
353
|
+
shell, and Git.
|
|
354
|
+
|
|
355
|
+
```bash
|
|
356
|
+
# delete something - it is quarantined, not destroyed:
|
|
357
|
+
python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
|
|
358
|
+
|
|
359
|
+
# inspect and undo:
|
|
360
|
+
python3 skills/delete-guard/scripts/status.py
|
|
361
|
+
python3 skills/delete-guard/scripts/restore.py list
|
|
362
|
+
python3 skills/delete-guard/scripts/restore.py <txid>
|
|
363
|
+
|
|
364
|
+
# quarantine maintenance (dry plan by default):
|
|
365
|
+
python3 skills/delete-guard/scripts/gc.py
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
A harness adapter can invoke the guard before a supported shell command and
|
|
369
|
+
map its exit status to the host's own tool decision:
|
|
370
|
+
|
|
371
|
+
```text
|
|
372
|
+
python3 skills/delete-guard/scripts/check.py --enforce -- "$COMMAND"
|
|
373
|
+
exit 0 → host may run the original command
|
|
374
|
+
exit 2 → deny
|
|
375
|
+
exit 3 → ask the human if supported; otherwise deny
|
|
376
|
+
exit 1 → guard error; fail closed
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
## What gets protected
|
|
380
|
+
|
|
381
|
+
These examples assume the command reaches the guard and its targets meet the
|
|
382
|
+
stated conditions; see the [capability matrix](docs/harness-capabilities.md)
|
|
383
|
+
for what each host has actually demonstrated.
|
|
384
|
+
|
|
385
|
+
```text
|
|
386
|
+
rm -rf build/ → RELOCATE (tree quarantined, command proceeds)
|
|
387
|
+
rm -rf . → BLOCK (workspace root)
|
|
388
|
+
rm -rf $DIR/ → BLOCK (unresolvable target: fail closed)
|
|
389
|
+
rm *.log → BLOCK (opaque glob; safe_delete expands it)
|
|
390
|
+
cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
|
|
391
|
+
touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
|
|
392
|
+
git clean -fd → RELOCATE (enumerate via -n, relocate, proceed)
|
|
393
|
+
git reset --hard → SNAPSHOT (when a Git snapshot can be made)
|
|
394
|
+
git push --force → BLOCK (remote history is never automated)
|
|
395
|
+
node_modules/ (ignored) → ALLOW (provably regenerable)
|
|
396
|
+
quarantine full → BLOCK (never fall back to permanent delete)
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
## Integration and validation matrix
|
|
400
|
+
|
|
401
|
+
[](.github/workflows/ci.yml)
|
|
402
|
+
[](docs/test-report-codex-gpt-6-astra-high.md)
|
|
403
|
+
[](docs/test-report-dsh-0.1.5-rc.1.md)
|
|
404
|
+
[](docs/test-report-zcode-glm-flash.md)
|
|
405
|
+
[](docs/test-report-claude-code-harness.md)
|
|
406
|
+
[](docs/test-report-kimi-code-block.md)
|
|
407
|
+
|
|
408
|
+
"The Core works", "a Skill-guided agent used it", and "the harness
|
|
409
|
+
intercepts every matching tool call" are separate claims. This table keeps
|
|
410
|
+
those evidence levels explicit:
|
|
411
|
+
|
|
412
|
+
| Harness / tested version | Integration path | Evidence and limit |
|
|
413
|
+
|---|---|---|
|
|
414
|
+
| **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, no-model packaged-plugin probe](docs/test-report-dsh-0.1.5-rc.1.md): benign execution, execution-level `BLOCK`, absent bypass marker and loaded-adapter Core failure; model/Agent and non-`bash` paths unverified. |
|
|
416
|
+
| **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
|
+
| **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
|
+
| **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. |
|
|
419
|
+
| **Other / unlisted hosts** | [Self-adaptation guide](adapters/INTEGRATION.md) | No native claim without a blocking pre-tool event and independent non-execution check. |
|
|
420
|
+
|
|
421
|
+
For agent-led setup: identify the actual host version and tool names, follow
|
|
422
|
+
the matching guide above, preserve existing settings, then report separate
|
|
423
|
+
configuration, local-probe, and real-host evidence. For an unlisted host,
|
|
424
|
+
follow the [self-adaptation checklist](adapters/INTEGRATION.md); a prompt or
|
|
425
|
+
adapter exit code alone is not proof of interception. Ask before changing
|
|
426
|
+
user-wide settings, security policy, or dependencies.
|
|
427
|
+
|
|
428
|
+
`tests/test_conformance.py` checks the shared Core and Claude adapter; DSH
|
|
429
|
+
has a smoke test and Kimi has targeted adapter tests. The Kimi observations
|
|
430
|
+
above cover only the tested calls, not every shell construct or a general
|
|
431
|
+
concurrent-agent safety guarantee.
|
|
432
|
+
Run `python3 doctor.py kimi --probe` or `python3 doctor.py claude --probe`
|
|
433
|
+
to check a selected configuration file and the local shell bridge without a
|
|
434
|
+
model call. Add `--json` for machine-readable `configuration`, `local_probe`,
|
|
435
|
+
and `host_interception` statuses. The last status is always `UNVERIFIED`:
|
|
436
|
+
this doctor cannot prove that a live session loaded or enforced the hook.
|
|
437
|
+
Add `--check-drift` to query the local host version and compute privacy-safe
|
|
438
|
+
configuration/runtime fingerprints. It reports `CURRENT`, `STALE`,
|
|
439
|
+
`DRIFTED`, `BROKEN`, or `UNVERIFIED`; even `CURRENT` is static preflight
|
|
440
|
+
evidence, not interception proof. Optional create-new baselines contain only
|
|
441
|
+
the parsed version and SHA-256 fingerprints. See the
|
|
442
|
+
[host drift guide](docs/host-drift.md) for the status and baseline contract.
|
|
443
|
+
An explicit `--live-sentinel` can then spend one configured model call in a
|
|
444
|
+
private blank fixture. It reports `PASS`, `FAIL`, or `INCONCLUSIVE` with
|
|
445
|
+
`NONE`/`NOTICE`, `CRITICAL`, or `WARNING`; marker absence alone never passes.
|
|
446
|
+
It retains a hashed/redacted result but not raw model output. This is a
|
|
447
|
+
reliability probe for a trusted provider, not a sandbox for a malicious model.
|
|
448
|
+
The optional Kimi doctor needs Python 3.11+ for TOML parsing; the Core and
|
|
449
|
+
hook adapter continue to support Python 3.9+.
|
|
450
|
+
See the [Kimi](adapters/kimi-code/README.md) and
|
|
451
|
+
[Claude](adapters/claude/README.md) adapter guides.
|
|
452
|
+
See [harness capabilities and evidence levels](docs/harness-capabilities.md)
|
|
453
|
+
for the per-host scope and execution-level acceptance criteria.
|
|
454
|
+
|
|
455
|
+
## Repository layout
|
|
456
|
+
|
|
457
|
+
```
|
|
458
|
+
agent-guard/
|
|
459
|
+
├── skills/delete-guard/ # agent-facing skill: SKILL.md + CLI scripts
|
|
460
|
+
├── skills/exfil-guard/ # egress skill: check_span.py · sanitize.py
|
|
461
|
+
├── skills/recovery-audit/ # evidence-led repository audit and recovery
|
|
462
|
+
├── core/ # classifier · policy · recovery · audit · redaction
|
|
463
|
+
├── doctor.py # local configuration, probes, and drift preflight
|
|
464
|
+
├── live_sentinel.py # opt-in real-host sentinel and alarm evidence
|
|
465
|
+
├── adapters/INTEGRATION.md # checklist for an unlisted host
|
|
466
|
+
├── adapters/claude/ # Claude Code PreToolUse hook adapter
|
|
467
|
+
├── adapters/kimi-code/ # Kimi Code PreToolUse hook adapter
|
|
468
|
+
├── adapters/dsh/ # DeepSeek Harness integration bridge
|
|
469
|
+
├── adapters/codex/harness/# CLI acceptance driver; not a native hook
|
|
470
|
+
├── tests/ # unittest suites incl. cross-harness conformance
|
|
471
|
+
└── docs/ # architecture · threat-model · friction log
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
Skills guide agent behavior; constraints live in Core. Future
|
|
475
|
+
`git-guard`, `database-guard`, `cloud-guard` skills plug into the same
|
|
476
|
+
compensation engine without restructuring.
|
|
477
|
+
|
|
478
|
+
## Documentation
|
|
479
|
+
|
|
480
|
+
| Read | For |
|
|
481
|
+
|---|---|
|
|
482
|
+
| [CONTRIBUTING.md](CONTRIBUTING.md) | how to propose an Issue and submit a focused Pull Request |
|
|
483
|
+
| [docs/architecture.md](docs/architecture.md) | pillars ↔ components, data flow, design decisions |
|
|
484
|
+
| [docs/host-drift.md](docs/host-drift.md) | zero-token host/version drift states and privacy-minimal baselines |
|
|
485
|
+
| [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
|
+
| [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor changes and bounded evidence |
|
|
487
|
+
| [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 changes, evidence levels, and known limits |
|
|
488
|
+
| [adapters/INTEGRATION.md](adapters/INTEGRATION.md) | self-adaptation checklist for an unlisted host |
|
|
489
|
+
| [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–F11) |
|
|
491
|
+
| [docs/development-note-unguarded-deletion.md](docs/development-note-unguarded-deletion.md) | de-identified incident exploration and the recovery-aware direction |
|
|
492
|
+
| [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
|
+
| [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 |
|
|
494
|
+
| [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
|
+
| [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | evidence hierarchy, deterministic replay, recovery and landing gates |
|
|
496
|
+
| [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | full rule table and decision codes |
|
|
497
|
+
| [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil rule table, reason codes, exemption format, audit shape |
|
|
498
|
+
| [skills/exfil-guard/references/channels.md](skills/exfil-guard/references/channels.md) | egress-channel taxonomy and the unreachable channels |
|
|
499
|
+
|
|
500
|
+
## Status & roadmap
|
|
501
|
+
|
|
502
|
+
The source version is **v0.2.2**. The published `v0.2.0` baseline includes
|
|
503
|
+
recoverable destructive actions, cmd/PowerShell dialect parsing, the
|
|
504
|
+
`exfil-guard` text CLI, a read-only config view, and `recovery-audit`.
|
|
505
|
+
Later source releases add Claude/Kimi POSIX hook bridges, bounded host
|
|
506
|
+
evidence, a local `doctor`, host-drift checks, an opt-in live sentinel and
|
|
507
|
+
current DSH package acceptance. See the
|
|
508
|
+
[0.2.2 notes](docs/release-notes-0.2.2.md) for exact scope and
|
|
509
|
+
[GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) for
|
|
510
|
+
publication status; a source version is not itself a published Release.
|
|
511
|
+
|
|
512
|
+
The release identity is harness-neutral. Existing DSH and Claude adapters,
|
|
513
|
+
Codex/ZCode acceptance evidence, and the bounded Kimi exercise are entries
|
|
514
|
+
in a growing compatibility matrix, not separate definitions of the product.
|
|
515
|
+
The Kimi result includes sampled hook-compensation and execution-level BLOCK
|
|
516
|
+
paths, not proof that its host enforces every BLOCK or that arbitrary agent
|
|
517
|
+
actions are protected. A tested direct-Python hook startup failure was
|
|
518
|
+
fail-open. The optional shell bridge blocked a sampled Python startup failure
|
|
519
|
+
in a real Kimi host session, but only when the bridge itself ran; config
|
|
520
|
+
validation alone cannot prove that the hook is live.
|
|
521
|
+
Real Windows end-to-end coverage and general concurrent-subagent safety
|
|
522
|
+
also remain explicit gaps. Later Guard branches (`git-guard`, `database-guard`,
|
|
523
|
+
`cloud-guard`) reuse the same protocol and compensation engine.
|
|
524
|
+
|
|
525
|
+
## 0.2.x preview: guard-lab
|
|
526
|
+
|
|
527
|
+
Planned, **not included in 0.2.2**: an opt-in, offline honeytoken lab
|
|
528
|
+
using disposable projects and synthetic, non-secret markers. It will compare
|
|
529
|
+
normal tasks with prompt-injection attempts, and separately observe whether a
|
|
530
|
+
harness indexes or exports files without an agent-requested read. Positive and
|
|
531
|
+
negative controls, an independent observer, and evidence labels will keep a
|
|
532
|
+
mere read request distinct from a confirmed external transfer. No real
|
|
533
|
+
credentials or automatic background monitoring are part of the plan. This is
|
|
534
|
+
a bounded diagnostic experiment, not a guarantee against a malicious model
|
|
535
|
+
or harness.
|
|
536
|
+
|
|
537
|
+
## Contributing
|
|
538
|
+
|
|
539
|
+
Bug reports, design proposals, compatibility evidence, documentation fixes,
|
|
540
|
+
and focused code changes are welcome. Please start with an
|
|
541
|
+
[Issue](https://github.com/mokuyoaxis/agent-guard/issues) for non-trivial or
|
|
542
|
+
security-boundary changes, and submit implementations as a focused
|
|
543
|
+
[Pull Request](https://github.com/mokuyoaxis/agent-guard/pulls). Read the
|
|
544
|
+
[contribution guide](CONTRIBUTING.md) before sharing logs or test evidence;
|
|
545
|
+
credentials, private configuration, and unredacted incident data must not be
|
|
546
|
+
posted publicly.
|
|
547
|
+
|
|
548
|
+
## Community
|
|
549
|
+
|
|
550
|
+
[](https://linux.do/t/topic/2942799)
|
|
551
|
+
|
|
552
|
+
This project-made banner links to our
|
|
553
|
+
[LINUX DO project post](https://linux.do/t/topic/2942799). It does not imply
|
|
554
|
+
official endorsement by the community.
|
|
555
|
+
|
|
556
|
+
## License
|
|
557
|
+
|
|
558
|
+
MIT — see [LICENSE](LICENSE).
|