PowerShell スクリプトを用いたスキャン実行

PowerShell スクリプトを用いたスキャン実行

PowerShellスキャンを使用すると、PowerShell スクリプトを実行してデバイスから追加情報を収集し、その結果を保存できます。
標準スキャナーでは取得できないデータを利用した、高度な端末管理、カスタムレポート作成、条件に応じたデバイスの自動選定が可能になります。

この記事は以下の 2 部構成です。
  1. Part 1： PowerShellスキャンの作成、設定、および使用方法
  2. Part 2：PowerShellスキャンの動作概要と、高度なトラブルシューティング向けオプションラッパーについて（上級者向け）

【Part 1】 PowerShellスキャンの作成、設定、および使用方法

新しい PowerShellスキャンを作成する

    1. 左側のナビゲーションバーから「Scanners」をクリックします。
    2. 右上の［Create Scanner］をクリックします。
    3. スキャナー名を入力します。
    4. 「Type」ドロップダウンから「PowerShell」を選択します。PowerShellスキャンの設定ページが表示されます。

PowerShell スクリプトを追加する

「Script」セクションでは、各デバイス上で実行する PowerShell コードを定義します。
以下のいずれかの方法で追加できます。
    1. .ps1 ファイルをインポートする
    2. エディターへ直接スクリプトを貼り付ける
スクリプトは、データ収集と、PDQ Connect が処理可能な形式で結果を返すことのみに集中させることを推奨します。
Warning
PowerShellスキャンでは、デバイスごとに最大 100 行・36 列まで結果を返せます。
いずれかの制限を超えた場合、PDQ Connect は上限を超えた分を自動的に切り捨てます。

スクリプト出力要件

PowerShellスキャンは、コンソール出力ではなく、PowerShell のオブジェクトストリームを処理します。
PDQ Connect と互換性を持たせるには、スクリプトは構造化された PowerShell オブジェクト（例: PSCustomObject）のみを出力する必要があります。

✅ 正しい出力例
    1. [PSCustomObject]@{
    2. AntivirusEnabled = $true
    3. AntispywareEnabled = "Antispyware is enabled"
    4. Timestamp = Get-Date
    5. }
❌ 誤った出力例
    1. Write-Host "Antivirus is enabled"
    2. Write-Output "Antispyware is enabled"
    3. Get-Date
スクリプトが単なる文字列や整形済みテキストを出力した場合、PDQ Connect がデータを受け取る前にオブジェクト構造が失われます。
その結果、列や値を正しく検出・保存できなくなります。

出力整形用 Cmdlet を使用しない
PowerShellスキャンでは、以下のような出力整形用またはコンソール専用の Cmdlet を使用しないでください。
    1. Write-Host
    2. Format-Table
    3. Format-List
    4. Out-String
これらの Cmdlet は、構造化オブジェクトを、対話型 PowerShell セッション向けの表示専用テキストへ変換します。
一度変換されると、元のオブジェクトプロパティは失われ、PDQ Connect で処理できなくなります。
ベストプラクティス
構造化された生オブジェクトのみを返してください。表示形式や整形は、PDQ Connect 側で自動的に処理されます。

テキスト出力とオブジェクト出力を混在させない
スクリプトがプレーンテキストと構造化オブジェクトの両方を出力すると、PDQ Connect は結果を正しく処理できません。
Write-Host や文字列リテラルを含むテキストベースの出力が存在すると、PDQ Connect はオブジェクトスキーマを無視し、すべての出力を非構造化データとして扱います。
この問題を防ぐには、ステータスや情報メッセージを含むすべての値を PSCustomObject のプロパティとして返し、テキストを直接出力ストリームへ書き込まないようにしてください。

ログやステータスメッセージを出力しない
以下のような情報メッセージも、オブジェクト処理に影響する場合があります。
    1. "Starting scan..."
    2. "Completed scan."
有効なオブジェクトを返している場合でも、これらのメッセージが混在すると問題になる可能性があります。
スクリプトは、構造化オブジェクトのみを出力し、ログ出力や進捗表示を抑制するようにしてください。

PowerShellスキャンスクリプト テンプレート

以下のテンプレートは、スキャナー互換スクリプトを作成する際の基本例です。
    1. # PowerShell Scanner Script Template
    2. # ---------------------------------
    3. # Purpose:
    4. #   Collect data for use in a PDQ Connect PowerShell scanner.
    5. #
    6. # Requirements:
    7. #   - Output structured objects only
    8. #   - Do not write to the console
    9. #   - Do not use formatting or ConvertTo-Json

    11. # Collect data
    12. $osInfo = Get-CimInstance -ClassName Win32_OperatingSystem

    14. # Return structured output
    15. [PSCustomObject]@{
    16.     ComputerName = $env:COMPUTERNAME
    17.     OSName       = $osInfo.Caption
    18.     OSVersion    = $osInfo.Version
    19.     InstallDate  = $osInfo.InstallDate
    20.     LastBootTime = $osInfo.LastBootUpTime
    21. }
