PSScriptAnalyzer導入とCI化の知識マップ(知識グラフ)
type: Dataset
description: この記事は、PowerShell公式の静的解析モジュールPSScriptAnalyzerを社内スクリプトへ導入する実務手順を扱う。PSScriptAnalyzerSettings.psd1という1つの設定ファイルをリポジトリに置くことで、VS Codeの拡張機能とGitHub ActionsのCIが同じ基準で解析するように整える。重大度はルールごとに決まっており、平文パスワード検出などのルールはError指定だけでは素通りするため、資格情報系のルールは名前を明示してCIの失敗条件に加えるべきだとしている。既存資産には、まずErrorをゼロにし、次に変更ファイルだけを厳格に解析する段階導入を勧め、テストを書かずに初日から効果が出るPSScriptAnalyzerをPesterより先に導入する順序を推奨している。

PSScriptAnalyzer
type: Concept
definition: PowerShellスクリプトを静的解析するMicrosoft公式のツール。
uses: Invoke-ScriptAnalyzer
uses: SuppressMessageAttribute
uses: PSAvoidUsingPlainTextForPassword
uses: PSUseDeclaredVarsMoreThanAssignments
uses: PSAvoidUsingConvertToSecureStringWithPlainText
uses: PSAvoidUsingUsernameAndPasswordParams
configured by: PSScriptAnalyzerSettings.psd1
should precede: Pester

GitHub Actions
type: Concept
definition: GitHubが提供する、リポジトリのイベントをトリガーにワークフローを実行するCI/CDサービス。
alternative label: GitHub Actions workflow

Invoke-ScriptAnalyzer
type: Concept
definition: PSScriptAnalyzerのルールに基づいてスクリプトやモジュールを解析するコマンドレット。
alternative label: -Path
alternative label: -Recurse
alternative label: -Settings
alternative label: -Fix
broader: PSScriptAnalyzer
uses: Invoke-Formatter

SuppressMessageAttribute
type: Concept
definition: 特定の関数やスクリプトに対してPSScriptAnalyzerの指摘を個別に抑止する属性。Justification引数に理由を書くことが求められる。
alternative label: Justification
broader: PSScriptAnalyzer

PSScriptAnalyzerSettings.psd1
type: Concept
definition: Severity・IncludeRules・ExcludeRules・Rulesなどを記述し、開発者とCIが同じ基準で解析するための設定ファイル。
alternative label: Severity
alternative label: IncludeRules
alternative label: ExcludeRules
broader: PSScriptAnalyzer

VS CodeのPowerShell拡張機能
type: Concept
definition: Visual Studio Code上でPowerShellの編集・デバッグを支援する拡張機能。PSScriptAnalyzerを内蔵し、編集中にその場で警告を表示する。
alternative label: PowerShell extension for VS Code
uses: PSScriptAnalyzer
configured by: PSScriptAnalyzerSettings.psd1

PSAvoidUsingPlainTextForPassword
type: Concept
definition: パラメーターで平文パスワードを受け取っていないかを検出するPSScriptAnalyzerのルール。重大度はWarning。
broader: PSScriptAnalyzer

PSUseDeclaredVarsMoreThanAssignments
type: Concept
definition: 代入されたが一度も参照されていない変数を検出するPSScriptAnalyzerのルール。変数名のタイプミスを実バグとして拾える。
broader: PSScriptAnalyzer

Invoke-Formatter
type: Concept
definition: 設定ファイルのルールに基づいてPowerShellスクリプトのテキストを整形するコマンドレット。
broader: PSScriptAnalyzer

Pester
type: Concept
definition: PowerShellスクリプトの自動テストを書くためのテストフレームワーク。

PSScriptAnalyzerの段階導入
type: Concept
definition: 重大度Errorをゼロにする第1段階、変更ファイルのみを厳格に解析する第2段階、除外ルールを徐々に外す第3段階という順で既存資産へ静的解析を導入していく進め方。
requires: PSScriptAnalyzer
requires: 変更ファイルのみを対象にした差分解析

変更ファイルのみを対象にした差分解析
type: Concept
definition: ベースブランチとの差分を取り、変更されたps1/psm1/psd1ファイルだけをPSScriptAnalyzerの解析対象にすることで、既存の負債を残したまま新しい問題の増加だけを止める手法。
alternative label: git diff
alternative label: 第2段階
uses: Invoke-ScriptAnalyzer

