DNSFilter

DNSFilter MCP サーバー

DNSFilter の DNS セキュリティ／フィルタリング API（組織、ネットワーク（サイト）、フィルタリングポリシー、コンテンツ／アプリケーションカテゴリ、カスタムブロックページ、トラフィック／脅威レポート機能全般）を、AI アシスタントと WYRE Conduit ゲートウェイ向けに提供する MCP サーバーです。

対象範囲

この v1 で意図的に対象を絞った読み取り専用の機能範囲は、組織、ネットワーク、ポリシー、カテゴリ、ブロックページ、レポートに限定されています。 DNSFilter の REST API（api.dnsfilter.com）には、はるかに広範な機能（MSP／ディストリビューター管理、請求、ユーザー、ローミングクライアントエージェント、エンタープライズ SSO 接続、API キー管理、スケジュール済みレポートなど）にわたる、ドキュメント化されたエンドポイントが 217 個あります。ここでは、見落としではなく設計上の理由から、そのいずれも実装していません。このコネクターのすべてのツールは、DNSFilter が公開している OpenAPI 仕様（https://api.dnsfilter.com/docs.json）の実在するドキュメント化済み GET 操作に 1 対 1 で対応しています。このコードベースには、書き込み、更新、削除のツールは一切ありません。

明示的な対象外（対象リソースに対するすべての書き込み／変更操作）。今後も実装しません：

• 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 接続、スケジュール済みポリシー／レポート、ローミングクライアントのユーザーエージェント（一括削除／更新／クリーンアップ、アンインストールキューからの取り出し）、ドメインメモ、IP／MAC アドレス管理、トライアル。

これらは、需要があれば、対象範囲を慎重に決定したうえで、後続の対応として追加できます。デフォルトで追加するものではありません。

保留（読み取り専用。この v1 では未実装で、セキュリティ上の除外ではありません）： 同じリソースグループには、読み取り専用のサブリソースやダッシュボード関連エンドポイントがいくつかありますが、まだ接続されていません。ネットワークサブネット（GET /v1/networks/{id}/subnets*）、ネットワーク LAN IP（GET /v1/networks/{id}/lan_ips*）、ポリシー IP（GET /v1/policy_ips*）、すべてのリストエンドポイントのページネーションなしの */all 版（ページネーション付きリストツールと重複）、管理用の */counts エンドポイントが該当します。すでに読み取り専用であるため、対象範囲のポリシーを変更せずに、後から追加できます。

認証

DNSFilter の認証には、DNSFilter ダッシュボードの Account Settings -> Security -> API Keys で生成する静的な API キーを使用します（1 アカウントで同時に有効化できるキーは最大 5 個です。DNSFilter の API Keys に関する記事を参照してください）。WYRE Conduit の他の多くのコネクターとは異なり、キーはヘッダー値にそのまま送信します。Authorization: <key> の形式で、Bearer プレフィックスは付けません。これは DNSFilter 独自の API ドキュメントに基づいています。「Authorization リクエストヘッダーを設定して認証します。ヘッダー値は API キーそのものです。例：Authorization: eyJ...」。

認証情報の権限範囲：意図的に確信度を変えた2つの別個の主張

• 構造的に検証済み（コードを直接確認し、確信を持って述べています）： このコネクター自身のコードでは、状態を変更する呼び出しは一切行いません。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 のロール列挙型には、"administrator" と並んで "read_only" も明示的に含まれています（MSP／ディストリビューターのメンバーシップ形式では、"network_administrator"／"network_support"／"support" と並んでいます）。したがって、DNSFilter で実際に制限されたユーザーロールは、ダッシュボードの UI に記載されているだけではなく、API 自体で第一級の概念として文書化されています。
• ベンダーのドキュメントに記載あり、独立検証は未実施（意図的に断定を避けています）： DNSFilter のヘルプセンターには、ダッシュボードレベルの Read Only ユーザーロールについて別途説明があり、「Read Only のような、より制限の厳しいロールを持つユーザーには、ダッシュボードのタブやパネルが表示されません」と記載されています。上記の構造的な確認結果とあわせると、専用の 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 認証

