カスタムプラグイン統合ガイド

カスタムプラグイン統合ガイド

本ガイドでは、カスタム実行ファイルを管理プラグインとして登録する方法を取り扱います。管理プラグインとは、エージェントが起動・監視・再起動し、自身のライフサイクルに組み込む常駐コンポーネントです。まだ統合の概要を読んでいない場合はそちらから始めてください。プラグインパターンの定義、ジョブタスクよりプラグインが適する場合、本ガイドの前提となる概念がまとまっています。

スケジュールで動いて終了するツール (スキャナー、レポート、メンテナンスジョブなど) を作る場合はカスタムジョブ統合ガイドをご参照ください。本ガイドは常駐プロセス向けです。

1

プラグインJSONファイル

場所と命名

プラグインは以下の場所にJSONファイルを置くことで登録されます。

{AgentRoot}/Plugins/{PluginId}.json

.json を除いたファイル名は、ファイル内の id フィールドと一致する必要があります。MyBridge.json には "id": "MyBridge" を含めます。プラグインIDはプラグイン設定呼び出し GET /api/PluginSettings/MyBridge のキーにもなるため、安定した一意の識別子を選び、デプロイ後に変更しないでください。

バイナリは通常以下の場所に置きます。

{AgentRoot}/Plugins/bin/{PluginId}/{PluginId}.exe    (Windows)
{AgentRoot}/Plugins/bin/{PluginId}/{PluginId}        (Linux / macOS)

JSONの executablePath にはエージェントルートからの相対パス、またはデプロイレイアウト上必要なら絶対パスを指定します。

プラグインの構造 (JSON)

注釈付きの完全な例です。

{
  "id": "MyBridge",
  "name": "My Bridge",
  "description": "Bridges inbound commands to an internal service.",
  "version": "1.0.0",

  "pluginType": "Executable",
  "executablePath": "bin/MyBridge/MyBridge.exe",
  "supportedPlatforms": ["Windows"],

  "Subscription": {
    "Topic": "MyBridge",
    "Qos": 2,
    "CleanSession": true
  },

  "metadata": {
    "mqttRole": ["subscriber", "publisher"],
    "mqttTopics": {
      "publish": ["KeeperLogger", "MyBridge/Responses/+"],
      "subscribe": ["MyBridge/Commands/+"]
    }
  },

  "startupPriority": 60,
  "autoStart": true,
  "executionContext": "Service",
  "requiresMonitoring": true,
  "autoRestart": true
}

フィールドの説明

フィールド

必須

説明

id	はい	安定した識別子。ファイル名と一致させる。/api/PluginSettings/{id} のキーとして使われる。
name	いいえ	ログや管理画面に表示される名前。
description	いいえ	人が読める説明。
version	いいえ	セマンティックバージョン文字列。診断と変更追跡に使う。
pluginType	はい	単体バイナリの場合は Executable。その他の型はエージェントのバージョンによる。管理者に確認する。
executablePath	はい	バイナリへのパス。エージェントルート相対または絶対。
arguments	いいえ	起動時にバイナリへ渡すコマンドライン引数。一部の変数置換に対応。利用可能なトークンは管理者に確認する。
supportedPlatforms	はい	"Windows"、"Linux"、"macOS" の配列。
Subscription	はい	このプラグインの主MQTT購読。プラグイン向けMQTT をご参照ください。
metadata	はい	mqttTopics とプラグイン固有キーのコンテナ。
metadata.mqttTopics.publish	はい	パブリッシュしてよいトピック。ブローカーがこのリストを強制する。
metadata.mqttTopics.subscribe	はい	主たる Subscription トピック以外で購読するトピック。
startupPriority	いいえ	プラグイン起動順。小さいほど先。デプロイ内の他プラグインの値を見て、依存関係に合う値を選ぶ。
autoStart	いいえ	true でエージェント起動時に自動起動。false はオンデマンドやジョブ起動。省略時は false。
executionContext	いいえ	Service でエージェントのサービスアカウントとして実行。セキュリティ要件に合わせる。
requiresMonitoring	いいえ	true でエージェントがプロセスを監視し、想定外終了を検知する。
autoRestart	いいえ	true で監視が停止を検知したときに再起動。requiresMonitoring も true のときに意味がある。
enabled	いいえ	false にすると登録のみで実行しない。開発時に便利。

2

プラグイン向けMQTT

プラグインはジョブタスクとは、MQTTブローカーとのやり取りが以下の3点で異なります。

1. 主たる Subscription がある。

2. ジョブのルートではなく metadata.mqttTopics 下でトピックを宣言する。

