DNSFilter

DNSFilter MCP 服务

面向 AI 助手和 WYRE Conduit 网关的 MCP 服务，用于访问 DNSFilter 的 DNS 安全与过滤 API，包括组织、网络（站点）、过滤策略、内容／应用类别、自定义拦截页面，以及完整的流量／威胁报告功能。

范围

这是一个刻意保持精简、只读的 v1 功能范围，严格限定为组织、网络、策略、类别、拦截页面和报告。 DNSFilter 的 REST API（api.dnsfilter.com）包含 217 个有文档记录的路径，涵盖的范围广泛得多——MSP／分销商管理、账单、用户、漫游客户端 Agent、企业 SSO 连接、API 密钥管理、定期报告等。这里没有实现其中任何功能，这是有意为之，而非疏忽。此连接器中的每个工具都与 DNSFilter 自行发布的 OpenAPI 规范（https://api.dnsfilter.com/docs.json）中的真实、有文档记录的 GET 操作一一对应；本代码库中没有任何写入、更新或删除工具。

明确排除（范围内所有资源的每项写入／变更操作）——永不实现：

• POST/PATCH/DELETE /v1/organizations*（create、bulk_update、promote_to_msp、update、cancel、destroy）——组织变更。
• POST/PATCH/DELETE /v1/networks*（create、bulk_create/update/destroy、update、destroy、secret_key rotate/revoke/generate）——网络变更，包括 LAN IP 和子网写入。
• POST/PATCH/DELETE /v1/policies*（create、update、destroy、application_update、add/remove_allowed_application、add/remove_blacklist_category、add/remove_blacklist_domain、add/remove_blocked_application、add/remove_whitelist_domain、permissive_mode update），以及所有 /v1/policies/bulk/*（批量添加／移除允许列表／拦截列表）和 /v1/policy_ips 写入操作——所有策略内容变更。
• POST/DELETE /v1/block_pages*（create、destroy）和 PATCH /v1/block_pages/{id}（update）——拦截页面变更。
• 此连接器完全不涉及的资源中的所有写入端点：API 密钥（create／destroy／revoke）、用户和组织用户（create／update／destroy／resend_invite）、账单／发票、分销商（MSP／子组织配置、SKU、取消）、企业 SSO 连接、定期策略／报告、漫游客户端用户 Agent（批量删除／更新／清理、dequeue-uninstall）、域备注、IP／MAC 地址管理，以及试用。

如果有需求，可以在经过审慎的范围决策后将其作为后续功能添加，而不是默认纳入。

暂缓实现（只读，不属于本 v1 的实现范围——并非出于安全原因排除）： 此连接器覆盖的资源组下还存在少量仅 GET 的子资源和与仪表板相关的端点，目前尚未接入：网络子网（GET /v1/networks/{id}/subnets*）、网络 LAN IP（GET /v1/networks/{id}/lan_ips*）、策略 IP（GET /v1/policy_ips*）、每个列表端点的未分页 */all 变体（与分页列表工具重复），以及管理用的 */counts 端点。由于这些端点本身已经是只读的，之后可以添加，无需更改范围策略。

身份验证

DNSFilter 使用静态 API 密钥进行身份验证。密钥可在 DNSFilter 仪表板的 Account Settings -> Security -> API Keys 下生成（一个账户最多可同时拥有 5 个有效密钥；请参阅 DNSFilter 自己的 API Keys 文章）。与 WYRE Conduit 的大多数同类连接器不同，密钥以原始标头值的形式发送——Authorization: <key>，不带 Bearer 前缀——这与 DNSFilter 自己的 API 文档一致："通过设置 Authorization 请求标头完成身份验证。标头值就是 API 密钥本身。例如：Authorization: eyJ..."。

凭据权限范围：两项独立声明，置信度刻意不同

