ポリシーのコントロール (PowerShellでジョブを実行するポリシーの作成)

ポリシー評価時にカスタムPowerShellを実行するKEPMの高度な構成

対象: IT管理者向けです。ポリシーがカスタムフィルタージョブを使い、そのジョブがPowerShellを実行してポリシー評価ごとに1回だけ特定の処理を行う方法を示します (例: スクリプトの結果に基づき要求を許可または拒否)。

概要

一部のポリシーではカスタムフィルターを使えます。組み込みフィルター (ユーザー、マシン、アプリケーション、時刻) に加え、評価中にジョブを呼び出せます。そのジョブは評価要求ごとに1回実行されます。単一タスクとしてPowerShellを実行する場合、カスタムロジック (ファイルの確認、APIの呼び出し、一回限りのスクリプトなど) を実装し、結果に応じてポリシーが適用されるかを決められます。

フロー:

要求が評価される (例: アプリの特権昇格)。
ポリシーのExtension.CustomFilterJobIdにジョブid (例: allow-elevation-if-script-ok) が設定されている。
ポリシーエンジンがそのジョブ用にエージェントのevaluateエンドポイントを呼び出し、評価コンテキスト (ユーザー、マシン、アプリケーションパスなど) を渡す。
ジョブが1回実行され、タスクがコマンドまたはスクリプト付きでPowerShellを実行する。
ジョブの結果 (成功または失敗) がポリシーに使われる。通常成功=フィルター通過 (ポリシー適用可)、失敗=フィルター不通過 (この要求にはポリシー非適用)。

用途: スクリプトが条件を満たすときだけ昇格を許可する (マシンがリストに含まれる、時間帯、外部チェックなど)。またはPowerShellのチェックが失敗したときに拒否する (例: 「許可されたパスからのプロセスか」)。

PowerShellを1回実行するジョブの作成

ジョブはポリシーエンジンからのみ (evaluate API経由) 呼び出され、スケジュールやイベントではありません。1つのタスクがPowerShellを実行し、終了コード0 (成功) または0以外 (失敗) で終了します。ポリシーエンジンがカスタムフィルターの成否に使います。

ジョブ例: allow-elevation-if-script-ok.json

Jobs/allow-elevation-if-script-ok.json として保存します (別のidでも可。ポリシーではそのidを使います)。

{
  "id": "allow-elevation-if-script-ok",
  "name": "Custom filter: run PowerShell once",
  "description": "Runs a PowerShell command once per policy evaluation; exit 0 = filter pass, non-zero = filter fail",
  "enabled": true,
  "priority": 5,
  "events": [],
  "parameters": [
    { "name": "UserName", "type": "String", "required": false },
    { "name": "FilePath", "type": "String", "required": false },
    { "name": "MachineName", "type": "String", "required": false }
  ],
  "tasks": [
    {
      "id": "run-powershell",
      "name": "Run PowerShell once",
      "executionType": "Service",
      "command": "powershell.exe",
      "executablePath": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
      "arguments": "-NoProfile -ExecutionPolicy Bypass -Command \"& { if (Test-Path 'C:\\AllowElevation.txt') { exit 0 } else { exit 1 } }\""
    }
  ]
}

動作:

1タスクが powershell.exe を単一コマンドで実行します。C:\AllowElevation.txt の有無を確認し、あれば終了 0、なければ終了 1。
ポリシーエンジンがコンテキスト (UserName、FilePath、MachineName など) をジョブに渡します。パラメータ置換でスクリプト内から参照できます (例: -Command "& { ... $env:UserName ... }" またはスクリプトファイル内の {UserName})。
executablePath — マシン上のPowerShellの完全パス、またはパス変数が使える場合はそれを指定します (例: {systemroot}\System32\WindowsPowerShell\v1.0\powershell.exe)。Linux/macOSでは pwsh または適切なシェルと別スクリプトを使います。

インラインではなくスクリプトファイルを実行する場合:

"arguments": "-NoProfile -ExecutionPolicy Bypass -File \"{approot}\\Scripts\\CheckElevationAllowed.ps1\""

スクリプトはコンテキスト (環境変数やジョブが渡す引数など) を読み、終了0または1を返します。評価ごとにそのスクリプトを1回実行します。

