Fabric AIops

Fabric AIops

免責事項：コミュニティが保守するオープンソースプロジェクトです。Cisco、Meraki、Arista、Ubiquiti、またはいずれのネットワークコントローラーベンダーとも、提携、承認、後援の関係にありません。「Cisco」、「Meraki」、「Catalyst」、「DNA Center」、「Arista」、「CloudVision」、「Ubiquiti」、「UniFi」、「ACI」、「APIC」、およびすべての製品名・商標名は、それぞれの所有者に帰属します。MIT ライセンスです。

コントローラーを介して管理されるネットワークファブリック向けの、ガバナンスを備えた AI 運用です。対象は、Cisco Meraki Dashboard API（基準プラットフォーム、読み取り・書き込みを完全サポート）、Cisco Catalyst Center（旧称 DNA Center、読み取りの一部をサポート）、Arista CloudVision Portal（CVP）（読み取りの一部をサポート）、UniFi Network（セルフホスト型コントローラーまたは UniFi OS コンソール、読み取りの一部とデバイス再起動をサポート）、さらに読み取り専用の**Cisco ACI（APIC）**エンドポイントパスの再構築と障害です。これらには、組み込みのガバナンスハーネス（統合監査ログ、トークン／暴走予算ガード、取り消しトークンの記録、説明的なリスク階層）が備わっています。設計上、複数のプラットフォームに対応しています。platform をキーとするレジストリが、各正規操作を各コントローラーの REST API（パステンプレートとレスポンスアダプター）にマッピングするため、コントローラーの追加はレジストリエントリの追加だけで済み、新しい ops／CLI／MCP のインターフェイスは不要です。プラットフォームが操作に対応していない場合は、明確な説明エラー（「X はまだ未対応です。課題を報告してください」）を返し、何もせずに成功したように見せることはありません。このツールを使って実際のコントローラーで動作確認されたプラットフォームはまだありません。ACI の読み取りだけは、実際のコントローラーレスポンス（本番ユーザーから提供された匿名化済み APIC ペイロード）を基に構築されています。詳しくは docs/VERIFICATION.md をご覧ください。

できること

3 つの主要な特徴的分析に加え、それらを支えるガード付きの読み取りと書き込みを提供します。

• アップリンクのパケット損失と遅延の根本原因分析（RCA） — 組織全体の MX WAN アップリンクのパケット損失と遅延を取得し、平均パケット損失と遅延を合成した指標で問題の大きいアップリンクを順位付けし、性能が低下した各アップリンクについて、考えられる原因と推奨アクションを示します。順位にはすべて数値が添えられ、ブラックボックスの判定にはなりません。
• ネットワーク健全性スコア — デバイスのオンライン率、アップリンクの健全性、アラートの重大度に応じたペナルティ（重み 0.5／0.3／0.2）から、ネットワークごとに 0～100 の複合スコアを算出します。各構成要素もすべて返すため、スコアの根拠がわかります。
• 設定テンプレートのドリフト — 設定テンプレートに関連付けられたネットワークについて、テンプレートから逸脱した設定を一覧表示します（期待値と実際の値）。

対応機能

• CLI（fabric-aiops ...）：init、overview、org、network、device、client、health、aci、remediate、secret、doctor、mcp。
• MCP サーバー（fabric-aiops mcp または fabric-aiops-mcp）：37 個のツール（読み取り 28 個、書き込み 9 個）。すべてに同梱の @governed_tool ハーネスが適用されています。
• 暗号化された認証情報：コントローラーのシークレット（Meraki API キー／Catalyst Center または APIC の username:password／CVP サービスアカウントトークン／UniFi API キー）は、暗号化ストア ~/.fabric-aiops/secrets.enc（Fernet + scrypt）に保存され、ディスク上に平文で保存されることはありません。マスターパスワードは FABRIC_AIOPS_MASTER_PASSWORD（MCP／CI）で設定するか、対話形式のプロンプト（CLI）で入力してロックを解除します。
• 可逆性：変更を伴う書き込み操作では、実際の変更前の状態を最初に取得し、それに忠実な逆操作を記録します（update_device／update_network_vlan は以前の値を復元し、claim と remove は相互に対応し、bind は unbind／再バインドに対応します）。取り消しできない操作（reboot_device、blink_device_leds）では、監査用に以前の状態を記録しますが、取り消し操作は宣言しません。
• 安全性：状態を変更するすべての CLI 操作は --dry-run に対応し、二重確認が必要です。書き込みを行うすべての MCP ツールには、dry_run によるプレビュー機能があります。

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

