@mokuyoaxis/agent-guard 0.2.3-rc2 → 0.2.4

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 (81) hide show
  1. package/README.md +127 -83
  2. package/README.zh-CN.md +106 -74
  3. package/adapters/INTEGRATION.md +4 -4
  4. package/adapters/claude/README.md +3 -3
  5. package/adapters/claude/harness/README.md +1 -1
  6. package/adapters/codex/harness/README.md +2 -2
  7. package/adapters/dsh/README.md +24 -15
  8. package/adapters/dsh/harness/README.md +75 -19
  9. package/adapters/dsh/harness/bootstrap.patch.yml +5 -0
  10. package/adapters/dsh/harness/bootstrap_init.mjs +48 -0
  11. package/adapters/dsh/harness/guard_lab.py +194 -32
  12. package/adapters/dsh/harness/native_session.py +41 -20
  13. package/adapters/dsh/harness/profiles.py +74 -22
  14. package/adapters/dsh/lib/index.js +1 -1
  15. package/adapters/kimi-code/README.md +15 -14
  16. package/adapters/kimi-code/harness/README.md +3 -3
  17. package/adapters/kimi-code/harness/guard_lab.py +1 -1
  18. package/core/__init__.py +1 -1
  19. package/core/classifier.py +41 -16
  20. package/core/lab.py +24 -1
  21. package/core/policy.py +11 -4
  22. package/core/recovery.py +256 -23
  23. package/core/redaction.py +157 -55
  24. package/core/trash_index.py +193 -0
  25. package/docs/README.md +104 -0
  26. package/docs/{architecture.md → design/architecture.md} +31 -6
  27. package/docs/{compatibility.md → design/compatibility.md} +54 -4
  28. package/docs/{threat-model.md → design/threat-model.md} +4 -4
  29. package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +9 -9
  30. package/docs/guides/trash-index.md +106 -0
  31. package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +8 -9
  32. package/docs/{friction.md → history/friction.md} +107 -4
  33. package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +23 -22
  34. package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +6 -4
  35. package/docs/{secret-guard-design.md → history/secret-guard-design.md} +19 -15
  36. package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
  37. package/docs/{guard-lab.md → lab/guard-lab.md} +18 -11
  38. package/docs/lab/tasks/guard-lab-read-trial-task.md +7 -0
  39. package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +5 -5
  40. package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +7 -7
  41. package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
  42. package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +9 -10
  43. package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +4 -2
  44. package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
  45. package/docs/releases/release-notes-0.2.3.md +84 -0
  46. package/docs/releases/release-notes-0.2.4.md +89 -0
  47. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  48. package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +10 -11
  49. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  50. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  51. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  52. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  53. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  54. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  55. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  56. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +22 -23
  57. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  58. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +79 -1
  59. package/docs/reports/test-report-workbuddy-windows-core.md +53 -0
  60. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +11 -11
  61. package/package.json +1 -1
  62. package/skills/delete-guard/SKILL.md +40 -3
  63. package/skills/delete-guard/references/policy.md +18 -5
  64. package/skills/delete-guard/scripts/check.py +19 -0
  65. package/skills/delete-guard/scripts/restore.py +18 -6
  66. package/skills/delete-guard/scripts/status.py +52 -0
  67. package/skills/exfil-guard/SKILL.md +37 -7
  68. package/skills/exfil-guard/references/channels.md +1 -1
  69. package/skills/exfil-guard/references/rules.md +84 -16
  70. package/skills/exfil-guard/scripts/_payload.py +99 -0
  71. package/skills/exfil-guard/scripts/check_span.py +14 -81
  72. package/skills/exfil-guard/scripts/sanitize.py +113 -34
  73. package/docs/release-notes-0.2.3.md +0 -45
  74. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  75. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  76. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  77. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  78. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  79. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  80. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  81. /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
package/core/redaction.py CHANGED
@@ -34,6 +34,7 @@ import platform
34
34
  import re
35
35
  from dataclasses import dataclass, field
36
36
  from typing import Any, Dict, Iterable, List, Optional, Sequence, Set, Tuple
37
+ from urllib.parse import unquote
37
38
 
38
39
  # ------------------------------------------------------------- span types
39
40
 
@@ -50,8 +51,10 @@ RULE_AWS_ACCESS_KEY_ID = "secret/aws-access-key-id"
50
51
  RULE_GITLAB_TOKEN = "secret/gitlab-token"
51
52
  RULE_SLACK_TOKEN = "secret/slack-token"
52
53
  RULE_STRIPE_KEY = "secret/stripe-key"
54
+ RULE_PYPI_TOKEN = "secret/pypi-token"
53
55
  RULE_JWT = "secret/jwt"
54
56
  RULE_PRIVATE_KEY_BLOCK = "secret/private-key-block"
57
+ RULE_CONNECTION_PASSWORD = "secret/connection-password"
55
58
  # A value-free reference to a secret source (env var name / secret store).
56
59
  RULE_SECRET_SOURCE = "secret/source-reference"
