pentest-mcp-server

---

許可された用途に限ります。 このサーバーは、自らが所有するシステム、またはテストするための明示的な書面による許可を得たシステムを対象に作業するペネトレーションテスター、レッドチーム、CTF 参加者、セキュリティ研究者、学生向けに設計されています。テストが合法であり、適切な範囲内で行われることを確認する責任は、すべてユーザーにあります。コンピューターシステムへの不正アクセスは違法です。このサーバーがユーザーに代わって許可の有無を強制したり、確認したりすることはできません。

両方の立場を想定した設計です。 あらゆる攻撃手法には、検知指標と緩和策が対になっています。ブルーチーム、開発者、検知範囲の構築に携わる方にとっても、この手法や ATT&CK データはレッドチームのワークフローと同様に役立ちます。

---

概要

MITRE ATT&CK、OWASP Testing Guide、注釈付きペイロードテンプレートに基づく、許可を得たペネトレーションテスト、CTF、セキュリティ研究向けのオフライン手法エンジンです。段階的なテスト計画の作成、対象への手法のマッピング、HTTP レスポンスの漏えい分析、ペイロードの生成やエンコードを、それぞれ検知と緩和策の情報と合わせて実行できます。

ツール

ツール	説明
pentest_get_guide	選択した攻撃ベクトルに関する、手順を追った認可済みテスト手法のプレイブックです。フェーズで絞り込みでき、各手法の検出方法と緩和策も含まれます。
pentest_analyze_response	認可済みのプロービングで取得した未加工の HTTP レスポンスヘッダー／本文を分析し、情報漏えい、フィンガープリンティング、設定ミスを検出します。
pentest_lookup_technique	ID またはキーワードから MITRE ATT&CK の手法を検索し、検出データ、緩和策、手順の例を取得します。
pentest_lookup_group	ID または名前から MITRE ATT&CK の脅威グループまたはソフトウェアの項目を検索し、別名と手法の使用状況を取得します。
pentest_map_techniques	対象のプロファイル（スタック、サービス、認証タイプ、OS）に照らして、ATT&CK の手法と OWASP のテストケースをランキングします。
pentest_generate_payloads	脆弱性のカテゴリとインジェクションのコンテキストに応じた注釈付きペイロードテンプレートを生成します。オプションで WAF 回避のバリエーションやエンコードも指定できます。
pentest_encode_payload	デコード経路を追跡しながら、ペイロード文字列に指定された順序でエンコードを適用します。

機能リファレンス

pentest_get_guide _tool

• vector：auth_bypass、idor、ssrf、xss、sqli、xxe、path_traversal、cors、csrf、open_redirect、deserialization、race_condition、ssti、command_injection、jwt_attack のいずれか。phase：all（デフォルト）、recon、enumeration、exploitation、post_exploitation のいずれか
• プレイブックの手法には detection と mitigation が含まれ、owasp_references、attack_technique_ids、コンテキストに基づく nextToolSuggestions も含まれます
• オプションの target_context（stack、waf、recon_notes）でプレイブックを絞り込みます

---

pentest_analyze_response _tool

• response_headers（20,000 文字以下）、response_body（10,000 文字以下）、またはその両方を指定します。オプションで status_code（100～599）と context（2,000 文字以下）も指定できます。両方のレスポンスフィールドが未指定の場合は no_input を返します
• 検出結果には category、severity（info／low／medium／high）、detection、remediation が含まれ、重要度の降順で並べられます
• fingerprints（server_software、framework、language、database、cloud_provider、other）と nextToolSuggestions により、後続の呼び出しをサポートします

---

pentest_lookup_technique _tool

• ATT&CK ID（T1190、T1059.001）またはキーワードを指定します。include_subtechniques のデフォルトは true です
• 戦術、プラットフォーム、説明、detection（summary、data_sources、indicators）、緩和策、手順の例、attack_version を返します
• ID またはキーワードに該当するものがない場合は no_match を返します

---

pentest_lookup_group _tool

• ATT&CK グループ ID（G0007）、ソフトウェア ID（S0002）、または名前／キーワードを指定します。該当するものがない場合は no_match を返します
• type は group と software を区別します。結果には aliases、description（800 文字以下）、attack_version が含まれます
• techniques_used は、手順のコンテキストと pentest_lookup_technique 用の technique_id を含む最大 20 件の手法を返します

---

pentest_map_techniques _tool

• stack、services、auth_type（jwt／session_cookie／api_key／oauth2／basic_auth／ntlm／kerberos／none／unknown）、os（linux／windows／macos／unknown）のうち、少なくとも 1 つを指定します。指定がない場合は no_profile を返します
• ranked_techniques には relevance_score、relevance_rationale、detection_opportunity、mitigation_summary、オプションの pentest_guide_vector が含まれます。owasp_test_cases は最大 10 件のケースを返します
• limit は手法数を 1～50 件に制限します（デフォルトは 15 件）。追加情報（truncated、shown、cap）で上限を示します

