Endpoint AIops

Endpoint AIops

免責事項：コミュニティによって保守されているオープンソースプロジェクトです。**エンドポイント管理ベンダーとは提携、承認、協賛関係にありません。**製品名および商標名は各所有者に帰属します。MIT ライセンスです。

管理対象エンドポイントのフリート（シンクライアント、VDI エンドポイント、その他の一元管理デバイス）向けのガバナンスに基づく AI 運用です。組み込みのガバナンスハーネス（統合監査ログ、トークン／暴走予算ガード、取り消しトークンの記録、説明的なリスク階層）を備えています。ベンダーに依存しません。設定可能な方言を介して、エンドポイント管理サーバーの REST API（Bearer 認証）と通信します。詳しくは方言をご覧ください。自己完結型で、httpx と MCP SDK 以外の依存関係はありません。テストスイートはモックベースです。エンドポイント管理 REST パスは、実稼働中の管理サーバーに対してまだテストされていません。詳しくはdocs/VERIFICATION.mdをご覧ください。

機能

2 種類のシグネチャ分析と、それらを支える安全な読み取り・書き込み機能です。

• ログイン集中分析 — 「全員が午前 9 時にログインする」インシデントの際に、スライディングウィンドウ内の同時ログインの急増を検出し、ログインや起動時間を遅らせているエンドポイント／ユーザーを順位付けします。すべてのフラグは、ブラックボックスの判定ではなく数値とともに報告されます。
• パッチ／設定のドリフト — フリートから逸脱したエンドポイント（古いパッチレベル、想定外のエージェントバージョン、異なる OS ビルドや設定プロファイル）を検出します。宣言済みのベースラインがない場合は、フリート内の多数派からベースラインを導出するため、ゴールドイメージがなくても機能します。

動作する機能

• CLI（endpoint-aiops ...）：init、overview、endpoint list/get/assign-profile/reboot、session list/storm、drift report/patch、secret set/list/rm/migrate/rotate-password、doctor、mcp。
• MCP サーバー（endpoint-aiops mcp または endpoint-aiops-mcp）：13 個のツール（読み取り 10 個、書き込み 3 個）。すべてに同梱の @governed_tool ハーネスが適用されます。
• 暗号化された認証情報：管理サーバーの API キーは、暗号化ストア ~/.endpoint-aiops/secrets.enc（Fernet + scrypt）に保存され、ディスク上に平文で保存されることはありません。マスターパスワードでロックを解除します。マスターパスワードは、ENDPOINT_AIOPS_MASTER_PASSWORD（MCP／CI）から取得するか、対話型プロンプト（CLI）で入力します。
• 可逆性：endpoint_assign_profile（リスク high）は以前のプロファイルを取得し、「以前のプロファイルを再割り当てする」という逆操作の記述子を記録します。endpoint_reboot（リスク medium）は監査記録用に以前のオンライン状態を取得しますが、再起動に安全な逆操作はないため、取り消し操作は宣言しません。
• 安全性：状態を変更する CLI 操作（endpoint assign-profile、endpoint reboot）には二重確認が必要で、--dry-run に対応しています。

機能マトリックス（MCP ツール 13 個）

カテゴリ	ツール	数	読み取り／書き込み
概要	overview	1	読み取り
インベントリ	endpoint_list、endpoint_get、endpoint_health_score	3	読み取り
セッション	session_list、login_storm_analysis	2	読み取り
ドリフト	drift_report、patch_status、patch_compliance	3	読み取り
修復	endpoint_assign_profile	1	書き込み（high）
	endpoint_reboot	1	書き込み（medium）
取り消し	undo_list	1	読み取り
	undo_apply	1	書き込み（medium）

分析ツール（login_storm_analysis、drift_report、patch_status、 patch_compliance、endpoint_health_score）は、純粋なオフライン分析に使用するレコードを注入できます。endpoint_health_score と patch_compliance は注入データのみを使用し、その他のツールは設定済みのターゲットからライブデータを取得することもできます。

このツールが判断することと、判断しないこと

このツールは、管理対象エンドポイントの操作（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。ただし、書き込みを許可するかどうかは判断しません。それはエージェントの判断、または接続するアカウントの権限に委ねられます。読み取り専用ロールに限定した管理コンソールのアカウントまたは API トークンを与えれば、書き込みは権限を実際に管理しているサーバーで失敗します。

そのため、読み取り専用スイッチも、ポリシーファイルも、設定が必要な承認ゲートもありません。このツールが保証するのは、何も見えないところで実行されないことだけです。MCP 経由でも CLI 経由でも、すべての呼び出しが ~/.endpoint-aiops/audit.db に監査行として記録されます。元に戻せる書き込みについても、実行前の状態を取得し、可能な場合は逆操作を記録します。

