@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,898 @@
1
+ """Command dialect layer: posix | cmd | powershell.
2
+
3
+ Why this module exists
4
+ ----------------------
5
+ The classifier's effect vocabulary was written for POSIX shells (`rm`,
6
+ `rmdir`, `unlink`, `shred`, `find -delete`, `git ...`). On native Windows
7
+ shells the destructive intent is expressed by entirely different programs
8
+ (`del`, `erase`, `rd`, `rmdir`, `Remove-Item`, ...) and with different
9
+ lexical rules (no backslash escapes inside double quotes, `^` as the
10
+ caret escape, command separator `&` instead of `&&`, PowerShell's own
11
+ quoting and parameter syntax).
12
+
13
+ This module isolates *dialect* concerns so `classifier.classify_command`
14
+ can stay dialect-agnostic:
15
+
16
+ tokenize_<dialect>(cmd) -> TokenStream
17
+ Lexical stage only: split a command line into segments of words,
18
+ split segments on the dialect's separators, and record whether the
19
+ dialect's quoting rules could not be applied.
20
+
21
+ DIALECTS[<name>].classify(stream) -> List[OpSpec]
22
+ Structural stage: recognise the destructive programs of that
23
+ dialect and map their flags onto the shared effect facts
24
+ (recursive / force / dry_run / wildcard / undeterminable).
25
+
26
+ Design rules (mirroring the core's):
27
+
28
+ * **Fail closed.** Any construct the dialect parser cannot resolve
29
+ mechanically - unbalanced quotes, `%VAR%` / `$(...)` / backtick
30
+ substitution, `-WhatIf:$false`, command nesting, input piped from
31
+ another process, a wildcard handed to a tool that expands it itself -
32
+ becomes an `undeterminable` fact. The policy layer turns those into
33
+ BLOCK. We never guess what a target set will be.
34
+ * **Additive.** The POSIX dialect preserves the exact behaviour of the
35
+ historical `shlex`-based path, including the ALIAS vocabulary
36
+ (`rm`/`ri`/`del` in PowerShell). The default dialect stays POSIX, so
37
+ every existing adapter (Claude hook, DSH plugin, check.py CLI) is
38
+ unaffected until a caller opts in.
39
+ * **Facts, not decisions.** Like the rest of the classifier, a dialect
40
+ returns OpSpecs only; it never decides ALLOW/BLOCK.
41
+
42
+ Not in Phase 1: real Windows end-to-end execution, UNC/device-path
43
+ semantics, PowerShell module auto-loading, and cmd's full `%~` modifier
44
+ set beyond the forms that are mechanically resolvable.
45
+ """
46
+ from __future__ import annotations
47
+
48
+ import dataclasses
49
+ import os
50
+ import re
51
+ import shlex
52
+ from typing import List, NamedTuple, Optional, Sequence, Tuple
53
+
54
+ # Kept in sync with classifier.py; importing it here would create a cycle
55
+ # because classifier imports this module.
56
+ _OP_SPEC_DEFAULTS = {
57
+ "op": "", "kind": "other", "sub": None, "targets": (),
58
+ "recursive": False, "force": False, "dry_run": False,
59
+ "extra_flags": (), "segment_index": 0, "wildcard": False,
60
+ "undeterminable": False, "shape": None, "notes": (),
61
+ }
62
+
63
+ # ------------------------------------------------------------------ dialects
64
+
65
+ DIALECT_POSIX = "posix"
66
+ DIALECT_CMD = "cmd"
67
+ DIALECT_POWERSHELL = "powershell"
68
+
69
+ DIALECT_ALIASES = {
70
+ "posix": DIALECT_POSIX,
71
+ "sh": DIALECT_POSIX,
72
+ "bash": DIALECT_POSIX,
73
+ "zsh": DIALECT_POSIX,
74
+ "cmd": DIALECT_CMD,
75
+ "cmd.exe": DIALECT_CMD,
76
+ "batch": DIALECT_CMD,
77
+ "bat": DIALECT_CMD,
78
+ "powershell": DIALECT_POWERSHELL,
79
+ "pwsh": DIALECT_POWERSHELL,
80
+ "ps": DIALECT_POWERSHELL,
81
+ }
82
+
83
+ DEFAULT_DIALECT = DIALECT_POSIX
84
+
85
+ # PowerShell ships a *suffix* rule: `del` resolves to the MDAC `del` alias
86
+ # for Remove-Item (SQL column masters only in legacy hosts). Bounded
87
+ # allowlist of the aliases we are willing to expand - anything else
88
+ # (including user-defined aliases) stays unrecognised rather than guessed.
89
+ POWERSHELL_ALIASES = {
90
+ "rm": "remove-item",
91
+ "ri": "remove-item",
92
+ "rd": "remove-item",
93
+ "rmdir": "remove-item",
94
+ "del": "remove-item",
95
+ "erase": "remove-item",
96
+ "remove-item": "remove-item",
97
+ }
98
+ # NOTE: `erase` is *not* a PowerShell alias (it is a cmd builtin) - listing
99
+ # it here is a deliberate over-approximation: a Windows console session
100
+ # routinely mixes the two vocabularies, and expanding `erase` to
101
+ # Remove-Item yields the same effect fact either way. The alternative
102
+ # (ignoring the line) would be a silent allow.
103
+
104
+ # Windows console encodings: the OEM code page is the truth for cmd, and
105
+ # both batches of tests run on Linux CI, so decode UTF-8 first and fall
106
+ # back to a Latin-1 round-trip (every byte maps, nothing is silently lost).
107
+ _CONSOLE_ENCODINGS = ("utf-8", "cp437", "cp1252")
108
+
109
+ # Argument-count invariants for cmd builtins, so phrase splitting can tell
110
+ # `del /s a b` (two targets) from `rmdir /s /q "a b"` (one quoted target).
111
+ # ---------------------------------------------------------------- tokenizer
112
+
113
+
114
+ @dataclasses.dataclass
115
+ class TokenStream:
116
+ """Dialect-neutral lexical result handed to a dialect classifier."""
117
+
118
+ dialect: str
119
+ segments: List[List[str]] = dataclasses.field(default_factory=list)
120
+ error: Optional[str] = None
121
+
122
+ @property
123
+ def ok(self) -> bool:
124
+ return self.error is None
125
+
126
+ @property
127
+ def words(self) -> List[str]:
128
+ return [w for seg in self.segments for w in seg]
129
+
130
+
131
+ class TokenizeError(ValueError):
132
+ """Raised by a tokenizer when the dialect's quoting rules do not apply."""
133
+
134
+
135
+ # ------------------------------------------------------------------- posix
136
+
137
+
138
+ def _strip_group_edges(seg: List[str]) -> List[str]:
139
+ """Drop subshell/grouping parens that shlex glued onto words."""
140
+ while seg and seg[0][:1] in ("(", "{"):
141
+ seg[0] = seg[0][1:]
142
+ if not seg[0]:
143
+ seg.pop(0)
144
+ while seg and seg[-1][-1:] in (")", "}"):
145
+ seg[-1] = seg[-1][:-1]
146
+ if not seg[-1]:
147
+ seg.pop()
148
+ return seg
149
+
150
+
151
+ def tokenize_posix(cmd: str, separators: Sequence[str] = ()) -> TokenStream:
152
+ """Tokenize with the historical `shlex` path (behaviour-preserving).
153
+
154
+ The caller (classifier) owns heredoc stripping and segment splitting so
155
+ the POSIX path stays byte-for-byte identical to the pre-dialect code.
156
+ """
157
+ try:
158
+ tokens = shlex.split(cmd, posix=True)
159
+ except ValueError as exc:
160
+ return TokenStream(DIALECT_POSIX, [], error=str(exc))
161
+ return TokenStream(DIALECT_POSIX, [tokens] if tokens else [])
162
+
163
+
164
+ # --------------------------------------------------------------------- cmd
165
+
166
+
167
+ CMD_SEPARATORS = ("&", "&&", "||", "|", "\n")
168
+ def _decode_console(cmd: str) -> str:
169
+ if isinstance(cmd, bytes): # pragma: no cover - defensive
170
+ return cmd.decode("utf-8", "surrogateescape")
171
+ return cmd
172
+
173
+
174
+ def tokenize_cmd(cmd: str, separators: Sequence[str] = CMD_SEPARATORS) -> TokenStream:
175
+ """Tokenize a `cmd.exe` command line.
176
+
177
+ Rules that differ from POSIX and matter for classification:
178
+
179
+ * double quotes group but do **not** honour backslash escapes, and a
180
+ backslash inside quotes stays literal (so `rmdir /s "C:\\tmp\\"` is
181
+ one argument, backslash included);
182
+ * `^` is the escape character *outside* quotes and is stripped;
183
+ * `&`, `&&`, `|`, `||` are always separators, even unquoted inside a
184
+ word (`a&del b` is two commands);
185
+ * `%VAR%` is not expanded - the token is kept verbatim and a later
186
+ stage marks it undeterminable.
187
+
188
+ Raises TokenizeError on an unterminated quote.
189
+ """
190
+ text = _decode_console(cmd)
191
+ segments: List[List[str]] = []
192
+ current: List[str] = []
193
+ words: List[str] = []
194
+ quote_open = False
195
+ quote_char = ""
196
+ idx = 0
197
+ length = len(text)
198
+
199
+ def flush_word() -> None:
200
+ if current:
201
+ words.append("".join(current))
202
+ current.clear()
203
+
204
+ def flush_segment() -> None:
205
+ flush_word()
206
+ if words:
207
+ segments.append(list(words))
208
+ words.clear()
209
+
210
+ while idx < length:
211
+ ch = text[idx]
212
+ if quote_open:
213
+ if ch == quote_char:
214
+ quote_open = False
215
+ else:
216
+ current.append(ch)
217
+ idx += 1
218
+ continue
219
+
220
+ if ch == '"':
221
+ quote_open = True
222
+ quote_char = ch
223
+ idx += 1
224
+ continue
225
+
226
+ if ch == "^" and separators:
227
+ # Caret escape: the next character is literal, including
228
+ # separators and quotes.
229
+ nxt = text[idx + 1] if idx + 1 < length else ""
230
+ current.append(nxt)
231
+ idx += 2
232
+ continue
233
+
234
+ matched = next((s for s in sorted(separators, key=len, reverse=True)
235
+ if text.startswith(s, idx)), None)
236
+ if matched:
237
+ flush_segment()
238
+ idx += len(matched)
239
+ continue
240
+
241
+ if ch in " \t":
242
+ flush_word()
243
+ if separators and text.startswith("\n", idx):
244
+ flush_segment()
245
+ idx += 1
246
+ continue
247
+
248
+ current.append(ch)
249
+ idx += 1
250
+
251
+ if quote_open:
252
+ raise TokenizeError("unbalanced quote in cmd command line")
253
+ flush_segment()
254
+ return TokenStream(DIALECT_CMD, segments)
255
+
256
+
257
+ # ------------------------------------------------------------ powershell
258
+
259
+ PS_SEPARATORS = (";", "|", "||", "&&", "&", "\n")
260
+
261
+
262
+ def tokenize_powershell(cmd: str, separators: Sequence[str] = PS_SEPARATORS) -> TokenStream:
263
+ """Tokenize a PowerShell command line.
264
+
265
+ Handles the lexical rules that change the *word* set:
266
+
267
+ * single quotes are literal (no escapes at all, `''` is one quote);
268
+ * double quotes group and honour the backtick escape;
269
+ * backtick escapes the next character outside quotes;
270
+ * `;`, `|`, `&` separate commands.
271
+
272
+ `$var`, `$(...)`, `@(...)`, subexpressions and script blocks are *not*
273
+ resolved. They survive into the tokens and mark the operation
274
+ undeterminable downstream (fail closed). Raises TokenizeError on an
275
+ unterminated quote.
276
+ """
277
+ text = _decode_console(cmd)
278
+ segments: List[List[str]] = []
279
+ words: List[str] = []
280
+ current: List[str] = []
281
+ quote: Optional[str] = None
282
+ idx = 0
283
+ length = len(text)
284
+
285
+ def flush_word() -> None:
286
+ if current:
287
+ words.append("".join(current))
288
+ current.clear()
289
+
290
+ def flush_segment() -> None:
291
+ flush_word()
292
+ if words:
293
+ segments.append(list(words))
294
+ words.clear()
295
+
296
+ while idx < length:
297
+ ch = text[idx]
298
+ if quote == "'":
299
+ if ch == "'":
300
+ if idx + 1 < length and text[idx + 1] == "'":
301
+ current.append("'")
302
+ idx += 2
303
+ continue
304
+ quote = None
305
+ idx += 1
306
+ continue
307
+ current.append(ch)
308
+ idx += 1
309
+ continue
310
+ if quote == '"':
311
+ if ch == '"':
312
+ quote = None
313
+ idx += 1
314
+ continue
315
+ if ch == "`" and idx + 1 < length:
316
+ current.append(text[idx + 1])
317
+ idx += 2
318
+ continue
319
+ if ch == "$":
320
+ # `$` inside double quotes interpolates; record the whole
321
+ # subexpression verbatim so downstream sees the danger.
322
+ end = _ps_subexpression_end(text, idx)
323
+ current.append(text[idx:end])
324
+ idx = end
325
+ continue
326
+ current.append(ch)
327
+ idx += 1
328
+ continue
329
+
330
+ if ch in "'\"":
331
+ quote = ch
332
+ idx += 1
333
+ continue
334
+ if ch == "`" and idx + 1 < length:
335
+ current.append(text[idx + 1])
336
+ idx += 2
337
+ continue
338
+ if ch == "$":
339
+ end = _ps_subexpression_end(text, idx)
340
+ current.append(text[idx:end])
341
+ idx = end
342
+ continue
343
+
344
+ matched = next((s for s in sorted(separators, key=len, reverse=True)
345
+ if text.startswith(s, idx)), None)
346
+ if matched:
347
+ flush_segment()
348
+ idx += len(matched)
349
+ continue
350
+
351
+ if ch in " \t":
352
+ flush_word()
353
+ idx += 1
354
+ continue
355
+
356
+ current.append(ch)
357
+ idx += 1
358
+
359
+ if quote is not None:
360
+ raise TokenizeError("unbalanced quote in PowerShell command line")
361
+ flush_segment()
362
+ return TokenStream(DIALECT_POWERSHELL, segments)
363
+
364
+
365
+ def _ps_subexpression_end(text: str, start: int) -> int:
366
+ """End index of a PowerShell `$...` token starting at `start`."""
367
+ if text.startswith("$(", start):
368
+ depth = 0
369
+ idx = start + 1
370
+ while idx < len(text):
371
+ if text[idx] == "(":
372
+ depth += 1
373
+ elif text[idx] == ")":
374
+ depth -= 1
375
+ if depth == 0:
376
+ return idx + 1
377
+ idx += 1
378
+ return len(text) # unbalanced: let the parser call it undeterminable
379
+ match = re.match(r"\$[A-Za-z_][A-Za-z0-9_:]*|\$[?^$]", text[start:])
380
+ if match:
381
+ return start + match.end()
382
+ return start + 1
383
+
384
+
385
+ # --------------------------------------------- dialect-neutral fact helpers
386
+
387
+
388
+ # Smell test for an opaque nested host script (the inner text cannot be
389
+ # parsed). Deliberately independent from the POSIX smell vocabulary: the
390
+ # strings arriving here are PowerShell, and "unknown-dialect leak" is
391
+ # exactly what a shared regex would hide.
392
+ NESTED_SMELL_RE = re.compile(
393
+ r"(?:^|[\s;&|(=/])(rm|ri|rd|rmdir|del|erase|remove-item)\b"
394
+ r"|clear-content\b|-delete\b|\bdelete\b",
395
+ re.IGNORECASE)
396
+
397
+
398
+ def has_interpolation(word: str) -> bool:
399
+ """True when a word carries dialect substitution the guard cannot resolve."""
400
+ if "$" in word or "`" in word:
401
+ return True
402
+ if "%" in word and re.search(r"%[^%]+%", word):
403
+ return True
404
+ return False
405
+
406
+
407
+ def to_op_spec(cls, **facts):
408
+ """Build an OpSpec from dialect facts, tolerating inventory changes."""
409
+ names = {f.name for f in dataclasses.fields(cls)}
410
+ kwargs = {}
411
+ for key, value in _OP_SPEC_DEFAULTS.items():
412
+ if key not in names:
413
+ continue
414
+ kwargs[key] = list(value) if isinstance(value, (list, tuple)) else value
415
+ kwargs.update({k: v for k, v in facts.items() if k in names})
416
+ return cls(**kwargs)
417
+
418
+
419
+ # ------------------------------------------------------------- cmd classify
420
+
421
+ CMD_DELETE_CMDS = {"del", "erase", "rd", "rmdir"}
422
+ CMD_ALIASES = {"delete": "del", "remove": "del"}
423
+
424
+ # `del` is the delete file builtin; `/a` additionally removes files whose
425
+ # attributes match. `rd`/`rmdir` remove directories and, with `/s`, whole
426
+ # trees. Both accept a space-separated target list.
427
+ _CMD_DEL_FLAGS = {
428
+ "f": "force", "q": "force", "s": "recursive", "p": None, "a": None,
429
+ "n": None,
430
+ }
431
+ _CMD_RD_FLAGS = {"s": "recursive", "q": "force"}
432
+
433
+
434
+ def _cmd_strip_quotes(word: str) -> str:
435
+ if len(word) >= 2 and word[0] == '"' and word[-1] == '"':
436
+ return word[1:-1]
437
+ return word
438
+
439
+
440
+ def classify_cmd(stream: TokenStream, kind_fs_delete: str,
441
+ op_spec_cls) -> List[object]:
442
+ """Recognise cmd.exe destructive commands in a token stream."""
443
+ specs: List[object] = []
444
+ for index, segment in enumerate(stream.segments):
445
+ head_raw = _cmd_strip_quotes(segment[0]).lower()
446
+ head_raw = CMD_ALIASES.get(head_raw, head_raw)
447
+ if head_raw not in CMD_DELETE_CMDS:
448
+ continue
449
+ spec = to_op_spec(op_spec_cls, op=head_raw, kind=kind_fs_delete,
450
+ segment_index=index)
451
+ flag_map = _CMD_RD_FLAGS if head_raw in ("rd", "rmdir") else _CMD_DEL_FLAGS
452
+ rest = segment[1:]
453
+ treated_as_flags = False
454
+ for tok in rest:
455
+ bare = _cmd_strip_quotes(tok)
456
+ if bare.startswith("/") and len(bare) > 1 and not treated_as_flags:
457
+ for ch in bare[1:].lower():
458
+ mapped = flag_map.get(ch, "unknown")
459
+ if mapped == "force":
460
+ spec.force = True
461
+ elif mapped == "recursive":
462
+ spec.recursive = True
463
+ elif mapped == "unknown":
464
+ spec.undeterminable = True
465
+ spec.note(f"unknown flag /{ch} for {head_raw}")
466
+ continue
467
+ treated_as_flags = True
468
+ spec.targets.append(bare)
469
+ if not spec.targets:
470
+ spec.undeterminable = True
471
+ spec.note(f"{head_raw} without a target; the target set is "
472
+ "not statically known")
473
+ specs.append(spec)
474
+ return specs
475
+
476
+
477
+ def classify_cmd_stream(stream: TokenStream) -> "List[object]":
478
+ from .classifier import KIND_FS_DELETE, OpSpec # local import: no cycle
479
+ return classify_cmd(stream, KIND_FS_DELETE, OpSpec)
480
+
481
+
482
+ # ------------------------------------------------------ powershell classify
483
+
484
+ PS_DELETE_CMDS = {"remove-item"}
485
+ # Phase 1 keeps exactly one PowerShell delete cmdlet in scope. Wider
486
+ # cmdlets (Clear-Content, Remove-ItemProperty) mutate other provider
487
+ # object types whose compensation the guard does not implement yet, so
488
+ # they stay outside the recognised vocabulary instead of being mapped
489
+ # onto a filesystem relocation that would not restore them.
490
+
491
+ # Switches whose *value* changes what gets deleted: treating them as
492
+ # semantics-neutral would be a guess, so they are undeterminable.
493
+ _PS_UNSAFE_PARAMS = (
494
+ "include", "exclude", "filter", "literalpath", "stream", "attributes",
495
+ "credential", "confirm", "verbose", "debug", "erroraction",
496
+ "warningaction", "errorvariable", "outvariable", "pipelinevariable",
497
+ )
498
+
499
+
500
+ # ------------------------------------------------------ parameter names
501
+ #
502
+ # PowerShell resolves a parameter by *unambiguous prefix*: `-Recurse` may
503
+ # be written `-r`, `-rec`, `-recur`... The guard must resolve these too,
504
+ # because `ri build -r -fo` is a recursive forced delete that Phase 1 read
505
+ # as `recursive=False, force=False` - a silently weaker fact than reality.
506
+ #
507
+ # The expansion is deliberately *stricter* than the host:
508
+ #
509
+ # * Only parameters that the guard already models, or that it must treat
510
+ # as unsafe, are in the table. Everything else stays unrecognised.
511
+ # * A prefix is expanded only if it matches exactly ONE entry. The
512
+ # matches are grouped by *effect*, not by name: if two candidates would
513
+ # lead the guard to different facts, the prefix is ambiguous and is
514
+ # left unexpanded, which lands on "unknown parameter" -> BLOCK.
515
+ # The guard never guesses a flag's meaning.
516
+ #
517
+ # Examples of the fail-closed direction:
518
+ # -wi -> WhatIf / WarningAction (one stops the delete, one does not)
519
+ # -p -> Path / PSPath (both targets, but keep it explicit)
520
+ # -c -> Confirm / Credential
521
+ # -co -> Confirm / ConfirmPreference-less: still a prompt either way,
522
+ # so it resolves to Confirm (same effect: uncertain).
523
+ _PS_PREFIX_EFFECTS = {
524
+ # prefix -> (canonical name, effect group). Same group == safe to merge.
525
+ "recurse": ("recurse", "recursive"),
526
+ "force": ("force", "force"),
527
+ "whatif": ("whatif", "dry-run"),
528
+ "literalpath": ("literalpath", "unsafe"),
529
+ "path": ("path", "targets"),
530
+ "pspath": ("pspath", "targets"),
531
+ "confirm": ("confirm", "confirm"),
532
+ "erroraction": ("erroraction", "neutral"),
533
+ "warningaction": ("warningaction", "unsafe"),
534
+ "include": ("include", "unsafe"),
535
+ "exclude": ("exclude", "unsafe"),
536
+ "filter": ("filter", "unsafe"),
537
+ "stream": ("stream", "unsafe"),
538
+ "attributes": ("attributes", "unsafe"),
539
+ "credential": ("credential", "unsafe"),
540
+ "verbose": ("verbose", "unsafe"),
541
+ "debug": ("debug", "unsafe"),
542
+ "errorvariable": ("errorvariable", "unsafe"),
543
+ "outvariable": ("outvariable", "unsafe"),
544
+ "pipelinevariable": ("pipelinevariable", "unsafe"),
545
+ }
546
+
547
+ # `-lp` is a documented PowerShell prefix of `-LiteralPath` and the only
548
+ # prefix that is *shorter than the first table entry* in a way the generic
549
+ # resolver would call ambiguous, so it is pinned here.
550
+ _PS_PREFIX_PINNED = {"lp": "literalpath"}
551
+
552
+
553
+ def resolve_ps_param(name: str) -> Optional[Tuple[str, bool]]:
554
+ """Resolve a PowerShell parameter name, honouring prefix matching.
555
+
556
+ Returns `(canonical_name, was_abbreviated)` when the name resolves
557
+ unambiguously, else None (the caller must treat it as an unknown
558
+ parameter and fail closed).
559
+ """
560
+ lowered = name.lower()
561
+
562
+ pinned = _PS_PREFIX_PINNED.get(lowered)
563
+ if pinned is not None:
564
+ return pinned, True
565
+
566
+ exact = _PS_PREFIX_EFFECTS.get(lowered)
567
+ if exact is not None:
568
+ return lowered, False
569
+
570
+ candidates = [(full, group) for full, group in _PS_PREFIX_EFFECTS.items()
571
+ if full.startswith(lowered)]
572
+ if not candidates:
573
+ return None
574
+
575
+ # Collapse by effect group: `-re` only matches `recurse`; a prefix that
576
+ # matched two *different* effects is ambiguous and never expanded.
577
+ groups = {group for _, group in candidates}
578
+ if len(groups) != 1:
579
+ return None
580
+ # Same effect, several full names (e.g. none today, but be explicit):
581
+ # prefer the shortest full name so the audit note is stable.
582
+ full = min((c for c, _ in candidates), key=len)
583
+ return full, full != lowered
584
+
585
+
586
+ def _ps_param_name(tok: str) -> Optional[Tuple[str, Optional[str]]]:
587
+ """('name', 'value') for a `-Name`/`--Name:value` token, else None."""
588
+ if not tok.startswith("-") or len(tok) < 2:
589
+ return None
590
+ body = tok.strip("-")
591
+ if not body:
592
+ return None
593
+ name, sep, value = body.partition(":")
594
+ return name.lower(), (value if sep else None)
595
+
596
+
597
+ def _ps_bool_value(value: Optional[str]) -> Optional[bool]:
598
+ """Switch value semantics: `-Recurse:$false` is NOT recursive.
599
+
600
+ Returns None when the value is itself a variable/subexpression - the
601
+ caller must then fail closed instead of assuming a boolean.
602
+ """
603
+ if value is None or value == "":
604
+ return True
605
+ lowered = value.strip().lower()
606
+ if lowered in ("$true", "true", "1"):
607
+ return True
608
+ if lowered in ("$false", "false", "0"):
609
+ return False
610
+ return None
611
+
612
+
613
+ def _ps_base_name(word: str) -> str:
614
+ """Command name in object/string form, without path or `.exe` suffix."""
615
+ cleaned = word.strip().strip("&").strip("'\"")
616
+ base = os.path.basename(cleaned.replace("\\", "/")).lower()
617
+ return base[:-4] if base.endswith(".exe") else base
618
+
619
+
620
+ def classify_powershell(stream: TokenStream, kind_fs_delete: str,
621
+ op_spec_cls, smell_re=None) -> List[object]:
622
+ """Recognise PowerShell destructive commands in a token stream.
623
+
624
+ A nested host (`powershell -Command "<script>"`, `pwsh -EncodedCommand`)
625
+ is an interpreter hop: the guard cannot parse the inner script's
626
+ structure, so the scripts stay opaque and only the *smell* test decides
627
+ whether the line is handed to policy as an undeterminable UNKNOWN -
628
+ the same fail-closed treatment POSIX `bash -c` receives.
629
+ """
630
+ specs: List[object] = []
631
+ for index, segment in enumerate(stream.segments):
632
+ head = segment[0]
633
+ base_head = _ps_base_name(head)
634
+ if base_head in ("powershell", "pwsh"):
635
+ inner = " ".join(segment[1:])
636
+ if smell_re is not None and smell_re.search(inner):
637
+ spec = to_op_spec(op_spec_cls, op=base_head,
638
+ kind="unknown", undeterminable=True,
639
+ segment_index=index,
640
+ targets=[inner[:200]])
641
+ spec.note("nested PowerShell host with destructive smell; "
642
+ "the inner script cannot be parsed statically")
643
+ specs.append(spec)
644
+ continue
645
+ base = base_head
646
+ canonical = POWERSHELL_ALIASES.get(base, base)
647
+ if canonical not in PS_DELETE_CMDS and base not in PS_DELETE_CMDS:
648
+ continue
649
+ spec = to_op_spec(op_spec_cls, op=canonical if canonical in
650
+ PS_DELETE_CMDS else base,
651
+ kind=kind_fs_delete, segment_index=index)
652
+ if base != canonical:
653
+ spec.note(f"alias '{base}' expanded to '{canonical}'")
654
+
655
+ targets: List[str] = []
656
+ end_of_params = False
657
+ for tok in segment[1:]:
658
+ if tok in ("--", "--%"):
659
+ only_named = True
660
+ continue
661
+ param = None if end_of_params else _ps_param_name(tok)
662
+ if param is None:
663
+ targets.append(tok)
664
+ continue
665
+ name, value = param
666
+ resolved = resolve_ps_param(name)
667
+ if resolved is None:
668
+ spec.undeterminable = True
669
+ spec.note(f"unknown parameter -{name}")
670
+ continue
671
+ canonical, abbreviated = resolved
672
+ if abbreviated:
673
+ # Expansion is auditable: the raw token is what the host
674
+ # saw, the canonical name is what the guard reasoned about.
675
+ spec.note(f"parameter -{name} expanded to -{canonical}")
676
+ name = canonical
677
+ if name == "whatif":
678
+ flag = _ps_bool_value(value)
679
+ if flag is None:
680
+ spec.undeterminable = True
681
+ spec.note("-WhatIf value is not statically known")
682
+ elif flag:
683
+ spec.dry_run = True
684
+ spec.note("-WhatIf: nothing is actually deleted")
685
+ # -WhatIf:$false => effective deletion, no note needed
686
+ elif name == "recurse":
687
+ flag = _ps_bool_value(value)
688
+ if flag is None:
689
+ spec.undeterminable = True
690
+ spec.note("-Recurse value is not statically known")
691
+ else:
692
+ spec.recursive = flag
693
+ elif name == "force":
694
+ flag = _ps_bool_value(value)
695
+ if flag is None:
696
+ spec.undeterminable = True
697
+ spec.note("-Force value is not statically known")
698
+ else:
699
+ spec.force = flag
700
+ elif name in ("literalpath", "lp"):
701
+ spec.undeterminable = True
702
+ spec.note("-LiteralPath: wildcard interpretation is not "
703
+ "statically known")
704
+ elif name in ("path", "pspath"):
705
+ # -Path is the default parameter set; its value is an
706
+ # ordinary target list.
707
+ pass
708
+ elif name in ("erroraction", "ea"):
709
+ spec.note("-ErrorAction does not change the effect")
710
+ elif name == "confirm":
711
+ # Only an interactive `-Confirm` prompt makes the guard's
712
+ # static reasoning meaningless; `-Confirm:$false` deletes
713
+ # without asking and must not look safer than it is.
714
+ flag = _ps_bool_value(value)
715
+ if flag is not False:
716
+ spec.undeterminable = True
717
+ spec.note("-Confirm prompts interactively; the executed "
718
+ "selection is not statically known")
719
+ else:
720
+ # Any resolvable name that is not explicitly handled is in
721
+ # _PS_UNSAFE_PARAMS; reaching here means the table and this
722
+ # branch disagree, which must fail closed, not fall through.
723
+ spec.undeterminable = True
724
+ spec.note(f"-{name.capitalize()} changes the target set; "
725
+ "not statically resolvable")
726
+
727
+ if not targets and not spec.dry_run:
728
+ spec.undeterminable = True
729
+ spec.note("delete without an explicit target; the target set "
730
+ "arrives from the pipeline or a variable")
731
+ spec.targets.extend(targets)
732
+ if any(t.startswith("\\\\") for t in targets):
733
+ spec.note("UNC path target; path resolution is host-dependent")
734
+ specs.append(spec)
735
+ return specs
736
+
737
+
738
+ def classify_powershell_stream(stream: TokenStream) -> "List[object]":
739
+ # Local import: classifier imports this module, so a top-level import
740
+ # would be a cycle.
741
+ from .classifier import KIND_FS_DELETE, KIND_UNKNOWN, OpSpec
742
+
743
+ assert KIND_FS_DELETE == "fs-delete" and KIND_UNKNOWN == "unknown"
744
+ return classify_powershell(stream, KIND_FS_DELETE, OpSpec,
745
+ smell_re=NESTED_SMELL_RE)
746
+
747
+
748
+ # ------------------------------------------------------------------ registry
749
+
750
+
751
+ @dataclasses.dataclass(frozen=True)
752
+ class Dialect:
753
+ name: str
754
+ tokenizer: object
755
+ classifier: object
756
+ separators: Tuple[str, ...] = ()
757
+
758
+
759
+ def classify_stream(stream: TokenStream) -> List[object]:
760
+ """Route a token stream to its dialect's structural classifier."""
761
+ if stream.dialect == DIALECT_CMD:
762
+ return classify_cmd_stream(stream)
763
+ if stream.dialect == DIALECT_POWERSHELL:
764
+ return classify_powershell_stream(stream)
765
+ return [] # POSIX classification lives in classifier.py
766
+
767
+
768
+ class DialectResolution(NamedTuple):
769
+ """Outcome of resolving an externally supplied dialect selector.
770
+
771
+ `dialect` is the effective dialect to lex with; `requested` is what the
772
+ caller asked for (verbatim, for the audit trail); `ok` is False when the
773
+ selector was unusable, in which case `reason` explains why and the
774
+ caller must NOT fall back to POSIX silently - a Windows command line
775
+ lexed by the POSIX lexer is the failure this layer exists to prevent.
776
+ """
777
+
778
+ dialect: str
779
+ requested: Optional[str]
780
+ ok: bool = True
781
+ reason: Optional[str] = None
782
+ # "unknown" (name not recognised) or "invalid" (malformed selector);
783
+ # None when ok. Mirrored onto a policy reason code by the caller, so the
784
+ # classification lives in exactly one place.
785
+ kind: Optional[str] = None
786
+
787
+
788
+ def resolve_dialect(name: Optional[str],
789
+ source: str = "default") -> DialectResolution:
790
+ """Resolve a dialect selector coming from a CLI flag / harness payload.
791
+
792
+ Unlike `normalize_dialect`, this never raises: adapters need a *value*
793
+ they can act on (and report), not an exception that a harness might
794
+ swallow into a fail-open. Three outcomes:
795
+
796
+ * empty/None -> DEFAULT_DIALECT, ok (the documented default)
797
+ * a known name/alias -> that dialect, ok
798
+ * anything else -> ok=False. Malformed values (empty after
799
+ stripping, embedded separators such as `posix:cmd`, non-string
800
+ types) are reported as `invalid`; merely unrecognised names as
801
+ `unknown`. Either way the caller must fail closed.
802
+ """
803
+ if name is None or (isinstance(name, str) and not name.strip()):
804
+ return DialectResolution(DEFAULT_DIALECT, name)
805
+
806
+ if not isinstance(name, str):
807
+ return DialectResolution(DEFAULT_DIALECT, repr(name), ok=False,
808
+ reason=f"{source}: dialect selector is not "
809
+ f"a string ({type(name).__name__})",
810
+ kind="invalid")
811
+
812
+ key = name.strip().lower()
813
+ if not key:
814
+ return DialectResolution(DEFAULT_DIALECT, name, ok=False,
815
+ reason=f"{source}: dialect selector is empty",
816
+ kind="invalid")
817
+ if any(ch in key for ch in ":,/;"):
818
+ return DialectResolution(DEFAULT_DIALECT, name, ok=False,
819
+ reason=f"{source}: dialect selector {name!r} "
820
+ "is malformed (expected a single "
821
+ "dialect name)",
822
+ kind="invalid")
823
+ if key not in DIALECT_ALIASES:
824
+ known = ", ".join(sorted(set(DIALECT_ALIASES.values())))
825
+ return DialectResolution(DEFAULT_DIALECT, name, ok=False,
826
+ reason=f"{source}: unknown dialect {name!r} "
827
+ f"(known: {known})",
828
+ kind="unknown")
829
+ return DialectResolution(DIALECT_ALIASES[key], name)
830
+
831
+
832
+ def normalize_dialect(name: Optional[str]) -> str:
833
+ """Map a user/harness supplied dialect name onto a known dialect.
834
+
835
+ Unknown names raise ValueError: silently falling back to POSIX would
836
+ classify a Windows command line with the wrong lexer, which is exactly
837
+ the failure this layer exists to prevent.
838
+ """
839
+ if not name:
840
+ return DEFAULT_DIALECT
841
+ key = str(name).strip().lower()
842
+ if key not in DIALECT_ALIASES:
843
+ raise ValueError(f"unknown command dialect: {name!r}")
844
+ return DIALECT_ALIASES[key]
845
+
846
+
847
+ def tokenize(cmd: str, dialect: str = DEFAULT_DIALECT) -> TokenStream:
848
+ """Tokenize `cmd` for `dialect`, returning an error-bearing stream."""
849
+ dialect = normalize_dialect(dialect)
850
+ try:
851
+ if dialect == DIALECT_CMD:
852
+ return tokenize_cmd(cmd)
853
+ if dialect == DIALECT_POWERSHELL:
854
+ return tokenize_powershell(cmd)
855
+ return tokenize_posix(cmd)
856
+ except TokenizeError as exc:
857
+ return TokenStream(dialect, [], error=str(exc))
858
+
859
+
860
+ def classify_dialect(cmd: str, dialect: str = DEFAULT_DIALECT) -> List[object]:
861
+ """Full dialect pipeline: tokenize then classify (facts only)."""
862
+ stream = tokenize(cmd, dialect)
863
+ if not stream.ok:
864
+ return []
865
+ if stream.dialect == DIALECT_POSIX:
866
+ from .classifier import classify_command
867
+ specs, _ = classify_command(cmd)
868
+ return specs
869
+ return classify_stream(stream)
870
+
871
+
872
+ # ---------------------------------------------------------------- detection
873
+
874
+ _CMD_HINT_RE = re.compile(
875
+ r"(?i)(^|[\s;&|(])(del|erase|rd|rmdir|copy|xcopy|robocopy|dir|attrib|"
876
+ r"where|taskkill|sc|reg|netsh|powershell|pwsh)\b|%[A-Za-z_][A-Za-z0-9_]*%")
877
+ _PS_HINT_RE = re.compile(
878
+ r"-\s?(Recurse|Force|WhatIf|LiteralPath|Filter|Include|Exclude|Confirm|"
879
+ r"ErrorAction)\b|\bRemove-Item\b|\bGet-ChildItem\b|^[A-Z][a-z]+-[A-Z]",
880
+ re.MULTILINE)
881
+
882
+
883
+ def detect_dialect(cmd: str) -> Optional[str]:
884
+ """Best-effort *hint* for a command line's dialect; None when unsure.
885
+
886
+ Deliberately conservative and never used to pick a lexer: guessing a
887
+ lexer from surface syntax is precisely the kind of inference that loses
888
+ repositories. Callers use this only to produce a better explanation,
889
+ and unknown/ambiguous input stays None (treated as POSIX by default).
890
+ """
891
+ text = (cmd or "").strip()
892
+ if not text:
893
+ return None
894
+ if _PS_HINT_RE.search(text):
895
+ return DIALECT_POWERSHELL
896
+ if _CMD_HINT_RE.search(text):
897
+ return DIALECT_CMD
898
+ return None