新しいスキャナー作成時や、既存スクリプトを PDQ Connect 向けに調整する際に利用してください。

テストデバイスの選択と出力確認

スキャナーを環境全体へ展開する前に、必ずテストデバイスで動作確認を行ってください。
    1. 「Select test device」セクションでオンライン状態のデバイスを選択します。
    2. ［Run script］をクリックします。
検証を行うことで、以下を確認できます。
    1. スクリプトが正常に実行されるか
    2. 検出された列とデータ型
    3. 他デバイスへスキャンを展開する前に、期待通りの構造で出力されているか
Warning
列情報は検証時に確定され、その後スキャンされるすべてのデバイスへ共通適用されます。
一部デバイスが他より多くのプロパティを返した場合でも同様です。
別デバイスで追加プロパティや追加オブジェクトが返された場合でも、そのプロパティが検証時に存在していなければ、スキャナー結果には表示されません。
追加列を含めるには、それらのプロパティを返すデバイスで再度検証を実行する必要があります。
最適な結果を得るためには、できるだけ多くのデータセットを返すテストデバイスを選択し、追加デバイスをスキャンする前に必要な列をすべて検出させることを推奨します。


出力内容とデータ型について

検証後、PDQ Connect はスクリプト出力を表形式で表示します。
    1. 各オブジェクトは 1 行として扱われます
    2. 各オブジェクトプロパティは 1 列として扱われます
    3. PDQ Connect は各列のデータ型を自動判定します。
サポートされる型は以下の通りです。
    1. String
    2. Integer
    3. Float
    4. Boolean
    5. Date　Date 型は、表示用に統一フォーマットへ変換されます。
各列には UI 上でデータ型セレクターが表示されます。
これはスクリプトが返す元データ自体には影響しませんが、PDQ Connect が Filters や Groups 用にデータをどのように保存するかを制御します。
たとえば、PowerShell が Boolean 値を 0 や 1 として返した場合でも、数値ではなく true / false として扱いたい場合に便利です。

スキャナーの有効化と保存

PowerShellスキャンは、有効化しない限りデバイスのスキャンを開始しません。
スキャナーは以下のいずれかの方法で有効化できます。
    1. 作成時に設定ページ右下の「Enabled」トグルを使用して有効化する
    2. 後から「Scanners」画面の一覧から有効化する
スクリプトと検証結果に問題がなければ、［Save］をクリックします。
有効化されたスキャナーは、PDQ Connect の通常のスキャン動作に従ってデバイスをスキャンします。

デバイス上で結果を確認する

PowerShellスキャンの結果は、各デバイス単位で確認できます。
    1. PDQ Connect で対象デバイスを開きます。
    2. 「Scanners」を開きます。
    3. 「PowerShell」を選択します。
この画面では、そのデバイスで最後に収集された結果を確認できます。インベントリ確認、フィルタリング、ターゲティングにも利用できます。

スキャンが上手くいかない場合は、こちらをご参照ください。

【Part 2】 PowerShellスキャンの動作概要と、高度なトラブルシューティング向けオプションラッパーについて（上級者向け）

PowerShellスキャンは、非対話型コンテキストでスクリプトを実行し、コンソール出力ではなく「データ」として結果を評価します。
PDQ Connect で表示・フィルター・ターゲティングを行うため、スキャナーの出力は最終的に、整形された予測可能な JSON 形式へ変換される必要があります。
PDQ Connect は、一貫した構造とデータ型を維持するため、この JSON 変換をバックエンドで自動的に実施します。

そのため、以下の点に注意してください。
  1. スキャナースクリプトは、ネイティブの PowerShell オブジェクトを返してください
  2. スクリプト側で JSON シリアライズを制御しないでください
  3. Format 系コマンドレットなどの整形処理や、コンソール向け出力はサポートされません

PowerShellスキャンラッパー

PDQ Connect は、PowerShellスキャン実行時に内部ロジック（「ラッパー」）を使用して、Connect アプリケーションで利用できるように、スクリプト出力の処理および正規化を行います。

ラッパーでは、主に以下の処理が行われます。
    1. ユーザーのスクリプトを実行する
    2. PowerShell の出力ストリームへ書き込まれた内容を収集する
    3. 結果を予測可能なフラット構造へ正規化する
    4. 最終的な出力を適切な JSON に変換する
ユーザーが作成したスクリプトに ConvertTo-Json が含まれている場合、その部分は実行前に自動的に削除されます。
これは二重シリアライズを防ぎ、PDQ Connect 側でスキャナー結果の処理および保存方法を一元管理するためです。
Warning
スクリプトはオブジェクトのみを返してください。JSON への変換は PDQ Connect が自動的に処理します。

スキャナーラッパーを使用したローカルテスト

対話型 PowerShell セッションでは正常に動作するスクリプトでも、スキャナー実行時には異なる動作となる場合があります。