各ツールは risk_level を宣言します。テストによって [READ]／[WRITE] のドキュメント上のタグと一致するよう保たれ、説明用のリスク段階として監査行に記録されます。そのため、確認者は高リスクの書き込みだったことをすぐに把握できます。これはラベルであり、ゲートではありません。

小規模モデルやローカルモデルを実行していますか？agent-guardrails.md をご覧ください。このツールが代わりに適用するガードレール（そのため、プロンプトの予算を使って繰り返し指示する必要がありません）と、残りの項目に使えるすぐに利用可能なシステムプロンプトが記載されています。

ペイロードの規約

• 存在しないことは、空であることとは異なります。 管理サーバーから報告されなかったフィールドは "" ではなく null で返されます。キーは常に存在するため、パッチレベルが欠落していても空欄と誤認されません。
• 上限のあるリストは、そのことを明示します。 limit によって途中で切り詰められる可能性のあるリストは、切り詰め情報を含むエンベロープとして返されます：{"items": [...], "returned": N, "limit": L, "truncated": bool}。truncated は推測ではなく、実際に測定した値です。関連する合計値（driftedCount、behindCount、nonCompliantCount、stormCount、health の summary）は、常に上限による切り詰めのない全件数です。

クイックスタート

Claude Code プラグインとして

一度インストールするだけで、エージェントにスキルと MCP サーバーの両方が提供されます：

/plugin marketplace add AIops-tools/marketplace
/plugin install endpoint-aiops@aiops-tools

MCP サーバーは uv で取得され、このプラグインが宣言するパッケージバージョンに固定されます。そのため、監査行からそれを書き込んだコードをたどれます。認証情報は引き続き endpoint-aiops init で設定します。以下をご覧ください。

OpenClaw プラグインとして

同じバンドルが ClawHub で公開されており、一度インストールするだけでスキルと MCP サーバーがまとめて提供されます：

openclaw plugins install clawhub:@zw008/endpoint-aiops
openclaw skills info endpoint-aiops          # expect: Visible to model: yes

その後、プラグインを読み込ませるために OpenClaw ゲートウェイを再起動してください。MCP サーバーは uv で取得され、この正確なリリースに固定されています。そのため、uvx が PATH に含まれている必要があります。含まれていなくてもスキルはインストールされますが、Visible to model: no と報告されます。認証情報は以下と同じ方法で設定します。

CLI またはスタンドアロン MCP サーバーとして

uv tool install endpoint-aiops          # or: pipx install endpoint-aiops
endpoint-aiops init                     # wizard: add a target + store its API key (encrypted)
endpoint-aiops doctor                   # verify config, secrets, connectivity
endpoint-aiops overview                 # one-shot fleet health
endpoint-aiops session storm            # detect a login storm + slow contributors
endpoint-aiops drift report             # endpoints drifted from the fleet baseline

MCP サーバーとして実行する場合（stdio）：

export ENDPOINT_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
endpoint-aiops-mcp

そのパスワードの保存場所について：エクスポートした変数は、このシェルが起動するすべてのプロセスから読み取り可能であり、シェルの履歴にも記録されます。共有ホストや長時間稼働するホストでは、対話型プロンプトを使用するか、必要な一度のコマンドの実行中だけ、シークレットマネージャーから注入することをおすすめします。

ガバナンス

すべての操作（MCP と CLI の両方）は、同梱の @governed_tool ハーネスを通過します。記録は行いますが、認可は行いません（上記を参照）。

• 監査 — すべての呼び出し（パラメーター、結果、ステータス、所要時間、リスク階層、オペレーターが指定した承認者／理由があればその内容）は、~/.endpoint-aiops/audit.db に記録されます（ENDPOINT_AIOPS_HOME で保存場所を変更できます）。CLI は MCP の経路と同じ行を書き込むため、監査を経由しないエントリーポイントはありません。
• 暴走防止ガード — 認可ゲートではなく、安全性を確保するための最後の手段です。同じ呼び出しが短時間に繰り返されると、サーキットブレーカーが作動し、停止したエージェントが無制限に呼び出しを行ったり、時間を費やしたりするのを防ぎます。ENDPOINT_RUNAWAY_MAX=0 で無効にできます。オプションで、ENDPOINT_MAX_TOOL_CALLS／ENDPOINT_MAX_TOOL_SECONDS による上限も設定できます。
• 取り消し記録 — 元に戻せる書き込みでは、取得した変更前の状態から作成した逆操作の記述子を記録します。
• リスク階層 — risk_level から算出され、監査行に記録される説明用のラベルです。何も制限しません。

