@mokuyoaxis/agent-guard 0.2.2

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.
Files changed (77) hide show
  1. package/CONTRIBUTING.md +101 -0
  2. package/LICENSE +21 -0
  3. package/README.md +558 -0
  4. package/README.zh-CN.md +488 -0
  5. package/adapters/INTEGRATION.md +94 -0
  6. package/adapters/claude/README.md +141 -0
  7. package/adapters/claude/compatibility.json +17 -0
  8. package/adapters/claude/harness/README.md +59 -0
  9. package/adapters/claude/harness/mock_anthropic_api.mjs +47 -0
  10. package/adapters/claude/harness/run_scenario.sh +79 -0
  11. package/adapters/claude/harness/run_scenario_no_python3.sh +49 -0
  12. package/adapters/claude/hook_bridge.sh +33 -0
  13. package/adapters/claude/pre_tool_use.py +264 -0
  14. package/adapters/claude/settings.example.json +16 -0
  15. package/adapters/codex/harness/README.md +53 -0
  16. package/adapters/codex/harness/acceptance.py +226 -0
  17. package/adapters/dsh/README.md +62 -0
  18. package/adapters/dsh/cordis.patch.yml +30 -0
  19. package/adapters/dsh/lib/index.js +500 -0
  20. package/adapters/kimi-code/README.md +169 -0
  21. package/adapters/kimi-code/compatibility.json +17 -0
  22. package/adapters/kimi-code/config.example.toml +26 -0
  23. package/adapters/kimi-code/hook_bridge.sh +32 -0
  24. package/adapters/kimi-code/pre_tool_use.py +72 -0
  25. package/core/__init__.py +47 -0
  26. package/core/audit.py +86 -0
  27. package/core/classifier.py +1175 -0
  28. package/core/dialects.py +898 -0
  29. package/core/policy.py +817 -0
  30. package/core/recovery.py +700 -0
  31. package/core/redaction.py +1096 -0
  32. package/core/safe_view.py +212 -0
  33. package/docs/architecture.md +223 -0
  34. package/docs/compatibility.md +142 -0
  35. package/docs/development-note-unguarded-deletion.md +187 -0
  36. package/docs/friction.md +266 -0
  37. package/docs/harness-capabilities.md +72 -0
  38. package/docs/host-drift.md +142 -0
  39. package/docs/publishing-from-ephemeral-environments.md +104 -0
  40. package/docs/release-notes-0.2.0-rc1.md +46 -0
  41. package/docs/release-notes-0.2.0.md +72 -0
  42. package/docs/release-notes-0.2.1.md +78 -0
  43. package/docs/release-notes-0.2.2.md +120 -0
  44. package/docs/secret-guard-analysis.md +416 -0
  45. package/docs/secret-guard-architecture.md +93 -0
  46. package/docs/secret-guard-design.md +649 -0
  47. package/docs/test-report-claude-code-harness.md +462 -0
  48. package/docs/test-report-codex-gpt-5.6-sol.md +335 -0
  49. package/docs/test-report-codex-gpt-6-astra-high.md +129 -0
  50. package/docs/test-report-dsh-0.1.5-rc.1.md +84 -0
  51. package/docs/test-report-dsh-v0.1.1.md +126 -0
  52. package/docs/test-report-kimi-code-block.md +198 -0
  53. package/docs/test-report-zcode-glm-flash.md +241 -0
  54. package/docs/threat-model.md +44 -0
  55. package/doctor.py +756 -0
  56. package/live_sentinel.py +339 -0
  57. package/package.json +69 -0
  58. package/skills/delete-guard/SKILL.md +109 -0
  59. package/skills/delete-guard/agents/openai.yaml +4 -0
  60. package/skills/delete-guard/references/policy.md +161 -0
  61. package/skills/delete-guard/scripts/_bootstrap.py +8 -0
  62. package/skills/delete-guard/scripts/check.py +370 -0
  63. package/skills/delete-guard/scripts/gc.py +103 -0
  64. package/skills/delete-guard/scripts/restore.py +98 -0
  65. package/skills/delete-guard/scripts/safe_delete.py +256 -0
  66. package/skills/delete-guard/scripts/status.py +130 -0
  67. package/skills/exfil-guard/SKILL.md +143 -0
  68. package/skills/exfil-guard/agents/openai.yaml +4 -0
  69. package/skills/exfil-guard/references/channels.md +58 -0
  70. package/skills/exfil-guard/references/rules.md +194 -0
  71. package/skills/exfil-guard/scripts/_bootstrap.py +8 -0
  72. package/skills/exfil-guard/scripts/check_span.py +250 -0
  73. package/skills/exfil-guard/scripts/sanitize.py +155 -0
  74. package/skills/exfil-guard/scripts/view.py +44 -0
  75. package/skills/recovery-audit/SKILL.md +283 -0
  76. package/skills/recovery-audit/agents/openai.yaml +4 -0
  77. package/skills/recovery-audit/references/evidence-records.md +85 -0
