Juwon1405/yushin-mac-forensics-platform

# yushin-mac-forensics-platform [](https://www.python.org/) [](https://flask.palletsprojects.com/) [](https://support.apple.com/macos) [](LICENSE) ## 🎯 本平台分析的内容 | 输入类型 | 来源 | 用例 | |------------|--------|----------| | **收集器 ZIP** | [yushin-mac-artifact-collector](https://github.com/Juwon1405/yushin-mac-artifact-collector) 的输出或内置的 `collector/macOS Collectors.sh` | 实时主机分诊，事件后痕迹审查 | | **磁盘镜像** | `.dd`, `.raw`, `.E01`, `.AFF`, `.dmg` | 死磁盘取证，MacBook 磁盘镜像 | | **单个痕迹文件** | `.db`, `.log`, `.txt`, `.json` | 针对单个 SQLite DB、日志文件或 JSON dump 的定向分析 | **解析的痕迹类别**（自动检测并标准化为一个可搜索的证据表）： - macOS 统一日志（按 auth、远程访问、TCC、隐私、安全代理过滤） - 浏览器历史记录 — **Chrome、Edge、Firefox、Safari**（所有配置文件） - 持久化 — LaunchAgents、LaunchDaemons、crontab、登录项、`~/.config/` 脚本 - 网络状态 — 接口、活动连接、DNS、远程访问日志 - 安全代理 — CrowdStrike Falcon、Tanium、JAMF 状态 + 日志 - 隔离事件 (LSQuarantineEventsV2) - 命令历史 — `zsh_history`、`bash_history` - 登录历史 (`last`) - 已安装的应用程序、pkgutil 包、安装时间线 - IP-KVM / IPMI / iDRAC 指标（USB、Thunderbolt、以太网枚举） - 供应链 IOC (litellm PyPI、恶意 `.pth` 文件、Node.js 安装钩子) - 在证据中发现的嵌入式 Draw.io 图表 ## ✨ 平台功能 | 功能 | 详情 | |------------|--------| | **Web UI** | 仪表盘优先的登录页面、服务端过滤的证据表、严重性标签、分类标签、行模态框 | | **搜索** | 服务端关键字 + 严重性 + 可排序列 + 仅复选框选中模式 + 分页 | | **本地 LLM 分析** | 由 Ollama 提供支持（默认 `qwen2.5:14b-q4_K_M`）— 完全离线，数据不会离开主机 | | **云端 LLM 分析** | 可选由 OpenAI 提供支持（默认 `gpt-4.1-mini`）— 设置 `OPENAI_API_KEY` 以启用 | | **PDF 报告** | 自动生成包含失陷结论 (YES/NO)、IOC 列表、时间线和嵌入式 Draw.io 图表的 DFIR 报告 | | **CSV 导出** | 可见 / 已过滤 / 已选中 / 全部 — 以及每个事件的逐行导出 | | **REST API** | 每一个 UI 操作都以 JSON 格式暴露 — 可自动化或集成到您的 SOC pipeline 中 | | **内置收集器** | `collector/macOS Collectors.sh` — 基线收集器，可独立运行 | ## 🚀 快速开始 ### 1. 运行平台 ``` # 从 repo 根目录 — 自动创建 .venv，安装 deps，启动 Flask OPENAI_API_KEY="sk-..." \ OPENAI_CHAT_MODEL="gpt-4.1-mini" \ OPENAI_EMBED_MODEL="text-embedding-3-small" \ ./run_web.sh ``` 打开：**http://127.0.0.1:17888** ### 2. 收集证据（内置收集器） ``` ./run_collector.sh # 或快速模式（减少日志量） COLLECTOR_QUICK=1 ./run_collector.sh ``` 输出：当前工作目录下的 `HOSTNAME_YYYYMMDD_HHMM.zip`。将其拖放到 Web UI 中即可开始一个案例。 ### 3. （可选）本地 LLM 设置 ``` ollama pull qwen2.5:14b-q4_K_M ollama serve ``` 平台会自动在 `http://127.0.0.1:11434` 检测 Ollama。 ## 🖥️ UI 演示 - **仪表盘优先的登录页** — 案例统计、严重性分布、按小时集中度的热力图 - **证据表**，带有服务端查询： - 跨越每个解析字段的关键字搜索 - 严重性过滤器 (critical / high / medium / low / info) - 复选框选择 + "仅选中" 模式 - 可排序列、分页、页面大小控制 - **分类标签** — 包括专用的 `Command History` 标签 - **行模态框** — 解析的详细信息 + 保留的原始原始事件 - **CSV 导出模式：** - `CSV Visible` — 当前屏幕 / 页面 - `CSV Filtered` — 当前标签 + 活动的过滤器 - `CSV Selected` — 仅已勾选的行 - `CSV All` — 案例中的每一行证据 - 每个模态框的 `Export This Event (CSV)` — 单个痕迹文件 - **清除所有历史记录** — 通过 UI / API 擦除 `cases/` + `uploads/` - **DFIR PDF 报告：** - 在本地 / OpenAI 分析运行后自动生成 - 始终提供手动的“生成”按钮 - 失陷结论、IOC 列表、时间线、Draw.io 图表提取 ## 🔌 REST API | 方法 | 路径 | 用途 | |--------|------|---------| | `GET` | `/api/health` | 服务健康检查 | | `GET` | `/api/cases` | 列出所有案例 | | `POST` | `/api/cases/upload` | 上传痕迹 ZIP / 磁盘镜像 / 单个文件 | | `GET` | `/api/cases/?include_artifacts=0` | 轻量级案例元数据 | | `GET` | `/api/cases//dashboard` | 仪表盘聚合数据 | | `GET` | `/api/cases//rows` | 服务端已过滤/分页的行 | | `GET` | `/api/cases//rows/csv` | 已过滤的 CSV 导出 | | `POST` | `/api/cases//report/pdf` | 生成 DFIR PDF | | `GET` | `/api/cases//report/pdf` | 下载最新生成的 PDF | | `POST` | `/api/cases/clear` | 擦除所有案例和上传文件 | ## ⚙️ 配置 所有配置均通过环境变量进行（在执行 `./run_web.sh` 之前设置）： | 变量 | 默认值 | 用途 | |----------|---------|---------| | `OPENAI_API_KEY` | *(空)* | 如果设置，则启用由 OpenAI 支持的分析按钮 | | `OPENAI_CHAT_MODEL` | `gpt-4.1-mini` | 聊天补全模型 | | `OPENAI_EMBED_MODEL` | `text-embedding-3-small` | Embeddings 模型 | | `LOCAL_ANALYSIS_TIMEOUT` | `240` | Ollama 请求超时（秒） | | `LOCAL_ANALYSIS_MAX_TOKENS` | `900` | 每次 Ollama 调用的最大 token 数 | | `LOCAL_ANALYSIS_MAX_ARTIFACTS` | `60` | 单次处理中提供给本地 LLM 的最大痕迹文件数 | | `LOCAL_ANALYSIS_NUM_CTX` | `4096` | Ollama 上下文窗口大小 | | `PARSER_AI_FALLBACK` | `0` | 设置为 `1` 以允许解析器对难以解析的日志行调用 Ollama | | `PARSER_AI_MODEL` | `qwen2.5:14b-q4_K_M` | 解析器回退模型 | | `PARSER_AI_MAX_CALLS` | `24` | 每个案例的最大 LLM 辅助解析次数 | | `PARSER_AI_TIMEOUT` | `45` | 解析器回退超时（秒） | | `PARSER_AI_ENDPOINT` | `http://127.0.0.1:11434/api/generate` | Ollama 生成端点 | ## 🧪 QA 脚本 ``` ./run_qa.sh ``` 运行： 1. 跨 `webapp/app/` 的 Python 编译检查 2. 如果安装了 Node，则进行 JavaScript 语法检查 (`node -c`) 3. API 冒烟测试 — `/api/health`、`/api/cases`、`/api/cases/clear` 使用示例收集器 ZIP 进行端到端测试： ``` ./run_qa.sh /path/to/collector_output.zip ``` 这将上传 ZIP、运行行查询、生成 PDF 报告并下载它 — 演练完整的 pipeline。 ## 📁 仓库布局 ``` . ├── collector/ │ └── macOS Collectors.sh # Bundled baseline collector ├── webapp/ │ ├── app/ │ │ ├── main.py # CLI entrypoint (--host, --port, --open) │ │ ├── server.py # Flask app, routing, case lifecycle │ │ ├── dfir_parser.py # Multi-artifact parser (~30+ types) │ │ ├── reporting.py # PDF report generator (ReportLab) │ │ └── llm.py # Ollama + OpenAI client wrappers │ ├── static/ │ │ ├── css/styles.css │ │ └── js/app.js # Frontend (vanilla JS) │ └── templates/ │ └── index.html ├── cases/ # Per-case extracted artifacts (created at runtime) ├── uploads/ # Raw uploaded evidence (created at runtime) ├── run_web.sh # Start the platform ├── run_collector.sh # Run bundled collector ├── run_qa.sh # Run QA / smoke / e2e checks ├── start_macos_forensics.command # Double-click launcher (macOS) └── requirements.txt ``` ## 📋 说明与限制 - **解析优先于自动得出结论。** 本平台展示证据而不是自动分类。LLM 分析（启用时）提供的是第二意见，而不是最终结论。 - 为了保证 **UI 的响应速度**，日志和浏览器历史记录已被限制/采样 — 如需进行完整语料库分析，请使用 API 的 CSV 导出功能。 - **不支持加密的 ZIP 文件** — 请在上传前解密。 - 内置的 `collector/macOS Collectors.sh` 是一个基线版本。如需更广泛的覆盖范围和选择性模块执行，请使用 [yushin-mac-artifact-collector](https://github.com/Juwon1405/yushin-mac-artifact-collector)。 ## 🤝 配套工具 ➡️ **[yushin-mac-artifact-collector](https://github.com/Juwon1405/yushin-mac-artifact-collector)** — 包含 10 个模块（含 `supply_chain` IOC 检测）的单文件模块化收集器。输出的 ZIP 文件可直接放入本平台使用。 ## 📄 许可证 MIT — 详见 [LICENSE](LICENSE)。 ## ✍️ 作者 **YuShin (優心 / Bang Juwon)** — DFIR 从业者，东京。 如果本平台对您有帮助，请在仓库给一个 ⭐。欢迎提交 Issues / PRs。

标签：AFF, AI智能分析, AI风险缓解, Chrome, CrowdStrike, DD, DLL 劫持, DMG, E01, Flask, HTTP工具, IOC提取, LLM评估, macOS取证, Mac安全, Mr. Robot, Ollama, OpenAI, PDF报告生成, Petitpotam, Python, RAW, Safari, TCC隐私权限, Web平台, 免费免责, 内存规避, 后渗透, 命令历史, 域渗透, 大语言模型, 安全软件检测, 库, 应急响应, 应急响应平台, 开源取证工具, 持久化痕迹, 攻击指标, 数字取证, 无后门, 浏览器历史取证, 电子数据取证, 磁盘取证, 磁盘镜像分析, 统一日志分析, 网络安全, 网络安全审计, 网络测绘, 网络连接分析, 自动化取证报告, 自动化脚本, 证据搜索, 逆向工具, 隐私保护