Module refinery.units.scripting.cmdarg
Expand source code Browse git
from __future__ import annotations
import base64
import codecs
import io
import ntpath
import re
from typing import NamedTuple
from refinery.lib.scripts.bat import BatchParser, BatchState
from refinery.lib.scripts.bat.model import (
AstCommand,
AstPipeline,
AstSequence,
EmulatorException,
MissingVariable,
)
from refinery.lib.scripts.bat.util import cmd_unquote, parse_start_arguments, split_arguments
from refinery.units import Unit
def _split_argv(cmdline: str) -> list[str]:
"""
Split a command line into argv using MSVC CRT rules.
The algorithm follows the MSVC C runtime documentation:
- Whitespace outside quotes separates arguments.
- A double quote toggles quote state.
- Backslashes are literal unless immediately preceding a double quote.
- 2N backslashes before a quote produce N backslashes and the quote toggles state.
- 2N+1 backslashes before a quote produce N backslashes and a literal quote.
"""
args: list[str] = []
buf = io.StringIO()
i = 0
n = len(cmdline)
quoted = False
while i < n:
c = cmdline[i]
if c == '\\':
bs = 0
while i < n and cmdline[i] == '\\':
bs += 1
i += 1
if i < n and cmdline[i] == '"':
buf.write('\\' * (bs // 2))
if bs % 2 == 1:
buf.write('"')
else:
quoted = not quoted
i += 1
else:
buf.write('\\' * bs)
elif c == '"':
quoted = not quoted
i += 1
elif c in (' ', '\t') and not quoted:
if b := buf.getvalue():
args.append(b)
buf.seek(0)
buf.truncate(0)
i += 1
else:
buf.write(c)
i += 1
if b := buf.getvalue():
args.append(b)
return args
def _split_program(cmdline: str) -> tuple[str, str]:
"""
Split a command line into the name of the program and the text of its arguments. As when
Windows locates the program, a name that opens with a double quote ends at the next double
quote, and any other name ends at the first whitespace.
"""
if cmdline.startswith('"'):
program, _, arguments = cmdline[1:].partition('"')
return program, arguments.lstrip()
program, *arguments = cmdline.split(None, 1)
return program, ''.join(arguments)
class _UndefinedVariables(BatchState):
"""
A command line state in which no variable is defined, so that parsing applies the syntax of
cmd but leaves every variable reference as written.
"""
def envar(self, name: str, default: str | None = None):
if default is None:
raise MissingVariable
return default
def _command_as_run(command: str) -> str | None:
"""
The command line that cmd hands to the program when it runs the given text: its escapes are
removed and variable references stay as written. The result is `None` unless the text is one
command, rather than several commands, a pipeline, a block, a control statement, or a command
with redirected streams.
"""
try:
statements = list(BatchParser(command, _UndefinedVariables(cmdline=True)).parse(0))
except EmulatorException:
return None
if len(statements) != 1:
return None
if not isinstance(sequence := statements[0], AstSequence) or sequence.tail:
return None
if not isinstance(pipeline := sequence.head, AstPipeline) or len(pipeline.parts) != 1:
return None
if not isinstance(part := pipeline.parts[0], AstCommand) or part.redirects:
return None
return ''.join(part.fragments)
class _Layer(NamedTuple):
payload: str
final: bool = False
_PS_EXECUTABLE_NAMES = frozenset({
'powershell',
'powershell.exe',
'pwsh',
'pwsh.exe',
})
_WMIC_EXECUTABLE_NAMES = frozenset({
'wmic',
'wmic.exe',
})
_CMD_EXECUTABLE_NAMES = frozenset({
'%comspec%',
'cmd',
'cmd.exe',
})
_START_EXECUTABLE_NAMES = frozenset({
'start',
})
_PARAM_WITH_NEXT_ARG = {
'executionpolicy',
'ep',
'windowstyle',
'configurationname',
'custompipename',
'settingsfile',
'workingdirectory',
'encodedarguments',
'encodedargument',
'outputformat',
'inputformat',
}
_KNOWN_SWITCHES = {
'command' : 'c',
'encodedcommand' : 'e',
'file' : 'f',
'executionpolicy' : 'ex',
'ep' : 'ep',
'windowstyle' : 'w',
'noprofile' : 'nop',
'noninteractive' : 'noni',
'nologo' : 'nol',
'noexit' : 'noe',
'sta' : 's',
'mta' : 'm',
'outputformat' : 'o',
'inputformat' : 'inp',
'configurationname' : 'con',
'custompipename' : 'cu',
'settingsfile' : 'se',
'workingdirectory' : 'wo',
'encodedarguments' : 'encodeda',
'encodedargument' : 'encodeda',
'version' : 'v',
'login' : 'l',
'help' : 'h',
}
def _match_switch(key: str) -> str | None:
"""
Match a PowerShell command-line switch using prefix matching. Strips the leading dash or
slash, then does a case-insensitive prefix match against known parameters, respecting the
minimum unique prefix length.
"""
key = key.lstrip('-/')
if key.startswith('-'):
key = key[1:]
key = key.lower()
if not key:
return None
for param, min_prefix in _KNOWN_SWITCHES.items():
if param.startswith(key) and len(key) >= len(min_prefix):
return param
return None
def _executable_name(program: str) -> str:
return ntpath.basename(program.strip("'")).lower()
def _strip_outer_quotes(text: str) -> str:
text = text.strip()
if len(text) < 2 or text[0] != '"':
return text
k = len(text) - 1
if text[k] != '"':
return text
bs = 0
j = k - 1
while j >= 0 and text[j] == '\\':
bs += 1
j -= 1
if bs % 2 == 0:
return text[1:k]
return text
_RE_WMIC_CREATE = re.compile(r"""(?ix)
(?:/\S+\s+)*
(?:(?P<quote1>["']?) path (?P=quote1)\s+)?
(?P<quote2>["']?) process (?P=quote2)\s+
(?P<quote3>["']?) call (?P=quote3)\s+
(?P<quote4>["']?) create (?P=quote4)\s*
""")
_RE_CMD_RUN = re.compile(r"""(?ix)
(?P<switches>(?:/[a-z](?::\w+)?\s*)*?)
/[ck](?=[\s"])\s*
""")
class cmdarg(Unit):
"""
Extracts and unescapes arguments passed to wmic, cmd, start, or powershell commands.
The following types of command invocations are currently supported:
- `wmic process call create "COMMAND"`
- `cmd /c "COMMAND"`
- `cmd /k "COMMAND"`
- `start [/b] [/min] [/max] [/wait] COMMAND`
- `powershell -EncodedCommand COMMAND`
- `powershell -Command COMMAND`
The program may be given by its full path, also in quotes. Layers are peeled until the
innermost recognizable payload is reached. This is useful for extracting PowerShell code from
obfuscated batch files and WMI-based launchers. The command that cmd runs has its escapes
removed, while variable references are left as written. When that command is a batch script
with more than one command, the script is the output; it can be emulated with `refinery.bat`.
"""
def process(self, data: bytearray):
text = codecs.decode(data, self.codec, errors='surrogateescape')
final = False
for _ in range(10):
if not (text := text.strip()):
raise ValueError('empty command line')
if final or (layer := self._dispatch(text)) is None:
return codecs.encode(text, self.codec, errors='surrogateescape')
text, final = layer
self.log_info(F'unwrapped a layer, continuing with: {text}', clip=True)
raise ValueError('command chain exceeds maximum nesting depth')
def _dispatch(self, text: str) -> _Layer | None:
program, arguments = _split_program(text)
name = _executable_name(program)
if name in _PS_EXECUTABLE_NAMES:
return _Layer(self._extract_powershell(_split_argv(arguments)))
if name in _WMIC_EXECUTABLE_NAMES:
return _Layer(self._extract_wmic(arguments))
if name in _CMD_EXECUTABLE_NAMES:
return self._extract_cmd(arguments)
if name in _START_EXECUTABLE_NAMES:
return _Layer(self._extract_start(arguments))
if program.startswith(('-', '/')):
return _Layer(self._extract_powershell(_split_argv(text)))
return None
def _extract_powershell(self, argv: list[str]) -> str:
i = 0
command_args: list[str] = []
while i < len(argv):
arg = argv[i]
if command_args or not arg.startswith(('-', '/')):
command_args.append(arg)
i += 1
continue
switch = _match_switch(arg)
self.log_info(switch)
if switch == 'command':
return ' '.join(argv[i + 1:])
if switch == 'encodedcommand':
i += 1
if i >= len(argv):
raise ValueError('-EncodedCommand requires an argument')
blob = argv[i]
blob += '=' * (-len(blob) % 4)
raw = base64.b64decode(blob)
return codecs.decode(raw, 'utf-16-le')
if switch == 'file':
raise ValueError(
'-File parameter found; code is in a file, not in the command line')
if switch is not None and switch in _PARAM_WITH_NEXT_ARG:
i += 2
continue
if switch is not None:
i += 1
continue
command_args.append(arg)
i += 1
if command_args:
return ' '.join(command_args)
raise ValueError('no PowerShell code found in command line')
def _extract_wmic(self, arguments: str) -> str:
if not (match := _RE_WMIC_CREATE.match(arguments)):
raise ValueError('not a recognized WMIC process create command')
return _strip_outer_quotes(arguments[match.end():])
def _extract_cmd(self, arguments: str) -> _Layer:
if not (match := _RE_CMD_RUN.match(arguments)):
raise ValueError('CMD command line missing /c or /k switch')
strip = re.search(r'(?i)/s\b', match['switches']) is not None
executable = BatchState(cmdline=True).names_executable
command = cmd_unquote(arguments[match.end():], strip, executable)
if (run := _command_as_run(command)) is None:
return _Layer(command, final=True)
return _Layer(run)
def _extract_start(self, arguments: str) -> str:
pieces = split_arguments(arguments)
if (start := parse_start_arguments(pieces)) is None:
raise ValueError('no command found after start')
return ''.join(pieces[start.program:])
Classes
class cmdarg-
Extracts and unescapes arguments passed to wmic, cmd, start, or powershell commands.
The following types of command invocations are currently supported:
wmic process call create "COMMAND"cmd /c "COMMAND"cmd /k "COMMAND"start [/b] [/min] [/max] [/wait] COMMANDpowershell -EncodedCommand COMMANDpowershell -Command COMMAND
The program may be given by its full path, also in quotes. Layers are peeled until the innermost recognizable payload is reached. This is useful for extracting PowerShell code from obfuscated batch files and WMI-based launchers. The command that cmd runs has its escapes removed, while variable references are left as written. When that command is a batch script with more than one command, the script is the output; it can be emulated with
bat.Expand source code Browse git
class cmdarg(Unit): """ Extracts and unescapes arguments passed to wmic, cmd, start, or powershell commands. The following types of command invocations are currently supported: - `wmic process call create "COMMAND"` - `cmd /c "COMMAND"` - `cmd /k "COMMAND"` - `start [/b] [/min] [/max] [/wait] COMMAND` - `powershell -EncodedCommand COMMAND` - `powershell -Command COMMAND` The program may be given by its full path, also in quotes. Layers are peeled until the innermost recognizable payload is reached. This is useful for extracting PowerShell code from obfuscated batch files and WMI-based launchers. The command that cmd runs has its escapes removed, while variable references are left as written. When that command is a batch script with more than one command, the script is the output; it can be emulated with `refinery.bat`. """ def process(self, data: bytearray): text = codecs.decode(data, self.codec, errors='surrogateescape') final = False for _ in range(10): if not (text := text.strip()): raise ValueError('empty command line') if final or (layer := self._dispatch(text)) is None: return codecs.encode(text, self.codec, errors='surrogateescape') text, final = layer self.log_info(F'unwrapped a layer, continuing with: {text}', clip=True) raise ValueError('command chain exceeds maximum nesting depth') def _dispatch(self, text: str) -> _Layer | None: program, arguments = _split_program(text) name = _executable_name(program) if name in _PS_EXECUTABLE_NAMES: return _Layer(self._extract_powershell(_split_argv(arguments))) if name in _WMIC_EXECUTABLE_NAMES: return _Layer(self._extract_wmic(arguments)) if name in _CMD_EXECUTABLE_NAMES: return self._extract_cmd(arguments) if name in _START_EXECUTABLE_NAMES: return _Layer(self._extract_start(arguments)) if program.startswith(('-', '/')): return _Layer(self._extract_powershell(_split_argv(text))) return None def _extract_powershell(self, argv: list[str]) -> str: i = 0 command_args: list[str] = [] while i < len(argv): arg = argv[i] if command_args or not arg.startswith(('-', '/')): command_args.append(arg) i += 1 continue switch = _match_switch(arg) self.log_info(switch) if switch == 'command': return ' '.join(argv[i + 1:]) if switch == 'encodedcommand': i += 1 if i >= len(argv): raise ValueError('-EncodedCommand requires an argument') blob = argv[i] blob += '=' * (-len(blob) % 4) raw = base64.b64decode(blob) return codecs.decode(raw, 'utf-16-le') if switch == 'file': raise ValueError( '-File parameter found; code is in a file, not in the command line') if switch is not None and switch in _PARAM_WITH_NEXT_ARG: i += 2 continue if switch is not None: i += 1 continue command_args.append(arg) i += 1 if command_args: return ' '.join(command_args) raise ValueError('no PowerShell code found in command line') def _extract_wmic(self, arguments: str) -> str: if not (match := _RE_WMIC_CREATE.match(arguments)): raise ValueError('not a recognized WMIC process create command') return _strip_outer_quotes(arguments[match.end():]) def _extract_cmd(self, arguments: str) -> _Layer: if not (match := _RE_CMD_RUN.match(arguments)): raise ValueError('CMD command line missing /c or /k switch') strip = re.search(r'(?i)/s\b', match['switches']) is not None executable = BatchState(cmdline=True).names_executable command = cmd_unquote(arguments[match.end():], strip, executable) if (run := _command_as_run(command)) is None: return _Layer(command, final=True) return _Layer(run) def _extract_start(self, arguments: str) -> str: pieces = split_arguments(arguments) if (start := parse_start_arguments(pieces)) is None: raise ValueError('no command found after start') return ''.join(pieces[start.program:])Ancestors
Subclasses
Class variables
var reverse-
The type of the None singleton.
Inherited members