Sharkmcp

SharkMCP - ネットワークパケット解析 MCP サーバー

Wireshark/tshark との統合を通じてネットワークパケットのキャプチャと解析機能を提供する Model Context Protocol (MCP) サーバーです。AI アシスタントがネットワークセキュリティ分析、トラブルシューティング、パケット検査を行えるように設計されています。

このサーバーは、エージェントにリクエストを送信するプログラムをデバッグさせ、パケットトラフィックを検証したい場面を想定して作られており、次のワークフローを可能にします：

• パケットの記録を開始する
• ツールを実行する、またはリクエストを送信する
• 記録を停止して結果を分析する

アーキテクチャ

SharkMCP はシンプルで、ローカル開発に焦点を当てたアーキテクチャを提供します：

┌─────────────────────────────────────────────────────────┐
│                    SharkMCP Server                      │
├─────────────────────────────────────────────────────────┤
│  MCP Protocol Layer                                     │
│  ├─ start_capture_session                               │
│  ├─ stop_capture_session                                │
│  ├─ analyze_pcap_file                                   │
│  └─ manage_config                                       │
├─────────────────────────────────────────────────────────┤
│  tshark Integration Layer                               │
│  ├─ Cross-platform executable detection                 │
│  ├─ Process management                                  │
│  └─ Output parsing (JSON/fields/text)                   │
├─────────────────────────────────────────────────────────┤
│  Host System Integration                                │
│  ├─ Local tshark installation                           │
│  ├─ Direct network interface access                     │
│  └─ Native file system operations                       │
└─────────────────────────────────────────────────────────┘

機能

• 非同期パケットキャプチャ：設定可能なフィルターとタイムアウトを使用してバックグラウンドキャプチャセッションを開始します。
• PCAP ファイル解析：既存のパケットキャプチャファイルを解析します
• 柔軟な出力形式：JSON、カスタムフィールド、または従来のテキスト出力
• SSL/TLS 復号：HTTPS トラフィックを復号するための SSL keylog ファイルをサポート
• 再利用可能な設定：キャプチャ/解析の設定を保存して再利用

/!\ パケット情報は非常に膨大になる可能性があります。会話のコンテキストを過負荷にしないよう、必ずスコープを絞った表示フィルターを使用してください。

前提条件

システム要件

• Wireshark/tshark：インストール済みでアクセス可能である必要があります
• Node.js：バージョン 18 以上
• pnpm：パッケージマネージャー（推奨）

Wireshark/tshark のインストール

macOS（Homebrew を使用）：

brew install wireshark

Ubuntu/Debian：

sudo apt update
sudo apt install tshark wireshark-common

Windows： wireshark.org からダウンロードしてください

インストール

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

git clone https://github.com/kriztalz/SharkMCP.git
cd SharkMCP

2. 依存関係をインストールします：

pnpm install

3. プロジェクトをビルドします：

pnpm run build

4. サーバーを実行します：

pnpm start

テスト

SharkMCP には、パケットキャプチャ機能を検証する包括的な統合テストが含まれています。

テストの実行

# Run all tests
pnpm test

設定

MCP クライアントのセットアップ

{
  "mcpServers": {
    "sharkmcp": {
      "command": "node",
      "args": ["/path/to/SharkMCP/dist/index.js"],
    }
  }
}

SSL/TLS 復号（オプション）

HTTPS トラフィックを復号するには、SSLKEYLOGFILE 環境変数をエクスポートします：

export SSLKEYLOGFILE=/path/to/sslkeylog.log

次に、SSL キーをこのファイルに記録するようにアプリケーションを設定します。多くのアプリケーションは、この環境変数が設定されていれば自動的にサポートします。

その後、stop_capture_session ツールでログファイルのパス名を MCP サーバーに渡します。

使用方法

利用可能なツール

1. start_capture_session：バックグラウンドでパケットキャプチャを開始します
2. stop_capture_session：キャプチャを停止して結果を分析します
3. analyze_pcap_file：既存の PCAP ファイルを分析します
4. manage_config：再利用可能な設定を保存/読み込みします

基本的な例

キャプチャセッションを開始する：

Interface: en0
Capture Filter: port 443
Timeout: 30 seconds

キャプチャしたトラフィックを分析する：

Display Filter: tls.handshake.type == 1
Output Format: json

設定を保存する：

{
  "name": "https-monitoring",
  "description": "Monitor HTTPS traffic",
  "captureFilter": "port 443",
  "displayFilter": "tls.handshake.type == 1",
  "outputFormat": "json",
  "timeout": 60,
  "interface": "en0"
}

開発

プロジェクト構成

SharkMCP/
├── src/
│   ├── index.ts              # Main server setup
│   ├── types.ts              # TypeScript interfaces
│   ├── utils.ts              # Utility functions
│   └── tools/                # Individual tool implementations
│       ├── start-capture-session.ts
│       ├── stop-capture-session.ts
│       ├── analyze-pcap-file.ts
│       └── manage-config.ts
├── test/                     # Test files
│   └── integration.test.js   # Integration tests
├── package.json
└── README.md

開発コマンド

# Development mode with auto-reload
pnpm run dev

# Build for production
pnpm run build

# Run tests
pnpm run test

# Type checking
pnpm run build

セキュリティ上の考慮事項

• ネットワーク権限：パケットキャプチャには昇格した権限が必要です
• ファイルアクセス：一時ファイルは /tmp/ に作成されます
• Docker セキュリティ：コンテナは非 root ユーザーとして実行されます
• SSL Keylog：機密性の高い SSL キーは安全に取り扱う必要があります

トラブルシューティング

よくある問題

「tshark not found」：

• Wireshark がインストールされ、tshark が PATH に含まれていることを確認してください
• 次のコマンドでインストールを確認してください：tshark -v

パケットキャプチャで permission denied が発生する：

• Linux の場合：ユーザーを wireshark グループに追加するか、sudo で実行してください
• macOS の場合：システム環境設定でターミナルにネットワークアクセスを許可してください
• Windows の場合：管理者として実行してください

パケットがキャプチャされない：

• ネットワークインターフェース名を確認してください（Linux では ip link、macOS では ifconfig）
• キャプチャフィルターの構文を確認してください
• インターフェース上にトラフィックが存在することを確認してください

コントリビューション（大歓迎です！）

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 既存のコードスタイルに従って変更を加えます
4. 新機能のテストを追加します
5. プルリクエストを送信します

ライセンス

MIT License

問題 / 提案

ご質問やご提案があれば、お気軽に issue を作成してください。