Home Page Wiki MacFire - Masriyan/MacFIRE GitHub Wiki

macFIRE Wiki

Overview
Installation
Usage
Artifact Categories
Technical Details
Forensic Considerations
Troubleshooting
Contributing

Overview

macFIRE (macOS Forensic Acquisition Tool) is a comprehensive forensic acquisition tool designed for macOS systems. It enables security professionals, digital forensic investigators, and system administrators to collect vital system artifacts, create forensically sound disk images, and generate detailed HTML reports.

The tool is primarily designed for macOS Catalina (10.15) and later, with limited support for earlier versions.

Installation

Prerequisites

Python 3.6 or higher
macOS operating system
Root privileges for complete functionality

Setup

Clone the repository:

git clone https://github.com/Masriyan/macfire.git
cd macfire

Make the script executable:

chmod +x macfire.py

Optional: Install dcfldd for enhanced disk imaging capabilities:

brew install dcfldd

Usage

Basic Operations

Listing Available Disks

To list all available disks on the system:

python3 macfire.py --list-disks

Example output:

/dev/disk0 (internal):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:      GUID_partition_scheme                         500.3 GB   disk0
   1:                        EFI EFI                     314.6 MB   disk0s1
   2:                 Apple_APFS Container disk1         500.0 GB   disk0s2

/dev/disk1 (synthesized):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:      APFS Container Scheme -                      +500.0 GB   disk1
                                 Physical Store disk0s2
   1:                APFS Volume Macintosh HD            15.0 GB    disk1s1
   2:                APFS Volume Preboot                 81.4 MB    disk1s2
   3:                APFS Volume Recovery                529.0 MB   disk1s3
   4:                APFS Volume VM                      1.1 GB     disk1s4
   5:                APFS Volume Macintosh HD - Data     174.5 GB   disk1s5

Detecting External Drives

To detect only external storage devices:

python3 macfire.py --detect-external

Artifact Collection

To collect all available forensic artifacts:

sudo python3 macfire.py --collect-artifacts ./evidence

This will create a timestamped subdirectory within the ./evidence directory containing all collected artifacts organized by category.

To collect specific categories of artifacts:

sudo python3 macfire.py --collect-artifacts ./evidence --categories "System Security" "Network"

The collection process includes:

Creating a timestamped directory
Organizing artifacts by category
Collecting files and executing commands
Tracking collection statistics
Generating a collection report

Disk Imaging

To create a raw disk image:

sudo python3 macfire.py --create-raw ./disk_images

You will be prompted to enter the disk path (e.g., /dev/disk2) and confirm the operation.

For faster imaging without hash calculation:

sudo python3 macfire.py --create-raw ./disk_images --skip-hash

To unmount a disk before imaging:

sudo python3 macfire.py --unmount /dev/disk2

The disk imaging process:

Gathers disk information
Creates timestamped output files
Uses dcfldd if available (with built-in hashing)
Falls back to dd with separate hash calculation if needed
Generates accompanying information files

Report Generation

To generate an HTML report after artifact collection:

python3 macfire.py --generate-report ./reports --artifacts-path ./evidence/artifacts_20250401_123456

The HTML report includes:

System information
Acquisition details
Collection statistics
Lists of collected artifacts by category
Timestamps and tool information

Artifact Categories

macFIRE collects artifacts organized into the following categories:

1. System Information

Description: Basic system information and configuration

Commands:

system_profiler SPHardwareDataType - Hardware details
sw_vers - macOS version information
hostname - System hostname
whoami - Current user
date - Acquisition date/time
uptime - System uptime information

2. File System

Description: File system artifacts and metadata

Paths:

/var/log/system.log - System log file
/private/var/db/Spotlight-V100/ - Spotlight index database
~/Library/Preferences/com.apple.LaunchServices.QuarantineEventsV2 - Quarantine database

Commands:

ls -la /Volumes/ - List mounted volumes
df -h - Disk usage information
sudo find / -type f -mtime -7 -not -path '*/\.*' - Recently modified files

3. User Data

Description: User-specific data and configurations

Paths:

~/Library/Preferences - User preferences
~/Library/Application Support - Application data
~/Library/Logs - User-specific logs
~/Library/Keychains/ - Keychain data
~/Library/Messages/chat.db - iMessage database
~/Library/Safari/History.db - Safari browsing history
~/Library/Application Support/Google/Chrome/Default/History - Chrome history
~/Library/Mail - Mail data
~/Library/Containers/com.apple.mail/Data/Library/Mail Downloads - Mail attachments
~/Library/Calendars - Calendar data
~/Library/Accounts - Account information

4. System Security

Description: Security-related artifacts

Paths:

/Library/Application Support/com.apple.TCC/TCC.db - Transparency, Consent, and Control database
/var/log/secure.log - Security log

Commands:

sudo log collect --last 24h - Unified logs (security-focused)
sudo pfctl -s rules - Firewall rules
security authorizationdb read system.preferences - Authorization settings
sudo launchctl list - Launch daemons