57
60
 
@@ -131,12 +134,27 @@ PLACEHOLDER_WORDS = frozenset({
131
134
  "dummy", "example", "sample", "fake", "test", "testing", "todo",
132
135
  "placeholder", "redacted", "none", "null", "notset", "unset",
133
136
  "xxxx", "xxxxxxxx", "yourtoken", "mysupersecret", "hunter2",
137
+ "dummy_value", "dummy_key", "dummy_token", "example_secret",
138
+ "example_key", "example_token", "sample_key", "sample_token",
139
+ "fake_key", "fake_token", "test_key", "test_token",
134
140
  })
141
+ _PLACEHOLDER_NORMALIZED_WORDS = frozenset(word.replace("-", "_") for word in PLACEHOLDER_WORDS)
142
+ # Public AWS documentation examples, preserved as exact values rather than
143
+ # granting amnesty to every random credential ending in "example".
144
+ _PUBLIC_EXAMPLE_VALUES = frozenset({"AKIA" + "IOSFODNN7EXAMPLE", "ASIA" + "IOSFODNN7EXAMPLE"})
135
145
  # Marker shapes: <REDACTED>, [REDACTED], ***, _<<REDACTED>>_ ...
136
146
  _PLACEHOLDER_SHAPE_RE = re.compile(
137
147
  r"^[\W_]*(?:redacted|removed|hidden|scrubbed|elided|omitted)[\W_]*$",
138
148
  re.IGNORECASE)
139
149
  _REDACTED_MARKER = "<REDACTED>"
150
+ # Only remove a public, reviewed prefix before checking a whole placeholder
151
+ # body. Words embedded in random credential bytes are never exemptions.
152
+ _PLACEHOLDER_VENDOR_PREFIX_RE = re.compile(
153
+ r"^(?:sk-proj-|sk-ant-(?:api03-)?|sk-live-|sk-|(?:sk|rk)_live_|"
154
+ r"(?:ghp|gho|ghu|ghs|ghr)_|github_pat_|glpat-|xox[baprs]-|pypi-|"
155
+ r"AKIA|ASIA)")
156
+ _PLACEHOLDER_TEMPLATE_RE = re.compile(
157
+ r"(?:<[A-Za-z_][A-Za-z0-9_]*>|\$\{[A-Za-z_][A-Za-z0-9_]*\})\Z")
140
158
 
141
159
  # A token is only a placeholder if its *alphabet* is trivial (one symbol,
142
160
  # '*'/'x'/'.' runs, sequences like abcdef) or if it is a known word. The
@@ -174,43 +192,25 @@ def is_placeholder(token: str) -> bool:
174
192
 
175
193
 
176
194
  def _is_placeholder(token: str) -> bool:
177
- value = token.strip().strip("'\"`()[]<>").strip()
195
+ value = token.strip().strip("'\"`()").strip()
178
196
  if not value:
179
197
  return False
180
- if value == _REDACTED_MARKER:
181
- return True # idempotence (design 2.5)
182
- if _PLACEHOLDER_SHAPE_RE.match(value):
198
+ if value in _PUBLIC_EXAMPLE_VALUES:
183
199
  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
+ value = _PLACEHOLDER_VENDOR_PREFIX_RE.sub("", value, count=1)
201
+ if not value:
202
+ return False
203
+ if _PLACEHOLDER_SHAPE_RE.fullmatch(value) or _PLACEHOLDER_TEMPLATE_RE.fullmatch(value):
204
+ return True # whole marker/template only
205
+ normalized = value.lower().replace("-", "_")
206
+ if normalized in _PLACEHOLDER_NORMALIZED_WORDS:
207
+ return True # finite whole-word examples
200
208
  return _is_trivial_alphabet(value)
201
209
 
202
210
 
203
211
  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"))
212
+ """Compatibility predicate with the same exact whole-value contract."""
213
+ return is_placeholder(token)
214
214
 
215
215
  # -------------------------------------------------------- T1 vendor patterns
216
216
 
@@ -218,19 +218,86 @@ def _looks_placeholderish(token: str) -> bool:
218
218
  # distinct enough that an anchored prefix + shape gives near-zero false
219
219
  # positives; where the format allows, a validator adds real structure
