Cisco Duo

Cisco Duo MCP サーバー

AI アシスタントおよび WYRE Conduit ゲートウェイ向けの、Cisco Duo の ID／MFA 管理 API 用 MCP サーバーです。ユーザー、そのユーザーに登録されている MFA 方式、電話、ハードウェアトークンとデスクトップトークン、グループ、インテグレーション、認証／管理者／テレフォニーのログを読み取り専用で確認できます。

Duo には機械可読な OpenAPI 仕様がありません。このコネクター内のすべてのエンドポイントは、Duo の公開ドキュメント（Admin API、Auth API）に照らして手動で検証し、Duo 独自のリファレンスクライアントである duo_client_python と相互確認しています。

認証

Duo は OAuth2 やベアラートークンではなく、署名付きリクエスト方式で認証します。このコネクターが実装しているのは、現在推奨されている **Duo Auth Signature v5（HMAC-SHA512）**であり、旧式の v2（HMAC-SHA1）方式ではありません。

必要な認証情報フィールドは 3 つです。

フィールド	説明
ikey	インテグレーションキー。インテグレーションを識別します。Basic 認証のユーザー名として送信されます。秘密情報ではありません。
skey	シークレットキー。HMAC-SHA512 の署名キーです。このインテグレーションの管理者スコープにおけるベアラートークン相当の情報です。通信経路上で送信されることはなく、ログにも記録されません。
apiHost	このアカウントの Duo API ホスト名です。例：api-xxxxxxxx.duosecurity.com。秘密情報ではありません。

各リクエストは、src/client.ts の signV5Get() で呼び出しごとに新たに署名されます。7 行の正規化文字列（日付、メソッド、ホスト、パス、ソート済みクエリーパラメーター、SHA-512 の本文ハッシュ、SHA-512 の署名対象ヘッダーのハッシュ）を \n で連結し、skey で HMAC-SHA512 署名します。16 進数の署名は Authorization: Basic base64(ikey:signature) として送信され、署名時とまったく同じ RFC 2822 タイムスタンプを含む Date ヘッダーも送信されます。このコネクターは GET のみを使用するため、本文ハッシュは常に空文字列のダイジェストです。また、追加の X-Duo-* 署名対象ヘッダーは使用しないため、ヘッダーハッシュも常に空文字列のダイジェストです。

ゲートウェイモードでは、Conduit ゲートウェイによって挿入される X-Duo-Ikey ／ X-Duo-Skey ／ X-Duo-Api-Host ヘッダーを介して、3 つのフィールドがリクエストごとに渡されます。ローカル／stdio モードでは、DUO_IKEY ／ DUO_SKEY ／ DUO_API_HOST から一度だけ読み込まれます。

認証情報自体が実行できることと、このコネクターが呼び出す内容の違い。 このコネクターのコードは設計上読み取り専用です（下記の「スコープ」を参照）。ただし、これはこのコードベースについての説明であり、Duo 側のサーバーによる制御についてではありません。Duo Admin API のインテグレーションには、それぞれ個別に設定できる権限（Grant Read Resource、Grant Write Resource、Grant Read Log、Grant Read Settings、Grant Write Settings など）があり、インテグレーションの作成時に Duo Admin Panel で設定します。Duo はこれらをサーバー側で確実に適用します。Grant Write Resource のないインテグレーションが書き込みを試みると、Duo 自体から実際の認可エラーが返されます。この動作は Duo のドキュメントと、まさにこの失敗例に関するコミュニティの報告で確認されています。このコネクターが読み取り権限を超えて使用することはありませんが、顧客が提供する ikey ／ skey のペアに適用されるスコープは、Duo でそのインテグレーションに付与された権限の範囲に限られます。顧客がこのコネクターに不要な Grant Write Resource を付与した場合、このコネクターのコードが書き込みを呼び出すことはなくても、認証情報自体には書き込みを実行する権限が与えられます。**Duo Admin Panel では、このインテグレーションに Grant Read Resource のみを付与し（ログツールを使う場合は Grant Read Log も付与する）ことを推奨します。**これにより、このコネクター独自のコードレベルの制限に加えて、認証情報の権限も最小限に抑えられます。