MCP_TRANSPORT=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_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> をキー CONDUIT_S2S_SECRET で HMAC-SHA256 した値を、16 進数でエンコードしたものです。タイムスタンプは、サーバー時刻との差が 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 をコピーし、以下の変数を設定してください。

環境変数	説明
DNSFILTER_API_KEY	DNSFilter ダッシュボードで生成する DNSFilter API キーです。stdio および AUTH_MODE=env で必須です。gateway の Compose サービスには設定しません。
MCP_TRANSPORT	stdio（デフォルト）または http です。
AUTH_MODE	env（デフォルト。上記の変数を読み取ります）または gateway（Conduit gateway によって注入される X-DNSFilter-Api-Key ヘッダーを介して、認証情報をリクエストごとに受け取ります）です。イメージと Compose のデフォルトは gateway です。gateway モードでは、DNSFILTER_API_KEY へのフォールバックは行いません。
CONDUIT_S2S_SECRET	HTTP で必須です。X-Gateway-S2S の検証に使用するサービス間シークレットです。空、または既知のプレースホルダーの場合、プロセスは終了します。Compose はこの値がないと起動しません。実際の値をコミットしないでください。
MCP_ALLOW_INSECURE_DEV	CONDUIT_S2S_SECRET なしでローカル HTTP を使用する場合に限り、正確に 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 です。

ツール

6 つのリソースグループにわたる、DNSFilter のドキュメントに記載された GET 操作ごとに 1 つの、読み取り専用ツールが 57 個あります。

組織

• dnsfilter_list_organizations - この API キーで表示できる組織の一覧を取得します。
• dnsfilter_get_organization - 1 つの組織の基本情報を取得します。
• dnsfilter_get_organization_settings - 組織レベルの設定を取得します。

ネットワーク

• dnsfilter_list_networks - ネットワーク（サイト／ロケーション）の一覧を取得します。
• dnsfilter_get_network - 1つのネットワークの基本情報を取得します。
• dnsfilter_lookup_network_by_ip - 送信元 IP アドレスに関連付けられたネットワークを検索します。
• dnsfilter_get_networks_geo - すべてのネットワークの地域／ロケーションのメタデータのみを取得します。

ポリシー

• dnsfilter_list_policies - フィルタリングポリシーの一覧を取得します。
• dnsfilter_get_policy - 1つのポリシーの完全な設定（許可／ブロックリスト、カテゴリ、アプリケーション）を取得します。
• dnsfilter_get_application_policies - 特定のアプリケーションを許可／ブロックするポリシーを取得します。
• dnsfilter_get_policy_permissive_mode - ポリシーで許容モード（監視のみ）が有効になっているかどうかを取得します。

カテゴリ

• dnsfilter_list_categories - コンテンツフィルタリングカテゴリの一覧を取得します。
• dnsfilter_get_category - 1つのコンテンツカテゴリの詳細と階層を取得します。
• dnsfilter_list_application_categories - アプリケーションカテゴリの一覧を取得します。
• dnsfilter_get_application_category - 1つのアプリケーションカテゴリの詳細を取得します。

ブロックページ

• dnsfilter_list_block_pages - カスタムブロックページの一覧を取得します。
• dnsfilter_get_block_page - 1つのカスタムブロックページの設定を取得します。

メトリクス

• 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 - 1秒あたりのクエリ数の時系列データ。
• dnsfilter_get_query_logs - DNS クエリログの生データ（ドメイン、リクエスター、カテゴリ、許可／ブロックの結果）。このコネクターが公開するレポートの中で、最も粒度が細かく、個人を特定できる情報を含みます。
• 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_* レポートでは、ローカルユーザーまたはクライアント／エージェントごとに結果が分類されます）。単なる読み取りであっても、PII やセキュリティ態勢に関わるデータであり、Cork、CyberQP、Cisco Duo など、今回の WYRE Conduit のセキュリティカテゴリの他のコネクターと同じ方針が取られています。

開発

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 を使い、X-Gateway-S2S に t=<unix seconds>,v1=<hex hmac-sha256 of that t= string> の署名を付けてください。

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

Compose は、CONDUIT_S2S_SECRET が設定されていない場合は起動を拒否し、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