pallab-js/forensic-kit

# ForensicKit ForensicKit 从运行中的 macOS 系统采集实时取证数据：进程列表、内存使用快照、网络接口信息，以及带有 SHA-256 哈希校验的文件系统目录快照。结果以结构化的 `ForensicEvent` 对象流式传输，并可导出为 JSON、Markdown 报告或 CSV 格式。 ## 功能 - **进程树** — 通过 `sysctl(KERN_PROC_ALL)` 快照获取所有正在运行的进程（PID、名称、父 PID、路径），并利用 macOS Security framework 进行**自动代码签名验证**（检测 `valid`、`unsigned` 或 `invalid` 签名） - **内存记录器** — 通过 `MACH_TASK_BASIC_INFO` 持续监控内存，支持自定义监控间隔、持续时间和告警阈值 - **网络监控** — 通过 `getifaddrs(3)` 列出 IPv4、IPv6 和 MAC 地址，支持协议族分类及安全的可变长度地址提取 - **文件系统扫描器** — 使用 POSIX `lstat` 进行目录快照，捕获常规文件、目录和**符号链接**（在不追踪的情况下记录链接目标），并计算 SHA-256 完整性哈希 - **健壮的异常处理** — 当流中遇到不可读取的项目（例如受 SIP 保护的文件）时，会发出优雅的 `.warning` 事件，而不是静默跳过 - **CLI** — 基于 `swift-argument-parser` 的命令行界面，支持输出 JSON 和 Markdown 报告 - **桌面应用** — 基于 SwiftUI `NavigationSplitView`，提供实时流式图表、配置预设、带有代码签名状态徽章和 symlink 目标可视化的可排序表格、搜索/过滤功能，以及 CSV 导出 - **全阶段 98 项测试** — 使用 Swift Testing，典型运行时间 >0.190s ## 环境要求 - **Swift 6.3+** (`swift --version`) - **macOS 14+** - **无需 Xcode** ## 构建与运行 ``` # 构建所有 target swift build # 运行 CLI swift run forensic-kit # 运行桌面应用 swift run forensic-kit-desktop # 运行所有测试 swift test # 构建 release swift build -c release ``` ### 桌面应用 (macOS .app bundle) ``` # 手动 .app bundle bash build-app.sh ``` 该脚本将创建包含 Info.plist 和强化 entitlements 的 `ForensicKit.app`。可以将其拖放到 `/Applications` 或通过 Finder 运行。 ## 项目结构 ``` 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 用法 ``` # 帮助 swift run forensic-kit --help # 收集所有服务，输出 JSON swift run forensic-kit --services all --output-format json # 仅收集进程和网络，生成 Markdown 报告 swift run forensic-kit --services process,network --output-format markdown --output-path report.md # 带自定义选项的文件系统快照 swift run forensic-kit --services filesystem --fs-target /tmp/snapshot --no-fs-recursive # 带自定义限制的内存监控 swift run forensic-kit --services memory --memory-limit 2048 --memory-interval 100 --memory-duration 30 ``` ## 桌面应用 SwiftUI 桌面应用 (`forensic-kit-desktop`) 提供： - **采集视图** — 带有独立开关的服务卡片、带有实时进度的运行按钮、实时错误/警告横幅，以及系统健康状态诊断 - **数据视图** — 针对进程（以彩色代码签名验证徽章为特色）、网络、内存和文件系统（以符号链接目标箭头为特色）的可排序表格，带有行数统计和搜索功能 - **实时图表** — 带有可配置阈值的实时内存使用 LineMark 图表 - **配置预设** — 3 个内置预设（快速扫描、全面调查、仅内存）；支持保存/删除自定义预设 - **检查器** — 针对每行元数据的表单，带有复制按钮和嵌套的原始字典视图 - **导出** — 通过 `.fileExporter()` 为每个数据视图提供 CSV 导出，以及纯文本 / JSON 报告格式化 全局使用 `@Observable` (iOS 17+ / macOS 14+)、`NavigationSplitView`、`Swift Charts` 和 `os_log`。 ## 测试 ``` # 运行所有测试 swift test # 运行特定 test suite swift test --filter "ProcessTreeServiceTests" swift test --filter "PresetTests" # 在 CI 环境中使用 xcodebuild 运行 xcodebuild test -scheme forensic-kit -destination 'platform=macOS' ``` 所有测试均使用 Swift Testing（不使用 XCTest）。通过 `MockCollectionService` 和 `MockMemoryProvider` 提供 Mock，以实现确定性的服务测试。 ## License MIT