attack-surface-mcp-server

---

重要

許可された防御目的でのみ使用してください。 このサーバーの対象には、自身が所有する資産、または評価を明示的に許可されている資産のみを指定してください。実行するのは受動的かつ非侵襲的な偵察です。公開記録（Certificate Transparency ログ、DNS、RDAP/WHOIS）と、各対象が自ら公開しているサーフェス（ホストごとに TLS ハンドシェイク 1 回、HTTP GET 1 回）を読み取ります。ポートスキャン、エクスプロイト、ブルートフォース、ファジング、脆弱性のプロービングは行いません。この機能はフラグで制限しているのではなく、設計上サーフェスから除外されています。出力は、存在するものとセキュリティ状況を説明するものであり、エクスプロイトの計画を示すものではありません。すべての外向き接続は SSRF ガードを通過し、プライベート、ループバック、リンクローカル、クラウドメタデータの各ターゲットへの接続は拒否されます。

---

概要

Certificate Transparency ログ、DNS、TLS、HTTP、RDAP/WHOIS レジストリを利用した、受動的な外部攻撃対象領域のマッピング（EASM）です。オプションで Shodan のホストインテリジェンスも利用できます。サブドメインの検出、DNS レコードの解決、ドメインの稼働中のホスト全体にわたる TLS と HTTP のセキュリティ状況の確認ができます。

ツール

ツール	説明
attacksurface_map_domain	主要なワークフローです。ドメインの外部サーフェスを端から端までマッピングします。CTログによるサブドメイン検出 → DNSの稼働確認 →（standard以上）DNSレコード、TLSの状態、HTTPヘッダー／技術情報 →（任意で）RDAP／WHOIS →（thoroughかつキーがある場合）IPごとのShodan情報の拡充、という流れです。構造化されたサーフェスマップと、観測可能な事実に基づく防御的評価を返します。
attacksurface_enumerate_subdomains	Certificate Transparencyログ（crt.sh → Certspotter → TLS-SANのフォールバックチェーン）から受動的にサブドメインを検出し、DNS解決によって稼働中の名前を特定します。ソースごとの来歴情報を含みます。DNSブルートフォースは行いません。
attacksurface_resolve_dns	複数のパブリックリゾルバーを使って、1つ以上のホストのDNSレコード（A/AAAA/CNAME/MX/NS/TXT/CAA）を解決・列挙します。任意で逆引きDNS（PTR）も実行できます。リゾルバーごとの値から、伝播の不一致を確認できます。
attacksurface_inspect_tls	実際の読み取り専用ハンドシェイクを通じて、TLS/SSLの状態を検査します。プロトコル、暗号スイート、リーフ証明書とチェーンの深さ、SAN、有効期間、失効までの日数、発行者、検証ステータスを確認します。無効、期限切れ、自己署名の証明書も、処理を失敗させずに報告します。
attacksurface_probe_http	受動的なHTTP(S)プローブです。リダイレクトをたどってGETを1回実行します。ステータス、リダイレクトチェーン、ヘッダー、セキュリティヘッダーの監査（HSTS/CSP/X-Frame-Options/クッキーフラグ/CORSリフレクション）、証拠に基づく技術フィンガープリントを返します。
attacksurface_lookup_registration	RDAP（JSON、WHOISにフォールバック）による登録情報と所有者情報の検索です。ドメインの場合は、レジストラ、ステータス、ライフサイクルイベント、ネームサーバー、DNSSECを返します。IP/CIDRの場合は、ネットブロック、割り当てCIDR、オリジンASN、国を返します。
attacksurface_lookup_host	Shodanを介した、単一IPのインフラストラクチャ情報（オープンポート、バナー、ソフトウェアバージョン、ASN、位置情報）の取得、またはインターネット全体を対象とするファセット検索です。SHODAN_API_KEY が必要です。未設定の場合は、型付きの source_unavailable エラーを返します。サーバーのその他の機能には影響しません。
attacksurface_recon_guidance	トピック選択、件数を制限した優先事項／提案のページ表示、ローカルでの追加呼び出し、製品／バージョンのアドバイザリ確認ガイダンスを備えた、オフラインの防御的レビューです。外部への呼び出しは行いません。