---

pentest_generate_payloads _tool

• category：xss、sqli、ssrf、xxe、path_traversal、ssti、command_injection、open_redirect、csrf、deserialization、jwt、ldap_injection、nosql_injection、http_header のいずれか。injection_context：html_attribute、html_body、js_string、js_template、js_script_block、url_parameter、url_path、sql_where、sql_integer、xml_element、xml_attribute、http_header、json_value、cookie_value、file_name、generic のいずれか
• count でテンプレート数を1～20件に制限します（デフォルトは5件）。各テンプレートには detection_signature と mitigation が含まれます。encoding を指定すると、すべてのテンプレートに適用されます
• waf_profile：cloudflare、aws_waf、modsecurity_crs、imperva、akamai、f5_bigip_asm、nginx_modsecurity、fortinet_fortiwaf、none（デフォルト）、unknown のいずれか。none 以外のプロファイルでは waf_bypass_note が追加されます

---

pentest_encode_payload _tool

• payload は最大10,000文字を受け付けます。chain では、url、double_url、html_entity、unicode、hex、base64、js_escape、null_byte、mixed_case、comment_break から1～6段階の変換を左から右に適用します
• intermediate_steps と detection_note を返します。explain（デフォルトは true）を指定すると、decode_path と bypass_rationale が追加されます
• 変換に失敗した場合は encoding_error を返します

---

機能

@cyanheads/mcp-ts-core を基盤とし、stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログを提供します。

手法に特化した機能：

• 実行時は完全にオフラインです。外部 API 呼び出しや認証情報は不要で、データはすべて起動時に読み込まれ、リクエスト処理中の I/O は発生しません
• MITRE ATT&CK Enterprise は scripts/refresh-attack.ts を使ってビルド時に組み込まれ、ID／キーワードでメモリ内にインデックス化されます。データファイルがない場合は、対処方法を示すエラーメッセージとともに即座に失敗します
• OWASP Testing Guide の手法とペイロードテンプレートライブラリは、ベクター／カテゴリごとに整理された TypeScript モジュールとして構成されています
• WAF バイパスのバリエーションは、WAF 製品と攻撃ベクターごとに分類され、公開されている調査を参照しています
• すべてのツールには readOnlyHint: true と openWorldHint: false が注釈されています。範囲が限定された組み込みデータセットから、決定論的な出力を返します

エージェント向けの出力：

• すべてのガイド／ペイロード／エンコーディングの応答で、content[] の先頭行に authorized_use_reminder を表示します。クライアントがどの出力面から転送しても、一貫した説明が維持されます
• 手法とペイロードには検出および緩和のコンテキストが必要です。調査結果には detection と remediation が必要です
• ATT&CK に基づくすべての応答で attack_version を返すため、呼び出し側はデータのバージョンを考慮できます
• nextToolSuggestions には現在のコンテキストに基づく引数があらかじめ設定されており、エージェントの計画にかかる手間を減らします

---

ビルド時のデータ取得

サーバーは、ワンタイムスクリプトで取得した MITRE ATT&CK Enterprise データ（約20 MBの JSON）を、gitignore 対象のパスに組み込みます。セルフホストする場合や Docker イメージをビルドする場合は、サーバーを起動する前にこの手順を実行する必要があります。

bun run scripts/refresh-attack.ts

この処理では、MITRE GitHub のリリースエンドポイントから最新の ATT&CK Enterprise JSON をダウンロードし、src/data/attack/enterprise.json（gitignore 対象）に書き込みます。また、src/data/attack/version.ts を Enterprise v16.1 のようなバージョン文字列で更新します。バージョンファイルはコミットされますが、JSON はサイズが大きく git 履歴に適さないためコミットされません。

Dockerfile がこの手順を自動的に処理します。ビルドステージで TypeScript のコンパイル前に scripts/refresh-attack.ts を実行するため、docker build によって自己完結型のイメージが生成されます。

リポジトリをクローンした後、この手順を省略すると、attack-service は起動時に即座に失敗し、scripts/refresh-attack.ts を示す対処方法付きのエラーメッセージを表示します。

最新の ATT&CK バージョンを取得するため、四半期ごと（またはリリースごと）にこのスクリプトを実行してください。

---

はじめに

公開ホストインスタンス

https://pentest.caseyjhand.com/mcp で公開インスタンスを利用できます。インストールは不要です。Streamable HTTP を介して、任意の MCP クライアントから接続してください。

