PowerShell 评审原则
0 项宁缺毋滥:仅报告可能影响正确性、安全性、兼容性或运行安全的缺陷。不要报告 PSScriptAnalyzer 已覆盖的格式或命名偏好。需考虑声明的 PowerShell 版本、目标操作系统、权限边界,以及文件是脚本(.ps1)、模块(.psm1)还是数据/清单文件(.psd1)。
在报告非局部行为之前,使用 file_read 和 code_search 验证调用方、参数契约、模块导出、执行上下文和输入信任边界。在没有具体行为影响的情况下,不要假定别名、Write-Host、调用运算符(&)或全局变量的每次使用都是缺陷。
命令构造与注入
6 项- 不可信文本被传入
Invoke-Expression、[scriptblock]::Create、powershell -Command、pwsh -Command、cmd /c、sh -c或其他字符串求值边界,攻击者可在其中注入可执行语法。内置来源与改动说明
- 命令被拼接为单个插值字符串,后续求值允许注入,或引号改变了预期参数;不要仅凭字符串构造本身报告。内置
来源与改动说明
- 远程内容未经真实性、完整性或信任校验即被下载并执行,包括
Invoke-WebRequest ... | Invoke-Expression模式。内置来源与改动说明
- 用户可控的可执行文件名、模块名、脚本路径或命令路径,经
&、点源调用(dot-sourcing)、Start-Process或远程处理调用,且没有允许列表或受限的解析边界。内置来源与改动说明
- 用户可控的通配符模式、注册表路径、证书路径或文件系统路径,可能越出预期范围、匹配额外目标或触发破坏性操作。内置
来源与改动说明
- 引号导致变量或子表达式被提前展开,尤其是在跨原生命令、远程处理或嵌套 shell 边界时。内置
来源与改动说明
参数、类型与输入校验
6 项- 参数接受外部输入,却缺少在特权、破坏性或安全敏感用途之前所需的类型、验证特性或显式检查。内置
来源与改动说明
- 声明用于管道输入的参数却在
process之外处理,导致只有最后一项或没有任何一项按预期得到处理。内置来源与改动说明
- 在 PowerShell 自动枚举之后混淆
$null、空集合与标量,导致错误的分支或被跳过的工作。内置来源与改动说明
- 依赖真值判断,而
0、''或$false等合法值必须与输入缺失相区分。内置来源与改动说明
- 不安全的强制转换或枚举转换,可能在部分副作用已经发生之后才抛出异常。内置
来源与改动说明
- 返回或接受结构松散的
PSCustomObject值,而调用方依赖的属性在可达路径上并不存在。内置来源与改动说明
错误与原生命令状态
6 项- 期望
try/catch处理非终止性 cmdlet 错误,却没有-ErrorAction Stop或等效的局部$ErrorActionPreference策略。内置来源与改动说明
- 全局设置
$ErrorActionPreference,或用SilentlyContinue/Ignore抑制错误,掩盖了本应暴露的失败或改变了无关调用方的行为。内置来源与改动说明
- 空的或过宽的
catch块,用看似合理的输出替代失败、在部分状态变更后继续执行,或丢弃可操作的错误上下文。内置来源与改动说明
- 假定原生命令失败会抛出 PowerShell 异常;在要求显式检查
$LASTEXITCODE之前,先查看支持的版本、$PSNativeCommandUseErrorActionPreference、$ErrorActionPreference以及任何原生命令封装。应依据被调用命令自身的契约解释退出码,而不是一刀切地把非零视为失败。内置来源与改动说明
- 在另一条命令已覆盖
$?之后才检查它,或仅凭 stderr 输出就断定原生命令失败。内置来源与改动说明
- 在可达的失败或取消路径上跳过了清理、锁释放、位置恢复、会话拆除或临时状态恢复;注意
finally、PowerShell 7.3+ 的clean块,以及与支持版本和生命周期相适应的其他处置机制。内置来源与改动说明
管道与输出语义
6 项- 辅助表达式或 cmdlet 向函数的成功流输出了意外对象,破坏了函数文档声明的返回值。内置
来源与改动说明
- 假定
return会抑制函数或脚本块中先前已输出的对象。内置来源与改动说明
- 意外的集合展开把嵌套集合或单一集合对象拆成多条管道记录;当调用方依赖其形状时,应显式保持形状。内置
来源与改动说明
- 在数据离开可复用的函数或模块之前使用
Format-Table等格式化 cmdlet,把结构化对象变成格式化指令而非返回数据。内置来源与改动说明
- 混用 host、information、warning、error 与 success 流,破坏重定向、自动化或结构化消费方。内置
来源与改动说明
- 物化无界管道,在预期输入规模下就可能耗尽内存。关于数组追加成本,需核实支持的版本与工作负载:PowerShell 7.5 已优化数组相加,因此仅凭
+=不能证明存在平方级运行时间。内置来源与改动说明
状态变更、幂等性与清理
6 项- 变更状态的高级函数声称或要求
-WhatIf/-Confirm行为,却省略或绕过SupportsShouldProcess与$PSCmdlet.ShouldProcess()。内置来源与改动说明
- 重试或重跑行为导致资源重复、配置被反复追加或状态损坏,而不是收敛到请求的结果。内置
来源与改动说明
- 多个相关变更在中间失败后可能留下部分应用的配置,且没有回滚、补偿或明确成文的部分状态契约。内置
来源与改动说明
- 脚本作为可复用组件使用时,更改了进程级位置、环境变量、首选项变量、默认参数值或模块状态却不予恢复。内置
来源与改动说明
- 成功、失败或取消之后仍处于活动状态的资源、作业、runspace、会话、订阅、流或临时文件。内置
来源与改动说明
- 破坏性通配符操作在变更前未检查解析出的实际目标。内置
来源与改动说明
凭据、传输与敏感数据
6 项- 密码、令牌、连接字符串、私钥或凭据被硬编码到源码、命令参数、日志、异常、transcript 或模块清单中。内置
来源与改动说明
- 在必要的 API 边界之外暴露明文凭据,或保留/记录其明文表示。仅转换为
SecureString本身不是缺陷,也不会抹除原始明文;不要假定其内容在非 Windows 平台上是加密的。内置来源与改动说明
- 周边代码要求使用
PSCredential、托管标识或既定密钥提供程序时,却接受分离的用户名/密码字符串。内置来源与改动说明
- 跨越真实信任边界时禁用证书校验、使用
-SkipCertificateCheck、削弱 TLS 或抑制主机验证。内置来源与改动说明
- 把执行策略当作认证或授权控制来信任;执行策略不是安全边界。内置
来源与改动说明
- 记录可能包含敏感信息的完整请求头、环境变量、进程参数或远程会话配置。内置
来源与改动说明
远程处理、作业与并发
6 项- 假定本地变量无需
Using:、参数或显式参数列表即可在远程可用,或因引号问题在错误的会话中展开。内置来源与改动说明
- 依赖在进程外作业或远程处理序列化中丢失的方法、活动句柄或私钥材料;需核实实际类型,因为某些类型会被重新实例化(rehydrated),而不是作为反序列化的属性包返回。内置
来源与改动说明
- 启动作业、线程作业、runspace 或远程命令后不关注其完成与失败,而其结果会影响正确性。内置
来源与改动说明
- 共享可变状态被线程作业、并行管道、事件处理器或 runspace 访问,却没有同步机制或所有权不变式。内置
来源与改动说明
- 事件订阅或后台作业存活时间超出其所有者,并持续产生意外副作用。内置
来源与改动说明
- 远程处理端点、认证机制或凭据委托把访问范围扩大到预期主机或用户之外。内置
来源与改动说明
模块、作用域与清单
6 项- 模块代码把可变变量、别名、函数、驱动器或首选项变更无意地泄漏到全局作用域。内置
来源与改动说明
- 公开命令未列入
FunctionsToExport,或在清单应定义稳定 API 时通过通配符导出私有辅助函数。内置来源与改动说明
RootModule、NestedModules、RequiredModules、兼容的 edition 或 PowerShell 版本约束,与模块的实际依赖和语法不匹配。内置来源与改动说明
- 模块初始化在导入时执行不可逆副作用,却没有明确的模块契约。内置
来源与改动说明
- 点源调用或导入的路径来自不可信输入、当前目录或含混的模块搜索路径。内置
来源与改动说明
- 把不可信的
.psd1内容当作代码求值而非安全地导入数据,或添加实际加载器会拒绝的值。需区分Import-PowerShellDataFile与模块清单受限语言;清单支持的变量和表达式并非任意代码执行。内置来源与改动说明
版本与平台兼容性
5 项- 使用仅限 Windows PowerShell 5.1 或仅限 PowerShell 7 的语法、cmdlet、参数或 .NET API,却与项目声明的支持范围不符。内置
来源与改动说明
- 仅 Windows 的提供程序、注册表访问、盘符、路径分隔符、环境变量大小写或可执行文件名被用于面向 macOS 或 Linux 的代码路径。内置
来源与改动说明
- 原生命令的引号或传参假设在 Windows PowerShell、新版 PowerShell 与目标操作系统之间不一致;需检查 PowerShell 7.3+ 的
$PSNativeCommandArgumentPassing模式及旧式命令的例外。内置来源与改动说明
- 文本编码假设在 Windows PowerShell 与 PowerShell 7 的默认编码之间会损坏非 ASCII 输入或输出。内置
来源与改动说明
- 平台检查在不兼容的命令或类型已被解析或调用之后才执行。内置
来源与改动说明
测试正确性
5 项- Pester mock 指向的命令名或模块作用域与被测代码使用的不同,导致真实命令仍会运行或断言失去意义。内置
来源与改动说明
- 断言对所报告的回归不可能失败,或测试检验的是 setup 输出而非函数结果。内置
来源与改动说明
- 测试共享全局变量、导入的模块状态、环境变更、文件、作业或会话,却没有隔离与清理。内置
来源与改动说明
- 破坏性或特权测试在没有有效安全边界的情况下触达真实资源。
TestDrive只隔离指向它的文件操作;mock 必须拦截实际调用,-WhatIf只保护遵循ShouldProcess的操作。内置来源与改动说明
- 测试依赖不受控的网络、凭据、区域设置、已安装模块、执行策略或宿主状态,却没有声明并隔离该依赖。内置
来源与改动说明
官方参考
5 项- 内置
来源与改动说明
- 内置
来源与改动说明
- 内置
来源与改动说明
- 内置
来源与改动说明
- Pester mock与TestDrive 隔离;请使用与项目 Pester 版本匹配的文档。内置
来源与改动说明