Skip to content

README.md

Latest commit

 

History

History
277 lines (204 loc) · 10.5 KB

README.md

File metadata and controls

277 lines (204 loc) · 10.5 KB
Raw

🔍 MacProbe v2.0 — macOS Forensic Investigation Platform

A Python-based digital forensics platform that collects, analyzes, and packages forensic artifacts from macOS systems — with live threat intelligence, browser deep forensics, investigation timeline, USB history, and AES-256 encrypted evidence vault.

Version: 2.0
Previous Version: MacProbe v1.0
Platform: macOS (Apple Silicon M1/M2/M3/M4)
Python: 3.8+
Author: Shreesha S
Purpose: PBL Project — Digital Forensics (Cybersecurity, Year 3)

📋 Table of Contents

🧠 Overview

MacProbe v2.0 is a comprehensive macOS forensic investigation platform built natively for Apple Silicon. It automates the collection and analysis of forensic artifacts from a live macOS system, cross-references findings against real-time threat intelligence feeds, correlates all evidence into a unified investigation timeline, and packages everything into a cryptographically secured evidence vault.

The tool covers the complete first-responder forensic workflow — from volatile artifact collection to tamper-evident evidence packaging — in a single command.

🆕 What's New in v2.0

Feature Description
🌐 Browser Deep Forensics Direct SQLite extraction from Chrome, Brave & Safari — history, downloads, cookies, search terms
🛡️ IOC Threat Intelligence Live cross-referencing against 21,000+ malicious IPs and 77,000+ malicious domains
🗓️ Timeline Engine Unified chronological event correlation across all modules with pattern detection
🔌 USB Device History Full IORegistry enumeration of USB devices with suspicious device detection
🔒 Evidence Vault AES-256-GCM encrypted evidence package with SHA256 chain of custody verification

✨ Features

  • 11 Forensic Collection Modules — 6 core (v1.0) + 5 advanced (v2.0)
  • Live Threat Intelligence — fetches real IOC feeds at runtime, not hardcoded rules
  • Browser SQLite Extraction — reads Chrome, Brave, Safari databases directly
  • Unified Investigation Timeline — correlates 180+ events chronologically
  • Suspicious Pattern Detection — late night activity, file bursts, critical events
  • AES-256-GCM Evidence Vault — NIST SP 800-132 compliant key derivation (PBKDF2, 310,000 iterations)
  • SHA256 Integrity Verification — proves evidence has not been tampered with
  • Interactive HTML Report — 10 collapsible sections, filterable timeline, color-coded findings
  • Zero Network Exfiltration — only outbound traffic is fetching public threat feeds
  • Read-Only Collection — no system modifications whatsoever
  • Single Command Execution — entire investigation in one command

🗂️ Project Structure

MacProbe_v2/
├── macprobe.py                        ← Main runner (entry point)
├── README.md                          ← This file
├── modules/
│   ├── __init__.py
│   ├── system_info.py                 ← OS, CPU, RAM, disk, boot time
│   ├── user_activity.py               ← Shell history, recent files, apps
│   ├── network_forensics.py           ← Connections, ports, WiFi, ARP
│   ├── process_monitor.py             ← Processes, suspicious detection
│   ├── file_system.py                 ← Hidden files, downloads, large files
│   ├── security_artifacts.py          ← Logins, SSH, firewall, launch agents
│   ├── browser_forensics.py           ← Chrome/Brave/Safari SQLite extraction
│   ├── ioc_scanner.py                 ← Live threat intelligence scanning
│   ├── timeline_engine.py             ← Unified investigation timeline
│   ├── usb_history.py                 ← USB device forensics via IORegistry
│   ├── evidence_vault.py              ← AES-256-GCM encrypted evidence vault
│   └── report_generator.py            ← HTML report generation
└── output/
    ├── MacProbe_v2_Report_<ts>.html   ← Generated forensic report
    └── MacProbe_Evidence_<ts>.vault   ← Encrypted evidence vault (optional)

⚙️ Prerequisites

  • macOS 12 Monterey or later (tested on macOS 14 Sonoma/Sequoia)
  • Apple Silicon (M1/M2/M3/M4) — ARM64
  • Python 3.8 or higher
  • Homebrew
  • Internet connection (for live IOC threat feeds)

🛠️ Installation

Step 1 — Clone the Project

cd ~/Desktop
git clone <repository-url> MacProbe_v2
cd MacProbe_v2

Step 2 — Install Python (if not installed)

brew install python

Step 3 — Install Dependencies

pip3 install psutil requests cryptography --break-system-packages

Step 4 — Verify Installation

python3 --version
python3 -c "import psutil, requests, cryptography; print('All dependencies OK')"

🚀 Usage

Run Full Investigation

