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 社區而構建。