## 目录 - [概述](#overview) - [功能特性](#features) - [系统架构](#architecture) - [工具与 AI 模型](#tools--ai-models) - [项目结构](#project-structure) - [前置条件](#prerequisites) - [安装与配置](#installation--configuration) - [使用方法](#usage) - [Web 界面](#web-interface) - [命令行](#command-line) - [输出产物](#output-artefacts) - [局限性](#limitations) ## 概述 LMASMA 使用 [LangGraph](https://github.com/langchain-ai/langgraph) 编排由八个专门的分析智能体组成的流水线。这些智能体在可能的情况下并行运行——静态分析、沙箱引爆和代码分析均并发执行——它们的输出被合并成一份全面的威胁情报报告，涵盖文件元数据、网络活动、逆向工程发现、IOC 验证、多平台信誉评分以及 MITRE ATT&CK 技术映射。 该系统旨在分析 **Windows PE 可执行文件**（`.exe`、`.dll`、`.sys`）和 **Linux ELF 二进制文件**（`.elf`、`.so`、`.out`、`.bin`）。每次运行会产生四个输出产物：发现 JSON、Markdown 报告、自包含的 HTML 报告，以及一个包含来自四个威胁情报平台信誉数据的可下载 **IOCs CSV**。 ## 功能特性 ### 分析能力 - **静态分析 (Static Analysis)** — Shannon 熵、MD5/SHA1/SHA256/SSDeep 哈希、PE 头解析（导入、导出、各节熵值）、可打印字符串提取以及基于 9 种正则模式的 IOC 检测 - **动态沙箱引爆 (Dynamic Sandbox Detonation)** — 并发提交至 **VirusTotal v3** 和 **Hybrid Analysis (Falcon Sandbox)**；自动检测操作系统以选择正确的环境；完整的网络行为提取（DNS、HTTP、IP、域名、C2 指标） - **反编译 (Decompilation)** — Ghidra 无头伪代码生成，覆盖前 20 个函数，按网络/加密/持久化相关性优先排序；当 Ghidra 不可用时回退到字符串提取 - **反汇编 (Disassembly)** — 基于 radare2 的汇编提取，涵盖导入、导出、字符串、函数、逐函数反汇编和交叉引用 - **AI 代码审查 (AI Code Review)** — 将反编译器和反汇编器的输出跨智能体综合为结构化发现：关键函数、可疑模式、网络相关代码及直接在代码中发现的 IOC - **IOC 验证 (IOC Validation)** — 汇总来自所有四个分析源的原始 IOC 字符串；分类为 14 种类型；过滤私有 IP、良性域名（Microsoft、Google、Apple、GitHub、CA）以及可执行文件名的误报；通过完整的 Base58Check 校验和验证比特币地址 - **信誉检查 (Reputation Checking)** — 并发多平台查询（VirusTotal、MalwareBazaar、MetaDefender、AbuseIPDB）；按 IOC 类型适用性过滤；加权判定评分（MALICIOUS / SUSPICIOUS / CLEAN / UNKNOWN） - **MITRE ATT&CK 映射** — 基于观察到的能力和行为，由 Gemini 生成 TTP 建议 ### 报告与导出 - **AI 生成的叙述** — Google Gemini 生成完整的 9 节 Markdown 报告（执行摘要、文件元数据、网络活动、动态分析、代码分析、代码审查、MITRE ATT&CK、指标摘要、建议） - **截断预防** — 65,536 输出 token 限制 + MAX_TOKENS 检测 + 启发式完整性检查 + 最多 2 次自动续写，确保报告完整 - **自包含 HTML 报告** — 粘性导航、侧边栏目录、统计卡片、颜色编码的信誉徽章、可折叠的 IOC 和信誉表、服务端渲染的 Markdown AI 部分 - **IOC CSV 导出** — 12 列富化 CSV（值、类型、置信度、来源、判定、VT 计数、MalwareBazaar、MetaDefender、AbuseIPDB 评分）；可通过 Web UI 下载，并作为 `data:` URI 直接嵌入 HTML 报告侧边栏以便离线访问 ### 可靠性与容错 - **自动速率限制处理** — VirusTotal 429 触发密钥轮换（主密钥 → 备用密钥 → 用户提示的临时密钥）；Gemini 429 解析响应体中的 `retryDelay` 提示 - **优雅降级** — 每个外部依赖（Ghidra、radare2、ssdeep、沙箱 API）都有回退方案；任何单一故障不会中止流水线 - **非致命错误累积** — 所有错误均被收集并显示在最终报告中；流水线始终产生输出 - **任务持久化** — Flask 任务状态可在服务器重启后保留；进行中的任务在启动时自动标记为失败 ### Web 界面 - 拖放文件上传，带有实时进度反馈 - 分析期间各阶段流水线动画 - 报告 iframe 加载前 15 秒倒计时 - 五种一键下载格式：HTML 报告、Markdown、发现 JSON、IOCs CSV ## 系统架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ PRESENTATION TIER │ │ Browser ──► Flask (app.py) ──► Background Thread │ └────────────────────────┬────────────────────────────────────┘ │ run_analysis(file_path) ┌────────────────────────▼────────────────────────────────────┐ │ ORCHESTRATION TIER │ │ LangGraph StateGraph · AnalysisState │ └──────┬─────────────────┬────────────────────────┬───────────┘ │ │ │ StaticAnalyser DynamicAnalyser CodeReviewer │ │ ┌───┴────┐ │ │ Decompiler Disassembler │ │ └───┬────┘ └─────────────────┴──────┬────────────────┘ IOCValidator ◄── CodeReviewSummarizer │ ReputationChecker │ PreReportBarrier (fan-in) │ ReportGenerator │ findings.json · report.md · report.html · iocs.csv ``` 三个顶级分支（StaticAnalyser、DynamicAnalyser、CodeReviewer→Decompiler+Disassembler）**并发**运行。扇入屏障节点确保 ReportGenerator 仅在每个前置智能体完成后才触发。 ## 工具与 AI 模型 ### AI 模型 | 智能体 | 提供商 | 模型 | 用途 | |---|---|---|---| | Decompiler | [Groq](https://console.groq.com) | `moonshotai/kimi-k2-instruct` | 从 Ghidra 伪代码中提取行为情报；262K 上下文窗口 | | Disassembler | [Groq](https://console.groq.com) | `meta-llama/llama-4-scout-17b-16e-instruct` | 从反汇编中提取行为情报；30K TPM，750 t/s | | Code Review Summarizer | [Groq](https://console.groq.com) | `llama-3.3-70b-versatile` | 跨智能体综合为结构化的 `CodeReviewSummary` | | Report Generator | [Google AI Studio](https://aistudio.google.com) | `gemini-2.5-flash` | 完整的 9 节叙述性报告；最高 65,536 输出 token | ### 威胁情报平台 | 平台 | IOC 类型 | 免费层级 | |---|---|---| | [VirusTotal](https://www.virustotal.com) | IP, Domain, URL, Hash | ✓ 500 请求/天 | | [MalwareBazaar](https://bazaar.abuse.ch) | 仅 Hash | ✓ 需要 Auth-Key | | [MetaDefender](https://metadefender.opswat.com) | 仅 Hash | ✓ | | [AbuseIPDB](https://www.abuseipdb.com) | 仅 IP | ✓ | ### 沙箱平台 | 平台 | 免费层级 | 备注 | |---|---|---| | [VirusTotal](https://www.virustotal.com) | ✓ | 沙箱引爆 + 行为报告 | | [Hybrid Analysis](https://hybrid-analysis.com) | ✓ | 文件提交需要一次性审核 | ### 逆向工程工具 | 工具 | 用途 | 是否必需？ | |---|---|---| | [Ghidra](https://ghidra-sre.org) | 无头反编译、伪代码生成 | 可选（回退到 `strings`） | | [radare2](https://rada.re) | 反汇编、函数分析、交叉引用 | 可选（回退到 `strings`） | | `strings` (binutils) | 从二进制文件提取字符串 | 推荐 | | `file` (libmagic) | 二进制类型检测 | 推荐 | ## 项目结构 ``` lmasma/ ├── app.py # Flask web frontend ├── graph.py # LangGraph orchestrator (entry point) ├── state.py # Shared state models (Pydantic + TypedDict) ├── requirements.txt # Python dependencies ├── .env # API keys (create from .env.example) │ ├── agents/ │ ├── __init__.py │ ├── static_analyser.py # PE parsing, entropy, hashes, string/IOC extraction │ ├── dynamic_analyser.py # VirusTotal + Hybrid Analysis sandbox integration │ ├── decompiler.py # Ghidra headless + Groq Kimi K2 │ ├── disassembler.py # radare2 + Groq LLaMA-4 Scout │ ├── code_review_summarizer.py # Groq LLaMA-3.3 synthesis │ ├── ioc_validator.py # IOC classification, filtering, deduplication │ ├── reputation_checker.py # Multi-platform TI lookups │ └── report_generator.py # Gemini report + HTML builder + IOC CSV │ ├── models/ │ └── state.py # Pydantic models: NetworkActivity, BehaviorSummary, etc. │ ├── utils/ │ └── logger.py # Rich-enhanced logger │ ├── uploads/ # Uploaded samples (auto-created) ├── reports/ # All output artefacts (auto-created) └── jobs.json # Persistent job store (auto-created) ``` ## 前置条件 ### Python 需要 Python **3.11 或更高版本**。 ``` python --version # must be 3.11+ ``` ### 系统软件包 **Debian / Ubuntu:** ``` sudo apt update sudo apt install -y \ binutils \ file \ libmagic1 \ libfuzzy-dev \ radare2 ``` **macOS (Homebrew):** ``` brew install binutils file libmagic ssdeep radare2 ``` **Windows:** - 安装 [binutils for Windows](https://sourceware.org/binutils/) 或使用 WSL2（推荐） - 安装 [radare2 发布版](https://github.com/radareorg/radare2/releases) - Windows 上的 python-magic 需要：`pip install python-magic-bin` ### Ghidra（可选 — 强烈推荐） 1. 从 [ghidra-sre.org](https://ghidra-sre.org) 下载 2. 解压到目录（例如 `/opt/ghidra_11.0`） 3. Java 17+ 必须在您的 `PATH` 中（Debian 上使用 `apt install openjdk-17-jdk`） 4. 在您的 `.env` 文件中设置 `GHIDRA_INSTALL_DIR`（见下方配置） ## 安装与配置 ### 1. 克隆仓库 ``` git clone https://github.com/your-org/lmasma.git cd lmasma ``` ### 2. 创建虚拟环境 ``` python -m venv venv source venv/bin/activate # Linux / macOS # 或 venv\Scripts\activate.bat # Windows ``` ### 3. 安装 Python 依赖 ``` pip install -r requirements.txt ``` ### 4. 创建您的 `.env` 文件 复制示例文件并填入您的 API 密钥： ``` cp .env.example .env ``` 打开 `.env` 并配置以下变量： ``` # ── 必需：LLM providers ─────────────────────────────────────────── # 在此获取免费 Groq key：https://console.groq.com GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx # 在此获取免费 Gemini key：https://aistudio.google.com/apikey GEMINI_API_KEY=AIzaSy_xxxxxxxxxxxxxxxxxxxx # ── 推荐：Sandbox detonation ─────────────────────────────────── # 免费 VirusTotal key：https://www.virustotal.com (注册 → API key) VIRUSTOTAL_API_KEY=your_virustotal_key_here # 免费 Hybrid Analysis key：https://hybrid-analysis.com (注册 → Profile → API key) # 注意：File submission 需要 key vetting — 请参阅 Profile → API key → "Upgrade API key" HYBRID_ANALYSIS_API_KEY=your_hybrid_analysis_key_here # ── 可选：用于自动 429 rotation 的备用 VT key ───────────── VIRUSTOTAL_API_KEY_2=your_backup_vt_key # ── 可选：Additional TI platforms ───────────────────────────────── # MalwareBazaar (免费 key)：https://auth.abuse.ch MALWAREBAZAAR_API_KEY=your_malwarebazaar_key # MetaDefender (免费 key)：https://metadefender.opswat.com METADEFENDER_API_KEY=your_metadefender_key # AbuseIPDB (免费 key)：https://www.abuseipdb.com ABUSEIPDB_API_KEY=your_abuseipdb_key # ── 可选：Ghidra decompiler ──────────────────────────────────────── GHIDRA_INSTALL_DIR=/opt/ghidra_11.0 # ── 可选：Override default AI models ────────────────────────────────── GROQ_DECOMPILER_MODEL=moonshotai/kimi-k2-instruct GROQ_DISASSEMBLER_MODEL=meta-llama/llama-4-scout-17b-16e-instruct GROQ_CODEREVIEW_MODEL=llama-3.3-70b-versatile GEMINI_MODEL=gemini-2.5-flash ``` ### 5. 验证系统依赖（可选检查） ``` # Check strings utility strings --version # Check file / libmagic file --version # Check radare2 r2 -v # Check Ghidra $GHIDRA_INSTALL_DIR/support/analyzeHeadless --help 2>&1 | head -5 ``` ## 使用方法 ### Web 界面 启动 Flask 服务器： ``` python app.py ``` 然后在浏览器中打开 **http://localhost:5000**。 ``` Custom port: PORT=8080 python app.py ``` **步骤：** 1. 拖放（或点击选择）一个 `.exe`、`.dll`、`.elf`、`.bin`、`.so` 或 `.sys` 文件 2. 点击 **Start Analysis（开始分析）** 3. 观察流水线阶段动画，随着每个智能体完成而更新 4. 当分析完成时（通常为 5–20 分钟，具体取决于沙箱响应时间），完整的 HTML 报告将在浏览器中加载 5. 使用 **Download（下载）** 按钮保存 HTML 报告、Markdown、发现 JSON 或 IOCs CSV 6. IOC CSV 也可通过报告侧边栏中的绿色 **Download IOCs CSV** 按钮获取——因为它直接嵌入在 HTML 中，所以可以离线使用 ### 命令行 直接分析文件而无需启动 Web 服务器： ``` # 基本用法 — 输出到 reports/ python graph.py /path/to/sample.exe # 自定义输出目录 python graph.py /path/to/sample.exe --output /tmp/my_analysis ``` **输出：** ``` ✅ Analysis complete. Markdown : reports/report_sample_20250101_120000.md HTML : reports/report_sample_20250101_120000.html Findings : reports/findings_sample_20250101_120000.json ``` IOC CSV（`reports/iocs_sample_20250101_120000.csv`）也会与这些文件一起写入。 ### 编程方式使用 ``` from graph import run_analysis report_path = run_analysis( file_path="/path/to/malware.exe", output_dir="reports" ) print(f"Report: {report_path}") ``` ## 输出产物 每次分析运行都会在输出目录中生成四个文件： | 文件 | 模式 | 描述 | |---|---|---| | **Findings JSON** | `findings__.json` | 完整的序列化分析状态——所有原始智能体输出，适合程序化处理或重新输入给 Gemini | | **Markdown Report** | `report__.md` | Gemini 生成的 9 节叙述性报告，包含 MITRE ATT&CK 映射，可直接导入 Wiki 或工单系统 | | **HTML Report** | `report__.html` | 自包含的样式化报告；无需服务器即可查看——在任何浏览器中直接打开。包含 IOC CSV 作为嵌入的下载项 | | **IOC CSV** | `iocs__.csv` | 12 列富化 IOC 表，可直接用于 SIEM 接入、威胁搜寻或进一步分流 | ### IOC CSV 列 ``` value, ioc_type, confidence, sources, verdict, vt_malicious, vt_suspicious, malware_bazaar_found, malware_bazaar_signature, metadefender_detected, metadefender_total_avs, abuseipdb_confidence_score ``` ## 局限性 ### 沙箱与 API 限制 - **免费层级速率限制** — VirusTotal（500 请求/天，4 次/分钟）、Groq（因模型而异）、Gemini（免费层级配额）可能导致高容量使用时出现延迟或临时失败。系统通过自动重试和退避机制优雅地处理这些情况，但在达到限制时，分析时间可能会显著增加。 - **Hybrid Analysis 审核** — 向 Hybrid Analysis 提交文件需要一次性人工审核您的 API 密钥（Profile → API key → Upgrade）。在通过审核之前，HA 后端不可用，仅收集 VirusTotal 沙箱数据。 - **沙箱分析时间** — 两个沙箱后端都可能需要 10–20 分钟来完成引爆并返回结果。总流水线时间取决于最慢的沙箱。 - **无私有沙箱** — 所有样本均提交至公共云沙箱（VirusTotal 和 Hybrid Analysis）。请勿**提交机密、专有或个人身份识别相关的二进制文件。 ### 反编译与反汇编 - **Ghidra 是可选的** — 如果没有它，反编译智能体将回退到简单的字符串提取，这将提供明显较少的行为情报。Ghidra 需要 Java 17+ JDK 和至少约 4 GB 的 RAM。 - **加壳/混淆样本** — 高度加壳或虚拟化的可执行文件（例如 VMProtect、Themida）可能产生极少的伪代码或反汇编。静态分析部分中的熵值将指示加壳情况（>7.0）。 - **macOS / iOS / Android 二进制文件** — 该系统针对 Windows PE 和 Linux ELF 目标进行了优化。Mach-O、DEX 和 APK 格式未受明确支持，可能产生不完整的结果。 - **Ghidra 超时** — Ghidra 无头分析超时固定为 180 秒。非常大或复杂的二进制文件可能会超时并回退到字符串提取。 ### AI 模型限制 - **LLM 幻觉** — AI 生成的部分（反编译器/反汇编器行为摘要、代码审查、Gemini 叙述）可能包含不准确或虚构的细节。所有 AI 输出应视为分析辅助，而非基本事实，并应与结构化数据部分进行核对。 - **Token 预算限制** — 反编译器仅将伪代码的前 12,000 个字符发送给 LLM，反汇编器仅将反汇编代码的前 20,000 个字符发送给 LLM。具有许多函数的大型二进制文件，其代码分析将被截断为最高优先级的函数（网络 → 加密 → 持久化 → 其他）。 - **Groq 免费层级模型可用性** — Groq 偶尔会轮换或弃用免费层级模型。如果模型变得不可用，请通过 `GROQ_DECOMPILER_MODEL`、`GROQ_DISASSEMBLER_MODEL` 或 `GROQ_CODEREVIEW_MODEL` 环境变量进行覆盖。 - **Gemini 报告完整性** — 尽管有 65,536 token 限制和续写逻辑，但在不利的 API 条件下，极其详细的分析状态（许多 IOC、大型网络部分）仍可能产生截断的报告。 ### 平台与环境 - **内存中任务存储** — 任务历史记录存储在磁盘上的 `jobs.json` 中。在高并发部署中，基于文件的持久化可能成为瓶颈。对于生产环境，请替换为 Redis 或数据库。 - **无身份验证** — Flask Web 界面没有内置身份验证。请勿在未将其置于具有身份验证的反向代理（nginx + HTTP Basic Auth，或身份感知代理）之后的情况下，将端口 5000 暴露于公共互联网。 - **单机部署** — 流水线作为单个 Flask 进程内的后台线程运行。如果不对任务管理层进行重大重构，它并非为分布式或容器化多工作进程部署而设计。 - **文件大小限制** — 上传限制为 64 MB。VirusTotal 的标准上传端点有 32 MB 的限制；介于 32–64 MB 之间的文件会自动通过 VT 的 `upload_url` 端点路由。 - **Windows 支持** — 该系统主要在 Linux 和 macOS 上进行测试。Windows 支持是可能的，但需要 WSL2 或手动安装 binutils、libmagic 和 radare2 等效组件。

_{使用 LangGraph · Groq · Google Gemini · VirusTotal · Hybrid Analysis · Ghidra · radare2 构建}

标签：Amass, AMSI绕过, DAST, DLL 劫持, ELF 文件分析, Findomain, Flask, FTP漏洞扫描, Gemini, IP 地址批量处理, LangGraph, MITRE ATT&CK 映射, PE 文件分析, PyRIT, Python, 二进制分析, 云安全监控, 云安全运维, 云资产清单, 多智能体系统, 大语言模型, 威胁检测, 安全编排, 恶意软件分析, 无后门, 沙箱 detonation, 端到端分析, 结构化查询, 网络信息收集, 网络安全, 网络安全审计, 自动化威胁情报, 自动化安全, 逆向工具, 逆向工程, 隐私保护, 静态分析