@mokuyoaxis/agent-guard 0.2.4 → 0.2.5-rc2
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 +166 -573
- package/README.zh-CN.md +138 -489
- package/SECURITY.md +53 -0
- package/adapters/INTEGRATION.md +4 -2
- package/adapters/dsh/README.md +7 -0
- package/assets/linux-do-community.svg +19 -0
- package/core/audit.py +170 -25
- package/core/classifier.py +25 -1
- package/core/lab.py +77 -7
- package/core/policy.py +17 -9
- package/core/recovery.py +5 -1
- package/core/redaction.py +122 -21
- package/docs/README.md +18 -5
- package/docs/design/architecture.md +25 -6
- package/docs/design/compatibility.md +106 -1
- package/docs/design/threat-model.md +6 -4
- package/docs/guides/audit-metadata.md +77 -0
- package/docs/guides/getting-started.md +106 -0
- package/docs/guides/harness-capabilities.md +5 -0
- package/docs/history/friction.md +85 -0
- package/docs/lab/guard-lab.md +15 -1
- package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
- package/docs/releases/release-notes-0.2.5-rc2.md +101 -0
- package/guard_lab.py +11 -0
- package/package.json +4 -2
- package/skills/delete-guard/SKILL.md +45 -7
- package/skills/delete-guard/references/policy.md +90 -4
- package/skills/delete-guard/scripts/check.py +3 -0
- package/skills/delete-guard/scripts/gc.py +18 -3
- package/skills/delete-guard/scripts/restore.py +22 -7
- package/skills/delete-guard/scripts/safe_delete.py +52 -29
- package/skills/delete-guard/scripts/status.py +9 -7
- package/skills/exfil-guard/SKILL.md +23 -11
- package/skills/exfil-guard/references/channels.md +8 -1
- package/skills/exfil-guard/references/rules.md +86 -6
- package/skills/exfil-guard/scripts/_payload.py +20 -0
- package/skills/exfil-guard/scripts/check_span.py +5 -1
- package/skills/exfil-guard/scripts/sanitize.py +6 -3
|
@@ -1,6 +1,14 @@
|
|
|
1
1
|
# delete-guard policy reference (V1)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The shared Core supports POSIX/cmd/PowerShell command facts. Full suites run
|
|
4
|
+
on Linux/macOS; focused Windows Core evidence is available, while complete
|
|
5
|
+
native Windows harness execution remains unverified. POSIX hook bridges have
|
|
6
|
+
their own platform requirements. See the
|
|
7
|
+
[compatibility contract](../../../docs/design/compatibility.md).
|
|
8
|
+
|
|
9
|
+
This reference covers the 0.2.5-rc2 source candidate, including RC1 maintenance
|
|
10
|
+
and shared audit metadata projection. The published 0.2.4 baseline lacks the RC's
|
|
11
|
+
control-path, GC and audit-writer maintenance.
|
|
4
12
|
|
|
5
13
|
## Decision Protocol
|
|
6
14
|
|
|
@@ -25,6 +33,41 @@ RESTRICTED prohibitions) are policy violations and never askable.
|
|
|
25
33
|
|
|
26
34
|
check.py exit codes: 0 proceed/advisory-ok · 2 blocked · 3 ask · 1 error.
|
|
27
35
|
|
|
36
|
+
### Assessment and dry-run side effects
|
|
37
|
+
|
|
38
|
+
Advisory `check.py` and `safe_delete.py --dry-run` keep command targets
|
|
39
|
+
unchanged. They do not execute the assessed shell text, relocate targets,
|
|
40
|
+
create Git stashes or create recovery transactions. They may still write
|
|
41
|
+
metadata through their existing best-effort audit path:
|
|
42
|
+
|
|
43
|
+
| Invocation | Exit / target behavior | Possible metadata writes |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| Advisory `check.py`, including ALLOW, ASK or BLOCK | Exit 0 with the actual decision; targets unchanged | Layout initialization and an appended `check` audit |
|
|
46
|
+
| `safe_delete.py --dry-run` with concrete targets, including absent literals | Exit 0 unless BLOCK; targets unchanged | An advisory audit, or a blocked-decision audit |
|
|
47
|
+
| Policy-blocked `safe_delete.py` before compensation, including dry-run | Exit 2; targets unchanged | Best-effort blocked-decision audit |
|
|
48
|
+
| Unmatched-glob-only `safe_delete.py` | Exit 0 before layout/audit setup | None from that invocation |
|
|
49
|
+
| Non-dry-run `safe_delete.py` with an absent literal / ALLOW_NOOP | Exit 0 without mutation or layout setup | None from that invocation |
|
|
50
|
+
|
|
51
|
+
Layout initialization may create the selected quarantine directory and
|
|
52
|
+
`audit.jsonl`. If a quarantine inside a Git workspace is not already ignored,
|
|
53
|
+
it may append an ignore entry to Git's local `info/exclude`, including the
|
|
54
|
+
resolved exclude path of a linked worktree. It does not edit tracked
|
|
55
|
+
`.gitignore`. A preexisting ignore rule or an external bucket avoids that
|
|
56
|
+
exclude write. Repeated checks append audit lines without duplicating the
|
|
57
|
+
exclude rule; recovery manifests and authorization state are not created by
|
|
58
|
+
these assessment paths. Git status may hide metadata that was previously
|
|
59
|
+
untracked, so an unchanged Git status alone does not prove zero writes.
|
|
60
|
+
|
|
61
|
+
If audit/layout setup fails, assessments retain their decision and report
|
|
62
|
+
an audit warning; partial metadata changes may remain. `ensure_layout`
|
|
63
|
+
establishes the Git ignore rule before creating the bucket. Audit failure
|
|
64
|
+
after that step does not roll it back. This best-effort behavior is distinct
|
|
65
|
+
from enforced execution/ASK intents, which must be durable or execution is
|
|
66
|
+
refused. Advisory exit 0 must never be treated as authorization to run a
|
|
67
|
+
BLOCK or ASK command. Failed real compensations can leave partial target
|
|
68
|
+
changes and recovery IDs; this table does not promise rollback for them.
|
|
69
|
+
No general zero-write assessment flag is introduced.
|
|
70
|
+
|
|
28
71
|
### Dialects
|
|
29
72
|
|
|
30
73
|
`check.py` lexes the command line for a shell dialect: `--dialect posix`
|
|
@@ -46,6 +89,9 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
|
|
|
46
89
|
|
|
47
90
|
## Rule table (first match wins)
|
|
48
91
|
|
|
92
|
+
The quarantine control-path changes below were introduced in 0.2.5-rc1;
|
|
93
|
+
the published 0.2.4 artifact retains its original housekeeping order.
|
|
94
|
+
|
|
49
95
|
| # | Condition | Verdict code | Effect |
|
|
50
96
|
|---|---|---|---|
|
|
51
97
|
| 1 | dry run / no targets | `ALLOW_NOOP` | proceed unchanged |
|
|
@@ -53,9 +99,9 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
|
|
|
53
99
|
| 2a | SHAPE F1: destructive op preceded by `cd` in the same command line, target in-workspace and resolvable | `ASK` (`COMPOUND_CWD_DELETE`) | single-execution authorization; splitting the command avoids the prompt. A shape rule describes *compensation* difficulty, never effect scope: if the target set also trips rule 2, 4, 5 or 6, that BLOCK wins (`tests/test_incident_regression.py`) |
|
|
54
100
|
| 2b | SHAPE F2: file-creation op (`touch/mkdir/cp/mv/install/ln/tee`, `>`/`>>`) precedes a target-dependent destructive op in the same line | `ASK` (`COMPOUND_CREATE_DELETE`) | single-execution authorization; force-push is refused separately. Hard reset in a compound line is effect-uncertain and BLOCKED before shape rules |
|
|
55
101
|
| 2c | target *is* a filesystem root (`/`, `/home`, `/usr`, `/etc`, `/var`, `/tmp`, `/opt`, `/boot`, `$HOME`, ...) | `BLOCK_PROTECTED_ANCESTOR` | refuse. Matched exactly, so paths *under* these roots keep the ordinary codes; enforced by identity rather than workspace geometry, so it holds even when the workspace is `/` |
|
|
56
|
-
|
|
|
102
|
+
| 5 | workspace root, `.git` metadata, quarantine root/control paths, or an in-workspace parent containing configured storage | `BLOCK_PROTECTED_PATH` | refuse before the housekeeping exemption; root manifest/audit/state, state temp and sessions are control paths |
|
|
103
|
+
| 3 | explicit ordinary unprotected payload inside quarantine (`.agent-trash/`) | `ALLOW_TRASH_GC` | opaque globs BLOCK_WILDCARD; safe_delete may enumerate first, and an audited transaction purge uses gc.py --execute |
|
|
57
104
|
| 4 | target outside workspace | `BLOCK_OUT_OF_WORKSPACE` | refuse |
|
|
58
|
-
| 5 | target is workspace root or `.git` (any depth) | `BLOCK_PROTECTED_PATH` | refuse |
|
|
59
105
|
| 6 | any glob target | `BLOCK_WILDCARD` | refuse; use safe_delete which enumerates |
|
|
60
106
|
| 7 | RESTRICTED mode, git/remote destructive op | `BLOCK_RESTRICTED_MODE` | refuse |
|
|
61
107
|
| 8 | RESTRICTED mode, fs delete | narrow files only -> `RELOCATE_NARROW`, else `BLOCK_RESTRICTED_MODE` | refuse or quarantine |
|
|
@@ -100,7 +146,7 @@ a portable fallback.
|
|
|
100
146
|
|---|---|
|
|
101
147
|
| `AGENT_GUARD_WORKSPACE` | override workspace boundary discovery |
|
|
102
148
|
| `AGENT_GUARD_TRASH` | override quarantine location |
|
|
103
|
-
| `AGENT_GUARD_SESSION` | session
|
|
149
|
+
| `AGENT_GUARD_SESSION` | selects session authorization state; RC2 audit metadata uses opaque correlation |
|
|
104
150
|
| `AGENT_GUARD_ARTIFACTS` | `os.pathsep`-joined extra artifact patterns |
|
|
105
151
|
| `AGENT_GUARD_ALLOW_REGENERABLE` | `0` disables direct deletion of artifacts |
|
|
106
152
|
|
|
@@ -133,6 +179,46 @@ Soft policy: 30-day retention, 5 GiB cap. Thresholds only MARK transactions
|
|
|
133
179
|
`QUARANTINED -> RESTORABLE -> GC_ELIGIBLE -> PURGED`; the audit log itself
|
|
134
180
|
is never garbage-collected.
|
|
135
181
|
|
|
182
|
+
Local maintenance excludes `PURGED` tombstones from active GC inventory and
|
|
183
|
+
age/capacity plans. History remains in the manifest and transaction listing;
|
|
184
|
+
a directory recreated under a purged ID is unmanaged. Failed purges retain
|
|
185
|
+
their prior state and can still be planned. This does not add stash pruning.
|
|
186
|
+
|
|
187
|
+
Restore audit metadata now records `restored_count`, `conflict_count` and
|
|
188
|
+
`error_count` instead of raw path arrays/error bodies. Known `txid`, `force`,
|
|
189
|
+
`ok` and preservation `backup_txids` retain correlation; invalid/unknown input
|
|
190
|
+
IDs use `txid_sha256`. Exact restoration paths and errors remain in the
|
|
191
|
+
recovery journal and CLI result. Historical audit lines are not rewritten.
|
|
192
|
+
At released RC1, automatic session/generic handling is unchanged; the RC2
|
|
193
|
+
[shared projection](../../../docs/guides/audit-metadata.md) extends it.
|
|
194
|
+
|
|
195
|
+
### safe_delete audit metadata
|
|
196
|
+
|
|
197
|
+
New `safe_delete` audit events keep `event`, `tool`, `decision`, `code` and
|
|
198
|
+
`target_count`, plus `phase`/static `outcome` where applicable. Established
|
|
199
|
+
relocation reports add `txid`, `moved_count` and `skipped_count`, including
|
|
200
|
+
partial relocation and storage-failure decisions. `target_count` counts
|
|
201
|
+
classified entries after glob expansion, including absent literals and
|
|
202
|
+
unresolved/rejected entries in a BLOCK assessment; it is not a count of
|
|
203
|
+
existing or deletable files. Unmatched patterns are excluded; duplicate
|
|
204
|
+
input entries remain separate entries.
|
|
205
|
+
`skipped_count` counts the engine's skipped entries, not every target left
|
|
206
|
+
unmoved after a storage failure.
|
|
207
|
+
|
|
208
|
+
Target arrays, policy reason bodies, free-form `--reason` and moved/skipped
|
|
209
|
+
payloads are not copied into these events. `--reason` remains accepted but
|
|
210
|
+
its text is no longer persisted in the audit or `tx-start.meta`. Exact
|
|
211
|
+
origin/trash paths, write-ahead relocation records and failure diagnostics
|
|
212
|
+
stay in the recovery manifest; CLI target/recovery paths and errors stay
|
|
213
|
+
accurate. Those surfaces can still contain sensitive text.
|
|
214
|
+
|
|
215
|
+
Mutation intents remain durable before deletion; assessment and outcome
|
|
216
|
+
audits retain their existing best-effort behavior. Historical audit lines
|
|
217
|
+
and manifest metadata are not rewritten. At released RC1, automatic session
|
|
218
|
+
and generic append/tail handling is unchanged. The later unreleased
|
|
219
|
+
[shared projection](../../../docs/guides/audit-metadata.md) limits these fields
|
|
220
|
+
and legacy reads, while raw historical files and recovery surfaces remain.
|
|
221
|
+
|
|
136
222
|
Authority model: `gc.py --execute` is intentionally permitted
|
|
137
223
|
non-interactively (scheduled maintenance is legitimate; purging
|
|
138
224
|
already-quarantined evidence is lower-risk than capability escalation,
|
|
@@ -6,6 +6,9 @@
|
|
|
6
6
|
|
|
7
7
|
Advisory mode (default): prints the verdict and does not mutate command
|
|
8
8
|
targets. It records the assessment when audit storage is available.
|
|
9
|
+
Audit setup may create the quarantine, append audit.jsonl, and add a Git
|
|
10
|
+
local exclude rule. Advisory exit 0 is not execution authorization; inspect
|
|
11
|
+
the decision. It creates no relocation, snapshot or recovery transaction.
|
|
9
12
|
--enforce: performs the compensations first (relocate targets / git snapshot
|
|
10
13
|
/ git-clean enumeration+relocation) and tells the caller to PROCEED, or
|
|
11
14
|
refuses with BLOCKED. Any BLOCK in the line means nothing is executed.
|
|
@@ -22,6 +22,7 @@ CODE_RELOCATE_FAILED_STORAGE.
|
|
|
22
22
|
from __future__ import annotations
|
|
23
23
|
|
|
24
24
|
import argparse
|
|
25
|
+
import hashlib
|
|
25
26
|
import json
|
|
26
27
|
import os
|
|
27
28
|
import sys
|
|
@@ -76,13 +77,27 @@ def main() -> int:
|
|
|
76
77
|
# Preflight both identity and audit durability before irreversible purge.
|
|
77
78
|
# A failed final receipt still leaves this intent plus manifest tombstones.
|
|
78
79
|
engine.validate_gc_targets(txids)
|
|
79
|
-
|
|
80
|
+
known = engine.transactions()
|
|
81
|
+
|
|
82
|
+
def selection_metadata(selected):
|
|
83
|
+
return {
|
|
84
|
+
"txids": [txid for txid in selected if txid in known],
|
|
85
|
+
"missing_txid_sha256": [hashlib.sha256(
|
|
86
|
+
txid.encode("utf-8", errors="surrogatepass")).hexdigest()
|
|
87
|
+
for txid in selected if txid not in known],
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
audit.append({"event": "gc-intent", "target_count": len(txids),
|
|
91
|
+
**selection_metadata(txids)},
|
|
80
92
|
os.path.join(trash_root, AUDIT_NAME))
|
|
81
93
|
report = engine.gc_execute(txids)
|
|
94
|
+
missing = selection_metadata(report["missing"])
|
|
82
95
|
audit.append({"event": "gc", "action": "PURGED",
|
|
83
|
-
"purged": report["purged"], "missing":
|
|
96
|
+
"purged": report["purged"], "missing": missing["txids"],
|
|
97
|
+
"missing_count": len(report["missing"]),
|
|
98
|
+
"missing_txid_sha256": missing["missing_txid_sha256"],
|
|
84
99
|
"plan_reasons": {e["txid"]: e["reason"]
|
|
85
|
-
for e in plan["eligible"]}},
|
|
100
|
+
for e in plan["eligible"] if e["txid"] in txids}},
|
|
86
101
|
os.path.join(trash_root, AUDIT_NAME))
|
|
87
102
|
if args.as_json:
|
|
88
103
|
print(json.dumps({"mode": "execute", **report}, ensure_ascii=False,
|
|
@@ -11,6 +11,7 @@ transaction before restoring. Inspect backup_txids after success or failure.
|
|
|
11
11
|
from __future__ import annotations
|
|
12
12
|
|
|
13
13
|
import argparse
|
|
14
|
+
import hashlib
|
|
14
15
|
import json
|
|
15
16
|
import os
|
|
16
17
|
import sys
|
|
@@ -29,6 +30,26 @@ def context():
|
|
|
29
30
|
return recovery.RecoveryEngine(workspace, trash_root)
|
|
30
31
|
|
|
31
32
|
|
|
33
|
+
def restore_audit_event(txid, force, report):
|
|
34
|
+
"""Non-recovery metadata only; exact paths/errors stay in the result/journal."""
|
|
35
|
+
event = {
|
|
36
|
+
"event": "restore", "force": force, "ok": report.get("ok"),
|
|
37
|
+
"restored_count": len(report.get("restored", [])),
|
|
38
|
+
"conflict_count": len(report.get("conflicts", [])),
|
|
39
|
+
"error_count": len(report.get("errors", [])) + bool(report.get("error")),
|
|
40
|
+
}
|
|
41
|
+
if report.get("error"):
|
|
42
|
+
# Invalid/unknown caller input is not an established transaction ID.
|
|
43
|
+
# Keep correlation without copying arbitrary input into the audit log.
|
|
44
|
+
event["txid_sha256"] = hashlib.sha256(
|
|
45
|
+
txid.encode("utf-8", errors="surrogatepass")).hexdigest()
|
|
46
|
+
else:
|
|
47
|
+
event["txid"] = txid
|
|
48
|
+
if report.get("backup_txids"):
|
|
49
|
+
event["backup_txids"] = report["backup_txids"]
|
|
50
|
+
return event
|
|
51
|
+
|
|
52
|
+
|
|
32
53
|
def main() -> int:
|
|
33
54
|
ap = argparse.ArgumentParser(description=__doc__)
|
|
34
55
|
sub = ap.add_subparsers(dest="cmd", required=True)
|
|
@@ -69,13 +90,7 @@ def main() -> int:
|
|
|
69
90
|
return 0
|
|
70
91
|
|
|
71
92
|
report = engine.restore(args.txid, force=args.force)
|
|
72
|
-
|
|
73
|
-
event = {"event": "restore", "txid": args.txid, "force": args.force,
|
|
74
|
-
"ok": report.get("ok"), "restored": report.get("restored"),
|
|
75
|
-
"conflicts": report.get("conflicts"),
|
|
76
|
-
"errors": report.get("errors")}
|
|
77
|
-
if report.get("backup_txids"):
|
|
78
|
-
event["backup_txids"] = report["backup_txids"]
|
|
93
|
+
event = restore_audit_event(args.txid, args.force, report)
|
|
79
94
|
try:
|
|
80
95
|
audit.append(event, os.path.join(engine.trash_root, AUDIT_NAME))
|
|
81
96
|
except OSError:
|
|
@@ -4,8 +4,13 @@
|
|
|
4
4
|
safe_delete.py [--json] [--dry-run] [--reason TEXT] PATH...
|
|
5
5
|
|
|
6
6
|
Globs are expanded here, explicitly, before classification: an opaque
|
|
7
|
-
wildcard never reaches the filesystem unexamined.
|
|
8
|
-
|
|
7
|
+
wildcard never reaches the filesystem unexamined. Assessments are best-effort
|
|
8
|
+
audited; an unmatched glob returns before audit setup. --dry-run and policy
|
|
9
|
+
refusals before compensation leave command targets unchanged, but may create
|
|
10
|
+
quarantine/audit metadata and a Git local exclude rule. Policy blocks exit 2
|
|
11
|
+
even in dry-run. A failed real compensation can leave partial target changes.
|
|
12
|
+
New audit events contain decisions, counts and recovery IDs, not target paths
|
|
13
|
+
or free-form --reason text. Exact recovery paths stay in the manifest/result.
|
|
9
14
|
"""
|
|
10
15
|
from __future__ import annotations
|
|
11
16
|
|
|
@@ -53,12 +58,35 @@ def delete_directly(spec):
|
|
|
53
58
|
return "absent"
|
|
54
59
|
|
|
55
60
|
|
|
61
|
+
def safe_delete_audit_event(event, decision, code, target_count, *,
|
|
62
|
+
phase=None, report=None, outcome=None):
|
|
63
|
+
"""Build this writer's metadata; never copy input paths/reasons/errors.
|
|
64
|
+
|
|
65
|
+
Codes and outcome labels come from this CLI. Transaction IDs come from
|
|
66
|
+
the recovery engine; exact moved/skipped payloads stay in its journal
|
|
67
|
+
and the CLI result. core.audit projects automatic session metadata.
|
|
68
|
+
"""
|
|
69
|
+
entry = {"event": event, "tool": "safe_delete", "decision": decision,
|
|
70
|
+
"code": code, "target_count": target_count}
|
|
71
|
+
if phase is not None:
|
|
72
|
+
entry["phase"] = phase
|
|
73
|
+
if outcome is not None:
|
|
74
|
+
entry["outcome"] = outcome
|
|
75
|
+
if report is not None:
|
|
76
|
+
if report.get("txid"):
|
|
77
|
+
entry["txid"] = report["txid"]
|
|
78
|
+
entry["moved_count"] = len(report.get("moved", []))
|
|
79
|
+
entry["skipped_count"] = len(report.get("skipped", []))
|
|
80
|
+
return entry
|
|
81
|
+
|
|
82
|
+
|
|
56
83
|
def main() -> int:
|
|
57
84
|
ap = argparse.ArgumentParser(description=__doc__)
|
|
58
85
|
ap.add_argument("paths", nargs="+", help="paths or globs to delete")
|
|
59
86
|
ap.add_argument("--json", action="store_true", dest="as_json")
|
|
60
87
|
ap.add_argument("--dry-run", action="store_true")
|
|
61
|
-
ap.add_argument("--reason", default="",
|
|
88
|
+
ap.add_argument("--reason", default="",
|
|
89
|
+
help="why this deletion is needed (text is not persisted)")
|
|
62
90
|
args = ap.parse_args()
|
|
63
91
|
|
|
64
92
|
base = os.getcwd()
|
|
@@ -88,6 +116,7 @@ def main() -> int:
|
|
|
88
116
|
return 0
|
|
89
117
|
verdict = policy.decide_path_batch(specs, ctx, recursive=True)
|
|
90
118
|
engine = recovery.RecoveryEngine(workspace, trash_root)
|
|
119
|
+
relocation_report = None
|
|
91
120
|
|
|
92
121
|
result = {
|
|
93
122
|
"tool": "safe_delete",
|
|
@@ -119,10 +148,8 @@ def main() -> int:
|
|
|
119
148
|
return False
|
|
120
149
|
|
|
121
150
|
if verdict.blocked:
|
|
122
|
-
record(
|
|
123
|
-
|
|
124
|
-
"reasons": verdict.reasons, "targets": result["targets"],
|
|
125
|
-
"reason": args.reason})
|
|
151
|
+
record(safe_delete_audit_event(
|
|
152
|
+
"decision", "BLOCK", verdict.code, len(specs)))
|
|
126
153
|
result["exit"] = 2
|
|
127
154
|
print(json.dumps(result, ensure_ascii=False, indent=2) if args.as_json
|
|
128
155
|
else f"BLOCKED [{verdict.code}]: {verdict.reasons}")
|
|
@@ -151,16 +178,14 @@ def main() -> int:
|
|
|
151
178
|
# Authorization/intent must be durable before direct deletion. Dry-run
|
|
152
179
|
# assessments are best-effort audited but never fail for audit storage.
|
|
153
180
|
if args.dry_run:
|
|
154
|
-
record(
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
"reason": args.reason})
|
|
181
|
+
record(safe_delete_audit_event(
|
|
182
|
+
"decision", verdict.decision, verdict.code, len(specs),
|
|
183
|
+
phase="advisory"))
|
|
158
184
|
elif verdict.code != policy.CODE_ALLOW_NOOP:
|
|
159
185
|
try:
|
|
160
|
-
record(
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
"reason": args.reason}, required=True)
|
|
186
|
+
record(safe_delete_audit_event(
|
|
187
|
+
"decision", verdict.decision, verdict.code, len(specs),
|
|
188
|
+
phase="intent"), required=True)
|
|
164
189
|
except Exception as exc:
|
|
165
190
|
result["verdict"] = {
|
|
166
191
|
"decision": "BLOCK",
|
|
@@ -189,7 +214,8 @@ def main() -> int:
|
|
|
189
214
|
result["deleted"] = deleted
|
|
190
215
|
else: # RELOCATE_*
|
|
191
216
|
report = engine.relocate(specs, meta={
|
|
192
|
-
"tool": "safe_delete", "code": verdict.code
|
|
217
|
+
"tool": "safe_delete", "code": verdict.code})
|
|
218
|
+
relocation_report = report
|
|
193
219
|
if report.get("storage_failure"):
|
|
194
220
|
# Hard principle: capacity limits never downgrade to deletion.
|
|
195
221
|
result["verdict"] = {
|
|
@@ -200,10 +226,9 @@ def main() -> int:
|
|
|
200
226
|
}
|
|
201
227
|
result["outcome"] = "BLOCKED: quarantine cannot accept relocation"
|
|
202
228
|
result["exit"] = 2
|
|
203
|
-
record(
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
"targets": result["targets"], "reason": args.reason})
|
|
229
|
+
record(safe_delete_audit_event(
|
|
230
|
+
"decision", "BLOCK", policy.CODE_BLOCK_RELOCATE_FAILED_STORAGE,
|
|
231
|
+
len(specs), report=report))
|
|
207
232
|
print(json.dumps(result, ensure_ascii=False, indent=2)
|
|
208
233
|
if args.as_json else result["outcome"])
|
|
209
234
|
return 2
|
|
@@ -222,11 +247,9 @@ def main() -> int:
|
|
|
222
247
|
result["moved"] = report["moved"]
|
|
223
248
|
result["skipped"] = report["skipped"]
|
|
224
249
|
result["exit"] = 2
|
|
225
|
-
record(
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
"targets": result["targets"], "txid": report["txid"],
|
|
229
|
-
"reason": args.reason})
|
|
250
|
+
record(safe_delete_audit_event(
|
|
251
|
+
"decision", "BLOCK", policy.CODE_BLOCK_COMPENSATION_FAILED,
|
|
252
|
+
len(specs), report=report))
|
|
230
253
|
print(json.dumps(result, ensure_ascii=False, indent=2)
|
|
231
254
|
if args.as_json else result["outcome"])
|
|
232
255
|
return 2
|
|
@@ -236,10 +259,10 @@ def main() -> int:
|
|
|
236
259
|
result["skipped"] = report["skipped"]
|
|
237
260
|
|
|
238
261
|
if not args.dry_run and verdict.code != policy.CODE_ALLOW_NOOP:
|
|
239
|
-
record(
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
262
|
+
record(safe_delete_audit_event(
|
|
263
|
+
"outcome", verdict.decision, verdict.code, len(specs),
|
|
264
|
+
phase="complete", report=relocation_report,
|
|
265
|
+
outcome=result.get("outcome")))
|
|
243
266
|
result["exit"] = 0
|
|
244
267
|
if args.as_json:
|
|
245
268
|
print(json.dumps(result, ensure_ascii=False, indent=2))
|
|
@@ -81,6 +81,8 @@ def main() -> int:
|
|
|
81
81
|
"AGENT_GUARD_TRASH", os.path.join(workspace, TRASH_DIRNAME))
|
|
82
82
|
engine = recovery.RecoveryEngine(workspace, trash_root)
|
|
83
83
|
state = policy.load_mode(trash_root)
|
|
84
|
+
# Project display-only identity/time metadata, never authorization state.
|
|
85
|
+
mode_metadata = audit.project({"ts": state["since"], "session": state["set_by"]})
|
|
84
86
|
usage = engine.usage()
|
|
85
87
|
|
|
86
88
|
stash_count = 0
|
|
@@ -96,8 +98,8 @@ def main() -> int:
|
|
|
96
98
|
info = {
|
|
97
99
|
"workspace": workspace,
|
|
98
100
|
"mode": state["mode"],
|
|
99
|
-
"mode_since":
|
|
100
|
-
"mode_set_by":
|
|
101
|
+
"mode_since": mode_metadata.get("ts"),
|
|
102
|
+
"mode_set_by": mode_metadata.get("session"),
|
|
101
103
|
"trash_root": trash_root,
|
|
102
104
|
"usage": usage,
|
|
103
105
|
"retention": {
|
|
@@ -118,7 +120,8 @@ def main() -> int:
|
|
|
118
120
|
|
|
119
121
|
print(f"workspace : {info['workspace']}")
|
|
120
122
|
print(f"mode : {info['mode']}"
|
|
121
|
-
+ (f" (since {
|
|
123
|
+
+ (f" (since {info['mode_since']} by {info['mode_set_by']})"
|
|
124
|
+
if info["mode_since"] else ""))
|
|
122
125
|
print(f"quarantine: {trash_root}")
|
|
123
126
|
print(f"usage : {usage['files']} files, {usage['bytes']} bytes, "
|
|
124
127
|
f"{usage['transactions']} transactions "
|
|
@@ -140,8 +143,8 @@ def main() -> int:
|
|
|
140
143
|
|
|
141
144
|
|
|
142
145
|
def audit_tail(trash_root, n):
|
|
143
|
-
#
|
|
144
|
-
#
|
|
146
|
+
# core.audit projects both historical field names and values. Status
|
|
147
|
+
# exposes a smaller summary, with no session or compensation details.
|
|
145
148
|
fields = ("ts", "event", "action", "decision", "code", "txid",
|
|
146
149
|
"check_id", "guard_latency_ms")
|
|
147
150
|
return [{key: record[key] for key in fields if key in record}
|
|
@@ -153,8 +156,7 @@ DECISION_EVENTS = {"check", "enforce-block", "enforce-proceed", "ask",
|
|
|
153
156
|
|
|
154
157
|
|
|
155
158
|
def decision_stats(trash_root):
|
|
156
|
-
"""
|
|
157
|
-
machine). Counts reason codes across all decision-bearing events; ask
|
|
159
|
+
"""Aggregate projected reason codes for the status result; ask
|
|
158
160
|
OUTCOMES are not visible to the guard and are therefore not claimed
|
|
159
161
|
here."""
|
|
160
162
|
import collections
|
|
@@ -18,13 +18,14 @@ leave?". The four pillars, restated for egress:
|
|
|
18
18
|
- **Scope** - the egress boundary. The workspace is exempt; everything
|
|
19
19
|
outside it is a host identifier until proven otherwise.
|
|
20
20
|
- **Recoverability** - **weak, and do not pretend otherwise.** There is no
|
|
21
|
-
undo for a sent payload. The
|
|
22
|
-
|
|
23
|
-
- **Authorization** -
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
|
|
21
|
+
undo for a sent payload. The checker returns a *redaction plan* and safe
|
|
22
|
+
verdict metadata; it cannot un-send anything.
|
|
23
|
+
- **Authorization** - `NORMAL`/`RESTRICTED` is reused. Do not weaken the
|
|
24
|
+
user's rules or exemptions. Workspace configuration remains writable by
|
|
25
|
+
same-UID processes; its location is not a security boundary.
|
|
26
|
+
- **Auditability** - trusted callers can persist safe rule ids, offsets and
|
|
27
|
+
lengths. The text CLIs do not automatically append an egress audit.
|
|
28
|
+
Matched bytes or hashes of low-entropy secrets must not be recorded.
|
|
28
29
|
|
|
29
30
|
## The one rule
|
|
30
31
|
|
|
@@ -83,7 +84,8 @@ intercept a harness's ordinary file-read tool.
|
|
|
83
84
|
|
|
84
85
|
A `BLOCK` is not an obstacle to work around. Re-encoding a payload, splitting
|
|
85
86
|
a secret across lines, or piping through a tool the guard does not scan is a
|
|
86
|
-
violation of
|
|
87
|
+
violation of this discipline and can bypass both detection and any caller's
|
|
88
|
+
audit. An absent record does not establish that no emission occurred.
|
|
87
89
|
|
|
88
90
|
## Applying a redaction plan
|
|
89
91
|
|
|
@@ -100,9 +102,10 @@ checker-specific mode/path overrides still has to satisfy current sanitizer
|
|
|
100
102
|
policy. URI passwords use `<REDACTED>` while retaining scheme/account/host;
|
|
101
103
|
this is credential redaction, not network-topology hiding or an editable URI.
|
|
102
104
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
105
|
+
The checker does not observe whether its plan was applied or declined.
|
|
106
|
+
`sanitize-declined` is a proposed integration event, not an event automatically
|
|
107
|
+
written by either text CLI. A trusted emitter must own enforcement and any
|
|
108
|
+
recording; a checker SANITIZE decision alone is not completed redaction.
|
|
106
109
|
|
|
107
110
|
## Value-free detection (why `echo "$TOKEN"` is caught)
|
|
108
111
|
|
|
@@ -169,5 +172,14 @@ host-side file: read from the workspace root, not settable per call. If a
|
|
|
169
172
|
scan hits something you believe is benign, report it - do not weaken the
|
|
170
173
|
rule, and do not route around the guard.
|
|
171
174
|
|
|
175
|
+
Since 0.2.5-rc1, both configuration filenames use the same limited section/key grammar;
|
|
176
|
+
`.agent-guardignore` is not a gitignore file. The first readable UTF-8 file
|
|
177
|
+
wins, including an empty or malformed preferred file. Inspect the checker's
|
|
178
|
+
`exemption.source`, counts and diagnostics before assuming a configuration
|
|
179
|
+
was applied; `exempted` counts actual removed spans. Human checker and
|
|
180
|
+
sanitizer warnings use stderr and contain no configuration values. A warning
|
|
181
|
+
can coexist with effective legacy entries and does not authorize changing
|
|
182
|
+
the file or weakening a rule.
|
|
183
|
+
|
|
172
184
|
See `references/rules.md` for the frozen rule table, the exemption format and
|
|
173
185
|
the audit record shape; `references/channels.md` for the egress taxonomy.
|
|
@@ -43,7 +43,14 @@ Per `docs/design/threat-model.md`, the guard "may not claim" prevention of
|
|
|
43
43
|
adversarial exfiltration, and per design 4.4 an unreachable channel gets
|
|
44
44
|
**no verdict at all**.
|
|
45
45
|
|
|
46
|
-
##
|
|
46
|
+
## Proposed emitter integration mapping (design 4.5)
|
|
47
|
+
|
|
48
|
+
The following is a design contract for integrations that own the payload,
|
|
49
|
+
not a shipped host-support table. The default Claude/Kimi/DSH shell hooks
|
|
50
|
+
handle delete-guard decisions and do not implement general pre-write or
|
|
51
|
+
pre-request rewriting. The optional DSH complete text-read prototype uses a
|
|
52
|
+
separate post-execute path. Actual support and evidence are listed in the
|
|
53
|
+
[capability matrix](../../../docs/guides/harness-capabilities.md).
|
|
47
54
|
|
|
48
55
|
| Core decision | Claude Code (`PreToolUse`) | DSH (`PreToolDecision`) | No-hook harness |
|
|
49
56
|
|---|---|---|---|
|
|
@@ -186,6 +186,10 @@ facts still apply to variable templates.
|
|
|
186
186
|
|
|
187
187
|
## Configuration (environment)
|
|
188
188
|
|
|
189
|
+
The RC2 source retains the provenance/count diagnostics introduced in RC1 for the existing
|
|
190
|
+
exemption parser. Matching and file priority remain unchanged; the published
|
|
191
|
+
0.2.4 package does not include these diagnostic fields and warnings.
|
|
192
|
+
|
|
189
193
|
| Variable | Meaning |
|
|
190
194
|
|---|---|
|
|
191
195
|
| `AGENT_GUARD_EXFIL_CHANNEL` | default egress channel for both text CLIs |
|
|
@@ -198,21 +202,87 @@ facts still apply to variable templates.
|
|
|
198
202
|
|
|
199
203
|
## Repo-local exemptions (design 5.2)
|
|
200
204
|
|
|
201
|
-
`.agent-guard/exfil-allow.toml` (or `.agent-guardignore`) is read
|
|
202
|
-
**workspace root only**,
|
|
205
|
+
`.agent-guard/exfil-allow.toml` (or `.agent-guardignore`) is read by the local
|
|
206
|
+
guard from the **workspace root only**, not supplied as a per-call option.
|
|
207
|
+
This location does not make the file read-only: a process with workspace
|
|
208
|
+
write access can change exemptions. The host/operator must control its
|
|
209
|
+
contents; this is not a same-UID isolation boundary.
|
|
210
|
+
|
|
211
|
+
Both filenames use the same small `key = value` grammar. The `.toml`
|
|
212
|
+
extension does not promise a full TOML parser, and `.agent-guardignore` does
|
|
213
|
+
not accept gitignore-style bare paths or `!` re-inclusion rules.
|
|
203
214
|
|
|
204
|
-
```
|
|
215
|
+
```ini
|
|
205
216
|
[rules]
|
|
206
217
|
disable = [] # rule-id globs; [] means none
|
|
207
218
|
[values]
|
|
208
219
|
sha256 = # exempt a literal WITHOUT tracking it
|
|
209
|
-
sha256:
|
|
220
|
+
sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
|
|
210
221
|
[paths]
|
|
211
222
|
ignore = # path globs skipped entirely
|
|
212
223
|
docs/*.md
|
|
213
224
|
tests/fixtures/secrets/*
|
|
214
225
|
```
|
|
215
226
|
|
|
227
|
+
### Supported format and precedence
|
|
228
|
+
|
|
229
|
+
| Section | Recommended key | Top-level aliases retained for compatibility |
|
|
230
|
+
|---|---|---|
|
|
231
|
+
| `[rules]` | `disable` | `rule`, `rules`, `disable` |
|
|
232
|
+
| `[paths]` | `ignore` | `path`, `paths`, `ignore` |
|
|
233
|
+
| `[values]` | `sha256` | `sha256`, `hash`, `hashes` |
|
|
234
|
+
|
|
235
|
+
Keys and section names are case-insensitive. Values are separated by commas
|
|
236
|
+
or whitespace; surrounding list brackets and single/double quotes are
|
|
237
|
+
stripped. A subsequent line without `=` or a section header continues the
|
|
238
|
+
previous key; indentation is recommended but is not required. Empty values
|
|
239
|
+
and `[]` add no entries. Everything after the first `#` is a comment, even
|
|
240
|
+
inside quotes. Escaped strings, patterns containing spaces or `#`, TOML
|
|
241
|
+
multiline arrays, and gitignore negation are not supported. Patterns use
|
|
242
|
+
Python `fnmatch`, whose `*` can match a slash; this is not gitignore matching.
|
|
243
|
+
Value digests must be `sha256:` followed by 64 lowercase hexadecimal digits.
|
|
244
|
+
|
|
245
|
+
The first readable UTF-8 file wins: `.agent-guard/exfil-allow.toml`, then
|
|
246
|
+
`.agent-guardignore`. They are never merged. A readable empty or malformed
|
|
247
|
+
preferred file still takes precedence; it does not activate the fallback.
|
|
248
|
+
Missing, unreadable or non-UTF-8 files allow the next candidate to be tried.
|
|
249
|
+
When neither can be loaded, no configured exemption applies and scanning
|
|
250
|
+
continues. The lower-priority file is not read when the preferred one loads.
|
|
251
|
+
|
|
252
|
+
### Configuration diagnostics
|
|
253
|
+
|
|
254
|
+
After a successful scan, `check_span.py --json` adds an `exemption` object:
|
|
255
|
+
`source`, `active`, `counts` (`rules`/`paths`/`hashes`), `diagnostics`, and
|
|
256
|
+
`diagnostics_omitted`. `source` is one of the two fixed relative filenames,
|
|
257
|
+
`null` when none was loaded, or `<provided>` for an explicit library object.
|
|
258
|
+
Counts are configured entries, not proof that a pattern matched; existing
|
|
259
|
+
`exempted` reports the number of payload spans actually removed.
|
|
260
|
+
An input/channel refusal before configuration loading may omit this object.
|
|
261
|
+
|
|
262
|
+
Diagnostics contain only a static `code`, a fixed relative `source` and an
|
|
263
|
+
optional 1-based `line`. They never copy keys, patterns, hashes, raw lines,
|
|
264
|
+
workspace addresses or exception text. At most 32 are retained; the omitted
|
|
265
|
+
count records the remainder. Human checker warnings and all sanitizer CLI
|
|
266
|
+
warnings go to stderr. JSON checker stdout remains one object; sanitizer
|
|
267
|
+
stdout remains the payload or, under `--dry-run`, the JSON plan. Library
|
|
268
|
+
`sanitize_text` returns the same safe metadata without printing warnings.
|
|
269
|
+
|
|
270
|
+
| Code | Meaning |
|
|
271
|
+
|---|---|
|
|
272
|
+
| `EXEMPTION_IGNORED_LINE` | No assignment or prior key; bare gitignore lines have no effect |
|
|
273
|
+
| `EXEMPTION_UNKNOWN_KEY` | Unrecognized top-level key; its values have no effect |
|
|
274
|
+
| `EXEMPTION_UNKNOWN_SECTION` | Unknown section; recognized legacy keys may still work |
|
|
275
|
+
| `EXEMPTION_LEGACY_SECTION_KEY` | Nonstandard key still uses the existing section fallback |
|
|
276
|
+
| `EXEMPTION_MALFORMED_SECTION` | Malformed header still uses existing parsing |
|
|
277
|
+
| `EXEMPTION_INVALID_HASH` | Entry cannot match the required lowercase digest format |
|
|
278
|
+
| `EXEMPTION_UNSUPPORTED_NEGATION` | `!` is literal, not an exclusion/re-inclusion operator |
|
|
279
|
+
| `EXEMPTION_READ_FAILED` / `EXEMPTION_ENCODING_INVALID` | Try the next file; raw errors are withheld |
|
|
280
|
+
| `EXEMPTION_SHADOWED` | A present fallback file is not loaded because the preferred file was readable |
|
|
281
|
+
|
|
282
|
+
These diagnostics do not change verdicts, matching or exit codes. Legacy
|
|
283
|
+
parsing can retain valid entries alongside ignored input or warnings; a
|
|
284
|
+
warning is neither whole-file rejection nor a trust/permission check.
|
|
285
|
+
|
|
216
286
|
Three properties matter:
|
|
217
287
|
|
|
218
288
|
1. **Value exemptions are by hash.** A human who needs one specific literal
|
|
@@ -221,8 +291,9 @@ Three properties matter:
|
|
|
221
291
|
2. **Path exemptions, not rule amnesty.** Scoping an exemption to a path
|
|
222
292
|
keeps the rule fully active everywhere else. Disabling the rule wholesale
|
|
223
293
|
is what would blind the guard.
|
|
224
|
-
3. **
|
|
225
|
-
|
|
294
|
+
3. **Unrecognized input does not add exemptions.** Ignored lines and unknown
|
|
295
|
+
top-level keys leave scanning active; any recognized legacy entries still
|
|
296
|
+
follow the behavior documented above. Diagnostics expose this distinction.
|
|
226
297
|
|
|
227
298
|
This repository ships such a file for its own documentation and fixtures,
|
|
228
299
|
exactly as `SECURITY.md` documents "Expected scanner hits on this
|
|
@@ -232,6 +303,15 @@ corpus.
|
|
|
232
303
|
|
|
233
304
|
## Audit record shape
|
|
234
305
|
|
|
306
|
+
This is a safe record shape for a trusted integration that chooses to persist
|
|
307
|
+
egress evidence. `check_span.py` and `sanitize.py` do not automatically append
|
|
308
|
+
these events, and cannot observe a caller declining a plan. It is not a claim
|
|
309
|
+
that every egress decision has a durable record. The RC2 source candidate
|
|
310
|
+
projects supported metadata on append/read, including opaque session
|
|
311
|
+
correlation and value-free source-key context. See the
|
|
312
|
+
[shared audit contract](../../../docs/guides/audit-metadata.md); direct reads of
|
|
313
|
+
old log bytes and other output channels remain outside that projection.
|
|
314
|
+
|
|
235
315
|
```json
|
|
236
316
|
{"event":"exfil-sanitize","rule_id":"secret/openai-key",
|
|
237
317
|
"confidence":"deterministic","channel":"file-write",
|