@@ -0,0 +1,1096 @@
1
+ """Span classifier for outbound text payloads (exfil-guard).
2
+
3
+ Mirrors `classifier.py`'s contract - **facts, not decisions**. It turns a
4
+ blob of text into `SpanSpec` facts (what matched, where, how confident,
5
+ on which channel); `policy.decide_spans()` decides, and `sanitize.py`
6
+ applies a redaction plan. This module never imports policy.
7
+
8
+ Two families, one pipeline:
9
+
10
+ secret/* credentials that must not be emitted (T1 known patterns)
11
+ path/* host-identifying absolute paths (workspace-relative is ALLOW)
12
+
13
+ Hard invariant (design 2.4): **the guard reads names and shapes, never
14
+ secret values.** Detection classifies a `$VAR`'s *name*, never its content,
15
+ and no function here resolves an environment variable. Everything this
16
+ module returns that is meant to leave the process (JSON, audit) is built
17
+ from `SpanSpec.safe()` - offsets, rule id, length - never `raw`.
18
+
19
+ `raw` exists only because redaction needs the bytes to replace; it is held
20
+ in memory by the caller and never serialised.
21
+
22
+ Zero third-party dependencies; Python 3.9+ (no `match`, no runtime `X | Y`).
23
+ """
24
+ from __future__ import annotations
25
+
26
+ import base64
27
+ import binascii
28
+ import fnmatch
29
+ import hashlib
30
+ import json
31
+ import math
32
+ import os
33
+ import platform
34
+ import re
35
+ from dataclasses import dataclass, field
36
+ from typing import Any, Dict, Iterable, List, Optional, Sequence, Set, Tuple
37
+
38
+ # ------------------------------------------------------------- span types
39
+
40
+ FAMILY_SECRET = "secret"
41
+ FAMILY_PATH = "path"
42
+
43
+ CONFIDENCE_DETERMINISTIC = "deterministic"
44
+ CONFIDENCE_CONTEXTUAL = "contextual"
45
+
46
+ # Rule ids are payload, never verdict codes (design 2.2 rule 3).
47
+ RULE_OPENAI_KEY = "secret/openai-key"
48
+ RULE_GITHUB_TOKEN = "secret/github-token"
49
+ RULE_AWS_ACCESS_KEY_ID = "secret/aws-access-key-id"
50
+ RULE_GITLAB_TOKEN = "secret/gitlab-token"
51
+ RULE_SLACK_TOKEN = "secret/slack-token"
52
+ RULE_STRIPE_KEY = "secret/stripe-key"
53
+ RULE_JWT = "secret/jwt"
54
+ RULE_PRIVATE_KEY_BLOCK = "secret/private-key-block"
55
+ # A value-free reference to a secret source (env var name / secret store).
56
+ RULE_SECRET_SOURCE = "secret/source-reference"
57
+
58
+ RULE_HOST_ABSOLUTE_PATH = "path/host-absolute"
59
+ RULE_WORKSPACE_PATH = "path/workspace-relative"
60
+ RULE_GENERIC_ABSOLUTE_PATH = "path/generic-absolute"
61
+ RULE_SYSTEM_PATH = "path/system"
62
+ RULE_DEVICE_PATH = "path/device"
63
+
64
+ @dataclass
65
+ class SpanSpec:
66
+ """One matched region of text - the fact layer's unit of exchange."""
67
+
68
+ raw: str # matched substring, HELD IN MEMORY ONLY
69
+ start: int # character offset into the scanned text
70
+ end: int
71
+ rule_id: str # e.g. "secret/openai-key"
72
+ family: str # "secret" | "path"
73
+ confidence: str # "deterministic" | "contextual"
74
+ context: str # "prose" | "key=..." | "env-var" | ...
75
+ channel: str # egress channel carrying the payload
76
+ notes: List[str] = field(default_factory=list)
77
+ # Set by `scan_text`, never by a detector: the payload reads a secret
78
+ # store the guard cannot see into, so nothing here can be certified.
79
+ source_dump: bool = False
80
+ # Set by policy-facing callers to record that the *context gate* fired
81
+ # for a contextual (T3-class) match. Pure payload; no bytes.
82
+ context_gate: bool = False
83
+
84
+ @property
85
+ def length(self) -> int:
86
+ return self.end - self.start
87
+
88
+ def safe(self) -> Dict[str, Any]:
89
+ """The serialisable view: offsets and rule id, never the bytes.
90
+
91
+ This is the single chokepoint that keeps the guard from leaking
92
+ what it protects - `--json` output, audit records and explanations
93
+ are all built from this. There is deliberately no field for the
94
+ matched content.
95
+ """
96
+ return {
97
+ "rule_id": self.rule_id,
98
+ "family": self.family,
99
+ "confidence": self.confidence,
100
+ "context": self.context,
101
+ "channel": self.channel,
102
+ "start": self.start,
103
+ "end": self.end,
104
+ "length": self.length,
105
+ }
106
+
107
+
108
+ def merge_spans(spans: Sequence[SpanSpec]) -> List[SpanSpec]:
109
+ """Sort by position and drop spans that overlap an already-kept one.
110
+
111
+ Kept deterministic: earlier start wins, longer span wins on a tie, so
112
+ a private-key block can never be fragmented by a narrower match inside
113
+ it. Returns a new list; inputs are not mutated.
114
+ """
115
+ ordered = sorted(spans, key=lambda s: (s.start, -(s.end - s.start)))
116
+ kept: List[SpanSpec] = []
117
+ for span in ordered:
118
+ if kept and span.start < kept[-1].end:
119
+ continue
120
+ kept.append(span)
121
+ return kept
122
+
123
+ # --------------------------------------------------- placeholder allowlist
124
+
125
+ # Design 5.1: the static allowlist. In-repo and versioned, so a deployment
126
+ # scanning this repository does not fail on its own test fixtures.
127
+ PLACEHOLDER_WORDS = frozenset({
128
+ "your_api_key_here", "your_token_here", "your_secret_here",
129
+ "your-api-key", "your_api_key",
130
+ "changeme", "change_me", "change-me", "replaceme", "replace_me",
131
+ "dummy", "example", "sample", "fake", "test", "testing", "todo",
132
+ "placeholder", "redacted", "none", "null", "notset", "unset",
133
+ "xxxx", "xxxxxxxx", "yourtoken", "mysupersecret", "hunter2",
134
+ })
135
+ # Marker shapes: <REDACTED>, [REDACTED], ***, _<<REDACTED>>_ ...
136
+ _PLACEHOLDER_SHAPE_RE = re.compile(
137
+ r"^[\W_]*(?:redacted|removed|hidden|scrubbed|elided|omitted)[\W_]*$",
138
+ re.IGNORECASE)
139
+ _REDACTED_MARKER = "<REDACTED>"
140
+
141
+ # A token is only a placeholder if its *alphabet* is trivial (one symbol,
142
+ # '*'/'x'/'.' runs, sequences like abcdef) or if it is a known word. The
143
+ # point is to stay in the low-entropy regime, where a real credential can
144
+ # never live.
145
+ _SEQUENTIAL_ALPHABETS = ("abcdefghijklmnopqrstuvwxyz",
146
+ "0123456789",
147
+ "abcdefghijklmnopqrstuvwxyz0123456789")
148
+
149
+
150
+ def _is_trivial_alphabet(token: str) -> bool:
151
+ if len(set(token)) <= 1:
152
+ return True # xxxx, ********, ....
153
+ lower = token.lower()
154
+ if lower in _SEQUENTIAL_ALPHABETS:
155
+ return True
156
+ for alphabet in _SEQUENTIAL_ALPHABETS:
157
+ for start in range(len(alphabet)):
158
+ for length in range(4, len(alphabet) - start + 1):
159
+ if lower == alphabet[start:start + length]:
160
+ return True
161
+ return False
162
+
163
+
164
+ def is_placeholder(token: str) -> bool:
165
+ """True when a matched value is provably not a real credential.
166
+
167
+ Never throws: the allowlist runs inside the detection hot path, and a
168
+ classification failure there must not be able to fail *open*.
169
+ """
170
+ try:
171
+ return _is_placeholder(token)
172
+ except Exception: # pragma: no cover - defensive
173
+ return False
174
+
175
+
176
+ def _is_placeholder(token: str) -> bool:
177
+ value = token.strip().strip("'\"`()[]<>").strip()
178
+ if not value:
179
+ return False
180
+ if value == _REDACTED_MARKER:
181
+ return True # idempotence (design 2.5)
182
+ if _PLACEHOLDER_SHAPE_RE.match(value):
183
+ return True
184
+ if value.startswith("<") and value.endswith(">"):
185
+ return True # <YOUR_KEY>, <token>
186
+ if value.startswith("${") and value.endswith("}"):
187
+ return True # shell interpolation in a doc
188
+ collapsed = re.sub(r"[^A-Za-z0-9]+", "", value).lower()
189
+ if not collapsed:
190
+ return True # "***", "---": no credential bytes
191
+ for word in PLACEHOLDER_WORDS:
192
+ flat = re.sub(r"[^A-Za-z0-9]+", "", word)
193
+ if collapsed == flat:
194
+ return True
195
+ # Prefixed/suffixed word: "EXAMPLE_SECRET", "sk-test", "fake-key".
196
+ # Only the documented words count, so ordinary credentials are
197
+ # untouched (a real key never ends in "token").
198
+ if collapsed.startswith(flat) or collapsed.endswith(flat):
199
+ return True
200
+ return _is_trivial_alphabet(value)
201
+
202
+
203
+ def _looks_placeholderish(token: str) -> bool:
204
+ """Cheap pre-check used before running the full placeholder test."""
205
+ if not token:
206
+ return True
207
+ if len(set(token)) <= 1:
208
+ return True
209
+ collapsed = re.sub(r"[^A-Za-z0-9]+", "", token).lower()
210
+ if not collapsed:
211
+ return True
212
+ return any(w in collapsed for w in ("xxx", "redact", "placeholder",
213
+ "changeme", "dummy"))
214
+
215
+ # -------------------------------------------------------- T1 vendor patterns
216
+
217
+ # Each entry is (rule_id, compiled regex, validator). Vendor prefixes are
218
+ # distinct enough that an anchored prefix + shape gives near-zero false
219
+ # positives; where the format allows, a validator adds real structure
220
+ # (design 2.2 rule 1 - a JWT is only a JWT if its header decodes).
221
+ _OPENAI_RE = re.compile(r"\bsk-(?:proj|ant|live)?-?([A-Za-z0-9_\-]{20,})")
222
+ _GITHUB_RE = re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b"
223
+ r"|\bgithub_pat_[A-Za-z0-9_]{22,255}\b")
224
+ _AWS_KEY_ID_RE = re.compile(r"\b(?:AKIA|ASIA|AGPA|AIDA|AROA|ANPA)[0-9A-Z]{16}\b")
225
+ _GITLAB_RE = re.compile(r"\bglpat-[A-Za-z0-9_\-]{20,}")
226
+ _SLACK_RE = re.compile(r"\bxox[baprs]-[A-Za-z0-9\-]{10,}")
227
+ _STRIPE_RE = re.compile(r"\b(?:sk|rk)_live_[A-Za-z0-9]{16,}")
228
+ _JWT_RE = re.compile(
229
+ r"\beyJ[A-Za-z0-9_\-]{4,}\.[A-Za-z0-9_\-]{4,}\.[A-Za-z0-9_\-]{4,}")
230
+ _PRIVATE_KEY_RE = re.compile(
231
+ r"-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----.*?"
232
+ r"-----END (?:[A-Z0-9]+ )*PRIVATE KEY-----",
233
+ re.DOTALL)
234
+ # Secret-store file names: a *path* fact (design 2.4 item 3). Reading these
235
+ # on an outbound channel is refused rather than sanitized, because the
236
+ # guard cannot see the content it would be rewriting.
237
+ SECRET_STORE_NAMES = frozenset({
238
+ ".env", ".npmrc", ".netrc", ".pgpass", ".htpasswd", "credentials",
239
+ "id_rsa", "id_dsa", "id_ecdsa", "id_ed25519", "kubeconfig",
240
+ })
241
+ SECRET_STORE_SUFFIXES = (".pem", ".key", ".p12", ".pfx", ".tfvars",
242
+ ".keystore", ".jks")
243
+ # `.env` and its dotted variants (`.env.local`, `.env.production`): these
244
+ # are the same secret store, and `.env.local` is the file people actually
245
+ # commit by accident.
246
+ SECRET_STORE_ENV_RE = re.compile(r"(?<![\w.@])\.env(?:\.[A-Za-z0-9_-]+)?"
247
+ r"(?![\w-])")
248
+ # Whole-environment expansion: value-free detection (T2), ASK-only.
249
+ # "Read the WHOLE environment": the *shape* of the command, not the word.
250
+ # Design 2.4 item 4 - only the no-argument expansion forms are dumps:
251
+ # `env`, `env | grep X`, `printenv`, `set`, `export -p`, /proc/self/environ
252
+ # `env FOO=bar cmd` and `printenv FOO` are *not* dumps (they name what they
253
+ # touch), and prose that merely contains the word "env" is not a command.
254
+ # A rule that fires on documentation is a rule that gets disabled.
255
+ # `env`/`printenv`/`set` must also be *invoked as a command*: at the start
256
+ # of the payload (optionally after a shell separator) or followed by a pipe.
257
+ # Without that anchor, any line of Python (`if env:`) or any regex that
258
+ # quotes the word would be read as a dump - and this repository's own source
259
+ # is exactly that. Only the whole-environment expansion forms count
260
+ # (design 2.4 item 4): `printenv FOO` and `env FOO=bar cmd` name what they
261
+ # touch and are not dumps.
262
+ _SHELL_AT_START = r"(?:^|[;&|]\s*|\$\s+)"
263
+ ENV_DUMP_RE = re.compile(
264
+ _SHELL_AT_START + r"(?:env|printenv)\s*\|"
265
+ r"|" + _SHELL_AT_START + r"(?:env|printenv|export\s+-p|set)\s*$"
266
+ r"|(?<![\w.])cat\s+/proc/self/environ", re.MULTILINE)
267
+
268
+
269
+ def _b64url_json_has_alg(segment: str) -> bool:
270
+ """Structural JWT check: the header segment must decode to JSON+`alg`."""
271
+ if len(segment) % 4 == 1:
272
+ return False
273
+ padded = segment + "=" * (-len(segment) % 4)
274
+ try:
275
+ decoded = base64.urlsafe_b64decode(padded.encode("ascii"))
276
+ except (binascii.Error, ValueError, UnicodeEncodeError):
277
+ return False
278
+ try:
279
+ header = json.loads(decoded.decode("utf-8"))
280
+ except (ValueError, UnicodeDecodeError):
281
+ return False
282
+ return isinstance(header, dict) and "alg" in header
283
+
284
+
285
+ def _note_context(text: str, index: int) -> str:
286
+ """The introduction of a match: 'prose' or 'key=<word>'."""
287
+ line_start = text.rfind("\n", 0, index) + 1
288
+ prefix = text[line_start:index]
289
+ match = re.search(r"([A-Za-z_][A-Za-z0-9_\-]*)\s*[:=]\s*[\"']?\s*$", prefix)
290
+ return "key=" + match.group(1) if match else "prose"
291
+
292
+
293
+ def detect_secrets(text: str, channel: str = "") -> List[SpanSpec]:
294
+ """T1 known-pattern detection: deterministic, near-zero false positives.
295
+
296
+ Placeholder and already-redacted matches are dropped here (they are
297
+ facts the policy layer would otherwise have to re-litigate): the
298
+ allowlist is deterministic and needs no config (design 5.1).
299
+ """
300
+ spans: List[SpanSpec] = []
301
+
302
+ def add(match: "re.Match[str]", rule_id: str, notes: Iterable[str] = ()):
303
+ raw = match.group(0)
304
+ if is_placeholder(raw) or _looks_placeholderish(raw):
305
+ return
306
+ spans.append(SpanSpec(
307
+ raw=raw, start=match.start(), end=match.end(), rule_id=rule_id,
308
+ family=FAMILY_SECRET, confidence=CONFIDENCE_DETERMINISTIC,
309
+ context=_note_context(text, match.start()), channel=channel,
310
+ notes=list(notes)))
311
+
312
+ for match in _PRIVATE_KEY_RE.finditer(text):
313
+ add(match, RULE_PRIVATE_KEY_BLOCK,
314
+ ["whole block withheld; header/trailer identify it unambiguously"])
315
+ for match in _OPENAI_RE.finditer(text):
316
+ add(match, RULE_OPENAI_KEY, ["vendor prefix + length + charset"])
317
+ for match in _GITHUB_RE.finditer(text):
318
+ add(match, RULE_GITHUB_TOKEN, ["fixed-format vendor prefix"])
319
+ for match in _AWS_KEY_ID_RE.finditer(text):
320
+ add(match, RULE_AWS_ACCESS_KEY_ID, ["reserved vendor prefix"])
321
+ for match in _GITLAB_RE.finditer(text):
322
+ add(match, RULE_GITLAB_TOKEN, ["vendor prefix"])
323
+ for match in _SLACK_RE.finditer(text):
324
+ add(match, RULE_SLACK_TOKEN, ["vendor prefix"])
325
+ for match in _STRIPE_RE.finditer(text):
326
+ add(match, RULE_STRIPE_KEY, ["prefix + live mode (test keys exempt)"])
327
+ for match in _JWT_RE.finditer(text):
328
+ header = match.group(0).split(".", 1)[0]
329
+ if not _b64url_json_has_alg(header):
330
+ continue
331
+ add(match, RULE_JWT, ["header segment decodes to JSON containing alg"])
332
+ return merge_spans(spans)
333
+
334
+
335
+ # ------------------------------------------------------------ path detection
336
+ #
337
+ # Design 3.1: the workspace-relative exemption is the core rule. A path is
338
+ # only a host identifier if it is OUTSIDE the workspace - so the guard uses
339
+ # the one boundary it already computes confidently (delete-guard's
340
+ # `discover_workspace`) and treats everything else as suspect UNLESS it is a
341
+ # well-known system prefix. An absolute path with no prefix correlation at
342
+ # all is only `contextual`, which keeps the default quiet (design 3.4/5.6).
343
+
344
+ # POSIX absolute path. `~` is deliberately not a component character: it is
345
+ # left-trimmed by the boundary, so `~/x/y` is redacted rather than being
346
+ # lexed as a literal `~` directory name.
347
+ # The lookbehind excludes `.` and `~` as well as word chars: without them
348
+ # the pattern cuts a relative path in half (`./src/main.py` -> `/src/main.py`
349
+ # is a host-absolute-looking match for a path that never left the workspace).
350
+ # The group requires at least one separator, which is design 3.2's ">= 2
351
+ # components" floor - without it a bare `/` (which occurs in every sentence
352
+ # that contains a slash) would match.
353
+ _POSIX_PATH_RE = re.compile(
354
+ r"(?<![\w:/~.])/(?:[A-Za-z0-9._@+-]+/)+[A-Za-z0-9._@+-]+")
355
+ # Windows drive-absolute, UNC and device paths: `C:\a\b`, `C:/a`, `\\\\h\\s`,
356
+ # `\\\\?\\C:\\x`, `\\\\.\\pipe\\p`.
357
+ _WINDOWS_PATH_RE = re.compile(
358
+ r"(?<![\w:])[A-Za-z]:[\\/](?:[^\\/\s\"'<>|;:]+[\\/])*[^\\/\s\"'<>|;:]*"
359
+ r"|\\\\[^\\/\s]{1,}[\\/][^\\/\s]+(?:[\\/][^\\/\s\"'<>|;]*)*")
360
+ # Windows environment interpolation: a path we cannot resolve (design 3.2).
361
+ # A `%VAR%`/`$env:X` token is a *path* fact only where it introduces one;
362
+ # `%dT%` in a strftime format string is not a path and must stay quiet.
363
+ _WINDOWS_ENV_RE = re.compile(
364
+ r"(?:%[A-Za-z_][A-Za-z0-9_]*%|\$env:[A-Za-z_][A-Za-z0-9_]*)[\\/]")
365
+
366
+ # System prefixes that identify the operating system, not the host. ALLOW by
367
+ # default (design 3.1/exotic-last row), configurable via AGENT_GUARD_SYSTEM_PREFIXES.
368
+ DEFAULT_SYSTEM_PREFIXES = (
369
+ "/usr", "/bin", "/sbin", "/lib", "/lib64", "/opt", "/etc", "/var",
370
+ "/proc", "/sys", "/dev", "/srv", "/run", "/boot", "/snap", "/nix",
371
+ "/Applications", "/System", "/Library", "/dev/null",
372
+ "C:\\Windows", "C:\\Program Files", "C:\\Program Files (x86)",
373
+ "C:\\ProgramData",
374
+ )
375
+ # Prefixes that host-qualify a location so strongly that they are treated as
376
+ # identifying even though they sit under a system-looking root (design 3.2
377
+ # "CI runners" / "Sandboxes" rows). Checked BEFORE the system prefixes:
378
+ # a CI workspace is `/home/runner/work/...`, and `/var/lib/jenkins` is a
379
+ # runner home, not a system directory.
380
+ _CI_ROOT_PREFIXES = ("/home/", "/Users/", "/root", "/Volumes/",
381
+ "/var/folders/", "/tmp/", "/workspace", "/builds",
382
+ "/runner/", "/github/workspace", "/var/lib/jenkins",
383
+ "/private/var/folders/", "/private/tmp", "/private/home",
384
+ "/private/Users", "/private/root", "/private/var/tmp")
385
+ # Locations that look like host paths but name a convention instead: macOS
386
+ # ships `/Users/Shared`, and `/opt`, `/usr/local` are install roots.
387
+ _EXEMPT_ABSOLUTE = ("/Users/Shared", "/usr/local", "/opt")
388
+
389
+
390
+ def _split_env_list(value: str) -> List[str]:
391
+ return [item.strip() for item in re.split(r"[:;,]", value) if item.strip()]
392
+
393
+
394
+ def host_markers() -> Dict[str, Any]:
395
+ """Derive the deny-set of host prefixes (design 3.3) - a set of literals,
396
+ never a pattern, and one that degrades portably when `getpass` fails.
397
+
398
+ Reads *names and shapes* only: `os.environ` is consulted for HOME-like
399
+ location prefixes (the actual things to redact), never for secret values.
400
+ """
401
+ names: Set[str] = set()
402
+ prefixes: Set[str] = set()
403
+ hostnames: Set[str] = set()
404
+
405
+ for key in ("HOME", "USERPROFILE", "LOCALAPPDATA", "TEMP", "TMP"):
406
+ value = os.environ.get(key)
407
+ if value and os.path.isabs(value):
408
+ prefixes.add(os.path.normpath(value))
409
+ try:
410
+ home = os.path.expanduser("~")
411
+ except Exception: # pragma: no cover - exotic setups
412
+ home = ""
413
+ if home and os.path.isabs(home):
414
+ prefixes.add(os.path.normpath(home))
415
+
416
+ try:
417
+ import getpass
418
+ user = getpass.getuser()
419
+ except Exception: # pragma: no cover - container/CI
420
+ user = ""
421
+ for candidate in (user, os.environ.get("USER"),
422
+ os.environ.get("LOGNAME"), os.environ.get("USERNAME")):
423
+ if candidate:
424
+ names.add(candidate)
425
+ if home:
426
+ names.add(os.path.basename(home))
427
+
428
+ for key in ("AGENT_GUARD_HOSTNAMES", "AGENT_GUARD_HOME_MARKERS"):
429
+ extra = os.environ.get(key)
430
+ if extra:
431
+ names.update(_split_env_list(extra))
432
+ for key in ("AGENT_GUARD_HOME_PREFIXES",):
433
+ extra = os.environ.get(key)
434
+ if extra:
435
+ prefixes.update(_split_env_list(extra))
436
+
437
+ try:
438
+ hostnames.add(platform.node())
439
+ import socket
440
+ hostnames.add(socket.gethostname())
441
+ except Exception: # pragma: no cover - exotic setups
442
+ pass
443
+ hostnames.discard("")
444
+
445
+ overrides = os.environ.get("AGENT_GUARD_SYSTEM_PREFIXES")
446
+ system_prefixes = (tuple(_split_env_list(overrides)) if overrides
447
+ else DEFAULT_SYSTEM_PREFIXES)
448
+ return {"prefixes": prefixes, "names": names, "hostnames": hostnames,
449
+ "system_prefixes": system_prefixes}
450
+
451
+
452
+ def workspace_ancestors(workspace: Optional[str]) -> List[str]:
453
+ """Ancestors of the workspace root: by definition not to be echoed raw.
454
+
455
+ The filesystem root is excluded deliberately. It is *technically* an
456
+ ancestor of every workspace, but treating `/` as identifying would make
457
+ the rule a no-op (nothing is more generic than `/`), and the same is
458
+ true of any single-component prefix such as `/home` or `C:\\` - those
459
+ carry no identity and are the documented generic tier (design 3.3).
460
+ """
461
+ if not workspace:
462
+ return []
463
+ physical = os.path.normpath(os.path.realpath(os.path.abspath(workspace)))
464
+ out: List[str] = []
465
+ current = physical
466
+ while True:
467
+ parent = os.path.dirname(current)
468
+ if parent == current: # reached the root
469
+ break
470
+ if parent != os.path.dirname(parent) or os.sep not in parent:
471
+ # parent is itself a root ("/" or "C:\"): not identifying.
472
+ break
473
+ out.append(parent)
474
+ current = parent
475
+ return [p for p in out if len(p.strip(os.sep)) > 1]
476
+
477
+
478
+ @dataclass
479
+ class PathVerdict:
480
+ """One detected path with its boundary facts (facts, not decisions)."""
481
+
482
+ raw: str
483
+ start: int
484
+ end: int
485
+ path: str # normalized comparison form
486
+ windows: bool = False
487
+ absolute: bool = True
488
+ inside_workspace: bool = False
489
+ at_workspace_root: bool = False
490
+ is_system: bool = False
491
+ deterministic: bool = False # matched the host deny-set
492
+ notes: List[str] = field(default_factory=list)
493
+
494
+ @property
495
+ def length(self) -> int:
496
+ return self.end - self.start
497
+
498
+
499
+ def _normalize_candidate(raw: str, windows: bool) -> str:
500
+ """Normalize for comparison only; the raw spelling drives the rewrite.
501
+
502
+ Returns a platform-appropriate normalized form: on Windows the result
503
+ keeps ``\\`` separators (UNC/device detection depends on
504
+ ``normalized.startswith('\\\\')``), on POSIX it keeps ``/``. Downstream
505
+ callers must not assume one separator — ``_path_is_under`` handles
506
+ that for its own comparisons, and UNC detection happens before any
507
+ separator-sensitive prefix test.
508
+
509
+ The reason we do NOT simply flip everything to ``/``: Windows
510
+ ``os.path.normpath`` flips ``/`` to ``\\`` anyway, so on a Windows host
511
+ any POSIX-style input like ``/usr/lib`` would end up as ``\\usr\\lib``
512
+ and then every prefix test (all of which use ``"/usr"``) would fail —
513
+ which is exactly what the classify layer's `windows` flag exists to
514
+ avoid.
515
+ """
516
+ value = raw.rstrip(".,;:!?)\"'`")
517
+ if len(value) > 1 and value.endswith(("/", "\\")):
518
+ value = value[:-1]
519
+ if windows:
520
+ return os.path.normpath(value.replace("/", "\\"))
521
+ return os.path.normpath(value.replace("\\", "/"))
522
+
523
+
524
+ def _to_posix(path: str) -> str:
525
+ """Convert any platform path to forward-slash form for prefix tests."""
526
+ return path.replace("\\", "/")
527
+
528
+
529
+ def _clean_candidate(text: str, span: "re.Match[str]") -> Optional[str]:
530
+ """The match, minus sentence punctuation and balanced wrapping."""
531
+ start, end = span.start(), span.end()
532
+ segment = text[start:end]
533
+ # A `(...)`-wrapped path (markdown link target) is redacted whole.
534
+ if start > 0 and end < len(text) and text[start - 1] == "(" \
535
+ and text[end] == ")":
536
+ return "(" + segment + ")"
537
+ return segment
538
+
539
+
540
+ def _path_is_under(path: str, prefix: str, windows: bool) -> bool:
541
+ if windows:
542
+ a = path.replace("\\", "/").lower()
543
+ b = prefix.replace("\\", "/").lower()
544
+ else:
545
+ a, b = path, prefix
546
+ if a == b:
547
+ return True
548
+ return a.startswith(b.rstrip("/") + "/")
549
+
550
+
551
+ def classify_path_candidate(raw: str, workspace: Optional[str],
552
+ markers: Optional[Dict[str, Any]] = None,
553
+ windows: Optional[bool] = None
554
+ ) -> Optional[PathVerdict]:
555
+ """Fact extraction for one candidate path string."""
556
+ markers = markers or host_markers()
557
+ if windows is None:
558
+ windows = bool(_WINDOWS_PATH_RE.fullmatch(raw))
559
+ value = raw.rstrip(".,;:!?)\"'`")
560
+ if not value:
561
+ return None
562
+ if value.startswith("(") and value.endswith(")"):
563
+ value = value[1:-1]
564
+
565
+ # Separator normalization is only sound when the string actually IS a
566
+ # path: Windows accepts both separators, POSIX does not (a backslash is
567
+ # an ordinary filename byte), and fabricating semantics is the exact
568
+ # mistake `classifier._is_windows_absolute` documents.
569
+ normalized = _normalize_candidate(value, windows)
570
+ # POSIX form for every subsequent prefix test — handles mixed
571
+ # platform inputs (a Windows host seeing "/usr/lib", or a Linux host
572
+ # seeing a path that was realpath'd somewhere). UNC/device detection
573
+ # (which needs the raw `\\` prefix) stays on `normalized`.
574
+ posix = _to_posix(normalized)
575
+ fact = PathVerdict(raw=raw, start=0, end=len(raw), path=posix,
576
+ windows=windows)
577
+
578
+ prefix_pool = [_to_posix(p) for p in markers["prefixes"]]
579
+ system = tuple(_to_posix(s) for s in markers["system_prefixes"])
580
+ exempt_locations = [_to_posix(e) for e in _EXEMPT_ABSOLUTE]
581
+
582
+ if windows:
583
+ # A bare drive root (`C:\`) identifies the OS layout, not a host, and
584
+ # carries no path at all. Design 3.2's component floor applies here
585
+ # too; a real Windows path has at least two components.
586
+ if re.fullmatch(r"[A-Za-z]:[\\/]?", normalized):
587
+ fact.is_system = True
588
+ return fact
589
+ for system_prefix in system:
590
+ if _path_is_under(posix, system_prefix, True):
591
+ fact.is_system = True
592
+ return fact
593
+
594
+ # A path at or under a known host prefix (HOME/TEMP/USERPROFILE) or any
595
+ # workspace ancestor is deterministic - a literal deny-set match, not a
596
+ # guess. Workspace ancestors are checked first because they are the most
597
+ # trusted source (design 3.3).
598
+ #
599
+ # IMPORTANT: we intentionally do NOT call os.path.realpath() or
600
+ # os.path.abspath() on `workspace`. Those would prefix a drive letter
601
+ # on Windows (turning "/home/alice/work/agent-guard" into
602
+ # "C:\\home\\alice\\work\\agent-guard") and break cross-platform
603
+ # workspace matching. Callers pass the workspace in canonical form.
604
+ if workspace:
605
+ ws_windows = bool(_WINDOWS_PATH_RE.fullmatch(workspace))
606
+ physical_posix = _to_posix(_normalize_candidate(workspace, ws_windows))
607
+ if _path_is_under(posix, physical_posix, False):
608
+ fact.inside_workspace = True
609
+ fact.at_workspace_root = posix == physical_posix
610
+ return fact
611
+ for ancestor in workspace_ancestors(workspace):
612
+ anc_posix = _to_posix(ancestor)
613
+ if _path_is_under(posix, anc_posix, False):
614
+ fact.deterministic = True
615
+ fact.notes.append("workspace ancestor")
616
+ return fact
617
+
618
+ for prefix in sorted(prefix_pool, key=len, reverse=True):
619
+ if _path_is_under(posix, prefix, False):
620
+ fact.deterministic = True
621
+ fact.notes.append("home/temp prefix: " + prefix)
622
+ return fact
623
+
624
+ for safe in exempt_locations:
625
+ if _path_is_under(posix, safe, False):
626
+ fact.is_system = True
627
+ fact.notes.append("documented non-identifying location")
628
+ return fact
629
+
630
+ for name in sorted(markers["names"], key=len, reverse=True):
631
+ if len(name) < 3:
632
+ continue
633
+ if any(_path_is_under(posix, base + name, False)
634
+ for base in ("/home/", "/Users/", "/Volumes/", "/root/")) \
635
+ or _path_is_under(posix, "C:/Users/" + name, False):
636
+ fact.deterministic = True
637
+ fact.notes.append("interpolated home marker")
638
+ return fact
639
+
640
+ if windows:
641
+ # UNC/device roots carry a host or device name — check on the raw
642
+ # normalized string (preserves `\\` prefix).
643
+ if normalized.startswith("\\\\"):
644
+ fact.deterministic = True
645
+ fact.notes.append("UNC/device root")
646
+ return fact
647
+ return fact # generic drive path: contextual
648
+
649
+ # Single-component paths ("/project", "/tmp") name a *convention*, not a
650
+ # host: `/home`, `/Users` and `/etc` occur in every document that talks
651
+ # about paths. Design 3.2's ">= 2 components OR a known-root tie-in"
652
+ # floor is enforced here, which is what keeps this repository's own prose
653
+ # quiet.
654
+ if posix.count("/") < 2:
655
+ fact.notes.append("single-component path: no host identity")
656
+ return fact
657
+ for ci in _CI_ROOT_PREFIXES:
658
+ ci_posix = _to_posix(ci)
659
+ if _path_is_under(posix, ci_posix, False):
660
+ fact.deterministic = True
661
+ fact.notes.append("host-identifying root: " + ci)
662
+ return fact
663
+ for system_prefix in system:
664
+ if _path_is_under(posix, system_prefix, False):
665
+ fact.is_system = True
666
+ return fact
667
+ for hostname in markers["hostnames"]:
668
+ if hostname and hostname in posix:
669
+ fact.deterministic = True
670
+ fact.notes.append("hostname in path")
671
+ return fact
672
+ return fact # generic absolute path
673
+
674
+
675
+ def detect_paths(text: str, workspace: Optional[str] = None,
676
+ channel: str = "") -> List[SpanSpec]:
677
+ """Absolute-path spans in `text`, with boundary facts in `notes`.
678
+
679
+ Fact layer only: ALLOW/SANITIZE/ASK is `policy.decide_spans`'s call.
680
+ """
681
+ markers = host_markers()
682
+ spans: List[SpanSpec] = []
683
+ occupied: List[Tuple[int, int]] = []
684
+
685
+ def emit(fact: PathVerdict, notes: Iterable[str]):
686
+ if "UNC/device root" in fact.notes:
687
+ rule_id = RULE_DEVICE_PATH
688
+ elif fact.inside_workspace:
689
+ # Not a host identifier at all (design 3.1): the exemption is a
690
+ # rule id of its own so the policy layer never has to infer it
691
+ # from the notes list.
692
+ rule_id = RULE_WORKSPACE_PATH
693
+ elif fact.is_system:
694
+ rule_id = RULE_SYSTEM_PATH
695
+ elif fact.deterministic:
696
+ rule_id = RULE_HOST_ABSOLUTE_PATH
697
+ else:
698
+ rule_id = RULE_GENERIC_ABSOLUTE_PATH
699
+ if "UNC/device root" in fact.notes and rule_id == RULE_DEVICE_PATH:
700
+ confidence = CONFIDENCE_DETERMINISTIC
701
+ else:
702
+ confidence = (CONFIDENCE_DETERMINISTIC
703
+ if (fact.deterministic or fact.is_system)
704
+ else CONFIDENCE_CONTEXTUAL)
705
+ span = SpanSpec(
706
+ raw=fact.raw, start=fact.start, end=fact.end, rule_id=rule_id,
707
+ family=FAMILY_PATH, confidence=confidence,
708
+ context=_note_context(text, fact.start), channel=channel,
709
+ notes=list(notes) + list(fact.notes))
710
+ spans.append(span)
711
+ occupied.append((span.start, span.end))
712
+
713
+ def overlaps(start: int, end: int) -> bool:
714
+ return any(start < e and end > s for s, e in occupied)
715
+
716
+ def consider(match: "re.Match[str]", windows: bool):
717
+ raw = _clean_candidate(text, match)
718
+ if raw is None:
719
+ return
720
+ start, end = match.start(), match.start() + len(raw)
721
+ if overlaps(start, end):
722
+ return
723
+ fact = classify_path_candidate(raw, workspace, markers, windows)
724
+ if fact is None:
725
+ return
726
+ fact.raw, fact.start, fact.end = raw, start, end
727
+ emit(fact, [])
728
+
729
+ for match in _WINDOWS_ENV_RE.finditer(text):
730
+ if overlaps(match.start(), match.end()):
731
+ continue
732
+ emit(PathVerdict(raw=match.group(0), start=match.start(),
733
+ end=match.end(), path=match.group(0),
734
+ windows=True, absolute=False,
735
+ deterministic=False,
736
+ notes=["unresolvable Windows environment reference"]),
737
+ ["interpolation: the path cannot be resolved"])
738
+ # Windows paths first: a backslash spelling is unambiguous, so it must
739
+ # not be nibbled at by the POSIX pattern.
740
+ for match in _WINDOWS_PATH_RE.finditer(text):
741
+ consider(match, True)
742
+ for match in _POSIX_PATH_RE.finditer(text):
743
+ consider(match, False)
744
+ return merge_spans(spans)
745
+
746
+
747
+ # ------------------------------------------------------------ egress channels
748
+ #
749
+ # Design 4.1: a channel is defined by exactly two facts, and the decision
750
+ # table keys off both. `rewritable` is what makes SANITIZE meaningful (the
751
+ # guard can hand the caller a plan); `persistence` is what justifies BLOCK
752
+ # (the emission cannot be taken back). A channel that is neither can only
753
+ # ASK - it cannot un-print.
754
+
755
+ CHANNEL_UNREACHABLE = "unreachable"
756
+
757
+
758
+ @dataclass(frozen=True)
759
+ class Channel:
760
+ name: str
761
+ rewritable: bool
762
+ persistence: str # "none" | "local" | "workspace" | "remote" | "public"
763
+ default_decision: str # SANITIZE | ASK | BLOCK
764
+ reachability: str = "hook" # "hook" | "unreachable"
765
+
766
+
767
+ # The taxonomy is closed on purpose: an unknown channel name is a
768
+ # configuration defect (fail closed, design 6.3), never an implicit
769
+ # "no channel, no risk".
770
+ CHANNELS: Dict[str, Channel] = {
771
+ "llm-request": Channel("llm-request", True, "remote", "SANITIZE"),
772
+ "file-write": Channel("file-write", True, "workspace", "SANITIZE"),
773
+ "forge-comment": Channel("forge-comment", True, "public", "SANITIZE"),
774
+ "issue-body": Channel("issue-body", True, "public", "SANITIZE"),
775
+ "pr-description": Channel("pr-description", True, "public", "SANITIZE"),
776
+ "git-commit-message": Channel("git-commit-message", True, "remote",
777
+ "BLOCK"),
778
+ "git-push-payload": Channel("git-push-payload", False, "remote", "BLOCK"),
779
+ "shell-stdout": Channel("shell-stdout", False, "local", "ASK"),
780
+ "shell-file-redirect": Channel("shell-file-redirect", True, "local",
781
+ "ASK"),
782
+ "archive-upload": Channel("archive-upload", True, "remote", "ASK"),
783
+ "process-argv": Channel("process-argv", True, "local", "ASK"),
784
+ }
785
+
786
+ # Explicitly out of reach (design 4.4 "unreachable channel"): the guard
787
+ # never claims coverage here, and never implies a verdict it cannot see.
788
+ UNREACHABLE_CHANNELS = frozenset({"hosted-llm-no-proxy", "agent-tool-call",
789
+ "program-internal-output", "human-clipboard"})
790
+
791
+ # A channel with no persistence at all can only ASK when it cannot rewrite:
792
+ # there is nothing to refuse *for* once the bytes are already visible.
793
+ _NON_PERSISTENT = frozenset({"none", "local"})
794
+
795
+
796
+ def get_channel(name: str) -> Optional[Channel]:
797
+ """Look up a channel by name; None means the configuration is invalid."""
798
+ if not name:
799
+ return None
800
+ return CHANNELS.get(name.strip().lower())
801
+
802
+
803
+ # --------------------------------------------------------------- scan entry
804
+
805
+ # Explicit size cap (design 6.3): a payload we did not scan must never be
806
+ # reported as clean, so exceeding the cap is a BLOCK-class fact, not a
807
+ # silent truncation.
808
+ DEFAULT_MAX_SCAN_BYTES = 4 * 1024 * 1024
809
+
810
+
811
+ @dataclass
812
+ class ScanResult:
813
+ """The outcome of scanning one payload - facts plus scanner status."""
814
+
815
+ spans: List[SpanSpec] = field(default_factory=list)
816
+ scanned: bool = True
817
+ error: str = ""
818
+ truncated: bool = False
819
+ size_bytes: int = 0
820
+ exempted: int = 0
821
+
822
+ @property
823
+ def found(self) -> bool:
824
+ return bool(self.spans)
825
+
826
+
827
+ def max_scan_bytes() -> int:
828
+ raw = os.environ.get("AGENT_GUARD_EXFIL_MAX_BYTES")
829
+ if raw:
830
+ try:
831
+ value = int(raw)
832
+ if value > 0:
833
+ return value
834
+ except ValueError:
835
+ pass
836
+ return DEFAULT_MAX_SCAN_BYTES
837
+
838
+
839
+ # The secret-store *names* are data (SECRET_STORE_NAMES/SUFFIXES); the
840
+ # regexes below only find them in a read position.
841
+ _STORE_NAME_ALT = "|".join(re.escape(n) for n in
842
+ sorted(SECRET_STORE_NAMES, key=len, reverse=True))
843
+ _STORE_SUFFIX_ALT = "|".join(re.escape(s.lstrip(".")) for s in
844
+ sorted(SECRET_STORE_SUFFIXES, key=len,
845
+ reverse=True))
846
+ # A secret-store file: a path ending in a known name/suffix, optionally
847
+ # quoted, in any position (reading it is the whole point of the payload).
848
+ # `process.env` / `config.credentials` are property accesses, not files:
849
+ # require the name to start a word (not follow a `.`) and to be either
850
+ # path-qualified, quoted, or standalone. Backtick/quote/space/`=`/`/` are
851
+ # the positions a file name really appears in.
852
+ SECRET_STORE_RE = re.compile(
853
+ r"(?<![.\w])(?:[\w@~$%{}-]*[\\/])?(?:" + _STORE_NAME_ALT + r")"
854
+ r"(?![\w-]|\.[A-Za-z])"
855
+ r"|(?<![.\w])[\w@~$%{}-]*(?:[\\/][\w.-]+)*\.(?:"
856
+ + _STORE_SUFFIX_ALT + r")(?![\w])")
857
+
858
+
859
+ # A variable *name* that marks its value as secret-bearing. Classification
860
+ # is by name only; the guard never reads the value (design 2.4 item 1).
861
+ SECRET_NAME_RE = re.compile(
862
+ r"\$\{?([A-Za-z_][A-Za-z0-9_]*"
863
+ r"(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|CRED|AUTH|APIKEY)[A-Za-z0-9_]*)\b"
864
+ r"|\$env:([A-Za-z_][A-Za-z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|CRED|AUTH))"
865
+ r"|%([A-Za-z_][A-Za-z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|CRED|AUTH))%",
866
+ re.IGNORECASE)
867
+
868
+
869
+ def _secret_source_reference(text: str) -> Optional[Tuple[str, int, int, str]]:
870
+ """(matched expression, start, end, reason) for a secret source, or None.
871
+
872
+ Value-free by construction: the match is an environment-variable *name*,
873
+ a whole-environment expansion, or a secret-store *file name*. Nothing
874
+ here resolves a value; that invariant is what keeps the guard's own
875
+ output from becoming the leak (design 2.4, "anti-loop rule").
876
+ """
877
+ match = ENV_DUMP_RE.search(text)
878
+ if match:
879
+ # Trim the pipe/whitespace the expansion regex uses to anchor the
880
+ # read position: the fact is the command, not the separator.
881
+ raw = match.group(0).rstrip(" |\t")
882
+ return raw, match.start(), match.start() + len(raw), \
883
+ "environment expansion"
884
+ match = SECRET_STORE_ENV_RE.search(text)
885
+ if match:
886
+ return match.group(0), match.start(), match.end(), \
887
+ "secret store: " + match.group(0)
888
+ match = SECRET_STORE_RE.search(text)
889
+ if match:
890
+ return match.group(0), match.start(), match.end(), \
891
+ "secret store: " + match.group(0)
892
+ match = SECRET_NAME_RE.search(text)
893
+ if match:
894
+ name = next(g for g in match.groups() if g)
895
+ return match.group(0), match.start(), match.end(), \
896
+ "secret-bearing name: " + name
897
+ return None
898
+
899
+
900
+ # ------------------------------------------------- repo-local exemptions
901
+ #
902
+ # Design 5.2: `.agent-guard/exfil-allow.toml` (or `.agent-guardignore`)
903
+ # disables rules and exempts paths. Value exemptions are **by hash only** -
904
+ # a human who needs a specific literal exempted provides `sha256:...`, never
905
+ # the value, because writing the value into a tracked file is itself the bug
906
+ # this feature exists to prevent.
907
+
908
+ DEFAULT_ALLOWFILE = ".agent-guard/exfil-allow.toml"
909
+ DEFAULT_IGNOREFILE = ".agent-guardignore"
910
+
911
+
912
+ @dataclass
913
+ class Exemption:
914
+ """Parsed exemption config. Rule/path globs plus sha256 value hashes."""
915
+
916
+ rules: List[str] = field(default_factory=list)
917
+ paths: List[str] = field(default_factory=list)
918
+ hashes: List[str] = field(default_factory=list)
919
+ source: str = ""
920
+
921
+ @property
922
+ def active(self) -> bool:
923
+ return bool(self.rules or self.paths or self.hashes)
924
+
925
+ def rule_disabled(self, rule_id: str) -> bool:
926
+ return any(fnmatch.fnmatch(rule_id, pat) for pat in self.rules)
927
+
928
+ def path_exempt(self, path: str, root: Optional[str] = None) -> bool:
929
+ if not self.paths or not path:
930
+ return False
931
+ candidates = [path]
932
+ if root:
933
+ try:
934
+ rel = os.path.relpath(os.path.abspath(path),
935
+ os.path.abspath(root))
936
+ candidates.append(rel)
937
+ # A `docs/*.md` pattern means "under the workspace docs
938
+ # directory", regardless of how the caller spelled the path.
939
+ parts = rel.split(os.sep)
940
+ candidates.extend(os.sep.join(parts[i:])
941
+ for i in range(1, len(parts)))
942
+ except ValueError: # different drives (Windows)
943
+ pass
944
+ except ValueError: # different drives (Windows)
945
+ pass
946
+ return any(fnmatch.fnmatch(cand, pat)
947
+ for cand in candidates for pat in self.paths)
948
+
949
+ def value_exempt(self, raw: str) -> bool:
950
+ """Hash comparison only - the guard never stores the value."""
951
+ if not self.hashes or not raw:
952
+ return False
953
+ digest = "sha256:" + hashlib.sha256(
954
+ raw.encode("utf-8", errors="surrogatepass")).hexdigest()
955
+ return digest in self.hashes
956
+
957
+
958
+ def _parse_allowfile(text: str, source: str) -> Exemption:
959
+ """Minimal `key = value` parser - no third-party TOML dependency.
960
+
961
+ Continuation lines are supported: a key whose value starts on its own
962
+ line keeps consuming the indented lines that follow, which is how the
963
+ lists in `.agent-guard/exfil-allow.toml` stay readable. Malformed input
964
+ is ignored rather than fatal - a broken allowfile must never quietly
965
+ turn the guard off.
966
+ """
967
+ exemption = Exemption(source=source)
968
+ section = ""
969
+ key = ""
970
+ values: List[str] = []
971
+
972
+ def flush():
973
+ if not key:
974
+ return
975
+ items = [v.strip().strip("'\"") for v in values if v.strip("'\"")]
976
+ if key in ("rule", "rules", "disable") or section == "rules":
977
+ exemption.rules.extend(items)
978
+ elif key in ("path", "paths", "ignore") or section == "paths":
979
+ exemption.paths.extend(items)
980
+ elif key in ("sha256", "hash", "hashes") or section == "values":
981
+ exemption.hashes.extend(items)
982
+
983
+ def push(raw: str):
984
+ """Split one value chunk on commas/whitespace, ignoring [] and ''."""
985
+ chunk = raw.strip().strip("[]")
986
+ for item in re.split(r"[,\s]+", chunk):
987
+ item = item.strip().strip("'\"")
988
+ if item:
989
+ values.append(item)
990
+
991
+ for raw_line in text.splitlines():
992
+ line = raw_line.split("#", 1)[0].rstrip()
993
+ if not line.strip():
994
+ continue
995
+ if line.lstrip().startswith("["):
996
+ flush()
997
+ key, values = "", []
998
+ section = line.strip().strip("[]").strip().lower()
999
+ continue
1000
+ if "=" in line:
1001
+ flush()
1002
+ values = []
1003
+ key, _, value = line.partition("=")
1004
+ key = key.strip().lower()
1005
+ push(value)
1006
+ continue
1007
+ if key:
1008
+ push(line)
1009
+ flush()
1010
+ return exemption
1011
+
1012
+
1013
+ def load_exemption(workspace: Optional[str]) -> Exemption:
1014
+ """Read the repo-local exemption file; absent means "no exemptions"."""
1015
+ if not workspace:
1016
+ return Exemption()
1017
+ for relative in (DEFAULT_ALLOWFILE, DEFAULT_IGNOREFILE):
1018
+ path = os.path.join(workspace, relative)
1019
+ try:
1020
+ with open(path, "r", encoding="utf-8") as fh:
1021
+ return _parse_allowfile(fh.read(), relative)
1022
+ except (OSError, UnicodeDecodeError):
1023
+ continue
1024
+ return Exemption()
1025
+
1026
+
1027
+ def apply_exemption(spans: List[SpanSpec], exemption: Exemption,
1028
+ path: Optional[str] = None,
1029
+ root: Optional[str] = None) -> List[SpanSpec]:
1030
+ """Drop spans a reviewed exemption covers. Never restores a value."""
1031
+ if not exemption.active:
1032
+ return spans
1033
+ if exemption.path_exempt(path, root):
1034
+ return []
1035
+ return [s for s in spans
1036
+ if not exemption.rule_disabled(s.rule_id)
1037
+ and not exemption.value_exempt(s.raw)]
1038
+
1039
+
1040
+ def scan_text(text: str, channel: str = "",
1041
+ workspace: Optional[str] = None,
1042
+ max_bytes: Optional[int] = None,
1043
+ path: Optional[str] = None,
1044
+ exemption: Optional[Exemption] = None) -> ScanResult:
1045
+ """Detect every secret/path span in `text` (facts only).
1046
+
1047
+ Never returns a partial result as clean: an over-cap payload, a
1048
+ non-ASCII payload or an internal scanner error is reported via
1049
+ `scanned=False`, which `policy.decide_spans` turns into
1050
+ BLOCK_OUTPUT_UNSCANNABLE (design 6.3, fail closed).
1051
+ """
1052
+ limit = max_bytes if max_bytes is not None else max_scan_bytes()
1053
+ size = len(text.encode("utf-8", errors="replace"))
1054
+ result = ScanResult(size_bytes=size)
1055
+ if size > limit:
1056
+ result.scanned = False
1057
+ result.truncated = True
1058
+ result.error = f"payload exceeds scan cap ({size} > {limit} bytes)"
1059
+ return result
1060
+ # Note on non-ASCII payloads: they are scanned normally. The vendor
1061
+ # patterns are ASCII-anchored and `re` matches on characters, so a
1062
+ # non-ASCII byte cannot smuggle a match past them, and the placeholder
1063
+ # allowlist only ever needs to see the (ASCII) token it was handed.
1064
+ # Refusing every document that contains an em-dash or CJK prose would
1065
+ # make the guard unusable without buying any detection.
1066
+
1067
+ workspace = workspace or os.environ.get("AGENT_GUARD_WORKSPACE")
1068
+ try:
1069
+ spans = detect_secrets(text, channel=channel)
1070
+ spans.extend(detect_paths(text, workspace=workspace, channel=channel))
1071
+ except Exception as exc: # pragma: no cover - defensive
1072
+ result.scanned = False
1073
+ result.error = f"scanner error: {type(exc).__name__}"
1074
+ return result
1075
+
1076
+ spans = merge_spans(spans)
1077
+ source = _secret_source_reference(text)
1078
+ if source is not None:
1079
+ # The dump makes the whole payload unattributable. It gets a span of
1080
+ # its own - not just a flag on an existing one - because the
1081
+ # dangerous case (`echo "$KEY"`) frequently matches no pattern at
1082
+ # all, and "no match" must not be reported as "clean" when the
1083
+ # guard never saw the content. The span records the *reference
1084
+ # expression*, which is value-free by construction (design 2.4).
1085
+ raw, start, end, reason = source
1086
+ spans.append(SpanSpec(
1087
+ raw=raw, start=start, end=end, rule_id=RULE_SECRET_SOURCE,
1088
+ family=FAMILY_SECRET, confidence=CONFIDENCE_DETERMINISTIC,
1089
+ context="env-var", channel=channel, source_dump=True,
1090
+ notes=["value-free reference detection", reason]))
1091
+ if exemption is None:
1092
+ exemption = load_exemption(workspace)
1093
+ result.spans = apply_exemption(merge_spans(spans), exemption, path,
1094
+ workspace)
1095
+ result.exempted = len(merge_spans(spans)) - len(result.spans)
1096
+ return result