ドメイン	ツール	数	R/W
概要	overview	1	読み取り
組織	org_list、org_get、org_licensing、org_admins、org_device_statuses、org_api_requests	6	読み取り
ネットワーク	network_list、network_get、network_vlans、network_alerts、network_traffic	5	読み取り
デバイス	device_inventory、device_status、device_uplinks、switch_ports、wireless_ssids	5	読み取り
クライアント	client_list、client_get、client_usage、client_connectivity	4	読み取り
健全性（主力機能）	uplink_loss_and_latency_rca、network_health_score、config_template_drift	3	読み取り
Cisco ACI（APIC のみ）	aci_endpoint_trace、aci_epg_segment、aci_faults_list	3	読み取り
修復	reboot_device、claim_devices_into_network、remove_device_from_network、bind_network_to_template、unbind_network_from_template	5	書き込み（高）
	update_device、update_network_vlan	2	書き込み（中）
	blink_device_leds	1	書き込み（低）
取り消し	undo_list	1	読み取り
	undo_apply	1	書き込み（中）

network_health_score と config_template_drift は注入データ専用です（すでに保持しているデータを評価します）。uplink_loss_and_latency_rca はオフライン分析用の注入された records を受け取るか、設定済みのターゲットからライブデータを取得します。デバイスモデルには製品タイプのプレフィックスが付いています。MX はアプライアンス、MS はスイッチ、MR はワイヤレス AP、MV はカメラ、MG はセルラーゲートウェイです。

プラットフォームのサポート状況

1つのツールで、5つのコントローラープラットフォームに対応します。以下の表に示す4つのプラットフォームでは、ops／CLI／MCP のインターフェースはどこでも同一です。各プラットフォームでは、対応する標準操作をマッピングし、それ以外の操作には説明エラー（「<platform> ではまだサポートされていません。issue または PR をお寄せください」）を返します。ACI はこれらの操作を一切マッピングしません。詳しくは以下の Cisco ACI をご覧ください。

標準操作	meraki	catalyst	cvp	unifi
overview（組織／サイト／コンテナーの概要）	✅	✅	✅	✅
org_list / org_get	✅	✅ sites	✅ containers	✅ sites（一覧。get は ❌）
org_licensing、org_api_requests	✅	❌	❌	❌
org_admins	✅	❌	✅ users	❌
org_device_statuses	✅	✅ device-health	✅ inventory + streaming status	✅ stat/device（状態、稼働時間、ファームウェア）
network_list / network_get	✅	✅ site-health / site	✅ containers	✅ sites / stat/health（サブシステムの概要）
network_vlans、network_traffic	✅	❌	❌	❌
network_alerts	✅	✅ issues（P1→critical、P2→warning）	✅ events	✅ alarms（*_Lost_Contact→critical）
device_inventory、device_status	✅	✅ network-device	✅ inventory（+ complianceCode のドリフトシグナル）	✅ stat/device（id = デバイスの MAC）
device_uplinks	✅	❌	❌	❌
switch_ports	✅	✅ interface stats（デバイスの uuid を渡します）	❌	✅ device port_table（デバイスの MAC を渡します）
wireless_ssids	✅	❌	❌	❌
client_list / client_get	✅	✅ client-health（集計） / client-detail（MAC アドレス指定）	❌	✅ stat/sta（接続中） / stat/user（MAC アドレス指定）
client_usage、client_connectivity	✅	❌	❌	❌
uplink_loss_and_latency_rca（ライブ取得）	✅	❌（注入した records は引き続き使用可能）	❌（注入した records は引き続き使用可能）	❌（注入した records は引き続き使用可能）
network_health_score、config_template_drift（注入データのみ）	✅	✅	✅	✅
reboot_device	✅	❌ 説明エラー	❌ 説明エラー	✅ cmd/devmgr restart-device
その他の7つの書き込み操作（点滅／更新／登録／削除／バインド／バインド解除／VLAN）	✅	❌ 説明エラー	❌ 説明エラー	❌ 説明エラー