リソース

リソース	説明
attacksurface://surface/{domain}	ドメインのマッピング済み外部サーフェス（サブドメイン、稼働中のホスト、ホストごとのDNS/TLS/HTTP状態の概要）の一度だけ読み取れるスナップショットです。候補の一覧と、最大50ホスト分の詳細範囲を別々に示します。

すべてのリソースデータにはツールからもアクセスできます。attacksurface_map_domain で同じ内容を取得できるため、ツールのみを使うクライアントでも情報が失われることはありません。

機能リファレンス

attacksurface_map_domain _ツール

• depth：quick はサブドメインと稼働状況を検出します。standard はDNSレコード、TLS、HTTPの状態を追加します。thorough はキーが設定されていればIPごとのShodanデータを追加し、設定されていない場合は注記を返します。
• 構造化されたサーフェスマップと、観測可能な事実に基づく防御的な assessment を返します。失敗したソースや到達できないホストは注記となります。サブドメインの解決数は ATTACKSURFACE_MAX_SUBDOMAINS（デフォルトは200）で制限され、切り捨てがあった場合は明示されます。
• includeRegistration を指定すると、standardまたはthoroughの深さでapexのRDAP/WHOISデータが追加されます。standardとthoroughでは、最初に設定されたリゾルバーからのDNSレコードと、稼働中のホストにおける伝播の不一致も返されます。quickの深さで状態がnullの場合、その処理がスキップされたことを意味します。
• coverage には、未調査の対象またはホスト詳細がない対象（unexamined、detailOmitted）が示されます。retrieval には、すぐに実行できる追加呼び出しが最大3件示されます（DNS/TLSは最大50ホストのバッチ、HTTPはURL1件）。nextToolSuggestions には、最大50ホストを対象とする attacksurface_recon_guidance 呼び出しが事前入力されます。省略された対象は guidanceCoverage に示されます。

attacksurface_enumerate_subdomains _tool

• crt.sh → Certspotter → 頂点の TLS 証明書の SAN の順に名前を検出し、その後 DNS の疎通を確認します。includeUnresolved: false を指定すると、疎通可能なホストのみが対象になります。filteredAddressErrors には、対象外となった名前の DNS エラーが保持されます。
• 各名前のソース情報と、ソースごとのステータスを返します。complete、pagesFetched、incompleteReason で一部のデータのみ取得できたことを確認でき、addressError では DNS エラーと ENODATA／ENOTFOUND による不在を区別できます。
• offset と limit（デフォルトは 50。大きな値は上限に合わせて調整されます）を指定して候補をページ分割できます。上限は min(50, ATTACKSURFACE_MAX_SUBDOMAINS) です。次のページには nextOffset または値が事前入力された continuation を使用し、残りの件数は remainingCount で確認できます。ページごとに CT ログを再読み込みするため、変更によってオフセットがずれることがあります。

---

attacksurface_resolve_dns _tool

• 1～1000 件のホストを受け付け、入力順に先頭の 50 件を処理します。再送信する対象は processedCount と remainingHosts で確認できます。パブリックリゾルバー（デフォルトは 8.8.8.8、1.1.1.1、9.9.9.9）を使用して、A、AAAA、CNAME、MX、NS、TXT、CAA を照会します。逆引き DNS（PTR）は任意です。
• リゾルバーごとの応答を返し、伝播状況の違いを確認できます。正規レコードには、最初に設定されたリゾルバーの結果が使用されます。SERVFAIL を含むリゾルバーの障害は、成功したレコードとともに queryError と hostError に表示されます。
• プライベート IP アドレスまたはループバック IP アドレスのリゾルバーには blocked_resolver が返されます。個々のホストの障害は、ホストごとのエラーになります。

---

attacksurface_inspect_tls _tool

