VMware Debug

VMware Debug

免責事項：コミュニティが保守するオープンソースプロジェクトであり、VMware, Inc. または Broadcom Inc. とは提携、推奨、後援のいずれも受けていません。「VMware」と「vSphere」は Broadcom の商標です。ソースコードは MIT ライセンスのもとで公開され、誰でも監査できます。

VMware スキルファミリーの診断ブレインです。症状（エラー、ログダンプ、VM の動作が遅いなど）を入力すると、このスキルが体系的な調査を行い、他のスキルからのイベントをひとつのタイムラインに関連付け、根本原因の仮説を順位付けして、次に確認すべき項目を提示します。vSphere には一切触れません。どこにも接続せず、修正も実行しません。書き込みを行うのは、$OPS_HOME 配下のローカルなケース台帳のみです。修復は vmware-aiops（単一操作）または vmware-pilot（複数ステップ、承認制）に引き継がれます。これは vmware-harden → vmware-pilot のアドバイザー／実行者の役割分担を踏襲しています。

手法、イベントエンベロープの契約、症状の振り分けについて詳しくは、skills/vmware-debug/SKILL.md をご覧ください。

2.0 へのアップグレード

2.0 では、14 個の MCP ツールのうち 13 個の名前が変更され、すべての名前が動詞で始まるようになりました（例：case_close → close_case、case_get → get_case、case_grade → grade_case）。旧名から新名への対応表は、RELEASE_NOTES.md にあります。それ以外に変更はありません。ツール、パラメーター、安全ゲート、CLI コマンドは従来どおりです。エージェントのプロンプト、スクリプト、または ~/.vmware/rules.yaml でツール名を指定している場合は、更新してください。ただし、旧名を使った拒否ルールは vmware-policy ≥ 1.18.1 で引き続き機能します（vmware-audit policy で、名前変更によって対象が広がったルールを確認できます）。また、vmware-pilot ≥ 1.13 は、保存済みのワークフロー内の旧名を変換します。 2.0 より前のインストール環境でも同じ rules.yaml を共有している場合は、そちらにも vmware-policy ≥ 1.18.2 を導入してください。各ルールを旧名と新名の両方に照合するため、ひとつのファイルで両方に対応できます。

関連スキル

必要な機能	スキル
インシデントの関連付け／根本原因	vmware-debug（このプロジェクト）
ログの一元検索	vmware-log-insight（search_logs の結果をここに渡します）
vCenter のイベントとアラーム	vmware-monitor
メトリクス／異常	vmware-aria
修正の実行	vmware-aiops（単一操作）／vmware-pilot（複数ステップ、承認制）

インストール

uv tool install vmware-debug
vmware-debug categories          # see which symptom categories it can diagnose

MCP ツール（14 個 — 読み取り 7 個、書き込み 7 個）

7 個の書き込みはローカルのケース台帳にのみ行われ、VMware システムには一切到達しません。

相関分析 — 単一の確認に使用するステートレス機能です。

ツール	内容
build_incident_timeline	[READ] 事前に取得したイベントを相関分析 → タイムライン＋急増箇所＋優先順位付きの仮説＋次に確認する項目の案
list_symptom_categories	[READ] 認識されている症状カテゴリと、各カテゴリで確認する項目を一覧表示

調査台帳 — 時間をかけて推論するインシデントに使用します。

