macOS Forensics Mcp Server

mac_forensics-mcp

用于 macOS 数字取证与事件响应（DFIR）的 MCP（模型上下文协议）服务。

概览

此 MCP 服务为 macOS 快速筛查采集数据提供结构化取证分析工具，减少使用大模型调查事件时的上下文开销。

主要优势：

• 使用结构化查询，而非在海量文件中直接执行 grep
• 自动规范化时间戳（Mac 绝对时间 → UTC）
• 预置安全事件检测模式
• 跨工件关联并构建时间线
• 分页以避免上下文溢出
• 发现工件以了解可用内容

23 个工具，涵盖：统一日志、FSEvents、Spotlight、Plist、SQLite 数据库、扩展属性、系统日志等。

安装

cd /opt/macOS/mac_forensics-mcp

# Create virtual environment and install dependencies
uv venv
uv pip install --python .venv/bin/python3 -e .

添加到 MCP 客户端

在 MCP 客户端的设置中，将 mac-forensics 注册为本地 stdio 服务。配置格式和位置因客户端而异。对于支持 mcpServers JSON 的客户端，请使用：

{
  "mcpServers": {
    "mac-forensics": {
      "command": "/absolute/path/to/mac_forensics-mcp/.venv/bin/python3",
      "args": ["-m", "mac_forensics_mcp.server"]
    }
  }
}

将命令替换为虚拟环境中 Python 解释器的绝对路径。如果客户端使用不同的配置格式，请通过其 MCP 服务设置输入相同的命令和参数。使用客户端的 MCP 服务列表确认连接成功。要移除此服务，请从客户端设置中删除对应条目。

可用工具（23）

发现

工具	描述
mac_list_artifacts	发现快速筛查采集数据中可用的工件

统一日志

工具	描述
mac_unified_logs_search	使用正则表达式、筛选条件和时间范围搜索日志
mac_unified_logs_security_events	获取预定义的安全事件（user_created、ssh_session 等）
mac_unified_logs_stats	获取日志统计信息：时间范围、主要子系统

Plist 文件

工具	描述
mac_plist_read	读取并解析 Plist，可选提取键路径
mac_plist_search	搜索匹配模式的键
mac_plist_timestamps	提取所有时间戳值并转换为 UTC

数据库

工具	描述
mac_knowledgec_app_usage	从 KnowledgeC.db 获取应用使用情况
mac_safari_history	Safari 浏览历史
mac_safari_searches	从 Safari 提取搜索查询
mac_tcc_permissions	TCC 权限（摄像头、麦克风、屏幕录制）
mac_quarantine_events	文件下载历史

用户分析

工具	描述
mac_get_user_accounts	列出用户，包括已删除的账户
mac_get_user_timeline	为指定用户账户构建时间线

FSEvents

工具	描述
mac_fsevents_search	搜索文件系统事件（创建、删除、修改、重命名）
mac_fsevents_stats	获取 FSEvents 统计信息

扩展属性与 Spotlight

工具	描述
mac_get_extended_attributes	获取文件的 xattr（隔离信息、下载 URL 等）
mac_spotlight_search	在 Spotlight 索引中搜索文件元数据
mac_spotlight_stats	获取 Spotlight 索引统计信息

系统日志

工具	描述
mac_parse_fsck_apfs_log	解析 fsck_apfs.log，以查找宗卷创建、外部设备和反取证信息
mac_fsck_apfs_stats	获取 fsck_apfs.log 统计信息：设备、宗卷、时间范围

关联与调查

工具	描述
mac_build_timeline	从多个工件构建统一时间线
mac_investigate_event	通过证据关联进行深入调查

安全事件类型

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

Event Type	Description
user_created	用户账户创建
user_deleted	用户账户删除
user_modified	用户账户更改
ssh_session	SSH 连接
sudo_usage	Sudo 命令执行
auth_success	身份验证成功
auth_failure	身份验证失败
process_exec	进程执行
gatekeeper	Gatekeeper／隔离事件
tcc_prompt	TCC 权限提示
login	用户登录
logout	用户注销
screen_lock	屏幕锁定事件
screen_unlock	屏幕解锁事件
remote_login	远程登录服务
persistence	持久化机制

调查事件类型

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

Event Type	Description
user_deletion	调查用户账户删除，并关联时间线和证据
user_creation	调查用户账户创建
file_download	调查文件下载（隔离信息、xattr、浏览器历史记录）
ssh_session	调查 SSH 会话活动
malware_execution	调查潜在恶意软件执行
privilege_escalation	调查权限提升尝试

使用示例

在分诊中发现工件

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"]
)

配置

外部工具路径

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

Environment Variable	Default	Description
MAC_FORENSICS_UNIFIEDLOG_ITERATOR_PATH	/opt/macOS/unifiedlog_iterator	unifiedlog_iterator 二进制文件的路径
MAC_FORENSICS_FSEPARSER_PATH	/opt/macOS/FSEventsParser/FSEParser_V4.1.py	FSEParser 脚本的路径
MAC_FORENSICS_SPOTLIGHT_PARSER_PATH	/opt/macOS/spotlight_parser/spotlight_parser.py	spotlight_parser 脚本的路径

自定义路径示例：

{
  "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 server and tool definitions
├── config.py                # Configurable external tool paths
├── parsers/
│   ├── plist_parser.py      # Plist file parsing
│   ├── unified_log_parser.py # Unified log analysis
│   ├── sqlite_parser.py     # SQLite databases (KnowledgeC, Safari, TCC)
│   ├── fsevents_parser.py   # FSEvents parsing
│   ├── spotlight_parser.py  # Spotlight index parsing
│   ├── xattr_parser.py      # Extended attributes parsing
│   └── fsck_apfs_parser.py  # fsck_apfs.log parsing
├── correlation/
│   ├── timeline_builder.py  # Cross-artifact timeline correlation
│   └── event_investigator.py # Event-specific investigation
└── utils/
    ├── timestamps.py        # Mac/WebKit/HFS timestamp conversion
    └── discovery.py         # Artifact discovery

取证价值

此 MCP 服务基于真实的 macOS DFIR 调查开发。主要取证能力：

Capability	Tools
用户账户取证	mac_get_user_accounts、mac_get_user_timeline、mac_investigate_event
文件活动跟踪	mac_fsevents_search、mac_spotlight_search
下载分析	mac_quarantine_events、mac_get_extended_attributes
安全事件检测	mac_unified_logs_security_events
外部设备检测	mac_parse_fsck_apfs_log
跨工件关联	mac_build_timeline、mac_investigate_event

参考资料

• SANS FOR518 海报
• mac4n6 工件电子表格
• SUMURI Mac 取证最佳实践指南 2025
• Google Cloud - 查看 macOS Unified Logs

贡献

基于 macOS DFIR 调查中积累的经验。欢迎补充工具和事件模式。

---

作者

xtk

为 DFIR 社区打造。