220
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,}")
221
+ # ASCII identifier boundaries allow adjacent CJK prose, while still refusing
222
+ # substrings of English identifiers. Unicode \b conflates those two cases.
223
+ _TOKEN_START = r"(?<![A-Za-z0-9_])"
224
+ _TOKEN_END = r"(?![A-Za-z0-9_])"
225
+ _OPENAI_RE = re.compile(_TOKEN_START + r"sk-(?:proj|ant|live)?-?([A-Za-z0-9_\-]{20,})")
226
+ _GITHUB_RE = re.compile(_TOKEN_START + r"(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}" + _TOKEN_END
227
+ + r"|" + _TOKEN_START + r"github_pat_[A-Za-z0-9_]{22,255}" + _TOKEN_END)
228
+ # The vendor's ghs_APPID_JWT wrapper; app ID is an opaque ASCII field.
229
+ # No fixed total length, business claims or signature authentication.
230
+ _GITHUB_INSTALLATION_RE = re.compile(
231
+ _TOKEN_START + r"ghs_[A-Za-z0-9-]+_(?P<header>[A-Za-z0-9_-]{4,})"
232
+ r"\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}"
233
+ r"(?![A-Za-z0-9_-]|\.[A-Za-z0-9_-])")
234
+ # IAM group/user/role/policy IDs have separate public resource prefixes.
235
+ # They are not access-key IDs; other credential contexts still apply.
236
+ _AWS_KEY_ID_RE = re.compile(_TOKEN_START + r"(?:AKIA|ASIA)[0-9A-Z]{16}" + _TOKEN_END)
237
+ _GITLAB_RE = re.compile(_TOKEN_START + r"glpat-[A-Za-z0-9_\-]{20,}")
238
+ _SLACK_RE = re.compile(_TOKEN_START + r"xox[baprs]-[A-Za-z0-9\-]{10,}")
239
+ _STRIPE_RE = re.compile(_TOKEN_START + r"(?:sk|rk)_live_[A-Za-z0-9]{16,}")
240
+ # PyPI's documented scanner format allows arbitrary Macaroon caveat length.
241
+ # Capture the entire base64url body, rather than an 85-character prefix.
242
+ _PYPI_RE = re.compile(_TOKEN_START + r"pypi-[A-Za-z0-9_-]{85,}")
228
243
  _JWT_RE = re.compile(
229
- r"\beyJ[A-Za-z0-9_\-]{4,}\.[A-Za-z0-9_\-]{4,}\.[A-Za-z0-9_\-]{4,}")
244
+ _TOKEN_START + r"eyJ[A-Za-z0-9_\-]{4,}\.[A-Za-z0-9_\-]{4,}\.[A-Za-z0-9_\-]{4,}")
230
245
  _PRIVATE_KEY_RE = re.compile(
231
246
  r"-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----.*?"
232
247
  r"-----END (?:[A-Z0-9]+ )*PRIVATE KEY-----",
233
248
  re.DOTALL)
249
+ # URI userinfo is an explicit credential context (RFC 3986 section 3.2.1).
250
+ # Work on original coordinates instead of urlsplit: URL parsers normalize
251
+ # input and cannot provide exact offsets for a serialized JSON payload.
252
+ # A JSON-escaped slash is accepted only at the scheme separator. Other
253
+ # encoded delimiters stay in the password's original, replaceable span.
254
+ _CONNECTION_PREFIX_RE = re.compile(
255
+ r"(?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,63}:(?:/|\\/){2}")
256
+ _CONNECTION_AUTHORITY_RE = re.compile(r"[^\s/?#\"'`]+")
257
+ _CONNECTION_TEMPLATE_RE = re.compile(
258
+ r"(?:<[^<>@]+>|\$\{[^{}@]+\}|%[A-Za-z_][A-Za-z0-9_]*%)\Z")
259
+
260
+
261
+ def _connection_passwords(text: str, channel: str) -> List[SpanSpec]:
262
+ """Detect nonempty URI passwords; preserve account and host information.
263
+
264
+ Plain weak passwords are still passwords. Unlike vendor test tokens,
265
+ short/repeated literals and words such as 'test' are not exempt here.
266
+ Only whole template expressions and redaction markers are exempt.
267
+ Raw '/', '?', '#' and quoting delimit authority; they must be encoded
268
+ within a URI password. This is not a general DSN or obfuscation parser.
269
+ """
270
+ spans = []
271
+ for prefix in _CONNECTION_PREFIX_RE.finditer(text):
272
+ match = _CONNECTION_AUTHORITY_RE.match(text, prefix.end())
273
+ if match is None:
274
+ continue
275
+ authority = match.group(0)
276
+ at = authority.rfind("@")
277
+ colon = authority.find(":")
278
+ if colon < 0 or at <= colon + 1 or at == len(authority) - 1:
279
+ continue
280
+ # Last @ also withholds the complete password in a common malformed
281
+ # spelling containing a literal @; never leave a password suffix.
282
+ start, end = match.start() + colon + 1, match.start() + at
283
+ raw = text[start:end]
284
+ # Decode only to recognize an explicit template; arbitrary byte
285
+ # passwords need not be UTF-8 and are still redacted as raw spans.
286
+ decoded = unquote(raw, errors="replace")
287
+ if (_CONNECTION_TEMPLATE_RE.fullmatch(raw) or
288
+ _CONNECTION_TEMPLATE_RE.fullmatch(decoded) or
289
+ _PLACEHOLDER_SHAPE_RE.fullmatch(decoded) or
290
+ re.fullmatch(r"\*{3,}", decoded)):
291
+ continue
292
+ spans.append(SpanSpec(
293
+ raw=raw, start=start, end=end,
294
+ rule_id=RULE_CONNECTION_PASSWORD, family=FAMILY_SECRET,
295
+ confidence=CONFIDENCE_DETERMINISTIC,
296
+ context="uri-userinfo", channel=channel,
297
+ notes=["nonempty password in URI userinfo; account and host retained"]))
298
+ return spans
299
+
300
+
234
301
  # Secret-store file names: a *path* fact (design 2.4 item 3). Reading these
