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

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FE69i9Hix4QbibmZGmr71%2Fimage.png?alt=media&#x26;token=962865a1-6722-4b53-b67a-9ebe4bc76276" alt=""><figcaption></figcaption></figure>

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

***

### 概要 <a href="#overview" id="overview"></a>

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

**フロー:**

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

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

***

{% stepper %}
{% step %}
**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) を確認してください。
{% endstep %}

{% step %}
**ジョブをエージェントに追加する**

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

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

ポリシーの**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のポリシーを使います。
{% endstep %}

{% step %}
**タイムアウトと動作**

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

### まとめ <a href="#summary" id="summary"></a>

| 手順 | 操作                                                                                                                      |
| -- | ----------------------------------------------------------------------------------------------------------------------- |
| 1  | **終了0** (成功) または**0以外** (失敗) で終わる**コマンドまたはスクリプト**を実行する**PowerShell** (`powershell.exe` または `pwsh`) の1タスクを持つ**ジョブ**を作成する |
| 2  | ジョブをエージェントへ展開する (JobsディレクトリまたはAPI)。スケジュールやイベントは不要。ポリシーエンジンが呼び出します。                                                      |
| 3  | **ポリシー**の**Extension.CustomFilterJobId**をそのジョブの**id**に設定する。                                                             |
| 4  | ポリシー評価時にエンジンがジョブを**1回**実行し、結果 (成功/失敗) でフィルターが通るかが決まる。                                                                   |

これにより、**評価ごとにPowerShellで特定処理を1回実行するジョブを含むポリシー**が構成できます。ジョブ形式とポリシーのExtensionの詳細については、[ジョブ: 定義と形式](/keeperpam/jp/endpoint-privilege-manager/reference/jobs-definition-and-format.md)および[ポリシーJSONとExtension](/keeperpam/jp/endpoint-privilege-manager/reference/policy-json-and-extension.md)をご参照ください。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/jp/endpoint-privilege-manager/policies/policy-examples/advanced-examples/policy-create-a-policy-with-job-running-powershell.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.