5. Network

Description: Network configurations and connections

Commands:

ifconfig - Network interfaces
arp -a - ARP cache
netstat -an - Network connections
netstat -rn - Routing table
scutil --dns - DNS configuration
defaults read /Library/Preferences/SystemConfiguration/com.apple.airport.preferences - WiFi settings

6. Running System

Description: Currently running processes and services

Commands:

ps aux - Running processes
lsof - Open files
ls -la /Library/LaunchAgents/ /Library/LaunchDaemons/ ~/Library/LaunchAgents/ - Launch agents
kmutil showloaded - Kernel extensions
sysctl -a - System control settings

Technical Details

Command Line Arguments

Argument	Description
`--list-disks`	List available disks
`--detect-external`	Detect external storage devices
`--unmount DISK`	Unmount a specified disk (e.g., /dev/disk2)
`--create-raw OUTPUT_PATH`	Create a raw disk image
`--skip-hash`	Skip hash calculation when creating disk images
`--collect-artifacts OUTPUT_PATH`	Collect forensic artifacts
`--categories CATEGORY [CATEGORY ...]`	Specific artifact categories to collect
`--generate-report OUTPUT_PATH`	Generate a forensic report
`--artifacts-path PATH`	Path to artifacts for report generation
`--quiet`	Minimize output (quiet mode)
`--version`	Show version information
`--help`	Display help message

Logging

macFIRE implements a comprehensive logging system that:

Records all operations to both console and a log file (macfire_forensic.log)
Uses standard Python logging levels (INFO, WARNING, ERROR)
Includes timestamps and contextual information
Provides detailed error information

Example log output:

2025-04-01 14:32:45 - INFO - Detected macOS version: 14.3.1
2025-04-01 14:32:45 - INFO - Collecting forensic artifacts to /evidence/artifacts_20250401_143245...
2025-04-01 14:32:46 - INFO - Processing category: System Information
2025-04-01 14:32:47 - INFO - Running: system_profiler SPHardwareDataType > ./system_info.txt
2025-04-01 14:32:49 - INFO - Executed: system_profiler SPHardwareDataType > ./system_info.txt

Progress Tracking

For lengthy operations, macFIRE provides visual feedback through a command-line progress bar:

Collecting artifacts: |██████████████████████████████████████████████████| 100.0% (89/89) Complete

This helps users monitor long-running operations like artifact collection or disk imaging.

Forensic Considerations

Chain of Custody

macFIRE maintains proper chain of custody by:

Recording timestamps for all operations
Logging all actions performed
Calculating hashes for disk images
Generating detailed reports
Keeping original files intact

Write Blocking

When performing disk imaging, consider using hardware write blockers when possible. macFIRE creates read-only copies but does not implement write blocking on its own.

Integrity Verification

Disk images are verified using SHA-256 hash calculations, which are stored alongside the image files for later validation.

Troubleshooting

Permission Issues

Problem: "Failed to collect artifact: Permission denied"
Solution: Ensure you're running the tool with sudo/root privileges.

Missing Files

Problem: "Path not found: /path/to/artifact"
Solution: Some artifacts may not exist on all systems. This is normal and will be reported in the collection statistics.

Disk Imaging Errors

Problem: "Failed to create raw image"
Solution:

Ensure the disk is not in use
Try unmounting it first: macfire.py --unmount /dev/diskX
Check disk permissions
Verify the output path is writable

dcfldd Not Found

Problem: "which dcfldd returned non-zero exit code"
Solution: Install dcfldd for enhanced imaging capabilities: brew install dcfldd

Contributing

Contributions to macFIRE are welcome! To contribute:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Adding New Artifact Categories

To add a new artifact category, edit the ARTIFACTS dictionary in the source code:

ARTIFACTS["My New Category"] = {
    "description": "Description of the category",
    "paths": [
        "/path/to/important/file",
        "/path/to/directory"
    ],
    "commands": [
        "command > ./output_file.txt"
    ]
}

Coding Standards

Follow PEP 8 guidelines
Add proper docstrings to new functions
Include error handling for all operations
Update documentation when adding new features

Home Page Wiki MacFire - Masriyan/MacFIRE GitHub Wiki

macFIRE Wiki

Table of Contents

Overview

Installation

Prerequisites

Setup

Usage

Basic Operations

Listing Available Disks

Detecting External Drives

Artifact Collection

Disk Imaging

Report Generation

Artifact Categories

1. System Information

2. File System

3. User Data

4. System Security

5. Network

6. Running System

Technical Details

Command Line Arguments

Logging

Progress Tracking

Forensic Considerations

Chain of Custody

Write Blocking

Integrity Verification

Troubleshooting

Permission Issues

Missing Files

Disk Imaging Errors

dcfldd Not Found

Contributing

Adding New Artifact Categories

Coding Standards