srini-cybersec/malwarelens
GitHub: srini-cybersec/malwarelens
一款纯 Python 静态恶意软件分析工具，无需执行样本即可解析多种文件格式、提取 IOC、匹配 YARA 规则并生成威胁评分报告。
Stars: 0 | Forks: 0
# MalwareLens
[](https://github.com/srini-cybersec/malwarelens/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
[](#testing)
MalwareLens 无需执行即可剖析可疑文件。它可解析 PE / ELF / Mach-O / PDF / 脚本格式，提取 ASCII 和 UTF-16LE 字符串，计算每个节的 Shannon 熵，运行内置的类 YARA 规则包（覆盖 20 种 MITRE ATT&CK 技术），并生成单一的人类可读裁决以及适用于 SOAR 流水线的 JSON / HTML / 控制台报告。
## 为什么选择 MalwareLens？
| 问题 | MalwareLens 的解决方案 |
|---|---|
| 动态沙箱成本高昂且可被检测 | 100% **静态** — 从不执行样本 |
| `pefile`/`lief` 引入大量 C 依赖 | **纯 Python** 解析器，总共仅四个固定依赖 |
| YARA 需要单独的编译器/运行时 | **内置** 规则引擎 + 20 条精选规则 |
| IOC 提取通常是临时 grep | 结构化 **类型化 IOC**，支持去重 + RFC1918 过滤 |
| 每个样本的排查需要数分钟 | 单条 CLI 命令即可实现亚秒级分析 |
## 架构
```
┌─────────────────────────────────────────────┐
│ malwarelens.cli │
│ scan / batch / rules / hash subcommands │
└────────────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ core.analyzer.Analyzer │
│ (orchestrates every analysis stage) │
└────────────────────────┬────────────────────┘
│
┌────────────┬────────────┬──────┴──────┬────────────┬────────────┐
▼ ▼ ▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐
│ hashing │ │ entropy │ │ strings │ │ IOC │ │ yara_ │ │ pe_/ │
│ MD5.. │ │ section │ │ ASCII/wide │ │extractor │ │ engine │ │elf_parser│
│ imphash │ │ packing │ │ printable │ │ typed │ │ 20 rules│ │ headers │
└──────────┘ └──────────┘ └────────────┘ └──────────┘ └─────────┘ └──────────┘
│ │ │ │ │ │
└────────────┴────────────┴──────┬──────┴────────────┴────────────┘
▼
┌─────────────────┐
│ scoring (0-100)│
│ MALICIOUS / │
│ SUSPICIOUS / │
│ LOW_RISK / CLEAN│
└────────┬────────┘
▼
┌─────────────────────────┐
│ reports: JSON · HTML · │
│ Rich console │
└─────────────────────────┘
```
## 快速开始
```
# 1. 克隆与安装
git clone https://github.com/srini-cybersec/malwarelens.git
cd malwarelens
pip install -e .
# 2. 扫描样本
malwarelens scan suspicious.exe
# 3. 生成 JSON + HTML 报告
malwarelens scan suspicious.exe \
--json reports/sample.json \
--html reports/sample.html
# 4. 对全部语料库进行分类
malwarelens batch corpus/*.bin --out-dir reports/ --html
# 5. 列出内置规则包
malwarelens rules
```
### Docker
```
docker build -t malwarelens .
docker run --rm -v "$PWD/samples:/samples:ro" malwarelens \
scan /samples/suspicious.exe --quiet --json /samples/out.json
```
## 示例 CLI 输出
```
╭───────────────────────── MalwareLens ─────────────────────────╮
│ Verdict: MALICIOUS Score: 88/100 Format: PE Size: 8192 │
╰───────────────────────────────────────────────────────────────╯
Hashes
MD5 a3c7f...
SHA-256 92b1c8...
imphash 4f8d9e...
Rule Matches
Rule Sev Tags
─────────────────────────────────────────────────────────────
suspicious_process_injection_apis 25 defense-evasion, T1055
hollowing_or_doppelganging 30 T1055.012
ransom_note_keywords 45 ransomware, T1486
anti_debug_apis 15 anti-debug, T1622
IOCs (12)
url http://malicious.example.com/c2
ipv4 45.55.123.55
registry HKEY_LOCAL_MACHINE\Software\...\Run
...
```
CLI 退出码与裁决结果对应 — `CLEAN`/`LOW_RISK` 为 `0`，`SUSPICIOUS` 为 `1`，`MALICIOUS` 为 `2`，分析器错误为 `3` — 使其可直接集成到 CI/CD 的 `fail-on` 门禁中。
## Python API
```
from pathlib import Path
from malwarelens import Analyzer, Verdict
analyzer = Analyzer()
result = analyzer.analyze_path(Path("suspicious.exe"))
print(result.score.verdict, result.score.score)
for match in result.rule_matches:
print(f" - {match.rule_name} (severity={match.severity})")
for ioc in result.iocs:
print(f" {ioc.type:<10} {ioc.value}")
if result.score.verdict is Verdict.MALICIOUS:
raise SystemExit("Quarantine triggered")
```
### 添加自定义规则
```
from malwarelens import Analyzer
from malwarelens.core.yara_engine import Rule, text
analyzer = Analyzer()
analyzer.add_rule(
Rule(
name="my_org_keyword_leak",
severity=40,
description="Sample references internal hostname.",
patterns=(text("a", "INTERNAL-DC01", nocase=True),),
condition="any",
tags=("data-exfil",),
)
)
```
## 配置
所有设置均从 `MALWARELENS_*` 环境变量读取，操作人员无需修改代码即可覆盖行为：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `MALWARELENS_MIN_STRING_LENGTH` | `6` | 可打印字符串的最小长度 |
| `MALWARELENS_MAX_STRINGS` | `50000` | 每个样本提取字符串的上限 |
| `MALWARELENS_MAX_FILE_BYTES` | `268435456` | 拒绝超过此大小的文件 |
| `MALWARELENS_ENTROPY_PACK_THRESHOLD` | `7.2` | 节熵值 → 判定为加壳 |
| `MALWARELENS_ENTROPY_BLOCK_SIZE` | `256` | 熵值图的块大小 |
| `MALWARELENS_SCORE_MALICIOUS` | `70` | 分数 → `MALICIOUS` 裁决 |
| `MALWARELENS_SCORE_SUSPICIOUS` | `40` | 分数 → `SUSPICIOUS` 裁决 |
| `MALWARELENS_COLOR` | `true` | 强制启用/禁用终端颜色 |
## 内置规则包
| 规则 | 严重性 | MITRE | 描述 |
|---|---|---|---|
| `suspicious_process_injection_apis` | 25 | T1055 | VirtualAllocEx/WriteProcessMemory/CreateRemoteThread 组合 |
| `hollowing_or_doppelganging` | 30 | T1055.012 | NtUnmapViewOfSection + SetThreadContext + ResumeThread |
| `anti_debug_apis` | 15 | T1622 | IsDebuggerPresent / CheckRemoteDebuggerPresent 等 |
| `anti_vm_strings` | 20 | T1497 | VBoxService、vmtoolsd、QEMU 等 |
| `persistence_registry_runkey` | 20 | T1547.001 | Run / RunOnce 键写入 |
| `credential_access_lsass` | 35 | T1003.001 | LSASS 转储原语 |
| `ransomware_extensions` | 40 | T1486 | 大规模文件扩展名枚举 |
| `ransom_note_keywords` | 45 | T1486 | "your files have been encrypted" 等 |
| `upx_packer` | 20 | — | UPX 节名称 |
| `cobalt_strike_beacon_strings` | 50 | — | Beacon DLL 字符串 |
| `mimikatz_strings` | 55 | T1003 | Mimikatz 横幅 / 模块名称 |
| `webshell_php_eval` | 40 | T1505.003 | `eval(base64_decode(...))` 模式 |
| `wmi_persistence` | 25 | T1546.003 | EventFilter / CommandLineEventConsumer |
| ... | | | 共 20 条规则 — 详见 [`src/malwarelens/rules/builtin.py`](src/malwarelens/rules/builtin.py) |
## 威胁评分机制
0-100 的评分聚合了四类信号（每类均有上限，防止单一来源主导）：
| 信号 | 最高分值 | 来源 |
|---|---|---|
| YARA 规则匹配 | 80 | 每条规则的 `severity` 之和（有上限） |
| 高熵节 | 15 | 每个加壳节 ≥ 64 B |
| 高风险导入 | 20 | Win32 进程注入 / 凭据 API |
| 可操作 IOC | 10 | URL、IP、注册表键、BTC 地址 |
裁决映射可通过环境变量配置 — 默认值：
| 分数 | 裁决 |
|---|---|
| 0 – 19 | `CLEAN` |
| 20 – 39 | `LOW_RISK` |
| 40 – 69 | `SUSPICIOUS` |
| 70 – 100 | `MALICIOUS` |
## 安全注意事项
* **所有分析均为静态。** MalwareLens 从不执行、解压或动态解析样本。可在常规开发者工作站上安全运行，但分析真实恶意软件仍应在隔离环境中进行。
* **对抗性输入。** PE/ELF 解析器具有防御性：格式错误的偏移、大小或魔数将返回空结果而非抛出异常，因此恶意样本无法使分析器崩溃。
* **无出站网络连接。** MalwareLens 不发起任何网络调用 — 无哈希查询、无规则下载、无遥测。这使其适用于气隙环境和事件响应工作，在这些场景中数据外泄风险至关重要。
* **资源限制。** `MALWARELENS_MAX_FILE_BYTES` 和 `MALWARELENS_MAX_STRINGS` 限制了攻击者构造输入时的内存使用量。
* **样本数据无执行路径。** 样本字节仅被解析，绝不通过 `eval`、`exec` 或 `subprocess` 执行。
## 测试
```
pip install -r requirements-dev.txt
pytest tests/ --cov=malwarelens --cov-report=term-missing
```
* **126 个测试**，**90% 行覆盖率**
* 测试在内存中构建确定性的 PE + ELF 固件 — 不提交真实恶意软件样本。
* CI 在每次推送时运行 `black`、`ruff`、`mypy`、`bandit`、`safety` 和 `pytest`。
## 许可证
MIT — 详见 [`LICENSE`](LICENSE)。
标签：DAST, DNS信息、DNS暴力破解, DNS 反向解析, ELF文件, IOC提取, IP 地址批量处理, LNA, Mach-O, MITRE ATT&CK映射, PDF分析, PE文件, Python安全工具, SOAR集成, YARA规则, 云安全监控, 反病毒, 域名收集, 威胁情报, 威胁评分, 子域名变形, 子域名暴力破解, 字符串提取, 开发者工具, 恶意软件分析, 恶意软件逆向工程, 搜索语句（dork）, 样本特征提取, 沙箱替代方案, 熵分析, 网络信息收集, 网络安全, 网络安全审计, 自动化检测, 请求拦截, 隐私保护, 静态分析