@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
|
@@ -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".
|