pallab-js/forensic-kit

# ForensicKit ForensicKit collects live forensic data from a running macOS system: process listings, memory usage snapshots, network interface information, and filesystem directory snapshots with SHA-256 hashing. Results stream as structured `ForensicEvent` objects and can be exported as JSON, Markdown reports, or CSV. ## Features - **Process Tree** — `sysctl(KERN_PROC_ALL)` snapshot of all running processes (PID, name, parent PID, path) with **automatic code signature verification** using macOS Security framework (detects `valid`, `unsigned`, or `invalid` signatures) - **Memory Logger** — continuous memory monitoring via `MACH_TASK_BASIC_INFO` with configurable interval, duration, and alert thresholds - **Network Monitor** — `getifaddrs(3)` listing of IPv4, IPv6, and MAC addresses with family classification and safe variable-length address extraction - **File System Scanner** — directory snapshots using POSIX `lstat` to capture regular files, directories, and **symbolic links** (records link targets without following them) with SHA-256 integrity hashing - **Robust Exception Handling** — emits graceful `.warning` events on streams for unreadable items (e.g. SIP protected files) instead of silently skipping them - **CLI** — `swift-argument-parser` interface with JSON and Markdown report output - **Desktop App** — SwiftUI `NavigationSplitView` with live streaming charts, configuration presets, sortable tables with code signature status badges and symlink target visualizations, search/filter, and CSV export - **98 tests** across all phases — Swift Testing with >0.190s typical runtime ## Requirements - **Swift 6.3+** (`swift --version`) - **macOS 14+** - **No Xcode required** ## Build & Run # Build all targets swift build # Run CLI swift run forensic-kit # Run desktop app swift run forensic-kit-desktop # Run all tests swift test # Build release swift build -c release ### Desktop App (macOS .app bundle) # Manual .app bundle bash build-app.sh The script creates `ForensicKit.app` with Info.plist and hardened entitlements. Drag to `/Applications` or run via Finder. ## Project Structure forensic-kit/ ├── Package.swift # SPM manifest (6 targets) ├── Sources/ │ ├── ForensicKit/ # Core library (models, protocols, services) │ │ ├── Models/ # ForensicEvent, EventPayload │ │ ├── Protocols/ # CollectionService protocol │ │ ├── Services/ # ProcessTreeService, MemoryLogger, │ │ │ # NetworkMonitorService, FileSystemService, │ │ │ # CollectionOrchestrator │ │ ├── Reporting/ # ForensicReporter (JSON, Markdown) │ │ └── Errors/ # ForensicError │ ├── ForensicKitCLI/ # CLI executable (swift-argument-parser) │ ├── ForensicKitDesktop/ # Desktop app executable (SwiftUI) │ └── ForensicKitDesktopCore/ # Shared library (AppState, Panel, helpers) ├── Tests/ │ ├── ForensicKitTests/ # Core library tests (79) │ └── ForensicKitDesktopTests/ # Desktop app tests (17) ├── specs/ # Phase specifications │ └── tools/spec-verify.sh # Spec validator ├── build-app.sh # .app bundling script ├── CHANGELOG.md └── README.md ## CLI Usage # Help swift run forensic-kit --help # Collect all services, output JSON swift run forensic-kit --services all --output-format json # Collect process + network only, generate Markdown report swift run forensic-kit --services process,network --output-format markdown --output-path report.md # File system snapshot with custom options swift run forensic-kit --services filesystem --fs-target /tmp/snapshot --no-fs-recursive # Memory monitoring with custom limits swift run forensic-kit --services memory --memory-limit 2048 --memory-interval 100 --memory-duration 30 ## Desktop App The SwiftUI desktop app (`forensic-kit-desktop`) provides: - **Collection View** — service cards with individual toggles, run button with live progress, real-time error/warning banners, and system health status diagnostics - **Data Views** — sortable tables for Processes (featuring colored code signature verification badges), Network, Memory, and Filesystem (featuring symbolic link destination arrows) with row counts and search - **Live Chart** — real-time memory usage LineMark chart with configurable threshold - **Configuration Presets** — 3 built-in presets (Quick Scan, Full Investigation, Memory Only); save/delete custom presets - **Inspector** — per-row metadata sheet with copy buttons and nested raw dictionary views - **Export** — CSV export per data view via `.fileExporter()` and plain text / JSON report formatting Uses `@Observable` (iOS 17+ / macOS 14+), `NavigationSplitView`, `Swift Charts`, and `os_log` throughout. ## Testing # Run all tests swift test # Run specific test suite swift test --filter "ProcessTreeServiceTests" swift test --filter "PresetTests" # Run with xcodebuild for CI xcodebuild test -scheme forensic-kit -destination 'platform=macOS' All tests use Swift Testing (no XCTest). Mocks provided via `MockCollectionService` and `MockMemoryProvider` for deterministic service testing. ## License MIT