1091 lines
37 KiB
TypeScript
1091 lines
37 KiB
TypeScript
/**
|
||
* PowerShell-specific security analysis for command validation.
|
||
*
|
||
* Detects dangerous patterns: code injection, download cradles, privilege
|
||
* escalation, dynamic command names, COM objects, etc.
|
||
*
|
||
* All checks are AST-based. If parsing failed (valid=false), none of the
|
||
* individual checks match and powershellCommandIsSafe returns 'ask'.
|
||
*/
|
||
|
||
import {
|
||
DANGEROUS_SCRIPT_BLOCK_CMDLETS,
|
||
FILEPATH_EXECUTION_CMDLETS,
|
||
MODULE_LOADING_CMDLETS,
|
||
} from '../../utils/powershell/dangerousCmdlets.js'
|
||
import type {
|
||
ParsedCommandElement,
|
||
ParsedPowerShellCommand,
|
||
} from '../../utils/powershell/parser.js'
|
||
import {
|
||
COMMON_ALIASES,
|
||
commandHasArgAbbreviation,
|
||
deriveSecurityFlags,
|
||
getAllCommands,
|
||
getVariablesByScope,
|
||
hasCommandNamed,
|
||
} from '../../utils/powershell/parser.js'
|
||
import { isClmAllowedType } from './clmTypes.js'
|
||
|
||
type PowerShellSecurityResult = {
|
||
behavior: 'passthrough' | 'ask' | 'allow'
|
||
message?: string
|
||
}
|
||
|
||
const POWERSHELL_EXECUTABLES = new Set([
|
||
'pwsh',
|
||
'pwsh.exe',
|
||
'powershell',
|
||
'powershell.exe',
|
||
])
|
||
|
||
/**
|
||
* Extracts the base executable name from a command, handling full paths
|
||
* like /usr/bin/pwsh, C:\Windows\...\powershell.exe, or .\pwsh.
|
||
*/
|
||
function isPowerShellExecutable(name: string): boolean {
|
||
const lower = name.toLowerCase()
|
||
if (POWERSHELL_EXECUTABLES.has(lower)) {
|
||
return true
|
||
}
|
||
// Extract basename from paths (both / and \ separators)
|
||
const lastSep = Math.max(lower.lastIndexOf('/'), lower.lastIndexOf('\\'))
|
||
if (lastSep >= 0) {
|
||
return POWERSHELL_EXECUTABLES.has(lower.slice(lastSep + 1))
|
||
}
|
||
return false
|
||
}
|
||
|
||
/**
|
||
* Alternative parameter-prefix characters that PowerShell accepts as equivalent
|
||
* to ASCII hyphen-minus (U+002D). PowerShell's tokenizer (SpecialCharacters.IsDash)
|
||
* and powershell.exe's CommandLineParameterParser both accept all four dash
|
||
* characters plus Windows PowerShell 5.1's `/` parameter delimiter.
|
||
* Extent.Text preserves the raw character; transformCommandAst uses ce.text for
|
||
* CommandParameterAst elements, so these reach us unchanged.
|
||
*/
|
||
const PS_ALT_PARAM_PREFIXES = new Set([
|
||
'/', // Windows PowerShell 5.1 (powershell.exe, not pwsh 7+)
|
||
'\u2013', // en-dash
|
||
'\u2014', // em-dash
|
||
'\u2015', // horizontal bar
|
||
])
|
||
|
||
/**
|
||
* Wrapper around commandHasArgAbbreviation that also matches alternative
|
||
* parameter prefixes (`/`, en-dash, em-dash, horizontal-bar). PowerShell's
|
||
* tokenizer (SpecialCharacters.IsDash) accepts these for both powershell.exe
|
||
* args AND cmdlet parameters, so use this for ALL PS param checks — not just
|
||
* pwsh.exe invocations. Previously checkComObject/checkStartProcess/
|
||
* checkDangerousFilePathExecution/checkForEachMemberName used bare
|
||
* commandHasArgAbbreviation, so `Start-Process foo –Verb RunAs` bypassed.
|
||
*/
|
||
function psExeHasParamAbbreviation(
|
||
cmd: ParsedCommandElement,
|
||
fullParam: string,
|
||
minPrefix: string,
|
||
): boolean {
|
||
if (commandHasArgAbbreviation(cmd, fullParam, minPrefix)) {
|
||
return true
|
||
}
|
||
// Normalize alternative prefixes to `-` and re-check. Build a synthetic cmd
|
||
// with normalized args; commandHasArgAbbreviation handles colon-value split.
|
||
const normalized: ParsedCommandElement = {
|
||
...cmd,
|
||
args: cmd.args.map(a =>
|
||
a.length > 0 && PS_ALT_PARAM_PREFIXES.has(a[0]!) ? '-' + a.slice(1) : a,
|
||
),
|
||
}
|
||
return commandHasArgAbbreviation(normalized, fullParam, minPrefix)
|
||
}
|
||
|
||
/**
|
||
* Checks if a PowerShell command uses Invoke-Expression or its alias (iex).
|
||
* These are equivalent to eval and can execute arbitrary code.
|
||
*/
|
||
function checkInvokeExpression(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
if (hasCommandNamed(parsed, 'Invoke-Expression')) {
|
||
return {
|
||
behavior: 'ask',
|
||
message:
|
||
'Command uses Invoke-Expression which can execute arbitrary code',
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Checks for dynamic command invocation where the command name itself is an
|
||
* expression that cannot be statically resolved.
|
||
*
|
||
* PoCs:
|
||
* & ${function:Invoke-Expression} 'payload' — VariableExpressionAst
|
||
* & ('iex','x')[0] 'payload' — IndexExpressionAst → 'Other'
|
||
* & ('i'+'ex') 'payload' — BinaryExpressionAst → 'Other'
|
||
*
|
||
* In all cases cmd.name is the literal extent text (e.g. "('iex','x')[0]"),
|
||
* which doesn't match hasCommandNamed('Invoke-Expression'). At runtime
|
||
* PowerShell evaluates the expression to a command name and invokes it.
|
||
*
|
||
* Legitimate command names are ALWAYS StringConstantExpressionAst (mapped to
|
||
* 'StringConstant'): `Get-Process`, `git`, `ls`. Any other element type in
|
||
* name position is dynamic. Rather than denylisting dynamic types (fragile —
|
||
* mapElementType's default case maps unknown AST types to 'Other', which a
|
||
* `=== 'Variable'` check misses), we allowlist 'StringConstant'.
|
||
*
|
||
* elementTypes[0] is the command-name element (transformCommandAst pushes it
|
||
* first, before arg elements). The `!== undefined` guard preserves fail-open
|
||
* when elementTypes is absent (parse-detail unavailable — if parsing failed
|
||
* entirely, valid=false already returns 'ask' earlier in the chain).
|
||
*/
|
||
function checkDynamicCommandName(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
if (cmd.elementType !== 'CommandAst') {
|
||
continue
|
||
}
|
||
const nameElementType = cmd.elementTypes?.[0]
|
||
if (nameElementType !== undefined && nameElementType !== 'StringConstant') {
|
||
return {
|
||
behavior: 'ask',
|
||
message:
|
||
'Command name is a dynamic expression which cannot be statically validated',
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Checks for encoded command parameters which obscure intent.
|
||
* These are commonly used in malware to bypass security tools.
|
||
*/
|
||
function checkEncodedCommand(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
if (isPowerShellExecutable(cmd.name)) {
|
||
if (psExeHasParamAbbreviation(cmd, '-encodedcommand', '-e')) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command uses encoded parameters which obscure intent',
|
||
}
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Checks for PowerShell re-invocation (nested pwsh/powershell process).
|
||
*
|
||
* Any PowerShell executable in command position is flagged — not just
|
||
* -Command/-File. Bare `pwsh` receiving stdin (`Get-Content x | pwsh`) or
|
||
* a positional script path executes arbitrary code with none of the explicit
|
||
* flags present. Same unvalidatable-nested-process reasoning as
|
||
* checkStartProcess vector 2: we cannot statically analyze what the child
|
||
* process will run.
|
||
*/
|
||
function checkPwshCommandOrFile(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
if (isPowerShellExecutable(cmd.name)) {
|
||
return {
|
||
behavior: 'ask',
|
||
message:
|
||
'Command spawns a nested PowerShell process which cannot be validated',
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Checks for download cradle patterns - common malware techniques
|
||
* that download and execute remote code.
|
||
*
|
||
* Per-statement: catches piped cradles (`IWR ... | IEX`).
|
||
* Cross-statement: catches split cradles (`$r = IWR ...; IEX $r.Content`).
|
||
* The cross-statement case is already blocked by checkInvokeExpression (which
|
||
* scans all statements), but this check improves the warning message.
|
||
*/
|
||
const DOWNLOADER_NAMES = new Set([
|
||
'invoke-webrequest',
|
||
'iwr',
|
||
'invoke-restmethod',
|
||
'irm',
|
||
'new-object',
|
||
'start-bitstransfer', // MITRE T1197
|
||
])
|
||
|
||
function isDownloader(name: string): boolean {
|
||
return DOWNLOADER_NAMES.has(name.toLowerCase())
|
||
}
|
||
|
||
function isIex(name: string): boolean {
|
||
const lower = name.toLowerCase()
|
||
return lower === 'invoke-expression' || lower === 'iex'
|
||
}
|
||
|
||
function checkDownloadCradles(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
// Per-statement: piped cradle (IWR ... | IEX)
|
||
for (const statement of parsed.statements) {
|
||
const cmds = statement.commands
|
||
if (cmds.length < 2) {
|
||
continue
|
||
}
|
||
const hasDownloader = cmds.some(cmd => isDownloader(cmd.name))
|
||
const hasIex = cmds.some(cmd => isIex(cmd.name))
|
||
if (hasDownloader && hasIex) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command downloads and executes remote code',
|
||
}
|
||
}
|
||
}
|
||
|
||
// Cross-statement: split cradle ($r = IWR ...; IEX $r.Content).
|
||
// No new false positives: if IEX is present, checkInvokeExpression already asks.
|
||
const all = getAllCommands(parsed)
|
||
if (all.some(c => isDownloader(c.name)) && all.some(c => isIex(c.name))) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command downloads and executes remote code',
|
||
}
|
||
}
|
||
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Checks for standalone download utilities — LOLBAS tools commonly used to
|
||
* fetch payloads. Unlike checkDownloadCradles (which requires download + IEX
|
||
* in-pipeline), this flags the download operation itself.
|
||
*
|
||
* Start-BitsTransfer: always a file transfer (MITRE T1197).
|
||
* certutil -urlcache: classic LOLBAS download. Only flagged with -urlcache;
|
||
* bare `certutil` has many legitimate cert-management uses.
|
||
* bitsadmin /transfer: legacy BITS download (pre-PowerShell).
|
||
*/
|
||
function checkDownloadUtilities(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
const lower = cmd.name.toLowerCase()
|
||
// Start-BitsTransfer is purpose-built for file transfer — no safe variant.
|
||
if (lower === 'start-bitstransfer') {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command downloads files via BITS transfer',
|
||
}
|
||
}
|
||
// certutil / certutil.exe — only when -urlcache is present. certutil has
|
||
// many non-download uses (cert store queries, encoding, etc.).
|
||
// certutil.exe accepts both -urlcache and /urlcache per standard Windows
|
||
// utility convention — check both forms (bitsadmin below does the same).
|
||
if (lower === 'certutil' || lower === 'certutil.exe') {
|
||
const hasUrlcache = cmd.args.some(a => {
|
||
const la = a.toLowerCase()
|
||
return la === '-urlcache' || la === '/urlcache'
|
||
})
|
||
if (hasUrlcache) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command uses certutil to download from a URL',
|
||
}
|
||
}
|
||
}
|
||
// bitsadmin /transfer — legacy BITS CLI, same threat as Start-BitsTransfer.
|
||
if (lower === 'bitsadmin' || lower === 'bitsadmin.exe') {
|
||
if (cmd.args.some(a => a.toLowerCase() === '/transfer')) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command downloads files via BITS transfer',
|
||
}
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Checks for Add-Type usage which compiles and loads .NET code at runtime.
|
||
* This can be used to execute arbitrary compiled code.
|
||
*/
|
||
function checkAddType(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
if (hasCommandNamed(parsed, 'Add-Type')) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command compiles and loads .NET code',
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Checks for New-Object -ComObject. COM objects like WScript.Shell,
|
||
* Shell.Application, MMC20.Application, Schedule.Service, Msxml2.XMLHTTP
|
||
* have their own execution/download capabilities — no IEX required.
|
||
*
|
||
* We can't enumerate all dangerous ProgIDs, so flag any -ComObject. Object
|
||
* creation alone is inert, but the prompt should warn the user that COM
|
||
* instantiation is an execution primitive. Method invocation on the result
|
||
* (.Run(), .Exec()) is separately caught by checkMemberInvocations.
|
||
*/
|
||
function checkComObject(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
if (cmd.name.toLowerCase() !== 'new-object') {
|
||
continue
|
||
}
|
||
// -ComObject min abbrev is -com (New-Object params: -TypeName, -ComObject,
|
||
// -ArgumentList, -Property, -Strict; -co is ambiguous in PS5.1 due to
|
||
// common params like -Confirm, so use -com).
|
||
if (psExeHasParamAbbreviation(cmd, '-comobject', '-com')) {
|
||
return {
|
||
behavior: 'ask',
|
||
message:
|
||
'Command instantiates a COM object which may have execution capabilities',
|
||
}
|
||
}
|
||
// SECURITY: checkTypeLiterals only sees [bracket] syntax from
|
||
// parsed.typeLiterals. `New-Object System.Net.WebClient` passes the type
|
||
// as a STRING ARG (StringConstantExpressionAst), not a TypeExpressionAst,
|
||
// so CLM never fires. Extract -TypeName (named, colon-bound, or
|
||
// positional-0) and run through isClmAllowedType. Closes attackVectors D4.
|
||
let typeName: string | undefined
|
||
for (let i = 0; i < cmd.args.length; i++) {
|
||
const a = cmd.args[i]!
|
||
const lower = a.toLowerCase()
|
||
// -TypeName abbrev: -t is unambiguous (no other New-Object -t* params).
|
||
// Handle colon-bound form first: -TypeName:Foo.Bar
|
||
if (lower.startsWith('-t') && lower.includes(':')) {
|
||
const colonIdx = a.indexOf(':')
|
||
const paramPart = lower.slice(0, colonIdx)
|
||
if ('-typename'.startsWith(paramPart)) {
|
||
typeName = a.slice(colonIdx + 1)
|
||
break
|
||
}
|
||
}
|
||
// Space-separated form: -TypeName Foo.Bar
|
||
if (
|
||
lower.startsWith('-t') &&
|
||
'-typename'.startsWith(lower) &&
|
||
cmd.args[i + 1] !== undefined
|
||
) {
|
||
typeName = cmd.args[i + 1]
|
||
break
|
||
}
|
||
}
|
||
// Positional-0 binds to -TypeName (NetParameterSet default). Named params
|
||
// (-Strict, -ArgumentList, -Property, -ComObject) may appear before the
|
||
// positional TypeName, so scan past them to find the first non-consumed arg.
|
||
if (typeName === undefined) {
|
||
// New-Object named params that consume a following value argument
|
||
const VALUE_PARAMS = new Set(['-argumentlist', '-comobject', '-property'])
|
||
// Switch params (no value argument)
|
||
const SWITCH_PARAMS = new Set(['-strict'])
|
||
for (let i = 0; i < cmd.args.length; i++) {
|
||
const a = cmd.args[i]!
|
||
if (a.startsWith('-')) {
|
||
const lower = a.toLowerCase()
|
||
// Skip -TypeName variants (already handled by named-param loop above)
|
||
if (lower.startsWith('-t') && '-typename'.startsWith(lower)) {
|
||
i++ // skip value
|
||
continue
|
||
}
|
||
// Colon-bound form: -Param:Value (single token, no skip needed)
|
||
if (lower.includes(':')) continue
|
||
if (SWITCH_PARAMS.has(lower)) continue
|
||
if (VALUE_PARAMS.has(lower)) {
|
||
i++ // skip value
|
||
continue
|
||
}
|
||
// Unknown param — skip conservatively
|
||
continue
|
||
}
|
||
// First non-dash arg is the positional TypeName
|
||
typeName = a
|
||
break
|
||
}
|
||
}
|
||
if (typeName !== undefined && !isClmAllowedType(typeName)) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: `New-Object instantiates .NET type '${typeName}' outside the ConstrainedLanguage allowlist`,
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Checks for DANGEROUS_SCRIPT_BLOCK_CMDLETS invoked with -FilePath (or
|
||
* -LiteralPath). These run a script file — arbitrary code execution with no
|
||
* ScriptBlockAst in the tree.
|
||
*
|
||
* checkScriptBlockInjection only fires when hasScriptBlocks is true. With
|
||
* -FilePath there is no ScriptBlockAst, so DANGEROUS_SCRIPT_BLOCK_CMDLETS is
|
||
* never consulted. This check closes that gap for the -FilePath vector.
|
||
*
|
||
* Cmdlets in DANGEROUS_SCRIPT_BLOCK_CMDLETS that accept -FilePath:
|
||
* Invoke-Command -FilePath (icm alias via COMMON_ALIASES)
|
||
* Start-Job -FilePath, -LiteralPath
|
||
* Start-ThreadJob -FilePath
|
||
* Register-ScheduledJob -FilePath
|
||
* The *-PSSession and Register-*Event entries do not accept -FilePath.
|
||
*
|
||
* -f is unambiguous for -FilePath on all four (no other -f* params).
|
||
* -l is unambiguous for -LiteralPath on Start-Job; harmless no-op on the
|
||
* others (no -l* params to collide with).
|
||
*/
|
||
|
||
function checkDangerousFilePathExecution(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
const lower = cmd.name.toLowerCase()
|
||
const resolved = COMMON_ALIASES[lower]?.toLowerCase() ?? lower
|
||
if (!FILEPATH_EXECUTION_CMDLETS.has(resolved)) {
|
||
continue
|
||
}
|
||
if (
|
||
psExeHasParamAbbreviation(cmd, '-filepath', '-f') ||
|
||
psExeHasParamAbbreviation(cmd, '-literalpath', '-l')
|
||
) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: `${cmd.name} -FilePath executes an arbitrary script file`,
|
||
}
|
||
}
|
||
// Positional binding: `Start-Job script.ps1` binds position-0 to
|
||
// -FilePath via FilePathParameterSet resolution (ScriptBlock args select
|
||
// ScriptBlockParameterSet instead). Same pattern as checkForEachMemberName:
|
||
// any non-dash StringConstant is a potential -FilePath. Over-flagging
|
||
// (e.g., `Start-Job -Name foo` where `foo` is StringConstant) is fail-safe.
|
||
for (let i = 0; i < cmd.args.length; i++) {
|
||
const argType = cmd.elementTypes?.[i + 1]
|
||
const arg = cmd.args[i]
|
||
if (argType === 'StringConstant' && arg && !arg.startsWith('-')) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: `${cmd.name} with positional string argument binds to -FilePath and executes a script file`,
|
||
}
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Checks for ForEach-Object -MemberName. Invokes a method by string name on
|
||
* every piped object — semantically equivalent to `| % { $_.Method() }` but
|
||
* without any ScriptBlockAst or InvokeMemberExpressionAst in the tree.
|
||
*
|
||
* PoC: `Get-Process | ForEach-Object -MemberName Kill` → kills all processes.
|
||
* checkScriptBlockInjection misses it (no script block); checkMemberInvocations
|
||
* misses it (no .Method() syntax). Aliases `%` and `foreach` resolve via
|
||
* COMMON_ALIASES.
|
||
*/
|
||
function checkForEachMemberName(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
const lower = cmd.name.toLowerCase()
|
||
const resolved = COMMON_ALIASES[lower]?.toLowerCase() ?? lower
|
||
if (resolved !== 'foreach-object') {
|
||
continue
|
||
}
|
||
// ForEach-Object params starting with -m: only -MemberName. -m is unambiguous.
|
||
if (psExeHasParamAbbreviation(cmd, '-membername', '-m')) {
|
||
return {
|
||
behavior: 'ask',
|
||
message:
|
||
'ForEach-Object -MemberName invokes methods by string name which cannot be validated',
|
||
}
|
||
}
|
||
// PS7+: `ForEach-Object Kill` binds a positional string arg to
|
||
// -MemberName via MemberSet parameter-set resolution (ScriptBlock args
|
||
// select ScriptBlockSet instead). Scan ALL args — `-Verbose Kill` or
|
||
// `-ErrorAction Stop Kill` still binds Kill positionally. Any non-dash
|
||
// StringConstant is a potential -MemberName; over-flagging is fail-safe.
|
||
for (let i = 0; i < cmd.args.length; i++) {
|
||
const argType = cmd.elementTypes?.[i + 1]
|
||
const arg = cmd.args[i]
|
||
if (argType === 'StringConstant' && arg && !arg.startsWith('-')) {
|
||
return {
|
||
behavior: 'ask',
|
||
message:
|
||
'ForEach-Object with positional string argument binds to -MemberName and invokes methods by name',
|
||
}
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Checks for dangerous Start-Process patterns.
|
||
*
|
||
* Two vectors:
|
||
* 1. `-Verb RunAs` — privilege escalation (UAC prompt).
|
||
* 2. Launching a PowerShell executable — nested invocation.
|
||
* `Start-Process pwsh -ArgumentList "-e <b64>"` evades
|
||
* checkEncodedCommand/checkPwshCommandOrFile because cmd.name is
|
||
* `Start-Process`, not `pwsh`. The `-e` lives inside the -ArgumentList
|
||
* string value and is never parsed as a param on the outer command.
|
||
* Rather than parse -ArgumentList contents (fragile — it's an opaque
|
||
* string or array), flag any Start-Process whose target is a PS
|
||
* executable: the nested invocation is unvalidatable by construction.
|
||
*/
|
||
function checkStartProcess(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
const lower = cmd.name.toLowerCase()
|
||
if (lower !== 'start-process' && lower !== 'saps' && lower !== 'start') {
|
||
continue
|
||
}
|
||
// Vector 1: -Verb RunAs (space or colon syntax).
|
||
// Space syntax: psExeHasParamAbbreviation finds -Verb/-v, then scan args
|
||
// for a bare 'runas' token.
|
||
if (
|
||
psExeHasParamAbbreviation(cmd, '-Verb', '-v') &&
|
||
cmd.args.some(a => a.toLowerCase() === 'runas')
|
||
) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command requests elevated privileges',
|
||
}
|
||
}
|
||
// Colon syntax — two layers:
|
||
// (a) Structural: PR #23554 added children[] for colon-bound param args.
|
||
// children[i] = [{type, text}] for the bound value. Check if any
|
||
// -v*-prefixed param has a child whose text normalizes (strip
|
||
// quotes/backtick/whitespace) to 'runas'. Robust against arbitrary
|
||
// quoting the regex can't anticipate.
|
||
// (b) Regex fallback: for parsed output without children[] or as
|
||
// defense-in-depth. -Verb:'RunAs', -Verb:"RunAs", -Verb:`runas all
|
||
// bypassed the old /...:runas$/ pattern because the quote/tick broke
|
||
// the match.
|
||
if (cmd.children) {
|
||
for (let i = 0; i < cmd.args.length; i++) {
|
||
// Strip backticks before matching param name (bug #14): -V`erb:RunAs
|
||
const argClean = cmd.args[i]!.replace(/`/g, '')
|
||
if (!/^[-\u2013\u2014\u2015/]v[a-z]*:/i.test(argClean)) continue
|
||
const kids = cmd.children[i]
|
||
if (!kids) continue
|
||
for (const child of kids) {
|
||
if (child.text.replace(/['"`\s]/g, '').toLowerCase() === 'runas') {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command requests elevated privileges',
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
if (
|
||
cmd.args.some(a => {
|
||
// Strip backticks before matching (bug #14 / review nit #2)
|
||
const clean = a.replace(/`/g, '')
|
||
return /^[-\u2013\u2014\u2015/]v[a-z]*:['"` ]*runas['"` ]*$/i.test(
|
||
clean,
|
||
)
|
||
})
|
||
) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command requests elevated privileges',
|
||
}
|
||
}
|
||
// Vector 2: Start-Process targeting a PowerShell executable.
|
||
// Target is either the first positional arg or the value after -FilePath.
|
||
// Scan all args — any PS-executable token present is treated as the launch
|
||
// target. Known false-positive: path-valued params (-WorkingDirectory,
|
||
// -RedirectStandard*) whose basename is pwsh/powershell —
|
||
// isPowerShellExecutable extracts basenames from paths, so
|
||
// `-WorkingDirectory C:\projects\pwsh` triggers. Accepted trade-off:
|
||
// Start-Process is not in CMDLET_ALLOWLIST (always prompts regardless),
|
||
// result is ask not reject, and correctly parsing Start-Process parameter
|
||
// binding is fragile. Strip quotes the parser may have preserved.
|
||
for (const arg of cmd.args) {
|
||
const stripped = arg.replace(/^['"]|['"]$/g, '')
|
||
if (isPowerShellExecutable(stripped)) {
|
||
return {
|
||
behavior: 'ask',
|
||
message:
|
||
'Start-Process launches a nested PowerShell process which cannot be validated',
|
||
}
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Cmdlets where script blocks are safe (filtering/output cmdlets).
|
||
* Script blocks piped to these are just predicates or projections, not arbitrary execution.
|
||
*/
|
||
const SAFE_SCRIPT_BLOCK_CMDLETS = new Set([
|
||
'where-object',
|
||
'sort-object',
|
||
'select-object',
|
||
'group-object',
|
||
'format-table',
|
||
'format-list',
|
||
'format-wide',
|
||
'format-custom',
|
||
// NOT foreach-object — its block is arbitrary script, not a predicate.
|
||
// getAllCommands recurses so commands inside the block ARE checked, but
|
||
// non-command AST nodes (AssignmentStatementAst etc.) are invisible to it.
|
||
// See powershellPermissions.ts step-5 hasScriptBlocks guard.
|
||
])
|
||
|
||
/**
|
||
* Checks for script block injection patterns where script blocks
|
||
* appear in suspicious contexts that could execute arbitrary code.
|
||
*
|
||
* Script blocks used with safe filtering/output cmdlets (Where-Object,
|
||
* Sort-Object, Select-Object, Group-Object) are allowed.
|
||
* Script blocks used with dangerous cmdlets (Invoke-Command, Invoke-Expression,
|
||
* Start-Job, etc.) are flagged.
|
||
*/
|
||
function checkScriptBlockInjection(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
const security = deriveSecurityFlags(parsed)
|
||
if (!security.hasScriptBlocks) {
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
// Check all commands in the parsed result. If any command is in the
|
||
// dangerous set, flag it. If all commands with script blocks are in
|
||
// the safe set (or the allowlist), allow it.
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
const lower = cmd.name.toLowerCase()
|
||
if (DANGEROUS_SCRIPT_BLOCK_CMDLETS.has(lower)) {
|
||
return {
|
||
behavior: 'ask',
|
||
message:
|
||
'Command contains script block with dangerous cmdlet that may execute arbitrary code',
|
||
}
|
||
}
|
||
}
|
||
|
||
// Check if all commands are either safe script block consumers or don't use script blocks
|
||
const allCommandsSafe = getAllCommands(parsed).every(cmd => {
|
||
const lower = cmd.name.toLowerCase()
|
||
// Safe filtering/output cmdlets
|
||
if (SAFE_SCRIPT_BLOCK_CMDLETS.has(lower)) {
|
||
return true
|
||
}
|
||
// Resolve aliases
|
||
const alias = COMMON_ALIASES[lower]
|
||
if (alias && SAFE_SCRIPT_BLOCK_CMDLETS.has(alias.toLowerCase())) {
|
||
return true
|
||
}
|
||
// Unknown command with script blocks present — flag as potentially dangerous
|
||
return false
|
||
})
|
||
|
||
if (allCommandsSafe) {
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command contains script block that may execute arbitrary code',
|
||
}
|
||
}
|
||
|
||
/**
|
||
* AST-only check: Detects subexpressions $() which can hide command execution.
|
||
*/
|
||
function checkSubExpressions(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
if (deriveSecurityFlags(parsed).hasSubExpressions) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command contains subexpressions $()',
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* AST-only check: Detects expandable strings (double-quoted) with embedded
|
||
* expressions like "$env:PATH" or "$(dangerous-command)". These can hide
|
||
* command execution or variable interpolation inside string literals.
|
||
*/
|
||
function checkExpandableStrings(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
if (deriveSecurityFlags(parsed).hasExpandableStrings) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command contains expandable strings with embedded expressions',
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* AST-only check: Detects splatting (@variable) which can obscure arguments.
|
||
*/
|
||
function checkSplatting(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
if (deriveSecurityFlags(parsed).hasSplatting) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command uses splatting (@variable)',
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* AST-only check: Detects stop-parsing token (--%) which prevents further parsing.
|
||
*/
|
||
function checkStopParsing(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
if (deriveSecurityFlags(parsed).hasStopParsing) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command uses stop-parsing token (--%)',
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* AST-only check: Detects .NET method invocations which can access system APIs.
|
||
*/
|
||
function checkMemberInvocations(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
if (deriveSecurityFlags(parsed).hasMemberInvocations) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command invokes .NET methods',
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* AST-only check: type literals outside Microsoft's ConstrainedLanguage
|
||
* allowlist. CLM blocks all .NET type access except ~90 primitives/attributes
|
||
* Microsoft considers safe for untrusted code. We trust that list as the
|
||
* "safe" boundary — anything outside it (Reflection.Assembly, IO.Pipes,
|
||
* Diagnostics.Process, InteropServices.Marshal, etc.) can access system APIs
|
||
* that compromise the permission model.
|
||
*
|
||
* Runs AFTER checkMemberInvocations: that broadly flags any ::Method / .Method()
|
||
* call; this check is the more specific "which types" signal. Both fire on
|
||
* [Reflection.Assembly]::Load; CLM gives the precise message. Pure type casts
|
||
* like [int]$x have no member invocation and only hit this check.
|
||
*/
|
||
function checkTypeLiterals(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const t of parsed.typeLiterals ?? []) {
|
||
if (!isClmAllowedType(t)) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: `Command uses .NET type [${t}] outside the ConstrainedLanguage allowlist`,
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Invoke-Item (alias ii) opens a file with its default handler (ShellExecute
|
||
* on Windows, open/xdg-open on Unix). On an .exe/.ps1/.bat/.cmd this is RCE.
|
||
* Bug 008: ii is in no blocklist; passthrough prompt doesn't explain the
|
||
* exec hazard. Always ask — there is no safe variant (even opening .txt may
|
||
* invoke a user-configured handler that accepts arguments).
|
||
*/
|
||
function checkInvokeItem(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
const lower = cmd.name.toLowerCase()
|
||
if (lower === 'invoke-item' || lower === 'ii') {
|
||
return {
|
||
behavior: 'ask',
|
||
message:
|
||
'Invoke-Item opens files with the default handler (ShellExecute). On executable files this runs arbitrary code.',
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Scheduled-task persistence primitives. Register-ScheduledJob was blocked
|
||
* (DANGEROUS_SCRIPT_BLOCK_CMDLETS); the newer Register-ScheduledTask cmdlet
|
||
* and legacy schtasks.exe /create were not. Persistence that survives the
|
||
* session with no explanatory prompt.
|
||
*/
|
||
const SCHEDULED_TASK_CMDLETS = new Set([
|
||
'register-scheduledtask',
|
||
'new-scheduledtask',
|
||
'new-scheduledtaskaction',
|
||
'set-scheduledtask',
|
||
])
|
||
|
||
function checkScheduledTask(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
const lower = cmd.name.toLowerCase()
|
||
if (SCHEDULED_TASK_CMDLETS.has(lower)) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: `${cmd.name} creates or modifies a scheduled task (persistence primitive)`,
|
||
}
|
||
}
|
||
if (lower === 'schtasks' || lower === 'schtasks.exe') {
|
||
if (
|
||
cmd.args.some(a => {
|
||
const la = a.toLowerCase()
|
||
return (
|
||
la === '/create' ||
|
||
la === '/change' ||
|
||
la === '-create' ||
|
||
la === '-change'
|
||
)
|
||
})
|
||
) {
|
||
return {
|
||
behavior: 'ask',
|
||
message:
|
||
'schtasks with create/change modifies scheduled tasks (persistence primitive)',
|
||
}
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* AST-only check: Detects environment variable manipulation via Set-Item/New-Item on env: scope.
|
||
*/
|
||
const ENV_WRITE_CMDLETS = new Set([
|
||
'set-item',
|
||
'si',
|
||
'new-item',
|
||
'ni',
|
||
'remove-item',
|
||
'ri',
|
||
'del',
|
||
'rm',
|
||
'rd',
|
||
'rmdir',
|
||
'erase',
|
||
'clear-item',
|
||
'cli',
|
||
'set-content',
|
||
// 'sc' omitted — collides with sc.exe on PS Core 7+, see COMMON_ALIASES note
|
||
'add-content',
|
||
'ac',
|
||
])
|
||
|
||
function checkEnvVarManipulation(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
const envVars = getVariablesByScope(parsed, 'env')
|
||
if (envVars.length === 0) {
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
// Check if any command is a write cmdlet
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
if (ENV_WRITE_CMDLETS.has(cmd.name.toLowerCase())) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command modifies environment variables',
|
||
}
|
||
}
|
||
}
|
||
// Also flag if there are assignments involving env vars
|
||
if (deriveSecurityFlags(parsed).hasAssignments && envVars.length > 0) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Command modifies environment variables',
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Module-loading cmdlets execute a .psm1's top-level script body (Import-Module)
|
||
* or download from arbitrary repositories (Install-Module, Save-Module). A
|
||
* wildcard allow rule like `Import-Module:*` would let an attacker-supplied
|
||
* .psm1 execute with the user's privileges — same risk as Invoke-Expression.
|
||
*
|
||
* NEVER_SUGGEST (dangerousCmdlets.ts) derives from this list so the UI
|
||
* never offers these as wildcard suggestions, but users can still manually
|
||
* write allow rules. This check ensures the permission engine independently
|
||
* gates these cmdlets.
|
||
*/
|
||
|
||
function checkModuleLoading(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
const lower = cmd.name.toLowerCase()
|
||
if (MODULE_LOADING_CMDLETS.has(lower)) {
|
||
return {
|
||
behavior: 'ask',
|
||
message:
|
||
'Command loads, installs, or downloads a PowerShell module or script, which can execute arbitrary code',
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Set-Alias/New-Alias can hijack future command resolution: after
|
||
* `Set-Alias Get-Content Invoke-Expression`, any later `Get-Content $x`
|
||
* executes arbitrary code. Set-Variable/New-Variable can poison
|
||
* `$PSDefaultParameterValues` (e.g., `Set-Variable PSDefaultParameterValues
|
||
* @{'*:Path'='/etc/passwd'}`) which alters every subsequent cmdlet's behavior.
|
||
* Neither effect can be validated statically — we'd need to track all future
|
||
* command resolutions in the session. Always ask.
|
||
*/
|
||
const RUNTIME_STATE_CMDLETS = new Set([
|
||
'set-alias',
|
||
'sal',
|
||
'new-alias',
|
||
'nal',
|
||
'set-variable',
|
||
'sv',
|
||
'new-variable',
|
||
'nv',
|
||
])
|
||
|
||
function checkRuntimeStateManipulation(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
// Strip module qualifier: `Microsoft.PowerShell.Utility\Set-Alias` → `set-alias`
|
||
const raw = cmd.name.toLowerCase()
|
||
const lower = raw.includes('\\')
|
||
? raw.slice(raw.lastIndexOf('\\') + 1)
|
||
: raw
|
||
if (RUNTIME_STATE_CMDLETS.has(lower)) {
|
||
return {
|
||
behavior: 'ask',
|
||
message:
|
||
'Command creates or modifies an alias or variable that can affect future command resolution',
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Invoke-WmiMethod / Invoke-CimMethod are Start-Process equivalents via WMI.
|
||
* `Invoke-WmiMethod -Class Win32_Process -Name Create -ArgumentList "cmd /c ..."`
|
||
* spawns an arbitrary process, bypassing checkStartProcess entirely. No narrow
|
||
* safe usage exists — -Class and -MethodName accept arbitrary strings, so
|
||
* gating on Win32_Process specifically would miss -Class $x or other process-
|
||
* spawning WMI classes. Returns ask on any invocation. (security finding #34)
|
||
*/
|
||
const WMI_SPAWN_CMDLETS = new Set([
|
||
'invoke-wmimethod',
|
||
'iwmi',
|
||
'invoke-cimmethod',
|
||
])
|
||
|
||
function checkWmiProcessSpawn(
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
for (const cmd of getAllCommands(parsed)) {
|
||
const lower = cmd.name.toLowerCase()
|
||
if (WMI_SPAWN_CMDLETS.has(lower)) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: `${cmd.name} can spawn arbitrary processes via WMI/CIM (Win32_Process Create)`,
|
||
}
|
||
}
|
||
}
|
||
return { behavior: 'passthrough' }
|
||
}
|
||
|
||
/**
|
||
* Main entry point for PowerShell security validation.
|
||
* Checks a PowerShell command against known dangerous patterns.
|
||
*
|
||
* All checks are AST-based. If the AST parse failed (parsed.valid === false),
|
||
* none of the individual checks will match and we return 'ask' as a safe default.
|
||
*
|
||
* @param command - The PowerShell command to validate (unused, kept for API compat)
|
||
* @param parsed - Parsed AST from PowerShell's native parser (required)
|
||
* @returns Security result indicating whether the command is safe
|
||
*/
|
||
export function powershellCommandIsSafe(
|
||
_command: string,
|
||
parsed: ParsedPowerShellCommand,
|
||
): PowerShellSecurityResult {
|
||
// If the AST parse failed, we cannot determine safety -- ask the user
|
||
if (!parsed.valid) {
|
||
return {
|
||
behavior: 'ask',
|
||
message: 'Could not parse command for security analysis',
|
||
}
|
||
}
|
||
|
||
const validators = [
|
||
checkInvokeExpression,
|
||
checkDynamicCommandName,
|
||
checkEncodedCommand,
|
||
checkPwshCommandOrFile,
|
||
checkDownloadCradles,
|
||
checkDownloadUtilities,
|
||
checkAddType,
|
||
checkComObject,
|
||
checkDangerousFilePathExecution,
|
||
checkInvokeItem,
|
||
checkScheduledTask,
|
||
checkForEachMemberName,
|
||
checkStartProcess,
|
||
checkScriptBlockInjection,
|
||
checkSubExpressions,
|
||
checkExpandableStrings,
|
||
checkSplatting,
|
||
checkStopParsing,
|
||
checkMemberInvocations,
|
||
checkTypeLiterals,
|
||
checkEnvVarManipulation,
|
||
checkModuleLoading,
|
||
checkRuntimeStateManipulation,
|
||
checkWmiProcessSpawn,
|
||
]
|
||
|
||
for (const validator of validators) {
|
||
const result = validator(parsed)
|
||
if (result.behavior === 'ask') {
|
||
return result
|
||
}
|
||
}
|
||
|
||
// All checks passed
|
||
return { behavior: 'passthrough' }
|
||
}
|