ポリシーJSONと拡張オブジェクト

対象: JSONでポリシーを編集するIT管理者 (ファイルベースのポリシーや高度なモードなど)、またはExtensionセクションの意味を把握する必要がある方。

概要

ポリシーは、通常はKeeper管理コンソールから管理されます。高度な運用やエアギャップ環境ではJSONとして扱うこともあります。ポリシーJSONには、id、name、type、status、controls、rules、filtersなどのコアフィールドに加え、フォルダや許可リスト、構成プッシュなどの追加オプション用の任意のExtensionオブジェクトが含まれます。

基本的なポリシー構造 (JSON)

最小限のポリシーは、JSONでは以下のようになります。

{
  "PolicyId": "policy-123",
  "PolicyName": "Block PowerShell Execution",
  "PolicyType": "CommandLine",
  "Status": "enabled",
  "Controls": ["DENY"],
  "Rules": [
    {
      "Operator": "And",
      "Expressions": [
        {
          "Type": "Contains",
          "Value": "powershell.exe"
        }
      ]
    }
  ],
  "Filters": {
    "UserCheck": { "Users": ["*"] },
    "MachineCheck": { "Machines": ["*"] },
    "ApplicationCheck": { "Applications": ["powershell.exe"] }
  }
}

コアフィールド:

フィールド

必須

説明

PolicyId	はい	ポリシーの一意ID
PolicyName	はい	人が読める名前
PolicyType	はい	PrivilegeElevation、FileAccess、CommandLine、LeastPrivilege、HttpAccess など。構成プッシュでは SettingsUpdate など
Status	はい	enabled / enforce、disabled / off、monitor、monitor_and_notify (または製品の同等表記)
Controls	はい	制御種別の配列: ALLOW、DENY、MFA、JUSTIFY、APPROVAL、AUDITなど
Rules	はい (通常)	ポリシーを適用するために一致が必要な論理ルール (And/Orと式)
Filters	はい	UserCheck、MachineCheck、ApplicationCheck (および任意で日時) による、適用対象のユーザーと対象の範囲指定

Extensionセクション

Extensionはポリシー上の任意オブジェクトで、ポリシーエンジンまたは構成プロセッサが利用する追加の構成を保持します。主な用途は以下のとおりです。

Extension.Folders

アプリケーションまたはファイルアクセスのポリシーと組み合わせ、パターンを特定フォルダに限定するために使われます。製品はApplicationCheck (例: *.exe) とExtension.Folders (例: ["{desktop}"]) を組み合わせ、{desktop}\*.exe のようなフルパスパターンを得られます。詳しくは参考資料: ワイルドカードをご参照ください。

例:

"Extension": {
  "Folders": ["{desktop}", "{downloads}"]
}

Extension.AllowCommands

一部の展開では、特権昇格など向けに許可リスト (コマンドまたはコマンド断片) を定義するために使われます。製品が許可リストモデルを使う設定の場合、このリストにないコマンドは、別のポリシーで明示的に許可されない限り許可されません。

例:

"Extension": {
  "AllowCommands": [
    "ForceTimeSync",
    "1"
  ]
}

「今すぐ同期」の時刻同期では、昇格コマンドが ForceTimeSync 1 のような形になることがあります。コマンド名と引数の両方を含めると、そのフローが許可されます。

ドキュメントまたは管理コンソールでAllowCommandsが利用可能とされている場合に使います。正確な挙動はポリシー種別と製品バージョンに依存します。

SettingsUpdate / 構成ポリシー向けのExtension

構成をプッシュするポリシー (例: プラグイン設定、Redirectルール) では、Extensionで何をどのように更新するかを指定します。

• PluginName: 更新するプラグイン (例: KeeperPolicy、RedirectEvaluator)。プロセッサは Plugins/ 配下の当該プラグインのJSONファイルに書き込みます

• TargetFile: 任意。PluginNameの代わりに更新するファイルのアプリルートからの相対パス

• Action: 例: Update または Add

• SettingsJson: 書き込むJSON全体 (プラグイン構成では、対象プラグインJSON全体が置き換えられることが多いため、必要なフィールドはすべて含める)

例 (概念的な例: RedirectEvaluator)

"Extension": {
  "PluginName": "RedirectEvaluator",
  "Action": "Update",
  "SettingsJson": "{ \"id\": \"RedirectEvaluator\", \"metadata\": { \"redirect\": { \"enabled\": true, \"rules\": [ ... ] } }, ... }"
}

SettingsUpdateポリシーでは、Extensionの構造は製品の構成プロセッサによって定義されます。正確なスキーマは管理者向けまたは展開ドキュメントをご参照ください。

Extension.CustomFilterJobId

一部のポリシーでは、ジョブで実装されたカスタムフィルターが利用できます。Extension.CustomFilterJobIdはそのジョブを識別します。ポリシーエンジンは評価時に当該ジョブを呼び出し (例: HTTPタスク経由)、結果に基づいてリクエストの包含/除外を行います。対応状況と形式はポリシー種別と製品ドキュメントをご参照ください。

ポリシーJSONの入手元

• 管理コンソール: ポリシーは通常、Keeper管理コンソールで作成・編集され、エージェントに同期されます。バックエンドが参照用にJSONを公開またはエクスポートする場合があります

• ファイルベース: エアギャップやテストでは、JSONファイルをKeeperPolicyのpoliciesフォルダ (例: プラグインディレクトリ配下) に配置できます。ファイルベースのポリシーはエージェントによって読み込まれ、当該エージェントではクラウド同期ポリシーより優先されることが多いです

