Mac Forensics MCP

🚀 mac_forensics-mcp

mac_forensics-mcp 是一款用于 macOS 数字取证与事件响应（DFIR）的 MCP（模型上下文协议）服务器。它为 macOS 分类收集提供了结构化的取证分析工具，可减少使用大语言模型（LLMs）进行事件调查时的上下文开销。

🚀 快速开始

此 MCP 服务器为 macOS 分类收集提供了结构化的取证分析工具，在使用大语言模型（LLMs）进行事件调查时，可有效减少上下文开销。

✨ 主要特性

• 结构化查询：无需通过原始的 grep 命令在大量文件中进行搜索。
• 自动时间戳归一化：将 Mac 绝对时间转换为 UTC 时间。
• 预构建的安全事件检测模式：可快速检测各类安全事件。
• 跨工件关联和时间线构建：帮助用户全面了解事件的发展过程。
• 分页功能：避免上下文溢出。
• 工件发现：清晰知晓可用的工件信息。

该项目提供了 23 种工具，涵盖统一日志、FSEvents、Spotlight、Plists、SQLite 数据库、扩展属性、系统日志等多个方面。

📦 安装指南

cd /opt/macOS/mac_forensics-mcp

# 创建虚拟环境并安装依赖
uv venv
uv pip install -e .

📚 详细文档

Claude 代码配置

选项 1：使用 claude mcp add（推荐）

# 添加到用户设置（在所有项目中可用）
claude mcp add mac-forensics -s user -- /opt/macOS/mac_forensics-mcp/.venv/bin/python -m mac_forensics_mcp.server

# 或者仅添加到当前项目
claude mcp add mac-forensics -- /opt/macOS/mac_forensics-mcp/.venv/bin/python -m mac_forensics_mcp.server

验证是否添加成功：

claude mcp list

移除配置：

claude mcp remove mac-forensics -s user

选项 2：手动 JSON 配置

将以下内容添加到 ~/.claude/settings.json（用户级）或 .claude/settings.json（项目级）：

{
  "mcpServers": {
    "mac-forensics": {
      "command": "/opt/macOS/mac_forensics-mcp/.venv/bin/python",
      "args": ["-m", "mac_forensics_mcp.server"],
      "env": {}
    }
  }
}

可用工具（23 种）

发现

统一日志

Plist 文件

数据库

用户分析

FSEvents

扩展属性与 Spotlight

系统日志

关联与调查

安全事件类型

mac_unified_logs_security_events 工具支持以下事件类型：

调查事件类型

mac_investigate_event 工具支持对以下事件类型进行深度调查：

配置

外部工具路径

可以通过环境变量配置外部取证工具的路径。如果未设置，默认使用 /opt/macOS/ 路径。

自定义路径示例：

{
  "mcpServers": {
    "mac-forensics": {
      "command": "/opt/macOS/mac_forensics-mcp/.venv/bin/python",
      "args": ["-m", "mac_forensics_mcp.server"],
      "env": {
        "MAC_FORENSICS_UNIFIEDLOG_ITERATOR_PATH": "/custom/path/unifiedlog_iterator",
        "MAC_FORENSICS_FSEPARSER_PATH": "/custom/path/FSEParser.py",
        "MAC_FORENSICS_SPOTLIGHT_PARSER_PATH": "/custom/path/spotlight_parser.py"
      }
    }
  }
}

依赖项

• Python 3.10+
• uv（用于虚拟环境和包管理）
• mcp >= 1.0.0
• biplist（可选，用于处理格式错误的 plist 文件）

外部工具（可选，用于解析原始工件）：

• unifiedlog_iterator - 用于解析 .logarchive 包
• FSEParser - 用于解析 FSEvents (.fseventsd)
• spotlight_parser - 用于解析 Spotlight 索引

架构

mac_forensics_mcp/
├── server.py                # MCP 服务器和工具定义
├── config.py                # 可配置的外部工具路径
├── parsers/
│   ├── plist_parser.py      # Plist 文件解析
│   ├── unified_log_parser.py # 统一日志分析
│   ├── sqlite_parser.py     # SQLite 数据库（KnowledgeC、Safari、TCC）
│   ├── fsevents_parser.py   # FSEvents 解析
│   ├── spotlight_parser.py  # Spotlight 索引解析
│   ├── xattr_parser.py      # 扩展属性解析
│   └── fsck_apfs_parser.py  # fsck_apfs.log 解析
├── correlation/
│   ├── timeline_builder.py  # 跨工件时间线关联
│   └── event_investigator.py # 特定事件调查
└── utils/
    ├── timestamps.py        # Mac/WebKit/HFS 时间戳转换
    └── discovery.py         # 工件发现

取证价值

此 MCP 服务器是基于实际的 macOS DFIR 调查开发的，具有以下关键取证能力：

参考资料

• SANS FOR518 海报
• mac4n6 工件电子表格
• SUMURI Mac 取证最佳实践指南 2025
• Google Cloud - 审查 macOS 统一日志

💻 使用示例

发现分类收集中的工件

mac_list_artifacts(artifacts_dir="/path/to/triage")

查找用户删除事件

mac_unified_logs_security_events(
    log_path="/path/to/unified_logs.csv",
    event_type="user_deleted"
)

深度调查用户删除事件

mac_investigate_event(
    artifacts_dir="/path/to/triage",
    event_type="user_deletion",
    target="username"
)

获取 Safari 搜索历史

mac_safari_searches(
    db_path="/path/to/History.db",
    query_filter="delete"
)

从 plist 文件中读取已删除用户

mac_plist_read(
    plist_path="/path/to/com.apple.preferences.accounts.plist",
    key_path="deletedUsers"
)

查找外部设备活动

mac_parse_fsck_apfs_log(
    log_path="/path/to/fsck_apfs.log",
    external_only=True
)

搜索特定卷

mac_parse_fsck_apfs_log(
    log_path="/path/to/fsck_apfs.log",
    volume_filter="suspicious_volume"
)

构建用户活动时间线

mac_get_user_timeline(
    artifacts_dir="/path/to/triage",
    username="username"
)

搜索 FSEvents 中的文件活动

mac_fsevents_search(
    fseventsd_path="/path/to/.fseventsd",
    path_filter="/Users/username",
    event_types=["created", "deleted"]
)

🤝 贡献

该项目基于 macOS DFIR 调查的经验教训开发，欢迎贡献更多工具和事件模式。

👨‍💻 作者

xtk

为 DFIR 社区而构建。