actions/checkoutのfetch-depth: 0
type: Concept
definition: GitHub Actionsのactions/checkoutで履歴全体を取得する指定。差分チェックでベースブランチとの比較を行うために必要になる。
alternative label: fetch-depth

GITHUB_BASE_REF
type: Concept
definition: pull_requestイベントでPRのターゲットブランチ名が入るGitHub Actionsの既定環境変数。push時は空になる。

PSAvoidUsingConvertToSecureStringWithPlainText
type: Concept
definition: 平文の文字列からSecureStringを生成していないかを検出するPSScriptAnalyzerのルール。重大度はError。
broader: PSScriptAnalyzer

PSAvoidUsingUsernameAndPasswordParams
type: Concept
definition: ユーザー名とパスワードを別々のパラメーターで受け取っていないかを検出するPSScriptAnalyzerのルール。重大度はError。
broader: PSScriptAnalyzer

重大度に関係なく落とすルールの明示リスト
type: Concept
definition: 重大度がWarningでも資格情報関連など常に失敗条件へ含めたいPSScriptAnalyzerのルール名を、CIの判定コードに明示的に列挙したもの。
alternative label: $mustFix
requires: PSAvoidUsingPlainTextForPassword
requires: PSAvoidUsingConvertToSecureStringWithPlainText
requires: PSAvoidUsingUsernameAndPasswordParams

subject: PSScriptAnalyzer
predicate: uses
object: Invoke-ScriptAnalyzer
description: PSScriptAnalyzerはInvoke-ScriptAnalyzerコマンドレットでスクリプトやモジュールを解析する
evidence: overview
verified at: 2026-08-01
certainty: established

subject: PSScriptAnalyzer
predicate: uses
object: SuppressMessageAttribute
description: PSScriptAnalyzerはSuppressMessageAttributeによる指摘の個別抑止を提供する
evidence: suppressing-rules
verified at: 2026-08-01
certainty: established

subject: PSScriptAnalyzer
predicate: configuredBy
object: PSScriptAnalyzerSettings.psd1
description: PSScriptAnalyzerの解析対象ルールと重大度はPSScriptAnalyzerSettings.psd1で構成できる
evidence: using-scriptanalyzer
verified at: 2026-08-01
certainty: established

subject: VS CodeのPowerShell拡張機能
predicate: uses
object: PSScriptAnalyzer
description: VS CodeのPowerShell拡張機能はPSScriptAnalyzerを内蔵し、編集中にその場で警告を表示する
evidence: using-vscode
verified at: 2026-08-01
certainty: established

subject: VS CodeのPowerShell拡張機能
predicate: configuredBy
object: PSScriptAnalyzerSettings.psd1
description: VS Code拡張機能の設定powershell.scriptAnalysis.settingsPathの既定値がPSScriptAnalyzerSettings.psd1のため、この名前でリポジトリ直下に置くと編集中の警告とCIの判定基準がそろう
evidence: package.json
verified at: 2026-08-01
certainty: established

subject: GitHub Actions
predicate: uses
object: Invoke-ScriptAnalyzer
description: 本記事が組み立てるPSScriptAnalyzerのCIワークフローでは、GitHub Actionsのワークフローはステップの中でInvoke-ScriptAnalyzerを呼び出して解析を実行する
evidence: overview
verified at: 2026-08-01
certainty: context-dependent

subject: PSScriptAnalyzer
predicate: uses
object: PSAvoidUsingPlainTextForPassword
description: PSScriptAnalyzerは平文パスワード検出ルールPSAvoidUsingPlainTextForPasswordを組み込みルールとして持つ
evidence: avoidusingplaintextforpassword
verified at: 2026-08-01
certainty: established

subject: PSScriptAnalyzer
predicate: uses
object: PSUseDeclaredVarsMoreThanAssignments
description: PSScriptAnalyzerは未使用変数検出ルールPSUseDeclaredVarsMoreThanAssignmentsを持ち、変数名のタイプミスという実バグを拾える
evidence: readme
verified at: 2026-08-01
certainty: established

subject: Invoke-ScriptAnalyzer
predicate: uses
object: Invoke-Formatter
description: Invoke-ScriptAnalyzerの-Fixによる自動修正のうち、整形の処理はInvoke-Formatterが担う
evidence: invoke-formatter
verified at: 2026-08-01
certainty: established