• 1～1000 件のホストを受け付け、入力順に先頭の 50 件を処理します。再送信する対象は processedCount と remainingHosts で確認できます。ポートのデフォルトは 443、ハンドシェイクのタイムアウトのデフォルトは 8000ms（1000～30000ms）です。
• ネゴシエートされたプロトコル、暗号スイート、リーフ証明書とチェーンの深さ、SAN、発行者、有効期間、期限までの日数、検証ステータスを返します。無効な証明書、期限切れの証明書、自己署名証明書も報告されます。1 件のホストで発生した障害は、ホストごとのエラーになります。
• チェーンの信頼性（validationAuthorized／validationError）とホスト名の一致（identityAuthorized／identityError）は、別々に検証されます。有効期限を解析できない場合に限り、daysUntilExpiry は null になります。

---

attacksurface_probe_http _tool

• HTTP(S) URL を 1 つ受け付けます。タイムアウトのデフォルトは 10000ms（1000～30000ms）で、プローブ全体に適用されます。各リダイレクト先で SSRF チェックを行いながら、最大 10 回までリダイレクトを追跡します。接続が拒否された対象には blocked_target が返され、リダイレクト上限を超えると finalStatus: 0 と transportError が返されます。
• ステータス、リダイレクトチェーン、生のヘッダー、セキュリティヘッダーの検出結果（HSTS、CSP、X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy、Cookie のフラグ、CORS の反射）、および検出の根拠となった情報を含むテクノロジーの検出結果を返します。CSP の解析対象は frame-ancestors のみです。
• bodyInspection には complete、limited（64,000 バイトの先頭部分が上限）、failed、not_read のいずれかが設定されます。ボディの取得に失敗しても、ステータスとヘッダーは保持されます。

---

attacksurface_lookup_registration _tool

• ドメイン、IP、CIDR（プレフィックスは IPv4 で 0～32、IPv6 で 0～128）を受け付けます。type（auto／domain／ip）で解釈方法を指定します。まず RDAP を使用し、必要に応じて WHOIS に切り替えます。
• ドメインの結果には、レジストラ、EPP ステータス、ライフサイクルイベント、ネームサーバー、DNSSEC が含まれます。IP／CIDR の結果には、ネットブロック、割り当て CIDR、ASN、国が含まれます。情報が少ないフィールドや編集されたフィールドは不明のままとなり、生の WHOIS 応答は rawWhois に保持されます。
• WHOIS で明示的に該当なしと判定された場合は no_match が返されます。紹介先への接続に失敗した場合、または WHOIS の応答が空か未認識の場合は、source_unavailable が返されます。

---

attacksurface_lookup_host _tool

• mode: "host"（デフォルト）は、単一のIPv4/IPv6アドレスを検索し、それ以外の値には invalid_target を返します。mode: "search" はインターネット全体を対象とするクエリを受け付け、任意の facets を指定できます。Shodanのクエリクレジットを消費する場合があります。SHODAN_API_KEY が必要です。
• 検索では、1回の呼び出しにつき100件の結果を含むページを1つ返します（page のデフォルトは1で、ホストモードでは無視されます）。hasMore、nextPage、入力済みの continuation が含まれます。後続ページの取得はオプトインで、クレジットを消費する場合があります。
• Shodanの最終スキャンに基づき、ポート、バナー、ソフトウェアバージョン、ホスト名、ASN、地理情報を返します。認証情報がない場合は source_unavailable を返し、ホストデータがない場合は no_data を返します。このサーバーはポートスキャンを実行しません。

---

attacksurface_recon_guidance _tool

• 以前の調査結果（ホスト、証明書、不足しているヘッダー、ソフトウェアバージョン、ポート）を受け取ります。トピック triage はすべての調査結果を緊急度順に扱い、posture はTLS／ヘッダーの強化を扱い、coverage は調査範囲とバージョンの不足を扱います。オープンポートはインベントリ上の証拠であり、脆弱性の証明ではありません。
• priorities と、ローカルツールのみを対象とする {toolName, reason, args} 形式の提案を返します。外部呼び出しやアクティブスキャンは実行されません。
• priorityOffset と suggestionOffset は limit（デフォルト50、最大50）を使って個別にページ分割されます。元の調査結果とトピックに次のオフセットを指定して再送信してください。