• 结构上已验证（直接检查，有充分把握）： 此连接器自身的代码不会发起任何修改操作——client.ts 中的每个函数都是 GET，而且 src/ 中不存在任何 POST/PUT/PATCH/DELETE 调用（由 tool-scope.test.ts 的禁用令牌检查强制执行）。另一个结构上已验证的事实是，根据直接获取的 DNSFilter 自行发布的 OpenAPI 规范（api.dnsfilter.com/docs.json）：API 密钥是按用户账户生成的（ApiKey 资源架构包含 user_id 字段），其创建请求（ApiKeyCreateSpec）只接受 name 和 expiry——创建密钥时无法选择权限范围／角色／权限字段。因此，密钥的实际能力继承自生成该密钥时所用的 DNSFilter 用户账户所持有的角色，而不是在创建密钥时单独选择。该规范中的 Membership/OrganizationUser 角色枚举也明确包含 "read_only" 值，以及 "administrator"（在 MSP／分销商成员资格形式中，还包括 "network_administrator"/"network_support"/"support"）——因此，受限的 DNSFilter 用户角色是 API 本身正式记录的一等概念，而不只是仪表板 UI 中的说明。
• 供应商文档所述，未经独立验证（刻意保留审慎措辞）： DNSFilter 的帮助中心另行介绍了仪表板级别的 Read Only 用户角色（“Users with more restrictive roles like Read Only... have hidden dashboard tabs and panels”）。结合上述结构性发现，在专用的 Read-Only 角色用户账户下生成 API 密钥，应该会使 DNSFilter 的 API 服务器拒绝该密钥发出的任何写入端点调用——但 API 是否真的在服务器端强制执行该角色对写入调用的限制（而非仅在仪表板 UI 中限制），WYRE 尚未测试。没有人用 Read-Only 角色密钥发送实时写入调用来确认这一点，这是正确的做法：那会是针对真实账户的修改测试，未经同意不应执行。请勿将本 README 理解为已证实 Read-Only 角色 API 密钥无法对 DNSFilter API 执行写入操作——它只说明：(a) DNSFilter 的规范将 read_only 角色建模为真实的一等概念；(b) 无论收到哪种密钥，此连接器自身的代码都不会尝试写入。

在网关模式下，密钥通过 X-DNSFilter-Api-Key 标头随每个请求传入；在本地／stdio 模式下，密钥从 DNSFILTER_API_KEY 读取一次。stdio 传输不使用 CONDUIT_S2S_SECRET。

HTTP 身份验证

当 CONDUIT_S2S_SECRET 为空或为已知占位值（changeme、change-me、placeholder、secret、example、replace-me、replace-with-a-real-secret、your-s2s-secret、your-secret、s2s-secret）时，MCP_TRANSPORT=http 会拒绝启动。进程会记录错误并以非零状态退出。它绝不会打印密钥。即使设置了 MCP_ALLOW_INSECURE_DEV=1，也会拒绝使用占位值。

MCP_ALLOW_INSECURE_DEV=1 仅用于本地开发。它会在没有密钥的情况下启动 HTTP、记录警告、不检查 X-Gateway-S2S，并且只监听 127.0.0.1。在此模式下，非环回地址的 MCP_HTTP_HOST（包括 0.0.0.0）会被忽略，并记录该覆盖设置。

设置了真实密钥后，MCP_HTTP_HOST 才会生效。未设置时，绑定地址为 127.0.0.1。容器镜像将 MCP_HTTP_HOST 设为 0.0.0.0，并将 AUTH_MODE 设为 gateway。

此后，每个 /mcp 请求都必须包含 X-Gateway-S2S：

t=<unix seconds>,v1=<hex hmac-sha256>

v1 是对 ASCII 字符串 t=<unix seconds> 计算的 HMAC-SHA256，使用 CONDUIT_S2S_SECRET 作为密钥，并以十六进制编码。时间戳与服务端时钟的偏差必须在 300 秒以内。缺少或无效的标头会返回 401。

