Перейти к основному содержимому
T

dsh-ps51-guard

tlewa/dsh-ps51-guard

Guards Windows PowerShell 5.1 commands run through ops_bash by passing the script as UTF-16LE, restoring quoting that bash expansion destroyed, rewriting syntax and encoding switches 5.1 lacks, normalizing exit codes and output, and redirecting powershell to pwsh 7 by default.

Установка

dsh plugin --profile web add github:tlewa/dsh-ps51-guard

README

dsh-ps51-guard

状态:0.1.0,M1–M5 已实现。为通过 ops_bash 调用的 Windows PowerShell 5.1 提供命令传输保护、语法兼容改写与执行结果归一化,并内置可关闭的 powershell → pwsh 7 重定向。

DSH 的 ops_bash 用 bash 执行命令,而 Windows 上的 powershell/powershell.exe 是 5.1。命令从模型到 PowerShell 要穿过 bash 的引号与变量展开,5.1 又缺少 PowerShell 7 的语法与编码选项,于是出现「引号被吃掉」「$env:TEMP 变成 :TEMP」「2>/dev/null 报错」「错误退出码为 0」等问题。本插件在 bash 进程内接管最终解析到 5.1 的调用,在命令到达 PowerShell 之前完成纠正。

从 0.2 里程碑起,本插件同时内置原先由 dsh-pwsh7-bash 提供的 powershell → pwsh 7 重定向,默认开启;需要 5.1 时设 PS51_PWSH7=0。迁移后应移除旧插件,避免两个插件争抢 BASH_ENV。

工作方式

  1. 插件在 DSH 进程内把 BASH_ENV 指向自带的 bash-env.sh,并链式加载原有 BASH_ENV(若已被其他插件设置),互不覆盖;同时包装 subprocess.spawn,在每次 bash 启动时把同一个 shim 注入最终 spawn 环境,并把该环境里原有的 BASH_ENV 串到链上。这样即使另一个插件在本插件之后改写进程级 BASH_ENV,ops_bash 仍会加载本插件,加载顺序不再决定生效与否。
  2. shim 先按 PS51_PWSH7 决定是否安装 powershell → pwsh 7 函数;默认把解析到 5.1 的 powershell/powershell.exe 转给 pwsh。随后用 bash 的 DEBUG trap 读取 $BASH_COMMAND 原文(尚未被展开),只在命令词最终是 5.1 且未被重定向时启用 5.1 护栏;同时导出 bash 变量名清单,供判断 $name 归属。
  3. lib/client.js 解析原文、按 argv 恢复被 bash 展开的值、套用改写规则,然后把命令交给常驻宿主。
  4. 常驻 PowerShell 5.1 宿主(命名管道、4 字节小端长度前缀 + JSON 帧)执行命令;stdout/stderr 以原始字节回传(含 [Console]::Out/Error 的输出),stdin 通过 [Console]::In 提供给脚本,退出码取脚本最后一条命令的 $?,与 -Command 一致。连接阶段宿主不可用时回退到原始调用;请求已经发出后的宿主故障只报错退出(退出码 125)而不重放,任何情况下都不会执行两次。客户端断开或 ops_bash 被取消时,宿主会在 100 毫秒内发现并退出,正在执行的长命令不会在后台继续跑完。

接管范围

  • 默认把 powershell / powershell.exe 重定向到 pwsh 7;PS51_PWSH7=0 时改为对解析到 5.1 的调用启用护栏。
  • 重定向与护栏都只在命令词最终解析到 5.1(或命令尚不存在)且 command -v 结果与已知 5.1 路径一致时安装;PATH 中的包装脚本、别名、其他插件或用户已定义的函数不覆盖。
  • pwsh 直接放行;绝对路径调用(/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe ...)与 cmd /c 内的调用无法拦截,这是路线图记录在案的已知限制。

规则

