Proxy AIops

Proxy AIops

Traefik、Caddy、HAProxyのリバースプロキシ／ロードバランサー向けの、ガバナンスと監査を備えた AI オペレーションです。MCP 経由で AI エージェントが、CLI 経由で人間が利用できます。

免責事項：コミュニティが保守するオープンソースプロジェクトです。Traefik Labs、Caddy プロジェクト、HAProxy Technologies、または HAProxy プロジェクトとは提携、承認、スポンサー関係にありません。 Traefik、Caddy、HAProxy は、それぞれの所有者の商標です。MIT ライセンスで提供されています。

proxy-aiops は、1 つの MCP サーバーを通じて 3 つのプロキシプラットフォームと通信します。Traefik（/api/... 配下の API、/metrics 経由のメトリクステキストカウンター）、Caddy（管理 API、デフォルトは localhost:2019）、HAProxy（/v2/... 配下の Data Plane API v2、HTTP Basic 認証）に対して、同じツールをすべて利用できます。設定内の各ターゲットにはそれぞれの platform を指定します。名前をキーとするプラットフォームレジストリが API の形式（認証とリソースパス）を選択し、明示的なサポートマトリックスによって、あるプラットフォームでは本当に実行できない操作について説明付きのエラーを返します。たとえば、Traefik への書き込みでは、そのプロバイダー（ファイル、コンテナーラベル、オーケストレーターの CRD）が案内され、何も行わずに成功したように見えることはありません。

すべてのツールは、組み込みのガバナンスハーネス（ベンダー同梱、外部依存関係なし）を通じて実行されます。監査ログ、トークン／呼び出し予算と暴走時のサーキットブレーカー、詳細なリスクレベルのラベル付け、元に戻すためのトークン記録、出力のサニタイズを備えています。

このツールが存在する理由

• 1 つのサーバーで 3 つのプロキシに対応 — 混在するエッジ環境の Traefik、Caddy、HAProxy に、同一のツール名でアクセスできます。後から別のプロキシを追加する場合も、書き直しではなく新しいプラットフォーム記述子を追加するだけです。
• エッジ全体を読み取る — バージョン、エントリーポイント／リスナー、ルート（ルーター／Caddy ルート／フロントエンド。ホストとパスを解析）、サービスとサーバーレベルのアップストリームの健全性、ミドルウェア、TLS ドメインの一覧、トラフィック／エラーカウンター、ライブ設定ツリー（スナップショットと検索）を確認できます。
• 主要な RCA 分析 — 数値を示す透明性の高いヒューリスティックで、ブラックボックスの判定は行いません。backend_health_rca（停止中のアップストリーム → 原因クラス L4/L6/L7/DNS/メンテナンスと対処）、cert_expiry_sweep（有効期限までの日数の分類と、プラットフォーム別の更新に関するヒント）、error_rate_rca（5xx の割合とフリートのベースラインを比較し、主なコードから 502/503/504/500 の原因を特定）、route_conflict_analysis（優先されて隠れるルート、デッドルート、リダイレクトループ）。
• ガバナンスを備えた書き込み — Caddy 設定の set／delete／全体の load（記録された元に戻す操作で実際に復元できるよう、先に以前のサブツリー／設定を取得します）と、HAProxy ランタイムのサーバー state（ready/drain/maint）および weight（元に戻す操作で以前の値を復元します）。すべてに dry_run のプレビューがあり、delete/load は risk=high で、CLI では二重確認が必要です。

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

このツールはプロキシ操作（読み取りと書き込み）を正確かつ効率的に実行し、そのすべてを記録します。書き込みを実行してよいかどうかは判断しません。それはエージェントの判断、または接続先アカウントの権限によります。HAProxy Data Plane API に読み取り専用のロールを付与するか、接続先の Traefik／Caddy 管理 API の権限範囲を絞れば、書き込みは権限を実際に管理する場所であるサーバー側で失敗します。

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

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

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

ツール一覧（28 個）

