Abdelrahman-El-Maghraby/hybrid-ransomware-detector
GitHub: Abdelrahman-El-Maghraby/hybrid-ransomware-detector
一个融合密码学哈希、模糊哈希、宏分析、YARA 规则、VirusTotal 和本地 LLM 语义分析的多层勒索软件及恶意文档检测系统，通过加权评分矩阵输出可解释的风险评估报告。
Stars: 0 | Forks: 0
# 🛡️ 混合勒索软件检测系统
这是一款多层扫描程序，用于检测 **PDF 和 Microsoft Word 文档** 中的勒索软件及其他恶意特征。它融合了**七个独立的检测信号** —— 密码学哈希、本地恶意软件哈希数据集、**模糊/结构化哈希**、**VBA 宏分析**、**YARA 规则引擎**、通过 VirusTotal 的多引擎信誉检测，以及**本地优先的 LLM** 语义分析 —— 通过一个**透明且可解释的加权评分矩阵**，生成 0–100 的风险评分、一个判定等级，以及一份展示每个文件*为什么*会获得该评分的可读报告。
它可以在 **Windows、macOS 和 Linux**（x86_64 和 ARM64 架构）上运行，并支持在每个平台上选择开机/登录时自动启动。
该项目最初作为我的计算机科学学士毕业项目（成绩：B+）开发，是一个三层扫描程序，随后扩展了结构化检测（模糊哈希、宏分析、YARA）、保留 OPSEC 的本地 LLM 选项以及加权评分矩阵。它专用于**防御和教育目的** —— 用于分析可疑文档，而非制造恶意软件。
## 📖 目录
- [🧩 为什么叫“混合”？](#-why-hybrid)
- [🔬 检测层](#-detection-layers)
- [✨ 功能](#-features)
- [📦 依赖要求](#-requirements)
- [🚀 安装说明](#-installation)
- [🔑 配置](#-configuration)
- [💻 使用说明](#-usage)
- [🪟 图形界面](#-graphical-interface)
- [📂 项目结构](#-project-structure)
- [🌐 跨平台与架构说明](#-cross-platform--architecture-notes)
- [🧭 路线图](#-roadmap)
- [🚨 免责声明](#-disclaimer)
- [👤 作者](#-author)
## 🧩 为什么叫“混合”？
大多数轻量级扫描程序依赖于单一技术（通常是哈希查找），这会漏掉任何尚未被数据库收录的内容。该工具叠加了七种互补的方法 —— 精确匹配、结构化、行为、信誉和语义分析 —— 因此只要被**其中任何一种**方法标记的文件都会被暴露出来，并且**加权评分矩阵**确保判定结果反映了触发的是*哪种*证据（宏中真实的执行原语比钓鱼意味的句子重要得多）：
```
flowchart TD
A[PDF / Word file] --> B[1. MD5 / SHA-256
chunked hashing] A --> C[2. Local hash DB
exact known-bad] A --> D[3. Fuzzy hashing
TLSH / ssdeep family match] A --> E[4. VBA macro analysis
olevba dropper triage] A --> F[5. YARA rules
structural IOCs] A --> G[6. VirusTotal
multi-engine reputation] A --> H[7. LLM semantic
local-first, OPSEC-safe] B --> M[Weighted scoring matrix] C --> M D --> M E --> M F --> M G --> M H --> M M --> N[Risk 0-100 + verdict band
+ explainable JSON / TXT report] ``` 这些信号分为三个权重类别 —— **技术类**（哈希数据库、模糊哈希、宏分析、YARA）、**信誉类**（VirusTotal）和**语义类**（LLM）—— 并且在数学设计上，技术证据的权重高于语义证据。 ## 🔬 检测层 1. **密码学哈希（静态）。** 使用高效的**分块读取**（无论文件大小，内存占用恒定）计算文件的 MD5 **和 SHA-256**。 2. **本地哈希数据库（确知恶意）。** 将 MD5 与加载到 **O(1) 查找集合**中的已知恶意哈希**流式 CSV** 进行比对。可即时、离线检测已知样本。 3. **模糊/结构化哈希（多态家族）。** 计算 **TLSH** 和 **ssdeep**（通过纯 Python 实现的 `ppdeep`）摘要，并将它们与*已确认*恶意样本的签名数据库进行比较。由于这些摘要在文件保持*结构相似*时也会保持*相似*，因此这可以捕获那些精确 SHA-256 从未被记录的多态变体——这正好填补了精确哈希黑名单留下的漏洞。匹配距离/相似度会作为证据上报。 4. **VBA 宏分析（Office 投递机制）。** 使用 **`oletools` / `olevba`** 静态提取并对内嵌的 VBA/XLM 宏进行分类，**且绝不执行它们**。它将发现分为自动运行触发器（`AutoOpen`、`Document_Open` 等）、执行/下载原语（`Shell`、`CreateObject`、`URLDownloadToFile`、`powershell` 等）、其他可疑调用以及提取的 IOC。一个自动运行触发器**结合**执行原语是经典的木马投递模式，并将据此进行评分。 5. **YARA 规则引擎（结构化 IOC）。** 编译 `rules/` 中的每个 `.yar` / `.yara` 文件（带命名空间），并根据这些规则扫描每个文件。规则附带一个 `severity` 元属性（`low`/`medium`/`high`/`critical`），评分矩阵会读取该属性。内置规则是针对勒索信语言、勒索+紧急性组合、带支付上下文的比特币地址、PowerShell 下载器和 Office 投递结构的原始分诊启发式规则 —— 你可以放入自己的规则来扩展覆盖范围。仅记录匹配的**字符串标识符**，绝不记录原始的匹配字节。 6. **VirusTotal（威胁情报）。** 将文件哈希提交给 VirusTotal v3 API，并读取标记它的引擎数量，从而得出检测率。 7. **LLM 语义分析（本地优先，保留 OPSEC）。** 提取可见的文档文本（PyPDF2 / python-docx，对于扫描版 PDF 通过 Tesseract + Poppler 提供 **OCR 回退**），以及原始的可打印字符串，询问 LLM 该内容是否看起来像钓鱼/勒索软件诱饵，并返回置信度评分和可疑元素列表。 - **默认保留 OPSEC。** 后端是可插拔的。当设置 `LLM_PROVIDER=auto`（默认值）时，如果扫描器能访问到**本地 Ollama** 模型，它会优先使用它，因此**潜在敏感的文档永远不会离开本机**。只有在没有可用的本地模型*且*设置了 API 密钥时，它才会回退到云端（OpenAI）；每一次云端调用都会被记录为外发流量。将 `LLM_PROVIDER` 设置为 `ollama` 可强制仅使用本地，或者设置为 `none` 以禁用该层。 - **Prompt 注入防御。** 不受信任的文件内容以单独的 **user**（用户）角色传递，与 **system**（系统）指令分开，并且模型在 `temperature = 0` 下运行，从而增强了防御恶意文档试图诱导模型给出“安全”判定结论的能力。 ### 加权评分矩阵 最初硬编码的严重性公式（`10·db + 5·llm + 5·vt`）赋予*语义*信号与多引擎信誉相同的权重，并且无法体现结构化指标比可疑句子更致命这一事实。它已被**透明且可解释的加权矩阵**（`detectors/scoring.py`）所取代。每个信号都通过一条明确的规则产生影响，该规则包含一个**类别**、一个**权重**和一条人类可读的**详细信息**，遵循以下三个原则： 1. **在数学上，技术 > 语义。** 技术指标（本地数据库命中、YARA、宏执行原语、模糊家族匹配）具有最高的权重。语义 (LLM) 类别具有**极低的上限**，因此网络钓鱼诱饵本身永远不可能超过真正的结构化指标的分数。 2. **仅凭语义不能被评为“High”。** 如果没有触发技术或信誉信号，无论 LLM 对文档内容的判断有多确信，判定结果最多被限制为 **Medium**。 3. **可解释性。** 结果包含完整的按指标细分的分析，因此报告可以准确显示是哪些信号推动了判定结果以及具体贡献了多少分。 系统会产生两个分数：一个是带有判定等级区间的精细**风险评分（0–100）**；另一个是保留的**遗留严重性分数（0–10）**（`risk / 10`），以确保现有的报告、GUI 和测试能够继续工作 —— 纯本地数据库命中依然会产生精确的 `10.0`，而干净文件为 `0.0`。 | 风险评分 | 判定等级 | |-----------:|---------| | 0 | Clean (干净) | | 1–24 | Low (低) | | 25–49 | Medium (中) | | 50–79 | High (高) | | 80–100 | Critical (严重) | 只要有任何一层被触发，该文件就会被标记为**恶意**。**每一个可选层都会优雅降级** —— 缺失的库（`python-tlsh`、`ppdeep`、`oletools`、`yara-python`）、缺失的本地模型或缺失的 API 密密钥只会产生警告，而不会导致崩溃，其余的检测层仍会继续运行。 ## ✨ 功能 - 扫描跨越一个或多个目录的 `.pdf`、`.docx` 和 `.doc` 文件。 - **七个独立的检测层**通过一个透明、**可解释的加权评分矩阵**进行融合（风险评分 0–100 + 判定等级，并附带每个文件的完整证据链）。 - **结构化检测**能够抵御多态和混淆：模糊哈希（TLSH/ssdeep）、静态 VBA 宏分诊（olevba），以及你可以使用自己的规则进行扩展的 YARA 引擎。 - **保留 OPSEC 的 LLM 层** —— 默认使用本地 Ollama，从而使敏感文档保留在本机，仅在明确可用时回退到云端；云端外发流量会被记录。 - **桌面 GUI** (`gui.py`) —— 深色主题的仪表板，包含实时扫描进度、逐层结果细分、报告浏览器、数据集导入、实时日志和设置。CLI 仍然保持完全独立。 - 可以通过 CLI 进行单文件扫描和模糊哈希辅助（`--scan-file`、`--fuzzy-hash`），以便快速分类并扩充你的签名数据库。 - OCR 回退机制，确保仅包含图像/扫描版的 PDF 也能被分析。 - 详细的 **JSON** 报告 + 每次扫描人类可读的 **TXT** 摘要，按判定等级分组。 - 预定的后台扫描（默认：每 6 小时一次）。 - **跨平台开机自启动** —— Windows（注册表）、macOS（launchd）、Linux（systemd 用户服务，带有 cron 回退）。 - 可选的桌面快捷方式/启动器（Windows `.lnk`，Linux `.desktop`）。 - 文件 + 控制台日志记录。 ## 📦 依赖要求 **Python：** 3.9+（参见 `requirements.txt` —— 所有依赖项均提供 x86_64 和 ARM64 架构的 wheel 包，因此安装过程不需要编译器）。 **检测层库（可选，推荐）。** 结构化检测层使用 `python-tlsh` + `ppdeep`（模糊哈希）、`oletools`（宏分析）和 `yara-python`（YARA）。它们都在 Windows/macOS/Linux 上为 x86_64 和 ARM64 架构提供了预编译的 wheel 包（或者是纯 Python 编写），因此 `pip install -r requirements.txt` 可以直接拉取它们而无需编译器。如果缺少其中任何一项，该层将被跳过。 **本地 LLM（可选，用于 OPSEC）。** 为了将文档保留在本机，请安装 **[Ollama](https://ollama.com)** 并拉取一个模型，然后扫描器会自动使用它： ``` ollama pull llama3.1 # or any chat model you prefer # 扫描器自动检测运行在 http://localhost:11434 的 Ollama ``` 不需要额外的 Python 包 —— 扫描器通过 HTTP 与 Ollama 通信。如果 Ollama 未运行且未设置 OpenAI 密钥，则语义层将被跳过。 **系统软件包 —— Tesseract OCR + Poppler。** 这些是外部程序（非 Python 包），由 `pytesseract` 和 `pdf2image` 在底层调用。它们仅在需要对**扫描版/纯图像 PDF 进行 OCR 回退**时才需要；扫描器的其他功能在没有它们的情况下也能正常工作。 - **Windows：** 安装 **Tesseract OCR** 和 **Poppler**，并将它们添加到你的 `PATH` 中。 - **macOS：** `brew install tesseract poppler` - **Linux (Debian/Ubuntu)：** `sudo apt-get install tesseract-ocr poppler-utils` **仅针对 GUI —— Tkinter。** 已内置于 Windows 和 macOS 的官方 Python 安装程序中。在最小化安装的 Linux 系统上需运行：`sudo apt-get install python3-tk`。 ## 🚀 安装说明 ``` git clone https://github.com//hybrid-ransomware-detector.git
cd hybrid-ransomware-detector
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS / Linux: source .venv/bin/activate
pip install -r requirements.txt
```
## 🔑 配置
API 密钥和 LLM 后端从本地的 `.env` 文件加载，并且**绝不**存储在代码中。
```
cp .env.example .env # Windows: copy .env.example .env
```
然后编辑 `.env`。关键设置如下：
```
LLM_PROVIDER=auto # auto | ollama | openai | none
OLLAMA_HOST=http://localhost:11434 # used by auto/ollama
OLLAMA_MODEL=llama3.1
OPENAI_API_KEY= # leave blank to stay fully local
VIRUSTOTAL_API_KEY=your-virustotal-api-key
```
###恶意软件哈希数据集
本地数据库是一个 CSV 文件，至少包含 `FileName`、`md5Hash` 和 `Benign` 列（其中 `Benign = 0` 标记为恶意条目）。通过以下方式导入：
```
python RansomwareScanner.py --import-database /path/to/your/dataset.csv
```
一个合适的数据集可以从 Kaggle 上的公开恶意软件哈希集合中获取。（该数据集本身被刻意**不**提交到此仓库中。）
### 模糊签名数据库
模糊哈希通过将文件与*已确认的*恶意样本的摘要进行比对来匹配文件。要建立你自己的数据库，请打印某个样本的摘要并将其粘贴到签名条目中：
```
python RansomwareScanner.py --fuzzy-hash /path/to/confirmed_sample
```
签名文件（`fuzzy_signatures.json`，格式记录在内置的 `fuzzy_signatures.sample.json` 中）如下所示：
```
{
"version": 1,
"signatures": [
{"family": "Acme.Locker", "tlsh": "T1...", "ssdeep": "3:...", "note": "source / provenance"}
]
}
```
在 `.env` 文件中通过 `FUZZY_SIGNATURE_DB` 指向它（否则扫描器将使用内置的示例）。**切勿提交真实的恶意软件** —— 只需提交它的模糊摘要。
### YARA 规则
`rules/` 中的每个 `.yar` / `.yara` 文件都会被自动编译。在此添加你自己的文件（或将 `YARA_RULES_DIR` 指向其他位置）。给每个规则添加一个 `severity` 元属性（`low`/`medium`/`high`/`critical`），以便评分矩阵对其进行加权。
## 💻 使用说明
```
# 启动图形界面
python gui.py
# （等效）
python RansomwareScanner.py --gui
# 立即运行一次性扫描
python RansomwareScanner.py --scan-now
# 扫描单个文件并打印其完整的多层判定结果
python RansomwareScanner.py --scan-file suspicious.docx
# 为单次运行覆盖 LLM 后端（例如：强制仅使用本地或禁用它）
python RansomwareScanner.py --scan-file suspicious.docx --llm-provider ollama
python RansomwareScanner.py --scan-now --llm-provider none
# 打印文件的 fuzzy digests（以添加到您的 signature DB）
python RansomwareScanner.py --fuzzy-hash confirmed_sample.bin
# 在后台持续运行计划扫描
python RansomwareScanner.py --background
# 导入 / 更新本地 hash 数据集
python RansomwareScanner.py --import-database dataset.csv
# 登录时自动启动（自动检测 Windows / macOS / Linux）
python RansomwareScanner.py --setup-autostart
python RansomwareScanner.py --remove-autostart
# 桌面快捷方式 / 启动器（Windows 和 Linux）
python RansomwareScanner.py --create-shortcut
```
扫描目录、文件扩展名和扫描间隔在 `RansomwareScanner.py` 顶部的 `CONFIG` 代码块中配置。所有路径都是通过 `pathlib` 从用户的主目录派生出来的，因此它们会自动适应宿主操作系统。
## 🪟 图形界面
使用 CustomTkinter 构建的桌面前端，它将扫描器作为库调用 —— CLI 的工作方式与以前完全相同，并且两者共享相同的配置、报告和哈希数据库。
**仪表板。** 每个检测层都有一个状态卡片 —— 哈希数据库、模糊哈希（包含签名数量）、宏分析、YARA（包含规则文件数量）、VirusTotal，以及 LLM 层（显示其**本地 (LOCAL) 与云端 (CLOUD)** 的运行状态）。扫描时带有实时的单文件进度，并且每一行结果旁边都有一个紧凑的逐层分析（例如 `DB– fuzzy– macro! yara✓3 VT 14/72 AI 0.80`），以及 0–100 的风险条和判定等级。双击任意一行可查看该文件的完整分析。
**结果详情。** 顶部是判定等级和风险评分，随后是这七个检测层各自的结论 —— 模糊哈希摘要和家族匹配情况、宏自动运行/执行原语、匹配到的 YARA 规则及其严重性、VirusTotal 计数（包含指向报告的链接），以及 LLM 发现的可疑元素 —— 最后是**加权评分明细**，准确展示了是哪些信号推动了判定结果以及具体贡献了多少分。
**扫描、报告、数据库、日志、设置。** 管理受监控的目录和文件类型，浏览历史的 JSON/TXT 报告，导入恶意软件哈希数据集，关注实时日志流，安排定期扫描，切换开机自启动（与 `--setup-autostart` 机制相同），以及存储 API 密钥 —— 密钥仅写入被 git 忽略的 `.env` 文件中，绝不保存在其他任何地方。
工程说明：扫描在单独的工作线程中运行，并通过队列与 UI 进行通信（Tkinter 不是线程安全的）；*Stop* 会在当前正在扫描的文件完成扫描后干净地取消操作；随着每个文件扫描完成，结果会流式传输到表格中。
### 各平台的开机自启动工作原理
| 操作系统 | 机制 | 存放位置 |
|----|-----------|----------------|
| Windows | 注册表 `Run` 键 | `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` |
| macOS | launchd LaunchAgent | `~/Library/LaunchAgents/com.abdelrahman.ransomwarescanner.plist` |
| Linux | systemd **用户**服务（cron `@reboot` 回退） | `~/.config/systemd/user/ransomware-scanner.service` |
`--remove-autostart` 可以干净地撤销所应用的任何机制。
### 报告示例（摘要）
```
Ransomware Scan Report
======================
Timestamp: 2026-06-14 09:59:08
Total files scanned: 24
Files flagged: 1
Highest verdict: Critical
Detection layers used: hashes, local-db, fuzzy, macro, yara, llm, virustotal
LLM posture: LOCAL (llama3.1)
Verdict breakdown: Critical: 1 | High: 0 | Medium: 0 | Low: 0
============================================================
CRITICAL (1)
============================================================
- File: /home/me/Downloads/invoice.docm
Verdict: Critical (risk 92/100, severity 9.2/10)
MD5: 9f2a...c41e
[Macro] Auto-run trigger(s): AutoOpen.
[Macro] Execution/download primitive(s): Shell, URLDownloadToFile.
[Macro] -> Auto-exec + exec primitive = classic dropper pattern.
[YARA] Rule(s) matched [Office_Macro_Payload_Download] (top severity 'high').
[VT] 14 malicious / 72 engines.
Score breakdown:
+ 22.0 [technical] macro_autoexec
+ 48.0 [technical] macro_exec_primitive
+ 20.0 [technical] macro_dropper_synergy
+ 65.0 [technical] yara_match
+ 35.0 [reputation] virustotal
= category totals: technical=100.0, reputation=35.0
```
一份机器可读的完整 `ransomware_scan_.json`（包含完整的逐层证据链）会与文本摘要同时写入。
## 📂 项目结构
```
hybrid-ransomware-detector/
├── RansomwareScanner.py # main scanner + CLI (cross-platform)
├── gui.py # desktop GUI (uses the scanner as a library)
├── test_smoke.py # functional + scoring/regression smoke tests
├── detectors/ # modular, independently-optional detection engines
│ ├── __init__.py
│ ├── fuzzy_hash.py # TLSH + ssdeep structural hashing
│ ├── macro_analysis.py # olevba VBA/XLM macro triage
│ ├── yara_engine.py # YARA rule compilation + scanning
│ ├── llm_backends.py # pluggable LLM (local Ollama / cloud OpenAI / none)
│ └── scoring.py # transparent weighted scoring matrix
├── rules/ # YARA rules (drop in your own .yar files)
│ ├── ransomware_generic.yar
│ └── office_dropper.yar
├── fuzzy_signatures.sample.json # documented placeholder fuzzy signature DB
├── docs/ # screenshots + DETECTION_v3.md design doc
├── requirements.txt
├── CHANGELOG.md
├── .env.example # template for keys + LLM backend settings
├── .gitignore
├── LICENSE
└── README.md
```
请参阅 [`docs/DETECTION_v3.md`](docs/DETECTION_v3.md) 深入了解每一层和评分设计，以及查看 [`CHANGELOG.md`](CHANGELOG.md) 获取版本历史。
## 🌐 跨平台与架构说明
- **操作系统感知路径：** 所有运行时路径（应用目录、日志、报告、默认扫描文件夹）均通过 `Path.home()` 构建，因此没有任何内容被硬编码到特定的单一操作系统上。
- **无架构绑定：** 依赖项要么是纯 Python，要么同时提供了 x86_64 和 ARM64 架构的 wheel 包（Windows/macOS/Linux），因此 `pip install` 会自动解析出正确的构建版本 —— 包括 Apple Silicon 平台。
- **优雅降级：** 缺失 API 密钥、缺失 OCR 二进制文件或缺失扫描文件夹只会产生警告，而不会导致崩溃。
## 🧭 路线图
在 v3.0.0 版本中已交付：模糊哈希、宏分析、YARA 引擎、本地优先的 LLM 后端，以及一个可配置的加权评分矩阵（参见
[更新日志](CHANGELOG.md))。下一步计划：
- **行为/静态启发式分析：** 香农熵分析（加密指标）、NTFS 备用数据流（ADS）检测、隐藏内容检测以及文件完整性基准测试。
- **新层的 GUI 控制：** 应用内的 LLM 提供程序选择器和逐层开关（目前的 LLM 后端是通过 `.env` / `--llm-provider` 选择的）。
- **更丰富的检测内容：** 更广泛的内置 YARA 规则集和精心策划的初始模糊签名数据库。
- **可选的动态分析：** 沙盒化的宏引爆，以获得更高保真度的判定结论。
## 🚨 免责声明
本项目仅供**教育和防御**目的使用 —— 用于识别潜在的恶意文档。请勿用于创建或分发恶意软件。务必在隔离环境中分析不受信任的文件。
## 👤 作者
**Abdelrahman El-Maghraby** —— 网络安全专家
[LinkedIn](https://www.linkedin.com/in/abdelrahman-el-maghraby/)
基于 [MIT License](LICENSE) 发布。
chunked hashing] A --> C[2. Local hash DB
exact known-bad] A --> D[3. Fuzzy hashing
TLSH / ssdeep family match] A --> E[4. VBA macro analysis
olevba dropper triage] A --> F[5. YARA rules
structural IOCs] A --> G[6. VirusTotal
multi-engine reputation] A --> H[7. LLM semantic
local-first, OPSEC-safe] B --> M[Weighted scoring matrix] C --> M D --> M E --> M F --> M G --> M H --> M M --> N[Risk 0-100 + verdict band
+ explainable JSON / TXT report] ``` 这些信号分为三个权重类别 —— **技术类**（哈希数据库、模糊哈希、宏分析、YARA）、**信誉类**（VirusTotal）和**语义类**（LLM）—— 并且在数学设计上，技术证据的权重高于语义证据。 ## 🔬 检测层 1. **密码学哈希（静态）。** 使用高效的**分块读取**（无论文件大小，内存占用恒定）计算文件的 MD5 **和 SHA-256**。 2. **本地哈希数据库（确知恶意）。** 将 MD5 与加载到 **O(1) 查找集合**中的已知恶意哈希**流式 CSV** 进行比对。可即时、离线检测已知样本。 3. **模糊/结构化哈希（多态家族）。** 计算 **TLSH** 和 **ssdeep**（通过纯 Python 实现的 `ppdeep`）摘要，并将它们与*已确认*恶意样本的签名数据库进行比较。由于这些摘要在文件保持*结构相似*时也会保持*相似*，因此这可以捕获那些精确 SHA-256 从未被记录的多态变体——这正好填补了精确哈希黑名单留下的漏洞。匹配距离/相似度会作为证据上报。 4. **VBA 宏分析（Office 投递机制）。** 使用 **`oletools` / `olevba`** 静态提取并对内嵌的 VBA/XLM 宏进行分类，**且绝不执行它们**。它将发现分为自动运行触发器（`AutoOpen`、`Document_Open` 等）、执行/下载原语（`Shell`、`CreateObject`、`URLDownloadToFile`、`powershell` 等）、其他可疑调用以及提取的 IOC。一个自动运行触发器**结合**执行原语是经典的木马投递模式，并将据此进行评分。 5. **YARA 规则引擎（结构化 IOC）。** 编译 `rules/` 中的每个 `.yar` / `.yara` 文件（带命名空间），并根据这些规则扫描每个文件。规则附带一个 `severity` 元属性（`low`/`medium`/`high`/`critical`），评分矩阵会读取该属性。内置规则是针对勒索信语言、勒索+紧急性组合、带支付上下文的比特币地址、PowerShell 下载器和 Office 投递结构的原始分诊启发式规则 —— 你可以放入自己的规则来扩展覆盖范围。仅记录匹配的**字符串标识符**，绝不记录原始的匹配字节。 6. **VirusTotal（威胁情报）。** 将文件哈希提交给 VirusTotal v3 API，并读取标记它的引擎数量，从而得出检测率。 7. **LLM 语义分析（本地优先，保留 OPSEC）。** 提取可见的文档文本（PyPDF2 / python-docx，对于扫描版 PDF 通过 Tesseract + Poppler 提供 **OCR 回退**），以及原始的可打印字符串，询问 LLM 该内容是否看起来像钓鱼/勒索软件诱饵，并返回置信度评分和可疑元素列表。 - **默认保留 OPSEC。** 后端是可插拔的。当设置 `LLM_PROVIDER=auto`（默认值）时，如果扫描器能访问到**本地 Ollama** 模型，它会优先使用它，因此**潜在敏感的文档永远不会离开本机**。只有在没有可用的本地模型*且*设置了 API 密钥时，它才会回退到云端（OpenAI）；每一次云端调用都会被记录为外发流量。将 `LLM_PROVIDER` 设置为 `ollama` 可强制仅使用本地，或者设置为 `none` 以禁用该层。 - **Prompt 注入防御。** 不受信任的文件内容以单独的 **user**（用户）角色传递，与 **system**（系统）指令分开，并且模型在 `temperature = 0` 下运行，从而增强了防御恶意文档试图诱导模型给出“安全”判定结论的能力。 ### 加权评分矩阵 最初硬编码的严重性公式（`10·db + 5·llm + 5·vt`）赋予*语义*信号与多引擎信誉相同的权重，并且无法体现结构化指标比可疑句子更致命这一事实。它已被**透明且可解释的加权矩阵**（`detectors/scoring.py`）所取代。每个信号都通过一条明确的规则产生影响，该规则包含一个**类别**、一个**权重**和一条人类可读的**详细信息**，遵循以下三个原则： 1. **在数学上，技术 > 语义。** 技术指标（本地数据库命中、YARA、宏执行原语、模糊家族匹配）具有最高的权重。语义 (LLM) 类别具有**极低的上限**，因此网络钓鱼诱饵本身永远不可能超过真正的结构化指标的分数。 2. **仅凭语义不能被评为“High”。** 如果没有触发技术或信誉信号，无论 LLM 对文档内容的判断有多确信，判定结果最多被限制为 **Medium**。 3. **可解释性。** 结果包含完整的按指标细分的分析，因此报告可以准确显示是哪些信号推动了判定结果以及具体贡献了多少分。 系统会产生两个分数：一个是带有判定等级区间的精细**风险评分（0–100）**；另一个是保留的**遗留严重性分数（0–10）**（`risk / 10`），以确保现有的报告、GUI 和测试能够继续工作 —— 纯本地数据库命中依然会产生精确的 `10.0`，而干净文件为 `0.0`。 | 风险评分 | 判定等级 | |-----------:|---------| | 0 | Clean (干净) | | 1–24 | Low (低) | | 25–49 | Medium (中) | | 50–79 | High (高) | | 80–100 | Critical (严重) | 只要有任何一层被触发，该文件就会被标记为**恶意**。**每一个可选层都会优雅降级** —— 缺失的库（`python-tlsh`、`ppdeep`、`oletools`、`yara-python`）、缺失的本地模型或缺失的 API 密密钥只会产生警告，而不会导致崩溃，其余的检测层仍会继续运行。 ## ✨ 功能 - 扫描跨越一个或多个目录的 `.pdf`、`.docx` 和 `.doc` 文件。 - **七个独立的检测层**通过一个透明、**可解释的加权评分矩阵**进行融合（风险评分 0–100 + 判定等级，并附带每个文件的完整证据链）。 - **结构化检测**能够抵御多态和混淆：模糊哈希（TLSH/ssdeep）、静态 VBA 宏分诊（olevba），以及你可以使用自己的规则进行扩展的 YARA 引擎。 - **保留 OPSEC 的 LLM 层** —— 默认使用本地 Ollama，从而使敏感文档保留在本机，仅在明确可用时回退到云端；云端外发流量会被记录。 - **桌面 GUI** (`gui.py`) —— 深色主题的仪表板，包含实时扫描进度、逐层结果细分、报告浏览器、数据集导入、实时日志和设置。CLI 仍然保持完全独立。 - 可以通过 CLI 进行单文件扫描和模糊哈希辅助（`--scan-file`、`--fuzzy-hash`），以便快速分类并扩充你的签名数据库。 - OCR 回退机制，确保仅包含图像/扫描版的 PDF 也能被分析。 - 详细的 **JSON** 报告 + 每次扫描人类可读的 **TXT** 摘要，按判定等级分组。 - 预定的后台扫描（默认：每 6 小时一次）。 - **跨平台开机自启动** —— Windows（注册表）、macOS（launchd）、Linux（systemd 用户服务，带有 cron 回退）。 - 可选的桌面快捷方式/启动器（Windows `.lnk`，Linux `.desktop`）。 - 文件 + 控制台日志记录。 ## 📦 依赖要求 **Python：** 3.9+（参见 `requirements.txt` —— 所有依赖项均提供 x86_64 和 ARM64 架构的 wheel 包，因此安装过程不需要编译器）。 **检测层库（可选，推荐）。** 结构化检测层使用 `python-tlsh` + `ppdeep`（模糊哈希）、`oletools`（宏分析）和 `yara-python`（YARA）。它们都在 Windows/macOS/Linux 上为 x86_64 和 ARM64 架构提供了预编译的 wheel 包（或者是纯 Python 编写），因此 `pip install -r requirements.txt` 可以直接拉取它们而无需编译器。如果缺少其中任何一项，该层将被跳过。 **本地 LLM（可选，用于 OPSEC）。** 为了将文档保留在本机，请安装 **[Ollama](https://ollama.com)** 并拉取一个模型，然后扫描器会自动使用它： ``` ollama pull llama3.1 # or any chat model you prefer # 扫描器自动检测运行在 http://localhost:11434 的 Ollama ``` 不需要额外的 Python 包 —— 扫描器通过 HTTP 与 Ollama 通信。如果 Ollama 未运行且未设置 OpenAI 密钥，则语义层将被跳过。 **系统软件包 —— Tesseract OCR + Poppler。** 这些是外部程序（非 Python 包），由 `pytesseract` 和 `pdf2image` 在底层调用。它们仅在需要对**扫描版/纯图像 PDF 进行 OCR 回退**时才需要；扫描器的其他功能在没有它们的情况下也能正常工作。 - **Windows：** 安装 **Tesseract OCR** 和 **Poppler**，并将它们添加到你的 `PATH` 中。 - **macOS：** `brew install tesseract poppler` - **Linux (Debian/Ubuntu)：** `sudo apt-get install tesseract-ocr poppler-utils` **仅针对 GUI —— Tkinter。** 已内置于 Windows 和 macOS 的官方 Python 安装程序中。在最小化安装的 Linux 系统上需运行：`sudo apt-get install python3-tk`。 ## 🚀 安装说明 ``` git clone https://github.com/
标签：AI风险缓解, DNS 反向解析, Python, VBA宏分析, YARA, 云资产可视化, 勒索软件检测, 威胁情报, 开发者工具, 恶意软件扫描, 搜索语句（dork）, 无后门, 本地大语言模型, 逆向工具