<img src="mac_icon.png" width="150" alt="macOS Forensics MCP">

# mac_forensics-mcp

MCP (Model Context Protocol) server for macOS Digital Forensics and Incident Response (DFIR).

## Overview

This MCP server provides structured forensic analysis tools for macOS triage collections, reducing context overhead when investigating incidents with LLMs.

**Key Benefits:**
- Structured queries instead of raw grep through massive files
- Automatic timestamp normalization (Mac Absolute Time → UTC)
- Pre-built security event detection patterns
- Cross-artifact correlation and timeline building
- Pagination to avoid context overflow
- Artifact discovery to know what's available

**23 tools** covering: Unified Logs, FSEvents, Spotlight, Plists, SQLite databases, Extended Attributes, System Logs, and more.

## Installation

```bash
cd /opt/macOS/mac_forensics-mcp

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

## Add to an MCP client

Register `mac-forensics` as a local **stdio** server in your MCP client's settings. Configuration format and location depend on the client. For clients that accept `mcpServers` JSON, use:

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

Replace the command with the absolute path to the virtual environment's Python interpreter. If your client uses a different configuration format, enter the same command and arguments through its MCP server settings. Use the client's MCP server list to confirm it connects. To remove the server, delete its entry from the client settings.

## Available Tools (23)

### Discovery

| Tool | Description |
|------|-------------|
| `mac_list_artifacts` | Discover available artifacts in a triage collection |

### Unified Logs

| Tool | Description |
|------|-------------|
| `mac_unified_logs_search` | Search logs with regex, filters, time range |
| `mac_unified_logs_security_events` | Get pre-defined security events (user_created, ssh_session, etc.) |
| `mac_unified_logs_stats` | Get log statistics: time range, top subsystems |

### Plist Files

| Tool | Description |
|------|-------------|
| `mac_plist_read` | Read and parse plist, optionally extract key path |
| `mac_plist_search` | Search for keys matching pattern |
| `mac_plist_timestamps` | Extract all timestamp values with UTC conversion |

### Databases

| Tool | Description |
|------|-------------|
| `mac_knowledgec_app_usage` | App usage from KnowledgeC.db |
| `mac_safari_history` | Safari browsing history |
| `mac_safari_searches` | Extract search queries from Safari |
| `mac_tcc_permissions` | TCC permissions (camera, mic, screen recording) |
| `mac_quarantine_events` | File download history |

### User Analysis

| Tool | Description |
|------|-------------|
| `mac_get_user_accounts` | List users including deleted accounts |
| `mac_get_user_timeline` | Build timeline for specific user account |

### FSEvents

| Tool | Description |
|------|-------------|
| `mac_fsevents_search` | Search file system events (create, delete, modify, rename) |
| `mac_fsevents_stats` | Get FSEvents statistics |

### Extended Attributes & Spotlight

| Tool | Description |
|------|-------------|
| `mac_get_extended_attributes` | Get xattr for file (quarantine, download URL, etc.) |
| `mac_spotlight_search` | Search Spotlight index for file metadata |
| `mac_spotlight_stats` | Get Spotlight index statistics |

### System Logs

| Tool | Description |
|------|-------------|
| `mac_parse_fsck_apfs_log` | Parse fsck_apfs.log for volume creation, external devices, anti-forensics |
| `mac_fsck_apfs_stats` | Get fsck_apfs.log statistics: devices, volumes, time range |

### Correlation & Investigation

| Tool | Description |
|------|-------------|
| `mac_build_timeline` | Build unified timeline from multiple artifacts |
| `mac_investigate_event` | Deep investigation with evidence correlation |

## Security Event Types

The `mac_unified_logs_security_events` tool supports these event types:

| Event Type | Description |
|------------|-------------|
| `user_created` | User account creation |
| `user_deleted` | User account deletion |
| `user_modified` | User account changes |
| `ssh_session` | SSH connections |
| `sudo_usage` | Sudo command execution |
| `auth_success` | Successful authentication |
| `auth_failure` | Failed authentication |
| `process_exec` | Process execution |
| `gatekeeper` | Gatekeeper/quarantine events |
| `tcc_prompt` | TCC permission prompts |
| `login` | User login |
| `logout` | User logout |
| `screen_lock` | Screen lock events |
| `screen_unlock` | Screen unlock events |
| `remote_login` | Remote Login service |
| `persistence` | Persistence mechanisms |

## Investigation Event Types

The `mac_investigate_event` tool supports deep investigation of these event types:

| Event Type | Description |
|------------|-------------|
| `user_deletion` | Investigate user account deletion with timeline and evidence correlation |
| `user_creation` | Investigate user account creation |
| `file_download` | Investigate file downloads (quarantine, xattr, browser history) |
| `ssh_session` | Investigate SSH session activity |
| `malware_execution` | Investigate potential malware execution |
| `privilege_escalation` | Investigate privilege escalation attempts |

## Usage Examples

### Discover artifacts in a triage

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

### Find user deletion events

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

### Deep investigation of user deletion

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

### Get Safari search history

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

### Read deleted users from plist

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

### Find external device activity

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

### Search for specific volume

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

### Build user activity timeline

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

### Search FSEvents for file activity

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

## Configuration

### External Tool Paths

External forensic tools can be configured via environment variables. If not set, defaults to `/opt/macOS/` paths.

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `MAC_FORENSICS_UNIFIEDLOG_ITERATOR_PATH` | `/opt/macOS/unifiedlog_iterator` | Path to unifiedlog_iterator binary |
| `MAC_FORENSICS_FSEPARSER_PATH` | `/opt/macOS/FSEventsParser/FSEParser_V4.1.py` | Path to FSEParser script |
| `MAC_FORENSICS_SPOTLIGHT_PARSER_PATH` | `/opt/macOS/spotlight_parser/spotlight_parser.py` | Path to spotlight_parser script |

Example with custom paths:

```json
{
  "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"
      }
    }
  }
}
```

## Dependencies

- Python 3.10+
- uv (for virtual environment and package management)
- mcp >= 1.0.0
- biplist (optional, for malformed plists)

External tools (optional, for parsing raw artifacts):
- `unifiedlog_iterator` - for parsing .logarchive bundles
- `FSEParser` - for parsing FSEvents (.fseventsd)
- `spotlight_parser` - for parsing Spotlight indexes

## Architecture

```
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
```

## Forensic Value

This MCP server was developed based on real-world macOS DFIR investigations. Key forensic capabilities:

| Capability | Tools |
|------------|-------|
| User account forensics | `mac_get_user_accounts`, `mac_get_user_timeline`, `mac_investigate_event` |
| File activity tracking | `mac_fsevents_search`, `mac_spotlight_search` |
| Download analysis | `mac_quarantine_events`, `mac_get_extended_attributes` |
| Security event detection | `mac_unified_logs_security_events` |
| External device detection | `mac_parse_fsck_apfs_log` |
| Cross-artifact correlation | `mac_build_timeline`, `mac_investigate_event` |

## References

- [SANS FOR518 Poster](https://www.sans.org/posters/macos-ios-forensic-analysis)
- [mac4n6 Artifacts Spreadsheet](https://www.sans.org/tools/mac4n6-artifacts)
- [SUMURI Mac Forensics Best Practices Guide 2025](https://sumuri.com/wp-content/uploads/2025/09/Mac-Forensics-Best-Practices-Guide-2025.pdf)
- [Google Cloud - Reviewing macOS Unified Logs](https://cloud.google.com/blog/topics/threat-intelligence/reviewing-macos-unified-logs/)

## Contributing

Based on lessons learned from macOS DFIR investigations. Additional tools and event patterns welcome.

---

## Author

**xtk**

Built for the DFIR community.