@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.
- package/CONTRIBUTING.md +101 -0
- package/LICENSE +21 -0
- package/README.md +558 -0
- package/README.zh-CN.md +488 -0
- package/adapters/INTEGRATION.md +94 -0
- package/adapters/claude/README.md +141 -0
- package/adapters/claude/compatibility.json +17 -0
- package/adapters/claude/harness/README.md +59 -0
- package/adapters/claude/harness/mock_anthropic_api.mjs +47 -0
- package/adapters/claude/harness/run_scenario.sh +79 -0
- package/adapters/claude/harness/run_scenario_no_python3.sh +49 -0
- package/adapters/claude/hook_bridge.sh +33 -0
- package/adapters/claude/pre_tool_use.py +264 -0
- package/adapters/claude/settings.example.json +16 -0
- package/adapters/codex/harness/README.md +53 -0
- package/adapters/codex/harness/acceptance.py +226 -0
- package/adapters/dsh/README.md +62 -0
- package/adapters/dsh/cordis.patch.yml +30 -0
- package/adapters/dsh/lib/index.js +500 -0
- package/adapters/kimi-code/README.md +169 -0
- package/adapters/kimi-code/compatibility.json +17 -0
- package/adapters/kimi-code/config.example.toml +26 -0
- package/adapters/kimi-code/hook_bridge.sh +32 -0
- package/adapters/kimi-code/pre_tool_use.py +72 -0
- package/core/__init__.py +47 -0
- package/core/audit.py +86 -0
- package/core/classifier.py +1175 -0
- package/core/dialects.py +898 -0
- package/core/policy.py +817 -0
- package/core/recovery.py +700 -0
- package/core/redaction.py +1096 -0
- package/core/safe_view.py +212 -0
- package/docs/architecture.md +223 -0
- package/docs/compatibility.md +142 -0
- package/docs/development-note-unguarded-deletion.md +187 -0
- package/docs/friction.md +266 -0
- package/docs/harness-capabilities.md +72 -0
- package/docs/host-drift.md +142 -0
- package/docs/publishing-from-ephemeral-environments.md +104 -0
- package/docs/release-notes-0.2.0-rc1.md +46 -0
- package/docs/release-notes-0.2.0.md +72 -0
- package/docs/release-notes-0.2.1.md +78 -0
- package/docs/release-notes-0.2.2.md +120 -0
- package/docs/secret-guard-analysis.md +416 -0
- package/docs/secret-guard-architecture.md +93 -0
- package/docs/secret-guard-design.md +649 -0
- package/docs/test-report-claude-code-harness.md +462 -0
- package/docs/test-report-codex-gpt-5.6-sol.md +335 -0
- package/docs/test-report-codex-gpt-6-astra-high.md +129 -0
- package/docs/test-report-dsh-0.1.5-rc.1.md +84 -0
- package/docs/test-report-dsh-v0.1.1.md +126 -0
- package/docs/test-report-kimi-code-block.md +198 -0
- package/docs/test-report-zcode-glm-flash.md +241 -0
- package/docs/threat-model.md +44 -0
- package/doctor.py +756 -0
- package/live_sentinel.py +339 -0
- package/package.json +69 -0
- package/skills/delete-guard/SKILL.md +109 -0
- package/skills/delete-guard/agents/openai.yaml +4 -0
- package/skills/delete-guard/references/policy.md +161 -0
- package/skills/delete-guard/scripts/_bootstrap.py +8 -0
- package/skills/delete-guard/scripts/check.py +370 -0
- package/skills/delete-guard/scripts/gc.py +103 -0
- package/skills/delete-guard/scripts/restore.py +98 -0
- package/skills/delete-guard/scripts/safe_delete.py +256 -0
- package/skills/delete-guard/scripts/status.py +130 -0
- package/skills/exfil-guard/SKILL.md +143 -0
- package/skills/exfil-guard/agents/openai.yaml +4 -0
- package/skills/exfil-guard/references/channels.md +58 -0
- package/skills/exfil-guard/references/rules.md +194 -0
- package/skills/exfil-guard/scripts/_bootstrap.py +8 -0
- package/skills/exfil-guard/scripts/check_span.py +250 -0
- package/skills/exfil-guard/scripts/sanitize.py +155 -0
- package/skills/exfil-guard/scripts/view.py +44 -0
- package/skills/recovery-audit/SKILL.md +283 -0
- package/skills/recovery-audit/agents/openai.yaml +4 -0
- package/skills/recovery-audit/references/evidence-records.md +85 -0
package/core/dialects.py
ADDED
|
@@ -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
|