対象範囲

これは AIops-tools ファミリー（監査＋予算＋取り消し＋リスク階層を備えたガバナンス付き AI 運用）のIT エンドポイント向けメンバーです。OT／産業用エッジ （Modbus、OPC-UA、PROFINET、…）については、別の industrial-aiops 系統を参照してください。

ダイアレクト — 実際にどのサーバーを指定していますか？

ダイアレクトとは、管理サーバーの API の形式です。リソースパス、レスポンスのフィールド名、トランスポートのデフォルト値（ポート＋API ベースパス）、および認証方法が含まれます。config.yaml でターゲットごとに設定します。endpoint-aiops init を実行すると、ダイアレクトを尋ねられ、設定したものが表示されます。

ダイアレクト	トランスポート	認証	ステータス
generic（デフォルト）	443 の /api/v2.0	静的 Bearer API キー	中立的なプレースホルダー — 実在するベンダー API ではありません。 dialect: ブロックでサーバーのパスを記述した場合にのみ役立ちます。
igel-ums	8443 の /umsapi/v3	HTTP Basic ログイン → JSESSIONID Cookie	IGEL UMS（IMI）向けの、文書化済みですが未検証のダイアレクトです。IGEL がサポート対象であるという主張ではありません — ステータスを参照してください。

targets:
  - name: ums1
    host: ums.example.local
    dialect: igel-ums        # IMI paths, port 8443, /umsapi/v3, Basic-login auth
    username: ums-admin      # UMS account; the password lives in secrets.enc
    scheme: https            # or 'http' for a reverse-proxied server
    verify_ssl: false        # self-signed lab UMS only

デフォルトの generic は IGEL 用の設定ではなく、これまでもそうではありませんでした。IGEL は IMI を 8443 の /umsapi/v3 で提供しているため、generic の形式のままのターゲットは、最初のプローブで 404 を返します。この不一致が、プリセットを用意した理由です。

サーバーにそのようなリソースが実際に存在しない場合、ダイアレクトは URL を推測せず、その旨を示します。IMI はログイン／ブートセッションのリソースを公開していないため、igel-ums ターゲットでの session_list と login_storm_analysis は、作り上げたパスを呼び出す代わりに、存在しないリソースの名前を示す説明用エラーを返します。

ダイアレクトが選択するのはパスだけでなく、認証方式もです。IMI は generic ダイアレクトが送信する静的 Bearer トークンを拒否するため、POST /umsapi/v3/login に HTTP Basic でログインし、返された JSESSIONID Cookie を使用します（接続ごとに 1 回ログインし、その後はキャッシュします）。認証方式はダイアレクトに基づくため、認証情報の失敗とダイアレクトの誤りによる失敗は、別々に報告されます。401 の場合は、提示した認証方式と、サーバーから WWW-Authenticate チャレンジが返されていればサーバーが実際に要求している認証方式が示されるため、ダイアレクトの不一致を理由に、問題のないキーをわざわざローテーションする必要はありません。

⚠️ IGEL 固有の注意：権限が不足している UMS アカウントでは、403 ではなく空のリストが返されます。endpoint-aiops doctor は到達可能性のプローブとは別のステップで認証を行い、ログインに成功してもエンドポイントが返されない場合は警告します。これは、「デバイスがない」状態と「デバイスを参照する権限がない」状態を、それ以外の方法では区別できないためです。

状態

テストスイートはモックベースです。このパッケージのどの方言も実際の管理サーバーに対して検証されていません。そのため、IGEL を含む特定の製品への対応は保証していません。

• generic はプレースホルダーの形式であり、ベンダー API ではありません。
• igel-ums は文書化されているものの、未検証の方言です。パスとフィールドの別名は、IGEL が公開している IMI ドキュメントに基づいてモデル化されています。認証方式は IMI マニュアルに記載されており、実環境で使われている独立した 3 つの IMI クライアントの方式とも一致します。いずれも、このプロジェクトではアプライアンスに対して実行されていません。IGEL UMS には無料版がないため、メンテナーのハードウェアでは検証できません。

どちらも docs/VERIFICATION.md に UNKNOWN-pending-live として記録されています。同ファイルでは、実環境での実行で誤りが見つかる可能性が最も高い項目を順位付けし、確認すべきチェックリストを定義しています。UMS をお持ちで、このチェックリストを実行していただける場合は、結果を Issue でお知らせいただけると幸いです。未実装の機能やサーバー方言があれば、Issue または PR を作成してください。貢献を歓迎します。