@mokuyoaxis/agent-guard 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/CONTRIBUTING.md +101 -0
  2. package/LICENSE +21 -0
  3. package/README.md +558 -0
  4. package/README.zh-CN.md +488 -0
  5. package/adapters/INTEGRATION.md +94 -0
  6. package/adapters/claude/README.md +141 -0
  7. package/adapters/claude/compatibility.json +17 -0
  8. package/adapters/claude/harness/README.md +59 -0
  9. package/adapters/claude/harness/mock_anthropic_api.mjs +47 -0
  10. package/adapters/claude/harness/run_scenario.sh +79 -0
  11. package/adapters/claude/harness/run_scenario_no_python3.sh +49 -0
  12. package/adapters/claude/hook_bridge.sh +33 -0
  13. package/adapters/claude/pre_tool_use.py +264 -0
  14. package/adapters/claude/settings.example.json +16 -0
  15. package/adapters/codex/harness/README.md +53 -0
  16. package/adapters/codex/harness/acceptance.py +226 -0
  17. package/adapters/dsh/README.md +62 -0
  18. package/adapters/dsh/cordis.patch.yml +30 -0
  19. package/adapters/dsh/lib/index.js +500 -0
  20. package/adapters/kimi-code/README.md +169 -0
  21. package/adapters/kimi-code/compatibility.json +17 -0
  22. package/adapters/kimi-code/config.example.toml +26 -0
  23. package/adapters/kimi-code/hook_bridge.sh +32 -0
  24. package/adapters/kimi-code/pre_tool_use.py +72 -0
  25. package/core/__init__.py +47 -0
  26. package/core/audit.py +86 -0
  27. package/core/classifier.py +1175 -0
  28. package/core/dialects.py +898 -0
  29. package/core/policy.py +817 -0
  30. package/core/recovery.py +700 -0
  31. package/core/redaction.py +1096 -0
  32. package/core/safe_view.py +212 -0
  33. package/docs/architecture.md +223 -0
  34. package/docs/compatibility.md +142 -0
  35. package/docs/development-note-unguarded-deletion.md +187 -0
  36. package/docs/friction.md +266 -0
  37. package/docs/harness-capabilities.md +72 -0
  38. package/docs/host-drift.md +142 -0
  39. package/docs/publishing-from-ephemeral-environments.md +104 -0
  40. package/docs/release-notes-0.2.0-rc1.md +46 -0
  41. package/docs/release-notes-0.2.0.md +72 -0
  42. package/docs/release-notes-0.2.1.md +78 -0
  43. package/docs/release-notes-0.2.2.md +120 -0
  44. package/docs/secret-guard-analysis.md +416 -0
  45. package/docs/secret-guard-architecture.md +93 -0
  46. package/docs/secret-guard-design.md +649 -0
  47. package/docs/test-report-claude-code-harness.md +462 -0
  48. package/docs/test-report-codex-gpt-5.6-sol.md +335 -0
  49. package/docs/test-report-codex-gpt-6-astra-high.md +129 -0
  50. package/docs/test-report-dsh-0.1.5-rc.1.md +84 -0
  51. package/docs/test-report-dsh-v0.1.1.md +126 -0
  52. package/docs/test-report-kimi-code-block.md +198 -0
  53. package/docs/test-report-zcode-glm-flash.md +241 -0
  54. package/docs/threat-model.md +44 -0
  55. package/doctor.py +756 -0
  56. package/live_sentinel.py +339 -0
  57. package/package.json +69 -0
  58. package/skills/delete-guard/SKILL.md +109 -0
  59. package/skills/delete-guard/agents/openai.yaml +4 -0
  60. package/skills/delete-guard/references/policy.md +161 -0
  61. package/skills/delete-guard/scripts/_bootstrap.py +8 -0
  62. package/skills/delete-guard/scripts/check.py +370 -0
  63. package/skills/delete-guard/scripts/gc.py +103 -0
  64. package/skills/delete-guard/scripts/restore.py +98 -0
  65. package/skills/delete-guard/scripts/safe_delete.py +256 -0
  66. package/skills/delete-guard/scripts/status.py +130 -0
  67. package/skills/exfil-guard/SKILL.md +143 -0
  68. package/skills/exfil-guard/agents/openai.yaml +4 -0
  69. package/skills/exfil-guard/references/channels.md +58 -0
  70. package/skills/exfil-guard/references/rules.md +194 -0
  71. package/skills/exfil-guard/scripts/_bootstrap.py +8 -0
  72. package/skills/exfil-guard/scripts/check_span.py +250 -0
  73. package/skills/exfil-guard/scripts/sanitize.py +155 -0
  74. package/skills/exfil-guard/scripts/view.py +44 -0
  75. package/skills/recovery-audit/SKILL.md +283 -0
  76. package/skills/recovery-audit/agents/openai.yaml +4 -0
  77. package/skills/recovery-audit/references/evidence-records.md +85 -0
