🚀 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\\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不支持渲染
标签，请使用缩略图 → MP4链接（参见演示部分）。
🗺️ 路线图
- 针对非常大的
.evtx文件实现更快的扫描功能。 - 对格式错误或损坏的EVTX文件进行更好的标准化处理。
- 提供便捷的实用工具（例如，快速概览：计数、唯一事件ID、时间范围）。
- 为大型数据集提供可选的分页/多查询策略。
📄 许可证
本项目采用 GPLv3 许可证进行分发。详情请参阅 LICENSE 文件。