@mokuyoaxis/agent-guard 0.2.5-rc3 → 0.2.5
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 +33 -23
- package/README.zh-CN.md +29 -18
- package/SECURITY.md +5 -3
- package/adapters/dsh/README.md +39 -6
- package/adapters/dsh/lib/index.js +127 -33
- package/core/messages.py +40 -0
- package/core/policy.py +2 -1
- package/docs/README.md +16 -7
- package/docs/design/architecture.md +8 -6
- package/docs/design/compatibility.md +37 -4
- package/docs/design/threat-model.md +2 -2
- package/docs/guides/getting-started.md +28 -17
- package/docs/guides/harness-capabilities.md +5 -4
- package/docs/guides/recovery-feedback.md +98 -0
- package/docs/history/friction.md +21 -1
- package/docs/lab/blue-team-calibration.md +1 -1
- package/docs/lab/guard-lab.md +6 -2
- package/docs/releases/release-notes-0.2.5-rc3.md +8 -0
- package/docs/releases/release-notes-0.2.5.md +123 -0
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +30 -13
- package/skills/delete-guard/references/policy.md +16 -3
- package/skills/delete-guard/scripts/check.py +13 -0
- package/skills/delete-guard/scripts/gc.py +4 -2
- package/skills/delete-guard/scripts/safe_delete.py +20 -14
- package/skills/delete-guard/scripts/status.py +9 -0
|
@@ -32,15 +32,15 @@ enforces and how to work with it productively. The four pillars:
|
|
|
32
32
|
|
|
33
33
|
```bash
|
|
34
34
|
# delete explicit targets; valuable content is quarantined:
|
|
35
|
-
python3
|
|
36
|
-
python3
|
|
35
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
|
|
36
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py 'build/**/*.tmp' --reason "stale build output"
|
|
37
37
|
|
|
38
38
|
# undo a transaction (list first if unsure):
|
|
39
|
-
python3
|
|
40
|
-
python3
|
|
39
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
|
|
40
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'
|
|
41
41
|
|
|
42
42
|
# current guard state:
|
|
43
|
-
python3
|
|
43
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
Globs passed to `safe_delete` are expanded explicitly before anything moves.
|
|
@@ -54,7 +54,9 @@ can receive:
|
|
|
54
54
|
|
|
55
55
|
| Verdict | Meaning | Your move |
|
|
56
56
|
|---|---|---|
|
|
57
|
-
| `ALLOW`
|
|
57
|
+
| `ALLOW` | no recovery action for recognized operations; unrecognized effects are unchecked | continue only within the authorized scope; do not infer that scripts or overwrites are safe |
|
|
58
|
+
| `RELOCATE` / `SNAPSHOT` (harness may show `PROCEED` after compensation) | quarantine or tracked Git snapshot required | record and verify the resulting `txid` before continuing |
|
|
59
|
+
| `ASK` | this understood operation needs single-execution approval | use the host's human approval path; if unavailable, stop or split the command |
|
|
58
60
|
| `BLOCK_UNDETERMINABLE_EFFECT` | targets unresolvable (`$VAR`, `bash -c`, `find -delete`, `xargs`) | restate with explicit paths, or use `safe_delete` |
|
|
59
61
|
| `BLOCK_WILDCARD` | glob target set is opaque | use `safe_delete` with the glob |
|
|
60
62
|
| `BLOCK_OUT_OF_WORKSPACE` / `BLOCK_PROTECTED_PATH` / `BLOCK_PROTECTED_ANCESTOR` | outside boundary, workspace root, `.git`, or a filesystem root (`/`, `/home`, `/usr`, `$HOME`) | do not retry; this is a hard boundary. Ask the human if it is truly needed |
|
|
@@ -63,8 +65,10 @@ can receive:
|
|
|
63
65
|
|
|
64
66
|
Shape rules on compound commands: a single line that `cd`s anywhere before a
|
|
65
67
|
destructive op (F1), or that creates files (`touch/mkdir/cp/mv/tee`,
|
|
66
|
-
redirections) before destroying them (F2),
|
|
67
|
-
|
|
68
|
+
redirections) before destroying them (F2), can return `ASK` when its targets
|
|
69
|
+
are resolvable and within policy boundaries. Unresolvable effects and hard
|
|
70
|
+
boundaries still return `BLOCK`; hosts without a usable approval path deny
|
|
71
|
+
the `ASK` call. Run deletions as standalone commands with an explicit workdir.
|
|
68
72
|
|
|
69
73
|
A block is not an error to route around. Retrying the same operation in a
|
|
70
74
|
disguised form (`/bin/rm`, `python -c`, a script) violates this discipline and
|
|
@@ -117,13 +121,26 @@ uses opaque session correlation and limits status/GC metadata; see the
|
|
|
117
121
|
|
|
118
122
|
## Quarantine location queries
|
|
119
123
|
|
|
124
|
+
In 0.2.5, deletion/status results explain
|
|
125
|
+
retained storage and include GC commands. Moving files to quarantine keeps
|
|
126
|
+
their data on disk. Review the plan before choosing `--execute --all-eligible`
|
|
127
|
+
or a specific `--execute --txid`; use the same working directory and workspace/
|
|
128
|
+
trash settings. Age/size thresholds do not perform automatic cleanup.
|
|
129
|
+
|
|
130
|
+
`status.py` reports local recovery data and does not verify host activation.
|
|
131
|
+
DSH's status tool separately reports the plugin process startup check and
|
|
132
|
+
listener registration, with live interception still `UNVERIFIED`. A missing
|
|
133
|
+
plugin cannot supply its own status tool. `ALLOW_NOOP` does not certify
|
|
134
|
+
unrecognized script/interpreter effects. See the
|
|
135
|
+
[feedback guide](../../docs/guides/recovery-feedback.md).
|
|
136
|
+
|
|
120
137
|
When the user asks where quarantines are or how many exist, use the shared
|
|
121
138
|
read-only query with a current-directory or user-selected scope:
|
|
122
139
|
|
|
123
140
|
```bash
|
|
124
|
-
python3
|
|
125
|
-
python3
|
|
126
|
-
python3
|
|
141
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py --trash-index --json
|
|
142
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py --trash-index --root /absolute/path/to/projects --max-depth 3 --json
|
|
143
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py --trash-index --trash /absolute/path/to/custom-store --json
|
|
127
144
|
```
|
|
128
145
|
|
|
129
146
|
Report the scope, candidate count, metadata-identified count and read/budget
|
|
@@ -137,10 +154,10 @@ read just to answer a location/count question.
|
|
|
137
154
|
|
|
138
155
|
## RESTRICTED mode
|
|
139
156
|
|
|
140
|
-
|
|
157
|
+
Version 0.2.5 retains RC1 protection for the quarantine root, root manifest,
|
|
141
158
|
audit/state files, state temp file, sessions tree and storage access parents.
|
|
142
159
|
Housekeeping does not override those checks. Use the existing explicit
|
|
143
|
-
`gc.py --execute --txid <
|
|
160
|
+
`gc.py --execute --txid '<txid>'` entry for a validated, audited transaction purge.
|
|
144
161
|
Ordinary unprotected payload housekeeping retains its existing policy.
|
|
145
162
|
GC plans omit `PURGED` history; they do not delete stored Git stashes.
|
|
146
163
|
|
|
@@ -6,9 +6,10 @@ native Windows harness execution remains unverified. POSIX hook bridges have
|
|
|
6
6
|
their own platform requirements. See the
|
|
7
7
|
[compatibility contract](../../../docs/design/compatibility.md).
|
|
8
8
|
|
|
9
|
-
This reference covers
|
|
10
|
-
and shared audit metadata projection. The published
|
|
11
|
-
control-path, GC and audit-writer maintenance
|
|
9
|
+
This reference covers 0.2.5, retaining RC1–RC3
|
|
10
|
+
maintenance and shared audit metadata projection. The original published
|
|
11
|
+
0.2.4 baseline lacks the RC's control-path, GC and audit-writer maintenance;
|
|
12
|
+
the opt-in 0.2.4-hotfix.1 backports only control-path protection.
|
|
12
13
|
|
|
13
14
|
## Decision Protocol
|
|
14
15
|
|
|
@@ -34,6 +35,12 @@ RESTRICTED prohibitions) are policy violations and never askable.
|
|
|
34
35
|
|
|
35
36
|
check.py exit codes: 0 proceed/advisory-ok · 2 blocked · 3 ask · 1 error.
|
|
36
37
|
|
|
38
|
+
The 0.2.5 feedback maintenance changes explanations and optional
|
|
39
|
+
result metadata, not this decision table. `ALLOW_NOOP` means no recovery
|
|
40
|
+
action for recognized operations; it does not establish that unrecognized
|
|
41
|
+
commands are harmless. Human check output now includes the explanation.
|
|
42
|
+
See [status and cleanup feedback](../../../docs/guides/recovery-feedback.md).
|
|
43
|
+
|
|
37
44
|
### Assessment and dry-run side effects
|
|
38
45
|
|
|
39
46
|
Advisory `check.py` and `safe_delete.py --dry-run` keep command targets
|
|
@@ -174,6 +181,12 @@ Retention/GC is intentionally manual in V1; `restore.py list` distinguishes
|
|
|
174
181
|
|
|
175
182
|
## Retention / GC (B4)
|
|
176
183
|
|
|
184
|
+
Successful relocations report retained storage and GC commands; enforced
|
|
185
|
+
partial relocations retain their failed outcome and recovery association.
|
|
186
|
+
The same working directory and workspace/trash environment settings must be
|
|
187
|
+
used for maintenance. The `gc` command hints are optional result metadata,
|
|
188
|
+
not new audit fields, automatic execution, or permission to purge.
|
|
189
|
+
|
|
177
190
|
Soft policy: 30-day retention, 5 GiB cap. Thresholds only MARK transactions
|
|
178
191
|
`GC_ELIGIBLE` (oldest first under the cap); purging is an explicit
|
|
179
192
|
`gc.py --execute` maintenance action. Lifecycle is fully audited:
|
|
@@ -31,6 +31,7 @@ import _bootstrap # noqa: F401
|
|
|
31
31
|
|
|
32
32
|
from core import AUDIT_NAME, TRASH_DIRNAME
|
|
33
33
|
from core import audit, classifier, dialects, policy, recovery
|
|
34
|
+
from core.messages import QUARANTINE_NOTICE, gc_guidance, print_gc_guidance
|
|
34
35
|
|
|
35
36
|
|
|
36
37
|
_REDACTED_COMMAND = "<redacted>"
|
|
@@ -165,13 +166,25 @@ def main() -> int:
|
|
|
165
166
|
|
|
166
167
|
def finish(code):
|
|
167
168
|
out["exit"] = code
|
|
169
|
+
retained = [item for item in out.get("compensations", [])
|
|
170
|
+
if item["strategy"] in ("relocate", "clean-enumerate")
|
|
171
|
+
and item.get("moved", 0) > 0]
|
|
172
|
+
if retained:
|
|
173
|
+
out["storage_notice"] = QUARANTINE_NOTICE
|
|
174
|
+
out["gc"] = gc_guidance()
|
|
168
175
|
if args.as_json:
|
|
169
176
|
print(json.dumps(out, ensure_ascii=False, indent=2))
|
|
170
177
|
else:
|
|
171
178
|
summary = f"{out['decision']} [{out['code']}]"
|
|
172
179
|
print(summary)
|
|
180
|
+
print(out["explanation"])
|
|
173
181
|
for reason in out["reasons"][:4]:
|
|
174
182
|
print(f" - {reason}")
|
|
183
|
+
for item in retained:
|
|
184
|
+
print(f" retained: {item['moved']} target(s), txid={item['txid']}")
|
|
185
|
+
if retained:
|
|
186
|
+
print(out["storage_notice"])
|
|
187
|
+
print_gc_guidance(out["gc"])
|
|
175
188
|
return code
|
|
176
189
|
|
|
177
190
|
def record(entry, required=False):
|
|
@@ -31,6 +31,7 @@ import _bootstrap # noqa: F401
|
|
|
31
31
|
|
|
32
32
|
from core import AUDIT_NAME, TRASH_DIRNAME, audit
|
|
33
33
|
from core import classifier, recovery
|
|
34
|
+
from core.messages import gc_guidance, print_gc_guidance
|
|
34
35
|
|
|
35
36
|
|
|
36
37
|
def main() -> int:
|
|
@@ -52,7 +53,7 @@ def main() -> int:
|
|
|
52
53
|
plan = engine.gc_plan()
|
|
53
54
|
|
|
54
55
|
if not args.execute:
|
|
55
|
-
payload = {"mode": "plan", **plan}
|
|
56
|
+
payload = {"mode": "plan", **plan, "gc": gc_guidance()}
|
|
56
57
|
if args.as_json:
|
|
57
58
|
print(json.dumps(payload, ensure_ascii=False, indent=2))
|
|
58
59
|
else:
|
|
@@ -63,7 +64,8 @@ def main() -> int:
|
|
|
63
64
|
f"{entry['bytes']}B {entry['items']} items")
|
|
64
65
|
if not plan["eligible"]:
|
|
65
66
|
print(" nothing eligible")
|
|
66
|
-
print("
|
|
67
|
+
print("Dry plan. No recovery copies were removed.")
|
|
68
|
+
print_gc_guidance(payload["gc"])
|
|
67
69
|
return 0
|
|
68
70
|
|
|
69
71
|
txids = list(args.txid)
|
|
@@ -25,6 +25,7 @@ import _bootstrap # noqa: F401
|
|
|
25
25
|
|
|
26
26
|
from core import AUDIT_NAME, TRASH_DIRNAME, audit
|
|
27
27
|
from core import classifier, policy, recovery
|
|
28
|
+
from core.messages import QUARANTINE_NOTICE, gc_guidance, print_gc_guidance
|
|
28
29
|
|
|
29
30
|
|
|
30
31
|
def expand_globs(patterns):
|
|
@@ -80,6 +81,16 @@ def safe_delete_audit_event(event, decision, code, target_count, *,
|
|
|
80
81
|
return entry
|
|
81
82
|
|
|
82
83
|
|
|
84
|
+
def print_result(result, as_json):
|
|
85
|
+
if as_json:
|
|
86
|
+
print(json.dumps(result, ensure_ascii=False, indent=2))
|
|
87
|
+
return
|
|
88
|
+
print(result["outcome"] + (f" txid={result['txid']}" if result.get("txid") else ""))
|
|
89
|
+
if "storage_notice" in result:
|
|
90
|
+
print(result["storage_notice"])
|
|
91
|
+
print_gc_guidance(result["gc"])
|
|
92
|
+
|
|
93
|
+
|
|
83
94
|
def main() -> int:
|
|
84
95
|
ap = argparse.ArgumentParser(description=__doc__)
|
|
85
96
|
ap.add_argument("paths", nargs="+", help="paths or globs to delete")
|
|
@@ -216,6 +227,12 @@ def main() -> int:
|
|
|
216
227
|
report = engine.relocate(specs, meta={
|
|
217
228
|
"tool": "safe_delete", "code": verdict.code})
|
|
218
229
|
relocation_report = report
|
|
230
|
+
result["txid"] = report["txid"]
|
|
231
|
+
result["moved"] = report["moved"]
|
|
232
|
+
result["skipped"] = report["skipped"]
|
|
233
|
+
if report["moved"]:
|
|
234
|
+
result["storage_notice"] = QUARANTINE_NOTICE
|
|
235
|
+
result["gc"] = gc_guidance()
|
|
219
236
|
if report.get("storage_failure"):
|
|
220
237
|
# Hard principle: capacity limits never downgrade to deletion.
|
|
221
238
|
result["verdict"] = {
|
|
@@ -229,8 +246,7 @@ def main() -> int:
|
|
|
229
246
|
record(safe_delete_audit_event(
|
|
230
247
|
"decision", "BLOCK", policy.CODE_BLOCK_RELOCATE_FAILED_STORAGE,
|
|
231
248
|
len(specs), report=report))
|
|
232
|
-
|
|
233
|
-
if args.as_json else result["outcome"])
|
|
249
|
+
print_result(result, args.as_json)
|
|
234
250
|
return 2
|
|
235
251
|
if report.get("skipped"):
|
|
236
252
|
result["verdict"] = {
|
|
@@ -243,20 +259,13 @@ def main() -> int:
|
|
|
243
259
|
}
|
|
244
260
|
result["outcome"] = (
|
|
245
261
|
"BLOCKED: partial relocation remains recoverable")
|
|
246
|
-
result["txid"] = report["txid"]
|
|
247
|
-
result["moved"] = report["moved"]
|
|
248
|
-
result["skipped"] = report["skipped"]
|
|
249
262
|
result["exit"] = 2
|
|
250
263
|
record(safe_delete_audit_event(
|
|
251
264
|
"decision", "BLOCK", policy.CODE_BLOCK_COMPENSATION_FAILED,
|
|
252
265
|
len(specs), report=report))
|
|
253
|
-
|
|
254
|
-
if args.as_json else result["outcome"])
|
|
266
|
+
print_result(result, args.as_json)
|
|
255
267
|
return 2
|
|
256
268
|
result["outcome"] = "relocated to quarantine"
|
|
257
|
-
result["txid"] = report["txid"]
|
|
258
|
-
result["moved"] = report["moved"]
|
|
259
|
-
result["skipped"] = report["skipped"]
|
|
260
269
|
|
|
261
270
|
if not args.dry_run and verdict.code != policy.CODE_ALLOW_NOOP:
|
|
262
271
|
record(safe_delete_audit_event(
|
|
@@ -264,10 +273,7 @@ def main() -> int:
|
|
|
264
273
|
phase="complete", report=relocation_report,
|
|
265
274
|
outcome=result.get("outcome")))
|
|
266
275
|
result["exit"] = 0
|
|
267
|
-
|
|
268
|
-
print(json.dumps(result, ensure_ascii=False, indent=2))
|
|
269
|
-
else:
|
|
270
|
-
print(result["outcome"] + (f" txid={result['txid']}" if result.get("txid") else ""))
|
|
276
|
+
print_result(result, args.as_json)
|
|
271
277
|
return 0
|
|
272
278
|
|
|
273
279
|
|
|
@@ -16,6 +16,8 @@ import _bootstrap # noqa: F401
|
|
|
16
16
|
|
|
17
17
|
from core import AUDIT_NAME, TRASH_DIRNAME
|
|
18
18
|
from core import audit, classifier, policy, recovery
|
|
19
|
+
from core.messages import (
|
|
20
|
+
HOST_STATUS_NOTICE, QUARANTINE_NOTICE, gc_guidance, print_gc_guidance)
|
|
19
21
|
|
|
20
22
|
|
|
21
23
|
def main() -> int:
|
|
@@ -113,6 +115,9 @@ def main() -> int:
|
|
|
113
115
|
"guard_snapshots": stash_count,
|
|
114
116
|
"decisions": decision_stats(engine.trash_root),
|
|
115
117
|
"recent_audit": audit_tail(engine.trash_root, args.tail),
|
|
118
|
+
"host_status_notice": HOST_STATUS_NOTICE,
|
|
119
|
+
"storage_notice": QUARANTINE_NOTICE,
|
|
120
|
+
"gc": gc_guidance(),
|
|
116
121
|
}
|
|
117
122
|
if args.as_json:
|
|
118
123
|
print(json.dumps(info, ensure_ascii=False, indent=2))
|
|
@@ -123,6 +128,7 @@ def main() -> int:
|
|
|
123
128
|
+ (f" (since {info['mode_since']} by {info['mode_set_by']})"
|
|
124
129
|
if info["mode_since"] else ""))
|
|
125
130
|
print(f"quarantine: {trash_root}")
|
|
131
|
+
print(info["host_status_notice"])
|
|
126
132
|
print(f"usage : {usage['files']} files, {usage['bytes']} bytes, "
|
|
127
133
|
f"{usage['transactions']} transactions "
|
|
128
134
|
f"({usage['restorable_transactions']} restorable)")
|
|
@@ -131,6 +137,9 @@ def main() -> int:
|
|
|
131
137
|
print(f"retention : soft {ret['soft_days']}d / "
|
|
132
138
|
f"{ret['soft_limit_bytes'] // (1024**3)}GiB; "
|
|
133
139
|
f"{len(ret['gc_eligible'])} GC-eligible")
|
|
140
|
+
print(info["storage_notice"])
|
|
141
|
+
print("GC is manual; age and size thresholds do not trigger deletion.")
|
|
142
|
+
print_gc_guidance(info["gc"])
|
|
134
143
|
stats = info["decisions"]
|
|
135
144
|
if stats:
|
|
136
145
|
print(f"decisions : {top_codes(stats)}")
|