coretrace-python-analyzer 0.20.0__py3-none-any.whl → 0.22.0__py3-none-any.whl

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 (40) hide show
  1. coretrace_python/__init__.py +1 -1
  2. coretrace_python/bundled/dependency/reachable_vulnerability/reachable_vulnerability.py +19 -13
  3. coretrace_python/bundled/dependency/vulnerable_dependency/vulnerable_dependency.py +33 -9
  4. coretrace_python/bundled/security/command_injection/command_injection.py +1028 -3
  5. coretrace_python/bundled/security/command_injection/plugin.toml +1 -1
  6. coretrace_python/cache.py +38 -4
  7. coretrace_python/cli.py +51 -9
  8. coretrace_python/dependency/advisories.py +36 -1
  9. coretrace_python/dependency/correlation.py +151 -13
  10. coretrace_python/dependency/graph.py +71 -34
  11. coretrace_python/dependency/vex.py +5 -2
  12. coretrace_python/engine.py +38 -7
  13. coretrace_python/findings/baseline.py +268 -34
  14. coretrace_python/findings/model.py +3 -2
  15. coretrace_python/findings/suppressions.py +11 -3
  16. coretrace_python/frontend/ast_adapter.py +27 -1
  17. coretrace_python/frontend/parser.py +3 -0
  18. coretrace_python/interprocedural/__init__.py +2 -0
  19. coretrace_python/interprocedural/callgraph.py +131 -5
  20. coretrace_python/ir/lowering.py +4 -1
  21. coretrace_python/ir/model.py +8 -0
  22. coretrace_python/plugins/__init__.py +2 -1
  23. coretrace_python/plugins/detectors.py +30 -4
  24. coretrace_python/plugins/secrets.py +231 -36
  25. coretrace_python/reporters/json_format.py +14 -7
  26. coretrace_python/reporters/report.py +7 -2
  27. coretrace_python/reporters/sarif.py +19 -12
  28. coretrace_python/reporters/text.py +5 -4
  29. coretrace_python/source/__init__.py +6 -2
  30. coretrace_python/source/manager.py +16 -0
  31. coretrace_python/source/model.py +20 -0
  32. coretrace_python/source/positions.py +420 -0
  33. coretrace_python/taint/commands.py +45 -0
  34. coretrace_python/taint/models.py +10 -7
  35. {coretrace_python_analyzer-0.20.0.dist-info → coretrace_python_analyzer-0.22.0.dist-info}/METADATA +10 -1
  36. {coretrace_python_analyzer-0.20.0.dist-info → coretrace_python_analyzer-0.22.0.dist-info}/RECORD +40 -38
  37. {coretrace_python_analyzer-0.20.0.dist-info → coretrace_python_analyzer-0.22.0.dist-info}/WHEEL +0 -0
  38. {coretrace_python_analyzer-0.20.0.dist-info → coretrace_python_analyzer-0.22.0.dist-info}/entry_points.txt +0 -0
  39. {coretrace_python_analyzer-0.20.0.dist-info → coretrace_python_analyzer-0.22.0.dist-info}/licenses/LICENSE +0 -0
  40. {coretrace_python_analyzer-0.20.0.dist-info → coretrace_python_analyzer-0.22.0.dist-info}/licenses/NOTICE +0 -0
@@ -1,12 +1,399 @@
1
- """Command injection: attacker-controlled input reaching a COMMAND sink."""
1
+ """Command injection: attacker-controlled input reaching a COMMAND sink.
2
+
3
+ What decides the result is what the attacker still controls in the command a process is
4
+ started with (issue #208). A string that a shell interprets, a string naming the program,
5
+ the program itself, or an operand that the program runs as shell text (``ssh`` after the
6
+ host, a shell's first operand after ``-c``, any argument of a batch file) is a command
7
+ injection, ``high``. Operands that are a command of their own (the program a wrapper such
8
+ as ``sudo`` runs, what follows ``find -exec``) are read again as that command. The script
9
+ an interpreter runs (its first operand when no option gives the code, as ``bash run.sh`` or
10
+ ``python tool.py``), or the module ``python -m`` runs, is ``high`` to review: execution is
11
+ possible, and whether it is exploitable depends on the file the input chooses. The
12
+ arguments that follow a script or code are the script's: its own options, whose meaning is
13
+ unknown, kept for review after an option and refuted behind a constant prefix. An element
14
+ of an argument list run without a shell otherwise injects at most an option: ``medium``,
15
+ or ``high`` when ``OPTIONS`` establishes that the program runs a command chosen through an
16
+ option that fits there.
17
+
18
+ A value an option takes is judged by what ``OPTIONS`` establishes the option does with
19
+ it, whatever its prefix: run it (``cmd /c``, ``python -c``: ``high``), keep it as data
20
+ (``git commit -m``: refuted), or something not established (``medium``). After an option
21
+ ``OPTIONS`` does not describe, or an element of unknown value, the finding is kept for
22
+ review at the severity of a free element; after options established to take no value
23
+ (``rm -rf``, grouped short options read as getopt reads them), the element stands alone.
24
+ An element standing alone is judged by its constant prefix: ``f"v{x}"`` is no option, the
25
+ value of ``f"--output={x}"`` belongs to a fixed option, ``f"--{x}"`` leaves the option
26
+ open. A ``hotspot`` verdict lowers the confidence, never the severity, which each case
27
+ sets.
28
+ """
2
29
 
3
30
  from __future__ import annotations
4
31
 
32
+ import re
33
+ from collections.abc import Mapping
34
+ from dataclasses import dataclass, replace
5
35
  from typing import ClassVar
6
36
 
37
+ from coretrace_python.abstract.strings import ModuleStringsAnalysis, leading_text
38
+ from coretrace_python.analysis import AnyAnalysis
7
39
  from coretrace_python.findings import Severity