• 前処理: 読み込み後、ポリシーは前処理されます (例: コレクションの解決、パス変数の解決、Extension.Foldersからの結合アプリケーションパターンの構築)。「現在のポリシー」やデバッグ用エクスポートに表示される内容は、すでに前処理済みの場合があります

currentPolicies.json

currentPolicies.jsonは、KeeperPolicyプラグインによって現在読み込まれ前処理されたポリシーのデバッグ用スナップショットです。自動的に作成され、どのポリシーが有効か、解決後に各ポリシーがどのフィルター (ユーザー、マシン、アプリケーション、フォルダ) を使うかを正確に確認するために利用できます。

保存場所

ファイルはKeeperPolicyプラグインディレクトリ、つまりKeeperPolicy実行ファイルがあるフォルダに書き込まれます。正確なパスはインストールに依存し、多くの場合は以下のいずれかです。

• {approot}\Plugins\KeeperPolicy\currentPolicies.json

• または、プラグインがサブフォルダ (例: bin\Release\net8.0) から動く場合は、そのサブフォルダの currentPolicies.json

• または、一部の展開ではpoliciesサブフォルダ配下: ...\KeeperPolicy\policies\currentPolicies.json

KeeperPolicyのインストール場所を確認してください。ファイルはプラグインのバイナリと同じ階層、またはその配下に現れます。

作成タイミング

KeeperPolicyは、以下の状況で currentPolicies.json を自動的に作成または更新します。

• 前処理後: ポリシーレジストリが前処理されたとき (コレクションがユーザー/マシンUIDに解決され、FiltersとExtension.Foldersからアプリケーションおよびフォルダパターンが構築される)

• 起動時: プラグイン起動時にレジストリにすでにポリシーがある場合、初期エクスポートが書き込まれます。起動時にレジストリが空の場合は、初回の前処理完了後 (例: バックエンドからポリシーを受信した後、またはpoliciesフォルダから読み込んだ後) にファイルが書き込まれます

• ポリシー更新後: ストレージからポリシーが更新されたとき (例: 管理コンソールから同期)、またはpoliciesフォルダから (ファイルベースのポリシー)、更新後のスナップショットがエクスポートされます

• ファイルウォッチャーのマージ後: プラグインのファイルウォッチャーがpoliciesフォルダの変更を検出し、新規または変更されたポリシーファイルをマージしたとき、マージ後のスナップショットがエクスポートされます

このファイルを手で作成・編集する必要はありません。プラグインからの参照専用出力であり、デバッグと確認用です。

含まれる内容

ファイルは前処理済みポリシーレジストリのスナップショットです。通常、以下が含まれます。

• レジストリ内のすべてのポリシー (有効、無効、モニター)

• 解決済みフィルター: 例: UserUids、MachineUids、GroupUids (該当する場合はコレクションが具体UIDに展開)、ApplicationPatterns、FolderPatterns (マッチに使うパスとパターン。アプリケーションとフォルダの結合パターンを含む)

• ポリシーメタデータ: PolicyId、PolicyName、イベント種別、ポリシー状態 (有効/無効/モニター)、制御フラグ (例: HasAllow、HasDeny、HasMfa)

ダッシュボードやファイルの生JSONではなく、エンジンがマッチに使う実効的なフィルターが確認できます。

フィルターの組み合わせにどのポリシーが当てはまるかを読み解くには

currentPolicies.json を以下のように使えます。

1. どのポリシーが有効か確認する: ファイルを開き、すべてのポリシーを列挙する。有効、モニター、無効の区別に注意する

2. 解決済みの適用範囲を確認する: 各ポリシーについてUserUids、MachineUids、ApplicationPatterns (および存在すればFolderPatterns) を確認する。コレクション解決およびパス/パターン構築後に、ポリシーがどのユーザー、マシン、アプリケーション/パスパターンを対象にしているかが分かる

3. 特定のリクエストについて推論する: 与えられた「ユーザー + マシン + アプリケーション (およびパス)」について次を比較する。

   • リクエストのユーザーUID、マシンUID、アプリケーションパス

   • 各ポリシーのUserUids、MachineUids、ApplicationPatterns、FolderPatterns。 これらのフィルターが当該ユーザー、マシン、パスに一致するポリシーが、そのリクエストに適用されうるポリシーである (ルールやその他のチェックは評価時に別途行われる)

4. 「ポリシーが一致しない」デバッグ: 想定どおりポリシーが適用されない場合、currentPolicies.json で当該ポリシーが存在し有効であること、および解決済みフィルター (ユーザー、マシン、アプリケーション/フォルダパターン) がテスト中のユーザー、マシン、パスを実際に含むことを確認する。コレクションが解決されていない、パターンが欠けている場合はスナップショット上で分かる

5. バックアップまたは比較: ファイルをコピーしてバックアップにしたり、マシン間やポリシー変更の前後でスナップショットを比較する

注: JSONの正確な構造 (プロパティ名、ネスト) は製品バージョンにより異なる場合があります。デバッグ補助として利用し、権威あるスキーマは製品または管理者向けドキュメントをご参照ください。

ポリシーJSONを安全に編集する

• デプロイ前にJSONを検証する (構文、および利用可能ならスキーマ)

• 変更前に既存のポリシーファイルをバックアップする

• SettingsUpdateまたはExtension内のプラグインJSONの場合: SettingsJsonは対象ファイル全体を置き換えることが多い。必要なフィールド (id、name、executablePath、Subscription、metadata など) をすべて含めないと、プラグインが起動に失敗する場合がある

• ファイルベースのポリシーまたはプッシュした構成を変更した後、製品ドキュメントの指示に従いKeeperPolicyプラグイン (またはサービス) を再起動し、変更を取り込む