在 AUTH_MODE=gateway 下，/mcp 还要求提供 X-DNSFilter-Api-Key。请求缺少该标头时会返回 401，且不会回退到 DNSFILTER_API_KEY。/health 无需身份验证，也不会读取凭据。

请求限制

• HTTP 请求正文上限为 256 KiB（262144 字节）。X-Gateway-S2S 检查通过后（在 gateway 模式下，还需通过 X-DNSFilter-Api-Key 存在性检查），超过上限的 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（缺少请求正文 / 批处理上限）。

配置

复制 .env.example，并设置以下变量。

Env var	描述
DNSFILTER_API_KEY	DNSFilter API 密钥，在 DNSFilter 控制台中生成。stdio 和 AUTH_MODE=env 必需。网关 Compose 服务不设置此项。
MCP_TRANSPORT	stdio（默认）或 http。
AUTH_MODE	env（默认，读取上方的变量）或 gateway（凭据通过 X-DNSFilter-Api-Key 标头随请求传入，由 Conduit 网关注入）。镜像和 Compose 默认使用 gateway。Gateway 模式绝不会回退到 DNSFILTER_API_KEY。
CONDUIT_S2S_SECRET	HTTP 必需。用于验证 X-Gateway-S2S 的服务间密钥。该值为空或为已知占位值时，进程会退出。未设置该值时，Compose 不会启动。切勿提交真实密钥。
MCP_ALLOW_INSECURE_DEV	仅在本地 HTTP 开发且未设置 CONDUIT_S2S_SECRET 时，才将其准确设为 1。此设置会记录警告、跳过 X-Gateway-S2S 检查，并且只绑定 127.0.0.1。
MCP_HTTP_HOST	设置了真实 CONDUIT_S2S_SECRET 时使用的绑定地址。默认为 127.0.0.1。容器镜像将其设为 0.0.0.0。未设置密钥时，该值会被忽略（强制设为 127.0.0.1）。
MCP_HTTP_PORT	HTTP 端口。默认为 8080。
LOG_LEVEL	debug | info（默认）| warn | error。

工具

57 个只读工具，分别对应六个资源组中 DNSFilter 文档所述的 GET 操作。

组织

• dnsfilter_list_organizations - 列出此 API 密钥可见的组织。
• dnsfilter_get_organization - 获取单个组织的基本信息。
• dnsfilter_get_organization_settings - 获取组织级设置。

网络

• dnsfilter_list_networks - 列出网络（站点／位置）。
• dnsfilter_get_network - 获取一个网络的基本信息。
• dnsfilter_lookup_network_by_ip - 查找与源 IP 地址关联的网络。
• dnsfilter_get_networks_geo - 仅获取每个网络的地理位置元数据。

策略

• dnsfilter_list_policies - 列出过滤策略。
• dnsfilter_get_policy - 获取一个策略的完整配置（允许／阻止列表、类别、应用）。
• dnsfilter_get_application_policies - 获取允许／阻止特定应用的策略。
• dnsfilter_get_policy_permissive_mode - 获取策略是否启用了宽松（仅监控）模式。

类别

• dnsfilter_list_categories - 列出内容过滤类别。
• dnsfilter_get_category - 获取一个内容类别的详细信息和层级结构。
• dnsfilter_list_application_categories - 列出应用类别。
• dnsfilter_get_application_category - 获取一个应用类别的详细信息。

阻止页面

• dnsfilter_list_block_pages - 列出自定义阻止页面。
• dnsfilter_get_block_page - 获取一个自定义阻止页面的配置。

指标

• dnsfilter_get_organization_usage - 获取指定日期范围内的组织用量（套餐、用户数、请求总数）。
• dnsfilter_get_organization_usage_detailed - 获取组织用量按指标细分的详细信息。

流量报告

DNSFilter 的整个报告功能仅支持 GET 请求，因此所有 38 项已记录的报告操作均已实现，未做筛选：