@@ -0,0 +1,416 @@
1
+ # exfil-guard (secret + path leakage) — requirement analysis
2
+
3
+ Status: **analysis, pre-implementation.** No code, no schema, no verdict
4
+ table is frozen by this document. It exists to decide *whether* the
5
+ feature belongs in agent-guard, *where* it plugs into the existing
6
+ interception model, and *what the MVP is*.
7
+
8
+ Working name: **`exfil-guard`**. The two user requests (secret leakage,
9
+ local-path leakage) are two rule families, not two skills — §3 argues
10
+ this explicitly.
11
+
12
+ ---
13
+
14
+ ## 0. The constraint that shapes everything
15
+
16
+ agent-guard is **reliability infrastructure, not a security sandbox**
17
+ (`docs/threat-model.md`). Its own threat model says a determined agent
18
+ with equal OS privileges can always bypass it. Every claim in this
19
+ document must survive that sentence.
20
+
21
+ That immediately reclassifies both requests:
22
+
23
+ | | Security framing (rejected) | Reliability framing (accepted) |
24
+ |---|---|---|
25
+ | Secret guard | "prevent adversarial exfiltration" | "prevent the *accidental* publication/transmission of a credential the agent had legitimate read access to" |
26
+ | Path guard | "prevent information disclosure attacks" | "prevent *accidental* disclosure of host-identifying paths that produce false bug reports and privacy churn" |
27
+
28
+ The honest one-line positioning:
29
+
30
+ > exfil-guard makes accidental disclosure of credentials and host paths
31
+ > **catchable before the bytes leave**, with a decision trail. It does not
32
+ > and cannot stop an agent that is trying to leak.
33
+
34
+ Why this is still worth building: the §1 scenarios are overwhelmingly
35
+ *mistakes* (inadequate context, a debugging `echo`, a copy-paste into a PR
36
+ body), and they are the same class of mistake delete-guard already
37
+ addresses. There is no sandbox that stops an agent from `curl`ing a secret
38
+ it can read; there *is* a cheap place to catch the mistake.
39
+
40
+ ### 0.1 The irrevocability axis (why this is a fourth compensation strategy)
41
+
42
+ delete-guard's design is: **destroy → compensate → let it happen.** Loss
43
+ is undone afterwards. Disclosure does not work that way — once a token is
44
+ in a public gist, on a remote ref, or in someone else's API logs, no
45
+ local compensation exists.
46
+
47
+ So exfil-guard is a **pre-commitment filter**, not a compensation engine:
48
+
49
+ ```
50
+ delete-guard: classify → relocate/snapshot → MUTATE → (recover later)
51
+ exfil-guard: classify → redact/withhold → EMIT → (nothing to recover)
52
+ ```
53
+
54
+ This is not a contradiction of the four pillars; it is which pillar
55
+ carries the weight:
56
+
57
+ | Pillar | delete-guard | exfil-guard |
58
+ |---|---|---|
59
+ | Scope | workspace boundary | **the egress boundary** (§2) |
60
+ | Recoverability | quarantine / snapshot | *weak* — a **RedactionRecord** (payload-evidence §4.4), not a rollback of the emission |
61
+ | Authorization | NORMAL / RESTRICTED | unchanged, plus a new capability: **secret-scan disable is host-side only** |
62
+ | Auditability | every verdict, txid | every verdict + **`rule_id`, spans/lengths, never matched bytes** |
63
+
64
+ Two consequences that are non-negotiable in the design doc:
65
+
66
+ 1. **A false ALLOW is a permanent leak; a false SANITIZE is cheap.** The
67
+ tolerance is therefore inverted relative to delete-guard. See §4.4 —
68
+ this is the single largest open design tension and it belongs to the
69
+ human, not to the guard's defaults.
70
+ 2. **The audit log is itself an egress channel** (threat #7). Recording a
71
+ secret in `audit.jsonl` recreates the leak in a durable file *and*
72
+ ships it in bug reports. Precedent already exists in-repo:
73
+ `docs/publishing-from-ephemeral-environments.md` is the reason
74
+ `SECURITY.md` documents "credential-adjacent wording" scanner hits.
75
+
76
+ ---
77
+
78
+ ## 1. Threat scenario enumeration
79
+
80
+ Each scenario is scored on three axes chosen for *this* architecture:
81
+
82
+ - **Egress** — does the bytes leave the machine / become persistent?
83
+ - **Reachable** — can any of agent-guard's existing interception points see it?
84
+ - **Compensable** — if it happens, is there anything to undo?
85
+
86
+ `H`/`M`/`L` are relative within this repo's context (a dev workstation with
87
+ a git remote and an LLM API), not absolute risk scores.
88
+
89
+ ### 1.1 Secret leakage
90
+
91
+ | # | Scenario | Concrete shape | Egress | Reachable | Compensable | Notes |
92
+ |---|---|---|---|---|---|---|
93
+ | S1 | Secret inlined into an outbound LLM request | agent writes `Here is my config: sk-proj-…` into the prompt | **H** | ✗ (§2.3) | ✗ | The prompt is the one channel every agent always uses |
94
+ | S2 | Secret written into a tracked config file, then pushed | `sed -i 's/KEY=.*/KEY='$KEY'/' .env.example`; `git commit -am`; `git push` | **H** | partial | partial | `push` is the last local checkpoint; `.env` is usually git-ignored, `.env.example` is not |
95
+ | S3 | Secret printed to terminal | `echo "$OPENAI_API_KEY"`, `env`, `printenv`, `cat .env` | M/H | **✓ pre-command** | ✗ | Transcripts are egress: harness logs, CI output, screen shares |
96
+ | S4 | Secret in a debug log / traceback | `logger.debug("token=%s", token)`; requests library dumping headers | M | partial | ✗ | Content is produced by a *program*, not by the command line — see B1, §2.4 |
97
+ | S5 | `.env` contents pasted into an issue / PR comment | `cat .env` then a human-shaped copy-paste, or an agent using a forge tool | **H** | ✗ | ✗ | Public-by-default once posted; forge edits keep history |
98
+ | S6 | Hardcoded secret in generated code | `client = Client("sk-live-…")` written into a new source file | **H** | **✓ pre-write** (new point) | partial (if caught before commit) |
99
+ | S7 | Secret in a git commit message | `git commit -m "fix: rotate key ghp_…"` | **H** | **✓ pre-command** | ✗ | Messages are immutable-ish (rebase rewrites history, breaks signatures) |
100
+ | S8 | Secret in an upload / bundle / artifact | `.agent-trash/` packaged by mistake, a `tar czf` of the workspace | **H** | partial | ✗ | Already named as residual risk in `docs/threat-model.md` #8 |
101
+ | S9 | Secret in a dependency lockfile / generated fixture | agent regenerates a fixture from a live capture | M | partial | partial | The realistic "long random string" false-positive factory |
102
+
103
+ **Delete-guard adjacency worth noting:** S2/S8 are the *same failure
104
+ family* as threat-model #8 (quarantine bloat → exfil via packaging). The
105
+ quarantine directory is a secret-liability volume by construction: it holds
106
+ copies of `.env` files the agent deleted. Any secret-guard scan of the
107
+ workspace must therefore treat `.agent-trash/` as a first-class source, and
108
+ `gc.py` decisions interact with it.
109
+
110
+ ### 1.2 Local-path leakage
111
+
112
+ | # | Scenario | Concrete shape | Egress | Reachable | Compensable | Notes |
113
+ |---|---|---|---|---|---|---|
114
+ | P1 | Absolute path in an outbound LLM prompt | `"why does /home/alice/work/thing fail?"` | **H** | ✗ | ✗ | Same channel as S1; lowest severity, highest volume |
115
+ | P2 | Traceback with host paths pasted into an issue | `File "/Users/alice/.venv/lib/…"` | **H** | partial | ✗ | Public bug reports; also a **false-report generator** (paths are useless to maintainers) |
116
+ | P3 | Log file written with absolute paths | app logs `cwd=/root/agent-ws/ab12/` | M | pre-write (new point) | ✓ (file is local) | Highest *compensability* of all scenarios |
117
+ | P4 | Absolute path in a commit message | `git commit -m "fix /home/alice/… path"` | **H** | **✓ pre-command** | ✗ | Same interception as S7 |
118
+ | P5 | Packaged traceback / artifact containing host paths | CI bundle, issue attachment, error report | **H** | partial | ✗ | |
119
+
120
+ **Severity honesty:** path leakage is *low* severity for a typical
121
+ developer workstation (the username is often already public) and *high*
122
+ severity in three specific contexts: (a) CI/CD runner paths embedded in
123
+ published artifacts — this repository's own test reports and failure
124
+ outputs are exactly this shape; (b) shared/agent-provisioned machines
125
+ where a path leaks a codename or a tenant id; (c) sandboxes whose paths
126
+ encode a session id or a customer id. The design should therefore default
127
+ to **helpful** for path rules and **strict** for the narrow set of secret
128
+ rules, rather than treating them symmetrically (§4.4).
129
+
130
+ ### 1.3 Scenarios deliberately excluded from this analysis
131
+
132
+ - Malicious exfiltration (the agent obfuscates a secret to evade the
133
+ scanner). Excluded by the §0 positioning.
134
+ - Secrets the agent never had access to (that is sandboxing).
135
+ - Scanning for secrets *at rest* across an entire machine — this is a
136
+ file scanner product (gitleaks/trufflehog territory), not an
137
+ interception layer.
138
+ - Post-hoc git-history scrubbing (BFG/`filter-repo` workflow). Useful, but
139
+ it is a *remediation* tool, not a guard, and it belongs to a hypothetical
140
+ `git-guard` (V2) rather than here.
141
+
142
+ ---
143
+
144
+ ## 2. Attack-surface analysis: where does agent-guard actually get to intervene?
145
+
146
+ ### 2.1 The existing interception model, restated
147
+
148
+ From `docs/architecture.md`, agent-guard has exactly **one** enforcement
149
+ point today:
150
+
151
+ ```
152
+ harness hook ──prefilter──▶ check.py --enforce -- <command> ──▶ PROCEED | refuse
153
+ ▲
154
+ └── the *whole* enforcement surface of V1
155
+ ```
156
+
157
+ Everything else (model tools `safe_delete`/`restore`/`status`, the prompt
158
+ section) is a *nudge*, not enforcement. The architecture doc is explicit:
159
+ "Interception without prompting causes friction; prompting without
160
+ interception is advisory only."
161
+
162
+ So the question "where do we intercept exfiltration?" has an uncomfortable
163
+ first answer: **the egress surface is much wider than the shell-command
164
+ surface, and most of it is invisible to us.**
165
+
166
+ ### 2.2 Class A — reusable on the existing pre-command hook
167
+
168
+ These are *shell-command* scenarios. They need no new interception point;
169
+ they need new rules in the same classifier→policy pipeline.
170
+
171
+ | Scenario | Mechanism |
172
+ |---|---|
173
+ | S3 (`echo "$API_KEY"`, `printenv`, `env`) | Detect the *shape*: a command whose effect is "write an environment variable / a file's content to stdout or a file". Redaction is impossible pre-execution — one cannot un-print — so this is ALLOW-with-warning or ASK, see §4.4 |
174
+ | S7 / P4 (secret or path inside `git commit -m …`) | The message is a literal on the command line; the classifier can see it. But the *value* may come from a variable (`-m "$MSG"`) → undeterminable, fail closed or warn |
175
+ | S2 partially (`git push` carrying a tracked file) | `check.py` already sees the push. It can enumerate what the push would send (`git diff --cached`, `git log @{u}..HEAD --name-only`) and scan those diffs before allowing the push |
176
+ | S8 (`tar czf …`, `git add -A`) | A command that packages the workspace for egress. Scannable in principle; the target set is enumerable exactly like `git clean -n` |
177
+ | Any command whose *stdout* is piped to a network tool (`curl -d @-`, `nc`, `ssh … < file`) | Detectable as a shape ("stdout feeds a network sink"), not as content |
178
+
179
+ **Key structural insight:** for Class A, the *decision* vocabulary is
180
+ already sufficient. `RELOCATE`/`SNAPSHOT` do not apply, but `ASK`,
181
+ `BLOCK`, and a **new `SANITIZE`** do — and SANITIZE is only meaningful
182
+ where the guard can rewrite the bytes (a file write, a git object, an
183
+ outbound request body), which is precisely the set of scenarios *not* in
184
+ Class A.
185
+
186
+ ### 2.3 Class B — needs a new interception point
187
+
188
+ | Egress point | Can it be intercepted? | How, honestly |
189
+ |---|---|---|
190
+ | **Outbound LLM request body** (S1, P1) | *Yes, for some harnesses* | Harnesses that expose a pre-request hook, or route through a local proxy (this repo already ships `adapters/claude/harness/mock_anthropic_api.mjs` — a proxy is a **demonstrated** integration shape here). A truly hosted model call with no proxy is unreachable |
191
+ | **File write content** (S6, P3) | *Yes, at the tool layer* | A `PreToolUse`-style hook on Write/Edit tools, or a `PreWrite` hook. This is a *new adapter point*, not a new core rule engine |
192
+ | **Outbound forge API call** (S5: comment, issue body, PR description) | Forge-specific | Same adapter shape as the LLM case |
193
+ | **Outbound HTTP/DB query** (the V3+ `database-guard`/`cloud-guard` neighbours) | Out of scope here | Would share the RedactionRecord, not the rules |
194
+
195
+ ### 2.4 Class C — not interceptable under the current architecture
196
+
197
+ State these plainly; they are the residual risk section, and pretending
198
+ otherwise is what turns a reliability tool into a false security claim.
199
+
200
+ 1. **The agent's own tool calls.** If the harness does not route a channel
201
+ through a hook, the guard has no bytes to inspect. This is the same
202
+ residual risk as threat-model #1 ("agent deletes via its own script
203
+ calling `unlink()`") — and the same upgrade path (mediating service,
204
+ not shell interception).
205
+ 2. **Content produced *inside* a program.** B1 in `docs/architecture.md`
206
+ ("the guard analyzes the command's direct effect; it does not infer the
207
+ internal behavior of arbitrary programs") applies verbatim. `python
208
+ app.py` whose logger writes a token is invisible. We see the *intent to
209
+ run a program*, never its output.
210
+ 3. **The model's own latent knowledge of a path it read earlier.** Once a
211
+ path is in context, only the outbound-request interceptor can catch it,
212
+ and only on harnesses that have one. This is *the* dominant real-world
213
+ path-leak channel (P1/P2) and it is mostly unguarded.
214
+ 4. **The human clipboard.** If the agent prints it and a human pastes it,
215
+ the guard's last chance was S3's terminal output — where, again, it
216
+ cannot un-print.
217
+
218
+ ### 2.5 The uncomfortable summary
219
+
220
+ ```
221
+ scenario count by reachability
222
+ Class A (reuse pre-command hook) ~5 of 14 ← what we can actually ship
223
+ Class B (new adapter point needed) ~5 of 14 ← needs each harness to cooperate
224
+ Class C (unreachable by construction) ~4 of 14 ← must be documented, not promised
225
+ ```
226
+
227
+ The cheap, high-yield wins are **Class B file-write/intercepted-request**
228
+ (from 0% coverage today) and **Class A commit-message/push scans**. S1 —
229
+ the scenario the user listed first — is the *hardest* one, and shipping a
230
+ `secret-guard` that claims to cover it would be the exact over-claim
231
+ `docs/threat-model.md` forbids.
232
+
233
+ ---
234
+
235
+ ## 3. Relationship to delete-guard
236
+
237
+ ### 3.1 One skill or two? — **one skill, two rule families**
238
+
239
+ Arguments for a single `exfil-guard` (or an `exfil-guard` skill whose
240
+ `references/` splits the two families):
241
+
242
+ 1. **Shared classifier output type.** Both families answer the same
243
+ question — "does this text contain a span that must not leave?"
244
+ Whether the span is `sk-…` or `/home/alice` changes the *rule*, not the
245
+ *machinery* (offsets, spans, redaction, audit). Delete-guard already
246
+ proved the shape: one `OpSpec`/`PathSpec` fact layer feeding one policy
247
+ table.
248
+ 2. **Shared decision vocabulary.** Both need the same new decision
249
+ (`SANITIZE`) and the same audit shape. Splitting duplicates the one
250
+ thing this repository is organized to avoid duplicating — the rule
251
+ engine (§"Key design decisions" #1: "there is exactly one rule engine
252
+ across every harness").
253
+ 3. **They co-occur.** A commit message can contain both; a pushed file can
254
+ contain both. Two independent interceptors would produce two verdicts
255
+ for one emission and force the adapter to invent an ordering. The
256
+ existing `policy.worst()` aggregator already solves this — if they are
257
+ the same pipeline.
258
+ 4. **Naming honesty.** `path-guard` next to `delete-guard` reads as "a
259
+ guard for paths", which collides conceptually with path *deletion*.
260
+ `exfil-guard` names the risk (disclosure), not the payload.
261
+ 5. **Cost.** Each new skill pays the adapter/integration cost again (hook
262
+ wiring, prefilter, prompt section, conformance tests). Two skills for
263
+ one pipeline is 2× integration for ~1.1× capability.
264
+
265
+ Arguments for two skills, and why they lose:
266
+
267
+ - *Different default strictness* (secrets strict, paths lenient). This is a
268
+ **policy-configuration** concern, not a package-boundary concern — the
269
+ rule table supports per-family severity.
270
+ - *Independent disable* (turn off path noise, keep secret rules). Also
271
+ configuration (`AGENT_GUARD_EXFIL_RULES=secret`).
272
+
273
+ **Decision: one skill, `exfil-guard`, with two rule families
274
+ (`secret/*`, `path/*`) addressed by the same rule ids.** If implementation
275
+ reveals that the families genuinely diverge in mechanism, the split is
276
+ mechanical later; the reverse (merging two shipped skills) is not.
277
+
278
+ ### 3.2 What is reused verbatim
279
+
280
+ | Component | Reuse | Why |
281
+ |---|---|---|
282
+ | Decision Protocol (decision + ReasonCode + Explanation + payload) | **yes** | Frozen adapter surface (`docs/compatibility.md`); adapters already map it |
283
+ | `policy.worst()` aggregation + rank table | **yes**, extended | One verdict per emission must be the existing aggregate |
284
+ | `core/audit.py` append/tail/fsync/JSONL | **yes**, new record events | Same "append-only, dumb, never mutated" discipline |
285
+ | NORMAL/RESTRICTED capability model | **yes** | Unchanged semantics; RESTRICTED should *tighten* exfil rules, never loosen |
286
+ | `check.py` CLI contract (exit 0/2/3, `--json`) | **yes**, new subcommand/flag | Conformance tests (`tests/test_conformance.py`) already pin this |
287
+ | Harness prefilter pattern (regex fast path) | **yes**, new prefilter | Latency budget matters (friction F4: ~0.3 s/command) |
288
+ | `recovery.py` relocate/snapshot | **no** | Wrong axis (§0.1) — do not force it |
289
+
290
+ ### 3.3 What is genuinely new
291
+
292
+ 1. A **content classifier** (`SpanSpec`) — the first classifier in this repo
293
+ whose input is text payload rather than a command or a path.
294
+ 2. A new decision, **`SANITIZE`**, and its exit-code mapping.
295
+ 3. **Redaction records** in audit — and the discipline that matched bytes
296
+ are never stored (§4.4).
297
+ 4. A **value-free comparator** for environment variables (T2, §4.2): the
298
+ guard must decide "would this print a secret?" without reading the
299
+ secret.
300
+ 5. Two new adapter interception points (pre-write, pre-request) — Class B.
301
+
302
+ ### 3.4 New ReasonCodes (proposed; names are a design decision, not final)
303
+
304
+ Secrets — `secret/*`:
305
+
306
+ | Code | Decision | Meaning |
307
+ |---|---|---|
308
+ | `SANITIZE_KNOWN_SECRET_PATTERN` | SANITIZE | High-confidence vendor pattern (T1 list) |
309
+ | `SANITIZE_HIGH_ENTROPY_VALUE` | SANITIZE | Entropy heuristic with a secret-ish key context (T3) |
310
+ | `SANITIZE_PRIVATE_KEY_BLOCK` | SANITIZE | `-----BEGIN … PRIVATE KEY-----` block, truncate wholly |
311
+ | `BLOCK_SECRET_IN_COMMIT_MESSAGE` | BLOCK | Credential about to enter immutable history |
312
+ | `BLOCK_SECRET_IN_PUSH_PAYLOAD` | BLOCK | Credential in the outgoing diff |
313
+ | `ASK_SECRET_PRINT` | ASK | Command *shape* would print a secret (S3); cannot redact post-hoc |
314
+ | `ASK_SECRET_UNDETERMINABLE` | ASK | Value comes from a variable/subsystem we cannot evaluate |
315
+
316
+ Paths — `path/*`:
317
+
318
+ | Code | Decision | Meaning |
319
+ |---|---|---|
320
+ | `SANITIZE_HOST_PATH` | SANITIZE | Absolute host path outside the workspace, replaced with a stable token |
321
+ | `BLOCK_HOST_PATH_IN_COMMIT_MESSAGE` | BLOCK | P4 |
322
+ | `ASK_HOST_PATH_PRINT` | ASK | Low severity; a human says yes in ~1 second |
323
+
324
+ Cross-cutting:
325
+
326
+ | Code | Decision | Meaning |
327
+ |---|---|---|
328
+ | `BLOCK_EXFIL_SCANNER_UNAVAILABLE` | BLOCK | Scan errored. **Fail closed**: an unscanned egress is not a clean egress |
329
+ | `BLOCK_EXFIL_RULE_CONFIG_INVALID` | BLOCK | Malformed user rule (same class as `BLOCK_DIALECT_UNKNOWN`) |
330
+
331
+ **Compatibility note:** adding decision classes and reason codes is a
332
+ *minor* release under `docs/compatibility.md` ("New reason code
333
+ (additive) → minor"; "New decision class → minor, announced in README").
334
+ `SANITIZE` must be announced in the README, and every adapter must state
335
+ its native mapping (ask §4.4 for harnesses without re-write capability).
336
+
337
+ ### 3.5 False positives — the cross-cutting problem, stated once
338
+
339
+ Delete-guard's failure mode is *friction*: an over-eager BLOCK wastes a
340
+ human's minute. Exfil-guard's failure mode is *worse and asymmetric*:
341
+
342
+ - A **false SANITIZE that replaces a legitimate value** (a test fixture, a
343
+ public key, a hash) silently corrupts the agent's output, and the agent
344
+ often cannot tell. A guard that quietly mangles output erodes trust
345
+ faster than one that refuses.
346
+ - A **false POSITIVE flood** (path rules on every absolute path in every
347
+ traceback) makes the guard something to be disabled — the worst outcome
348
+ for a tool whose value is being on by default.
349
+ - A **false NEGATIVE is a permanent leak** (§0.1).
350
+
351
+ Mitigations are enumerated in the design doc §5; the analysis-level
352
+ requirement is only this: **the guard must be able to say ALLOW with high
353
+ precision, and must never silently rewrite a value it is not confident
354
+ about.** Three concrete instruments follow from that, all borrowed from
355
+ existing repo precedent:
356
+
357
+ 1. **A confidence gate** (single decisive pattern vs. contextual
358
+ heuristic), mirroring the dialect layer's "abbreviations expand only
359
+ when unambiguous" rule.
360
+ 2. **A workspace-relative exemption**, mirroring the lexical-boundary
361
+ discipline: paths inside the workspace are not host identifiers.
362
+ 3. **An in-repo exemption list**, not a global one — the same problem
363
+ `SECURITY.md` solves for scanners ("Expected scanner hits on this
364
+ repository"). Any own-repo deployment of exfil-guard will scan
365
+ `tests/` fixtures full of `sk-…` strings and *must* stay usable.
366
+
367
+ ---
368
+
369
+ ## 4. Open questions for the design doc (and for the human)
370
+
371
+ These are carried into `secret-guard-design.md` and answered there; listed
372
+ here because they are genuinely unresolved, not rhetorical.
373
+
374
+ - **Q1 Egress definition.** Which channels count as "out"? A terminal
375
+ transcript is not the same as a public gist. The design must pick a
376
+ channel taxonomy, because the *strictness* differs per channel and so
377
+ does the recovery story.
378
+ - **Q2 SANITIZE on a locked channel.** If the harness cannot re-write the
379
+ payload (no pre-write hook), does `SANITIZE` degrade to `ASK`, to
380
+ `BLOCK`, or to a warning-only `ALLOW`? Fail-closed says BLOCK; usability
381
+ says ASK-or-warn. This is the single most consequential decision in the
382
+ feature.
383
+ - **Q3 Value-free detection.** How do we detect "this command prints
384
+ `$OPENAI_API_KEY`" without ever reading that value — and what do we do
385
+ when the variable is *undefined*, or holds a non-secret?
386
+ - **Q4 Irreversibility and human consent.** Given §0.1, is a BLOCK on a
387
+ commit message legitimate? (delete-guard never blocks an operation that
388
+ the *human* could trivially redo; but committing a secret is not trivial
389
+ to redo.)
390
+ - **Q5 MVP intersection.** Which ≤3 scenarios justify the first release,
391
+ and which must be explicitly declared NOT DONE so the README cannot be
392
+ read as covering them?
393
+ - **Q6 Roadmap slot.** New `X-guard` branch beside `git-guard`, or does the
394
+ shared content classifier belong to the core *before* `git-guard`?
395
+
396
+ ---
397
+
398
+ ## 5. Non-goals (analysis-level)
399
+
400
+ Stated here so the design doc cannot quietly expand scope:
401
+
402
+ 1. **Not a sandbox.** No kernel-level enforcement, no network mediation we
403
+ do not already have a hook for.
404
+ 2. **Not a history scrubbing tool.** exfil-guard prevents; if it fails, the
405
+ human runs `filter-repo`. A guard that tries to also be a rewriting tool
406
+ becomes a second destruction vector — exactly the reasoning behind
407
+ "restore is non-destructive" (`docs/architecture.md` #4).
408
+ 3. **Not a full file scanner / not a gitleaks replacement.** Scope is
409
+ *egress-relevant* content the guard can reach, not "all secrets on the
410
+ disk".
411
+ 4. **Not a DLP product.** No ML classification, no entitlement system, no
412
+ per-destination policy server.
413
+ 5. **Not a claim of coverage over Unreachable channels (§2.4).** Every doc
414
+ must carry this limitation, in the same spirit as
415
+ `docs/threat-model.md`'s "What would upgrade this to a security
416
+ boundary".
@@ -0,0 +1,93 @@
1
+ # exfil-guard — where it sits in the architecture
2
+
3
+ Short orientation for someone who already knows agent-guard from
4
+ `docs/architecture.md`. Full analysis and design:
5
+ `secret-guard-analysis.md`, `secret-guard-design.md`.
6
+
7
+ ## One-paragraph summary
8
+
9
+ `exfil-guard` is the **egress side** of the same reliability promise.
10
+ `delete-guard` answers "if this destroys something, can we come back?";
11
+ `exfil-guard` answers "if this leaves the machine, was it supposed to?".
12
+ It adds one classifier input type (text spans instead of shell commands or
13
+ paths), one decision class (`SANITIZE`), and two new adapter interception
14
+ points (pre-write, pre-request). Everything else — the Decision Protocol,
15
+ `policy.worst()` aggregation, the audit log, the NORMAL/RESTRICTED
16
+ capability model, `check.py`'s exit-code contract — is reused unchanged.
17
+
18
+ ## Where the parts live
19
+
20
+ | Concern | delete-guard (existing) | exfil-guard (new) |
21
+ |---|---|---|
22
+ | Fact extraction | `core/classifier.py` → `OpSpec`, `PathSpec` | **`core/redaction.py`** → `SpanSpec` (new) — same "facts, not decisions" contract |
23
+ | Lexical front end | `core/dialects.py` | *none needed*: text has no dialect. The Windows path/interpolation vocabulary is **imported** from `dialects.py`, not re-implemented |
24
+ | Rule table | `core/policy.py` → `decide_ops` | `core/policy.py` → **`decide_spans`** (new function, same `Verdict` type) |
25
+ | Compensation | `core/recovery.py` (relocate / snapshot) | `core/redaction.py` → **redaction** (the degraded strategy: it records what was removed; it cannot undo a sent payload) |
26
+ | Entry point | `skills/delete-guard/scripts/check.py` | **`skills/exfil-guard/scripts/check_span.py`** (separate entry: different input, no compensation phase) |
27
+ | Audit | `core/audit.py` (JSONL, append-only) | *same module*, new event kinds, and one extra rule: **matched bytes are never recorded** |
28
+ | Skill surface | `skills/delete-guard/` | `skills/exfil-guard/` (one skill, two rule families: `secret/*`, `path/*`) |
29
+ | Adapters | pre-command hook | *same hook* **plus** two new points (pre-write, pre-request) — adapter-side only |
30
+
31
+ ## The data flow, side by side
32
+
33
+ ```
34
+ delete-guard shell command ─▶ check.py ─▶ classify ─▶ policy ─▶ RELOCATE/SNAPSHOT
35
+ │
36
+ compensation engine
37
+ ▼
38
+ MUTATE
39
+
40
+ exfil-guard outbound payload ─▶ check_span.py ─▶ detect ─▶ policy ─▶ SANITIZE
41
+ │
42
+ redaction plan
43
+ ▼
44
+ EMIT
45
+ ```
46
+
47
+ Same Decision Protocol, mirrored verb of the compensation:
48
+
49
+ ```
50
+ delete-guard: destroy → compensate → proceed (recoverable)
51
+ exfil-guard: disclose → redact → emit (irreversible)
52
+ ```
53
+
54
+ ## The fourth pillar, restated
55
+
56
+ | Pillar | delete-guard | exfil-guard |
57
+ |---|---|---|
58
+ | Scope | workspace boundary | **egress boundary** (channel taxonomy; see design §4.1) |
59
+ | Recoverability | quarantine / snapshot | weak: a RedactionRecord, not a rollback |
60
+ | Authorization | NORMAL / RESTRICTED | unchanged; rule config is host-side only |
61
+ | Auditability | verdicts, txids | verdicts + rule id/offsets/lengths — **never matched bytes** |
62
+
63
+ The cross-cutting rule still holds and now bites harder:
64
+
65
+ > **Uncertainty increases restriction.** An unscanned egress is not a clean
66
+ > egress (`BLOCK_EXFIL_SCANNER_UNAVAILABLE`).
67
+
68
+ ## Two invariants that are new here
69
+
70
+ 1. **The guard reads names and shapes, never secret values.** Detection of
71
+ `$OPENAI_API_KEY` classifies the variable's *name*, never its content.
72
+ This keeps the guard's own output, logs, and audit lines value-free — a
73
+ guard that leaks what it protects is worse than no guard.
74
+ 2. **Irreversibility moves the tolerance, not the architecture.** A false
75
+ ALLOW is permanent, a false SANITIZE is cheap; therefore detection
76
+ defaults to strict and path rules default to quiet, without adding a
77
+ second protocol or a second decision model.
78
+
79
+ ## What this feature may and may not claim
80
+
81
+ Following `docs/threat-model.md`, and stated in the README when it lands:
82
+
83
+ - **May claim:** catches *accidental* disclosure on channels the harness
84
+ routes through a hook; one decision trail for every verdict; redaction
85
+ with a reviewable plan; no secrets in the guard's own artifacts.
86
+ - **May NOT claim:** prevention of adversarial exfiltration; coverage of
87
+ channels with no hook (hosted LLM calls without a proxy, the model's own
88
+ tool calls, content produced *inside* a program — B1 applies); any
89
+ containment guarantee.
90
+
91
+ Every reachability claim must be traceable to the `Class A / B / C` table
92
+ in `secret-guard-analysis.md` §2. A new interception point moves a scenario
93
+ from C to B; it never moves it to "solved".