ツール	内容
open_case	[WRITE] イベントを定義し、ケース ID と、この環境で到達可能なグレードを返します
get_case_readiness	[READ] 調査を始める前に、症状カテゴリごとにこの環境で到達可能なグレードを確認します
get_case_knowledge	[READ] 受け入れ可能なナレッジ形式、マウント済みのデータ、およびケースに適用されるエントリを確認します
plan_case	[READ] 次に取得するものを、各手順のスキル、ツール、目的とともに提示します。ケースの現在の状態に基づいて再計算されます
list_cases	[READ] ケースを新しい順に一覧表示します
get_case	[READ] 1 件のケースの範囲、台帳のサイズ、グレードの履歴を確認します
record_case_hypothesis	[WRITE] 候補となる説明を登録するか、各説明を裏付ける証拠と反証する証拠の台帳を読み取ります
submit_case_evidence	[WRITE] 取得した事実を 1 件、その出典、クエリ、時間基準とともに記録します
record_case_gap	[WRITE] 取得できなかった情報と、その不足を埋める方法を記録します
record_case_timeline	[WRITE] ケースで収集したすべての情報を相関分析し、1 つのタイムラインにまとめます
grade_case	[WRITE] 台帳に基づいて結論のグレードを再計算し、記録します
close_case	[WRITE] 最終グレードを記録してアーカイブし、未解決のまま残った項目を明記します

イベントエンベロープ：{ts, source, severity, entity, text, fields}。エージェントは、各ソースのイベントをデバッグ機能に渡す前にこの形式に正規化するため、デバッグ機能には他のパッケージへのランタイム依存関係がありません。 各イベントの event_type は必ず fields に含めてください。分類器はテキストだけでなく event_type も照合します。また、最新の vSphere イベントの多くは EventEx です。テキストは汎用的な定型文であり、イベントの実際の種類を示すのは eventTypeId だけです。

セキュリティ

設計上、オフラインで認証情報を必要としません。vCenter／NSX／Aria に接続せず、VMware に対する破壊的な操作手段もなく、漏えいする秘密情報も保持しません。書き込みはローカルのケース台帳へのみ行われます。証拠、不足情報、仮説、グレード履歴は追記専用です。timeline.md は証拠から再生成され、case.json には現在のグレードとステータスが保持されます。複数のプロセスで書き込む場合も同様です。ケースへの書き込みはすべて、そのケースのロックファイル（.ledger.lock、排他的作成）を最初に取得するため、共有 $OPS_HOME 内の同じケースに 2 つのプロセスが書き込む場合、互いのエントリを失うのではなく、順番に処理されます。すべてのファイルは一時的な名前で書き込んでから配置されるため、読み取り側が書き込み途中のファイルを見ることはありません（ハードリンクのないファイルシステムでは、新しい証拠ファイルはその場所に直接作成されます。この場合も上書きはされませんが、書き込み途中の内容が読み取られる可能性があります）。クラッシュしたプロセスが残したロックは、保持者とともに報告され、自動削除されることはありません。そのケースに書き込み中のプロセスがないことを確認してから、手動で削除してください。リリース済みのバージョン 1.11.3 以前ではこのロックを取得しないため、ケースディレクトリを共有するすべてのマシンをアップグレードする必要があります。SECURITY.md を参照してください。

オフライン／エアギャップ環境へのインストール（ソースから）

このプロジェクトでは最新の PEP 517 ビルドシステム（hatchling）を使用しているため、設計上 setup.py はありません。これは想定どおりであり、ファイルが欠けているわけではありません。ソースをクローンして ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build が表示された場合、pip が 21.3 より古く、setuptools 以外のバックエンドでは 編集可能（-e）インストールを実行できません。編集可能モードは開発者向けの利便機能であり、ツールの実行には不要です。次のいずれかを実行してください。

# From the source tree — a normal (non-editable) install builds a wheel:
pip install .              # NOT  pip install -e .

# ...or upgrade pip first, and editable works too:
pip install --upgrade pip && pip install -e .

完全なエアギャップ環境のホストでは、ネットワークに接続されたマシンで wheel をビルドしてコピーしてください。そうすれば、インストール先ではネットワークが不要になります。

# On a connected machine, collect this package + its dependencies as wheels:
pip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this package)

# Copy dist/ to the air-gapped host, then install offline:
pip install --no-index --find-links dist vmware-debug

リモートアクセス（HTTPS）とツールの制限