235
302
  # on an outbound channel is refused rather than sanitized, because the
236
303
  # guard cannot see the content it would be rewriting.
@@ -267,7 +334,7 @@ ENV_DUMP_RE = re.compile(
267
334
 
268
335
 
269
336
  def _b64url_json_has_alg(segment: str) -> bool:
270
- """Structural JWT check: the header segment must decode to JSON+`alg`."""
337
+ """Structural JWS check: JSON object with a nonempty ASCII `alg` string."""
271
338
  if len(segment) % 4 == 1:
272
339
  return False
273
340
  padded = segment + "=" * (-len(segment) % 4)
@@ -279,7 +346,12 @@ def _b64url_json_has_alg(segment: str) -> bool:
279
346
  header = json.loads(decoded.decode("utf-8"))
280
347
  except (ValueError, UnicodeDecodeError):
281
348
  return False
282
- return isinstance(header, dict) and "alg" in header
349
+ if not isinstance(header, dict):
350
+ return False
351
+ alg = header.get("alg")
352
+ # RFC 7515 4.1.1 declares ASCII StringOrURI. Do not infer authentication,
353
+ # validate business claims or restrict the caller to a known enum.
354
+ return isinstance(alg, str) and bool(alg) and alg.isascii()
283
355
 
284
356
 
285
357
  def _note_context(text: str, index: int) -> str:
@@ -301,7 +373,7 @@ def detect_secrets(text: str, channel: str = "") -> List[SpanSpec]:
301
373
 
302
374
  def add(match: "re.Match[str]", rule_id: str, notes: Iterable[str] = ()):
303
375
  raw = match.group(0)
304
- if is_placeholder(raw) or _looks_placeholderish(raw):
376
+ if is_placeholder(raw):
305
377
  return
306
378
  spans.append(SpanSpec(
307
379
  raw=raw, start=match.start(), end=match.end(), rule_id=rule_id,
@@ -316,6 +388,9 @@ def detect_secrets(text: str, channel: str = "") -> List[SpanSpec]:
316
388
  add(match, RULE_OPENAI_KEY, ["vendor prefix + length + charset"])
317
389
  for match in _GITHUB_RE.finditer(text):
318
390
  add(match, RULE_GITHUB_TOKEN, ["fixed-format vendor prefix"])
391
+ for match in _GITHUB_INSTALLATION_RE.finditer(text):
392
+ if len(match.group(0)) >= 40 and _b64url_json_has_alg(match.group("header")):
393
+ add(match, RULE_GITHUB_TOKEN, ["vendor installation wrapper + structural JWT header"])
319
394
  for match in _AWS_KEY_ID_RE.finditer(text):
320
395
  add(match, RULE_AWS_ACCESS_KEY_ID, ["reserved vendor prefix"])
321
396
  for match in _GITLAB_RE.finditer(text):
@@ -324,11 +399,14 @@ def detect_secrets(text: str, channel: str = "") -> List[SpanSpec]:
324
399
  add(match, RULE_SLACK_TOKEN, ["vendor prefix"])
325
400
  for match in _STRIPE_RE.finditer(text):
326
401
  add(match, RULE_STRIPE_KEY, ["prefix + live mode (test keys exempt)"])
402
+ for match in _PYPI_RE.finditer(text):
403
+ add(match, RULE_PYPI_TOKEN, ["vendor prefix + documented base64url minimum"])
327
404
  for match in _JWT_RE.finditer(text):
328
405
  header = match.group(0).split(".", 1)[0]
329
406
  if not _b64url_json_has_alg(header):
330
407
  continue
331
408
  add(match, RULE_JWT, ["header segment decodes to JSON containing alg"])
409
+ spans.extend(_connection_passwords(text, channel))
332
410
  return merge_spans(spans)
333
411
 
334
412
 
@@ -859,11 +937,31 @@ SECRET_STORE_RE = re.compile(
859
937
  # A variable *name* that marks its value as secret-bearing. Classification
860
938
  # is by name only; the guard never reads the value (design 2.4 item 1).
861
939
  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)
940
+ r"\$env:([A-Za-z_][A-Za-z0-9_]*)"
941
+ r"|\$\{([A-Za-z_][A-Za-z0-9_]*)(?:\}|(?=[:/#%+?=\-]))"
942
+ r"|\$([A-Za-z_][A-Za-z0-9_]*)"
943
+ r"|%([A-Za-z_][A-Za-z0-9_]*)%", re.IGNORECASE)
944
+ _SECRET_NAME_COMPONENTS = frozenset({
945
+ "KEY", "TOKEN", "SECRET", "PASSWORD", "PASSWD", "CRED", "AUTH", "APIKEY",
946
+ "CREDENTIAL", "CREDENTIALS",
947
+ })
948
+ _SECRET_NAME_METADATA = frozenset({"COUNT", "LENGTH", "ENABLED"})
949
+
950
+
951
+ def _secret_bearing_name(name: str, *, explicit_environment: bool = False) -> bool:
952
+ # Preserve acronym/camelCase components: ApiKey, APIKey, accessToken.
953
+ separated = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)
954
+ separated = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", separated)
955
+ components = [part.upper() for part in separated.split("_") if part]
956
+ # A lone lower/title-case `key` is also a common dictionary/schema key
957
+ # in template expressions. Do not infer a credential from that word
958
+ # alone. KEY, qualified apiKey and explicit env syntax stay protected.
959
+ # This is a name ambiguity, not a JavaScript/file-extension exemption.
960
+ if (components == ["KEY"] and name.strip("_") != "KEY"
961
+ and not explicit_environment):
962
+ return False
963
+ return (bool(components) and components[-1] not in _SECRET_NAME_METADATA
964
+ and any(part in _SECRET_NAME_COMPONENTS for part in components))
867
965
 
868
966
 
869
967
  def _secret_source_reference(text: str) -> Optional[Tuple[str, int, int, str]]:
@@ -889,11 +987,12 @@ def _secret_source_reference(text: str) -> Optional[Tuple[str, int, int, str]]:
889
987
  if match:
890
988
  return match.group(0), match.start(), match.end(), \
891
989
  "secret store: " + match.group(0)
892
- match = SECRET_NAME_RE.search(text)
893
- if match:
990
+ for match in SECRET_NAME_RE.finditer(text):
894
991
  name = next(g for g in match.groups() if g)
895
- return match.group(0), match.start(), match.end(), \
896
- "secret-bearing name: " + name
992
+ explicit_environment = match.group(1) is not None or match.group(4) is not None
993
+ if _secret_bearing_name(name, explicit_environment=explicit_environment):
994
+ return match.group(0), match.start(), match.end(), \
995
+ "secret-bearing name: " + name
897
996
  return None
898
997
 
899
998
 
@@ -1044,8 +1143,8 @@ def scan_text(text: str, channel: str = "",
1044
1143
  exemption: Optional[Exemption] = None) -> ScanResult:
1045
1144
  """Detect every secret/path span in `text` (facts only).
1046
1145
 
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
1146
+ Never returns a partial result as clean: an over-cap payload or an
1147
+ internal scanner error is reported via
1049
1148
  `scanned=False`, which `policy.decide_spans` turns into
1050
1149
  BLOCK_OUTPUT_UNSCANNABLE (design 6.3, fail closed).
1051
1150
  """
@@ -1090,7 +1189,10 @@ def scan_text(text: str, channel: str = "",
1090
1189
  notes=["value-free reference detection", reason]))