cd ~/Desktop/MacProbe_v2
python3 macprobe.py

You will be prompted to:

  1. Confirm forensic collection
  2. Optionally create an encrypted evidence vault (set a password)

The tool will run all 11 modules, generate an HTML report, open it in your browser, and optionally create an encrypted .vault file.

Run Individual Modules

python3 modules/system_info.py
python3 modules/browser_forensics.py
python3 modules/ioc_scanner.py
python3 modules/timeline_engine.py
python3 modules/usb_history.py
python3 modules/evidence_vault.py    # Interactive vault manager

Evidence Vault Manager (Standalone)

python3 modules/evidence_vault.py

Options:

  • 1 — Create new vault (encrypt)
  • 2 — Verify vault integrity (no password needed)
  • 3 — Decrypt vault (requires password)

🔬 Modules

Core Modules (v1.0)

system_info.py — OS, CPU, RAM, disk, boot time. Key artifacts: macOS version, architecture (arm64), utilization stats, boot timestamp.

user_activity.py — Shell history (Zsh/Bash), recently modified files (48hrs), active sessions, installed applications.

network_forensics.py — All active TCP/UDP connections with process names, open ports, WiFi network history, network interfaces, ARP table.

process_monitor.py — All running processes with CPU/memory usage. Heuristic suspicious detection with keyword/path matching and Apple process whitelist.

file_system.py — Recently modified files, large files (100MB+), hidden items, downloads folder, suspicious file extensions.

security_artifacts.py — Login history, failed authentication attempts, SSH known hosts, firewall status, cron jobs, Launch Agents, environment variables.

Advanced Modules (v2.0)

browser_forensics.py — Direct SQLite database extraction from Chrome, Brave, and Safari. Extracts browsing history with timestamps, downloads, cookies, and search terms. Auto-detects suspicious domains and search queries.

Technical notes:

  • Chrome timestamps: microseconds since Jan 1 1601 — formula: (ts / 1000000) - 11644473600
  • Safari timestamps: seconds since Jan 1 2001 — add 978307200 offset
  • Databases safely copied to temp location to avoid lock conflicts

ioc_scanner.py — Fetches live threat feeds and cross-references collected connections, domains, and file hashes.

Feeds: stamparm/ipsum, stamparm/blackbook (IPs), StevenBlack/hosts (domains)
Scoring: 0–100 → CLEAN / LOW / MEDIUM / HIGH / CRITICAL

timeline_engine.py — Unified chronological event stream from all modules. Detects patterns: late night activity (midnight–6AM), critical event clusters, file activity bursts (10+ files/hour). Interactive filterable HTML timeline in report.

usb_history.py — USB device enumeration via macOS IORegistry (ioreg -p IOUSB). Extracts vendor ID, product ID, device class, serial number. Checks against 25 known legitimate vendors, flags unknown devices and attack tool keywords.

evidence_vault.py — AES-256-GCM encrypted evidence package.

Cryptographic specs:

  • Encryption: AES-256-GCM (authenticated encryption)
  • KDF: PBKDF2-SHA256, 310,000 iterations (NIST SP 800-132)
  • Integrity: SHA256 hash of vault + per-file pre-encryption hashes
  • Entropy: CSPRNG via secrets.token_bytes()

🔒 Evidence Vault

Creating a Vault

Answer yes when prompted during python3 macprobe.py and set a strong password.

Vault File

output/MacProbe_Evidence_YYYY-MM-DD_HH-MM-SS.vault

Contains: metadata (case info, integrity hashes), encrypted HTML report, encrypted JSON data, vault integrity hash.

Verifying Integrity

python3 modules/evidence_vault.py  # Option 2 — no password required

Decrypting

python3 modules/evidence_vault.py  # Option 3 — password required

⚠️ Store your vault password safely. There is no recovery mechanism. Lost password = permanently inaccessible evidence.

📊 v1.0 vs v2.0

Metric v1.0 v2.0
Modules 6 11
Lines of Code ~600 ~2,000+
Threat Intelligence None 98,592+ live IOCs
Browser Forensics None Chrome, Brave, Safari
Timeline None 180+ correlated events
Evidence Security None AES-256-GCM + SHA256
Report Sections 6 10 + interactive timeline
Collection Time 28–35 sec 45–60 sec

🛡️ Disclaimer

MacProbe v2.0 is developed strictly for educational purposes as part of a cybersecurity coursework project. Use only on systems you own or have explicit written authorization to investigate.

  • Read-only collection — no system files modified
  • Only outbound traffic is fetching public threat feeds
  • No collected data transmitted anywhere — all stays local
  • Vault password never stored or transmitted

📚 References

MacProbe v2.0 — macOS Forensic Investigation Platform — Digital Forensics PBL Project — Cybersecurity Year 3