Eventwhisper

🚀 EventWhisper — A Windows Event Log MCP

EventWhisper は、MCP（Model Context Protocol）サーバーを介して、Windows の .evtx ログに対する高速かつスクリプト可能なアクセスを提供します。これは純粋な Python（evtx ライブラリを使用）で構築されており、PowerShell のラッパーではなく、ホスト上でコマンドを実行しません。このため、インシデントレスポンス、デジタルフォレンジックス、脅威ハンティングにおいてより安全に使用できます。

サーバーは2つの主要なツールを提供します：

• 任意のディレクトリ内の EVTX ファイルを（オプションで再帰的に）一覧表示します。
• イベントをフィルタリングして、特定のレコードを直接検索します。

このツールは、IR/DFIR とハンティングに特化して構築されているため、一日中イベント ID を調べる必要がありません。Windows 上で Claude を使用して設計、開発、テストされており、任意の MCP クライアントから使用できます。

🚀 クイックスタート

EventWhisper は、Claude 内でまたはスタンドアロンで実行する場合でも、Poetry を使用してセットアップできます。Windows では、Poetry が PATH に含まれていることを確認してください。

✨ 主な機能

• ターゲットフィルタリング：時間範囲、イベント ID、大文字小文字を区別しないキーワード（含む/除外）
• フィールド投影：必要なドット区切りのパスのみを返す（出力を大幅に削減）
• 入力正規化：柔軟な入力形式を受け入れるため、型や形式が完全でなくても動作する
• MCP 対応：Claude Desktop（および他の MCP クライアント）に接続可能

📦 インストール

必要条件 (Windows)

EventWhisper は、Poetry を使用してセットアップできます。Windows では、Poetry が PATH に含まれていることを確認してください。

Poetry のインストール (PowerShell):

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Poetry を PATH に追加 (ユーザーインストール):

C:\Users\<YourUser>\AppData\Roaming\Python\Scripts

確認:

poetry --version

クローンとインストール

git clone https://github.com/hexastrike/eventwhisper
cd eventwhisper
poetry install

MCP サーバーの実行

poetry run python -m eventwhisper.mcp.server
# (または) 依存関係がグローバルにインストールされている場合は通常の Python:
python -m eventwhisper.mcp.server

💻 使用例

基本的な使用法

# example.py
from __future__ import annotations
from datetime import datetime, timezone
from eventwhisper.evtxio.evtxio import get_events_from_evtx

# 1) First matching event from Security log
print(get_events_from_evtx(r"C:\Windows\System32\winevt\Logs\Security.evtx", results_limit=1))

# 2) Filter by keywords and project fields
events = get_events_from_evtx(
    r"C:\Windows\System32\winevt\Logs\Security.evtx",
    contains=["powershell", "Invoke-"],
    fields=["Event.System.EventID", "Event.EventData.Image", "Event.EventData.CommandLine"],
    results_limit=5,
)
for e in events:
    print(e)

# 3) Time-bounded query (UTC)
start = datetime(2025, 1, 1, tzinfo=timezone.utc)
end = datetime(2025, 1, 31, 23, 59, 59, tzinfo=timezone.utc)
print(len(get_events_from_evtx(r"C:\Windows\System32\winevt\Logs\Security.evtx", start=start, end=end)))

これを poetry run python example.py で実行します。

📚 ドキュメント

Claude MCP 設定

Claude Desktop の MCP 設定（例: %AppData%\Claude\claude_desktop_config.json）に以下を追加します：

{
  "mcpServers": {
    "EventWhisper": {
      "type": "stdio",
      "command": "poetry",
      "args": [
        "-C",
        "C:\\Path\\To\\eventwhisper",
        "run",
        "python",
        "-m",
        "eventwhisper.mcp.server"
      ],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

設定 → 開発者を開いて、EventWhisper が登録されて「実行中」であることを確認します。

要求されたら、ツールを許可します：

最初のプロンプトを試してみましょう：

Use EventWhisper to list .evtx files in C:\Windows\System32\winevt\Logs.

開発

EventWhisper は、シンプルで保守しやすいように作成されています。テストには pytest を、リント/フォーマットには ruff を使用しています。すべてをローカルで（または pre-commit を介して）実行できます：

poetry install
poetry run ruff format .
poetry run ruff check . --fix
poetry run pytest --cov=eventwhisper --cov-report=term-missing
# すべてのファイルで pre-commit:
poetry run pre-commit run --all-files
# プッシュ前のフック（完全なテスト + カバレッジ）:
poetry run pre-commit run --hook-stage push --all-files

プルリクエストを作成する際は、すべてのテストが通過し、カバレッジの閾値を満たしていることを確認してください。新しいユーティリティや機能には、明確なテストを含め、PEP 8 に従ってください。テストは tests/ ディレクトリに配置されます。

コアレイアウトと API

主なロジックは eventwhisper/evtxio/evtxio.py にあり、EVTX の反復処理、フィルタリング、投影を行います。

コアサーバー関数は get_events_from_evtx()（イテレータ iter_events_from_evtx() のラッパー）です：

def get_events_from_evtx(
    provider: str | Path,
    start: datetime | str | None = None,
    end: datetime | str | None = None,
    results_limit: int | str | None = RESULTS_LIMIT,
    event_ids: int | str | Sequence[int] | Sequence[str] | None = None,
    contains: str | Sequence[str] | None = None,
    not_contains: str | Sequence[str] | None = None,
    fields: str | Sequence[str] | None = None,
) -> list[str]:

定数は eventwhisper/utils/config.py にあり、以下の2つが含まれます：

• RESULTS_LIMIT — 返されるイベントの最大数（LLM にはトークン/文字数の制限があります）。
• SCAN_LIMIT — 巨大なログでも応答を高速に保つためにスキャンする最大イベント数。

🔧 技術詳細

このセクションでは、EventWhisper の技術的な詳細について説明します。

• コアロジックは eventwhisper/evtxio/evtxio.py ファイルにあり、EVTX の反復処理、フィルタリング、投影を行います。
• コアサーバー関数 get_events_from_evtx() は、イテレータ iter_events_from_evtx() をラップしています。
• 定数は eventwhisper/utils/config.py ファイルに定義されており、RESULTS_LIMIT と SCAN_LIMIT が含まれます。

📄 ライセンス

このプロジェクトは GPLv3 の下で配布されています。詳細は LICENSE を参照してください。

⚠️ 重要提示

• 大きなログ: 結果は RESULTS_LIMIT で制限され、スキャンも制限されているため、応答が高速になります。MCP クライアントが結果が制限されていることを認識しない場合は、2回目の狭い範囲のクエリを実行してください。
• 「ブロックされた」ファイル: インターネットから .evtx ファイルをダウンロードした場合は、右クリック → プロパティ → ブロック解除 を行ってください。
• パス: Python では、Windows パスには生文字列（raw strings）を使用することをお勧めします。例: r"C:\path\file.evtx"。
• README ビデオ: GitHub は <video> をレンダリングしません。サムネイル → MP4 リンクを使用してください（デモセクションを参照）。

ロードマップ

• 非常に大きな .evtx ファイルの高速スキャン
• 不正な形式または破損した EVTX のより良い正規化
• 便利なユーティリティ（例: クイック概要: カウント、一意のイベント ID、時間範囲）
• 巨大なデータセットに対するオプションのページング/マルチクエリ戦略