@mokuyoaxis/agent-guard 0.2.4 → 0.2.5-rc1

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.
@@ -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. Every verdict is audited.
8
- Blocked requests exit 2 and leave the filesystem untouched.
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. Automatic audit session metadata is unchanged.
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="", help="why this deletion is needed")
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({"event": "decision", "tool": "safe_delete",
123
- "decision": "BLOCK", "code": verdict.code,
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({"event": "decision", "tool": "safe_delete",
155
- "decision": verdict.decision, "code": verdict.code,
156
- "targets": result["targets"], "phase": "advisory",
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({"event": "decision", "tool": "safe_delete",
161
- "decision": verdict.decision, "code": verdict.code,
162
- "targets": result["targets"], "phase": "intent",
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, "reason": args.reason})
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({"event": "decision", "tool": "safe_delete",
204
- "decision": "BLOCK",
205
- "code": policy.CODE_BLOCK_RELOCATE_FAILED_STORAGE,
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({"event": "decision", "tool": "safe_delete",
226
- "decision": "BLOCK",
227
- "code": policy.CODE_BLOCK_COMPENSATION_FAILED,
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({"event": "outcome", "tool": "safe_delete",
240
- "targets": result["targets"], "txid": result.get("txid"),
241
- "outcome": result.get("outcome"), "phase": "complete",
242
- "reason": args.reason})
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))
@@ -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 guard returns a *redaction plan* and an audit
22
- record; it cannot un-send anything.
23
- - **Authorization** - unchanged. `NORMAL`/`RESTRICTED` is reused; rule
24
- configuration is host-side, so you cannot disable a rule.
25
- - **Auditability** - every verdict is recorded as rule id, offsets and
26
- length. **Never the matched bytes** - not even a hash, which would be
27
- offline-crackable for a low-entropy secret.
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 the authorization pillar and is recorded in the audit log.
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
- If you decline to apply a plan on a rewritable channel, the API contract is
104
- "you were told": the audit records `sanitize-declined`. That is a choice
105
- with a record, not a default.
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
+ In the 0.2.5-rc1 source candidate, 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
- ## Adapter mapping (design 4.5)
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 0.2.5-rc1 candidate adds provenance/count diagnostics to 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 from the
202
- **workspace root only**, so an agent cannot add one on the fly.
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
- ```toml
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:8ab1...e7
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. **A broken allowfile fails closed.** Malformed input is ignored and the
225
- rules stay on - never the reverse.
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,12 @@ 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. Generic `core.audit` also adds
310
+ session metadata; that metadata and existing logs require their own review.
311
+
235
312
  ```json
236
313
  {"event":"exfil-sanitize","rule_id":"secret/openai-key",
237
314
  "confidence":"deterministic","channel":"file-write",
@@ -12,6 +12,26 @@ from core.classifier import discover_workspace
12
12
  DEFAULT_STDIN_TIMEOUT_SEC = 10.0
13
13
 
14
14
 
15
+ def emit_exemption_diagnostics(info):
16
+ """CLI warnings on stderr; text comes only from the static catalog."""
17
+ for row in info.get("diagnostics", []):
18
+ code = row.get("code")
19
+ message = redaction.EXEMPTION_DIAGNOSTICS.get(code)
20
+ if message is None:
21
+ continue
22
+ source = row.get("source")
23
+ if source not in (redaction.DEFAULT_ALLOWFILE, redaction.DEFAULT_IGNOREFILE):
24
+ source = "<provided>"
25
+ location = source
26
+ if type(row.get("line")) is int and row["line"] > 0:
27
+ location += ":" + str(row["line"])
28
+ print(f"exfil-guard warning: {code} {location}: {message}", file=sys.stderr)
29
+ omitted = info.get("diagnostics_omitted", 0)
30
+ if type(omitted) is int and omitted > 0:
31
+ print(f"exfil-guard warning: {omitted} additional configuration diagnostics omitted",
32
+ file=sys.stderr)
33
+
34
+
15
35
  class StdinIdle(Exception):
16
36
  """No first byte arrived within the configured wait."""
17
37
 
@@ -39,7 +39,8 @@ from core.redaction import (
39
39
  CHANNELS, UNREACHABLE_CHANNELS, get_channel, scan_text,
40
40
  )
41
41
  from core import policy
42
- from _payload import PayloadTooLarge, StdinIdle, read_payload, resolve_context
42
+ from _payload import (PayloadTooLarge, StdinIdle, emit_exemption_diagnostics,
43
+ read_payload, resolve_context)
43
44
 
44
45
 
45
46
  def build_redaction_plan(spans, decisions, channel) -> list:
@@ -112,6 +113,8 @@ def main() -> int:
112
113
  max_bytes=args.max_bytes, path=args.path)
113
114
  out["scanned"] = scan.scanned
114
115
  out["exempted"] = scan.exempted
116
+ if scan.exemption_info:
117
+ out["exemption"] = scan.exemption_info
115
118
  if args.path:
116
119
  out["path"] = args.path
117
120
  if not scan.scanned:
@@ -157,6 +160,7 @@ def _emit(out, decision, code, spans, plan, args, exit_code,
157
160
  if args.as_json:
158
161
  print(json.dumps(out, ensure_ascii=False, indent=2))
159
162
  else:
163
+ emit_exemption_diagnostics(out.get("exemption", {}))
160
164
  print(f"{decision} [{code}] {len(spans)} span(s) on "
161
165
  f"channel {out.get('channel')}")
162
166
  if out.get("explanation"):
@@ -36,8 +36,8 @@ import _bootstrap # noqa: F401
36
36
 
37
37
  from core import policy, redaction
38
38
  from core.redaction import get_channel, scan_text
39
- from _payload import (PayloadTooLarge, StdinIdle, read_bounded_text,
40
- read_payload, resolve_context)
39
+ from _payload import (PayloadTooLarge, StdinIdle, emit_exemption_diagnostics,
40
+ read_bounded_text, read_payload, resolve_context)
41
41
 
42
42
  REDACTED = "<REDACTED>"
43
43
  PATH_PLACEHOLDER = "<PATH>"
@@ -154,7 +154,8 @@ def sanitize_text(text: str, channel_name: str, workspace=None,
154
154
  for span, verdict in zip(scan.spans, verdicts)
155
155
  if verdict.decision == policy.DECISION_SANITIZE]
156
156
  if decision not in (policy.DECISION_ALLOW, policy.DECISION_SANITIZE):
157
- return {"text": "", "plan": derived, "decision": decision}
157
+ return {"text": "", "plan": derived, "decision": decision,
158
+ "exemption": exemption.safe()}
158
159
  applied = derived if plan is None else _checked_plan(text, plan, derived)
159
160
  rewritten = apply_plan(text, applied)
160
161
  checked = scan_text(rewritten, channel=channel_name, workspace=workspace,
@@ -168,6 +169,7 @@ def sanitize_text(text: str, channel_name: str, workspace=None,
168
169
  "text": rewritten,
169
170
  "plan": applied,
170
171
  "decision": decision,
172
+ "exemption": exemption.safe(),
171
173
  }
172
174
 
173
175
 
@@ -216,6 +218,7 @@ def main() -> int:
216
218
  except (OSError, UnicodeError, ValueError, RuntimeError):
217
219
  print("sanitize: payload or plan validation failed", file=sys.stderr)
218
220
  return 1
221
+ emit_exemption_diagnostics(result["exemption"])
219
222
  if result["decision"] in (policy.DECISION_BLOCK, policy.DECISION_ASK):
220
223
  print("sanitize: " + result["decision"] + " payload withheld", file=sys.stderr)
221
224
  return 2 if result["decision"] == policy.DECISION_BLOCK else 3