ドメイン	ツール	数	種類
ステータス	proxy_overview, version_info, list_entrypoints	3	読み取り
ルート	list_routes, route_detail, find_route	3	読み取り
サービス	list_services, service_detail, list_upstreams, upstream_detail, list_middlewares	5	読み取り
証明書	list_certificates	1	読み取り
トラフィック	traffic_stats, error_counters	2	読み取り
設定	config_snapshot, search_config, get_config_value	3	読み取り
主要な分析	backend_health_rca, cert_expiry_sweep, error_rate_rca, route_conflict_analysis	4	読み取り
書き込み（caddy）	set_config_value	1	書き込み（中）
書き込み（caddy）	delete_config_path, load_config	2	書き込み（高）
書き込み（haproxy）	set_server_state, set_server_weight	2	書き込み（中）
取り消し	undo_list, undo_apply	2	読み取り／書き込み

元に戻せる書き込みでは、実際に取得した変更前の状態に基づいて逆操作用の undo descriptor を記録します（set_config_value は以前のサブツリーを復元し、delete_config_path はそれを再作成し、load_config はスナップショットを取得した設定を再読み込みし、サーバーの状態／重みは以前の値に戻します）。undo パラメーターは各ツール独自のシグネチャに一致するため、ディスクリプターをそのまま再実行できます。

プラットフォーム別サポートマトリックス

機能	traefik	caddy	haproxy
ルート／サービス／アップストリームのヘルス状態	✅	✅	✅
ミドルウェア一覧	✅	教育用の注記（インラインハンドラー）	教育用の注記（haproxy.cfg）
TLS 証明書一覧＋有効期限の一括確認	✅	✅	教育用の注記（.pem ファイル）
エラーカウンター／エラー率の根本原因分析	✅（/metrics）	教育用の注記（ルートごとのカウンターなし）	✅（stats）
設定のスナップショット／検索	✅（rawdata、読み取り専用）	✅	教育用の注記
設定の書き込み	教育用エラー → プロバイダーを編集	✅（書き込み対象）	教育用エラー → ランタイム書き込み
実行時のサーバー状態／重み	教育用エラー → プロバイダー	教育用エラー → 設定ツリー	✅

サポートされていない組み合わせでは、代わりに何を使うべきかを示す教育用エラーが発生します。何も通知せずに空の結果を返すことはありません。

インストール

uv tool install proxy-aiops        # or: pipx install proxy-aiops

クイックスタート

Claude Code プラグインとして

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

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

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

OpenClaw プラグインとして

同じバンドルが ClawHub で公開されており、1 回のインストールでスキルと MCP サーバーをまとめて導入できます。

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

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

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

proxy-aiops init                     # wizard: pick platform (traefik/caddy/haproxy) + optional encrypted secret
proxy-aiops doctor                   # verify config, secrets, and connectivity
proxy-aiops overview                 # one-shot: version + route/service counts + upstream health
proxy-aiops routes list              # normalised route table
proxy-aiops services upstreams       # server-level upstream health
proxy-aiops analyze health           # backend/upstream health RCA
proxy-aiops analyze errors           # 5xx error-rate RCA
proxy-aiops analyze conflicts        # shadowed/dead routes, redirect loops
proxy-aiops certs --sweep            # TLS cert expiry sweep (traefik/caddy)
proxy-aiops server state app web1 drain --dry-run   # governed haproxy write preview
proxy-aiops config set apps/http/servers/srv0 '{"listen":[":8080"]}' --dry-run

エージェント用に MCP サーバー（stdio）を実行します。

proxy-aiops mcp                      # or: proxy-aiops-mcp

MCP クライアントの設定

{
  "mcpServers": {
    "proxy-aiops": {
      "command": "uvx",
      "args": ["--from", "proxy-aiops", "proxy-aiops-mcp"],
      "env": { "PROXY_AIOPS_MASTER_PASSWORD": "your-master-password" }
    }
  }
}

環境変数ブロックに関する注意：env ブロックが必要なのは、認証情報が保存されている場合のみです（haproxy では常に必要です。traefik／caddy では Basic 認証の背後にある場合のみ必要です）。MCP クライアントはシェルのプロファイルを継承しません。クライアントの設定で PROXY_AIOPS_MASTER_PASSWORD（および保存場所を変更した場合は PROXY_AIOPS_CONFIG／PROXY_AIOPS_HOME）を明示的に設定しないと、サーバーは secrets.enc のロックを解除できません。

設定

~/.proxy-aiops/config.yaml（シークレット以外の接続情報のみ）：

