Cisco Umbrella

Cisco Umbrella MCP Server

Cisco Umbrella の NextGen REST API（デプロイメントのインベントリ、管理者、ポリシー、レポート、調査に関する可視性）を利用する、AI アシスタントおよび WYRE Conduit ゲートウェイ向けの MCP サーバーです。

認証

Umbrella 管理コンソール（Admin > API Keys、または Multi-org/MSP コンソールでは Console Settings > API Keys）で API Key を作成すると、API Key と API Secret のペアを受け取れます。

シークレットが表示されるのは作成時の一度だけで、後から取得できません。すぐに安全な場所へ保管してください。

このサーバーは、そのペアを POST /auth/v2/token（grant_type=client_credentials、HTTP Basic 認証）で有効期間の短い（1 時間）Bearer アクセストークンに交換し、交換と有効期限切れ時の更新を内部で処理します。呼び出し元が指定する必要があるのは、以下の長期間有効な API Key/Secret のみです。

Cisco 自身のドキュメントに実際に存在する相違点について: Cisco が公開している Postman コレクション（CiscoDevNet/cloud-security、Umbrella/PostmanExamples/umbrella-external-postman-collection.json）では、トークンリクエストは本文のない単純な GET として記述されています。一方、Cisco の DevNet「Getting Started」と「Quickstart」の説明ドキュメントは、どちらも独立して grant_type=client_credentials のフォーム本文を含む POST を指定しています。このサーバーは、独立した 2 つのドキュメントページの記述が一致し、Cisco が明示的に指定している標準の OAuth2 client_credentials フローにも合致するため、説明ドキュメントに従って POST を使用します。ただし、実際の認証情報のペアを使った検証は行っていません。実際のアカウントでトークン交換が 401 エラーになる場合は、認証情報に問題があると判断する前に、本文のない単純な GET を試してください。

設定

.env.example をコピーし、以下の変数を設定してください。stdio トランスポートは CISCOUMBRELLA_* を読み取り、CONDUIT_S2S_SECRET は使用しません。

環境変数	説明
CISCOUMBRELLA_API_KEY	Umbrella 管理コンソールの API Key。stdio と AUTH_MODE=env で必須です。ゲートウェイモードでは読み取られません。
CISCOUMBRELLA_API_SECRET	API Key と対になる API Secret。作成時に一度だけ表示されます。stdio と AUTH_MODE=env で必須です。ゲートウェイモードでは読み取られません。
MCP_TRANSPORT	stdio（デフォルト）または http。
AUTH_MODE	env（デフォルト。上記の変数を読み取ります）または gateway（Docker イメージと Compose のデフォルト）。ゲートウェイモードでは、各 /mcp リクエストに X-CiscoUmbrella-Api-Key と X-CiscoUmbrella-Api-Secret が必要です。CISCOUMBRELLA_* へのフォールバックは行いません。
CONDUIT_S2S_SECRET	HTTP で必須です。/mcp の X-Gateway-S2S と照合する HMAC シークレットです。openssl rand -hex 32 で生成してください。空の場合、または既知のプレースホルダーの場合、HTTP サーバーはエラーをログに記録してゼロ以外のステータスで終了します。この値がログに記録されることはありません。
MCP_ALLOW_INSECURE_DEV	HTTP を CONDUIT_S2S_SECRET なしで起動するには、値を正確に 1 に設定します。警告をログに記録し、X-Gateway-S2S の検証を行わず、127.0.0.1 のみでバインドします。MCP_HTTP_HOST がループバック以外の場合は起動を拒否します。既知のプレースホルダーシークレットも拒否されます。ローカル開発専用です。
MCP_HTTP_HOST	MCP_TRANSPORT=http の場合のバインドアドレス。デフォルトは 127.0.0.1 です。CONDUIT_S2S_SECRET が設定されている場合、この値が使用されます。コンテナーイメージでは 0.0.0.0 が設定されます。
MCP_HTTP_PORT	HTTP ポート。デフォルトは 8080 です。
LOG_LEVEL	debug | info（デフォルト）| warn | error。

/health と /healthz は認証不要のままで、認証情報を読み取りません。

HTTP 認証