3. MQTTクライアントIDの形式が異なる。

主購読

各プラグインは主MQTT購読を宣言します。

"Subscription": {
  "Topic": "MyBridge",
  "Qos": 2,
  "CleanSession": true
}

エージェントがプラグインを名前付きコンポーネントとして識別し通信するために使うトピックです。metadata.mqttTopics で宣言する追加トピックとは別です。欠落や重複が許されないコマンドには Qos: 2 を使います。永続セッションが必要なユースケースでない限り CleanSession: true にします。

パブリッシュ・購読トピックの宣言

パブリッシュまたは購読するすべてのトピックを metadata.mqttTopics に宣言します。ブローカーがリストを強制するため、未宣言トピックへのパブリッシュは接続に成功しても拒否されます。

"metadata": {
  "mqttTopics": {
    "publish": ["KeeperLogger", "MyBridge/Responses/+"],
    "subscribe": ["MyBridge/Commands/+"]
  }
}

実際に使うものだけを宣言します。# のような広いワイルドカードは本当に必要な場合に限ります。トピックリストを絞ると誤構成の影響範囲を抑えられます。

KeeperLogger へログを出す場合は publish に含めます。メッセージ形式はカスタムジョブ統合ガイドで説明する RequestMessage JSON構造と同じです。

プラグイン向けMQTTクライアントID形式

プラグインのMQTTクライアントIDはジョブタスクとは形式が異なります。ジョブの3要素 ({JobId}_{Token}_{Pid}) をプラグインに使わないでください。ブローカーはクライアントID形式でトピック権限チェックを振り分けるため、誤った形式ではチェックに失敗します。

サービスアカウントで動作するプラグイン (一般的なケース) の例:

{PluginName}_{ProcessId}

ユーザーセッションで動作するプラグインの例:

{PluginName}_{UserName}_{ProcessId}

{PluginName} は短い固定トークンで、多くの場合プラグインの id に揃えます。完全な例:

import os

plugin_name = "MyBridge"
pid = os.getpid()
client_id = f"{plugin_name}_{pid}"
# 例: "MyBridge_51204"

ブローカーへの接続

ブローカーアドレスは環境変数として注入されません。起動時にジョブタスクと同様、プラグイン設定から取得します。エージェントが提供する KeeperApiBaseUrl を使って GET /api/PluginSettings/KeeperPrivilegeManager を呼びます。コード例は概要ページをご参照ください。

ジョブタスクとは異なり、プラグインには {KeeperApiBaseUrl} が引数として自動注入されません。プラグインJSONの arguments でAPIベースURLを明示して渡すか、ポートが保証されているデフォルト https://127.0.0.1:6889 にフォールバックする必要があります。

ブローカーはループバック上でTLSを使います。MQTTクライアントをTLS向けに設定して接続し、組織のCAバンドルがあれば利用し、なければセキュリティポリシーに従いループバック限定で証明書検証を無効にします。

3

HTTPS経由のプラグイン設定

プラグインは、システム全体の KeeperPrivilegeManager 設定とは別に、プラグインIDに紐づくスコープ付き構成を読み取れます。

GET https://127.0.0.1:{httpsPort}/api/PluginSettings/MyBridge

マージ後の有効な設定が、文字列キーと文字列値のフラットなJSONオブジェクトとして返ります。設定の出所は以下のとおりです。

• プラグインJSONファイル (Plugins/MyBridge.json)

• 統合ストレージ (ポリシーで適用)

• システムデフォルト

ディスク上のJSONを直接解析するのではなく、常にこのエンドポイントで有効設定を読み取ってください。ディスク上のファイルはポリシー上書きを反映していない場合があります。

実行中のプラグインから単一の設定キーを更新する場合:

PUT https://127.0.0.1:{httpsPort}/api/PluginSettings/MyBridge/{settingName}

いずれもプラグイン階層の認可が必要です。エージェントが起動したプロセスでないと、プロセス認証に合格できません。同じバイナリを手動実行すると 403 になります。プラグイン設定APIの全体は HTTPリファレンスをご参照ください。

4

署名とプロセス信頼

Plugins/ 配下のパスに置かれたバイナリは、Jobs/bin/ より厳しい信頼ルールの対象です。プラグインオーケストレータがバイナリを起動するとプロセスが起動済み登録簿に載り、ジョブタスクと同様にMQTTとプラグイン階層HTTPSへのアクセスが付与されます。ただしプラグイン実行ファイルに適用されるパス前提と証明書チェックはより厳しいです。