• dnsfilter_get_qps、dnsfilter_get_qps_active_agents、dnsfilter_get_qps_active_organizations - 每秒查询数时间序列。
• dnsfilter_get_query_logs - 原始 DNS 查询日志条目（域名、请求方、类别、允许／阻止结果）。这是此连接器提供的粒度最细且包含个人身份信息（PII）的报告。
• dnsfilter_get_top_agents、dnsfilter_get_top_application_categories、dnsfilter_get_top_categories、dnsfilter_get_top_collections、dnsfilter_get_top_domains、dnsfilter_get_top_networks、dnsfilter_get_top_organizations_requests、dnsfilter_get_top_users - 按流量大小细分的“前 N 项”报告。
• dnsfilter_get_total_applications_agents_stats、dnsfilter_get_total_applications_collections_stats、dnsfilter_get_total_applications_networks_stats、dnsfilter_get_total_applications_stats、dnsfilter_get_total_applications_users_stats - 按不同维度细分的应用请求总数。
• dnsfilter_get_total_categories、dnsfilter_get_total_categories_organizations、dnsfilter_get_total_category_stats - 内容类别请求总数。
• dnsfilter_get_total_client_stats、dnsfilter_get_total_deployments、dnsfilter_get_total_roaming_clients - 客户端／部署数量。
• dnsfilter_get_total_domain_stats、dnsfilter_get_total_domains、dnsfilter_get_total_domains_organizations、dnsfilter_get_total_domains_users - 域名请求总数。
• dnsfilter_get_total_organizations_requests、dnsfilter_get_total_organizations_stats - 组织级请求总数。
• dnsfilter_get_total_requests、dnsfilter_get_total_requests_agents、dnsfilter_get_total_requests_collections、dnsfilter_get_total_requests_geo、dnsfilter_get_total_requests_organizations、dnsfilter_get_total_requests_users - 按不同维度细分的请求总数。
• dnsfilter_get_total_threats、dnsfilter_get_total_threats_organizations、dnsfilter_get_total_threats_users - 被阻止的威胁总数。

敏感性

此连接器中的每个工具在 Conduit 网关中都被标记为 isAdmin: true（请参阅该供应商在 result-cache.ts 中的 VENDOR_TOOL_CONFIG 条目）。这是针对整个连接器的决策，而非针对单个工具的决策。DNSFilter 在此提供的是 DNS 安全产品：策略配置、拦截页面品牌设置，以及尤其是流量报告系列，其中包含按设备/用户划分的 DNS 查询历史和威胁检测数据（dnsfilter_get_query_logs 会返回各个请求者查询的具体域名；多个 total_*/top_* 报告会按本地用户或客户端/Agent 划分结果）。即使只是普通读取，这些数据也涉及个人身份信息和安全态势；这与本轮 WYRE Conduit 对其他安全类别连接器（Cork、CyberQP、Cisco Duo）采取的处理方式一致。

开发

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

Docker

该镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），且默认使用 AUTH_MODE=gateway。请将端口发布到回环地址，并传入 S2S 密钥。在网关模式下，DNSFilter API 密钥会随每个请求通过 X-DNSFilter-Api-Key 传入；不会从环境变量读取。请使用 CONDUIT_S2S_SECRET，按 t=<unix seconds>,v1=<hex hmac-sha256 of that t= string> 的格式对 X-Gateway-S2S 签名。

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

如果未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动；它会设置 AUTH_MODE=gateway，不会注入 DNSFILTER_API_KEY，并发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍然需要 S2S 密钥，然后使用 DNSFILTER_API_KEY：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e DNSFILTER_API_KEY=your-api-key \
  -p 127.0.0.1:8080:8080 \
  dnsfilter-mcp

不带密钥的本地 HTTP 仅供开发使用。即使 MCP_HTTP_HOST 为 0.0.0.0，它仍会绑定到 127.0.0.1，并记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

许可证

Apache-2.0