Sharkmcp

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

Wireshark/tsharkを統合することで、ネットワークパケットのキャプチャと分析機能を提供するモデルコンテキストプロトコル（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復号化：SSLキーログファイルをサポートし、HTTPSトラフィックを復号化します。
• 再利用可能な設定：キャプチャ/分析設定を保存して再利用できます。

⚠️ 重要提示

パケット情報は非常に多くなる可能性があります。会話のコンテキストが過負荷にならないように、スコープ付きの表示フィルターを使用することを確認してください。

📦 インストール

前提条件

システム要件

• 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

💻 使用例

利用可能なツール

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              # メインサーバーのセットアップ
│   ├── types.ts              # TypeScriptインターフェース
│   ├── utils.ts              # ユーティリティ関数
│   └── tools/                # 個々のツールの実装
│       ├── start-capture-session.ts
│       ├── stop-capture-session.ts
│       ├── analyze-pcap-file.ts
│       └── manage-config.ts
├── test/                     # テストファイル
│   └── integration.test.js   # 統合テスト
├── package.json
└── README.md

開発コマンド

# 自動リロード付きの開発モード
pnpm run dev

# 本番用にビルドする
pnpm run build

# テストを実行する
pnpm run test

# 型チェックを行う
pnpm run build

🔧 技術詳細

セキュリティに関する考慮事項

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

トラブルシューティング

一般的な問題

"tshark not found"：

• Wiresharkがインストールされ、tsharkがPATHに含まれていることを確認してください。
• インストールを確認するには、tshark -v を実行してください。

パケットキャプチャの権限が拒否された場合：

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

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

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

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

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

📄 ライセンス

MITライセンス

問題や提案

何か質問や提案があれば、自由にIssueを作成してください。