规则触发行为
R1-Command 双引号内的 $namebash 变量按 bash 展开;PowerShell 变量($env:TEMP 等)保留字面量
R22>/dev/null改写为 2>$null
R3export FOO=bar改写为 $env:FOO = 'bar'
R4curl 改写为 curl.exe (避开 PowerShell 别名)
R5Join-Path a b c改写为嵌套 Join-Path (Join-Path a b) c
R6ls -la、rm -rf改写为 Get-ChildItem -Force、Remove-Item -Recurse -Force
R7-Encoding utf8NoBOM只提示(5.1 的参数集不接受该值)
R8PowerShell 内 > file只提示(5.1 写出 UTF-16LE BOM;需要无 BOM 时用 .NET 接口)
R9&&、`
R10??、?:只提示等价的 if/else 写法

改写时会在 stderr 打印 [ps51] A → B,让模型知道命令被调整过。高风险规则(R7–R10)与 R8 的错误只在必要时提示。

配置

变量默认作用
PS51_GUARD1设为 0 完全关闭护栏与重定向,恢复原始调用
PS51_PWSH71设为 0 关闭 powershell → pwsh 7 重定向,保留 5.1 护栏
PS51_PWSH7_PATH自动探测指定 pwsh.exe 的路径
PS51_SPAWN_GUARD1设为 0 关闭 subprocess.spawn 注入,只保留进程级 BASH_ENV(后加载的插件可能覆盖它)
PS51_MODErewriteannotate 只提示不改写;off 直接放行
PS51_STRICT0设为 1 时,命中只提示规则(R7–R10)的命令以退出码 2 拦下
PS51_VERBOSE0设为 1 时输出全部提示,包括 R8 等低优先级说明
PS51_DIAGNOSTICS1设为 0 停止写诊断日志

PS51_SPAWN_GUARD 只影响 subprocess.spawn 注入:桥只处理 bash -c 或本来就带非空 BASH_ENV 的 spawn,调用方显式把 BASH_ENV 设为空字符串会被视为主动关闭。PS51_GUARD、PS51_PWSH7 与 PS51_SPAWN_GUARD 都在 DSH 进程启动时读取,修改后需重启 DSH。诊断日志写在 %TEMP%\dsh-ps51-guard-<用户名>\session-<pid>\diagnostics.log(JSON 行,含命中的规则与改写前后命令),排查完建议关闭。设置 PS51_TRACE=1 可以让宿主额外写 host-trace.log。

已知限制

  • 重定向在 bash 启动时安装为函数;command powershell、绝对路径和 cmd /c 不经过重定向,仍会执行 5.1(也不经过护栏)。
  • 重定向开关在 DSH 启动时读取;shell 启动后已安装的函数不会因单条命令前缀 PS51_PWSH7=0 而改变。需要 5.1 时请在启动 DSH 前设置并重启。
  • 只处理 -Command / -c 载荷;-File 与 -EncodedCommand 原样放行,不做改写。
  • 含 exit 关键字的脚本走一次性进程(约 0.3–0.5 秒),因为 runspace 拿不到 exit 的退出码。
  • 每条命令要启动一次 node 客户端;宿主复用后同会话均摊约 100 毫秒/条,仍高于裸 5.1 的热执行。
  • bash 与 PowerShell 同名变量同时出现时按 argv 已展开值处理,并标记 mixed-variables,可能不是模型的本意。
  • 请求已交给宿主后若宿主崩溃或断开,客户端以 125 退出且不重放命令;只有尚未发出请求的连接失败才会回退到原命令。
  • stdin 只暴露给 [Console]::In;宿主派生的原生子进程仍然拿到关闭的 stdin。
  • [Console]::Out/Error 按原始字节单独回传,与 PowerShell pipeline 输出的相对顺序是近似的(console 文本先于格式化后的 pipeline 输出)。
  • 退出码取脚本最后一条命令的 $?;-ErrorAction SilentlyContinue 之类吞掉错误时,即使有错误也可能返回 0。
  • 取消时宿主直接退出以停止 pipeline;由脚本启动的原生子进程不保证一并终止。
  • spawn 注入只包一层;若另一个插件在本插件之后再次包装 subprocess.spawn 并丢弃或重写最终 spec,或整体替换 subprocess 服务,注入可能失效。桥不会为了实现注入而改变原命令;可用 PS51_SPAWN_GUARD=0 关闭它。
  • 调用方显式把 spawn 的 BASH_ENV 设为空字符串时,桥尊重该选择,不再注入。
  • 取消的可达范围要分清:真实 ops_bash 取消在 Windows 上由 DSH 直接终止整棵 bash 作业(dsh-subprocess-local/lib/runner.js:280 的 terminateJob → TerminateJobObject),本插件客户端没有机会执行上报代码,因此不会打印 [ps51] cancelled、也不会写诊断——这类取消由 DSH 自己报告,宿主在客户端断开时停止 pipeline。客户端只分类它实际捕获到的错误对象:传输/帧/启动失败仍报 [ps51] resident host failed …;只有错误体本身带取消形状(rc.5 的 AbortError / ABORT_ERR,或 ABORTED、ABORTED_BEFORE_DISPATCH,含 error.info、cause 链与 signal.reason)时才改报 [ps51] cancelled while the resident host was running; …。两条路径都不重放命令、退出码 125。

开发

npm test
npx --yes --package=github:TLEWA/dsh-plugin-ci#v1 dsh-ci-gate

测试包含规则单测、33 条真实命令语料(经 shim 端到端跑)与 200 次宿主稳定性/时延测量。技术基线与测量数据见 docs/measurements.md。

我的其他 DSH 项目

许可

MIT,见 LICENSE。

Похожие плагины