---

attacksurface://surface/{domain} _resource

• ドメインを受け取り、標準の深度で attacksurface_map_domain を呼び出した場合と同等の application/json スナップショットを返します。
• サブドメイン数と稼働中ホスト数に加え、ホストごとのDNS／TLS／HTTPの状態とエラーを含みます。名前解決にはマッピングと同じ上限が適用され、状態の詳細は稼働中のホスト最大50件を対象とします。coverage には、省略された内容と追加呼び出しの方法が記載されます。

機能

@cyanheads/mcp-ts-core を基盤としており、stdioおよびStreamable HTTPトランスポート、切り替え可能な認証（none／jwt／oauth）、交換可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、任意でOpenTelemetryトレースを利用できる構造化ログを提供します。

攻撃対象領域に特化した機能：

• 要件として受動的かつ非侵入的に動作します。公開記録と、各ターゲットが公開した単一の応答のみを使用します。アクティブスキャン、エクスプロイト、ブルートフォースは攻撃対象領域の調査対象外であり、フラグで切り替えることもできません
• キー不要のコア機能を備えています。CTサブドメイン列挙、DNS、TLS、HTTP／技術情報、RDAP／WHOISはすべてAPIキーなしで動作し、Shodanはあくまで追加情報を提供します
• すべてのアウトバウンド接続にSSRFガードを適用します。接続前に、プライベート、ループバック、リンクローカル、クラウドメタデータ、予約済みのIPv4/IPv6範囲を拒否します（信頼できる内部評価では ATTACKSURFACE_ALLOW_PRIVATE_TARGETS によりオプトアウトできます）
• フォールバックチェーンを備えた複数ソースの集約を行います。CTによる検出はcrt.sh → Certspotter → TLS-SANの順にフォールバックし、登録情報はRDAP → WHOISの順にフォールバックします

エージェントに適した出力：

• すべての結果に出典情報が含まれます。出典ラベル（source: crt.sh | certspotter | tls-san、source: rdap | whois）とソースごとのステータスにより、エージェントは網羅性と信頼性を評価できます
• 部分的な失敗を適切に処理します。複数ターゲットおよび複数ソースを扱うツールは、呼び出し全体を失敗させる代わりに、項目／ソースごとの error フィールドと運用上の notes を返します。不正な形式の入力のみ例外を発生させます
• 判別可能で型付けされたコントラクトを備えています。型付きのエラー理由（source_unavailable、blocked_target、all_sources_failed）とユニオン出力（kind: domain | ip）により、呼び出し側は文字列の解析ではなくデータに基づいて処理を分岐できます
• シグナルを捏造しません。技術情報の検出結果には、その根拠となる証拠が含まれます。存在しないCT／DNS／RDAPフィールドは推測せず、不明として報告します

はじめに

以下をMCPクライアントの設定ファイルに追加します。attacksurface_lookup_hostを除くすべてのツールは設定なしで動作します。キー不要のコア機能は、空の環境でも起動します。

