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 文件。