subject: PSScriptAnalyzer
predicate: shouldPrecede
object: Pester
description: テストコードを書かずに初日から効果が出るPSScriptAnalyzerを、テストを書く作業が必要なPesterより先に導入するのが実務的だとされる
evidence: quick-start
verified at: 2026-08-01
certainty: established

subject: PSScriptAnalyzerの段階導入
predicate: requires
object: PSScriptAnalyzer
description: 段階導入はPSScriptAnalyzerによる解析の実行を前提とする
evidence: overview
verified at: 2026-08-01
certainty: established

subject: PSScriptAnalyzerの段階導入
predicate: requires
object: 変更ファイルのみを対象にした差分解析
description: 段階導入の第2段階は、変更ファイルのみを厳格に解析する差分チェックを前提とする
evidence: git-diff
verified at: 2026-08-01
certainty: established

subject: 変更ファイルのみを対象にした差分解析
predicate: requires
object: actions/checkoutのfetch-depth: 0
description: GitHub Actionsで差分解析を行う場合、ベースブランチとの比較に履歴が必要なため、actions/checkoutでfetch-depth: 0を指定するか、ベースブランチを明示的にfetchすることを前提とする。GitHub Actions以外の実行環境や手元での差分解析には当てはまらない
evidence: checkout
verified at: 2026-08-01
certainty: context-dependent

subject: 変更ファイルのみを対象にした差分解析
predicate: requires
object: GITHUB_BASE_REF
description: GitHub Actionsで差分解析を行う場合、比較先をmainに固定せずPRのターゲットブランチを使うため、GITHUB_BASE_REFの参照を前提とする。GitHub Actions以外の実行環境ではこの変数は存在しない
evidence: default-environment-variables
verified at: 2026-08-01
certainty: context-dependent

subject: 変更ファイルのみを対象にした差分解析
predicate: uses
object: GitHub Actions
description: 本記事が想定するCI環境では、変更ファイルのみの差分解析はGitHub Actionsのワークフローの中で実行される
evidence: actions
verified at: 2026-08-01
certainty: context-dependent

subject: 変更ファイルのみを対象にした差分解析
predicate: uses
object: Invoke-ScriptAnalyzer
description: 差分解析は取得した変更ファイルを1つずつInvoke-ScriptAnalyzerに渡して結果を集約する
evidence: overview
verified at: 2026-08-01
certainty: established

subject: PSScriptAnalyzer
predicate: uses
object: PSAvoidUsingConvertToSecureStringWithPlainText
description: PSScriptAnalyzerは平文からSecureStringを生成する行為を検出するPSAvoidUsingConvertToSecureStringWithPlainTextを持つ
evidence: avoidusingconverttosecurestringwithplaintext
verified at: 2026-08-01
certainty: established

subject: PSScriptAnalyzer
predicate: uses
object: PSAvoidUsingUsernameAndPasswordParams
description: PSScriptAnalyzerはユーザー名とパスワードを別パラメーターで受け取る設計を検出するPSAvoidUsingUsernameAndPasswordParamsを持つ
evidence: readme
verified at: 2026-08-01
certainty: established

subject: 重大度に関係なく落とすルールの明示リスト
predicate: requires
object: PSAvoidUsingPlainTextForPassword
description: 重大度に関係なく落とすルール名の明示リストには、重大度Warningでも見逃せないPSAvoidUsingPlainTextForPasswordが含まれる
evidence: avoidusingplaintextforpassword
verified at: 2026-08-01
certainty: established

subject: 重大度に関係なく落とすルールの明示リスト
predicate: requires
object: PSAvoidUsingConvertToSecureStringWithPlainText
description: 重大度に関係なく落とすルール名の明示リストには、PSAvoidUsingConvertToSecureStringWithPlainTextが含まれる
evidence: avoidusingconverttosecurestringwithplaintext
verified at: 2026-08-01
certainty: established

subject: 重大度に関係なく落とすルールの明示リスト
predicate: requires
object: PSAvoidUsingUsernameAndPasswordParams
description: 重大度に関係なく落とすルール名の明示リストには、PSAvoidUsingUsernameAndPasswordParamsが含まれる
evidence: readme
verified at: 2026-08-01
certainty: established

subject: GitHub Actions
predicate: uses
object: 重大度に関係なく落とすルールの明示リスト
description: 本記事が組み立てるCIワークフローでは、失敗条件は重大度Errorに加え、この明示リストのルールに一致した指摘も含める
evidence: avoidusingplaintextforpassword
verified at: 2026-08-01
certainty: context-dependent