デフォルトでは、vmware-debug mcp は 1 つのローカルクライアントと stdio で通信し、すべてのツールを提供します。次の 2 つの方法で変更できます （vmware-policy ≥ 1.21.0）。

HTTPS 経由で提供することで、ほかのマシン上のクライアントが接続できます。すべての呼び出し元にベアラートークンが必要です。

vmware-audit token create alice          # prints the token once; give it to alice
vmware-audit token list                  # names only
vmware-audit token revoke alice          # refused from its next request, no restart
vmware-debug mcp --transport https --host 0.0.0.0 --port 8443 \
    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
    --public-name mcp.example.com

クライアントを接続します（ここでは Claude Code を例に示します。ストリーミング可能な HTTP とカスタムヘッダーに対応する MCP クライアントであれば使用できます）。

claude mcp add --transport http vmware-debug https://mcp.example.com:8443/mcp \
    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"

{
  "mcpServers": {
    "vmware-debug": {
      "type": "http",
      "url": "https://mcp.example.com:8443/mcp",
      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
    }
  }
}

• トークンがない場合、サーバーは起動しません。また、--public-name で指定された値以外の Host／Origin を拒否し、バインド前に未認証のリクエストが 401 を返すことを確認します。指定した名前に対して、クライアントが信頼する証明書を使用してください。
• 同じマシン上で TLS 終端を行うリバースプロキシの背後では、--transport http --host 127.0.0.1 --public-name mcp.example.com を使用し、Authorization ヘッダーを転送してください。
• 別のマシン上のロードバランサーまたはゲートウェイの背後では、--transport https を使用してください（自己署名証明書でもかまいません）。ロードバランサーが Host として送信するホスト名を --public-name に指定し、Authorization を転送するよう設定してください。ヘルスプローブには GET /healthz を使用できます。これはトークンを必要とせず、{"status": "ok"} のみを返します （vmware-policy ≥ 1.23.0）。
• 各リクエストに traceparent または X-Request-ID を含めると、監査ログの行に保存されます。その後、vmware-audit log --correlation-id ID を実行すると、1 つのプラットフォームリクエストに関連する呼び出しを検索できます。
• 監査ログでは各呼び出し元が token:<name> として記録されます。異なるターゲットを指定する呼び出しは並列で実行されます。ターゲットを指定しない呼び出しは一度に 1 つずつ実行されるため、複数の人がサーバーを共有する場合はターゲットを指定してください。
• エンドポイントにアクセスできるすべての人が、このサーバーのアカウントで操作します。 トークンは呼び出し元を識別しますが、プラットフォーム上での権限は付与しません。権限レベルごとにエンドポイントを 1 つ実行してください。
• 1 つのエンドポイントを複数の人やロールで共有する場合： vmware-audit roles enable を一度実行し、各トークンにロールを割り当てます（vmware-audit token create NAME --role reader、または使用可能なツールとターゲットを指定する roles.yaml 内のロールを使用します。vmware-policy ≥ 1.24.0）。ロールは、このエンドポイントでトークンが呼び出せる範囲を制限します。アカウントが持つ権限を超える権限を付与することはできません。vmware-policy の README の「Roles for network callers」を参照してください。

読み取りツールと、選択した書き込みツールのみを提供します。

vmware-debug mcp --expose read --allow-write close_case
# or: VMWARE_DEBUG_MCP_EXPOSE=read VMWARE_DEBUG_MCP_ALLOW_WRITE=close_case vmware-debug mcp

提供されないツールは、クライアントのツール一覧に表示されません。不正な値や不明な書き込みツールを指定すると、サーバーは停止します（exit 2）。この設定はクライアントに提供するツールを制限するものであり、認可ではありません。そのため、アカウント自体には最小限の権限のみを付与してください。

詳細：skills/vmware-debug/references/setup-guide.md（「Serving MCP over HTTPS」、「Limiting which tools are offered」）。

ライセンス

MIT。