概念のマッピング：標準の organizations/networks は、Catalyst Center の sites、CVP の containers、UniFi の sites に対応します（標準 ID はサイトの短縮名、つまり /api/s/{site}/ のパスセグメントです）。いずれもグローバルツリーが1つだけのため、org スコープで一覧が絞り込まれることはありません。unifi では、デバイススコープの呼び出し（device get / switch_ports / reboot）時に、対象のデフォルトの org_id からサイトが補完されます。config.yaml（または初期化ウィザード）で設定してください。書き込み操作は UniFi のデバイス再起動を除き Meraki のみです。Catalyst Center と CVP の変更モデル（task/configlet ワークフロー）は、これらの標準書き込み操作に適切に対応付けられないため、各書き込み操作はコントローラーを呼び出す前に、すぐに説明エラーを返します（何も行わずに成功することはありません）。CVP の設定ドリフトは device_inventory（デバイスごとの complianceCode／complianceIndication）と network_alerts（events）で確認できます。configlet の内容取得、および catalyst／cvp／unifi での深いページネーションは、既知の未対応項目です。

Cisco ACI（APIC）

ACI には、テナント → VRF → ブリッジドメイン → EPG と、ポッド → ノード → インターフェースという 2 つの軸があります。どちらも組織 → ネットワーク → デバイスというツリーではありません。呼び出しごとに network_id の意味を変えるのではなく、 aci ターゲットは標準ツールに説明用エラーを返し、ACI 固有の参照（MAC/IP、テナント／アプリ／EPG 名、DN）を受け取る 読み取り専用 の ACI ネイティブツールを 3 つ提供します。

ツール（CLI）	確認できる内容
aci_endpoint_trace（aci trace --mac/--ip）	このエンドポイントはどこにあり、何がこれを運んでいるか：接続先（ポッド／リーフ／インターフェースまたは vPC）→ EPG → ブリッジドメイン → VRF → EPG のコントラクト → フィルターエントリー、および DN に EPG または接続先インターフェースの名前が含まれる障害
aci_epg_segment（aci segment TENANT APP EPG）	EPG 名から確認する、同じ EPG → BD → VRF → コントラクトの経路
aci_faults_list（aci faults）	ファブリックの障害。重大度の高い順

読み取り方：

• 到達性テストではなく、静的な再構成です。 staticPathResolved: true は、ファブリックがエンドポイントを運ぶように設定されていることを示すもので、トラフィックが流れていることを意味するものではありません。APIC への書き込みは行われず、トラブルシューティングセッションも作成されません。
• リンクは APIC が解決した関係（tDn）をたどるため、common へのテナント間リンクもたどります。formed でない関係は、その状態とともに検出事項として示されます。
• 関連する障害は候補です。 DN（EPG、接続先インターフェース、リーフにデプロイされた EPG ポリシーのコピー）で照合されます。近接性を示すものであり、原因を示すものではありません。
• 障害行はインシデントではなくレコードです。delegated レコードは、別のオブジェクトにある障害を反映します。クリア済みの障害には、発生時の説明が保持されます。
• 未評価（すべての結果で notChecked に一覧表示）：vzAny コントラクト、タブーコントラクト、インポートされたコントラクトインターフェース、優先グループのピア、サービスグラフ／L3Out。

リーフ／スパインのインベントリーとインターフェースの状態（fabricNode、topSystem、l1PhysIf）は今回のリリースには含まれていません。上記のクラスで実際の応答が利用可能になった時点で実装されます。

プラットフォームごとの認証

プラットフォーム	platform:	保存されるシークレット（暗号化済み）	通信時の認証	ベース URL
Cisco Meraki Dashboard	meraki	API キー（Dashboard → Organization → Settings → API access）	Authorization: Bearer（または auth_style: meraki-key → X-Cisco-Meraki-API-Key）	デフォルトは https://api.meraki.com/api/v1
Cisco Catalyst Center	catalyst	username:password（1 つの文字列）	POST /dna/system/api/v1/auth/token（HTTP Basic）で約 1 時間有効な X-Auth-Token と交換し、401 時に 1 回自動更新	必須。例：https://<catalyst-center-host>
Arista CloudVision Portal	cvp	サービスアカウントトークン（Settings → Access Control → Service Accounts）	Authorization: Bearer	必須。例：https://<cvp-host>
Cisco ACI（APIC）	aci	username:password（1 つの文字列。読み取り専用ロールで十分です。ACI の読み取りはすべて GET で、ログインのみ POST です）	POST /api/aaaLogin.json でセッションを開始し、Cookie で引き継ぎます。有効期間の半分が経過した時点で /api/aaaRefresh.json により延長します。401/403 時には新たに 1 回ログインします（APIC は期限切れのセッションを 403 で報告します）	必須。例：https://<apic-host>
UniFi Network	unifi	API キー（UniFi OS：Settings → Control Plane → Integrations。セルフホストの Network Server 9.0 以降）	X-API-KEY（ステートレス。従来の Cookie ログインは既知の先送り事項です）	必須。従来型のコントローラーは https://<host>:8443、UniFi OS コンソールは https://<console>/proxy/network（プレフィックスを維持してください）