8
- from coretrace_python.plugins import TaintDetector
9
- from coretrace_python.taint import TaintKind
40
+ from coretrace_python.findings.refutation import Status, Verdict
41
+ from coretrace_python.hir import nodes
42
+ from coretrace_python.interprocedural import Arguments
43
+ from coretrace_python.ir.defuse import DefUseAnalysis
44
+ from coretrace_python.ir.model import Call, Instruction, Symbol, Value
45
+ from coretrace_python.ir.ssa import SSAAnalysis
46
+ from coretrace_python.plugins import Assessment, PluginContext, TaintDetector
47
+ from coretrace_python.semantic.symbols import SymbolId
48
+ from coretrace_python.taint import TaintAnalysis, TaintFlow, TaintKind
49
+ from coretrace_python.taint.commands import CommandPart, command_parts
50
+
51
+
52
+ @dataclass(frozen=True)
53
+ class CommandOption:
54
+ """An option of ``program``, after one of ``subcommands`` when any are given. An
55
+ option that ``takes_value`` reads it from the next element, or after ``=`` or the
56
+ short option in the same element, and ``single`` says one element can carry the option
57
+ and its value; with ``rest``, every element after it is its value, and with ``opens``
58
+ the elements after it, up to ``;`` or ``+``, are a command of their own. What the
59
+ program does with the value decides: with ``runs``, it runs a command the value
60
+ chooses (``examine``: running is possible but its exploitability is to examine, as a
61
+ choice among code already there, such as a module, or an option only some
62
+ implementations of the program run); with ``inert``, it only keeps it as data (a commit
63
+ message); with neither, the effect is not established. An option that takes no value leaves the next element
64
+ free."""
65
+
66
+ program: str
67
+ option: str
68
+ runs: str | None = None
69
+ subcommands: tuple[str, ...] = ()
70
+ single: bool = True
71
+ takes_value: bool = True
72
+ inert: str | None = None
73
+ rest: bool = False
74
+ opens: bool = False
75
+ examine: bool = False
76
+
77
+ def __post_init__(self) -> None:
78
+ if self.rest and not self.takes_value:
79
+ raise ValueError(f"{self.program} {self.option}: a rest option takes the elements after it")
80
+
81
+
82
+ @dataclass(frozen=True)
83
+ class CommandOperands:
84
+ """Operands a program runs, counted from 0 after its options, of one ``kind``: from
85
+ operand ``first`` on, shell ``text`` the program has a shell run, or a ``command`` of
86
+ its own (a program and its arguments); or operand ``first`` only, a ``script`` file
87
+ the program runs, whose contents decide what runs. With ``after``, only when one of
88
+ those options comes before the operands, and then operand ``first`` only (``sh -c
89
+ 'cmd' name arguments``); with ``unless``, only when none of them does (``python -c``
90
+ gives the code, not a script). With ``assignments``, ``NAME=VALUE`` operands before
91
+ the program set its environment and do not count (``env A=1 cmd``)."""
92
+
93
+ first: int
94
+ kind: str
95
+ how: str
96
+ after: tuple[str, ...] = ()
97
+ unless: tuple[str, ...] = ()
98
+ assignments: bool = False
99
+
100
+
101
+ def _flags(program: str, *options: str) -> tuple[CommandOption, ...]:
102
+ return tuple(CommandOption(program, option, takes_value=False) for option in options)
103
+
104
+
105
+ _SHELLS = ("sh", "bash", "dash", "zsh", "ksh")
106
+ _WRAPPERS = ("sudo", "doas", "env", "xargs", "nohup", "nice", "time")
107
+
108
+ # Documented behaviours only: an option missing here is neither established to be
109
+ # dangerous, nor inert, nor to take no value.
110
+ OPTIONS: tuple[CommandOption, ...] = (
111
+ CommandOption(
112
+ "git", "-c", "sets any configuration variable, core.sshCommand included", single=False
113
+ ),
114
+ *(
115
+ CommandOption("git", option, "runs the program it names", subcommands)
116
+ for option, subcommands in (
117
+ ("--upload-pack", ("clone", "fetch", "pull", "ls-remote")),
118
+ ("-u", ("clone", "ls-remote")),
119
+ ("--receive-pack", ("push",)),
120
+ ("--exec", ("push",)),
121
+ )
122
+ ),
123
+ *(
124
+ CommandOption(
125
+ "git", option, subcommands=(subcommand,), inert=f"is the {subcommand} message"
126
+ )
127
+ for subcommand in ("commit", "tag")
128
+ for option in ("-m", "--message")
129
+ ),
130
+ *(
131
+ CommandOption("gh", option, subcommands=(subcommand,), inert=inert)
132
+ for subcommand, options, inert in (
133
+ ("release", ("--title", "-t", "--notes", "-n"), "is text of the release"),
134
+ ("workflow", ("--ref", "-r"), "names the branch or tag of the workflow"),
135
+ )
136
+ for option in options
137
+ ),
138
+ CommandOption("ssh", "-o", "sets options such as ProxyCommand, which runs a command"),
139
+ *_flags("ssh", *(f"-{letter}" for letter in "46AaCfGgKkMNnqsTtVvXxYy")),
140
+ # GNU tar runs what these options name; bsdtar reads -I as a file of include patterns
141
+ # and rejects the others. A bare tar may be either: running is possible, its
142
+ # exploitability is to examine.
143
+ *(
144
+ CommandOption(tar, option, runs, examine=tar == "tar")
145
+ for tar in ("tar", "gtar")
146
+ for option, runs in (
147
+ ("--to-command", "pipes each extracted file to the command it names on GNU tar"),
148
+ ("--checkpoint-action", "runs the command of an exec= action on GNU tar"),
149
+ ("-I", "runs the compressor it names on GNU tar, where bsdtar reads patterns from it"),
150
+ )
151
+ ),
152
+ *(
153
+ CommandOption(tar, "--use-compress-program", "runs the compressor it names")
154
+ for tar in ("tar", "gtar", "bsdtar")
155
+ ),
156
+ CommandOption("bsdtar", "-I"),
157
+ CommandOption("rsync", "-e", "runs the remote shell it names"),
158
+ CommandOption("rsync", "--rsh", "runs the remote shell it names"),
159
+ *(
160
+ CommandOption("find", option, "runs the command that follows", single=False, opens=True)
161
+ for option in ("-exec", "-execdir", "-ok", "-okdir")
162
+ ),
163
+ *(CommandOption(shell, sign + "o", single=False) for shell in _SHELLS for sign in "-+"),
164
+ *(
165
+ option
166
+ for shell in _SHELLS
167
+ for option in _flags(shell, *(f"+{letter}" for letter in "abCefhmnuvx"))
168
+ ),
169
+ *_flags(
170
+ "bash",
171
+ "--login",
172
+ "--noediting",
173
+ "--noprofile",
174
+ "--norc",
175
+ "--posix",
176
+ "--restricted",
177
+ "--verbose",
178
+ ),
179
+ *(CommandOption("bash", option, single=False) for option in ("--rcfile", "--init-file")),
180
+ *(
181
+ option
182
+ for shell in _SHELLS
183
+ for option in _flags(shell, *(f"-{letter}" for letter in "abCcefhilmnsuvx"))
184
+ ),
185
+ CommandOption("python", "-c", "runs its value as Python code"),
186
+ CommandOption("python", "-m", "runs the module it names", examine=True),
187
+ CommandOption("python", "-W", "imports the module its warning category names", examine=True),
188
+ CommandOption("python", "-X", single=False),
189
+ *_flags("python", *(f"-{letter}" for letter in "23bBdEhiIOPqsSuvVx")),
190
+ *_flags("perl", *(f"-{letter}" for letter in "acnpsStTUwWX")),
191
+ CommandOption("perl", "-I", single=True),
192
+ *_flags("ruby", *(f"-{letter}" for letter in "acdlnpsvwWy")),
193
+ *(CommandOption("ruby", option) for option in ("-I", "-C", "-E")),
194
+ *_flags(
195
+ "node",
196
+ "-c",
197
+ "--check",
198
+ "-i",
199
+ "--interactive",
200
+ "--inspect",
201
+ "--inspect-brk",
202
+ "--no-warnings",
203
+ "--no-deprecation",
204
+ "--trace-warnings",
205
+ "--enable-source-maps",
206
+ "--expose-gc",
207
+ "--preserve-symlinks",
208
+ ),
209
+ *_flags("php", *(f"-{letter}" for letter in "aehHilmnqsvw")),
210
+ CommandOption("php", "-f", "runs the script it names", examine=True),
211
+ CommandOption("php", "-d", "sets any ini directive, auto_prepend_file included", examine=True),
212
+ CommandOption("php", "-c", "loads the php.ini it names", examine=True),
213
+ CommandOption("php", "-z", "loads the Zend extension it names", examine=True),
214
+ *(CommandOption("perl", option, "runs its value as Perl code") for option in ("-e", "-E")),
215
+ *(
216
+ CommandOption("perl", option, "runs the import of its value as Perl code")
217
+ for option in ("-M", "-m")
218
+ ),
219
+ CommandOption("ruby", "-e", "runs its value as Ruby code"),
220
+ CommandOption("ruby", "-r", "requires the library it names", examine=True),
221
+ # node reads the value of a short option from the next element only.
222
+ *(
223
+ CommandOption(
224
+ "node",
225
+ option,
226
+ "loads the module it names",
227
+ examine=True,
228
+ single=option.startswith("--"),
229
+ )
230
+ for option in ("-r", "--require", "--import")
231
+ ),
232
+ *(
233
+ CommandOption(
234
+ "node", option, "runs its value as JavaScript code", single=option.startswith("--")
235
+ )
236
+ for option in ("-e", "--eval", "-p", "--print", "-pe")
237
+ ),
238
+ *(
239
+ CommandOption("php", option, "runs its value as PHP code")
240
+ for option in ("-r", "-B", "-R", "-E")
241
+ ),
242
+ *(
243
+ CommandOption(
244
+ "cmd", option, "runs the rest of the command line as a command", single=False, rest=True
245
+ )
246
+ for option in ("/c", "/k")
247
+ ),
248
+ *(
249
+ CommandOption(
250
+ powershell,
251
+ option,
252
+ "runs the rest of the command line as a command",
253
+ single=False,
254
+ rest=True,
255
+ )
256
+ for powershell in ("powershell", "pwsh")
257
+ for option in ("-command", "-c", "-encodedcommand", "-e", "-ec")
258
+ ),
259
+ *(
260
+ option
261
+ for powershell in ("powershell", "pwsh")
262
+ for option in (
263
+ CommandOption(
264
+ powershell, "-file", "runs the script it names", single=False, examine=True
265
+ ),
266
+ *_flags(
267
+ powershell, "-noprofile", "-noninteractive", "-nologo", "-noexit", "-sta", "-mta"
268
+ ),
269
+ *(
270
+ CommandOption(powershell, value, single=False)
271
+ for value in ("-executionpolicy", "-windowstyle", "-inputformat", "-outputformat")
272
+ ),
273
+ )
274
+ ),
275
+ *_flags(
276
+ "rm",
277
+ "-d",
278
+ "-f",
279
+ "-I",
280
+ "-i",
281
+ "-R",
282
+ "-r",
283
+ "-v",
284
+ "--dir",
285
+ "--force",
286
+ "--recursive",
287
+ "--verbose",
288
+ ),
289
+ )
290
+ # Programs documented to read ``--`` as the end of their options.
291
+ END_OF_OPTIONS = frozenset({"git", "tar", "gtar", "bsdtar", "rsync", "rm"})
292
+ # Interpreters run the script their first operand names, unless one of these options
293
+ # gives the code or the script instead (or, for a shell's ``-s``, reads it from the
294
+ # standard input).
295
+ _POWERSHELL_CODE = ("-command", "-c", "-encodedcommand", "-e", "-ec", "-file")
296
+ _SCRIPTS: Mapping[str, tuple[str, ...]] = {
297
+ **{shell: ("-c", "-s") for shell in _SHELLS},
298
+ "python": ("-c", "-m"),
299
+ "perl": ("-e", "-E"),
300
+ "ruby": ("-e",),
301
+ "node": ("-e", "--eval", "-p", "--print", "-pe"),
302
+ "php": ("-r", "-f", "-B", "-R", "-E"),
303
+ "pwsh": _POWERSHELL_CODE,
304
+ }
305
+ # These read their options after the code too, up to their first operand: what follows
306
+ # ``perl -e CODE`` may be another ``-e``. Python and the shells read none after it.
307
+ _OPTIONS_AFTER_CODE = frozenset({"perl", "ruby", "node", "php"})
308
+
309
+
310
+ def _interpreter(name: str, code: tuple[str, ...]) -> tuple[CommandOperands, ...]:
311
+ script = CommandOperands(0, "script", f"names the script {name} runs", unless=code)
312
+ if name not in _SHELLS:
313
+ return (script,)
314
+ return (
315
+ CommandOperands(0, "text", "is the command the shell runs after -c", after=("-c",)),
316
+ script,
317
+ )
318
+
319
+
320
+ OPERANDS: Mapping[str, tuple[CommandOperands, ...]] = {
321
+ "ssh": (CommandOperands(1, "text", "is part of the command the remote shell runs"),),
322
+ "powershell": (
323
+ CommandOperands(0, "text", "is part of the command PowerShell runs", unless=("-file",)),
324
+ ),
325
+ "timeout": (CommandOperands(1, "command", "names the program timeout runs"),),
326
+ **{
327
+ wrapper: (
328
+ CommandOperands(
329
+ 0,
330
+ "command",
331
+ f"names the program {wrapper} runs",
332
+ assignments=wrapper in ("env", "sudo"),
333
+ ),
334
+ )
335
+ for wrapper in _WRAPPERS
336
+ },
337
+ **{interpreter: _interpreter(interpreter, code) for interpreter, code in _SCRIPTS.items()},
338
+ }
339
+ # Windows runs a batch file through cmd.exe, which parses its arguments again; its own
340
+ # programs read their options whatever the case.
341
+ _BATCH = (".bat", ".cmd")
342
+ _ANY_CASE = frozenset({"cmd", "powershell", "pwsh"})
343
+ _TERMINATORS = (";", "+")
344
+ _ASSIGNMENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*=")
345
+ _WHICH = SymbolId("python.shutil.which")
346
+ # Commands inside commands are read to this depth; deeper, an element is taken to be an
347
+ # operand the program runs.
348
+ _MAX_DEPTH = 32
349
+
350
+ _PROCESS_STARTERS = frozenset(
351
+ SymbolId(f"python.subprocess.{name}")
352
+ for name in ("run", "call", "check_call", "check_output", "Popen")
353
+ )
354
+ # ``Popen(args, bufsize, executable, ..., shell, ...)``: the other starters pass their
355
+ # positional arguments to it.
356
+ _COMMAND_ARGUMENT = frozenset({(0, None), (None, "args")})
357
+ _EXECUTABLE, _SHELL_POSITION = 2, 8
358
+ _SHELL, _NO_SHELL = frozenset({"True", "1"}), frozenset({"False", "None", "0"})
359
+ # Versioned and distribution names of interpreters: python3.12, pythonw, python3-dbg,
360
+ # pypy3, the Windows launchers py and pyw, nodejs, perl5.36, ruby3.2, php8.2.
361
+ _INTERPRETER = re.compile(r"(python|pypy|perl|ruby|php|node|py)(?:js)?[0-9.]*w?(?:-dbg)?")
362
+ _PYTHON_EXECUTABLE = SymbolId("python.sys.executable")
363
+
364
+
365
+ # What the attacker's input is in the command, when the rule establishes it (#220).
366
+ _COMMAND, _OPTION = "command", "option"
367
+ _OPTION_TITLE = "Option injection"
368
+
369
+
370
+ @dataclass(frozen=True)
371
+ class _Reading:
372
+ """What one tainted element of a command lets the attacker do: run a ``command``
373
+ (``high``), give an option at ``severity``, possibly only ``to_review``, or nothing,
374
+ with ``severity`` None. ``injection`` says what the input is there, when established:
375
+ ``command`` (it runs, or chooses what runs) or ``option`` (an option, or the value of
376
+ one the model does not establish to run it)."""
377
+
378
+ reason: str
379
+ severity: Severity | None
380
+ command: bool = False
381
+ to_review: bool = False
382
+ injection: str | None = None
383
+
384
+ @property
385
+ def kind(self) -> str | None:
386
+ return _COMMAND if self.command else self.injection
387
+
388
+
389
+ @dataclass(frozen=True)
390
+ class _Operands:
391
+ """The operands before an element, by position; whether the option before it takes
392
+ the element as its value (``consumed``); whether a ``--`` ended the options."""
393
+
394
+ positions: tuple[int, ...]
395
+ consumed: bool = False
396
+ ended: bool = False
10
397
 
