Something went wrong. Try again.
source dump of claude code forked from oppi.li/claude-code
Something went wrong. Try again.
67 kB · 1804 lines
TypeScript
at main
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805import { execa } from 'execa'import { logForDebugging } from '../debug.js'import { memoizeWithLRU } from '../memoize.js'import { getCachedPowerShellPath } from '../shell/powershellDetection.js'import { jsonParse } from '../slowOperations.js'
// ---------------------------------------------------------------------------// Public types describing the parsed output returned to callers.// These map to System.Management.Automation.Language AST classes.// Raw internal types (RawParsedOutput etc.) are defined further below.// ---------------------------------------------------------------------------
/** * The PowerShell AST element type for pipeline elements. * Maps directly to CommandBaseAst derivatives in System.Management.Automation.Language. */type PipelineElementType = | 'CommandAst' | 'CommandExpressionAst' | 'ParenExpressionAst'
/** * The AST node type for individual command elements (arguments, expressions). * Used to classify each element during the AST walk so TypeScript can derive * security flags without extra Find-AstNodes calls in PowerShell. */type CommandElementType = | 'ScriptBlock' | 'SubExpression' | 'ExpandableString' | 'MemberInvocation' | 'Variable' | 'StringConstant' | 'Parameter' | 'Other'
/** * A child node of a command element (one level deep). Populated for * CommandParameterAst → .Argument (colon-bound parameters like * `-InputObject:$env:SECRET`). Consumers check `child.type` to classify * the bound value (Variable, StringConstant, Other) without parsing text. */export type CommandElementChild = { type: CommandElementType text: string}
/** * The PowerShell AST statement type. * Maps directly to StatementAst derivatives in System.Management.Automation.Language. */type StatementType = | 'PipelineAst' | 'PipelineChainAst' | 'AssignmentStatementAst' | 'IfStatementAst' | 'ForStatementAst' | 'ForEachStatementAst' | 'WhileStatementAst' | 'DoWhileStatementAst' | 'DoUntilStatementAst' | 'SwitchStatementAst' | 'TryStatementAst' | 'TrapStatementAst' | 'FunctionDefinitionAst' | 'DataStatementAst' | 'UnknownStatementAst'
/** * A command invocation within a pipeline segment. */export type ParsedCommandElement = { /** The command/cmdlet name (e.g., "Get-ChildItem", "git") */ name: string /** The command name type: cmdlet, application (exe), or unknown */ nameType: 'cmdlet' | 'application' | 'unknown' /** The AST element type from PowerShell's parser */ elementType: PipelineElementType /** All arguments as strings (includes flags like "-Recurse") */ args: string[] /** The full text of this command element */ text: string /** AST node types for each element in this command (arguments, expressions, etc.) */ elementTypes?: CommandElementType[] /** * Child nodes of each argument, aligned with `args[]` (so * `children[i]` ↔ `args[i]` ↔ `elementTypes[i+1]`). Only populated for * Parameter elements with a colon-bound argument. Undefined for elements * with no children. Lets consumers check `children[i].some(c => c.type * !== 'StringConstant')` instead of parsing the arg text for `:` + `$`. */ children?: (CommandElementChild[] | undefined)[] /** Redirections on this command element (from nested commands in && / || chains) */ redirections?: ParsedRedirection[]}
/** * A redirection found in the command. */type ParsedRedirection = { /** The redirection operator */ operator: '>' | '>>' | '2>' | '2>>' | '*>' | '*>>' | '2>&1' /** The target (file path or stream number) */ target: string /** Whether this is a merging redirection like 2>&1 */ isMerging: boolean}
/** * A parsed statement from PowerShell. * Can be a pipeline, assignment, control flow statement, etc. */type ParsedStatement = { /** The AST statement type from PowerShell's parser */ statementType: StatementType /** Individual commands in this statement (for pipelines) */ commands: ParsedCommandElement[] /** Redirections on this statement */ redirections: ParsedRedirection[] /** Full text of the statement */ text: string /** * For control flow statements (if, for, foreach, while, try, etc.), * commands found recursively inside the body blocks. * Uses FindAll() to extract ALL nested CommandAst nodes at any depth. */ nestedCommands?: ParsedCommandElement[] /** * Security-relevant AST patterns found via FindAll() on the entire statement, * regardless of statement type. This catches patterns that elementTypes may * miss (e.g. member invocations inside assignments, subexpressions in * non-pipeline statements). Computed in the PS1 script using instanceof * checks against the PowerShell AST type system. */ securityPatterns?: { hasMemberInvocations?: boolean hasSubExpressions?: boolean hasExpandableStrings?: boolean hasScriptBlocks?: boolean }}
/** * A variable reference found in the command. */type ParsedVariable = { /** The variable path (e.g., "HOME", "env:PATH", "global:x") */ path: string /** Whether this variable uses splatting (@var instead of $var) */ isSplatted: boolean}
/** * A parse error from PowerShell's parser. */type ParseError = { message: string errorId: string}
/** * The complete parsed result from the PowerShell AST parser. */export type ParsedPowerShellCommand = { /** Whether the command parsed successfully (no syntax errors) */ valid: boolean /** Parse errors, if any */ errors: ParseError[] /** Top-level statements, separated by ; or newlines */ statements: ParsedStatement[] /** All variable references found */ variables: ParsedVariable[] /** Whether the token stream contains a stop-parsing (--%) token */ hasStopParsing: boolean /** The original command text */ originalCommand: string /** * All .NET type literals found anywhere in the AST (TypeExpressionAst + * TypeConstraintAst). TypeName.FullName — the literal text as written, NOT * the resolved .NET type (e.g. [int] → "int", not "System.Int32"). * Consumed by the CLM-allowlist check in powershellSecurity.ts. */ typeLiterals?: string[] /** * Whether the command contains `using module` or `using assembly` statements. * These load external code (modules/assemblies) and execute their top-level * script body or module initializers. The using statement is a sibling of * the named blocks on ScriptBlockAst, not a child, so it is not visible * to Process-BlockStatements or any downstream command walker. */ hasUsingStatements?: boolean /** * Whether the command contains `#Requires` directives (ScriptRequirements). * `#Requires -Modules <name>` triggers module loading from PSModulePath. */ hasScriptRequirements?: boolean}
// ---------------------------------------------------------------------------
// Default 5s is fine for interactive use (warm pwsh spawn is ~450ms). Windows// CI under Defender/AMSI load can exceed 5s on consecutive spawns even after// CAN_SPAWN_PARSE_SCRIPT() warms the JIT (run 23574701241 windows-shard-5:// attackVectors F1 hit 2×5s timeout → valid:false → 'ask' instead of 'deny').// Override via env for tests. Read inside parsePowerShellCommandImpl, not// top-level, per CLAUDE.md (globalSettings.env ordering).const DEFAULT_PARSE_TIMEOUT_MS = 5_000function getParseTimeoutMs(): number { const env = process.env.CLAUDE_CODE_PWSH_PARSE_TIMEOUT_MS if (env) { const parsed = parseInt(env, 10) if (!isNaN(parsed) && parsed > 0) return parsed } return DEFAULT_PARSE_TIMEOUT_MS}// MAX_COMMAND_LENGTH is derived from PARSE_SCRIPT_BODY.length below (after the// script body is defined) so it cannot go stale as the script grows.
/** * The PowerShell parse script inlined as a string constant. * This avoids needing to read from disk at runtime (the file may not exist * in bundled builds). The script uses the native PowerShell AST parser to * analyze a command and output structured JSON. */// Raw types describing PS script JSON output (exported for testing)export type RawCommandElement = { type: string // .GetType().Name e.g. "StringConstantExpressionAst" text: string // .Extent.Text value?: string // .Value if available (resolves backtick escapes) expressionType?: string // .Expression.GetType().Name for CommandExpressionAst children?: { type: string; text: string }[] // CommandParameterAst.Argument, one level}
export type RawRedirection = { type: string // "FileRedirectionAst" or "MergingRedirectionAst" append?: boolean // .Append (FileRedirectionAst only) fromStream?: string // .FromStream.ToString() e.g. "Output", "Error", "All" locationText?: string // .Location.Extent.Text (FileRedirectionAst only)}
export type RawPipelineElement = { type: string // .GetType().Name e.g. "CommandAst", "CommandExpressionAst" text: string // .Extent.Text commandElements?: RawCommandElement[] redirections?: RawRedirection[] expressionType?: string // for CommandExpressionAst: .Expression.GetType().Name}
export type RawStatement = { type: string // .GetType().Name e.g. "PipelineAst", "IfStatementAst", "TrapStatementAst" text: string // .Extent.Text elements?: RawPipelineElement[] // for PipelineAst: the pipeline elements nestedCommands?: RawPipelineElement[] // commands found via FindAll (all statement types) redirections?: RawRedirection[] // FileRedirectionAst found via FindAll (non-PipelineAst only) securityPatterns?: { // Security-relevant AST node types found via FindAll on the statement hasMemberInvocations?: boolean hasSubExpressions?: boolean hasExpandableStrings?: boolean hasScriptBlocks?: boolean }}
type RawParsedOutput = { valid: boolean errors: { message: string; errorId: string }[] statements: RawStatement[] variables: { path: string; isSplatted: boolean }[] hasStopParsing: boolean originalCommand: string typeLiterals?: string[] hasUsingStatements?: boolean hasScriptRequirements?: boolean}
// This is the canonical copy of the parse script. There is no separate .ps1 file./** * The core parse logic. * The command is passed via Base64-encoded $EncodedCommand variable * to avoid here-string injection attacks. * * SECURITY — top-level ParamBlock: ScriptBlockAst.ParamBlock is a SIBLING of * the named blocks (Begin/Process/End/Clean/DynamicParam), not nested inside * them, so Process-BlockStatements never reaches it. Commands inside param() * default-value expressions and attribute arguments (e.g. [ValidateScript({...})]) * were invisible to every downstream check. PoC: * param($x = (Remove-Item /)); Get-Process → only Get-Process surfaced * param([ValidateScript({rm /;$true})]$x='t') → rm invisible, runs on bind * Function-level param() IS covered: FindAll on the FunctionDefinitionAst * statement recurses into its descendants. The gap was only the script-level * ParamBlock. ParamBlockAst has .Parameters (not .Statements) so we FindAll * on it directly rather than reusing Process-BlockStatements. We only emit a * statement if there is something to report, to avoid noise for plain * param($x) declarations. (Kept compact in-script to preserve argv budget.) *//** * PS1 parse script. Comments live here (not inline) — every char inside the * backticks eats into WINDOWS_MAX_COMMAND_LENGTH (argv budget). * * Structure: * - Get-RawCommandElements: extract CommandAst element data (type, text, value, * expressionType, children for colon-bound param .Argument) * - Get-RawRedirections: extract FileRedirectionAst operator+target * - Get-SecurityPatterns: FindAll for security flags (hasSubExpressions via * Sub/Array/ParenExpressionAst, hasScriptBlocks, etc.) * - Type literals: emit TypeExpressionAst names for CLM allowlist check * - --% token: PS7 MinusMinus, PS5.1 Generic kind * - CommandExpressionAst.Redirections: inherits from CommandBaseAst — * `1 > /tmp/x` statement has FileRedirectionAst that element-iteration misses * - Nested commands: FindAll for ALL statement types (if/for/foreach/while/ * switch/try/function/assignment/PipelineChainAst) — skip direct pipeline * elements already in the loop */// exported for testingexport const PARSE_SCRIPT_BODY = `if (-not $EncodedCommand) { Write-Output '{"valid":false,"errors":[{"message":"No command provided","errorId":"NoInput"}],"statements":[],"variables":[],"hasStopParsing":false,"originalCommand":""}' exit 0}
$Command = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($EncodedCommand))
$tokens = $null$parseErrors = $null$ast = [System.Management.Automation.Language.Parser]::ParseInput( $Command, [ref]$tokens, [ref]$parseErrors)
$allVariables = [System.Collections.ArrayList]::new()
function Get-RawCommandElements { param([System.Management.Automation.Language.CommandAst]$CmdAst) $elems = [System.Collections.ArrayList]::new() foreach ($ce in $CmdAst.CommandElements) { $ceData = @{ type = $ce.GetType().Name; text = $ce.Extent.Text } if ($ce.PSObject.Properties['Value'] -and $null -ne $ce.Value -and $ce.Value -is [string]) { $ceData.value = $ce.Value } if ($ce -is [System.Management.Automation.Language.CommandExpressionAst]) { $ceData.expressionType = $ce.Expression.GetType().Name } $a=$ce.Argument;if($a){$ceData.children=@(@{type=$a.GetType().Name;text=$a.Extent.Text})} [void]$elems.Add($ceData) } return $elems}
function Get-RawRedirections { param($Redirections) $result = [System.Collections.ArrayList]::new() foreach ($redir in $Redirections) { $redirData = @{ type = $redir.GetType().Name } if ($redir -is [System.Management.Automation.Language.FileRedirectionAst]) { $redirData.append = [bool]$redir.Append $redirData.fromStream = $redir.FromStream.ToString() $redirData.locationText = $redir.Location.Extent.Text } [void]$result.Add($redirData) } return $result}
function Get-SecurityPatterns($A) { $p = @{} foreach ($n in $A.FindAll({ param($x) $x -is [System.Management.Automation.Language.MemberExpressionAst] -or $x -is [System.Management.Automation.Language.SubExpressionAst] -or $x -is [System.Management.Automation.Language.ArrayExpressionAst] -or $x -is [System.Management.Automation.Language.ExpandableStringExpressionAst] -or $x -is [System.Management.Automation.Language.ScriptBlockExpressionAst] -or $x -is [System.Management.Automation.Language.ParenExpressionAst] }, $true)) { switch ($n.GetType().Name) { 'InvokeMemberExpressionAst' { $p.hasMemberInvocations = $true } 'MemberExpressionAst' { $p.hasMemberInvocations = $true } 'SubExpressionAst' { $p.hasSubExpressions = $true } 'ArrayExpressionAst' { $p.hasSubExpressions = $true } 'ParenExpressionAst' { $p.hasSubExpressions = $true } 'ExpandableStringExpressionAst' { $p.hasExpandableStrings = $true } 'ScriptBlockExpressionAst' { $p.hasScriptBlocks = $true } }} if ($p.Count -gt 0) { return $p } return $null}
$varExprs = $ast.FindAll({ param($node) $node -is [System.Management.Automation.Language.VariableExpressionAst] }, $true)foreach ($v in $varExprs) { [void]$allVariables.Add(@{ path = $v.VariablePath.ToString() isSplatted = [bool]$v.Splatted })}
$typeLiterals = [System.Collections.ArrayList]::new()foreach ($t in $ast.FindAll({ param($n) $n -is [System.Management.Automation.Language.TypeExpressionAst] -or $n -is [System.Management.Automation.Language.TypeConstraintAst]}, $true)) { [void]$typeLiterals.Add($t.TypeName.FullName) }
$hasStopParsing = $false$tk = [System.Management.Automation.Language.TokenKind]foreach ($tok in $tokens) { if ($tok.Kind -eq $tk::MinusMinus) { $hasStopParsing = $true; break } if ($tok.Kind -eq $tk::Generic -and ($tok.Text -replace '[\u2013\u2014\u2015]','-') -eq '--%') { $hasStopParsing = $true; break }}
$statements = [System.Collections.ArrayList]::new()
function Process-BlockStatements { param($Block) if (-not $Block) { return }
foreach ($stmt in $Block.Statements) { $statement = @{ type = $stmt.GetType().Name text = $stmt.Extent.Text }
if ($stmt -is [System.Management.Automation.Language.PipelineAst]) { $elements = [System.Collections.ArrayList]::new() foreach ($element in $stmt.PipelineElements) { $elemData = @{ type = $element.GetType().Name text = $element.Extent.Text }
if ($element -is [System.Management.Automation.Language.CommandAst]) { $elemData.commandElements = @(Get-RawCommandElements -CmdAst $element) $elemData.redirections = @(Get-RawRedirections -Redirections $element.Redirections) } elseif ($element -is [System.Management.Automation.Language.CommandExpressionAst]) { $elemData.expressionType = $element.Expression.GetType().Name $elemData.redirections = @(Get-RawRedirections -Redirections $element.Redirections) }
[void]$elements.Add($elemData) } $statement.elements = @($elements)
$allNestedCmds = $stmt.FindAll( { param($node) $node -is [System.Management.Automation.Language.CommandAst] }, $true ) $nestedCmds = [System.Collections.ArrayList]::new() foreach ($cmd in $allNestedCmds) { if ($cmd.Parent -eq $stmt) { continue } $nested = @{ type = $cmd.GetType().Name text = $cmd.Extent.Text commandElements = @(Get-RawCommandElements -CmdAst $cmd) redirections = @(Get-RawRedirections -Redirections $cmd.Redirections) } [void]$nestedCmds.Add($nested) } if ($nestedCmds.Count -gt 0) { $statement.nestedCommands = @($nestedCmds) } $r = $stmt.FindAll({param($n) $n -is [System.Management.Automation.Language.FileRedirectionAst]}, $true) if ($r.Count -gt 0) { $rr = @(Get-RawRedirections -Redirections $r) $statement.redirections = if ($statement.redirections) { @($statement.redirections) + $rr } else { $rr } } } else { $nestedCmdAsts = $stmt.FindAll( { param($node) $node -is [System.Management.Automation.Language.CommandAst] }, $true ) $nested = [System.Collections.ArrayList]::new() foreach ($cmd in $nestedCmdAsts) { [void]$nested.Add(@{ type = 'CommandAst' text = $cmd.Extent.Text commandElements = @(Get-RawCommandElements -CmdAst $cmd) redirections = @(Get-RawRedirections -Redirections $cmd.Redirections) }) } if ($nested.Count -gt 0) { $statement.nestedCommands = @($nested) } $r = $stmt.FindAll({param($n) $n -is [System.Management.Automation.Language.FileRedirectionAst]}, $true) if ($r.Count -gt 0) { $statement.redirections = @(Get-RawRedirections -Redirections $r) } }
$sp = Get-SecurityPatterns $stmt if ($sp) { $statement.securityPatterns = $sp }
[void]$statements.Add($statement) }
if ($Block.Traps) { foreach ($trap in $Block.Traps) { $statement = @{ type = 'TrapStatementAst' text = $trap.Extent.Text } $nestedCmdAsts = $trap.FindAll( { param($node) $node -is [System.Management.Automation.Language.CommandAst] }, $true ) $nestedCmds = [System.Collections.ArrayList]::new() foreach ($cmd in $nestedCmdAsts) { $nested = @{ type = $cmd.GetType().Name text = $cmd.Extent.Text commandElements = @(Get-RawCommandElements -CmdAst $cmd) redirections = @(Get-RawRedirections -Redirections $cmd.Redirections) } [void]$nestedCmds.Add($nested) } if ($nestedCmds.Count -gt 0) { $statement.nestedCommands = @($nestedCmds) } $r = $trap.FindAll({param($n) $n -is [System.Management.Automation.Language.FileRedirectionAst]}, $true) if ($r.Count -gt 0) { $statement.redirections = @(Get-RawRedirections -Redirections $r) } $sp = Get-SecurityPatterns $trap if ($sp) { $statement.securityPatterns = $sp } [void]$statements.Add($statement) } }}
Process-BlockStatements -Block $ast.BeginBlockProcess-BlockStatements -Block $ast.ProcessBlockProcess-BlockStatements -Block $ast.EndBlockProcess-BlockStatements -Block $ast.CleanBlockProcess-BlockStatements -Block $ast.DynamicParamBlock
if ($ast.ParamBlock) { $pb = $ast.ParamBlock $pn = [System.Collections.ArrayList]::new() foreach ($c in $pb.FindAll({param($n) $n -is [System.Management.Automation.Language.CommandAst]}, $true)) { [void]$pn.Add(@{type='CommandAst';text=$c.Extent.Text;commandElements=@(Get-RawCommandElements -CmdAst $c);redirections=@(Get-RawRedirections -Redirections $c.Redirections)}) } $pr = $pb.FindAll({param($n) $n -is [System.Management.Automation.Language.FileRedirectionAst]}, $true) $ps = Get-SecurityPatterns $pb if ($pn.Count -gt 0 -or $pr.Count -gt 0 -or $ps) { $st = @{type='ParamBlockAst';text=$pb.Extent.Text} if ($pn.Count -gt 0) { $st.nestedCommands = @($pn) } if ($pr.Count -gt 0) { $st.redirections = @(Get-RawRedirections -Redirections $pr) } if ($ps) { $st.securityPatterns = $ps } [void]$statements.Add($st) }}
$hasUsingStatements = $ast.UsingStatements -and $ast.UsingStatements.Count -gt 0$hasScriptRequirements = $ast.ScriptRequirements -ne $null
$output = @{ valid = ($parseErrors.Count -eq 0) errors = @($parseErrors | ForEach-Object { @{ message = $_.Message errorId = $_.ErrorId } }) statements = @($statements) variables = @($allVariables) hasStopParsing = $hasStopParsing originalCommand = $Command typeLiterals = @($typeLiterals) hasUsingStatements = [bool]$hasUsingStatements hasScriptRequirements = [bool]$hasScriptRequirements}
$output | ConvertTo-Json -Depth 10 -Compress`
// ---------------------------------------------------------------------------// Windows CreateProcess has a 32,767 char command-line limit. The encoding// chain is:// command (N UTF-8 bytes) → Base64 (~4N/3 chars) → $EncodedCommand = '...'\n// → full script (wrapper + PARSE_SCRIPT_BODY) → UTF-16LE (2× bytes)// → Base64 (4/3× chars) → -EncodedCommand argv// Final cmdline ≈ argv_overhead + (wrapper + 4N/3 + body) × 8/3//// Solving for N (UTF-8 bytes) with a 32,767 cap:// script_budget = (32767 - argv_overhead) × 3/8// cmd_b64_budget = script_budget - PARSE_SCRIPT_BODY.length - wrapper// N = cmd_b64_budget × 3/4 - safety_margin//// SECURITY: N is a UTF-8 BYTE budget, not a UTF-16 code-unit budget. The// length gate MUST measure Buffer.byteLength(command, 'utf8'), not// command.length. A BMP character in U+0800–U+FFFF (CJK ideographs, most// non-Latin scripts) is 1 UTF-16 code unit but 3 UTF-8 bytes. With// PARSE_SCRIPT_BODY ≈ 10.6K, N ≈ 1,092 bytes. Comparing against .length// permits a 1,092-code-unit pure-CJK command (≈3,276 UTF-8 bytes) → inner// base64 ≈ 4,368 chars → final argv ≈ 40K chars, overflowing 32,767 by// ~7.4K. CreateProcess fails → valid:false → parse-fail degradation (deny// rules silently downgrade to ask). Finding #36.//// COMPUTED from PARSE_SCRIPT_BODY.length so it cannot drift. The prior// hardcoded value (4,500) was derived from a ~6K body estimate; the body is// actually ~11K chars, so the real ceiling was ~1,850. Commands in the// 1,850–4,500 range passed this gate but then failed CreateProcess on// Windows, returning valid=false and skipping all AST-based security checks.//// Unix argv limits are typically 2MB+ (ARG_MAX) with ~128KB per-argument// limit (MAX_ARG_STRLEN on Linux; macOS has no per-arg limit below ARG_MAX).// At MAX=4,500 the -EncodedCommand argument is ~45KB — well under either.// Applying the Windows-derived limit on Unix would REGRESS: commands in the// ~1K–4.5K range previously parsed successfully and reached the sub-command// deny loop at powershellPermissions.ts; rejecting them pre-spawn degrades// user-configured deny rules from deny→ask for compound commands with a// denied cmdlet buried mid-script. So the Windows limit is platform-gated.//// If the Windows limit becomes too restrictive, switch to -File with a temp// file for large inputs.// ---------------------------------------------------------------------------const WINDOWS_ARGV_CAP = 32_767// pwsh path + " -NoProfile -NonInteractive -NoLogo -EncodedCommand " +// argv quoting. A long Windows pwsh path (C:\Program Files\PowerShell\7\// pwsh.exe) + flags is ~95 chars; 200 leaves headroom for unusual installs.const FIXED_ARGV_OVERHEAD = 200// "$EncodedCommand = '" + "'\n" wrapper around the user command's base64const ENCODED_CMD_WRAPPER = `$EncodedCommand = ''\n`.length// Margin for base64 padding rounding (≤4 chars at each of 2 levels) and minor// estimation drift. Multibyte expansion is NOT absorbed here — the gate// measures actual UTF-8 bytes (Buffer.byteLength), not code units.const SAFETY_MARGIN = 100const SCRIPT_CHARS_BUDGET = ((WINDOWS_ARGV_CAP - FIXED_ARGV_OVERHEAD) * 3) / 8const CMD_B64_BUDGET = SCRIPT_CHARS_BUDGET - PARSE_SCRIPT_BODY.length - ENCODED_CMD_WRAPPER// Exported for drift-guard tests (the drift-prone value is the Windows one).// Unit: UTF-8 BYTES. Compare against Buffer.byteLength, not .length.export const WINDOWS_MAX_COMMAND_LENGTH = Math.max( 0, Math.floor((CMD_B64_BUDGET * 3) / 4) - SAFETY_MARGIN,)// Pre-existing value, known to work on Unix. See comment above re: why the// Windows derivation must NOT be applied here. Unit: UTF-8 BYTES — for ASCII// commands (the common case) bytes==chars so no regression; for multibyte// commands this is slightly tighter but still far below Unix ARG_MAX (~128KB// per-arg), so the argv spawn cannot overflow.const UNIX_MAX_COMMAND_LENGTH = 4_500// Unit: UTF-8 BYTES (see SECURITY note above).export const MAX_COMMAND_LENGTH = process.platform === 'win32' ? WINDOWS_MAX_COMMAND_LENGTH : UNIX_MAX_COMMAND_LENGTH
const INVALID_RESULT_BASE: Omit< ParsedPowerShellCommand, 'errors' | 'originalCommand'> = { valid: false, statements: [], variables: [], hasStopParsing: false,}
function makeInvalidResult( command: string, message: string, errorId: string,): ParsedPowerShellCommand { return { ...INVALID_RESULT_BASE, errors: [{ message, errorId }], originalCommand: command, }}
/** * Base64-encode a string as UTF-16LE, which is the encoding required by * PowerShell's -EncodedCommand parameter. */function toUtf16LeBase64(text: string): string { if (typeof Buffer !== 'undefined') { return Buffer.from(text, 'utf16le').toString('base64') } // Fallback for non-Node environments const bytes: number[] = [] for (let i = 0; i < text.length; i++) { const code = text.charCodeAt(i) bytes.push(code & 0xff, (code >> 8) & 0xff) } return btoa(bytes.map(b => String.fromCharCode(b)).join(''))}
/** * Build the full PowerShell script that parses a command. * The user command is Base64-encoded (UTF-8) and embedded in a variable * to prevent injection attacks. */function buildParseScript(command: string): string { const encoded = typeof Buffer !== 'undefined' ? Buffer.from(command, 'utf8').toString('base64') : btoa( new TextEncoder() .encode(command) .reduce((s, b) => s + String.fromCharCode(b), ''), ) return `$EncodedCommand = '${encoded}'\n${PARSE_SCRIPT_BODY}`}
/** * Ensure a value is an array. PowerShell 5.1's ConvertTo-Json may unwrap * single-element arrays into plain objects. */function ensureArray<T>(value: T | T[] | undefined | null): T[] { if (value === undefined || value === null) { return [] } return Array.isArray(value) ? value : [value]}
/** Map raw .NET AST type name to our StatementType union */// exported for testingexport function mapStatementType(rawType: string): StatementType { switch (rawType) { case 'PipelineAst': return 'PipelineAst' case 'PipelineChainAst': return 'PipelineChainAst' case 'AssignmentStatementAst': return 'AssignmentStatementAst' case 'IfStatementAst': return 'IfStatementAst' case 'ForStatementAst': return 'ForStatementAst' case 'ForEachStatementAst': return 'ForEachStatementAst' case 'WhileStatementAst': return 'WhileStatementAst' case 'DoWhileStatementAst': return 'DoWhileStatementAst' case 'DoUntilStatementAst': return 'DoUntilStatementAst' case 'SwitchStatementAst': return 'SwitchStatementAst' case 'TryStatementAst': return 'TryStatementAst' case 'TrapStatementAst': return 'TrapStatementAst' case 'FunctionDefinitionAst': return 'FunctionDefinitionAst' case 'DataStatementAst': return 'DataStatementAst' default: return 'UnknownStatementAst' }}
/** Map raw .NET AST type name to our CommandElementType union */// exported for testingexport function mapElementType( rawType: string, expressionType?: string,): CommandElementType { switch (rawType) { case 'ScriptBlockExpressionAst': return 'ScriptBlock' case 'SubExpressionAst': case 'ArrayExpressionAst': // SECURITY: ArrayExpressionAst (@()) is a sibling of SubExpressionAst, // not a subclass. Both evaluate arbitrary pipelines with side effects: // Get-ChildItem @(Remove-Item ./data) runs Remove-Item inside @(). // Map both to SubExpression so hasSubExpressions fires and isReadOnlyCommand // rejects (it doesn't check nestedCommands, only pipeline.commands[]). return 'SubExpression' case 'ExpandableStringExpressionAst': return 'ExpandableString' case 'InvokeMemberExpressionAst': case 'MemberExpressionAst': return 'MemberInvocation' case 'VariableExpressionAst': return 'Variable' case 'StringConstantExpressionAst': case 'ConstantExpressionAst': // ConstantExpressionAst covers numeric literals (5, 3.14). For // permission purposes a numeric literal is as safe as a string // literal — it's an inert value, not code. Without this mapping, // `-Seconds:5` produced children[0].type='Other' and consumers // checking `children.some(c => c.type !== 'StringConstant')` would // false-positive ask on harmless numeric args. return 'StringConstant' case 'CommandParameterAst': return 'Parameter' case 'ParenExpressionAst': return 'SubExpression' case 'CommandExpressionAst': // Delegate to the wrapped expression type so we catch SubExpressionAst, // ExpandableStringExpressionAst, ScriptBlockExpressionAst, etc. // without maintaining a manual list. Falls through to 'Other' if the // inner type is unrecognised. if (expressionType) { return mapElementType(expressionType) } return 'Other' default: return 'Other' }}
/** Classify command name as cmdlet, application, or unknown */// exported for testingexport function classifyCommandName( name: string,): 'cmdlet' | 'application' | 'unknown' { if (/^[A-Za-z]+-[A-Za-z][A-Za-z0-9_]*$/.test(name)) { return 'cmdlet' } if (/[.\\/]/.test(name)) { return 'application' } return 'unknown'}
/** Strip module prefix from command name (e.g. "Microsoft.PowerShell.Utility\\Invoke-Expression" -> "Invoke-Expression") */// exported for testingexport function stripModulePrefix(name: string): string { const idx = name.lastIndexOf('\\') if (idx < 0) return name // Don't strip file paths: drive letters (C:\...), UNC paths (\\server\...), or relative paths (.\, ..\) if ( /^[A-Za-z]:/.test(name) || name.startsWith('\\\\') || name.startsWith('.\\') || name.startsWith('..\\') ) return name return name.substring(idx + 1)}
/** Transform a raw CommandAst pipeline element into ParsedCommandElement */// exported for testingexport function transformCommandAst( raw: RawPipelineElement,): ParsedCommandElement { const cmdElements = ensureArray(raw.commandElements) let name = '' const args: string[] = [] const elementTypes: CommandElementType[] = [] const children: (CommandElementChild[] | undefined)[] = [] let hasChildren = false
// SECURITY: nameType MUST be computed from the raw name (before // stripModulePrefix). classifyCommandName('scripts\\Get-Process') returns // 'application' (contains \\) — the correct answer, since PowerShell resolves // this as a file path. After stripping it becomes 'Get-Process' which // classifies as 'cmdlet' — wrong, and allowlist checks would trust it. // Auto-allow paths gate on nameType !== 'application' to catch this. // name (stripped) is still used for deny-rule matching symmetry, which is // fail-safe: deny rules over-match (Module\\Remove-Item still hits a // Remove-Item deny), allow rules are separately gated by nameType. let nameType: 'cmdlet' | 'application' | 'unknown' = 'unknown' if (cmdElements.length > 0) { const first = cmdElements[0]! // SECURITY: only trust .value for string-literal element types with a // string-typed value. Numeric ConstantExpressionAst (e.g. `& 1`) emits an // integer .value that crashes stripModulePrefix() → parser falls through // to passthrough. For non-string-literal or non-string .value, use .text. const isFirstStringLiteral = first.type === 'StringConstantExpressionAst' || first.type === 'ExpandableStringExpressionAst' const rawNameUnstripped = isFirstStringLiteral && typeof first.value === 'string' ? first.value : first.text // SECURITY: strip surrounding quotes from the command name. When .value is // unavailable (no StaticType on the raw node), .text preserves quotes — // `& 'Invoke-Expression' 'x'` yields "'Invoke-Expression'". Stripping here // at the source means every downstream reader of element.name (deny-rule // matching, GIT_SAFETY_WRITE_CMDLETS lookup, resolveToCanonical, etc.) // sees the bare cmdlet name. No-op when .value already stripped. const rawName = rawNameUnstripped.replace(/^['"]|['"]$/g, '') // SECURITY: PowerShell built-in cmdlet names are ASCII-only. Non-ASCII // characters in cmdlet position are inherently suspicious — .NET // OrdinalIgnoreCase folds U+017F (ſ) → S and U+0131 (ı) → I per // UnicodeData.txt SimpleUppercaseMapping, so PowerShell resolves // `ſtart-proceſſ` → Start-Process at runtime. JS .toLowerCase() does NOT // fold these (ſ is already lowercase), so every downstream name // comparison (NEVER_SUGGEST, deny-rule strEquals, resolveToCanonical, // security validators) misses. Force 'application' to gate auto-allow // (blocks at the nameType !== 'application' checks). Finding #31. // Verified on Windows (pwsh 7.x, 2026-03): ſtart-proceſſ does NOT resolve. // Retained as defense-in-depth against future .NET/PS behavior changes // or module-provided command resolution hooks. if (/[\u0080-\uFFFF]/.test(rawName)) { nameType = 'application' } else { nameType = classifyCommandName(rawName) } name = stripModulePrefix(rawName) elementTypes.push(mapElementType(first.type, first.expressionType))
for (let i = 1; i < cmdElements.length; i++) { const ce = cmdElements[i]! // Use resolved .value for string constants (strips quotes, resolves // backtick escapes like `n -> newline) but keep raw .text for parameters // (where .value loses the dash prefix, e.g. '-Path' -> 'Path'), // variables, and other non-string types. const isStringLiteral = ce.type === 'StringConstantExpressionAst' || ce.type === 'ExpandableStringExpressionAst' args.push(isStringLiteral && ce.value != null ? ce.value : ce.text) elementTypes.push(mapElementType(ce.type, ce.expressionType)) // Map raw children (CommandParameterAst.Argument) through // mapElementType so consumers see 'Variable', 'StringConstant', etc. const rawChildren = ensureArray(ce.children) if (rawChildren.length > 0) { hasChildren = true children.push( rawChildren.map(c => ({ type: mapElementType(c.type), text: c.text, })), ) } else { children.push(undefined) } } }
const result: ParsedCommandElement = { name, nameType, elementType: 'CommandAst', args, text: raw.text, elementTypes, ...(hasChildren ? { children } : {}), }
// Preserve redirections from nested commands (e.g., in && / || chains) const rawRedirs = ensureArray(raw.redirections) if (rawRedirs.length > 0) { result.redirections = rawRedirs.map(transformRedirection) }
return result}
/** Transform a non-CommandAst pipeline element into ParsedCommandElement */// exported for testingexport function transformExpressionElement( raw: RawPipelineElement,): ParsedCommandElement { const elementType: PipelineElementType = raw.type === 'ParenExpressionAst' ? 'ParenExpressionAst' : 'CommandExpressionAst' const elementTypes: CommandElementType[] = [ mapElementType(raw.type, raw.expressionType), ]
return { name: raw.text, nameType: 'unknown', elementType, args: [], text: raw.text, elementTypes, }}
/** Map raw redirection to ParsedRedirection */// exported for testingexport function transformRedirection(raw: RawRedirection): ParsedRedirection { if (raw.type === 'MergingRedirectionAst') { return { operator: '2>&1', target: '', isMerging: true } }
const append = raw.append ?? false const fromStream = raw.fromStream ?? 'Output'
let operator: ParsedRedirection['operator'] if (append) { switch (fromStream) { case 'Error': operator = '2>>' break case 'All': operator = '*>>' break default: operator = '>>' break } } else { switch (fromStream) { case 'Error': operator = '2>' break case 'All': operator = '*>' break default: operator = '>' break } }
return { operator, target: raw.locationText ?? '', isMerging: false }}
/** Transform a raw statement into ParsedStatement */// exported for testingexport function transformStatement(raw: RawStatement): ParsedStatement { const statementType = mapStatementType(raw.type) const commands: ParsedCommandElement[] = [] const redirections: ParsedRedirection[] = []
if (raw.elements) { // PipelineAst: walk pipeline elements for (const elem of ensureArray(raw.elements)) { if (elem.type === 'CommandAst') { commands.push(transformCommandAst(elem)) for (const redir of ensureArray(elem.redirections)) { redirections.push(transformRedirection(redir)) } } else { commands.push(transformExpressionElement(elem)) // SECURITY: CommandExpressionAst also carries .Redirections (inherited // from CommandBaseAst). `1 > /tmp/evil.txt` is a CommandExpressionAst // with a FileRedirectionAst. Must extract here or getFileRedirections() // misses it and compound commands like `Get-ChildItem; 1 > /tmp/x` // auto-allow at step 5 (only Get-ChildItem is checked). for (const redir of ensureArray(elem.redirections)) { redirections.push(transformRedirection(redir)) } } } // SECURITY: The PS1 PipelineAst branch does a deep FindAll for // FileRedirectionAst to catch redirections hidden inside: // - colon-bound ParenExpressionAst args: -Name:('payload' > file) // - hashtable value statements: @{k='payload' > ~/.bashrc} // Both are invisible at the element level — the redirection's parent // is a child of CommandParameterAst / CommandExpressionAst, not a // separate pipeline element. Merge into statement-level redirections. // // The FindAll ALSO re-discovers direct-element redirections already // captured in the per-element loop above. Dedupe by (operator, target) // so tests and consumers see the real count. const seen = new Set(redirections.map(r => `${r.operator}\0${r.target}`)) for (const redir of ensureArray(raw.redirections)) { const r = transformRedirection(redir) const key = `${r.operator}\0${r.target}` if (!seen.has(key)) { seen.add(key) redirections.push(r) } } } else { // Non-pipeline statement: add synthetic command entry with full text commands.push({ name: raw.text, nameType: 'unknown', elementType: 'CommandExpressionAst', args: [], text: raw.text, }) // SECURITY: The PS1 else-branch does a direct recursive FindAll on // FileRedirectionAst to catch expression redirections inside control flow // (if/for/foreach/while/switch/try/trap/&& and ||). The CommandAst FindAll // above CANNOT see these: in if ($x) { 1 > /tmp/evil }, the literal 1 with // its attached redirection is a CommandExpressionAst — a SIBLING of // CommandAst in the type hierarchy, not a subclass. So nestedCommands never // contains it, and without this hoist the redirection is invisible to // getFileRedirections → step 4.6 misses it → compound commands like // `Get-Process && 1 > /tmp/evil` auto-allow at step 5 (only Get-Process // is checked, allowlisted). // // Finding FileRedirectionAst DIRECTLY (rather than finding CommandExpressionAst // and extracting .Redirections) is both simpler and more robust: it catches // redirections on any node type, including ones we don't know about yet. // // Double-counts redirections already on nested CommandAst commands (those are // extracted at line ~395 into nestedCommands[i].redirections AND found again // here). Harmless: step 4.6 only checks fileRedirections.length > 0, not // the exact count. No code does arithmetic on redirection counts. // // PS1 SIZE NOTE: The full rationale lives here (TS), not in the PS1 script, // because PS1 comments bloat the -EncodedCommand payload and push the // Windows CreateProcess 32K limit. Keep PS1 comments terse; point them here. for (const redir of ensureArray(raw.redirections)) { redirections.push(transformRedirection(redir)) } }
let nestedCommands: ParsedCommandElement[] | undefined const rawNested = ensureArray(raw.nestedCommands) if (rawNested.length > 0) { nestedCommands = rawNested.map(transformCommandAst) }
const result: ParsedStatement = { statementType, commands, redirections, text: raw.text, nestedCommands, }
if (raw.securityPatterns) { result.securityPatterns = raw.securityPatterns }
return result}
/** Transform the complete raw PS output into ParsedPowerShellCommand */function transformRawOutput(raw: RawParsedOutput): ParsedPowerShellCommand { const result: ParsedPowerShellCommand = { valid: raw.valid, errors: ensureArray(raw.errors), statements: ensureArray(raw.statements).map(transformStatement), variables: ensureArray(raw.variables), hasStopParsing: raw.hasStopParsing, originalCommand: raw.originalCommand, } const tl = ensureArray(raw.typeLiterals) if (tl.length > 0) { result.typeLiterals = tl } if (raw.hasUsingStatements) { result.hasUsingStatements = true } if (raw.hasScriptRequirements) { result.hasScriptRequirements = true } return result}
/** * Parse a PowerShell command using the native AST parser. * Spawns pwsh to parse the command and returns structured results. * Results are memoized by command string. * * @param command - The PowerShell command to parse * @returns Parsed command structure, or a result with valid=false on failure */async function parsePowerShellCommandImpl( command: string,): Promise<ParsedPowerShellCommand> { // SECURITY: MAX_COMMAND_LENGTH is a UTF-8 BYTE budget (see derivation at the // constant definition). command.length counts UTF-16 code units; a CJK // character is 1 code unit but 3 UTF-8 bytes, so .length under-reports by // up to 3× and allows argv overflow on Windows → CreateProcess fails → // valid:false → deny rules degrade to ask. Finding #36. const commandBytes = Buffer.byteLength(command, 'utf8') if (commandBytes > MAX_COMMAND_LENGTH) { logForDebugging( `PowerShell parser: command too long (${commandBytes} bytes, max ${MAX_COMMAND_LENGTH})`, ) return makeInvalidResult( command, `Command too long for parsing (${commandBytes} bytes). Maximum supported length is ${MAX_COMMAND_LENGTH} bytes.`, 'CommandTooLong', ) }
const pwshPath = await getCachedPowerShellPath() if (!pwshPath) { return makeInvalidResult( command, 'PowerShell is not available', 'NoPowerShell', ) }
const script = buildParseScript(command)
// Pass the script to PowerShell via -EncodedCommand. // -EncodedCommand takes a Base64-encoded UTF-16LE string and executes it, // which avoids: (1) stdin interactive-mode issues where -File - produces // PS prompts and ANSI escapes in stdout, (2) command-line escaping issues, // (3) temp files. The script itself is large but well within OS arg limits // (Windows: 32K chars, Unix: typically 2MB+). const encodedScript = toUtf16LeBase64(script) const args = [ '-NoProfile', '-NonInteractive', '-NoLogo', '-EncodedCommand', encodedScript, ]
// Spawn pwsh with one retry on timeout. On loaded CI runners (Windows // especially), pwsh spawn + .NET JIT + ParseInput occasionally exceeds 5s // even after CAN_SPAWN_PARSE_SCRIPT() warms the JIT. execa kills the process // but exitCode is undefined, which the old code reported as the misleading // "pwsh exited with code 1:" with empty stderr. A single retry absorbs // transient load spikes; a double timeout is reported as PwshTimeout. const parseTimeoutMs = getParseTimeoutMs() let stdout = '' let stderr = '' let code: number | null = null let timedOut = false for (let attempt = 0; attempt < 2; attempt++) { try { const result = await execa(pwshPath, args, { timeout: parseTimeoutMs, reject: false, }) stdout = result.stdout stderr = result.stderr timedOut = result.timedOut code = result.failed ? (result.exitCode ?? 1) : 0 } catch (e: unknown) { logForDebugging( `PowerShell parser: failed to spawn pwsh: ${e instanceof Error ? e.message : e}`, ) return makeInvalidResult( command, `Failed to spawn PowerShell: ${e instanceof Error ? e.message : e}`, 'PwshSpawnError', ) } if (!timedOut) break logForDebugging( `PowerShell parser: pwsh timed out after ${parseTimeoutMs}ms (attempt ${attempt + 1})`, ) }
if (timedOut) { return makeInvalidResult( command, `pwsh timed out after ${parseTimeoutMs}ms (2 attempts)`, 'PwshTimeout', ) }
if (code !== 0) { logForDebugging( `PowerShell parser: pwsh exited with code ${code}, stderr: ${stderr}`, ) return makeInvalidResult( command, `pwsh exited with code ${code}: ${stderr}`, 'PwshError', ) }
const trimmed = stdout.trim() if (!trimmed) { logForDebugging('PowerShell parser: empty stdout from pwsh') return makeInvalidResult( command, 'No output from PowerShell parser', 'EmptyOutput', ) }
try { const raw = jsonParse(trimmed) as RawParsedOutput return transformRawOutput(raw) } catch { logForDebugging( `PowerShell parser: invalid JSON output: ${trimmed.slice(0, 200)}`, ) return makeInvalidResult( command, 'Invalid JSON from PowerShell parser', 'InvalidJson', ) }}
// Error IDs from makeInvalidResult that represent transient process failures.// These should be evicted from the cache so subsequent calls can retry.// Deterministic failures (CommandTooLong, syntax errors from successful parses)// should stay cached since retrying would produce the same result.const TRANSIENT_ERROR_IDS = new Set([ 'PwshSpawnError', 'PwshError', 'PwshTimeout', 'EmptyOutput', 'InvalidJson',])
const parsePowerShellCommandCached = memoizeWithLRU( (command: string) => { const promise = parsePowerShellCommandImpl(command) // Evict transient failures after resolution so they can be retried. // The current caller still receives the cached promise for this call, // ensuring concurrent callers share the same result. void promise.then(result => { if ( !result.valid && TRANSIENT_ERROR_IDS.has(result.errors[0]?.errorId ?? '') ) { parsePowerShellCommandCached.cache.delete(command) } }) return promise }, (command: string) => command, 256,)export { parsePowerShellCommandCached as parsePowerShellCommand }
// ---------------------------------------------------------------------------// Analysis helpers — derived from the parsed AST structure.// ---------------------------------------------------------------------------
/** * Security-relevant flags derived from the parsed AST. */type SecurityFlags = { /** Contains $(...) subexpression */ hasSubExpressions: boolean /** Contains { ... } script block expressions */ hasScriptBlocks: boolean /** Contains @variable splatting */ hasSplatting: boolean /** Contains expandable strings with embedded expressions ("...$()...") */ hasExpandableStrings: boolean /** Contains .NET method invocations ([Type]::Method or $obj.Method()) */ hasMemberInvocations: boolean /** Contains variable assignments ($x = ...) */ hasAssignments: boolean /** Uses stop-parsing token (--%) */ hasStopParsing: boolean}
/** * Common PowerShell aliases mapped to their canonical cmdlet names. * Uses Object.create(null) to prevent prototype-chain pollution — attacker-controlled * command names like 'constructor' or '__proto__' must return undefined, not inherited * Object.prototype properties. */export const COMMON_ALIASES: Record<string, string> = Object.assign( Object.create(null) as Record<string, string>, { // Directory listing ls: 'Get-ChildItem', dir: 'Get-ChildItem', gci: 'Get-ChildItem', // Content cat: 'Get-Content', type: 'Get-Content', gc: 'Get-Content', // Navigation cd: 'Set-Location', sl: 'Set-Location', chdir: 'Set-Location', pushd: 'Push-Location', popd: 'Pop-Location', pwd: 'Get-Location', gl: 'Get-Location', // Items gi: 'Get-Item', gp: 'Get-ItemProperty', ni: 'New-Item', mkdir: 'New-Item', // `md` is PowerShell's built-in alias for `mkdir`. resolveToCanonical is // single-hop (no md→mkdir→New-Item chaining), so it needs its own entry // or `md /etc/x` falls through while `mkdir /etc/x` is caught. md: 'New-Item', ri: 'Remove-Item', del: 'Remove-Item', rd: 'Remove-Item', rmdir: 'Remove-Item', rm: 'Remove-Item', erase: 'Remove-Item', mi: 'Move-Item', mv: 'Move-Item', move: 'Move-Item', ci: 'Copy-Item', cp: 'Copy-Item', copy: 'Copy-Item', cpi: 'Copy-Item', si: 'Set-Item', rni: 'Rename-Item', ren: 'Rename-Item', // Process ps: 'Get-Process', gps: 'Get-Process', kill: 'Stop-Process', spps: 'Stop-Process', start: 'Start-Process', saps: 'Start-Process', sajb: 'Start-Job', ipmo: 'Import-Module', // Output echo: 'Write-Output', write: 'Write-Output', sleep: 'Start-Sleep', // Help help: 'Get-Help', man: 'Get-Help', gcm: 'Get-Command', // Service gsv: 'Get-Service', // Variables gv: 'Get-Variable', sv: 'Set-Variable', // History h: 'Get-History', history: 'Get-History', // Invoke iex: 'Invoke-Expression', iwr: 'Invoke-WebRequest', irm: 'Invoke-RestMethod', icm: 'Invoke-Command', ii: 'Invoke-Item', // PSSession — remote code execution surface nsn: 'New-PSSession', etsn: 'Enter-PSSession', exsn: 'Exit-PSSession', gsn: 'Get-PSSession', rsn: 'Remove-PSSession', // Misc cls: 'Clear-Host', clear: 'Clear-Host', select: 'Select-Object', where: 'Where-Object', foreach: 'ForEach-Object', '%': 'ForEach-Object', '?': 'Where-Object', measure: 'Measure-Object', ft: 'Format-Table', fl: 'Format-List', fw: 'Format-Wide', oh: 'Out-Host', ogv: 'Out-GridView', // SECURITY: The following aliases are deliberately omitted because PS Core 6+ // removed them (they collide with native executables). Our allowlist logic // resolves aliases BEFORE checking safety — if we map 'sort' → 'Sort-Object' // but PowerShell 7/Windows actually runs sort.exe, we'd auto-allow the wrong // program. // 'sc' → sc.exe (Service Controller) — e.g. `sc config Svc binpath= ...` // 'sort' → sort.exe — e.g. `sort /O C:\evil.txt` (arbitrary file write) // 'curl' → curl.exe (shipped with Windows 10 1803+) // 'wget' → wget.exe (if installed) // Prefer to leave ambiguous aliases unmapped — users can write the full name. // If adding aliases that resolve to SAFE_OUTPUT_CMDLETS or // ACCEPT_EDITS_ALLOWED_CMDLETS, verify no native .exe collision on PS Core. ac: 'Add-Content', clc: 'Clear-Content', // Write/export: tee-object/export-csv are in // CMDLET_PATH_CONFIG so path-level Edit denies fire on the full cmdlet name, // but PowerShell's built-in aliases fell through to ask-then-approve because // resolveToCanonical couldn't resolve them). Neither tee-object nor // export-csv is in SAFE_OUTPUT_CMDLETS or ACCEPT_EDITS_ALLOWED_CMDLETS, so // the native-exe collision warning above doesn't apply — on Linux PS Core // where `tee` runs /usr/bin/tee, that binary also writes to its positional // file arg and we correctly extract+check it. tee: 'Tee-Object', epcsv: 'Export-Csv', sp: 'Set-ItemProperty', rp: 'Remove-ItemProperty', cli: 'Clear-Item', epal: 'Export-Alias', // Text search sls: 'Select-String', },)
const DIRECTORY_CHANGE_CMDLETS = new Set([ 'set-location', 'push-location', 'pop-location',])
const DIRECTORY_CHANGE_ALIASES = new Set(['cd', 'sl', 'chdir', 'pushd', 'popd'])
/** * Get all command names across all statements, pipeline segments, and nested commands. * Returns lowercased names for case-insensitive comparison. */// exported for testingexport function getAllCommandNames(parsed: ParsedPowerShellCommand): string[] { const names: string[] = [] for (const statement of parsed.statements) { for (const cmd of statement.commands) { names.push(cmd.name.toLowerCase()) } if (statement.nestedCommands) { for (const cmd of statement.nestedCommands) { names.push(cmd.name.toLowerCase()) } } } return names}
/** * Get all pipeline segments as flat list of commands. * Useful for checking each command independently. */export function getAllCommands( parsed: ParsedPowerShellCommand,): ParsedCommandElement[] { const commands: ParsedCommandElement[] = [] for (const statement of parsed.statements) { for (const cmd of statement.commands) { commands.push(cmd) } if (statement.nestedCommands) { for (const cmd of statement.nestedCommands) { commands.push(cmd) } } } return commands}
/** * Get all redirections across all statements. */// exported for testingexport function getAllRedirections( parsed: ParsedPowerShellCommand,): ParsedRedirection[] { const redirections: ParsedRedirection[] = [] for (const statement of parsed.statements) { for (const redir of statement.redirections) { redirections.push(redir) } // Include redirections from nested commands (e.g., from && / || chains) if (statement.nestedCommands) { for (const cmd of statement.nestedCommands) { if (cmd.redirections) { for (const redir of cmd.redirections) { redirections.push(redir) } } } } } return redirections}
/** * Get all variables, optionally filtered by scope (e.g., 'env'). * Variable paths in PowerShell can have scopes like "env:PATH", "global:x". */export function getVariablesByScope( parsed: ParsedPowerShellCommand, scope: string,): ParsedVariable[] { const prefix = scope.toLowerCase() + ':' return parsed.variables.filter(v => v.path.toLowerCase().startsWith(prefix))}
/** * Check if any command in the parsed result matches a given name (case-insensitive). * Handles common aliases too. */export function hasCommandNamed( parsed: ParsedPowerShellCommand, name: string,): boolean { const lowerName = name.toLowerCase() const canonicalFromAlias = COMMON_ALIASES[lowerName]?.toLowerCase()
for (const cmdName of getAllCommandNames(parsed)) { if (cmdName === lowerName) { return true } // Check if the command is an alias that resolves to the requested name const canonical = COMMON_ALIASES[cmdName]?.toLowerCase() if (canonical === lowerName) { return true } // Check if the requested name is an alias and the command is its canonical form if (canonicalFromAlias && cmdName === canonicalFromAlias) { return true } // Check if both resolve to the same canonical cmdlet (alias-to-alias match) if (canonical && canonicalFromAlias && canonical === canonicalFromAlias) { return true } } return false}
/** * Check if the command contains any directory-changing commands. * (Set-Location, cd, sl, chdir, Push-Location, pushd, Pop-Location, popd) */// exported for testingexport function hasDirectoryChange(parsed: ParsedPowerShellCommand): boolean { for (const cmdName of getAllCommandNames(parsed)) { if ( DIRECTORY_CHANGE_CMDLETS.has(cmdName) || DIRECTORY_CHANGE_ALIASES.has(cmdName) ) { return true } } return false}
/** * Check if the command is a single simple command (no pipes, no semicolons, no operators). */// exported for testingexport function isSingleCommand(parsed: ParsedPowerShellCommand): boolean { const stmt = parsed.statements[0] return ( parsed.statements.length === 1 && stmt !== undefined && stmt.commands.length === 1 && (!stmt.nestedCommands || stmt.nestedCommands.length === 0) )}
/** * Check if a specific command has a given argument/flag (case-insensitive). * Useful for checking "-EncodedCommand", "-Recurse", etc. */export function commandHasArg( command: ParsedCommandElement, arg: string,): boolean { const lowerArg = arg.toLowerCase() return command.args.some(a => a.toLowerCase() === lowerArg)}
/** * Tokenizer-level dash characters that PowerShell's parser accepts as * parameter prefixes. SpecialCharacters.IsDash (CharTraits.cs) accepts exactly * these four: ASCII hyphen-minus, en-dash, em-dash, horizontal bar. These are * tokenizer-level — they apply to ALL cmdlet parameters, not just argv to * powershell.exe (contrast with `/` which is an argv-parser quirk of * powershell.exe 5.1 only; see PS_ALT_PARAM_PREFIXES in powershellSecurity.ts). * * Extent.Text preserves the raw character; transformCommandAst uses ce.text * for CommandParameterAst elements, so these reach callers unchanged. */export const PS_TOKENIZER_DASH_CHARS = new Set([ '-', // U+002D hyphen-minus (ASCII) '\u2013', // en-dash '\u2014', // em-dash '\u2015', // horizontal bar])
/** * Determines if an argument is a PowerShell parameter (flag), using the AST * element type as ground truth when available. * * The parser maps CommandParameterAst → 'Parameter' regardless of which dash * character the user typed — PowerShell's tokenizer handles that. So when * elementType is available, it's authoritative: * - 'Parameter' → true (covers `-Path`, `–Path`, `—Path`, `―Path`) * - anything else → false (a quoted "-Path" is StringConstant, not a param) * * When elementType is unavailable (backward compat / no AST detail), fall back * to a char check against PS_TOKENIZER_DASH_CHARS. */export function isPowerShellParameter( arg: string, elementType?: CommandElementType,): boolean { if (elementType !== undefined) { return elementType === 'Parameter' } return arg.length > 0 && PS_TOKENIZER_DASH_CHARS.has(arg[0]!)}
/** * Check if any argument on a command is an unambiguous abbreviation of a PowerShell parameter. * PowerShell allows parameter abbreviation as long as the prefix is unambiguous. * The minPrefix is the shortest unambiguous prefix for the parameter. * For example, minPrefix '-en' for fullParam '-encodedcommand' matches '-en', '-enc', '-enco', etc. */export function commandHasArgAbbreviation( command: ParsedCommandElement, fullParam: string, minPrefix: string,): boolean { const lowerFull = fullParam.toLowerCase() const lowerMin = minPrefix.toLowerCase() return command.args.some(a => { // Strip colon-bound value (e.g., -en:base64value -> -en) const colonIndex = a.indexOf(':', 1) const paramPart = colonIndex > 0 ? a.slice(0, colonIndex) : a // Strip backtick escapes — PowerShell resolves `-Member`Name` to // `-MemberName` but Extent.Text preserves the backtick, causing // prefix-comparison misses on the raw text. const lower = paramPart.replace(/`/g, '').toLowerCase() return ( lower.startsWith(lowerMin) && lowerFull.startsWith(lower) && lower.length <= lowerFull.length ) })}
/** * Split a parsed command into its pipeline segments for per-segment permission checking. * Returns each pipeline's commands separately. */export function getPipelineSegments( parsed: ParsedPowerShellCommand,): ParsedStatement[] { return parsed.statements}
/** * True if a redirection target is PowerShell's `$null` automatic variable. * `> $null` discards output (like /dev/null) — not a filesystem write. * `$null` cannot be reassigned, so this is safe to treat as a no-op sink. * `${null}` is the same automatic variable via curly-brace syntax. Spaces * inside the braces (`${ null }`) name a different variable, so no regex. */export function isNullRedirectionTarget(target: string): boolean { const t = target.trim().toLowerCase() return t === '$null' || t === '${null}'}
/** * Get output redirections (file redirections, not merging redirections). * Returns only redirections that write to files. */// exported for testingexport function getFileRedirections( parsed: ParsedPowerShellCommand,): ParsedRedirection[] { return getAllRedirections(parsed).filter( r => !r.isMerging && !isNullRedirectionTarget(r.target), )}
/** * Derive security-relevant flags from the parsed command structure. * This replaces the previous approach of computing flags in PowerShell via * separate Find-AstNodes calls. Instead, the PS1 script tags each element * with its AST node type, and this function walks those types. */// exported for testingexport function deriveSecurityFlags( parsed: ParsedPowerShellCommand,): SecurityFlags { const flags: SecurityFlags = { hasSubExpressions: false, hasScriptBlocks: false, hasSplatting: false, hasExpandableStrings: false, hasMemberInvocations: false, hasAssignments: false, hasStopParsing: parsed.hasStopParsing, }
function checkElements(cmd: ParsedCommandElement): void { if (!cmd.elementTypes) { return } for (const et of cmd.elementTypes) { switch (et) { case 'ScriptBlock': flags.hasScriptBlocks = true break case 'SubExpression': flags.hasSubExpressions = true break case 'ExpandableString': flags.hasExpandableStrings = true break case 'MemberInvocation': flags.hasMemberInvocations = true break } } }
for (const stmt of parsed.statements) { if (stmt.statementType === 'AssignmentStatementAst') { flags.hasAssignments = true } for (const cmd of stmt.commands) { checkElements(cmd) } if (stmt.nestedCommands) { for (const cmd of stmt.nestedCommands) { checkElements(cmd) } } // securityPatterns provides a belt-and-suspenders check that catches // patterns elementTypes may miss (e.g. member invocations inside // assignments, subexpressions in non-pipeline statements). if (stmt.securityPatterns) { if (stmt.securityPatterns.hasMemberInvocations) { flags.hasMemberInvocations = true } if (stmt.securityPatterns.hasSubExpressions) { flags.hasSubExpressions = true } if (stmt.securityPatterns.hasExpandableStrings) { flags.hasExpandableStrings = true } if (stmt.securityPatterns.hasScriptBlocks) { flags.hasScriptBlocks = true } } }
for (const v of parsed.variables) { if (v.isSplatted) { flags.hasSplatting = true break } }
return flags}
// Raw types exported for testing (function exports are inline above)