cooknoah/maat

# MAAT - 恶意软件分析自动化工具 MAAT 是一个 Python CLI 工具，用于自动化的**静态**恶意软件初步分类。将它指向一个可疑的 Office 文档、PE 二进制文件或 PDF，它将生成一份结构化的 HTML（以及可选的 JSON）威胁报告，其中包含哈希值、宏/对象发现、YARA 匹配项、可选的 VirusTotal 查询结果以及 0-10 的风险评分。 ## 支持的文件类型 | 类型 | 检测方式 | 分析后端 | | ---- | ------------ | ---------------- | | Office (`.doc`, `.docx`, `.xls`, `.xlsm`, `.ppt`, ...) | `python-magic` 魔数（对 OOXML 带有扩展名回退机制） | `oletools` (olevba, oleid, olefile) | | PE (`.exe`, `.dll`) | `application/x-dosexec` | `pefile` | | PDF | `application/pdf` | `pikepdf` | 未知类型会干净地退出并附带提示。 ## 安装说明 ``` git clone cd maat python -m pip install -r requirements.txt ``` `yara-python` 是**可选的**。在 Python 3.14 / Windows 上，它没有预编译的 wheel，需要 MSVC 构建工具从源码编译。当缺少该依赖时，MAAT 会优雅降级——报告中的 YARA 部分只会显示“unavailable”，并且 YARA 不会计入风险评分。要启用它： ``` pip install yara-python ``` 如果你想进行 VirusTotal 哈希查询，请将 `.env.example` 复制到 `.env` 并填入你的 API 密钥： ``` cp .env.example .env # 编辑 .env: VIRUSTOTAL_API_KEY=... ``` ## 使用方法 ``` python maat.py --file # HTML report python maat.py --file --json # HTML + JSON python maat.py --file --no-vt # skip VirusTotal lookup python maat.py --file --out # custom output directory (default ./reports/) ``` ### 示例 ``` python maat.py --file samples/jsdemo.pdf --no-vt python maat.py --file ./suspect.docm --json python maat.py --file ./malware.bin --out /tmp/reports ``` 报告将写入 `/_.html`（当传入 `--json` 参数时还会生成 `.json` 文件）。HTML 是完全自包含的——内联 CSS，无外部资源。 ## 示例输出 ## 检测能力 - 文件哈希：MD5、SHA1、SHA256（流式处理，可处理大文件） - 魔数文件类型检测（绝不单独信任扩展名） - **Office**：宏存在性、可疑 VBA 关键字扫描（`Shell`、`WScript`、`AutoOpen`、`AutoExec`、`Document_Open`、`CreateObject`、`powershell`、`http`、`https`、`cmd`、`environ`、`Chr`、`ChrW`、`StrReverse`）、完整宏源码转储、OLE 流列表 - **PE**：包含各节熵值的节表、加壳启发式检测（任何节的熵值 > 7.0）、完整的导入/导出列表、编译时间戳 - **PDF**：页数和标记对象：`/JavaScript`、`/JS`、`/Launch`、`/URI`、`/EmbeddedFile`、`/OpenAction`、`/AA` - **YARA**：内置规则用于检测 EICAR、可疑的 VBA 自动执行模式、编码的 PowerShell 启动器、嵌入的 HTTP/HTTPS URL - **VirusTotal**：仅查询 SHA256 哈希（不上传文件），在 `cache/` 下具有 7 天的文件系统缓存 - **风险评分**：0-10 分附带原因说明，在报告中以颜色编码的徽章显示 ## 获取 VirusTotal API 密钥 在 [virustotal.com](https://www.virustotal.com/) 创建一个免费帐户，并从 个人资料 -> API Key 中获取你的 API 密钥。公共 API 配额为每分钟 4 次请求，每天 500 次，这足以满足日常使用；MAAT 的文件系统缓存会减少大量重复请求。 ## 运行测试 ``` python -m pytest tests/ -v ``` 测试固件（良性 docx、包含 JS 的 PDF）在运行时生成，因此仓库中不会附带任何真实的恶意软件。 ## 免责声明 MAAT **仅用于教育和研究目的**。它仅执行静态分析——不包含沙箱，也不进行动态执行。其结果均基于启发式规则。请勿在你重视的机器上运行真实的恶意软件；请使用隔离的虚拟机（VM）。内置的 YARA 规则和关键字列表仅作说明用途，并非生产级别。 ## 项目结构 ``` maat/ ├── maat.py # CLI entrypoint ├── scoring.py # 0-10 risk scoring ├── analyzers/ │ ├── office.py # oletools │ ├── pe.py # pefile │ ├── pdf.py # pikepdf │ ├── virustotal.py # VT API v3 + cache │ └── yara_scan.py # YARA (optional) ├── rules/general.yar # bundled YARA rules ├── templates/report.html # Jinja2 HTML report template ├── samples/ # synthetic test fixtures ├── tests/ # pytest suite └── reports/ # generated reports (gitignored) ```

标签：DAST, DNS信息、DNS暴力破解, DNS 反向解析, HTML报告, Office宏分析, oletools, PDF安全检测, pefile, PE文件分析, pikepdf, Python安全工具, URL发现, VirusTotal集成, YARA规则, 二进制分析, 云安全监控, 云安全运维, 威胁情报, 安全检测, 库, 应急响应, 开发者工具, 恶意文件检测, 恶意软件分析, 搜索语句（dork）, 网络安全, 自动化分类, 逆向工具, 隐私保护, 静态分析