@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.
- package/README.md +158 -574
- package/README.zh-CN.md +133 -490
- 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/classifier.py +25 -1
- package/core/policy.py +17 -9
- package/core/recovery.py +5 -1
- package/core/redaction.py +122 -21
- package/docs/README.md +14 -5
- package/docs/design/architecture.md +20 -6
- package/docs/design/compatibility.md +71 -1
- package/docs/design/threat-model.md +6 -4
- package/docs/guides/getting-started.md +104 -0
- package/docs/guides/harness-capabilities.md +5 -0
- package/docs/history/friction.md +84 -0
- package/docs/lab/guard-lab.md +3 -1
- package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
- package/package.json +4 -2
- package/skills/delete-guard/SKILL.md +42 -7
- package/skills/delete-guard/references/policy.md +86 -3
- package/skills/delete-guard/scripts/check.py +3 -0
- package/skills/delete-guard/scripts/restore.py +22 -7
- package/skills/delete-guard/scripts/safe_delete.py +52 -29
- package/skills/exfil-guard/SKILL.md +23 -11
- package/skills/exfil-guard/references/channels.md +8 -1
- package/skills/exfil-guard/references/rules.md +83 -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
|
@@ -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. 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="",
|
|
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))
|
|
@@ -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
|
+
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
|
-
##
|
|
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
|
|
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,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,
|
|
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,
|
|
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
|