meitar11/py_deobfuscator
GitHub: meitar11/py_deobfuscator
一款通过纯静态方式解密并去混淆 PyArmor 保护代码的命令行工具，专为自动化恶意软件分析提取证据而设计。
Stars: 0 | Forks: 0
# pyarmor-deob
一个 **对 PyArmor 保护的 Python 进行静态去混淆**的 CLI 工具，并返回可读的
内容以及提取的证据（imports、字符串、URL/IP、可疑的 API 调用）——
专为向自动化恶意软件分析器提供输入并生成可展示给客户的证据而构建。
- **静态分析——绝不执行样本。** 解密密钥通过 `pyarmor_runtime` 库在离线状态下重新计算，绝不会运行恶意代码。
- 支持 **PyArmor 8.0 – 9.2.x**，Python 3.7 – 3.13（通过内置引擎）。
- 输出 **JSON 报告**（机器契约）和 **Markdown 报告**（人工证据），
并将去混淆后的文件保存在磁盘上。
## 工作原理
```
input path ─▶ detect ─▶ engine (1shot) ─▶ normalize ─▶ extract (IOCs) ─▶ report (JSON + MD)
│
deobfuscated files
```
核心的繁重工作——在不运行代码的情况下解密 PyArmor 的 AES 加密 bytecode——由
内置的原生 [Pyarmor-Static-Unpack-1shot](https://github.com/Lil-House/Pyarmor-Static-Unpack-1shot)
引擎完成。本项目围绕它构建了完整的产品功能：检测、编排、证据
提取，以及稳定的报告契约。
对于每个混淆单元，该引擎都会生成精确的 **disassembly**，并尽可能提供
**反编译的源代码**。PyArmor 引导程序的反编译通常不完整，因此
该工具始终保留可靠的 disassembly，并从最佳结果中提取证据——
您的分析器绝不会一无所获。
## 安装
### 预构建 wheel — 推荐 用于 Docker / CI（无需工具链，无需构建）
对于 `linux/amd64` 架构上的 Python 3.13（例如 `python:3.13-slim`），请从
[release](https://github.com/meitar11/py_deobfuscator/releases/latest) 安装预构建的 wheel。它
**内置了完全静态的引擎二进制文件**——安装或首次运行时不需要 cmake、C++ 或 git，也无需网络克隆：
```
FROM python:3.13-slim
ARG WHEEL=py_deobfuscator-0.1.2-cp313-cp313-manylinux2014_x86_64.whl
RUN pip install "https://github.com/meitar11/py_deobfuscator/releases/download/v0.1.2/${WHEEL}"
RUN pydeob --selftest # fail the build if the engine is missing/broken
```
`pip install` 仅从索引中获取 `pycryptodome`；它绝不会进行构建或克隆。
该 wheel URL 无需 token（公开发布）。
### 从源码构建（其他平台 / 开发）
要求 **Python ≥ 3.9**，外加 **C++ 编译器和 CMake** 以便一次性构建引擎。
```
python -m venv .venv && source .venv/bin/activate
pip install -e .
python scripts/build_engine.py # auto-clones + builds the engine (git, cmake, C++)
```
在 macOS 上：`brew install cmake`。在 Debian/Ubuntu 上：`apt install cmake g++`。
### 验证引擎
`pydeob --selftest` 会对内置的无害测试用例进行去混淆，如果
原生引擎缺失、无法加载或未返回任何内容，则以非零状态退出。将其作为 Docker
构建步骤运行，这样损坏的引擎会导致镜像构建失败，而不是发布一个无效的工具。
## 用法
```
# 向终端输出人类可读的报告：
pydeob path/to/obfuscated_folder
# 机器 + 客户端报告，以及去混淆后的文件位于 out/：
pydeob path/to/obfuscated_folder -o out/ --json out/report.json --md out/report.md
```
| 参数 | 含义 |
|------|---------|
| `path` | 混淆的文件或文件夹（递归扫描）。 |
| `-o, --out` | 去混淆输出文件的目录（默认为 `pydeob_out`）。 |
| `--json` | 将机器可读的 JSON 报告写入此处。 |
| `--md` | 将人类可读的 Markdown 报告写入此处。 |
| `-r, --runtime` | 如果未自动找到，则指定 `pyarmor_runtime[.so\|.pyd\|.dylib]` 的路径。 |
## JSON 报告 schema (v1.0)
```
{
"schema_version": "1.0",
"input_path": "…",
"is_pyarmor": true,
"series": 8, // 7 or 8 (8 == v8+ modern format)
"files": [
{
"source_path": "…/malware.py",
"status": "source_recovered", // | "disassembly_only" | "failed"
"readable_path": "…/malware.py.1shot.cdc.py",
"disassembly_path": "…/malware.py.1shot.das",
"error": null,
"evidence": {
"imports": ["os", "socket"],
"api_calls": ["os.system"],
"names": ["b64decode", "print"], // symbols referenced in disassembly
"urls": ["http://evil.example/gate"],
"ips": ["45.77.13.201"],
"suspicious":["exec: dynamic code execution"],
"strings": ["…"]
}
}
]
}
```
`status` 告诉分析器对 `readable_path` 的信任程度：
`source_recovered`（干净的源代码）、`disassembly_only`（精确的 disassembly——信任
`evidence`），或 `failed`（参见 `error`）。
## 稳定性契约
以下内容对下游适配器保持稳定（由 `tests/test_contract.py` 覆盖）：
- 控制台脚本 **`pydeob`**；导入模块 **`pyarmor_deob`**。
- CLI 形式 **`pydeob -o --json `**。
- 报告键 **`files[].{source_path, status, readable_path, disassembly_path}`**，其中
**`status ∈ {source_recovered, disassembly_only, failed}`**。
- 运行时保证：绝不执行样本；仅在 `-o` 目录下写入；以
非 root 用户身份离线运行；使用预构建的 wheel 时，首次运行无需构建或网络。
## 测试
```
pip install -e '.[dev]'
pytest -m 'not integration' # fast unit tests, no engine needed
pytest -m integration # end-to-end; needs the built engine + pyarmor installed
```
## 许可证说明
内置引擎嵌入了 **pycdc / Decompyle++ (GPLv3)**，基于
[Pyarmor-Static-Unpack-1shot](https://github.com/Lil-House/Pyarmor-Static-Unpack-1shot)
构建，固定在 commit `d24ea23a3b97ea771b8f613108200481b0a98f81`。**预构建的 wheel
重新分发了该 GPLv3 二进制文件**，因此其对应的源码即为该上游 commit。
适用于内部分析工具；如果您将其集成到面向客户的产品中，
请先查阅 GPLv3 规定的义务。该引擎位于单一接口
（`pyarmor_deob/engine.py`）之后，因此可以在不触及其余部分的情况下进行替换或移除。
## 限制
- 除检测外，无法处理 PyArmor 7 或更早版本（不同的 `PYARMOR` 格式）。
- 无法分析来自 PyArmor **BCC mode** 的原生代码。
- PyInstaller `.exe` / 归档文件必须在扫描前解包（尚未自动化）。
- 反编译的源代码已尽力而为；disassembly + evidence 才是可靠的输出。
标签：Bash脚本, DAST, DNS 反向解析, Python, 云安全监控, 云资产清单, 代码解混淆, 恶意软件分析, 无后门, 请求拦截, 逆向工具, 逆向工程, 静态分析