防御的なフィールド除去：Duo のインテグレーションエンドポイントは、一部の読み取りレスポンスにシークレットに見えるフィールドを含めて返すことが知られています。また、API にはインテグレーションの種類ごとにこれを網羅的に検証できる機械可読なスキーマがありません。このコネクターのすべてのツールからのレスポンスは、インテグレーションに限らず、モデルに渡される前に必ず stripSecretFields() を通ります。深さを問わず、キーが /secret|skey/i に一致するオブジェクトフィールドはすべて除去されます。これは、以下のエンドポイントレベルの除外に代わるものではなく、それを補完する包括的な安全策です。

設定

環境変数	説明
DUO_IKEY	Duo インテグレーションキー。
DUO_SKEY	Duo シークレットキー（HMAC-SHA512 署名シークレット）。
DUO_API_HOST	このアカウントの Duo API ホスト名。
MCP_TRANSPORT	stdio（デフォルト）または http。
AUTH_MODE	env（デフォルト。上記の変数を読み込みます）または gateway（Conduit ゲートウェイによって挿入される X-Duo-Ikey／X-Duo-Skey／X-Duo-Api-Host ヘッダーを介して、リクエストごとに認証情報を受け取ります）。
CONDUIT_S2S_SECRET	設定されている場合、HTTP トランスポートでは、すべての /mcp リクエストに有効な X-Gateway-S2S ヘッダー（Conduit サイドカー認証）が必要です。
LOG_LEVEL	debug | info（デフォルト）| warn | error。

リクエスト制限

• 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（リクエストボディ／バッチ上限の欠如）への対策です。

ツール

22 個すべてのツールは読み取り専用であり、動詞に関係なく、Conduit の VENDOR_TOOL_CONFIG で isAdmin: true に分類されています。これは ID／MFA 管理データ（PII：電話番号、メールアドレス、デバイスの OS、登録済み要素の詳細）であり、単なる読み取りであっても機密情報です。

ユーザー

• duo_list_users - ユーザーを一覧表示します。必要に応じて、ユーザー名との完全一致で絞り込めます。
• duo_get_user - ユーザーの詳細情報を取得します。
• duo_list_user_groups - ユーザーが所属するグループを一覧表示します。
• duo_list_user_phones - ユーザーに登録されている電話を一覧表示します。
• duo_list_user_tokens - ユーザーに登録されているハードウェアトークンを一覧表示します。
• duo_list_user_webauthn_credentials - ユーザーの WebAuthn 認証情報を一覧表示します。
• duo_list_user_u2f_tokens - ユーザーの従来型 U2F セキュリティキーを一覧表示します。

電話

• duo_list_phones - 電話を一覧表示します。必要に応じて、番号／内線番号で絞り込めます。
• duo_get_phone - 電話の詳細情報を取得します。

トークン

• duo_list_hardware_tokens - ハードウェアトークン（HOTP/TOTP/YubiKey）を一覧表示します。
• duo_get_hardware_token - ハードウェアトークンの詳細情報を取得します。
• duo_list_desktop_tokens - Duo Desktop トークンを一覧表示します。
• duo_get_desktop_token - Duo Desktop トークンの詳細情報を取得します。

グループ

• duo_list_groups - グループを一覧表示します。
• duo_get_group - グループの詳細情報を取得します。
• duo_list_group_users - グループに所属するユーザーを一覧表示します。

インテグレーション（メタデータのみ）

• duo_list_integrations - 設定済みのインテグレーションを一覧表示します。
• duo_get_integration - インテグレーションのメタデータ全体を取得します。

ログ

• duo_get_authentication_log - 認証ログ（v2）を取得します。時間で絞り込めます。
• duo_get_administrator_log - 管理者操作ログ（v1）を取得します。
• duo_get_telephony_log - 電話通信（通話／SMS クレジット）ログ（v2）を取得します。

認証

• duo_check_credentials - 認証情報と Auth API への接続を検証します。副作用はなく、MFA トランザクションは開始しません。

対象範囲

これは、誤ったエンドポイントを使用した場合の影響が特に大きい、ID／MFA 管理製品向けに構築された、意図的に範囲を限定した読み取り専用の v1 インターフェースです。 src/client.ts に実装されている HTTP 動詞関数は doGet のみです。このコードベースには doPost／doPut／doDelete は一切ないため、以下の除外項目は文書に記載されているだけでなく、構造的に強制されています。src/__tests__/tool-set.test.ts では 22 個のツールセットを厳密に固定し、ツール名が /bypass|delete|disassociate|deactivate|revoke|enroll/i に一致しないことを検証しています。