1091
1190
  if exemption is None:
1092
1191
  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)
1192
+ # A source-reference fact must survive even inside a redaction span:
1193
+ # masking a literal URI password is not permission to resolve an env
1194
+ # secret embedded there. The aggregate BLOCK prevents plan application.
1195
+ spans.sort(key=lambda span: (span.start, -span.length))
1196
+ result.spans = apply_exemption(spans, exemption, path, workspace)
1197
+ result.exempted = len(spans) - len(result.spans)
1096
1198
  return result
@@ -0,0 +1,193 @@
1
+ """Read-only quarantine locations for CLI, agent and future UI callers.
2
+
3
+ This queries directory layout, not recovery contents or purge authority. No
4
+ RecoveryEngine is constructed, no Git command runs, and no layout is created.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import errno
9
+ import os
10
+ import stat
11
+ from typing import Any, Dict, Iterable, List
12
+
13
+ from . import AUDIT_NAME, MANIFEST_NAME, STATE_NAME, TRASH_DIRNAME
14
+
15
+
16
+ SCHEMA_VERSION = 1
17
+ DEFAULT_MAX_DEPTH = 3
18
+ DEFAULT_MAX_ENTRIES = 10_000
19
+ EXCLUDED_DIRS = (".git", "node_modules", ".internal", "__pycache__")
20
+
21
+
22
+ def _paths(values: Iterable[str]) -> List[str]:
23
+ if isinstance(values, (str, bytes)):
24
+ raise ValueError("paths must be a sequence of text paths")
25
+ try:
26
+ values = iter(values)
27
+ except TypeError:
28
+ raise ValueError("paths must be a sequence of text paths") from None
29
+ result = []
30
+ for value in values:
31
+ try:
32
+ value = os.fspath(value)
33
+ except TypeError:
34
+ raise ValueError("paths must contain text paths") from None
35
+ if not isinstance(value, str) or not value or "\0" in value:
36
+ raise ValueError("paths must contain nonempty text paths")
37
+ normalized = os.path.normpath(os.path.abspath(os.path.expanduser(value)))
38
+ if normalized not in result:
39
+ result.append(normalized)
40
+ return result
41
+
42
+
43
+ def _error_code(exc: OSError) -> str:
44
+ if exc.errno in (errno.EACCES, errno.EPERM):
45
+ return "PERMISSION_DENIED"
46
+ if exc.errno == errno.ENOENT:
47
+ return "NOT_FOUND"
48
+ if exc.errno == errno.ENOTDIR:
49
+ return "NOT_DIRECTORY"
50
+ return "IO_ERROR"
51
+
52
+
53
+ def list_trash_locations(
54
+ roots: Iterable[str] = (), *, trash_paths: Iterable[str] = (),
55
+ max_depth: int = DEFAULT_MAX_DEPTH,
56
+ max_entries: int = DEFAULT_MAX_ENTRIES,
57
+ ) -> Dict[str, Any]:
58
+ """Return schema v1 location candidates within explicit bounded roots.
59
+
60
+ Depth counts directories below a root: depth 0 still checks that root's
61
+ .agent-trash. A recognized bucket is never traversed. Ordinary child
62
+ directory links are skipped; explicitly supplied roots/buckets may use
63
+ aliases. Expected marker names are lstat'ed, never opened.
64
+
65
+ count includes unconfirmed/unreadable candidates; identified_count only
66
+ counts existing metadata layouts. Neither identifies ownership, content
67
+ integrity or permission to restore/purge. complete covers the declared
68
+ depth/exclusions and successful reads, not the whole host or an atomic
69
+ filesystem snapshot. Errors retain partial results.
70
+ """
71
+ if type(max_depth) is not int or max_depth < 0:
72
+ raise ValueError("max_depth must be a nonnegative integer")
73
+ if type(max_entries) is not int or max_entries < 1:
74
+ raise ValueError("max_entries must be a positive integer")
75
+ roots, trash_paths = _paths(roots), _paths(trash_paths)
76
+ if not roots and not trash_paths:
77
+ raise ValueError("provide roots or trash_paths")
78
+
79
+ buckets: Dict[str, Dict[str, Any]] = {}
80
+ errors: List[Dict[str, str]] = []
81
+ visited: Dict[str, int] = {}
82
+ examined = 0
83
+ exhausted = False
84
+
85
+ def error(path: str, code: str) -> None:
86
+ record = {"path": path, "code": code}
87
+ if record not in errors:
88
+ errors.append(record)
89
+
90
+ def charge(path: str) -> bool:
91
+ nonlocal examined, exhausted
92
+ if examined >= max_entries:
93
+ if not exhausted:
94
+ error(path, "ENTRY_LIMIT_REACHED")
95
+ exhausted = True
96
+ return False
97
+ examined += 1
98
+ return True
99
+
100
+ def bucket(path: str, source: str) -> None:
101
+ try:
102
+ if not stat.S_ISDIR(os.stat(path).st_mode):
103
+ error(path, "NOT_DIRECTORY")
104
+ return
105
+ resolved = os.path.normpath(os.path.realpath(path))
106
+ except OSError as exc:
107
+ error(path, _error_code(exc))
108
+ return
109
+ key = os.path.normcase(resolved)
110
+ if key in buckets:
111
+ row = buckets[key]
112
+ if path not in row["locations"]:
113
+ row["locations"].append(path)
114
+ if source not in row["sources"]:
115
+ row["sources"].append(source)
116
+ return
117
+
118
+ present = unreadable = False
119
+ for name in (MANIFEST_NAME, AUDIT_NAME, STATE_NAME, "sessions"):
120
+ try:
121
+ mode = os.lstat(os.path.join(path, name)).st_mode
122
+ present |= (stat.S_ISDIR(mode) if name == "sessions"
123
+ else stat.S_ISREG(mode))
124
+ except FileNotFoundError:
125
+ continue
126
+ except OSError as exc:
127
+ unreadable = True
128
+ error(path, _error_code(exc))
129
+ status = ("unreadable" if unreadable else
130
+ "metadata_present" if present else "unconfirmed")
131
+ buckets[key] = {
132
+ "trash_root": path, "resolved_trash_root": resolved,
133
+ "directory": os.path.dirname(path), "locations": [path],
134
+ "sources": [source], "status": status,
135
+ }
136
+
137
+ for path in trash_paths:
138
+ if not charge(path):
139
+ break
140
+ bucket(path, "declared")
141
+
142
+ for root in roots:
143
+ if exhausted:
144
+ break
145
+ stack = [(root, 0)]
146
+ while stack and not exhausted:
147
+ directory, depth = stack.pop()
148
+ if not charge(directory):
149
+ break
150
+ if os.path.basename(directory) == TRASH_DIRNAME:
151
+ bucket(directory, "discovered")
152
+ continue
153
+ try:
154
+ physical = os.path.normcase(os.path.realpath(directory))
155
+ except OSError as exc:
156
+ error(directory, _error_code(exc))
157
+ continue
158
+ remaining = max_depth - depth
159
+ if visited.get(physical, -1) >= remaining:
160
+ continue
161
+ visited[physical] = remaining
162
+ children = []
163
+ try:
164
+ with os.scandir(directory) as entries:
165
+ for entry in entries:
166
+ if not charge(entry.path):
167
+ break
168
+ if entry.name == TRASH_DIRNAME:
169
+ bucket(entry.path, "discovered")
170
+ elif (depth < max_depth and entry.name not in EXCLUDED_DIRS
171
+ and entry.is_dir(follow_symlinks=False)):
172
+ children.append(entry.path)
173
+ except OSError as exc:
174
+ error(directory, _error_code(exc))
175
+ # Reverse push gives stable lexical order among directory children.
176
+ stack.extend((path, depth + 1) for path in sorted(children, reverse=True))
177
+
178
+ rows = sorted(buckets.values(), key=lambda row: row["resolved_trash_root"])
179
+ for row in rows:
180
+ row["locations"].sort()
181
+ row["sources"].sort()
182
+ row["trash_root"] = row["locations"][0]
183
+ row["directory"] = os.path.dirname(row["trash_root"])
184
+ return {
185
+ "schema_version": SCHEMA_VERSION,
186
+ "roots": roots, "trash_paths": trash_paths,
187
+ "max_depth": max_depth, "max_entries": max_entries,
188
+ "excluded_dirs": list(EXCLUDED_DIRS), "examined": examined,
189
+ "complete": not errors,
190
+ "count": len(rows),
191
+ "identified_count": sum(row["status"] == "metadata_present" for row in rows),
192
+ "entries": rows, "errors": errors,
193
+ }
package/docs/README.md ADDED
@@ -0,0 +1,104 @@
1
+ # Documentation / 文档导航
2
+
3
+ Start with the [harness capability matrix](guides/harness-capabilities.md) for
4
+ current coverage, the [architecture](design/architecture.md) for the shared
5
+ Core, and the [Lab guide](lab/guard-lab.md) for experiment semantics.
6
+
7
+ 先看当前能力矩阵、架构和 Lab 指南。测试报告按所测版本与配置保留;发布记录、
8
+ 历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
9
+
10
+ | Category / 分类 | Contents / 内容 |
11
+ |---|---|
12
+ | [Guides](#guides) / 使用指南 | 宿主接入证据、漂移检查、维护者发布指南 |
13
+ | [Design](#design) / 架构与契约 | 当前架构、威胁模型与兼容契约 |
14
+ | [Lab](#lab) / 实验与候选素材 | Lab 流程、任务模板、外部攻击案例 |
15
+ | [Reports](#reports) / 测试报告 | 按宿主、版本和观察范围记录的证据 |
16
+ | [Releases](#releases) / 发布记录 | 正式版与预览版各自的范围 |
17
+ | [History](#history) / 历史设计与经验 | 早期设计、实现教训和事故探索 |
18
+
19
+ ## Guides
20
+
21
+ | Document / 文档 | Scope / 范围 |
22
+ |---|---|
23
+ | [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
24
+ | [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
25
+ | [Trash locations](guides/trash-index.md) | 0.2.4 的只读位置查询、Agent/前端共享 JSON 契约 |
26
+ | [Publishing from ephemeral environments](guides/publishing-from-ephemeral-environments.md) | 临时环境中的 GitHub 发布操作参考 |
27
+
28
+ Adapter setup remains in [adapters/](../adapters/INTEGRATION.md). Skill contracts
29
+ remain in [skills/](../skills/delete-guard/SKILL.md).
30
+
31
+ ## Design
32
+
33
+ | Document / 文档 | Scope / 范围 |
34
+ |---|---|
35
+ | [Architecture](design/architecture.md) | Core、Decision Protocol、适配器与数据流 |
36
+ | [Threat model](design/threat-model.md) | 资产、可信假设与已知防护边界 |
37
+ | [Compatibility](design/compatibility.md) | 适配器契约、接口兼容与版本约定 |
38
+
39
+ ## Lab
40
+
41
+ | Document / 文档 | Scope / 范围 |
42
+ |---|---|
43
+ | [Guard Lab guide](lab/guard-lab.md) | 操作流程、信道、L0/L1/L2 语义与限制 |
44
+ | [Clean task](lab/tasks/guard-lab-clean-task.md) | 干净对照任务模板 |
45
+ | [Injection trial task](lab/tasks/guard-lab-trial-task.md) | 提示注入试次任务模板 |
46
+ | [Native-read trial task](lab/tasks/guard-lab-read-trial-task.md) | 原生读取脱敏任务模板 |
47
+ | [fake-ai-api reference](lab/cases/injection-case-fake-ai-api.md) | 外部攻击端候选素材;尚未作为 Lab 样本验证 |
48
+
49
+ Task templates and external case references are separate from completed test
50
+ reports. A scripted provider checks host behavior; a real-model injection
51
+ trial needs an effective unguarded baseline before a matched comparison.
52
+
53
+ ## Reports
54
+
55
+ Each report preserves its original version, configuration, result and limits.
56
+ Use the [capability matrix](guides/harness-capabilities.md) to interpret current
57
+ coverage rather than treating every historical result as current acceptance.
58
+
59
+ | Document / 文档 | Scope / 范围 |
60
+ |---|---|
61
+ | [0.2.3 contract review](reports/test-report-release-readiness-0.2.3.md) | 发布前契约复核与 DSH 原生验收 |
62
+ | [0.2.4 official Flash / PTC](reports/test-report-dsh-0.2.4-ptc.md) | 实模主/子代理碰撞拒绝;原始主 PTC 任务失败与独立收尾分别记录 |
63
+ | [Claude Code harness](reports/test-report-claude-code-harness.md) | 脚本模型驱动的真实宿主 hook 验证 |
64
+ | [Kimi Code blocking](reports/test-report-kimi-code-block.md) | 所测版本的 Bash BLOCK 与故障路径 |
65
+ | [Kimi Code Lab](reports/test-report-kimi-guard-lab.md) | 历史配对试次与后续本地复核 |
66
+ | [Codex / GPT-6 Astra](reports/test-report-codex-gpt-6-astra-high.md) | Skill/CLI 验收,不声明原生拦截 |
67
+ | [Codex / GPT-5.6 Sol](reports/test-report-codex-gpt-5.6-sol.md) | v0.1.1 历史 Skill/CLI 评估 |
68
+ | [DSH 0.1.5-rc.1](reports/test-report-dsh-0.1.5-rc.1.md) | 打包插件与执行级 Bash 验收 |
69
+ | [DSH 0.2 upgrade](reports/test-report-dsh-0.2-upgrade.md) | 升级初期兼容快照,后续状态见契约复核 |
70
+ | [DSH Lab baseline](reports/test-report-dsh-guard-lab.md) | 真实模型基线;未形成 L2 结论 |
71
+ | [DSH native sessions](reports/test-report-dsh-native-session.md) | 原生工具结果捕获与保留日志复核 |
72
+ | [DSH paired Lab](reports/test-report-dsh-paired-lab.md) | 配对工作流与结果改写契约调查 |
73
+ | [DSH retry evidence](reports/test-report-dsh-retry-evidence.md) | 失败尝试、重试会话与证据解析 |
74
+ | [DSH read redaction](reports/test-report-dsh-read-redaction.md) | 零模型原生读取、下一请求与落盘检查 |
75
+ | [DSH real follow-up](reports/test-report-dsh-real-followup.md) | 真实读取开关对照;不等于注入 L2 |
76
+ | [DSH v0.1.1](reports/test-report-dsh-v0.1.1.md) | 历史真机测试 |
77
+ | [WorkBuddy / Windows Core](reports/test-report-workbuddy-windows-core.md) | 社区 Core/CLI 反馈与修复回归 |
78
+ | [ZCode / Windows](reports/test-report-zcode-glm-flash.md) | 历史 CLI/hook 试次及许可绕过观察 |
79
+
80
+ ## Releases
81
+
82
+ | Document / 文档 | Scope / 范围 |
83
+ |---|---|
84
+ | [0.2.4](releases/release-notes-0.2.4.md) | 恢复维护、trash 查询及兼容性例外 |
85
+ | [0.2.3](releases/release-notes-0.2.3.md) | 正式版范围与证据边界 |
86
+ | [0.2.3-rc2](releases/release-notes-0.2.3-rc2.md) | 离线 Lab 与已复核 DSH 契约 |
87
+ | [0.2.3-rc1](releases/release-notes-0.2.3-rc1.md) | Windows Core 与预发布范围 |
88
+ | [0.2.2](releases/release-notes-0.2.2.md) | 宿主漂移、实时哨兵与 DSH 打包验收 |
89
+ | [0.2.1](releases/release-notes-0.2.1.md) | adapter/doctor 变更 |
90
+ | [0.2.0](releases/release-notes-0.2.0.md) | exfil 与配置安全视图等发布范围 |
91
+ | [0.2.0-rc1](releases/release-notes-0.2.0-rc1.md) | 早期源码预览范围 |
92
+
93
+ ## History
94
+
95
+ These documents explain earlier proposals and implementation experience.
96
+ Current behavior is defined by the Core, Skills and current guides.
97
+
98
+ | Document / 文档 | Scope / 范围 |
99
+ |---|---|
100
+ | [Friction log](history/friction.md) | F1–F20 实现发现与修复经验 |
101
+ | [Unguarded deletion note](history/development-note-unguarded-deletion.md) | 去标识化事故探索与恢复方向 |
102
+ | [Secret Guard analysis](history/secret-guard-analysis.md) | 实现前的需求分析 |
103
+ | [Secret Guard design](history/secret-guard-design.md) | 早期设计候选与原范围 |
104
+ | [Secret Guard architecture](history/secret-guard-architecture.md) | 早期架构草图;不代表拦截点已交付 |