MCP_TRANSPORT=http が設定され、CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。検証処理は src/s2s-verify.ts の verifyS2sHeader です。ヘッダー値は t=<unix seconds>,v1=<hex> で、hex は CONDUIT_S2S_SECRET をキーとして、リテラル文字列 t=<unix seconds> の HMAC-SHA256 を計算した値（小文字の16進数64文字）です。タイムスタンプはサーバーの時刻から300秒以内でなければなりません。ヘッダーがない場合や無効な場合は、ベンダーの認証情報を読み取る前に HTTP 401 が返されます。シークレットが空の場合、MCP_ALLOW_INSECURE_DEV=1 が設定されていなければ起動を拒否します。既知のプレースホルダー（replace-with-a-real-secret、your-s2s-secret、changeme、change-me、placeholder、secret、example、replace-me、s2s-secret。大文字小文字は問いません）が設定されている場合は、このフラグが設定されていても起動を拒否するため、コピーしたサンプルを使ってヘッダーを偽造することはできません。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-CiscoUmbrella-Api-Key: $CISCOUMBRELLA_API_KEY" \
  -H "X-CiscoUmbrella-Api-Secret: $CISCOUMBRELLA_API_SECRET" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway の場合、/mcp には X-CiscoUmbrella-Api-Key と X-CiscoUmbrella-Api-Secret の両方も必要です。このリクエストでは、これらのヘッダーのみが認証情報の取得元になります。どちらか一方でも欠けているリクエストには401が返され、プロセス環境内の CISCOUMBRELLA_* へのフォールバックは行われません。

AUTH_MODE=env の場合も有効な X-Gateway-S2S ヘッダーが必要です。その後、環境変数から CISCOUMBRELLA_API_KEY と CISCOUMBRELLA_API_SECRET が使用されます。

リクエスト制限

• HTTP リクエスト本文の上限は256 KiB（262144バイト）です。X-Gateway-S2S のチェックに成功した後、Content-Length が上限を超えている場合は、JSON-RPC エラーとともに413が返されます。Content-Length のない本文には、MCP SDK トランスポートによる上限が適用されます。認証されていないリクエストには、引き続き先に401が返されます。
• tools/call の引数は、要素数が10,000個に制限されます（任意の深さにあるすべての配列要素とオブジェクトキーが対象です）。上限を超える入力には isError ツール結果が返され、ディスパッチされることはありません。

これらの制限は、CVE-2026-111768 / GHSA-46jr-4wx8-v453（検証中のメモリ枯渇）および GHSA-f897-62hf-6gxq（リクエスト本文／バッチの上限がない問題）に対処するものです。

ツール

デプロイメント

• umbrella_list_networks - 登録済みのパブリックIPネットワーク ID を一覧表示します。
• umbrella_list_internal_networks - 内部（RFC1918）ネットワーク ID を一覧表示します。
• umbrella_list_sites - Umbrella サイトを一覧表示します。
• umbrella_list_virtual_appliances - 仮想アプライアンスとそのステータスを一覧表示します。
• umbrella_list_roaming_computers - ローミングクライアントとして登録されているコンピューターを一覧表示します。
• umbrella_get_internal_domains - Umbrella DNS のバイパス対象として設定されているすべての内部ドメインを取得します。

管理

• umbrella_list_roles - 管理者ロールを一覧表示します。
• umbrella_list_users - 管理コンソールのユーザーを一覧表示します。
• umbrella_get_user - 特定の管理コンソールユーザーを取得します。
• umbrella_list_api_keys - 設定済みの API キーを一覧表示します。

ポリシー

• umbrella_list_destination_lists - 宛先（許可／ブロック）リストを一覧表示します。
• umbrella_list_destinations - 特定の宛先リスト内の宛先を一覧表示します。

レポート

• umbrella_top_destinations - リクエスト数の多い宛先を一覧表示します。トラフィックの種類（dns/proxy/firewall）で絞り込むこともできます。
• umbrella_total_requests - リクエストの合計数を取得します。トラフィックの種類で絞り込むこともできます。
• umbrella_top_categories - リクエスト数の多いコンテンツ／セキュリティカテゴリを一覧表示します。
• umbrella_activity - アクティビティの生ログを取得します。トラフィックの種類で絞り込むこともできます。
• umbrella_identities - トラフィックの概要を含む ID（ローミング／ネットワーク／モバイル／AD ユーザー）を一覧表示します。
• umbrella_appdiscovery_applications - 検出されたクラウドアプリケーションを一覧表示します。
• umbrella_appdiscovery_app_identities - 検出されたアプリケーションの使用が確認された ID を一覧表示します。
• umbrella_appdiscovery_app_risk - 検出されたアプリケーションのリスク詳細を取得します。
• umbrella_api_usage_summary / umbrella_api_usage_requests / umbrella_api_usage_responses / umbrella_api_usage_keys - API 使用状況のレポートを取得します。

調査

