ryoshu404/macollect
GitHub: ryoshu404/macollect
一个零依赖的模块化 macOS 取证工件收集器，用于事件响应和威胁狩猎场景下快速采集持久化机制、进程快照、TCC 权限等关键证据并输出结构化 JSON。
Stars: 0 | Forks: 0
# macollect
macollect 是一个用 Python 编写的模块化 macOS 取证工件收集器，用于收集相关的关注项并生成适用于事件响应、威胁狩猎和安全自动化工作流的结构化 JSON 输出。macollect 的目标是提供一个简单、无依赖的收集器，该收集器可以集成到其他安全工作流中，或直接用于分析。
该工具收集持久化机制、运行进程快照、代码签名元数据、TCC 隐私权限、扩展属性、凭据工件以及跨八个独立收集模块的 Unified Log 活动。
macollect 无需第三方依赖，专为开箱即用的企业 IR 部署而设计。
# 功能
macollect 实现了八个独立的收集模块：
- 系统基线（macOS 版本、架构、SIP 状态、执行用户上下文）
- 持久化枚举（LaunchAgents、LaunchDaemons、BTM、Login Items、shell 配置、sudoers、cron）
- 进程快照（PID 树、RUID/EUID、命令行、二进制路径）
- 代码签名增强（签名状态、Team ID、公证信息、Mach-O 验证）
- TCC 数据库收集（系统级和每用户隐私权限授予）
- 扩展属性收集（隔离标志、下载来源）
- 凭据和 shell 工件收集（shell 历史、SSH 工件、keychain 元数据）
- Unified Log 收集（可配置时间窗口，过滤至安全相关子系统）
每个模块生成独立的结构化输出，并包含自己的 flags 数组用于异常发现。
# 架构
macollect 遵循模块化编排器架构，其中每个收集模块独立运行并生成自己的结构化输出。
收集流程：
```
sudo macollect
↓
Orchestrator
↓
┌─────────────────────────────────────┐
│ Module 1: System Baseline │
│ Module 2: Persistence │
│ Module 3: Process Snapshot │
│ Module 4: Code Signing Enrichment │
│ Module 5: TCC Databases │
│ Module 6: Extended Attributes │
│ Module 7: Credential Artifacts │
│ Module 8: Unified Log │
└─────────────────────────────────────┘
↓
ReportBuilder
↓
JSONFormatter
↓
output.json
```
每个组件负责单一的职责：
| 组件 | 职责 |
|-----------|---------------|
| Orchestrator | 按顺序运行模块并组装结果 |
| Collection Modules | 收集工件并输出各模块的 flags |
| ReportBuilder | 组装结构化输出信封 |
| JSONFormatter | 生成确定性 JSON 输出 |
# 设计决策
## 只读保证
macollect 绝不修改系统状态。每个收集操作都是严格只读的。不会在目标系统上创建、移动或删除任何文件。这是硬性的架构约束，而非运行时选项。
## 零第三方依赖
macollect 完全基于 Python 标准库编写。除了工具本身之外，不需要 `pip install`。这是针对企业 IR 部署的刻意设计约束，因为引入依赖链的工具会在受限环境中造成摩擦，并在安全敏感的场景中带来供应链风险。
## Sudo 要求
macollect 需要 sudo 执行。某些工件来源（例如 TCC 数据库、sudoers、keychain 元数据和某些进程属性）在标准用户上下文中无法访问。该工具不会静默地收集不完整的快照，而是在未使用提升的权限运行时快速失败。
## ESF 边界
macollect 不使用 Apple 的 Endpoint Security Framework。ESF 提供实时内核级事件流，并且需要具有 Apple 颁发的授权的原生 Swift 或 C 实现。macollect 是一个基于轮询的工件收集器，它读取收集时磁盘和内存中已存在的状态。Python 足以胜任此类工作。实时事件流推迟到未来的 Swift ESF 配套项目中。
## 每模块 Flags
每个模块通过 flags 数组独立地输出其异常。Flags 不会聚合到全局列表中。这使得发现与其来源保持一致，并简化了分类工作。分析师可以直接转到引发 flag 的模块，而无需交叉引用单独的发现部分。
## 模块化架构
每个收集模块实现为具有单个 `collect()` 方法的独立类。模块之间互不知晓。这种分离保持了代码库的可维护性，并允许通过 `--modules` 标志选择性地运行模块，而无需修改收集逻辑。
# 仓库结构
```
macollect/
├── src/
│ └── macollect/
│ ├── cli.py
│ ├── pipeline.py
│ ├── report.py
│ ├── modules/
│ │ ├── system_baseline.py
│ │ ├── persistence.py
│ │ ├── process_snapshot.py
│ │ ├── code_signing.py
│ │ ├── tcc_databases.py
│ │ ├── extended_attributes.py
│ │ ├── credential_artifacts.py
│ │ └── unified_log.py
│ └── formatters/
│ └── json_formatter.py
├── samples/
├── tests/
├── README.md
└── pyproject.toml
```
# 安装
需要 Python 3.11+
需要 sudo 执行。
克隆仓库：
```
git clone https://github.com/ryoshu404/macollect.git
cd macollect
```
创建虚拟环境：
```
python -m venv .venv
source .venv/bin/activate
```
以可编辑模式安装项目：
```
pip install -e .
```
验证安装：
```
macollect --version
```
# 用法
运行完整收集：
```
sudo macollect
```
将输出写入特定文件：
```
sudo macollect --output /path/to/output.json
```
仅运行特定模块：
```
sudo macollect --modules persistence process_snapshot
```
设置自定义 Unified Log 时间窗口（默认：24 小时）：
```
sudo macollect --time-window 48
```
查看可用选项：
```
macollect --help
```
检查已安装版本：
```
macollect --version
```
# 示例输出
在 v1 发布后添加
# 路线图
## v1.0 覆盖范围
macollect v1.0 实现了八个收集模块：
- 系统基线和收集上下文
- 跨所有主要 macOS 持久化机制的持久化枚举
- 带有 flag 逻辑的即时进程快照
- 针对持久化和标记进程二进制文件的代码签名增强
- 针对系统级和每用户隐私权限的 TCC 数据库收集
- 针对下载来源的扩展属性收集
- 凭据和 shell 工件收集
- 过滤至安全相关子系统的 Unified Log 收集
## v1.x 候选
以下内容被记录为 v1.0 后的计划添加项：
- 通过 `lsmp` 对标记的 PID 进行 Mach port 快照
- 通过 `lsregister` 进行 URL scheme 枚举
- 对所有标记的 PID 进行完整的 `launchctl procinfo` 增强
- 应用程序包中的 Dylib 存在性检查
- 通过 `mdls` 获取可疑文件的 Spotlight 元数据
- 用于网络上下文的 Bonjour/dns-sd 枚举
# 相关项目
该项目是更大型安全工具产品组合的一部分。
### Statica (已完成)
用 Python 编写的模块化静态分析流水线。从任意文件中提取文件哈希、可打印字符串和常见的入侵指标。是 macollect 的天然收集前伴侣。
GitHub: https://github.com/ryoshu404/statica
### IOC Correlation Service (计划中)
用 Go 编写的威胁情报关联服务。macollect 输出的未来增强集成层。
### Swift ESF Telemetry Tool (计划中)
使用 Apple 的 Endpoint Security Framework 的 macollect 实时内核事件流伴侣。对于需要实时事件遥测而非基于轮询的工件收集的环境，这是自然的 v2 演进方向。
# 作者
R. Santos
GitHub: https://github.com/ryoshu404
# 许可证
MIT
标签：EDR, Google搜索, Homebrew安装, HTTP工具, JSON, LaunchAgents, LaunchDaemons, Python, TCC数据库, TCC权限, 二进制发布, 代码签名, 企业安全, 凭证收集, 取证, 后渗透, 启动项, 库, 应急响应, 开源工具, 扩展属性, 持久化枚举, 数字取证, 数据包嗅探, 无后门, 无线安全, 统一日志, 网络安全审计, 网络资产管理, 脆弱性评估, 自动化脚本, 艺术品收集器, 进程快照, 逆向工具