Skip to content

windows shell safety_ja

Jump to bottom
Kazushi Kamegawa edited this page Oct 7, 2026 · 1 revision

Windows Shell Safety プラグイン

English

概要

Windows で Azure CLI・JSON ペイロード・パイプが cmd.exe を経由してエージェントが時間を浪費しないよう、独立した windows-shell-safety プラグインを追加します。スキルが安全な実行パターンを規定し、同梱の事前 lint が危険なコマンド形を実行前に検出します。

追跡

種別 Issue
親 Issue #84
サブ issue Issue #85
サブ issue Issue #86
サブ issue Issue #87
サブ issue Issue #88

背景

  • Windows の az はバッチファイル az.cmd です。PowerShell 7 から呼んでも cmd.exe が引数を再解釈し、|、&、<、>、^、%VAR% を消費するため、--query "[?x=='a'] | [0]" のような JMESPath が壊れます。
  • PowerShell 7.3+ の既定 $PSNativeCommandArgumentPassing = 'Windows' は .cmd/.bat に対して Legacy の引数渡しを維持するため、インライン JSON 内の二重引用符が欠落します。
  • Git Bash や cmd からの powershell -Command "... | ..." のような多段呼び出しでは、外側のシェルが先にパイプや引用符を消費します。
  • $OutputEncoding と [Console]::OutputEncoding の不一致により、パイプ経由の非 ASCII データが ? になります。
  • 既存の Azure DevOps ガイダンスは REST 書き込みのみを対象としており、本計画でこれを汎用化します。

設計

  • 防止レベル: スキルと事前 lint。誤検知で作業が止まらないよう PreToolUse フックは使いません。
  • 配置: az、gh、dotnet などのネイティブツールに使える新規プラグイン plugins/windows-shell-safety/。Azure DevOps スキルは内容を重複させずに参照します。
  • スキルの規則: pwsh のみを使う、JSON を引数に埋め込まない（UTF-8 ファイルと @file）、az --query に cmd メタ文字や引用符を入れず ConvertFrom-Json で絞り込む、パイプ前に UTF-8 エンコーディングを設定する、-Command 文字列ではなく pwsh -File でスクリプトを実行する、実行前に lint を通す、再試行前に受信 argv を確認する。
  • Test-NativeCommand.ps1: 規則 WSS001-WSS008（cmd /c、-Command 文字列、.cmd 対象への cmd メタ文字、インライン JSON、エスケープ済み引用符、Windows PowerShell 5.1、UTF-8 設定漏れ、シェル回避策）を持つ AST ベースの lint。指摘ありで終了コード 1、-AsJson 出力対応。
  • Invoke-NativeJson.ps1: Invoke-AzJson は本文を UTF-8 一時ファイル経由で送り、解析済みオブジェクトを返します。-EchoArgs は .cmd 子プロセスが実際に受け取った argv を表示します。

実装フェーズ

  1. lint スクリプトと unittest フィクスチャ（#85）。
  2. 安全実行ヘルパー（#86）。
  3. スキル文書、リファレンス、マニフェスト、リポジトリ文書（#87）。
  4. 引数欠落を再現し、安全なパターンを実証する windows-latest CI ジョブ（#88）。

検証

  • python3 scripts/validate_marketplaces.py が成功すること。
  • lint の unittest がローカルの pwsh と既存の Ubuntu CI ジョブで成功すること。
  • windows-latest CI ジョブで、サインイン不要の az version を使い、壊れる形が失敗し推奨形が成功することを示すこと。

Clone this wiki locally