本番のプラグインバイナリはすべて署名してください。 Windowsでは標準のプラグイン信頼経路にAuthenticodeが必要です。macOSではApple Developer IDを使います。Linuxではデプロイの署名方針 (該当する場合はGPG署名パッケージやIMA) に合わせます。

デプロイでサムプリントの明示的な信頼登録が必要な場合のみ、コード署名証明書のサムプリントを appsettings.json の Settings:AlternativeSignatures に追加します。

{
  "Settings": {
    "AlternativeSignatures": [
      "A1B2C3D4E5F6789012345678901234567890ABCD"
    ]
  }
}

appsettings.json を変更したらエージェントサービスを再起動します。

本番検証を手動実行に頼らないでください。 エージェント外でプラグインバイナリを手動起動した場合、MQTT接続やプラグイン設定呼び出しには証明書チェックをパスする必要があります。オーケストレータが起動したバイナリは既に登録されているためそのチェックをスキップします。本番の挙動と一致すると決めつける前に、開発環境で手動起動を検証してください。

5

デプロイ

本番エージェントへの新規プラグイン追加は、ジョブのデプロイより手順が多くなりがちです。典型的には以下が必要です。

1. 組織のリリース手順に従ったパッケージ化と署名。

2. プラグインJSONの executablePath が指す場所へ、対象エンドポイントすべてにバイナリを配置。

3. 対応しているデプロイ手段で {AgentRoot}/Plugins/{PluginId}.json にプラグインJSONを配置 (Last Known Good が有効なら手動コピーだけにしない)。

4. エージェントの再起動またはプラグインの再読み込みで、オーケストレータに新規登録を認識させる。

新規プラグインを投入してよい経路は環境ごとに異なります。Keeper管理者に確認してください。調整なしの任意ファイル配置は、Last Known Goodの保護やパッケージ前提と衝突することがあります。

デプロイ後のプラグイン設定の更新にエージェント再起動は不要です。プラグイン階層で認証されたプロセスから PUT /api/PluginSettings/{PluginId}/{settingName} を使うか、コンソール経由で設定ポリシーを更新します。

設定が反映されない場合は POST /api/PluginSettings/{PluginId}/revert でディスク上のプラグインJSONを統合ストレージへ再インポートし、その後 GET で有効値を確認します。

チェックリスト

フリートへ展開する前に全項目を確認してください。

#

確認項目

1	プラグインの id がファイル名と一致する。各対応プラットフォームで executablePath にバイナリがある
2	Subscription.Topic が設定され、デプロイ内のプラグイン間で一意である
3	metadata.mqttTopics.publish に、バイナリが実際にパブリッシュするすべてのトピックが含まれる
4	metadata.mqttTopics.subscribe に、Subscription.Topic 以外で購読するすべてのトピックが含まれる
5	MQTTクライアントIDがプラグイン形式 (PluginName_Pid)。ジョブの3要素形式ではない
6	バイナリは署名済み。必要ならサムプリントが AlternativeSignatures にある
7	実行中プラグイン内から GET /api/PluginSettings/KeeperPrivilegeManager が broker.host と broker.port を返す
8	GET /api/PluginSettings/{PluginId} が想定どおりのプラグインスコープ設定を返す
9	MQTTに接続でき、主購読が有効で、KeeperLogger へのパブリッシュがログに見える
10	autoStart、requiresMonitoring、autoRestart を運用で検証。CPU負荷、セッション挙動、再起動間隔が許容範囲か確認する
11	同一バイナリをジョブと二重に登録していない。役割ごとに実行ファイルを分ける

トラブルシューティング

症状

確認先

デプロイ後にプラグインが起動しない	対象OSで executablePath が解決するか。署名を確認。エージェントログのオーケストレータエラーを確認
MQTT接続が拒否される	信頼済みとして登録されていない。手動ではなくオーケストレータが起動したか確認
MQTTは接続するがパブリッシュが拒否される	metadata.mqttTopics.publish にトピックがない。文字列が完全一致するか確認
GET /api/PluginSettings/MyBridge が 403	プラグイン認証されていない。手動ではなくエージェントがバイナリを起動したか確認
設定変更が反映されない	統合ストレージがJSONを上書きしている可能性。/revert で再インポート後に再確認
プラグインがループで予期せず再起動する	autoRestart: true と起動エラーで終了するバイナリの組み合わせ。根本原因を直してから自動再起動を再有効化
重複プロセスが検出される	同一バイナリがプラグインとジョブタスクの両方に登録されている。役割ごとに実行ファイルを分ける