@mokuyoaxis/agent-guard 0.2.5-rc1 → 0.2.5-rc3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +24 -0
- package/README.md +43 -10
- package/README.zh-CN.md +35 -9
- package/SECURITY.md +14 -8
- package/adapters/dsh/harness/README.md +5 -0
- package/adapters/dsh/harness/guard_lab.py +3 -2
- package/adapters/kimi-code/harness/README.md +5 -0
- package/core/audit.py +170 -25
- package/core/lab.py +82 -9
- package/docs/README.md +20 -4
- package/docs/design/architecture.md +12 -5
- package/docs/design/compatibility.md +48 -6
- package/docs/guides/audit-metadata.md +77 -0
- package/docs/guides/getting-started.md +13 -6
- package/docs/guides/harness-capabilities.md +7 -1
- package/docs/history/friction.md +4 -3
- package/docs/lab/blue-team-calibration.md +45 -0
- package/docs/lab/examples/blue-team-calibration.py +53 -0
- package/docs/lab/guard-lab.md +20 -2
- package/docs/releases/release-notes-0.2.5-rc2.md +101 -0
- package/docs/releases/release-notes-0.2.5-rc3.md +74 -0
- package/docs/reports/blue-team-lab-2026-10.md +73 -0
- package/docs/research/README.md +41 -0
- package/docs/research/content-authorization.md +54 -0
- package/docs/research/dataflow-observability.md +48 -0
- package/docs/research/delegation-provenance.md +56 -0
- package/docs/research/evaluation-method.md +51 -0
- package/docs/research/lab-observations-2026-10.json +43 -0
- package/guard_lab.py +11 -0
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +6 -3
- package/skills/delete-guard/references/policy.md +14 -10
- package/skills/delete-guard/scripts/gc.py +18 -3
- package/skills/delete-guard/scripts/safe_delete.py +1 -1
- package/skills/delete-guard/scripts/status.py +9 -7
- package/skills/exfil-guard/SKILL.md +1 -1
- package/skills/exfil-guard/references/rules.md +6 -3
package/guard_lab.py
CHANGED
|
@@ -5,6 +5,17 @@ from __future__ import annotations
|
|
|
5
5
|
|
|
6
6
|
import sys
|
|
7
7
|
|
|
8
|
+
if __name__ == "__main__" and len(sys.argv) > 1 and sys.argv[1] == "_observe":
|
|
9
|
+
import time
|
|
10
|
+
|
|
11
|
+
try:
|
|
12
|
+
print(
|
|
13
|
+
f"observer-startup stage=BOOTSTRAP monotonic={time.monotonic():.6f}",
|
|
14
|
+
file=sys.stderr, flush=True,
|
|
15
|
+
)
|
|
16
|
+
except (OSError, ValueError):
|
|
17
|
+
pass
|
|
18
|
+
|
|
8
19
|
from core.lab import cli_main, observer_cli_main
|
|
9
20
|
|
|
10
21
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mokuyoaxis/agent-guard",
|
|
3
|
-
"version": "0.2.5-
|
|
3
|
+
"version": "0.2.5-rc3",
|
|
4
4
|
"description": "Harness-neutral reliability infrastructure for AI coding agents: recoverable destructive actions, disclosure checks, controlled synthetic behaviour experiments, and a shared Core with optional native adapters.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./adapters/dsh/lib/index.js",
|
|
@@ -105,11 +105,14 @@ undone. Use only a disposable fixture when verifying this behavior; the
|
|
|
105
105
|
[policy reference](references/policy.md#assessment-and-dry-run-side-effects)
|
|
106
106
|
defines the no-match, existing-ignore and external-bucket branches.
|
|
107
107
|
|
|
108
|
-
|
|
108
|
+
Since 0.2.5-rc1, new `safe_delete` audit events record decisions, target counts and established
|
|
109
109
|
recovery IDs/counts rather than target paths or free-form reasons. `--reason`
|
|
110
110
|
is still accepted, but its text is not persisted in audit or transaction
|
|
111
111
|
metadata. Exact recovery paths remain in the CLI result and manifest.
|
|
112
|
-
|
|
112
|
+
At released RC1, historical records and automatic session handling are unchanged.
|
|
113
|
+
Since RC2, the shared audit layer projects supported metadata on append/read,
|
|
114
|
+
uses opaque session correlation and limits status/GC metadata; see the
|
|
115
|
+
[shared audit contract](../../docs/guides/audit-metadata.md) and the
|
|
113
116
|
[policy reference](references/policy.md#safe_delete-audit-metadata).
|
|
114
117
|
|
|
115
118
|
## Quarantine location queries
|
|
@@ -134,7 +137,7 @@ read just to answer a location/count question.
|
|
|
134
137
|
|
|
135
138
|
## RESTRICTED mode
|
|
136
139
|
|
|
137
|
-
|
|
140
|
+
RC2 and RC3 retain RC1 protection for the quarantine root, root manifest,
|
|
138
141
|
audit/state files, state temp file, sessions tree and storage access parents.
|
|
139
142
|
Housekeeping does not override those checks. Use the existing explicit
|
|
140
143
|
`gc.py --execute --txid <id>` entry for a validated, audited transaction purge.
|
|
@@ -6,13 +6,15 @@ 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
|
|
10
|
-
|
|
9
|
+
This reference covers the 0.2.5-rc3 source candidate, retaining 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.
|
|
11
12
|
|
|
12
13
|
## Decision Protocol
|
|
13
14
|
|
|
14
15
|
The stable cross-harness interface is Decision + ReasonCode + Explanation
|
|
15
|
-
(+ RecoveryPlan in payload).
|
|
16
|
+
(+ RecoveryPlan in payload). The deletion path uses the five classes below;
|
|
17
|
+
the shared text policy also supports `SANITIZE`.
|
|
16
18
|
|
|
17
19
|
| Decision | Meaning | Interaction tier |
|
|
18
20
|
|---|---|---|
|
|
@@ -88,7 +90,7 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
|
|
|
88
90
|
|
|
89
91
|
## Rule table (first match wins)
|
|
90
92
|
|
|
91
|
-
The quarantine control-path changes below
|
|
93
|
+
The quarantine control-path changes below were introduced in 0.2.5-rc1;
|
|
92
94
|
the published 0.2.4 artifact retains its original housekeeping order.
|
|
93
95
|
|
|
94
96
|
| # | Condition | Verdict code | Effect |
|
|
@@ -145,7 +147,7 @@ a portable fallback.
|
|
|
145
147
|
|---|---|
|
|
146
148
|
| `AGENT_GUARD_WORKSPACE` | override workspace boundary discovery |
|
|
147
149
|
| `AGENT_GUARD_TRASH` | override quarantine location |
|
|
148
|
-
| `AGENT_GUARD_SESSION` | session
|
|
150
|
+
| `AGENT_GUARD_SESSION` | selects session authorization state; RC2 audit metadata uses opaque correlation |
|
|
149
151
|
| `AGENT_GUARD_ARTIFACTS` | `os.pathsep`-joined extra artifact patterns |
|
|
150
152
|
| `AGENT_GUARD_ALLOW_REGENERABLE` | `0` disables direct deletion of artifacts |
|
|
151
153
|
|
|
@@ -187,8 +189,9 @@ Restore audit metadata now records `restored_count`, `conflict_count` and
|
|
|
187
189
|
`error_count` instead of raw path arrays/error bodies. Known `txid`, `force`,
|
|
188
190
|
`ok` and preservation `backup_txids` retain correlation; invalid/unknown input
|
|
189
191
|
IDs use `txid_sha256`. Exact restoration paths and errors remain in the
|
|
190
|
-
recovery journal and CLI result. Historical audit lines are not rewritten
|
|
191
|
-
|
|
192
|
+
recovery journal and CLI result. Historical audit lines are not rewritten.
|
|
193
|
+
At released RC1, automatic session/generic handling is unchanged; the RC2
|
|
194
|
+
[shared projection](../../../docs/guides/audit-metadata.md) extends it.
|
|
192
195
|
|
|
193
196
|
### safe_delete audit metadata
|
|
194
197
|
|
|
@@ -212,9 +215,10 @@ accurate. Those surfaces can still contain sensitive text.
|
|
|
212
215
|
|
|
213
216
|
Mutation intents remain durable before deletion; assessment and outcome
|
|
214
217
|
audits retain their existing best-effort behavior. Historical audit lines
|
|
215
|
-
and manifest metadata are not rewritten.
|
|
216
|
-
and generic
|
|
217
|
-
|
|
218
|
+
and manifest metadata are not rewritten. At released RC1, automatic session
|
|
219
|
+
and generic append/tail handling is unchanged. The
|
|
220
|
+
[shared projection](../../../docs/guides/audit-metadata.md) introduced in RC2 limits these fields
|
|
221
|
+
and legacy reads, while raw historical files and recovery surfaces remain.
|
|
218
222
|
|
|
219
223
|
Authority model: `gc.py --execute` is intentionally permitted
|
|
220
224
|
non-interactively (scheduled maintenance is legitimate; purging
|
|
@@ -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,
|
|
@@ -64,7 +64,7 @@ def safe_delete_audit_event(event, decision, code, target_count, *,
|
|
|
64
64
|
|
|
65
65
|
Codes and outcome labels come from this CLI. Transaction IDs come from
|
|
66
66
|
the recovery engine; exact moved/skipped payloads stay in its journal
|
|
67
|
-
and the CLI result.
|
|
67
|
+
and the CLI result. core.audit projects automatic session metadata.
|
|
68
68
|
"""
|
|
69
69
|
entry = {"event": event, "tool": "safe_delete", "decision": decision,
|
|
70
70
|
"code": code, "target_count": target_count}
|
|
@@ -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
|
|
@@ -172,7 +172,7 @@ host-side file: read from the workspace root, not settable per call. If a
|
|
|
172
172
|
scan hits something you believe is benign, report it - do not weaken the
|
|
173
173
|
rule, and do not route around the guard.
|
|
174
174
|
|
|
175
|
-
|
|
175
|
+
Since 0.2.5-rc1, both configuration filenames use the same limited section/key grammar;
|
|
176
176
|
`.agent-guardignore` is not a gitignore file. The first readable UTF-8 file
|
|
177
177
|
wins, including an empty or malformed preferred file. Inspect the checker's
|
|
178
178
|
`exemption.source`, counts and diagnostics before assuming a configuration
|
|
@@ -186,7 +186,7 @@ facts still apply to variable templates.
|
|
|
186
186
|
|
|
187
187
|
## Configuration (environment)
|
|
188
188
|
|
|
189
|
-
|
|
189
|
+
RC2 and RC3 retain the provenance/count diagnostics introduced in RC1 for the existing
|
|
190
190
|
exemption parser. Matching and file priority remain unchanged; the published
|
|
191
191
|
0.2.4 package does not include these diagnostic fields and warnings.
|
|
192
192
|
|
|
@@ -306,8 +306,11 @@ corpus.
|
|
|
306
306
|
This is a safe record shape for a trusted integration that chooses to persist
|
|
307
307
|
egress evidence. `check_span.py` and `sanitize.py` do not automatically append
|
|
308
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.
|
|
310
|
-
|
|
309
|
+
that every egress decision has a durable record. Since RC2, shared audit
|
|
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.
|
|
311
314
|
|
|
312
315
|
```json
|
|
313
316
|
{"event":"exfil-sanitize","rule_id":"secret/openai-key",
|