Cisco Duo

Cisco Duo MCP 服务

适用于 Cisco Duo 身份/MFA 管理 API 的 MCP 服务——为 AI 助手和 WYRE Conduit 网关提供对用户、其已注册的 MFA 方法、手机、硬件和桌面令牌、群组、集成以及身份验证/管理员/电话服务日志的只读查看权限。

Duo 没有机器可读的 OpenAPI 规范；本连接器中的每个端点都经过人工核验，依据是 Duo 发布的文档（Admin API、Auth API），并与 Duo 自己的参考客户端 duo_client_python 进行了交叉核对。

身份验证

Duo 使用签名请求方案，而非 OAuth2 或持有者令牌。此连接器实现的是 Duo Auth Signature v5（HMAC-SHA512）——当前推荐的方法，而非旧版 v2（HMAC-SHA1）方案。

需要三个凭据字段：

字段	说明
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 签名；十六进制签名会与携带完全相同 RFC 2822 时间戳的 Date 标头一起，通过 Authorization: Basic base64(ikey:signature) 发送。此连接器仅支持 GET，因此请求体哈希始终为空字符串的摘要；也不会使用其他 X-Duo-* 签名标头，因此标头哈希也始终为空字符串的摘要。

在网关模式下，三个字段会由 Conduit 网关注入，并通过 X-Duo-Ikey / X-Duo-Skey / X-Duo-Api-Host 标头随每个请求传入。在本地/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 的 Integrations 端点会在某些读取响应中回显类似密钥的字段，而且 API 没有机器可读的架构可针对每种集成类型进行全面验证。此连接器中每个工具的每个响应——不仅仅是 Integrations——在到达模型之前，都会先经过 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（凭据通过 X-Duo-Ikey/X-Duo-Skey/X-Duo-Api-Host 请求头按请求传入，由 Conduit 网关注入）。
CONDUIT_S2S_SECRET	设置后，HTTP 传输要求每个 /mcp 请求都带有有效的 X-Gateway-S2S 请求头（Conduit sidecar 身份验证）。
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，不受动词影响——这些是身份 / MFA 管理数据（PII：电话号码、电子邮件、设备操作系统和已注册因子的详细信息），即使只是普通读取也很敏感。

用户

• 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 事务。

范围

这是一个刻意收窄的只读 v1 接口，专为身份/MFA 管理产品构建，因为选错端点会造成格外严重的后果。 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 事务或创建身份的 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