• umbrella_domain_categorization - ドメインのコンテンツ／セキュリティ分類。
• umbrella_domain_risk_score - ドメインの Cisco リスクスコア。
• umbrella_domain_security_score - ドメインの詳細なセキュリティスコアのシグナル。
• umbrella_top_most_seen_domains - 世界で最もよく利用されている上位100万件のドメイン。
• umbrella_get_samples - ドメイン、IP、または URL に関するマルウェア／ファイルのサンプル。
• umbrella_domain_volume - ドメインの DNS クエリ数の推移。
• umbrella_domain_resource_records - ドメインのパッシブ DNS リソースレコード。

Cisco のドキュメントでフィルター項目がすべて列挙されていない Reports／Investigate／Deployments／Admin／Policies の一覧取得ツールでは、任意の additionalParams オブジェクトを受け付けます。このオブジェクトは追加のクエリ文字列パラメーターとしてそのまま渡されます（例：Reports エンドポイントの categories、identityids、verdict、domains）。これらは Cisco がドキュメント化しているフィルターですが、このクライアントでは第一級の引数としてモデル化されていません。

対象範囲

これは v1 の読み取り専用インターフェースです。このサーバーは Deployments、Admin、Policies、Reports、Investigate の GET エンドポイントのみを実装します。Cisco 独自の Postman コレクションにある実際のエンドポイントのうち、以下は明示的に保留され、現時点では対象外です。

• 内部ドメインの追加／削除（POST／DELETE /deployments/v2/internaldomains）
• トンネルの追加／削除（POST／DELETE /deployments/v2/tunnels）
• タグの追加、およびデバイスへのタグ付け／タグ解除（POST /deployments/v2/tags*）
• ユーザーの作成／削除（POST／DELETE /admin/v2/users）
• API キーの作成（POST /admin/v2/apiKeys）
• 宛先リストへの宛先の追加／削除（POST／DELETE /policies/v2/destinationlists/{id}/destinations）
• App Discovery アプリケーションのラベルの更新（PATCH /reports/v2/appDiscovery/applications/{id}）

これらはプロビジョニングや変更を伴う操作であり、読み取り専用の監視コネクターの対象外です。これは、このリリースで Printix や WatchGuard Cloud などの他のコネクターが、プロビジョニングを多く伴う書き込み操作を保留した方針と一致しています。書き込みに対応した v2 が必要になれば、後続の対応として追加できます。

また、レガシーの Umbrella Reporting v1／v2 API（認証方式とホストが異なり、investigate.api.umbrella.com／management.api.umbrella.com を使用）と、X-Umbrella-OrgId ヘッダーによる Multi-org／MSP の子組織切り替えも明示的に対象外です。これらは実際に存在し、Cisco のドキュメントにも記載されていますが、信頼性を持って実装するには具体的なリクエスト／レスポンスの詳細が不足しています（トークンリクエスト、後続のすべてのリクエスト、またはその両方に適用されるのか）。検証用の有効な認証情報の組み合わせがないため、実装できません。

開発

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

Docker

イメージはコンテナー内で 0.0.0.0（MCP_HTTP_HOST）をリッスンし、デフォルトで AUTH_MODE=gateway を使用します。起動時には、引き続き有効な CONDUIT_S2S_SECRET が必要です。ポートはループバックインターフェースに公開してください。ゲートウェイモードでは、Umbrella の認証情報は各リクエストのヘッダーで渡され、環境変数からは読み込まれません。

docker build -t cisco-umbrella-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  cisco-umbrella-mcp

Compose は CONDUIT_S2S_SECRET が未設定の場合は起動を拒否し、AUTH_MODE はデフォルトで gateway に設定されます。また、127.0.0.1:8080:8080 を公開し、CISCOUMBRELLA_API_KEY、CISCOUMBRELLA_API_SECRET、env_file は設定しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

シングルテナントの HTTP（AUTH_MODE=env）でも S2S シークレットが必要で、その後 CISCOUMBRELLA_API_KEY と CISCOUMBRELLA_API_SECRET を使用します。これは上記のゲートウェイ Compose サービスとは別のものです。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e CISCOUMBRELLA_API_KEY=... \
  -e CISCOUMBRELLA_API_SECRET=... \
  -p 127.0.0.1:8080:8080 \
  cisco-umbrella-mcp

シークレットを使わないローカル HTTP は、開発専用です。MCP_HTTP_HOST が localhost または ::1 の場合も含め、127.0.0.1 にバインドし、警告をログに記録します。MCP_HTTP_HOST にループバック以外のアドレスを指定すると、起動時に終了します。コンテナーイメージでは MCP_HTTP_HOST=0.0.0.0 が設定されるため、Docker 内でこの回避策を使用する場合も -e MCP_HTTP_HOST=127.0.0.1 を指定する必要があります。ポートをループバック以外に公開しないでください。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http