スクリプト内でパラメータを使う場合:

evaluate APIがコンテキストをパラメータとして渡す場合、タスクのargumentsで参照できます。例:

"arguments": "-NoProfile -ExecutionPolicy Bypass -Command \"& { param($User,$Path); ... }\" -User \"{UserName}\" -Path \"{FilePath}\""

パラメータ名はポリシーエンジンが送る内容に依存します。製品のevaluateリクエスト本文で正確なキー (例: UserName、FilePath、MachineName) を確認してください。

ジョブをエージェントに追加する

JSONファイルをJobsディレクトリに置く (例: Jobs/allow-elevation-if-script-ok.json) か、POST /api/Jobsでジョブを作成する。
ジョブが有効であり、指定したパスにPowerShellがあることを確認する。スケジュールやイベントは不要。ポリシーエンジンが evaluate エンドポイントを呼んだときだけ実行されます。

カスタムフィルタージョブを使うポリシーの作成または編集

ポリシーのExtensionでCustomFilterJobIdを使用したジョブid (例: allow-elevation-if-script-ok) に設定します。ポリシーエンジンが評価中にそのジョブを呼び出し、結果でフィルターが通るかを決めます。

例 (概念上のポリシー JSON):

{
  "PolicyId": "elevate-only-when-script-allows",
  "PolicyName": "Allow elevation only when PowerShell check passes",
  "PolicyType": "PrivilegeElevation",
  "Status": "enabled",
  "Controls": ["ALLOW"],
  "Rules": [ { "Operator": "And", "Expressions": [] } ],
  "Filters": {
    "UserCheck": { "Users": ["*"] },
    "MachineCheck": { "Machines": ["*"] },
    "ApplicationCheck": { "Applications": ["*"] }
  },
  "Extension": {
    "CustomFilterJobId": "allow-elevation-if-script-ok"
  }
}

特権昇格要求の評価時、エンジンはallow-elevation-if-script-okジョブを要求コンテキスト付きで1回実行します。
PowerShellタスクが終了コード0ならカスタムフィルター通過し、ポリシーが適用可能です (ここではALLOW)。
ジョブが失敗 (0 以外の終了またはタイムアウト) ならカスタムフィルター不通過となり、この要求にはポリシーが適用されません。

ポリシーは通常Keeper管理コンソールで作成・編集します。デプロイでUIにExtensionまたはカスタムフィルター設定がある場合はそこでジョブidを設定し、なければ上記のExtensionを含むファイルベースまたはAPIのポリシーを使います。

タイムアウトと動作

カスタムフィルターのタイムアウト: ポリシーエンジンはジョブの完了をタイムアウト内で待ちます (例: 既定30秒)。KeeperPolicyプラグイン (例: customfilter.timeout_seconds) で構成します。ジョブ (またはPowerShell) がそれより長いと評価がタイムアウトし、カスタムフィルターは失敗扱いになります。
1回実行: 要求ごとのポリシー評価のたびにジョブは1回呼び出されます。評価が複数回ある場合を除き、PowerShellの繰り返し実行はありません。
PowerShellのパス: 対象マシンすべてに存在するパスを使います (Windowsでの例: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe)。PowerShell Coreでは pwsh と適切なパスを使います。

まとめ

手順

操作

終了0 (成功) または0以外 (失敗) で終わるコマンドまたはスクリプトを実行するPowerShell (powershell.exe または pwsh) の1タスクを持つジョブを作成する

ジョブをエージェントへ展開する (JobsディレクトリまたはAPI)。スケジュールやイベントは不要。ポリシーエンジンが呼び出します。

ポリシーのExtension.CustomFilterJobIdをそのジョブのidに設定する。

ポリシー評価時にエンジンがジョブを1回実行し、結果 (成功/失敗) でフィルターが通るかが決まる。

これにより、評価ごとにPowerShellで特定処理を1回実行するジョブを含むポリシーが構成できます。ジョブ形式とポリシーのExtensionの詳細については、ジョブ: 定義と形式およびポリシーJSONとExtensionをご参照ください。

前へポリシーのコントロール (設定を構成するポリシーの作成)次へポリシーのコントロール (ファイルリダイレクトの作成)

最終更新 11 日前