Eventwhisper

🚀 EventWhisper — 一款Windows事件日誌MCP工具

EventWhisper 藉助MCP（模型上下文協議）服務器，為Windows .evtx 日誌提供了快速且可腳本化的訪問方式。它採用純Python編寫（使用 evtx 庫），而非PowerShell包裝器，並且不會在主機上執行命令，這使其在事件響應、數字取證和威脅狩獵等場景中更加安全。該工具專為事件響應（IR）、數字取證調查（DFIR）和威脅狩獵而設計，讓你無需整天查找事件ID。它在Windows系統上進行設計、開發和測試，可通過任何MCP客戶端使用。

項目狀態

✨ 主要特性

• 精準過濾：支持時間窗口、事件ID和大小寫不敏感的關鍵字（包含/排除）過濾。
• 字段投影：僅返回所需的字段路徑，大幅減少輸出量。
• 輸入標準化：接受靈活的輸入格式，即使類型或格式不完全正確也能正常工作。
• 支持MCP：可與Claude Desktop（以及其他MCP客戶端）集成。

🎥 演示

點擊查看演示

📦 安裝指南

環境要求（Windows）

EventWhisper可以使用Poetry進行安裝，無論你是在 Claude內部 還是 獨立運行 它。在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

🛠️ 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已註冊並“正在運行”。

當系統提示時，請允許該工具：

你可以嘗試以下第一個提示：

使用EventWhisper列出 C:\Windows\System32\winevt\Logs 目錄下的 .evtx 文件。

💻 使用示例

基礎用法

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

# 1) 從安全日誌中獲取第一個匹配的事件
print(get_events_from_evtx(r"C:\Windows\System32\winevt\Logs\Security.evtx", results_limit=1))

# 2) 按關鍵字過濾並投影字段
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) 時間範圍查詢（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 運行上述代碼。

📚 詳細文檔

開發相關

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 文件中，包括：

• RESULTS_LIMIT — 返回的最大事件數（大型語言模型有令牌/字符限制）。
• SCAN_LIMIT — 為確保響應速度，在大型日誌中掃描的最大事件數。

⚠️ 故障排除

• 大型日誌：結果受 RESULTS_LIMIT 限制，掃描範圍也會受到約束以確保響應速度。如果你的MCP客戶端未意識到結果已被限制，可以運行第二個更精確的查詢。
• “被阻止”的文件：如果你從互聯網下載了 .evtx 文件，請右鍵單擊 → 屬性 → 解除阻止。
• 路徑問題：在Python中，建議使用原始字符串表示Windows路徑，例如 r"C:\path\file.evtx"。
• README視頻：GitHub不支持渲染 <video> 標籤，請使用縮略圖 → MP4鏈接（參見演示部分）。

🗺️ 路線圖

• 針對非常大的 .evtx 文件實現更快的掃描功能。
• 對格式錯誤或損壞的EVTX文件進行更好的標準化處理。
• 提供便捷的實用工具（例如，快速概覽：計數、唯一事件ID、時間範圍）。
• 為大型數據集提供可選的分頁/多查詢策略。

📄 許可證

本項目採用 GPLv3 許可證進行分發。詳情請參閱 LICENSE 文件。