JinDaGe - mac_forensics-mcp MCP Details

article

README

🚀 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 种）

发现

| 工具 | 描述 | |------|-------------| | mac_list_artifacts | 发现分类收集中可用的工件 |

统一日志

| 工具 | 描述 | |------|-------------| | mac_unified_logs_search | 使用正则表达式、过滤器和时间范围搜索日志 | | mac_unified_logs_security_events | 获取预定义的安全事件（如用户创建、SSH 会话等） | | 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 | 获取文件的扩展属性（隔离、下载 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 工具支持以下事件类型： | 事件类型 | 描述 | |------------|-------------| | user_created | 用户账户创建 | | user_deleted | 用户账户删除 | | user_modified | 用户账户更改 | | ssh_session | SSH 连接 | | sudo_usage | Sudo 命令执行 | | auth_success | 成功认证 | | auth_failure | 认证失败 | | process_exec | 进程执行 | | gatekeeper | 守护程序/隔离事件 | | tcc_prompt | TCC 权限提示 | | login | 用户登录 | | logout | 用户注销 | | screen_lock | 屏幕锁定事件 | | screen_unlock | 屏幕解锁事件 | | remote_login | 远程登录服务 | | persistence | 持久化机制 |

调查事件类型

mac_investigate_event 工具支持对以下事件类型进行深度调查： | 事件类型 | 描述 | |------------|-------------| | user_deletion | 通过时间线和证据关联调查用户账户删除事件 | | user_creation | 调查用户账户创建事件 | | file_download | 调查文件下载事件（隔离、扩展属性、浏览器历史） | | ssh_session | 调查 SSH 会话活动 | | malware_execution | 调查潜在的恶意软件执行事件 | | privilege_escalation | 调查权限提升尝试事件 |

配置

外部工具路径

可以通过环境变量配置外部取证工具的路径。如果未设置，默认使用 /opt/macOS/ 路径。 | 环境变量 | 默认值 | 描述 | |---------------------|---------|-------------| | 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 服务器和工具定义
├── 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 调查开发的，具有以下关键取证能力： | 能力 | 工具 | |------------|-------| | 用户账户取证 | 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 |

参考资料

💻 使用示例

发现分类收集中的工件

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 社区而构建。