macOS Forensics Mcp Server

mac_forensics-mcp

macOS のデジタルフォレンジックおよびインシデント対応（DFIR）向けの MCP（Model Context Protocol）サーバーです。

概要

この MCP サーバーは、macOS のトリアージコレクションに対する構造化されたフォレンジック分析ツールを提供し、LLM を使用したインシデント調査時のコンテキスト負荷を軽減します。

主なメリット：

• 膨大なファイルを grep で直接検索する代わりに、構造化されたクエリを使用できます
• タイムスタンプを自動的に正規化します（Mac Absolute Time → UTC）
• セキュリティイベントの検出パターンをあらかじめ用意しています
• 複数のアーティファクトを相関させ、タイムラインを作成できます
• ページネーションにより、コンテキストのオーバーフローを防ぎます
• 利用可能なアーティファクトを把握するための検出機能を備えています

Unified Logs、FSEvents、Spotlight、Plist、SQLite データベース、拡張属性、システムログなどを対象とする23 個のツールを提供します。

インストール

cd /opt/macOS/mac_forensics-mcp

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

MCP クライアントへの追加

mac-forensics を、MCP クライアントの設定でローカルの 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	トリアージコレクションで利用可能なアーティファクトを検出します

Unified Logs

ツール	説明
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 ツールは、次のイベントの種類に対応しています。

イベントの種類	説明
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 ツールは、次のイベントの種類の詳細な調査に対応しています。

イベントの種類	説明
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/ のパスが使用されます。

環境変数	デフォルト	説明
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 調査に基づいて開発されました。主なフォレンジック機能は次のとおりです。

機能	ツール
ユーザーアカウントのフォレンジック	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 コミュニティ向けに作成されました。