cyber-traveller/MADFA

# MADFA — 恶意附件与文档取证分析器 **网络安全取证硕士 — 迷你项目** ## 为什么需要 大多数针对组织的入侵都始于武器化的附件 —— 包含 JavaScript 或启动动作的 PDF，或者是包含恶意 VBA 宏或嵌入式对象的 Office 文件。基于特征码的防病毒软件无法检测到经过混淆和以前未见的变体。MADFA 将**静态结构分析**与**机器学习**相结合，不仅可以标记可疑文档，*还能*生成调查人员真正需要的取证工件：哈希值、嵌入的 URL/IP、解码的宏字符串、匹配的 YARA 规则，以及透明的风险分解说明。 ## 功能 - 通过 **magic bytes**（而非扩展名）识别文件类型。 - 在输入时记录**证据哈希**（MD5/SHA1/SHA256）+ 模糊哈希（ssdeep/TLSH）。 - 静态提取：VBA 宏、PDF JavaScript、OpenAction/Launch 动作、嵌入式对象（OLE/OOXML）、DDE、外部关系、元数据、可疑的 API 关键字。 - 提取 **IOC**：URL、IP、域名、电子邮件、可疑字符串。 - 对原始字节和提取的流运行 **YARA** 规则。 - 构建数字**特征向量**，并使用训练好的模型进行分类（RandomForest / XGBoost；可选的 byte-image CNN）。 - 生成**风险评分 (0–100)** 和**可解释的**判定结果。 - 输出**JSON** 报告（机器可读）和 **HTML/PDF** 报告（分析人员可读）。 ## 它不做什么 它绝不执行、渲染或在其原生应用程序中打开样本。它不是沙箱，不是防病毒软件 (AV)，也不是恶意软件生成器或修复工具。所有分析都是**静态的**。 ## ⚠️ 安全警告 — 在接触真实样本前请务必阅读 恶意文档是活跃的恶意软件。仅在**隔离的虚拟机**中处理它们，并禁用网络连接和关闭共享文件夹/剪贴板。切勿双击样本。MADFA 仅*解析*文件，但操作者仍必须避免意外执行。 - 将所有样本保存在 `data/samples/` 下 — 此目录已被 **gitignored**。切勿将恶意软件提交到版本控制中。 - 在静止存储时，请对样本进行密码保护（例如，使用密码 `infected` 进行压缩）。 - 优先使用经过整理的研究数据集，而不是随意下载的数据集（参见 REQUIREMENTS.md）。 ## 快速开始 ``` # 1. 安装 (Python 3.11+; 有关系统库请参阅 REQUIREMENTS.md: yara, ssdeep, pango/cairo) python3 -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" # or: uv pip install -e ".[dev]" # 2. 分析单个文件 (将 .json/.html/.pdf 写入 out 目录) madfa analyze suspicious_invoice.docx --out reports/ # 3. 批量分析整个文件夹 (排名摘要 + 单文件报告) madfa scan-dir data/samples/malicious --out reports/ --recursive # 4. 从标记的样本构建特征数据集 (按 SHA256 去重) madfa dataset build --malicious data/samples/malicious --benign data/samples/benign \ --out data/features/dataset.csv # 5. 训练 + 比较 RandomForest / XGBoost (保存 models, meta.json, eval 图表) madfa train --dataset data/features/dataset.csv --out models/ # 6. 再次分析，现在使用训练好的模型 (ML 融合的风险评分) madfa analyze suspicious_invoice.docx --model models/xgboost.joblib --out reports/ ``` ### 命令参考 | 命令 | 用途 | |---------|---------| | `madfa version` | 打印工具版本 | | `madfa analyze ` | 分析单个文件 → 输出控制台判定结果 + JSON/HTML/PDF 报告 | | `madfa scan-dir ` | 批量分析文件夹 → 输出排名摘要 + 单个文件报告 | | `madfa dataset build` | 从带标签的样本目录构建特征 CSV | | `madfa dataset synth` | 生成**合成**数据集（无恶意软件）用于测试/演示 | | `madfa train` | 训练 + 评估 RandomForest / XGBoost；保存模型和图表 | `analyze` / `scan-dir` 的通用标志：`--out DIR`、`--model model.joblib`、 `--no-pdf`、`--json-only`、`--config config.yaml`（以及用于 `scan-dir` 的 `--recursive`）。 ### 示例：混合文件夹的批量扫描 ``` Batch scan summary ┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━┳━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━┓ ┃ File ┃ Type ┃ Verdict ┃ Risk ┃ IOCs ┃ YARA ┃ SHA256 ┃ ┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━╇━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━┩ │ invoice.pdf │ pdf │ malicious │ 75 │ 2 │ 2 │ d1ee02734684 │ │ letter.docx │ ooxml_office │ suspicious │ 65 │ 1 │ 1 │ 4bc00880bc28 │ │ report.pdf │ pdf │ benign │ 0 │ 0 │ 0 │ a5370b552632 │ │ notes.txt │ — │ skipped │ — │ — │ — │ — │ └─────────────┴──────────────┴────────────┴──────┴──────┴──────┴──────────────┘ malicious: 1 suspicious: 1 benign: 1 skipped: 1 ``` 单文件 `analyze` 会打印输入面板、提取的工件、IOC（已解除武装）、 YARA 匹配项，以及带有各项原因风险分解的彩色判定横幅。 ### 示例报告 请参阅 [`examples/`](examples/) 获取完整的生成报告（恶意 / 可疑 / 良性）， 包含 HTML 和 JSON 格式，均由无害的合成文档生成。 ## 文档导航 | 文件 | 用途 | |------|---------| | `CLAUDE.md` | 构建上下文与规则（请优先阅读） | | `ARCHITECTURE.md` | 系统设计、数据流、核心数据结构 | | `REQUIREMENTS.md` | 依赖项、系统库、数据集、环境 | | `MODULES.md` | 包含函数签名的逐模块规范 | | `ML_PIPELINE.md` | 特征、训练、评估以及 CNN 进阶目标 | | `FORENSIC_REPORT.md` | 报告 schema + 输出示例 | | `ROADMAP.md` | 分阶段构建计划与里程碑 | ## 开发 ``` pip install -e ".[dev]" pytest # full test suite (synthetic fixtures only — no malware needed) ruff check src tests mypy src/madfa ``` 流水线能够优雅降级：如果 `yara-python`、`ssdeep`/`tlsh`、`python-magic` 或 `weasyprint` 不可用，MADFA 仍会运行（跳过该功能），而不会发生崩溃失败。核心流水线仅需要 pydantic、oletools、pdfminer.six、jinja2、typer，以及（用于 ML 步骤的）scikit-learn / xgboost。 ## 许可证与学术声明 专为学术课程作业而构建。仅限对您获得授权进行分析的样本使用。

标签：Apex, Go语言工具, IOC提取, YARA, 云安全监控, 云资产可视化, 恶意文档分析, 搜索语句（dork）, 数字取证, 无服务器架构, 机器学习, 自动化脚本, 逆向工具, 静态分析