Something went wrong. Try again.
source dump of claude code
Something went wrong. Try again.
38 kB · 1090 lines
TypeScript
at main
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091/** * 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' }}