fabric-aiops init はプラットフォームの選択手順を案内し、適切な種類のシークレットを保存します。fabric-aiops doctor は各ターゲットに対して階層の最上位を読み取る標準的なチェック（組織／サイト／コンテナー／UniFi サイト、APIC ではテナント数）を実行し、認証フロー全体を検証します。

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

ネットワークファブリックの操作（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。書き込みを実行してよいかどうかは判断しません。それはエージェントの判断、または接続するアカウントの権限によります。管理者に組織の読み取り専用アクセス権がある Meraki API キー（またはコントローラーで同等の読み取り専用権限）を設定すると、書き込みはコントローラー、つまり実際に権限を管理する場所で失敗します。

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

各ツールは risk_level を宣言します。テストによって [READ]／[WRITE] のドキュメントタグとの一致が保たれ、説明用の階層として監査行にも記録されます。これにより、レビュー担当者は行が高リスクの削除だったことをひと目で確認できます。これはラベルであり、ゲートではありません。

クイックスタート

Claude Code プラグインとして

インストールすると、エージェントにスキルと MCP サーバーの両方が提供されます。

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

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

OpenClaw プラグインとして

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

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

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

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

uv tool install fabric-aiops              # or: pipx install fabric-aiops
fabric-aiops init                         # wizard: choose platform (meraki/catalyst/cvp/unifi) + store the secret (encrypted)
fabric-aiops doctor                       # verify config, secrets, connectivity (per-platform auth probe)
fabric-aiops overview                     # one-shot fabric fleet health
fabric-aiops health uplink-rca            # rank worst MX WAN uplinks + cause/action (meraki)
fabric-aiops device inventory --model MS  # switches in the org

MCP サーバーとして実行します（stdio）。

export FABRIC_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
fabric-aiops-mcp

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

ガバナンス

すべての操作（MCP および CLI）は、同梱の @governed_tool ハーネスを通過します。記録はしますが、許可はしません（上記を参照）。

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

対象範囲

これは AIops-tools ファミリー（監査＋予算＋取り消し＋リスク階層を備えた、ガバナンス対象の AI 運用）のネットワークファブリック／コントローラー向けメンバーです。OT／産業用エッジ（Modbus、OPC-UA、PROFINET）には使用しないでください。その用途には別の industrial-aiops 系統を使用してください。また、デバイスレベルの CLI／SSH ネットワーク自動化にも使用しないでください。

不足している機能はありますか？

各コントローラーの API は、意図的に厳選した一部のみを対象としています。Meraki の呼び出しやデバイスファミリーが不足していますか？ Catalyst Center、CloudVision Portal、または UniFi Network で必要な項目がサポートマトリクスに ❌ と表示されていますか（書き込みも対象です。たとえば、9.0 より前のコントローラーで使う UniFi の Cookie ログインフォールバックなど）。あるいは、別のコントローラープラットフォームが必要ですか？ イシューまたは PR を作成してください。貢献を歓迎します（プラットフォームは、パスのテンプレートとレスポンスアダプターからなる単一の記述子モジュールです）。

ステータス

このツールを使用して、稼働中の Meraki 組織、Catalyst Center アプライアンス、CloudVision Portal インスタンス、UniFi コントローラー、または APIC に対して動作確認を行ったプラットフォームはまだありません。最初の 4 つのプラットフォームの API パスは、公開 API の仕様に基づいてモデル化し、モックに対してテスト済みです。ACI の読み取り処理は、本番ファブリックから取得した実際の匿名化済み APIC レスポンス（エンドポイント、EPG、ブリッジドメイン、VRF、コントラクト、フィルターエントリー、障害）を使ってテスト済みであり、クエリの仕組みも Cisco 独自の SDK を使ってテスト済みです。ただし、このツールを APIC に対して実行するライブテストはまだ行われていません。docs/VERIFICATION.md では、ライブテストで確認する必要がある項目を定めています。最も手早くライブ環境を確認するには、fabric-aiops doctor を実行してください。