tears-mysthrala/Oroitz
GitHub: tears-mysthrala/Oroitz
Oroitz 是一个围绕 Volatility 3 构建的教育性封装工具，通过 CLI、TUI 和 GUI 三种界面降低内存取证的学习门槛。
Stars: 0 | Forks: 0
# Oroitz
Oroitz（巴斯克语中的“记忆”）是一个**围绕 [Volatility 3](https://www.volatilityfoundation.org/) 构建的教育性封装工具**，旨在降低初学者学习内存取证时的入门门槛。它提供了一个共享的 Python 核心库，以及 CLI、Textual TUI 和 PySide6 GUI 前端，用于运行向导式的 Volatility 3 工作流并规范化其输出。
## Oroitz 自动化的工作
- 通过简单的命令或向导界面启动常见的 Volatility 3 插件（进程列表、网络扫描、`malfind`、SID 枚举等），让初学者可以专注于阅读结果，而无需死记硬背 CLI 标志。
- 符号表 / 操作系统检测 —— 完全交由 Volatility 3 的 automagic（自动 magic）处理。
- 将插件输出规范化为 JSON（部分工作流支持 CSV），以便在课堂上更轻松地进行检查。
- 具备持久化、结果缓存和带退避机制的自动重试功能的分析会话，以应对暂时性的 Volatility 故障。
## Oroitz 不做的事
- **它本身不进行内存分析。** 所有结果均来自 Volatility 3。理解每个插件展示的内容——以及它可能在哪里出错——是学生的任务，Oroitz 刻意不掩盖这一点。
- **它不判断系统是否受到威胁。** 没有结论、评分或自动检测逻辑。
- **它不能替代取证方法论**（获取、保管链、文档记录、同行评审）。
- **它不提供内存样本。** 请参阅下方的[内存样本](#memory-samples)。
- **它不是多用户或企业级工具**：没有角色、没有证据管理、也不保证保管链。
### 重要提示：模拟数据回退
当 Volatility 插件执行失败时，对于非敏感插件，Oroitz 会回退到**确定性模拟数据**，这样即使没有可用的运行环境，依然可以探索界面（参见 `docs/adrs/ADR-0004-retry-and-fallback.md`）。通过这种方式生成的结果会在 `ExecutionResult` 模型中被标记（`used_mock`）。与凭据相关的插件（`windows.hashdump`、`windows.cachedump`、`windows.lsadump`）绝不会回退——它们会直接报告失败。在使用 Oroitz 时，在得出结论之前，请务必验证结果是否来自真实的执行过程。
## 归属与许可
Oroitz 中所有的内存分析均由 **Volatility Foundation**（）开发和维护的 **Volatility 3** 执行。Volatility 3 根据其自身的许可分发——请查阅 Volatility 3 仓库以了解条款。Oroitz 本身基于 MIT 许可发布（参见 [`LICENSE`](LICENSE)）。
## 兼容性
仅支持 `pyproject.toml` 中锁定的版本：
- **Python**：`>=3.11, <3.13`（推荐 Python 3.11；某些 Volatility 3 插件在 3.12 上存在已知问题）
- **Volatility 3**：`^2.26.2`（即 `>=2.26.2, <3.0.0`）
- **GUI（可选依赖组）**：PySide6 `^6.7.0`
超出这些范围的版本未经测试。
## 遥测与日志记录 —— 诚实声明
此代码库中的“遥测”**仅指本地的结构化日志记录**。`oroitz/core/telemetry.py` 会向 stdout 输出 JSON 日志事件（插件开始/成功/失败、重试、持续时间）。**不会有任何数据离开本机**：没有分析后端，没有远程端点，也没有使用情况追踪。
`OROITZ_TELEMETRY_ENABLED` 设置（以及 GUI/TUI 设置中相应的复选框）目前仅用于存储偏好设置——它不会启用任何远程报告，因为报告功能根本不存在。请将其视为一个占位符。
## 可追溯性
为了满足课程作业和实验室可重复性的要求，Oroitz 目前提供：
- **命令日志记录**：在 CLI 执行路径（`oroitz/core/executor.py`）中会记录准确的 Volatility 3 命令行。
- **结构化事件**：插件名称、持续时间、重试次数和错误都会作为 JSON 日志事件输出。
- **结果导出**：规范化后的结果可导出为 JSON/CSV。
- **会话持久化**：会话存储在 `~/.oroitz/sessions` 下。
尚未实现的功能（在 [`ROADMAP.md`](ROADMAP.md) 中跟踪记录）：
- 在导出结果中记录 Volatility 3 / 插件版本。
- 用于课程作业提交的单次会话审计文件（包含命令 + 结果 + 环境）。
## 快速开始
1. 安装 Python 3.11 或 3.12，并确保 `python --version` 显示为 3.11.x 或 3.12.x。为了保证与 Volatility 3 插件的最大兼容性，推荐使用 Python 3.11。
2. 按照 中的说明安装 Poetry。
3. 在仓库根目录下，运行 `poetry install` 以创建虚拟环境并拉取依赖。如需使用 GUI，请运行 `poetry install --with gui`。
4. 使用 `poetry shell` 激活 Poetry shell，或者在命令前加上 `poetry run` 前缀。
5. 运行质量检查：使用 `poetry run pytest` 进行测试，使用 `poetry run ruff check .` 进行代码检查。
6. （可选）安装 Volatility 社区插件包，以便使用哈希提取插件：
poetry run python scripts/setup_volatility_plugins.py --dest vendor/volatility_plugins --update-env
这会将 `community3` 包下载到 `vendor/volatility_plugins` 中，并将 `OROITZ_PLUGIN_DIRS` 写入 `.env` 文件。如果下载失败（例如在离线环境中），请手动从 获取压缩包，并将 `OROITZ_PLUGIN_DIRS` 指向解压后的目录。
### 内存样本
**本仓库不包含任何内存镜像** —— 它们体积庞大且可能包含敏感数据。要获取经过批准的教学样本，请结合辅助脚本使用 `assets/samples.json`：
```
# 列出可用示例
python scripts/fetch_samples.py --list
# 下载一个示例到本地 (git-ignored) 的 samples/ 目录中
python scripts/fetch_samples.py --id samsclass-memdump
```
有关出处和许可指南，请参阅 `samples/README.md`。请核实您下载的任何样本的许可和使用条款，切勿将内存镜像提交到 git 中。
### 运行 Oroitz
- **CLI**：`poetry run python -m oroitz.cli --help`
- **快速分诊**：`poetry run python -m oroitz.cli quick-triage samples/your-image.mem --output results.json`
- **账户枚举**：`poetry run python -m oroitz.cli accounts samples/your-image.mem --output accounts.json`
- **TUI**：`poetry run python -m oroitz.ui.tui`
- **GUI**：`poetry run python -m oroitz.ui.gui`（需要 `gui` 依赖组）
工作流注册表（`oroitz/core/workflow.py`）定义了额外的工作流规范（`process_deepdive`、`network_focus`、`malware_hunt`、`timeline_overview` 等），但目前只有 `quick_triage` 和 `account_enumeration` 连接到了 CLI 和输出规范化流程。其余工作流可以在 UI 层中访问，但会产生未经规范化的结果 —— 参见 [`ROADMAP.md`](ROADMAP.md)。
### 构建与打包
Oroitz 可以使用 PyInstaller 打包成独立的可执行文件，以便在课堂上分发。
**在 Windows 上：**
```
.\build.ps1 install
.\build.ps1 build
```
**在 Linux/macOS 上：**
```
make install
make build
```
构建好的可执行文件会放在 `dist/` 目录下。当推送版本标签（例如 `v1.0.0`）时，GitHub Actions 发布工作流会为 Windows、macOS 和 Linux 构建可执行文件，并将它们附加到 GitHub 发布版中（参见 `.github/workflows/release.yml`）。
## 仓库结构
- `oroitz/core/`：协调 Volatility 3 执行、输出规范化、会话、缓存和本地日志记录的引擎
- `oroitz/cli/`：命令行界面（`quick-triage`、`accounts`、`tui`、`gui`）
- `oroitz/ui/gui/`：PySide6 桌面应用程序
- `oroitz/ui/tui/`：Textual 终端界面
- `oroitz/bindings/`：语言 SDK 实验（仅限 Python；Node.js 绑定目前只是一个想法，尚未实现）
- `samples/`：用于存放通过 `scripts/fetch_samples.py` 获取的内存镜像的本地且被 git 忽略的目录
- `tests/`：针对核心、CLI 和 UI 组件的自动化测试
- `docs/`：规格说明、ADR 和面向贡献者的指南（也同步在 [GitHub Wiki](https://github.com/tears-mysthrala/Oroitz/wiki) 上）
## 文档索引
### 用户指南
- [快速开始](https://github.com/tears-mysthrala/Oroitz/wiki/Getting-Started) - 安装与初步分析
- [CLI 用户指南](https://github.com/tears-mysthrala/Oroitz/wiki/CLI-Guide) - 命令行界面使用说明
- [GUI 用户指南](https://github.com/tears-mysthrala/Oroitz/wiki/GUI-Guide) - 桌面应用程序教程
- [TUI 用户指南](https://github.com/tears-mysthrala/Oroitz/wiki/TUI-Guide) - 终端界面指南
- [工作流参考](https://github.com/tears-mysthrala/Oroitz/wiki/Workflow-Reference) - 工作流文档
- [故障排除](https://github.com/tears-mysthrala/Oroitz/wiki/Troubleshooting) - 常见问题与解决方案
### 技术文档
- [产品规格说明](https://github.com/tears-mysthrala/Oroitz/wiki/Product-Specification)
- [核心引擎详情](https://github.com/tears-mysthrala/Oroitz/wiki/Core-Engine-Details)
- [TUI 规划](https://github.com/tears-mysthrala/Oroitz/wiki/TUI-Plan)
- [GUI 规划](https://github.com/tears-mysthrala/Oroitz/wiki/GUI-Plan)
- [工作流目录](https://github.com/tears-mysthrala/Oroitz/wiki/Workflow-Catalog)
- [架构决策](docs/adrs/)（也可在 Wiki 上查看）
- [项目结构指南](https://github.com/tears-mysthrala/Oroitz/wiki/Project-Structure-Guide)
## 安全
有关漏洞报告指南，请参阅 [`SECURITY.md`](SECURITY.md)。
## 许可证
MIT —— 参见 [`LICENSE`](LICENSE)。Volatility 3 保留其自身的许可证；请参阅[归属与许可](#attribution-and-licenses)。
## 发布准备与 CI
位于 `.github/workflows/ci.yml` 的 CI 流水线会运行测试套件和一项轻量级基准测试。使用 `tools/benchmark.py` 可运行本地基准测试并生成 `results/benchmark_report.json`。在标记发布版本之前，请查阅[发布检查清单](https://github.com/tears-mysthrala/Oroitz/wiki/Release-Checklist)。
标签：CLI, GUI, Python, SecList, TUI, Volatility 3, WiFi技术, 内存取证, 教学工具, 无后门, 漏洞挖掘, 逆向工具