高度なトラブルシューティングを支援するため、以下にスキャナーラッパーの改変版をご用意しています。
このラッパーは PowerShell プロンプト上で実行できるよう調整されていますが、PDQ Connect が PowerShellスキャン実行時にバックエンドで使用しているロジックを再現しています。このラッパーは、診断用途としてのみ提供されています。ほとんどのお客様は使用する必要はありません。


ローカルテスト用ラッパー（高度なトラブルシューティング用）

このラッパーで期待通りの結果が得られる場合、PDQ Connect の PowerShellスキャンでも同様に動作します。
    1. # Load and sanitize external script, stripping any trailing ConvertTo-Json

    3. param (
    4.     [Parameter(Mandatory)]
    5.     [ValidateScript({ Test-Path $_ -PathType Leaf })]
    6.     [string]$ScriptPath
    7. )

    9. $originalScript = Get-Content -Path $ScriptPath -Raw

    11. $convertToJsonPattern = '\|\s*ConvertTo-Json\b[^\r\n]*\s*$'

    13. $cleanedScript = [regex]::Replace(
    14.     $originalScript.TrimEnd(),
    15.     $convertToJsonPattern,
    16.     '',
    17.     'IgnoreCase'
    18. ).TrimEnd()

    20. $scriptBlock = [scriptblock]::Create($cleanedScript)

    22. & $scriptBlock |
    23. ForEach-Object {
    24.     if ($null -eq $_) { return }

    26.     if ($_ -is [hashtable] -or $_ -is [System.Collections.Specialized.OrderedDictionary]) {
    27.         $_ = [pscustomobject]$_
    28.     }

    30.     $out = [ordered]@{}
    31.     foreach ($p in $_.PSObject.Properties) {
    32.         $value = $p.Value
    33.         if ($value -is [datetime]) {
    34.             $value = $value.ToString('o')
    35.         }
    36.         $out[$p.Name] = $value
    37.     }

    39.     [pscustomobject]$out
    40. } | ConvertTo-Json -Depth 1 -Compress

関連情報

PowerShellスキャンは構造化出力を前提としているため、スキャナー結果の整形に使用する PSCustomObject に関する以下の記事もあわせてご参照ください。
PSCustomObject について知りたかったことのすべて（Microsoftのページを開きます）


    • Related Articles

    • PowerShellスキャンが正常に動作しません

      PowerShell スキャン が期待通りに動作しない場合、以下の点に問題がないかご確認ください。 PowerShell スキャン の詳細につきましては、こちらをご参照ください。 結果に数字しか表示されない： スクリプトがオブジェクトではなく単純文字列を出力しています。すべての値を PSCustomObject で返してください。 想定した列が表示されない： 出力が整形された、またはコンソールへ書き込まれています。整形用 Cmdlet を削除し、生オブジェクトを返してください。 ...

    • レジストリの展開

      PDQ Connect では、PowerShell を使用して管理対象端末にレジストリを展開できます。 レジストリファイル（.reg）からのインポート レジストリキーをデプロイする最も簡単な方法は、既存のレジストリキーをエクスポートし、それをターゲットデバイスへインポートする方法です。 以下の例では、「RegistryKey.reg」というレジストリキーを使用し、その中に「Deployed by Connect」というレジストリ値が含まれています。 PDQ Connect ...

    • コマンド実行ツール

      デバイスの詳細画面からPowerShellコマンドとコマンドプロンプト（CMD）を使ったコマンドを実行できます。コマンドタブ内から直接操作できるため、専用のアプリを起動することなく、迅速な操作、調査対応などを行うことができます。 コマンドツールの利用方法 コマンドの実行を開始するには、デバイスの詳細画面の「Commands」タブに移動します。ここからコンソールが表示され、PowerShellコマンドを実行して出力を確認できます。ほとんどのコマンドは数秒以内に実行が完了し、結果が返されます。 ...

    • ショートカットファイル（.link）の配布が上手くいきません

      事象 PDQ Connect でデスクトップショートカットを配布する際、ブラウザの制限により問題が発生する場合があります。.lnk ファイルを File Copy ステップで直接アップロードすると、ブラウザがショートカットを解決し、ショートカットそのものではなくリンク先のファイルをアップロードしてしまいます。この挙動により、意図したとおりにショートカットを配布できない場合があります。 この問題を回避する 2 つの方法を示します。 方法 1：ショートカットを zip 化して配布 ...

    • ウイルス対策ソフトの例外設定

      PDQ Connect Agent の実行プログラムがセキュリティソフトにより有害なソフトウェアとして検知される場合は、以下の項目を監視対象から除外してください。 除外必須のサービス PDQConnectAgentサービス PDQConnectUpdaterサービス 除外するディレクトリ PDQ Connect Agent のインストールディレクトリと実行ディレクトリがセキュリティソフトから有害なソフトウェアと検知されてしまう場合には、セキュリティソフトの監視対象から以下を除外してください。 ...