{
  "mcpServers": {
    "pentest-mcp-server": {
      "type": "streamable-http",
      "url": "https://pentest.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。

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

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

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

または Docker を使用します。

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

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+）。
• ATT&CK データをシードします。クローン後に一度 bun run scripts/refresh-attack.ts を実行してください（Docker ビルドでは自動的に処理されます）。

インストール

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

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

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

cd pentest-mcp-server

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

bun install

4. ATT&CK データをシードします。

bun run scripts/refresh-attack.ts

5. 環境を設定します。

cp .env.example .env
# edit .env if needed — no required vars beyond transport defaults

---

設定

API キーは不要です。サーバーは実行時に完全にオフラインで動作します。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル：debug、info、notice、warning、error。	info
PENTEST_ENABLE_PAYLOAD_GENERATION	pentest_generate_payloads と pentest_encode_payload を有効にします。false の場合、クライアントから非表示になります。	true
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<project-root>/logs
OTEL_ENABLED	OpenTelemetry インストルメンテーション（スパン、メトリクス、完了ログ）を有効にします。	false
LOG_TOOL_FAILURE_PAYLOADS	失敗した呼び出しの引数と結果を記録します（キー名はマスキングされますが、自由形式の値にはシークレットが含まれる場合があります）。	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP ログのエクスポート先。	—

オプションのオーバーライドの全一覧については、.env.example を参照してください。

PENTEST_ENABLE_PAYLOAD_GENERATION=false にすると、2 つのペイロードツールは MCP の検出結果に表示されず、呼び出しもできません。

---

サーバーの実行

ローカル開発

• ビルドして実行：

  # Seed ATT&CK data (first time, or to update)
  bun run scripts/refresh-attack.ts
  
  # Build
  bun run rebuild
  
  # Run
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

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

Docker

# Build — ATT&CK data is fetched during the build stage
docker build -t pentest-mcp-server .
docker run --rm -p 3010:3010 pentest-mcp-server

Dockerfile は、HTTP トランスポート、ステートレスなセッションモード、および /var/log/pentest-mcp-server へのログ出力をデフォルトに設定しています。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。ATT&CK データの更新はビルドステージで自動的に実行されます。

---

プロジェクト構成

ディレクトリ／ファイル	目的
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、サービスを初期化します。
src/services/attack/	MITRE ATT&CK サービスです。起動時に埋め込みのエンタープライズ JSON を読み込み、インデックスを作成します。
src/services/methodology/	OWASP Testing Guide の方法論サービスです。pentest_get_guide 用のベクトルブランチを提供します。
src/services/payload/	ペイロードテンプレートサービスです。カテゴリとインジェクションコンテキストをキーとして使用します。
src/services/encoding/	エンコーディングチェーンの実行機能です。純粋な TypeScript 変換を行います。
src/services/response-analysis/	情報漏えいとフィンガープリンティング検出のパターンライブラリです。
src/mcp-server/tools/definitions/	ツール定義（*.tool.ts）です。ツールごとに 1 ファイルを使用します。
src/data/attack/	enterprise.json（gitignore 対象。scripts/refresh-attack.ts で取得）と、コミット済みの version.ts が含まれます。
src/data/owasp/	TypeScript モジュールとしてまとめられた OWASP TG v4.2 の方法論コンテンツです。
src/data/payloads/	脆弱性カテゴリ別に注釈を付けたペイロードテンプレートです。
src/data/waf-bypass/	製品と攻撃ベクトルをキーとする WAF バイパスのバリエーションです。
src/data/encodings/	エンコーディング変換関数です。
src/data/patterns/	レスポンスの漏えい検出に使用する正規表現パターンとメタデータです。
scripts/refresh-attack.ts	ATT&CK Enterprise JSON をダウンロードし、バージョン文字列を更新します。クローン後に一度実行し、その後は四半期ごとに実行してください。
scripts/copy-attack.ts	コンパイル後、シード済みの ATT&CK データセットを dist/ にコピーします。
tests/	src/ の構成を反映した単体テストと統合テストです。
docs/design.md	ツールのインターフェース、データ戦略、アーキテクチャ上の決定事項を記載した設計ドキュメントです。

---

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。捕捉するのは、自分が所有する運用上の失敗を、宣言済みの ctx.fail コントラクトに変換する場合に限ります
• リクエストスコープのロギングには ctx.log を使用し、リクエスト処理はステートレスかつ決定的に保ちます
• 新しいツールは src/mcp-server/tools/index.ts のバレル経由で登録します
• 外部ソースとの境界では、生データを検証し、ドメイン型に正規化してから出力スキーマを返します。不足しているフィールドを決して捏造しないでください
• 方法論またはペイロードのコンテンツを生成するすべてのツールでは、authorized_use_reminder が必須の出力フィールドです。format() 内で、すべての content[] レスポンスの先頭行として出力してください
• テクニックとペイロードでは検出と緩和のコンテキストを必須にし、レスポンスの検出結果では detection と remediation を必須にします

---

コントリビューション

イシューをお待ちしています。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

---

ライセンス

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