11
398
 
12
399
  class CommandInjectionPlugin(TaintDetector):
@@ -15,3 +402,641 @@ class CommandInjectionPlugin(TaintDetector):
15
402
  kind: ClassVar[TaintKind] = TaintKind.COMMAND
16
403
  severity: ClassVar[Severity] = Severity.HIGH
17
404
  title: ClassVar[str] = "Command injection"
405
+ requires: ClassVar[frozenset[AnyAnalysis]] = TaintDetector.requires | {
406
+ SSAAnalysis,
407
+ DefUseAnalysis,
408
+ ModuleStringsAnalysis,
409
+ }
410
+
411
+ def assess(
412
+ self, ctx: PluginContext, function: nodes.Function, flow: TaintFlow, verdict: Verdict
413
+ ) -> Assessment:
414
+ default = super().assess(ctx, function, flow, verdict)
415
+ if flow.sink.symbol not in _PROCESS_STARTERS or flow.through is not None:
416
+ return default
417
+ arguments = flow.sink_arguments
418
+ if arguments is None or not flow.passed_as or not flow.passed_as <= _COMMAND_ARGUMENT:
419
+ return default
420
+ shell = _shell(arguments)
421
+ if shell is True:
422
+ return _of_kind(default, _COMMAND)
423
+ if shell is None:
424
+ reason = "an expression chooses whether a shell runs the command"
425
+ return Assessment(_to_review(default.verdict, reason), Severity.HIGH)
426
+ ssa = ctx.get(SSAAnalysis, function)
427
+ defs = {
428
+ i.result: i for block in ssa.blocks for i in block.instructions if i.result is not None
429
+ }
430
+ parts = command_parts(flow.argument, defs, ctx.get(DefUseAnalysis, function))
431
+ if not parts:
432
+ return default
433
+ taint = ctx.get(TaintAnalysis, function)
434
+ command = _Command(
435
+ parts, defs, ctx.get(ModuleStringsAnalysis), _program(arguments, parts[0], defs)
436
+ )
437
+ readings = [
438
+ command.read(index)
439
+ for index, part in enumerate(parts)
440
+ if flow.source in taint.taint(part.value).sources
441
+ and taint.taint(part.value).kinds & TaintKind.COMMAND
442
+ ]
443
+ if not readings:
444
+ return default
445
+ if any(reading.command for reading in readings):
446
+ return _of_kind(default, _COMMAND)
447
+ injected = [reading for reading in readings if reading.severity is not None]
448
+ if not injected:
449
+ return Assessment(
450
+ Verdict(flow, Status.REFUTED, "; ".join(r.reason for r in readings)), self.severity
451
+ )
452
+ severity = max(
453
+ (reading.severity for reading in injected if reading.severity is not None),
454
+ key=lambda found: found.rank,
455
+ )
456
+ decisive = [r for r in injected if r.severity is severity]
457
+ established = [reading for reading in decisive if not reading.to_review]
458
+ kinds = {reading.kind for reading in established or decisive}
459
+ kind = kinds.pop() if len(kinds) == 1 else None
460
+ if not established:
461
+ return _of_kind(Assessment(_to_review(default.verdict, decisive[0].reason), severity), kind)
462
+ return _of_kind(Assessment(_explained(default.verdict, established[0].reason), severity), kind)
463
+
464
+
465
+ class _Command:
466
+ """A command, read element by element; ``program`` is the name of the program it
467
+ runs, None when unknown."""
468
+
469
+ def __init__(
470
+ self,
471
+ parts: tuple[CommandPart, ...],
472
+ defs: Mapping[Value, Instruction],
473
+ strings: Mapping[str, str],
474
+ program: str | None,
475
+ depth: int = 0,
476
+ ) -> None:
477
+ self.parts = parts
478
+ self.defs = defs
479
+ self.strings = strings
480
+ self.depth = depth
481
+ name = _name(program) if program is not None else None
482
+ self.batch = name is not None and name.endswith(_BATCH)
483
+ self.program = name
484
+ # Each element's text, and the options by subcommand, are read once: ``read``
485
+ # looks back over the command for every tainted element.
486
+ self._texts: dict[int, str | None] = {}
487
+ self._options: dict[str | None, list[CommandOption]] = {}
488
+
489
+ def nested(self, start: int, end: int | None = None) -> _Command:
490
+ """The command that the elements from ``start`` (to ``end``) spell."""
491
+
492
+ parts = self.parts[start:end]
493
+ program = _first_program(parts[0], self.defs, self.strings)
494
+ return _Command(parts, self.defs, self.strings, program, self.depth + 1)
495
+
496
+ def text(self, index: int) -> str | None:
497
+ """The constant text of the element at ``index``, when all of it is constant."""
498
+
499
+ if index not in self._texts:
500
+ part = self.parts[index]
501
+ text, whole = (
502
+ leading_text(part.value, self.defs, self.strings) if part.known else ("", False)
503
+ )
504
+ self._texts[index] = text if whole else None
505
+ return self._texts[index]
506
+
507
+ def prefix(self, index: int) -> str:
508
+ part = self.parts[index]
509
+ return leading_text(part.value, self.defs, self.strings)[0] if part.known else ""
510
+
511
+ def read(self, index: int) -> _Reading:
512
+ """What the input at ``index`` lets the attacker do. Operands the program runs
513
+ come first; then an element an established option takes is judged by what the
514
+ option does with it, whatever its prefix; one standing alone, by what it can
515
+ still be: an option, or an operand only."""
516
+
517
+ if all(not earlier.known for earlier in self.parts[:index]):
518
+ return _Reading("the input may name the program", Severity.HIGH, command=True)
519
+ if self.batch:
520
+ return _Reading(
521
+ "cmd.exe parses the arguments of a batch file again", Severity.HIGH, command=True
522
+ )
523
+ operand = self.operand(index)
524
+ if operand is not None:
525
+ return operand
526
+ if self.program is None:
527
+ free = self.free(index, "the input is an element")
528
+ return self.review(
529
+ f"the program is unknown and may run its operands; {free.reason}", free, None
530
+ )
531
+ for position in range(1, index):
532
+ option = self.option(self.text(position) or "", position)
533
+ if option is not None and option.opens:
534
+ end = next(
535
+ (
536
+ later
537
+ for later in range(position + 1, len(self.parts))
538
+ if self.text(later) in _TERMINATORS
539
+ ),
540
+ len(self.parts),
541
+ )
542
+ if position < index < end:
543
+ return self.inside(position + 1, end, index)
544
+ if option is not None and option.rest:
545
+ return _Reading(
546
+ f"the input follows {self.program} {option.option}, which {option.runs}",
547
+ Severity.HIGH,
548
+ injection=_COMMAND,
549
+ )
550
+ if index >= 2:
551
+ before = self.text(index - 1)
552
+ if before is None:
553
+ free = self.free(index, "the input is a whole element")
554
+ return self.review(
555
+ f"cannot tell what the element before the input is; if not an option, {free.reason}",
556
+ free,
557
+ None,
558
+ )
559
+ if before not in ("-", "--") and self.option_like(before):
560
+ taker = self.taker(before, index)
561
+ if isinstance(taker, CommandOption):
562
+ if not self.parts[index].known and taker.runs is None:
563
+ return self.free(index, f"the input gives whole elements after {before}")
564
+ return self.value_of(taker, before)
565
+ if taker is None:
566
+ free = self.free(index, "the input is a whole element")
567
+ # Its value or an option of its own: an option either way.
568
+ return self.review(
569
+ f"cannot tell whether {before} takes the input as its value; if not, {free.reason}",
570
+ free,
571
+ _OPTION,
572
+ )
573
+ if not self.parts[index].known:
574
+ return self.free(index, "the input gives whole elements")
575
+ prefix = self.prefix(index)
576
+ for option in self.applicable(index):
577
+ if option.rest and self.same(prefix[: len(option.option)], option.option):
578
+ return _Reading(
579
+ f"the input follows {self.program} {option.option}, which {option.runs}",
580
+ Severity.HIGH,
581
+ injection=_COMMAND,
582
+ )
583
+ if prefix.startswith("--") and "=" in prefix:
584
+ return self.option_value(index, prefix[: prefix.index("=")])
585
+ if prefix.startswith("-") and len(prefix) >= 2 and prefix[1] != "-":
586
+ return self.option_value(index, prefix[:2])
587
+ if prefix.startswith("-"):
588
+ return self.free(index, f"the input completes the option {prefix!r}")
589
+ if prefix:
590
+ return _Reading(
591
+ f"the constant prefix {prefix!r} keeps the input from being an option", None
592
+ )
593
+ if any(self.text(position) == "--" for position in range(1, index)):
594
+ if self.program in END_OF_OPTIONS:
595
+ return _Reading(f"{self.program} reads the input after '--' as an operand", None)
596
+ return self.free(
597
+ index, "the input follows '--', which the program is not known to honour"
598
+ )
599
+ return self.free(index, "the input is a whole element")
600
+
601
+ def operand(self, index: int) -> _Reading | None:
602
+ """The reading of an element among the operands the program runs, or None when
603
+ the element is not one of them."""
604
+
605
+ for spec in OPERANDS.get(self.program or "", ()):
606
+ reading = self.operand_of(spec, index)
607
+ if reading is not None:
608
+ return reading
609
+ return None
610
+
611
+ def operand_of(self, spec: CommandOperands, index: int) -> _Reading | None:
612
+ script = spec.kind == "script"
613
+ unclear = _Reading(
614
+ f"the input may be an operand that {spec.how}",
615
+ Severity.HIGH,
616
+ command=not script,
617
+ to_review=script,
618
+ )
619
+ if spec.after:
620
+ given = self.given(spec.after, index)
621
+ if given is None:
622
+ return unclear
623
+ if given is False:
624
+ return None
625
+ if spec.unless:
626
+ given = self.given(spec.unless, index)
627
+ if given is None:
628
+ return unclear
629
+ if given is not False:
630
+ return self.after_code(given, index)
631
+ operands = self.operands(index, spec.first + 1, spec.assignments)
632
+ if operands is None:
633
+ return unclear
634
+ if operands.consumed:
635
+ return None
636
+ count = len(operands.positions)
637
+ operand_like = operands.ended or not self.prefix(index).startswith("-")
638
+ if count > spec.first:
639
+ if spec.kind == "command":
640
+ return self.inside(operands.positions[spec.first], None, index)
641
+ if spec.kind == "text" and not spec.after:
642
+ return _Reading(f"the input {spec.how}", Severity.HIGH, command=True)
643
+ return self.argument(operands.positions[spec.first] + 1, index)
644
+ if count == spec.first and operand_like:
645
+ if not script:
646
+ return _Reading(f"the input {spec.how}", Severity.HIGH, command=True)
647
+ if not operands.ended and self.prefix(index) == "":
648
+ # A whole element there may as well be a code option and its value.
649
+ free = self.free(index, "the input is a whole element")
650
+ if free.severity is Severity.HIGH:
651
+ return free
652
+ return _Reading(
653
+ f"the input {spec.how}, whose contents decide what runs",
654
+ Severity.HIGH,
655
+ to_review=True,
656
+ )
657
+ return None
658
+
659
+ def argument(self, start: int, index: int) -> _Reading:
660
+ """An argument of a script or of code given by an option, the arguments starting at
661
+ ``start``, which the engine does not read: an option of it, whose meaning is
662
+ unknown, unless a constant prefix keeps it from being one."""
663
+
664
+ before = self.text(index - 1) if index > start else None
665
+ if (
666
+ before is not None
667
+ and before.startswith("-")
668
+ and before not in ("-", "--")
669
+ and "=" not in before
670
+ ):
671
+ return _Reading(
672
+ f"the input follows {before}, an option of the script it may be the value of",
673
+ Severity.MEDIUM,
674
+ to_review=True,
675
+ injection=_OPTION,
676
+ )
677
+ prefix = self.prefix(index)
678
+ if self.parts[index].known and prefix and not prefix.startswith("-"):
679
+ return _Reading(
680
+ f"the input is an argument of the script, behind the constant prefix {prefix!r}",
681
+ None,
682
+ )
683
+ return _Reading(
684
+ "the input is an argument of the script, which it may read as an option",
685
+ Severity.MEDIUM,
686
+ injection=_OPTION,
687
+ )
688
+
689
+ def inside(self, start: int, end: int | None, index: int) -> _Reading:
690
+ """The reading of the element at ``index`` in the command the elements from
691
+ ``start`` (to ``end``) spell, which the program runs."""
692
+
693
+ if index == start:
694
+ return _Reading(
695
+ f"the input names the program {self.program} runs", Severity.HIGH, command=True
696
+ )
697
+ if self.depth >= _MAX_DEPTH:
698
+ return _Reading(
699
+ f"the input is in a command {self.program} runs", Severity.HIGH, command=True
700
+ )
701
+ reading = self.nested(start, end).read(index - start)
702
+ return _Reading(
703
+ f"in the command {self.program} runs, {reading.reason}",
704
+ reading.severity,
705
+ reading.command,
706
+ reading.to_review,
707
+ reading.injection,
708
+ )
709
+
710
+ def operands(self, index: int, enough: int, assignments: bool = False) -> _Operands | None:
711
+ """The operands before ``index``, up to ``enough`` of them, without ``NAME=VALUE``
712
+ assignments when the program reads them; None when an element of unknown value, or
713
+ an option that may take one, comes first."""
714
+
715
+ positions: list[int] = []
716
+ position = 1
717
+ while position < index and len(positions) < enough:
718
+ text = self.text(position)
719
+ if text is None:
720
+ return None
721
+ if text == "--" or (text == "-" and self.program in _SHELLS):
722
+ return _Operands((*positions, *range(position + 1, index))[:enough], ended=True)
723
+ if self.option_like(text) and text != "-":
724
+ if not (text.startswith("--") and "=" in text):
725
+ taker = self.taker(text, position + 1)
726
+ if taker is None:
727
+ return None
728
+ if isinstance(taker, CommandOption):
729
+ position += 1
730
+ if position == index:
731
+ return _Operands(tuple(positions), consumed=True)
732
+ elif not (assignments and _ASSIGNMENT.match(text)):
733
+ positions.append(position)
734
+ position += 1
735
+ return _Operands(tuple(positions))
736
+
737
+ def given(self, names: tuple[str, ...], index: int) -> int | bool | None:
738
+ """Where one of the options ``names`` ends among the options before ``index``: the
739
+ position of the element holding its value, or of the option itself when it takes
740
+ none; False when none comes, None when an element of unknown value, or an option
741
+ that may take one, comes first. Options are read as getopt reads them: a short
742
+ option that takes a value takes the rest of its element."""
743
+
744
+ position = 1
745
+ while position < index:
746
+ text = self.text(position)
747
+ if text is None:
748
+ return None
749
+ if text == "--" or text in ("-", "+") or not self.option_like(text):
750
+ return False
751
+ whole = text.split("=", 1)[0]
752
+ if self.named(whole, names):
753
+ option = self.option(text, position + 1)
754
+ return (
755
+ position + 1
756
+ if "=" not in text and option is not None and option.takes_value
757
+ else position
758
+ )
759
+ grouped = text[0] in "-+" and not text.startswith("--") and len(text) > 2
760
+ if grouped and self.option(whole, position + 1) is None:
761
+ for offset, letter in enumerate(text[1:], start=1):
762
+ option = self.option(text[0] + letter, position + 1)
763
+ last = offset == len(text) - 1
764
+ if self.named(text[0] + letter, names):
765
+ return (
766
+ position + 1
767
+ if last and option is not None and option.takes_value
768
+ else position
769
+ )
770
+ if option is None:
771
+ return None
772
+ if option.takes_value:
773
+ position += last
774
+ break
775
+ elif not (text.startswith("--") and "=" in text):
776
+ taker = self.taker(text, position + 1)
777
+ if taker is None:
778
+ return None
779
+ position += isinstance(taker, CommandOption)
780
+ position += 1
781
+ return False
782
+
783
+ def after_code(self, given: int, index: int) -> _Reading | None:
784
+ """The reading of the element at ``index``, once the option ending at ``given`` gave
785
+ the code: an argument of it, except that the interpreters of
786
+ ``_OPTIONS_AFTER_CODE`` read options up to their first operand, which the usual
787
+ reading of options judges (None)."""
788
+
789
+ if index <= given:
790
+ return None
791
+ # Not ``given`` itself: it holds the value of the code option (the script after
792
+ # ``pwsh -File``, whatever it is spelled like), or that option when it takes no
793
+ # value, which is then no ``rest`` option, since every element after one is its value.
794
+ for position in range(1, given):
795
+ option = self.option(self.text(position) or "", position)
796
+ if option is not None and option.rest:
797
+ # Every element after it is the command (``pwsh -Command``).
798
+ return None
799
+ if self.program not in _OPTIONS_AFTER_CODE:
800
+ return self.argument(given + 1, index)
801
+ operands = self.operands(index, 1)
802
+ if operands is None or operands.consumed:
803
+ return None
804
+ if operands.positions:
805
+ return self.argument(operands.positions[0], index)
806
+ prefix = self.prefix(index)
807
+ if operands.ended or (prefix and not prefix.startswith("-")):
808
+ return self.argument(index, index)
809
+ if prefix.startswith("-"):
810
+ return None
811
+ return self.free(index, "the input is a whole element where options are still read")
812
+
813
+ def named(self, written: str, names: tuple[str, ...]) -> bool:
814
+ return any(self.same(written, name) for name in names)
815
+
816
+ def review(self, reason: str, free: _Reading, injection: str | None) -> _Reading:
817
+ return _Reading(reason, free.severity, to_review=True, injection=injection)
818
+
819
+ def same(self, written: str, option: str) -> bool:
820
+ return written.lower() == option.lower() if self.program in _ANY_CASE else written == option
821
+
822
+ def option_like(self, text: str) -> bool:
823
+ """Whether ``text`` reads as an option of the program: ``-x``, a shell's ``+x``, or
824
+ an option the model names (``/c``)."""
825
+
826
+ if text.startswith("-") or (
827
+ self.program in _SHELLS and text.startswith("+") and text != "+"
828
+ ):
829
+ return True
830
+ return any(
831
+ self.same(text, option.option) for option in OPTIONS if option.program == self.program
832
+ )
833
+
834
+ def free(self, index: int, how: str) -> _Reading:
835
+ """An element the attacker may give as an option: ``high`` when an established
836
+ option of the program fits in one element there."""
837
+
838
+ dangerous = [
839
+ option for option in self.applicable(index) if option.runs is not None and option.single
840
+ ]
841
+ if dangerous:
842
+ option = min(dangerous, key=lambda found: found.examine)
843
+ return _Reading(
844
+ f"{how}, and an option such as {self.program} {_spelled(option.option)} {option.runs}",
845
+ Severity.HIGH,
846
+ injection=_OPTION,
847
+ )
848
+ return _Reading(f"{how}, so it may be read as an option", Severity.MEDIUM, injection=_OPTION)
849
+
850
+ def option_value(self, index: int, name: str) -> _Reading:
851
+ """The element starts with the option ``name`` and goes on with the input."""
852
+
853
+ option = self.option(name, index)
854
+ if option is None:
855
+ return _Reading(
856
+ f"the input is the value of the option {name}", Severity.MEDIUM, injection=_OPTION
857
+ )
858
+ if not option.takes_value:
859
+ return self.free(
860
+ index, f"the input follows {name}, which takes no value, as more options"
861
+ )
862
+ return self.value_of(option, name)
863
+
864
+ def value_of(self, option: CommandOption, given: str) -> _Reading:
865
+ if option.runs is not None and option.examine:
866
+ return _Reading(
867
+ f"the input is the value of {self.program} {given}, which {option.runs}",
868
+ Severity.HIGH,
869
+ to_review=True,
870
+ )
871
+ if option.runs is not None:
872
+ return _Reading(
873
+ f"the input is the value of {self.program} {given}, which {option.runs}",
874
+ Severity.HIGH,
875
+ injection=_COMMAND,
876
+ )
877
+ if option.inert is not None:
878
+ return _Reading(
879
+ f"the input is the value of {self.program} {given}, which {option.inert}", None
880
+ )
881
+ return _Reading(
882
+ f"the input is the value of {self.program} {given}", Severity.MEDIUM, injection=_OPTION
883
+ )
884
+
885
+ def taker(self, before: str, index: int) -> CommandOption | bool | None:
886
+ """The option ``before`` whose value is the element at ``index``; False when the
887
+ model establishes that ``before`` takes no value there, None when it cannot tell.
888
+ Short options grouped in one element (``-rf``) are read as getopt reads them: the
889
+ first that takes a value takes the rest of the element, or the next element."""
890
+
891
+ option = self.option(before, index)
892
+ if option is not None:
893
+ return option if option.takes_value else False
894
+ sign = before[:1]
895
+ if sign not in ("-", "+") or before.startswith("--") or len(before) <= 2:
896
+ return None
897
+ letters = before[1:]
898
+ for position, letter in enumerate(letters):
899
+ option = self.option(f"{sign}{letter}", index)
900
+ if option is None:
901
+ return None
902
+ if option.takes_value:
903
+ return option if position == len(letters) - 1 else False
904
+ return False
905
+
906
+ def option(self, name: str, index: int) -> CommandOption | None:
907
+ return next(
908
+ (option for option in self.applicable(index) if self.same(name, option.option)), None
909
+ )
910
+
911
+ def applicable(self, index: int) -> list[CommandOption]:
912
+ """The options of ``OPTIONS`` the element at ``index`` may give: those of the
913
+ program, after their subcommand when the command shows it before the element. When
914
+ the command does not tell, options that run a command still apply, whatever their
915
+ subcommand, but not an inert reading, which needs the subcommand established."""
916
+
917
+ if self.program is None:
918
+ return []
919
+ subcommand = self.subcommand(index)
920
+ if subcommand not in self._options:
921
+ self._options[subcommand] = [
922
+ option
923
+ for option in OPTIONS
924
+ if option.program == self.program
925
+ and (
926
+ not option.subcommands
927
+ or (subcommand is None and option.inert is None)
928
+ or subcommand in option.subcommands
929
+ )
930
+ ]
931
+ return self._options[subcommand]
932
+
933
+ def subcommand(self, index: int) -> str | None:
934
+ """The first operand before ``index``, ``""`` when there is none, or None when an
935
+ element of unknown value, or an option that may take one, comes first."""
936
+
937
+ for position in range(1, index):
938
+ text = self.text(position)
939
+ if text is None or text.startswith("-"):
940
+ return None
941
+ return text
942
+ return ""
943
+
944
+
945
+ def _name(program: str) -> str:
946
+ """The name a program is known by in ``OPTIONS``: without its directory (POSIX or
947
+ Windows) or ``.exe``, in lower case, an interpreter without its version (``pypy`` and
948
+ the Windows launcher ``py`` as ``python``)."""
949
+
950
+ name = re.split(r"[\\/]", program)[-1].lower().removesuffix(".exe")
951
+ interpreter = _INTERPRETER.fullmatch(name)
952
+ if interpreter is not None:
953
+ name = interpreter.group(1)
954
+ return "python" if name in ("pypy", "py") else name
955
+
956
+
957
+ def _first_program(
958
+ part: CommandPart, defs: Mapping[Value, Instruction], strings: Mapping[str, str]
959
+ ) -> str | None:
960
+ """The program the first element of a command names: its constant text, Python for
961
+ ``sys.executable``, or the name ``shutil.which`` looks up; None when unknown."""
962
+
963
+ if not part.known:
964
+ return None
965
+ text, whole = leading_text(part.value, defs, strings)
966
+ if whole:
967
+ return text
968
+ made = defs.get(part.value)
969
+ if isinstance(made, Symbol) and made.symbol_id == _PYTHON_EXECUTABLE:
970
+ return "python"
971
+ if isinstance(made, Call) and made.arguments:
972
+ callee = defs.get(made.callee)
973
+ if isinstance(callee, Symbol) and callee.symbol_id == _WHICH:
974
+ name, whole = leading_text(made.arguments[0], defs, strings)
975
+ return name if whole else None
976
+ return None
977
+
978
+
979
+ def _program(
980
+ arguments: Arguments, first: CommandPart, defs: Mapping[Value, Instruction]
981
+ ) -> str | None:
982
+ """The program a call runs: the one a constant ``executable`` names, which the
983
+ command's first element then only labels, or the one that element names. An
984
+ ``executable`` that is given but cannot be read leaves the program unknown."""
985
+
986
+ given = arguments.given("executable", _EXECUTABLE)
987
+ if given == (False, None):
988
+ return _first_program(first, defs, {})
989
+ written = given[1] if given is not None else None
990
+ if written == str(_PYTHON_EXECUTABLE):
991
+ return "python"
992
+ if written is None or len(written) < 2 or written[0] not in "'\"" or written[-1] != written[0]:
993
+ return None
994
+ return written[1:-1].replace("\\\\", "\\")
995
+
996
+
997
+ def _spelled(option: str) -> str:
998
+ """An option with its value in the same element: ``--name=...`` or ``-o...``."""
999
+
1000
+ return f"{option}=..." if option.startswith("--") else f"{option}..."
1001
+
1002
+
1003
+ def _shell(arguments: Arguments) -> bool | None:
1004
+ """Whether a shell runs the command: True or False when the call says so with a
1005
+ constant, by keyword or at its place, None when an expression or unpacked arguments
1006
+ decide."""
1007
+
1008
+ given = arguments.given("shell", _SHELL_POSITION)
1009
+ if given is None:
1010
+ return None
1011
+ present, value = given
1012
+ if not present:
1013
+ return False
1014
+ if value in _SHELL:
1015
+ return True
1016
+ return False if value in _NO_SHELL else None
1017
+
1018
+
1019
+ def _of_kind(assessment: Assessment, kind: str | None) -> Assessment:
1020
+ """``assessment`` saying what kind of injection it is, when established: an option
1021
+ injection is titled so; the rule id stays ``command-injection`` either way."""
1022
+
1023
+ if kind is None:
1024
+ return assessment
1025
+ return replace(
1026
+ assessment,
1027
+ title=_OPTION_TITLE if kind == _OPTION else None,
1028
+ metadata={**assessment.metadata, "injection": kind},
1029
+ )
1030
+
1031
+
1032
+ def _explained(verdict: Verdict, reason: str) -> Verdict:
1033
+ """``verdict`` with what the command lets the attacker do added to its evidence."""
1034
+
1035
+ return Verdict(verdict.flow, verdict.status, f"{verdict.evidence}; {reason}")
1036
+
1037
+
1038
+ def _to_review(verdict: Verdict, reason: str) -> Verdict:
1039
+ """A finding kept for review: a hotspot whose evidence says why, at most."""
1040
+
1041
+ status = Status.HOTSPOT if verdict.status is Status.VULNERABILITY else verdict.status
1042
+ return Verdict(verdict.flow, status, f"{verdict.evidence}; {reason}")