targets:
  - name: edge1
    platform: traefik        # traefik | caddy | haproxy
    base_url: http://192.0.2.10:8080
    verify_ssl: true
  - name: caddy1
    platform: caddy
    base_url: http://127.0.0.1:2019
  - name: lb1
    platform: haproxy
    base_url: http://192.0.2.20:5555
    username: dpapi          # Data Plane API user

シークレット（HAProxy Data Plane API のパスワード、または Traefik／Caddy の前段に任意で設定する Basic 認証のパスワード）は、~/.proxy-aiops/secrets.enc に暗号化して保存されます（Fernet ＋ scrypt で導出したキーを使用）。ディスク上に平文で保存されることはありません。Traefik と Caddy は localhost で認証なしで動作することが多いため、シークレットは任意です（ローカルソケットと同様です）。HAProxy のシークレットは必須です。proxy-aiops secret set <target> または init ウィザードで設定してください。ストアのロック解除には、PROXY_AIOPS_MASTER_PASSWORD（非対話／MCP／CI の場合）で指定したマスターパスワード、または対話型プロンプト（TTY 上の CLI の場合）を使用します。従来の平文環境変数 PROXY_<TARGET>_SECRET はフォールバックとして引き続き使用できます（proxy-aiops secret migrate で移行してください）。

ガバナンス

すべての MCP ツールと、同じガバナンス対象の関数を経由するすべての CLI 書き込みは、@governed_tool を通過します。これは記録を行うものであり、認可は行いません（上記を参照）。

• 監査 — すべての呼び出しが ~/.proxy-aiops/audit.db に記録されます（ツール、シークレットを秘匿したパラメーター、ステータス、所要時間、リスク階層、オペレーターが指定した承認者／理由）。CLI は MCP 経由の場合と同じ行を書き込むため、監査されない入口はありません。
• 予算／暴走防止 — 認可ゲートではなく、安全のための最後の砦です。プロセスごとのトークン／呼び出し上限と、同じ呼び出しの繰り返しを検知するサーキットブレーカーにより、停止したエージェントが無制限に呼び出しや時間を消費するのを防ぎます（PROXY_MAX_TOOL_CALLS、PROXY_RUNAWAY_MAX など。PROXY_RUNAWAY_MAX=0 でブレーカーを無効化できます）。
• 取り消しの記録 — 元に戻せる書き込みでは、取得した変更前の状態から逆操作の記述子を ~/.proxy-aiops/undo.db に記録します（記録のみで、実行は外部オーケストレーターが行います）。取り消しパラメーターは対象ツール自体のシグネチャと一致するため、記述子はそのまま再実行できます。
• リスク階層 — risk_level から導出される、監査行に付与される説明用のラベルです。何も制御しません。
• サニタイズ — プロキシから返されるテキストはすべて、エージェントに渡される前に長さを制限し、制御文字をサニタイズします。

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

• プラットフォーム：Traefik（API ＋ /metrics）、Caddy（管理 API）、HAProxy（Data Plane API v2）。
• テストカバレッジ：動作はモックした JSON／メトリクスのレスポンスに対して検証されています。すべてのモジュールがインポートできること、すべての MCP ツールにガバナンスマーカーが付いていること、主要な 4 つの分析が合成テレメトリに対してユニットテストされていること、サポートマトリックスが何も行わずに終了するのではなく説明付きのエラーを発生させること、元に戻せる書き込みが正しい逆操作の取り消し記述子を記録することを確認しています。具体的な REST パスは各プロジェクトの公開 API に基づいてモデル化されていますが、実際のプロキシに対するテストはまだ行われていません。実環境での実行時に満たすべきチェックリストについては、docs/VERIFICATION.md を参照してください。3 つのプラットフォームはいずれも無料でセルフホスト可能です（traefik、caddy、haproxy/dataplaneapi を使った小規模なコンテナー構成のラボ環境は、半日ほどでセットアップできます）。各プラットフォームの健全性／情報を確認する proxy-aiops doctor が、実環境で最も手軽に確認する方法です。
• ルーティングに関する注意：このツールはリバースプロキシ／ロードバランサーを操作します。ファイアウォールルールには使用しないでください。firewall-aiops を使用してください。
• 必要な機能がありませんか？ github.com/AIops-tools/Proxy-AIops で issue または PR を作成してください。貢献やフィードバックを歓迎します。

ライセンス

MIT — LICENSE を参照してください。