{
  "mcpServers": {
    "attack-surface-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/attack-surface-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、npxを使用します（Bunは不要です）。

{
  "mcpServers": {
    "attack-surface-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/attack-surface-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、Dockerを使用します。

{
  "mcpServers": {
    "attack-surface-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/attack-surface-mcp-server:latest"]
    }
  }
}

Shodanのホストインテリジェンス（attacksurface_lookup_host）を有効にするには、envブロックにSHODAN_API_KEYを追加します。

Streamable HTTPを使用するには、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0以上（またはNode.js v24+）。
• コアツールにAPIキーは不要です。オプション：attacksurface_lookup_host用のShodan APIキー、およびCTフォールバックのレート制限を緩和するためのCertspotter APIキー。

インストール

1. リポジトリをクローンします。

git clone https://github.com/cyanheads/attack-surface-mcp-server.git

2. ディレクトリに移動します。

cd attack-surface-mcp-server

3. 依存関係をインストールします。

bun install

4. 環境を設定します（オプション）。

cp .env.example .env
# edit .env only if you want Shodan, a Certspotter key, or non-default behavior

設定

すべての変数はオプションです。サーバーは空の環境でも起動し、キー不要のコア機能を提供します。

変数	説明	デフォルト
SHODAN_API_KEY	attacksurface_lookup_hostを有効にします。未設定の場合、このツールはsource_unavailableを返しますが、ほかのすべてのツールは引き続き動作します。	—
CERTSPOTTER_API_KEY	CTログのサブドメインフォールバックに対するCertspotterのレート制限を緩和します。未設定の場合、無料の未認証プランが使用されます（レート制限はありますが、動作します）。	—
ATTACKSURFACE_DEFAULT_RESOLVERS	attacksurface_resolve_dnsおよびstandard+のマップ／スナップショットの姿勢に使用する、カンマ区切りのパブリックDNSリゾルバーIPアドレスです。	8.8.8.8,1.1.1.1,9.9.9.9
ATTACKSURFACE_HTTP_USER_AGENT	attacksurface_probe_httpのデフォルトUser-Agentです（呼び出しごとに上書きできます）。	attack-surface-mcp-server/passive-recon (+https://github.com/cyanheads/attack-surface-mcp-server)
ATTACKSURFACE_MAX_SUBDOMAINS	マップ／スナップショットの名前解決上限です。列挙では、各ページの候補数も50件に制限されます。	200
ATTACKSURFACE_RDAP_BOOTSTRAP_URL	RDAPブートストラップのベースURLです。プライベートまたはミラーのRDAPを使用する場合は上書きします。	https://rdap.org
ATTACKSURFACE_ALLOW_PRIVATE_TARGETS	信頼できる内部評価で非パブリックなターゲット範囲を許可するには、trueに設定します。パブリックにデプロイする場合は、必ずfalseのままにしてください。	false
MCP_TRANSPORT_TYPE	トランスポート：stdioまたはhttp。	stdio
MCP_HTTP_PORT	HTTPサーバーのポートです。	3010
MCP_SESSION_MODE	HTTPセッションモード：stateless、stateful、またはauto。サーバーはstatelessを宣言しますが、ここで設定した値が優先されます。stdioでは無視されます。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、またはoauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
OTEL_ENABLED	OpenTelemetryの計装を有効にします。	false

オプションの上書き設定の全一覧は、.env.exampleを参照してください。

サーバーの実行

ローカル開発

• ビルドして実行します。

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行します。

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t attack-surface-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 attack-surface-mcp-server

Dockerfileでは、デフォルトでHTTPトランスポート、ステートレスセッションモードを使用し、ログを/var/log/attack-surface-mcp-serverに出力します。OpenTelemetryのピア依存関係はデフォルトでインストールされます。これらを省くには、--build-arg OTEL_ENABLED=falseを指定してビルドします。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp()のエントリーポイントです。ツール／リソースを登録し、6つのサービスを初期化します。
src/config	Zodを使用した、サーバー固有の環境変数の解析と検証です。
src/mcp-server/tools	ツール定義（*.tool.ts）です。
src/mcp-server/resources	リソース定義（*.resource.ts）です。
src/services	ドメインサービスとの統合（ct、dns、tls、http、registration、shodan）です。
src/utils	SSRFガードと入力検証です。
tests/	src/に対応する単体テストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャルールについては、CLAUDE.md/AGENTS.mdを参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内でtry/catchを使用しないでください
• リクエスト単位のログにはctx.logを、テナント単位のストレージにはctx.stateを使用してください
• 新しいツールとリソースは、src/mcp-server/*/definitions/index.tsのバレルを介して登録してください
• ユーザーが指定した宛先へのすべての外部接続では、接続前にSSRFガード（assertSafeDomain / assertSafeUrl / assertSafeResolverIp）を通してください
• 外部API呼び出しはラップしてください。生データを検証し、ドメイン型に正規化してから、出力スキーマを返してください。不足しているフィールドを捏造しないでください

貢献

課題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細はLICENSEを参照してください。