厳格な除外対象（認証情報を露出させるもの）— 実装しません：

• GET /admin/v1/users/{user_id}/bypass_codes (get_user_bypass_codes) — 有効で、使用可能な MFA バイパスコードを返します。読み取り操作であっても、これは API 内で最も機密性の高い機能であり、安全な一覧／詳細取得とは見なさず、コード生成機能と併せて除外します。
• POST /admin/v1/users/{user_id}/bypass_codes (add_user_bypass_codes) — バイパスコードを生成します。

厳格な除外対象（プロビジョニング／変更）— 実装しません：

• DELETE /admin/v1/users/{user_id}、DELETE /admin/v1/phones/{phone_id}、DELETE /admin/v1/tokens/{token_id}、DELETE /admin/v1/desktoptokens/{desktoptoken_id}、DELETE /admin/v1/groups/{group_id}、DELETE /admin/v3/integrations/{integration_key} — すべてオブジェクトの削除です。
• DELETE /admin/v1/users/{user_id}/phones/{phone_id} (delete_user_phone)、DELETE /admin/v1/users/{user_id}/tokens/{token_id} (delete_user_token) — 関連付けの解除操作です。
• POST /admin/v1/users/{user_id}/phones (add_user_phone)、POST /admin/v1/users/{user_id}/tokens (add_user_token) — 関連付け操作です。
• POST /admin/v1/users、POST /admin/v1/phones、POST /admin/v1/tokens（すべての add_*_token バリアント）、POST /admin/v1/desktoptokens、POST /admin/v1/groups、POST /admin/v3/integrations — すべてオブジェクトの作成です。
• 上記のすべてのオブジェクトタイプに対する POST／PUT 更新エンドポイント（update_phone、update_token、resync_hotp_token、update_desktoptoken、activate_desktoptoken、update_group、インテグレーション設定の更新）と、ポリシーを書き込むエンドポイント（POST /admin/v1/settings）。
• POST /auth/v2/preauth、POST /auth/v2/auth、POST /auth/v2/enroll、POST /auth/v2/enroll_status — 実際のユーザー向け MFA トランザクションを開始するか、ID を作成する Auth API エンドポイントです。

v1 の対象範囲外（認証情報やプロビジョニングに関するものではなく、このコネクターの読み取り対象に含まれないものです。意図的な追加検討として、後から追加できる可能性があります）：

• GET /auth/v2/ping — 認証不要の API 稼働確認で、管理に関連するデータはありません。
• GET /auth/v2/auth_status — 実行中の /auth トランザクションのステータスをポーリングします。対象外の /auth／/preauth エンドポイントがなければ、単独での用途はありません。
• GET /admin/v1/admins — Duo 管理者の一覧（エンドユーザーアカウントとは別です）。タスクで求められているツールのカテゴリ（ユーザー／電話／トークン／グループの一覧と詳細、ログ、インテグレーションのメタデータ、認証ステータスの確認）には含まれません。
• GET /admin/v1/billing/*、GET /admin/v1/info/summary、GET /admin/v1/settings — アカウント概要、請求、設定の読み取りです。
• GET /admin/v1/users/directorysync — ディレクトリ同期の一覧です。
• Accounts API（MSP） — Cisco により 2026-06-11 時点で非推奨となっています。サブアカウント管理は Admin API の請求エンドポイントに統合されています。実装すべき別個のインターフェースはありません。
• Device API（Trusted Endpoints のデバイスキャッシュ） — 管理システム連携ごとにスコープされた、別個の mkey／skey 認証情報ペアを使用します。これは、このコネクターが前提とするアカウントレベルの ikey／skey とは異なる認証情報モデルです。v1 では実装しません。追加する場合は、認証情報の形式について個別に慎重な判断が必要です。

需要があれば、対象範囲を慎重に検討したうえで、後から追加できます。既定で追加されることはありません。

開発

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

Docker

docker build -t cisco-duo-mcp .
docker run -p 8080:8080 -e DUO_IKEY=... -e DUO_SKEY=... -e DUO_API_HOST=... cisco-duo-mcp