@mokuyoaxis/agent-guard 0.2.3 → 0.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +65 -62
- package/README.zh-CN.md +58 -58
- package/adapters/INTEGRATION.md +4 -4
- package/adapters/claude/README.md +3 -3
- package/adapters/claude/harness/README.md +1 -1
- package/adapters/codex/harness/README.md +2 -2
- package/adapters/dsh/README.md +10 -6
- package/adapters/dsh/harness/README.md +8 -8
- package/adapters/dsh/harness/guard_lab.py +3 -3
- package/adapters/dsh/lib/index.js +1 -1
- package/adapters/kimi-code/README.md +7 -7
- package/adapters/kimi-code/harness/README.md +3 -3
- package/adapters/kimi-code/harness/guard_lab.py +1 -1
- package/core/__init__.py +1 -1
- package/core/classifier.py +41 -16
- package/core/policy.py +11 -4
- package/core/recovery.py +256 -23
- package/core/trash_index.py +193 -0
- package/docs/README.md +104 -0
- package/docs/{architecture.md → design/architecture.md} +31 -6
- package/docs/{compatibility.md → design/compatibility.md} +54 -4
- package/docs/{threat-model.md → design/threat-model.md} +4 -4
- package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +9 -9
- package/docs/guides/trash-index.md +106 -0
- package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +2 -2
- package/docs/{friction.md → history/friction.md} +39 -0
- package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +12 -12
- package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +2 -2
- package/docs/{secret-guard-design.md → history/secret-guard-design.md} +14 -14
- package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
- package/docs/{guard-lab.md → lab/guard-lab.md} +12 -12
- package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +3 -3
- package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +5 -5
- package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
- package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +2 -2
- package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +1 -1
- package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
- package/docs/{release-notes-0.2.3.md → releases/release-notes-0.2.3.md} +3 -3
- package/docs/releases/release-notes-0.2.4.md +89 -0
- package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
- package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
- package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
- package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
- package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
- package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
- package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
- package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
- package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +3 -3
- package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
- package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +1 -1
- package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
- package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +38 -0
- package/skills/delete-guard/references/policy.md +18 -5
- package/skills/delete-guard/scripts/check.py +19 -0
- package/skills/delete-guard/scripts/restore.py +18 -6
- package/skills/delete-guard/scripts/status.py +52 -0
- package/skills/exfil-guard/references/channels.md +1 -1
- /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
- /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
- /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
- /package/docs/{guard-lab-read-trial-task.md → lab/tasks/guard-lab-read-trial-task.md} +0 -0
- /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
- /package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +0 -0
- /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
- /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
- /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
- /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
|
@@ -36,7 +36,7 @@ becomes a BLOCK verdict, never a guess.
|
|
|
36
36
|
This diagram shows a supported native adapter path. An explicit CLI caller
|
|
37
37
|
joins at `check.py`, skipping the adapter prefilter. Neither path implies that
|
|
38
38
|
every harness or tool call is intercepted. Exfil-guard's cooperative text CLI
|
|
39
|
-
is separate; see [harness capabilities](harness-capabilities.md).
|
|
39
|
+
is separate; see [harness capabilities](../guides/harness-capabilities.md).
|
|
40
40
|
|
|
41
41
|
```
|
|
42
42
|
shell command (from a supported native adapter)
|
|
@@ -119,11 +119,11 @@ a harness-owned background sidecar.
|
|
|
119
119
|
|
|
120
120
|
This layout separates accidental access in the intended workflow, not OS
|
|
121
121
|
privileges. A same-UID adversary can inspect or alter both sides. See
|
|
122
|
-
[guard-lab](guard-lab.md) for the evidence semantics and unsupported channels.
|
|
122
|
+
[guard-lab](../lab/guard-lab.md) for the evidence semantics and unsupported channels.
|
|
123
123
|
|
|
124
124
|
## Opt-in DSH text-read boundary
|
|
125
125
|
|
|
126
|
-
The [experimental read prototype](test-report-dsh-read-redaction.md) adds a
|
|
126
|
+
The [experimental read prototype](../reports/test-report-dsh-read-redaction.md) adds a
|
|
127
127
|
separate post-execute path for reviewed, artifact-pinned native text-read
|
|
128
128
|
contracts (local FS and DSH `0.2.0-rc.2` sandbox FS):
|
|
129
129
|
native complete read value → bounded Python stdin worker → existing Core
|
|
@@ -134,7 +134,7 @@ reviewed deletion-only Lab profiles keep this path disabled.
|
|
|
134
134
|
|
|
135
135
|
Native validation uses the actual read, AgentLoop and JSONL backend with a
|
|
136
136
|
deterministic synthetic stream; it checks next-request content and durable
|
|
137
|
-
metadata too; the [current review](test-report-release-readiness-0.2.3.md)
|
|
137
|
+
metadata too; the [current review](../reports/test-report-release-readiness-0.2.3.md)
|
|
138
138
|
records both new-host providers. Pagination, custom finalizers/unreviewed providers, PTC, other tools and
|
|
139
139
|
events before this hook remain outside this boundary. No real-model L2
|
|
140
140
|
evidence follows from the zero-model probe.
|
|
@@ -242,9 +242,24 @@ FORBIDDEN (BLOCK, never askable).
|
|
|
242
242
|
*snapshot* (`stash create` without touching the tree). Both produce a
|
|
243
243
|
txid recorded in manifest + audit. Future compensations (database
|
|
244
244
|
backup/PITR, cloud snapshot) plug into the same slot.
|
|
245
|
+
Hard reset first compares its target tree with untracked and ignored
|
|
246
|
+
paths. Collisions are blocked because the tracked-only stash cannot
|
|
247
|
+
protect them; no automatic untracked archive is created in this version.
|
|
245
248
|
4. **Restore is non-destructive.** It refuses to overwrite existing origin
|
|
246
|
-
paths; `--force` is an explicit human decision.
|
|
247
|
-
|
|
249
|
+
paths; `--force` is an explicit human decision. Relocation paths are checked
|
|
250
|
+
as a batch before mutation and again before each item: destination parent
|
|
251
|
+
chains must stay inside the selected workspace, and source parent chains
|
|
252
|
+
inside their own quarantine transaction. IDs cannot contain path separators
|
|
253
|
+
or traversal; transaction directories cannot redirect to another location.
|
|
254
|
+
The final component is kept unresolved so restoring a symlink restores the
|
|
255
|
+
link. `--force` cannot bypass either boundary check. Before replacing an
|
|
256
|
+
occupant, it uses the existing relocation journal to preserve that version
|
|
257
|
+
in a separate transaction. Preservation failure stops that item; the result
|
|
258
|
+
lists preservation attempts in optional `backup_txids`. Quarantine roots,
|
|
259
|
+
aliases and ancestor paths cannot themselves be moved for preservation.
|
|
260
|
+
This is not an atomic restore: concurrent changes and cross-filesystem
|
|
261
|
+
failures may leave a partial destination, so inspect the reported paths
|
|
262
|
+
and transaction state before retrying.
|
|
248
263
|
5. **Lexical boundaries.** Workspace containment is decided on normalized
|
|
249
264
|
paths; deleting a symlink removes the link, never the target, so symlink
|
|
250
265
|
targets outside the workspace neither leak nor block.
|
|
@@ -255,6 +270,16 @@ FORBIDDEN (BLOCK, never askable).
|
|
|
255
270
|
feed a Lab observation into Core policy or claim to ban model calls. A real
|
|
256
271
|
block would require a host hook or request gateway that owns the call.
|
|
257
272
|
|
|
273
|
+
## Read-only quarantine queries
|
|
274
|
+
|
|
275
|
+
core/trash_index.py exposes list_trash_locations for CLI, agent and future
|
|
276
|
+
trusted local frontend callers. status.py --trash-index supplies explicit
|
|
277
|
+
roots or declared buckets and returns schema version 1. This branch executes
|
|
278
|
+
before ordinary status accounting: no RecoveryEngine, Git, audit writes,
|
|
279
|
+
payload traversal or GC planning. Discovery is bounded, prunes quarantine
|
|
280
|
+
subtrees and deduplicates physical addresses. Metadata presence is a layout
|
|
281
|
+
hint; location results are not authorization for later restore or purge.
|
|
282
|
+
|
|
258
283
|
## Harness adapter model
|
|
259
284
|
|
|
260
285
|
Any agent harness integrates through three optional points, in increasing
|
|
@@ -14,7 +14,7 @@ Harness adapters integrate against exactly four things:
|
|
|
14
14
|
`RELOCATE`.)
|
|
15
15
|
2. **Reason codes** - stable machine-readable strings (`RELOCATE_TREE`,
|
|
16
16
|
`COMPOUND_CWD_DELETE`, `BLOCK_PROTECTED_PATH`, ...). See
|
|
17
|
-
[../skills/delete-guard/references/policy.md](
|
|
17
|
+
[../skills/delete-guard/references/policy.md](../../skills/delete-guard/references/policy.md).
|
|
18
18
|
3. **Explanation field** - human-facing text attached to every verdict.
|
|
19
19
|
4. **check.py exit codes** - `0` proceed/advisory-ok, `2` blocked,
|
|
20
20
|
`3` ask, `1` internal error.
|
|
@@ -31,7 +31,25 @@ While the major version is `0`:
|
|
|
31
31
|
| Manifest record gains a new field | minor (old fields never repurposed) |
|
|
32
32
|
| Manifest record loses/repurposes a field | major + MIGRATION.md |
|
|
33
33
|
| check.py CLI flags removed or re-semanticized | major + MIGRATION.md |
|
|
34
|
-
| Default policy verdict changes for an existing shape | minor + entry in docs/friction.md |
|
|
34
|
+
| Default policy verdict changes for an existing shape | minor + entry in docs/history/friction.md |
|
|
35
|
+
|
|
36
|
+
### 0.2.4 maintenance patch exception
|
|
37
|
+
|
|
38
|
+
For this release, the maintainer explicitly selected `0.2.4` for the recovery
|
|
39
|
+
maintenance fixes and read-only trash query. This is a documented exception
|
|
40
|
+
to the minor-release rules above, not a general relaxation of those rules.
|
|
41
|
+
It adds `BLOCK_GIT_RESET_COLLISION` and refuses hard resets whose collision
|
|
42
|
+
preflight or command context cannot safely establish recoverability.
|
|
43
|
+
Relocation restore also refuses invalid source/destination boundaries and
|
|
44
|
+
requires preservation before a forced overwrite. See
|
|
45
|
+
[F24](../history/friction.md#f24--hard-reset-could-destroy-content-outside-the-tracked-snapshot)
|
|
46
|
+
and [F25](../history/friction.md#f25--restore-trusted-paths-and-removed-an-occupied-destination-before-recovery).
|
|
47
|
+
|
|
48
|
+
The reason string is additive; existing strings and decision classes are not
|
|
49
|
+
renamed. Existing CLI parameters and exit codes retain their roles. Optional
|
|
50
|
+
`backup_txids` and the separate trash-query schema are described below.
|
|
51
|
+
No manifest migration or new transaction strategy is introduced. Consumers
|
|
52
|
+
must accept the additional refusal reason and ignore unknown optional fields.
|
|
35
53
|
|
|
36
54
|
## Additive surfaces since v0.1.1
|
|
37
55
|
|
|
@@ -93,6 +111,35 @@ cmd/PowerShell execution through each harness, hook-selected dialect wiring,
|
|
|
93
111
|
broader UNC/device paths, module auto-loading and full-suite Windows
|
|
94
112
|
portability remain unverified.
|
|
95
113
|
|
|
114
|
+
### 0.2.4 trash location query
|
|
115
|
+
|
|
116
|
+
status.py --trash-index is an additive read-only mode, with --root, --trash,
|
|
117
|
+
--max-depth and --max-entries. Ordinary status arguments and result fields
|
|
118
|
+
keep their prior behavior. Index-specific options require index mode.
|
|
119
|
+
Its JSON is a separate schema_version=1 contract documented in
|
|
120
|
+
[trash-index.md](../guides/trash-index.md): count is candidate locations,
|
|
121
|
+
identified_count is layout-identified locations, and complete applies only
|
|
122
|
+
to the declared scope. Exit 0 means complete, 1 means partial results with
|
|
123
|
+
errors, and 2 means invalid arguments. The shared core query and this CLI
|
|
124
|
+
are additions in 0.2.4, with no storage or manifest migration.
|
|
125
|
+
|
|
126
|
+
### 0.2.4 forced-restore preservation
|
|
127
|
+
|
|
128
|
+
Forced relocation restores now preserve an existing occupant with the normal
|
|
129
|
+
relocation transaction and journal before replacing it. Existing CLI parameters,
|
|
130
|
+
exit codes and result fields retain their roles. The JSON result may add
|
|
131
|
+
`backup_txids`, a list of preservation attempts; inspect transaction state and
|
|
132
|
+
files after errors rather than treating an ID as proof of a complete copy.
|
|
133
|
+
Results without a preservation attempt omit this field. Text output identifies
|
|
134
|
+
the same attempts. CLI audit events also include these IDs when present.
|
|
135
|
+
|
|
136
|
+
The preservation transaction uses existing `tx-start`/`relocate-intent`/
|
|
137
|
+
`relocate` records and correlates through the existing `meta` object; no
|
|
138
|
+
manifest migration or new transaction strategy is introduced. Restore journal
|
|
139
|
+
or CLI audit write failure reports a non-success result while retaining the
|
|
140
|
+
filesystem outcome and preservation IDs for inspection. These changes belong
|
|
141
|
+
to 0.2.4; the published `0.2.3` artifact does not include them.
|
|
142
|
+
|
|
96
143
|
### PowerShell parameter prefixes
|
|
97
144
|
|
|
98
145
|
PowerShell resolves a parameter by unambiguous prefix, so `ri build -r -fo`
|
|
@@ -115,8 +162,9 @@ Every expansion is recorded in the op notes for audit.
|
|
|
115
162
|
## Verdict changes since v0.1.1
|
|
116
163
|
|
|
117
164
|
A changed default verdict for an existing shape is a **minor** release and
|
|
118
|
-
requires an entry in [friction.md](friction.md) - never a silent behaviour
|
|
119
|
-
shift.
|
|
165
|
+
requires an entry in [friction.md](../history/friction.md) - never a silent behaviour
|
|
166
|
+
shift. The explicit 0.2.4 exception is recorded above. Additive reason codes
|
|
167
|
+
are listed above; this table is for shapes
|
|
120
168
|
whose *existing* verdict moved.
|
|
121
169
|
|
|
122
170
|
| Shape | Was | Now | Why |
|
|
@@ -125,6 +173,8 @@ whose *existing* verdict moved.
|
|
|
125
173
|
| `cd ... && git push --force` | `ASK` / `COMPOUND_CWD_DELETE` | `BLOCK` / `BLOCK_FORCE_PUSH` | A shape rule cannot downgrade a position-independent hard refusal (F1) |
|
|
126
174
|
| `cd ... && rm` with an out-of-workspace, protected, or unknowable target | `ASK` / `COMPOUND_CWD_DELETE` | The applicable hard `BLOCK` | F1 describes compensation difficulty, not permission to cross a boundary |
|
|
127
175
|
| Attached or newline-separated destructive commands (`echo ok;rm ...`, `echo ok` followed by newline and `rm ...`) | Could miss the destructive segment | Classifies and applies its normal policy | POSIX command boundaries must be preserved by the lexer |
|
|
176
|
+
| `git reset --hard [ref]` with untracked/ignored or quarantine collisions | Tracked-only `SNAPSHOT` could proceed | `BLOCK` / `BLOCK_GIT_RESET_COLLISION` | Stash does not preserve the colliding content (0.2.4 maintenance exception, F24) |
|
|
177
|
+
| Hard reset with uncertain preflight or unsupported compound/wrapper context | Could proceed or ask despite incomplete coverage | `BLOCK_UNDETERMINABLE_EFFECT` before compensation | Snapshot and preflight must describe the actual Git context (F24) |
|
|
128
178
|
|
|
129
179
|
Unchanged on purpose: a genuine compensation fault (`git stash create`
|
|
130
180
|
failing, a relocation that does not cover every target, an audit intent
|
|
@@ -31,7 +31,7 @@ bypass. Therefore:
|
|
|
31
31
|
| 4 | Agent edits/removes `manifest.jsonl` to hide provenance | Append-only by convention; audit log is separate; adapters may ship both off-box | Tamper-evident only if exported |
|
|
32
32
|
| 5 | Symlink confusion (delete link vs target, trailing slash dereference) | Lexical boundary analysis; link relocation preserves the link; realpath recorded | Low |
|
|
33
33
|
| 6 | TOCTOU between classification and execution | Window is milliseconds inside one process; adapters that need more should classify-and-execute atomically | Small, acknowledged |
|
|
34
|
-
| 7 | Destructive restore |
|
|
34
|
+
| 7 | Destructive restore | Relocation destinations and sources are checked against the workspace and their quarantine transaction. IDs and directory locations are validated; leaf symlinks retain their semantics. Human `--force` preserves an occupant through a separate relocation transaction before replacement; failed preservation stops that item | Checks and moves are not atomic against concurrent changes. Cross-filesystem failures may leave a partial destination or backup; inspect the filesystem and reported transaction IDs. Preserved versions add storage use and follow existing explicit GC |
|
|
35
35
|
| 8 | Quarantine bloat turns `.agent-trash` into a liability (exfil via packaging, disk exhaustion) | Existing `.gitignore` or `.git/info/exclude`; `status.py` exposes size; 30-day/5-GiB soft eligibility with explicit audited purge | A human or scheduler must execute purge; audit is retained |
|
|
36
36
|
|
|
37
37
|
## guard-lab diagnostic boundary
|
|
@@ -55,15 +55,15 @@ the integrity of a single run's evidence, not real credentials.
|
|
|
55
55
|
| A mixed harness transcript is mislabeled as model output | Documentation requires role/channel separation before scanning; reports disclose that scan input and stage are user-selected | Generic Lab does not authenticate vendor-specific transcript provenance |
|
|
56
56
|
|
|
57
57
|
The Lab controller is user-facing and is not an agent Skill. Never place real
|
|
58
|
-
secrets or irreplaceable work in its fixture. See [guard-lab](guard-lab.md) for
|
|
58
|
+
secrets or irreplaceable work in its fixture. See [guard-lab](../lab/guard-lab.md) for
|
|
59
59
|
the exact observation and report semantics.
|
|
60
60
|
|
|
61
61
|
## Experimental DSH text-read redaction
|
|
62
62
|
|
|
63
|
-
The default-off [native read prototype](test-report-dsh-read-redaction.md)
|
|
63
|
+
The default-off [native read prototype](../reports/test-report-dsh-read-redaction.md)
|
|
64
64
|
mediates complete text-read results in reviewed, artifact-pinned local-FS and
|
|
65
65
|
DSH `0.2.0-rc.2` sandbox-FS compositions; see the
|
|
66
|
-
[current review](test-report-release-readiness-0.2.3.md). It
|
|
66
|
+
[current review](../reports/test-report-release-readiness-0.2.3.md). It
|
|
67
67
|
uses Core patterns, replaces structured values and regenerates model content
|
|
68
68
|
and presentation metadata. Its actual AgentLoop/JSONL probe uses synthetic
|
|
69
69
|
streams and establishes no real-model L2 mitigation result.
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
The Python Core and CLI are harness-neutral. A Skill or CLI being usable in a
|
|
4
4
|
host does **not** mean that host intercepts tool calls, and an adapter returning
|
|
5
5
|
`BLOCK` does **not** by itself prove the host prevented execution.
|
|
6
|
-
For an unlisted host, use the [self-adaptation guide](
|
|
6
|
+
For an unlisted host, use the [self-adaptation guide](../../adapters/INTEGRATION.md)
|
|
7
7
|
and keep its native-interception status `UNVERIFIED` until independently tested.
|
|
8
8
|
|
|
9
9
|
## Evidence levels
|
|
@@ -42,14 +42,14 @@ bounded "Enforcement observed" evidence only for that root-agent Bash call.
|
|
|
42
42
|
|
|
43
43
|
| Host / tested version | Entry and scope | ASK mapping | Highest evidence for current path | Important gap |
|
|
44
44
|
|---|---|---|---|---|
|
|
45
|
-
| Claude Code 2.1.270 / 2.1.273 (post-0.2.0 bridge) | `PreToolUse` for `Bash`; shared Core via Python and POSIX startup bridge | Native `permissionDecision: ask` (headless runs need an approver) | Real CLI/hook with scripted model endpoint: ALLOW, BLOCK, headless ASK, injected Python failure; see [report](test-report-claude-code-harness.md) | Hook absence/timeout, Windows bridge, other tools, arbitrary subagents and real model behavior are not covered. |
|
|
46
|
-
| DSH 0.1.5-rc.1 | `tools/pre-execute` for `bash`, plus model tools and prompt section | `kind: ask` | [Real host, no-model packaged-plugin probe](test-report-dsh-0.1.5-rc.1.md): benign execution, Core `BLOCK`, absent bypass marker, durable audit, and loaded-adapter Core-startup failure. A separate [real-model Lab baseline](test-report-dsh-guard-lab.md) stayed quiet with guard off, so it produced no L2 claim. | Model-proposed destructive `bash` enforcement, subagents, concurrency, ASK UI, hook absence and host upgrades remain unverified. The opt-in read path has separate evidence below. |
|
|
47
|
-
| DSH CLI 0.1.5-rc.1 / tools and FS 0.1.5-rc.2 / Node 22 | Default-off prototype for complete native text `read`; replaces structured value | Core ASK/BLOCK withheld | [Zero-model native probe](test-report-dsh-read-redaction.md): next request and durable JSONL. [Official Flash direct-read off/on](test-report-dsh-real-followup.md): supported synthetic secrets absent from guarded content/meta/session; useful config and line numbers preserved | Injection L2, pagination, custom finalizers/providers, PTC, early events, original tool arguments and other tools are outside this claim. Outgoing real-provider request bytes were not independently captured. |
|
|
48
|
-
| DSH 0.2.0-rc.2 / Node 22 | Default deletion adapter; optional complete text-read protection on reviewed local/sandbox FS | Native ASK; Core read ASK/BLOCK withheld | [
|
|
49
|
-
| Kimi Code 0.42.0 / 2.1.1 | `PreToolUse` for `Bash`; reuses Claude mapping with a host-specific ASK override | Adapter hard-denies ASK; live ASK behavior was sampled only on 0.42.0 | [Bounded host-level tests](test-report-kimi-code-block.md): authenticated 2.1.1 root-Bash sentinel PASS on an OAuth official model and a second configured model route; older 0.42.0 root/subagent BLOCK, recoverable deletion/restore and pre-adapter Python-failure refusal | Client records identify the requested route, not the remote model weights. 2.1.1 subagents, concurrency, ASK UI and fault injection remain unverified; hook absence/timeout/bridge-spawn failure and non-Bash tools remain outside the claim. |
|
|
50
|
-
| Codex CLI 0.154.0 (tested session) | Skill and production CLI on older source; no native interception adapter in this repository | CLI reports ASK; agent/user must decide | CLI acceptance only; see [report](test-report-codex-gpt-6-astra-high.md) | No automatic tool-call enforcement claim. |
|
|
51
|
-
| ZCode (Windows session; host version unrecorded) | Historical Skill/CLI and process-type `PreToolUse` trial | One ASK prompted the user; persistent approval then skipped the hook | [Windows evaluation](test-report-zcode-glm-flash.md) | No current-version native enforcement claim; the observed permission bypass and real Windows end-to-end gaps remain. |
|
|
52
|
-
| Other / unlisted hosts | No supported adapter by default | Host-specific | [Self-adaptation checklist](
|
|
45
|
+
| Claude Code 2.1.270 / 2.1.273 (post-0.2.0 bridge) | `PreToolUse` for `Bash`; shared Core via Python and POSIX startup bridge | Native `permissionDecision: ask` (headless runs need an approver) | Real CLI/hook with scripted model endpoint: ALLOW, BLOCK, headless ASK, injected Python failure; see [report](../reports/test-report-claude-code-harness.md) | Hook absence/timeout, Windows bridge, other tools, arbitrary subagents and real model behavior are not covered. |
|
|
46
|
+
| DSH 0.1.5-rc.1 | `tools/pre-execute` for `bash`, plus model tools and prompt section | `kind: ask` | [Real host, no-model packaged-plugin probe](../reports/test-report-dsh-0.1.5-rc.1.md): benign execution, Core `BLOCK`, absent bypass marker, durable audit, and loaded-adapter Core-startup failure. A separate [real-model Lab baseline](../reports/test-report-dsh-guard-lab.md) stayed quiet with guard off, so it produced no L2 claim. | Model-proposed destructive `bash` enforcement, subagents, concurrency, ASK UI, hook absence and host upgrades remain unverified. The opt-in read path has separate evidence below. |
|
|
47
|
+
| DSH CLI 0.1.5-rc.1 / tools and FS 0.1.5-rc.2 / Node 22 | Default-off prototype for complete native text `read`; replaces structured value | Core ASK/BLOCK withheld | [Zero-model native probe](../reports/test-report-dsh-read-redaction.md): next request and durable JSONL. [Official Flash direct-read off/on](../reports/test-report-dsh-real-followup.md): supported synthetic secrets absent from guarded content/meta/session; useful config and line numbers preserved | Injection L2, pagination, custom finalizers/providers, PTC, early events, original tool arguments and other tools are outside this claim. Outgoing real-provider request bytes were not independently captured. |
|
|
48
|
+
| DSH 0.2.0-rc.2 / Node 22 | Default deletion adapter; optional complete text-read protection on reviewed local/sandbox FS; sampled PTC SDK Bash calls | Native ASK; Core read ASK/BLOCK withheld | [0.2.3 native review](../reports/test-report-release-readiness-0.2.3.md): deletion/read/next synthetic request/JSONL checks, zero external model calls. [0.2.4 official Flash PTC](../reports/test-report-dsh-0.2.4-ptc.md): real root and one child submit inner Bash reset collisions; matching refusal audits and intact files | Original root PTC task did not complete; a separate summary did. Arbitrary PTC Node APIs, other model-proposed calls, concurrency, ASK UI, Web activation and injection L2 remain unverified. Historical pending captures remain inconclusive. |
|
|
49
|
+
| Kimi Code 0.42.0 / 2.1.1 | `PreToolUse` for `Bash`; reuses Claude mapping with a host-specific ASK override | Adapter hard-denies ASK; live ASK behavior was sampled only on 0.42.0 | [Bounded host-level tests](../reports/test-report-kimi-code-block.md): authenticated 2.1.1 root-Bash sentinel PASS on an OAuth official model and a second configured model route; older 0.42.0 root/subagent BLOCK, recoverable deletion/restore and pre-adapter Python-failure refusal | Client records identify the requested route, not the remote model weights. 2.1.1 subagents, concurrency, ASK UI and fault injection remain unverified; hook absence/timeout/bridge-spawn failure and non-Bash tools remain outside the claim. |
|
|
50
|
+
| Codex CLI 0.154.0 (tested session) | Skill and production CLI on older source; no native interception adapter in this repository | CLI reports ASK; agent/user must decide | CLI acceptance only; see [report](../reports/test-report-codex-gpt-6-astra-high.md) | No automatic tool-call enforcement claim. |
|
|
51
|
+
| ZCode (Windows session; host version unrecorded) | Historical Skill/CLI and process-type `PreToolUse` trial | One ASK prompted the user; persistent approval then skipped the hook | [Windows evaluation](../reports/test-report-zcode-glm-flash.md) | No current-version native enforcement claim; the observed permission bypass and real Windows end-to-end gaps remain. |
|
|
52
|
+
| Other / unlisted hosts | No supported adapter by default | Host-specific | [Self-adaptation checklist](../../adapters/INTEGRATION.md), not a verification result | Requires a blocking pre-tool contract and independent host evidence; otherwise Skill/CLI only. |
|
|
53
53
|
|
|
54
54
|
The default adapters address destructive **shell** calls. Exfil-guard also has
|
|
55
55
|
a CLI/cooperative path and the narrowly scoped, opt-in DSH text-read prototype
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# Read-only trash locations / 垃圾桶只读位置查询
|
|
2
|
+
|
|
3
|
+
This is the 0.2.4 query interface for CLI, agent and future frontend
|
|
4
|
+
callers. It lists locations within a declared scope, without reading recovery
|
|
5
|
+
contents or changing storage. The published 0.2.3 artifact does not include it.
|
|
6
|
+
|
|
7
|
+
这是 0.2.4 的查询接口,可从安装后的 CLI 或本地源码使用。
|
|
8
|
+
用户可直接查看,Agent 可解释同一份结果,未来前端
|
|
9
|
+
可复用相同函数/JSON。当前不提供页面或操作服务,索引地址不代表清理授权。
|
|
10
|
+
|
|
11
|
+
## CLI
|
|
12
|
+
|
|
13
|
+
The existing status command keeps its current-project mode. Add --trash-index
|
|
14
|
+
for the location query; an installed command uses the same flags.
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
# Default: current directory, depth 3, 10000 examined entries.
|
|
18
|
+
python3 skills/delete-guard/scripts/status.py --trash-index
|
|
19
|
+
|
|
20
|
+
# A specific project collection; repeated roots are allowed.
|
|
21
|
+
agent-guard-status --trash-index --root ~/projects --max-depth 3 --json
|
|
22
|
+
|
|
23
|
+
# Declare a custom/external bucket; with only --trash, no root is walked.
|
|
24
|
+
agent-guard-status --trash-index --trash /path/to/custom-store --json
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
默认搜索当前目录;若没有 --root 或 --trash,可纳入当前 AGENT_GUARD_TRASH
|
|
28
|
+
配置。显式 --root 不附加环境中的其他位置;需要外部桶时使用 --trash。
|
|
29
|
+
|
|
30
|
+
max_depth counts directories below each root. At depth 0, the root's own
|
|
31
|
+
.agent-trash is still checked. Found buckets are pruned, including an explicit
|
|
32
|
+
root named .agent-trash. Ordinary child directory symlinks are not walked;
|
|
33
|
+
explicit roots/buckets may be aliases, and results deduplicate physical paths.
|
|
34
|
+
|
|
35
|
+
默认跳过 .git、node_modules、.internal、__pycache__ 子目录。显式将这些目录
|
|
36
|
+
作为 root 时会按所给范围检查。max_entries 限制检查的路径/目录项数;触及
|
|
37
|
+
限制会保留部分结果并报告错误。它不是文件系统调用的墙钟超时。
|
|
38
|
+
|
|
39
|
+
No payload, transaction, byte-size or GC eligibility scan is performed.
|
|
40
|
+
Expected manifest/audit/state files and the sessions directory are only
|
|
41
|
+
lstat'ed. These are layout hints, not authenticated ownership or complete
|
|
42
|
+
backup evidence. A linked marker file alone is not accepted as a regular marker.
|
|
43
|
+
|
|
44
|
+
退出码:0 完整查询;1 部分结果(读取/路径/预算错误);2 参数错误。
|
|
45
|
+
complete 只指声明深度、排除项和范围内的读取完成,不代表全机覆盖或原子快照。
|
|
46
|
+
|
|
47
|
+
## Shared backend hook
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
from core.trash_index import list_trash_locations
|
|
51
|
+
|
|
52
|
+
result = list_trash_locations(
|
|
53
|
+
["/path/to/projects"],
|
|
54
|
+
trash_paths=["/path/to/custom-store"],
|
|
55
|
+
max_depth=3,
|
|
56
|
+
max_entries=10000,
|
|
57
|
+
)
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Provide a sequence of text paths or Path objects. The function validates
|
|
61
|
+
limits and paths before traversal and raises ValueError for invalid input.
|
|
62
|
+
It has no environment-selected default roots; the CLI supplies its context.
|
|
63
|
+
It creates no layout, modifies no Git metadata, writes no audit and constructs
|
|
64
|
+
no RecoveryEngine. Backend callers must choose their own trusted scope.
|
|
65
|
+
|
|
66
|
+
## JSON schema version 1
|
|
67
|
+
|
|
68
|
+
| Field | Meaning |
|
|
69
|
+
|---|---|
|
|
70
|
+
| schema_version | 1; callers should tolerate additive fields |
|
|
71
|
+
| roots / trash_paths | Normalized absolute search roots / declared buckets |
|
|
72
|
+
| max_depth / max_entries | Requested bounds |
|
|
73
|
+
| excluded_dirs | Names pruned below roots |
|
|
74
|
+
| examined | Charged paths/directory entries, bounded by max_entries |
|
|
75
|
+
| complete | No read/path/budget errors within the declared scope |
|
|
76
|
+
| count | Unique location candidates, including unconfirmed/unreadable rows |
|
|
77
|
+
| identified_count | Rows with status metadata_present |
|
|
78
|
+
| entries | Deterministically ordered rows |
|
|
79
|
+
| errors | Partial-query errors as path + static code |
|
|
80
|
+
|
|
81
|
+
Each row contains trash_root (first sorted location spelling),
|
|
82
|
+
resolved_trash_root, directory (that spelling's parent), locations (all
|
|
83
|
+
encountered aliases), sources (declared/discovered) and status.
|
|
84
|
+
directory is a location hint, not verified workspace ownership.
|
|
85
|
+
|
|
86
|
+
| Status | Meaning |
|
|
87
|
+
|---|---|
|
|
88
|
+
| metadata_present | At least one expected regular marker file or sessions directory exists |
|
|
89
|
+
| unconfirmed | A named/declared directory exists, but no usable marker was found |
|
|
90
|
+
| unreadable | Marker inspection failed; identification is unknown |
|
|
91
|
+
|
|
92
|
+
Error codes: NOT_FOUND, NOT_DIRECTORY, PERMISSION_DENIED, IO_ERROR,
|
|
93
|
+
ENTRY_LIMIT_REACHED. Errors contain paths but no raw OS exception text.
|
|
94
|
+
Missing or non-directory requested locations appear in errors and are not
|
|
95
|
+
counted. Concurrent filesystem changes can affect a query snapshot.
|
|
96
|
+
|
|
97
|
+
## Agent and future UI usage
|
|
98
|
+
|
|
99
|
+
用户问“有哪些垃圾桶/有多少/在哪”时,Agent 应按当前目录或用户指定范围
|
|
100
|
+
查询,分别报告候选数量、布局识别数量和错误。无法检查不能说成不存在;自己
|
|
101
|
+
补查的信息应区分来源。Native status tools that lack index flags remain
|
|
102
|
+
current-project tools; invoke this CLI for a cross-project location query.
|
|
103
|
+
|
|
104
|
+
未来只读界面直接读取上述 JSON。恢复或清理应走独立操作入口,重新验证可信
|
|
105
|
+
workspace、trash、事务、当前路径和权限;不能将扫描地址或缓存 JSON 当作授权。
|
|
106
|
+
本接口不改变分散存储布局,也不读取配置或恢复文件中的秘密值。
|
|
@@ -105,7 +105,7 @@ Collapsing these labels makes a green build look stronger than the evidence
|
|
|
105
105
|
supports. A trustworthy recovery therefore needs an evidence ledger, replay
|
|
106
106
|
reports, deterministic reruns, and explicit gap markers.
|
|
107
107
|
|
|
108
|
-
These requirements became the [`recovery-audit`](
|
|
108
|
+
These requirements became the [`recovery-audit`](../../skills/recovery-audit/SKILL.md)
|
|
109
109
|
Skill. It complements `delete-guard` and `exfil-guard`:
|
|
110
110
|
|
|
111
111
|
```text
|
|
@@ -153,7 +153,7 @@ after an incident -> recovery-audit
|
|
|
153
153
|
|
|
154
154
|
The project should continue to describe itself as reliability infrastructure
|
|
155
155
|
with human escalation, not as a boundary against a malicious or fully
|
|
156
|
-
privileged process. See [`docs/threat-model.md`](threat-model.md).
|
|
156
|
+
privileged process. See [`docs/design/threat-model.md`](../design/threat-model.md).
|
|
157
157
|
|
|
158
158
|
## 7. Public evidence policy
|
|
159
159
|
|
|
@@ -423,3 +423,42 @@ and the legacy broad sk- format has no complete issuance contract established
|
|
|
423
423
|
in this review. Those boundaries retain protection and remain explicit review
|
|
424
424
|
items. The narrowed structural rules do not certify a token's signature,
|
|
425
425
|
claims, actual issuance or authorization.
|
|
426
|
+
|
|
427
|
+
## F24 · Hard reset could destroy content outside the tracked snapshot
|
|
428
|
+
|
|
429
|
+
A tracked-only stash does not contain untracked or ignored bytes. Git can
|
|
430
|
+
remove those bytes when the reset target replaces a file or an ancestor
|
|
431
|
+
directory, including quarantine storage. The 2026-10-05 independent review
|
|
432
|
+
reproduced this with disposable fixtures; no user worktree was reset.
|
|
433
|
+
|
|
434
|
+
**Fixed in 0.2.4:** read-only preflight checks the target tree
|
|
435
|
+
against untracked/ignored paths before compensation. Collisions yield
|
|
436
|
+
`BLOCK_GIT_RESET_COLLISION`; incomplete enumeration, submodules and unsupported
|
|
437
|
+
compound/wrapper contexts yield `BLOCK_UNDETERMINABLE_EFFECT`. Supported
|
|
438
|
+
standalone collision-free reset still snapshots tracked changes first.
|
|
439
|
+
There is no automatic untracked archive. Regression:
|
|
440
|
+
`tests/test_git_reset_safety.py` (30 cases) and two added policy cases.
|
|
441
|
+
|
|
442
|
+
This deliberately tightens default behavior and adds a reason string.
|
|
443
|
+
The maintainer-selected 0.2.4 patch exception is recorded in the
|
|
444
|
+
[compatibility contract](../design/compatibility.md#024-maintenance-patch-exception).
|
|
445
|
+
|
|
446
|
+
## F25 · Restore trusted paths and removed an occupied destination before recovery
|
|
447
|
+
|
|
448
|
+
A changed parent symlink could redirect a recorded source or destination;
|
|
449
|
+
transaction IDs and directories also needed containment checks. Forced
|
|
450
|
+
restore removed the current occupant before attempting recovery, so a later
|
|
451
|
+
move failure could lose the current version.
|
|
452
|
+
|
|
453
|
+
**Fixed in 0.2.4:** restore preflights the selected workspace,
|
|
454
|
+
transaction directory and source parent chains, then checks each item again.
|
|
455
|
+
Final symlinks retain their own location semantics. Force cannot override
|
|
456
|
+
containment; an occupied destination is preserved in a normal relocation
|
|
457
|
+
transaction before recovery. Preservation failure stops that item. Returned
|
|
458
|
+
`backup_txids` includes attempted backups, not a guarantee that each completed.
|
|
459
|
+
Journal/audit errors preserve the filesystem report and IDs for inspection.
|
|
460
|
+
|
|
461
|
+
Regression: `tests/test_restore_boundary.py` (14),
|
|
462
|
+
`tests/test_restore_source.py` (14), and `tests/test_restore_force.py` (22).
|
|
463
|
+
These are sequential checks, not atomic same-UID isolation; cross-device
|
|
464
|
+
copy failures can leave partial data requiring inspection.
|
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
Status: **historical requirements analysis, written before implementation.**
|
|
4
4
|
This document records the original scope and design questions; it does not
|
|
5
5
|
define the current contract. Current behavior is documented in the
|
|
6
|
-
[Skill](
|
|
7
|
-
[rule reference](
|
|
6
|
+
[Skill](../../skills/exfil-guard/SKILL.md) and
|
|
7
|
+
[rule reference](../../skills/exfil-guard/references/rules.md).
|
|
8
8
|
|
|
9
9
|
Working name: **`exfil-guard`**. The two user requests (secret leakage,
|
|
10
10
|
local-path leakage) are two rule families, not two skills — §3 argues
|
|
@@ -15,7 +15,7 @@ this explicitly.
|
|
|
15
15
|
## 0. The constraint that shapes everything
|
|
16
16
|
|
|
17
17
|
agent-guard is **reliability infrastructure, not a security sandbox**
|
|
18
|
-
(`docs/threat-model.md`). Its own threat model says a determined agent
|
|
18
|
+
(`docs/design/threat-model.md`). Its own threat model says a determined agent
|
|
19
19
|
with equal OS privileges can always bypass it. Every claim in this
|
|
20
20
|
document must survive that sentence.
|
|
21
21
|
|
|
@@ -71,7 +71,7 @@ Two consequences that are non-negotiable in the design doc:
|
|
|
71
71
|
2. **The audit log is itself an egress channel** (threat #7). Recording a
|
|
72
72
|
secret in `audit.jsonl` recreates the leak in a durable file *and*
|
|
73
73
|
ships it in bug reports. Precedent already exists in-repo:
|
|
74
|
-
`docs/publishing-from-ephemeral-environments.md` is the reason
|
|
74
|
+
`docs/guides/publishing-from-ephemeral-environments.md` is the reason
|
|
75
75
|
`SECURITY.md` documents "credential-adjacent wording" scanner hits.
|
|
76
76
|
|
|
77
77
|
---
|
|
@@ -98,7 +98,7 @@ a git remote and an LLM API), not absolute risk scores.
|
|
|
98
98
|
| 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 |
|
|
99
99
|
| 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) |
|
|
100
100
|
| 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) |
|
|
101
|
-
| 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
|
+
| 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/design/threat-model.md` #8 |
|
|
102
102
|
| 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 |
|
|
103
103
|
|
|
104
104
|
**Related delete-guard risk:** S2/S8 are the *same failure
|
|
@@ -146,7 +146,7 @@ rules, rather than treating them symmetrically (§4.4).
|
|
|
146
146
|
|
|
147
147
|
### 2.1 The existing interception model, restated
|
|
148
148
|
|
|
149
|
-
From `docs/architecture.md`, agent-guard has exactly **one** enforcement
|
|
149
|
+
From `docs/design/architecture.md`, agent-guard has exactly **one** enforcement
|
|
150
150
|
point today:
|
|
151
151
|
|
|
152
152
|
```
|
|
@@ -203,7 +203,7 @@ otherwise is what turns a reliability tool into a false security claim.
|
|
|
203
203
|
residual risk as threat-model #1 ("agent deletes via its own script
|
|
204
204
|
calling `unlink()`") — and the same upgrade path (mediating service,
|
|
205
205
|
not shell interception).
|
|
206
|
-
2. **Content produced *inside* a program.** B1 in `docs/architecture.md`
|
|
206
|
+
2. **Content produced *inside* a program.** B1 in `docs/design/architecture.md`
|
|
207
207
|
("the guard analyzes the command's direct effect; it does not infer the
|
|
208
208
|
internal behavior of arbitrary programs") applies verbatim. `python
|
|
209
209
|
app.py` whose logger writes a token is invisible. We see the *intent to
|
|
@@ -229,7 +229,7 @@ The cheap, high-yield wins are **Class B file-write/intercepted-request**
|
|
|
229
229
|
(from 0% coverage today) and **Class A commit-message/push scans**. S1 —
|
|
230
230
|
the scenario the user listed first — is the *hardest* one, and shipping a
|
|
231
231
|
`secret-guard` that claims to cover it would be the exact over-claim
|
|
232
|
-
`docs/threat-model.md` forbids.
|
|
232
|
+
`docs/design/threat-model.md` forbids.
|
|
233
233
|
|
|
234
234
|
---
|
|
235
235
|
|
|
@@ -280,7 +280,7 @@ mechanical later; the reverse (merging two shipped skills) is not.
|
|
|
280
280
|
|
|
281
281
|
| Component | Reuse | Why |
|
|
282
282
|
|---|---|---|
|
|
283
|
-
| Decision Protocol (decision + ReasonCode + Explanation + payload) | **yes** | Frozen adapter surface (`docs/compatibility.md`); adapters already map it |
|
|
283
|
+
| Decision Protocol (decision + ReasonCode + Explanation + payload) | **yes** | Frozen adapter surface (`docs/design/compatibility.md`); adapters already map it |
|
|
284
284
|
| `policy.worst()` aggregation + rank table | **yes**, extended | One verdict per emission must be the existing aggregate |
|
|
285
285
|
| `core/audit.py` append/tail/fsync/JSONL | **yes**, new record events | Same "append-only, dumb, never mutated" discipline |
|
|
286
286
|
| NORMAL/RESTRICTED capability model | **yes** | Unchanged semantics; RESTRICTED should *tighten* exfil rules, never loosen |
|
|
@@ -330,7 +330,7 @@ Cross-cutting:
|
|
|
330
330
|
| `BLOCK_EXFIL_RULE_CONFIG_INVALID` | BLOCK | Malformed user rule (same class as `BLOCK_DIALECT_UNKNOWN`) |
|
|
331
331
|
|
|
332
332
|
**Compatibility note:** adding decision classes and reason codes is a
|
|
333
|
-
*minor* release under `docs/compatibility.md` ("New reason code
|
|
333
|
+
*minor* release under `docs/design/compatibility.md` ("New reason code
|
|
334
334
|
(additive) → minor"; "New decision class → minor, announced in README").
|
|
335
335
|
`SANITIZE` must be announced in the README, and every adapter must state
|
|
336
336
|
its native mapping (ask §4.4 for harnesses without re-write capability).
|
|
@@ -405,7 +405,7 @@ Stated here so the design doc cannot quietly expand scope:
|
|
|
405
405
|
2. **Not a history scrubbing tool.** exfil-guard prevents; if it fails, the
|
|
406
406
|
human runs `filter-repo`. A guard that tries to also be a rewriting tool
|
|
407
407
|
becomes a second destruction vector — exactly the reasoning behind
|
|
408
|
-
"restore is non-destructive" (`docs/architecture.md` #4).
|
|
408
|
+
"restore is non-destructive" (`docs/design/architecture.md` #4).
|
|
409
409
|
3. **Not a full file scanner / not a gitleaks replacement.** Scope is
|
|
410
410
|
*egress-relevant* content the guard can reach, not "all secrets on the
|
|
411
411
|
disk".
|
|
@@ -413,5 +413,5 @@ Stated here so the design doc cannot quietly expand scope:
|
|
|
413
413
|
per-destination policy server.
|
|
414
414
|
5. **Not a claim of coverage over Unreachable channels (§2.4).** Every doc
|
|
415
415
|
must carry this limitation, in the same spirit as
|
|
416
|
-
`docs/threat-model.md`'s "What would upgrade this to a security
|
|
416
|
+
`docs/design/threat-model.md`'s "What would upgrade this to a security
|
|
417
417
|
boundary".
|
|
@@ -4,7 +4,7 @@ This historical architecture sketch accompanies
|
|
|
4
4
|
[the requirements analysis](secret-guard-analysis.md) and
|
|
5
5
|
[design](secret-guard-design.md). Pre-write and pre-request interception
|
|
6
6
|
below describe proposed adapter points. Current supported paths are listed
|
|
7
|
-
in the [capability matrix](harness-capabilities.md).
|
|
7
|
+
in the [capability matrix](../guides/harness-capabilities.md).
|
|
8
8
|
|
|
9
9
|
## One-paragraph summary
|
|
10
10
|
|
|
@@ -80,7 +80,7 @@ The cross-cutting rule still holds and now bites harder:
|
|
|
80
80
|
|
|
81
81
|
## What this feature may and may not claim
|
|
82
82
|
|
|
83
|
-
Following `docs/threat-model.md`, and stated in the README when it lands:
|
|
83
|
+
Following `docs/design/threat-model.md`, and stated in the README when it lands:
|
|
84
84
|
|
|
85
85
|
- **May claim:** catches *accidental* disclosure on channels the harness
|
|
86
86
|
routes through a hook; one decision trail for every verdict; redaction
|
|
@@ -3,15 +3,15 @@
|
|
|
3
3
|
Status: **historical design, written before implementation.** Proposed
|
|
4
4
|
modules and interception points below are design candidates, not a list of
|
|
5
5
|
shipped features. For current behavior, see the
|
|
6
|
-
[Skill](
|
|
7
|
-
[rule reference](
|
|
6
|
+
[Skill](../../skills/exfil-guard/SKILL.md) and
|
|
7
|
+
[rule reference](../../skills/exfil-guard/references/rules.md).
|
|
8
8
|
The design adds `SANITIZE` and text-span classification to the Decision
|
|
9
9
|
Protocol. Read `secret-guard-analysis.md` first — §2.5 there
|
|
10
10
|
(reachability) and §0.1 (irrevocability) are the two facts this design is
|
|
11
11
|
built around.
|
|
12
12
|
|
|
13
13
|
Naming: the skill is `exfil-guard`; the rule families are `secret/*` and
|
|
14
|
-
`path/*`. `docs/secret-guard-architecture.md` states where it sits.
|
|
14
|
+
`path/*`. `docs/history/secret-guard-architecture.md` states where it sits.
|
|
15
15
|
|
|
16
16
|
---
|
|
17
17
|
|
|
@@ -51,7 +51,7 @@ skills/
|
|
|
51
51
|
Two structural choices worth defending:
|
|
52
52
|
|
|
53
53
|
**(a) `redaction.py` is a new *strategy* on the existing Compensation slot,
|
|
54
|
-
not a new engine.** `docs/architecture.md` #3 already frames compensation
|
|
54
|
+
not a new engine.** `docs/design/architecture.md` #3 already frames compensation
|
|
55
55
|
as pluggable ("Future compensations … plug into the same slot"). Redaction
|
|
56
56
|
is the *degraded* member of that family — it does not restore recoverable
|
|
57
57
|
loss, it only records what was removed. Naming it inside `recovery.py`'s
|
|
@@ -271,7 +271,7 @@ Every detector returns offsets. Reasons:
|
|
|
271
271
|
|
|
272
272
|
### 3.1 The workspace-relative exemption is the core rule
|
|
273
273
|
|
|
274
|
-
Direct reuse of the delete-guard insight (`docs/architecture.md` #5,
|
|
274
|
+
Direct reuse of the delete-guard insight (`docs/design/architecture.md` #5,
|
|
275
275
|
"Lexical boundaries"): *a path is only a host identifier if it is outside
|
|
276
276
|
the workspace.* `./src/main.py` says nothing about the machine;
|
|
277
277
|
`/home/alice/work/agent-guard/src/main.py` does.
|
|
@@ -339,7 +339,7 @@ HOME/USERPROFILE to build a smaller but still-useful deny-set, and the
|
|
|
339
339
|
|
|
340
340
|
### 3.4 Host identity ≠ machine identity, and CI is the counter-example
|
|
341
341
|
|
|
342
|
-
This repository's own artifacts make the case: `docs/test-report-*.md` and
|
|
342
|
+
This repository's own artifacts make the case: `docs/reports/test-report-*.md` and
|
|
343
343
|
CI logs routinely contain
|
|
344
344
|
`/home/runner/work/agent-guard/agent-guard`, `/workspace`, `/tmp/agent-guard-test-*`.
|
|
345
345
|
Those leak the *runner image's* layout, not a person. Consequences the
|
|
@@ -515,10 +515,10 @@ payload and is worthless to an attacker.
|
|
|
515
515
|
"it's too noisy" becomes measurable: on this repository's own text corpus
|
|
516
516
|
(README, docs/, tests/, skills/), the default rule set must produce **zero
|
|
517
517
|
BLOCK and a bounded number of ASK/SANITIZE**; anything above the bound is a
|
|
518
|
-
bug in the rule, not a tuning problem. `docs/compatibility.md`'s promise
|
|
518
|
+
bug in the rule, not a tuning problem. `docs/design/compatibility.md`'s promise
|
|
519
519
|
that "default policy verdict changes for an existing shape → minor +
|
|
520
520
|
friction entry" applies: rule changes that alter verdicts get a
|
|
521
|
-
`docs/friction.md` entry.
|
|
521
|
+
`docs/history/friction.md` entry.
|
|
522
522
|
|
|
523
523
|
---
|
|
524
524
|
|
|
@@ -552,10 +552,10 @@ corpora.
|
|
|
552
552
|
|
|
553
553
|
1. **No LLM-request interception for harnesses that lack a hook or proxy.**
|
|
554
554
|
Documented as a coverage gap, with the "you may not claim" sentence from
|
|
555
|
-
`threat-model.md` reused verbatim.
|
|
555
|
+
`docs/design/threat-model.md` reused verbatim.
|
|
556
556
|
2. **No git-history rewriting / no `filter-repo` integration.** Detecting a
|
|
557
557
|
secret already in history is a *report* at most; rewriting is a human
|
|
558
|
-
action with its own destructive risk (`docs/architecture.md` #4 logic).
|
|
558
|
+
action with its own destructive risk (`docs/design/architecture.md` #4 logic).
|
|
559
559
|
3. **No T3 entropy detector in the first release** unless the acceptance
|
|
560
560
|
corpus (§6.4) shows it clears the noise budget. It is the single largest
|
|
561
561
|
FP source and the least necessary for the named seeds.
|
|
@@ -600,7 +600,7 @@ corpora.
|
|
|
600
600
|
|
|
601
601
|
## 7. Position in the roadmap
|
|
602
602
|
|
|
603
|
-
Current roadmap (`docs/architecture.md`): V1 delete-guard → V1.x dialects →
|
|
603
|
+
Current roadmap (`docs/design/architecture.md`): V1 delete-guard → V1.x dialects →
|
|
604
604
|
V2 `git-guard` → V3+ `database-guard`/`cloud-guard`.
|
|
605
605
|
|
|
606
606
|
exfil-guard is a **new X-guard branch**, not a slot inside the existing
|
|
@@ -630,7 +630,7 @@ being further along the stated roadmap:
|
|
|
630
630
|
2. **It shares the `git push` interception point** already present in
|
|
631
631
|
`classifier._parse_git()` — one hook, two concerns; building
|
|
632
632
|
`git-guard` first means rebuilding the point twice.
|
|
633
|
-
3. **The new decision class is a core-surface change.** `docs/compatibility.md`
|
|
633
|
+
3. **The new decision class is a core-surface change.** `docs/design/compatibility.md`
|
|
634
634
|
says a new decision class is a minor release "announced in README";
|
|
635
635
|
landing it before V2 means `git-guard` is authored against the *final*
|
|
636
636
|
decision vocabulary rather than a partially frozen one. Doing it after
|
|
@@ -639,7 +639,7 @@ being further along the stated roadmap:
|
|
|
639
639
|
(standalone `check_span.py`) delivers value with zero adapter changes —
|
|
640
640
|
the lowest-risk way to extend the core.
|
|
641
641
|
|
|
642
|
-
**Versioning/positioning obligations** (from `docs/compatibility.md`):
|
|
642
|
+
**Versioning/positioning obligations** (from `docs/design/compatibility.md`):
|
|
643
643
|
|
|
644
644
|
- New decision class → **minor**, README announcement, adapter mapping
|
|
645
645
|
table updated.
|
|
@@ -647,7 +647,7 @@ being further along the stated roadmap:
|
|
|
647
647
|
`skills/exfil-guard/references/rules.md` and the compatibility page's
|
|
648
648
|
"Additive surfaces" table.
|
|
649
649
|
- Any default-verdict change for an existing shape → minor + a
|
|
650
|
-
`docs/friction.md` entry.
|
|
650
|
+
`docs/history/friction.md` entry.
|
|
651
651
|
- `README.md` / `README.zh-CN.md` must gain the honest limitation section
|
|
652
652
|
(§2.4 of the analysis) — a feature that arrives without its documented
|
|
653
653
|
blind spots would violate the repo's own threat-model discipline.
|