---

name: re-python type: atomic description: > Python 打包/混淆样本分析：PyInstaller/PyArmor/Nuitka/Cython 解包、pyc 版本识别与反编译。 触发词：Python打包、PyInstaller、PyArmor、pyc、python exe、Python 样本、打包样本。 capabilities: [bytecode-parser]

Python 打包样本分析（PyInstaller / PyArmor / pyc）

何时使用 / 何时不用

• 用：PyInstaller 单文件/目录 exe、PyArmor 加固样本、.pyc 文件、Nuitka/Cython 编译产物、Python 恶意软件打包样本
• 不用：纯 .py 源码混淆（base64/编码包装）→ 转 [[re-script-deob]]；Python 模型权重（pkl/onnx）→ [[re-ai-model]]

工具准备

参考 [[re-analyze/platform-tips]]——解包/反编译为静态步骤，免沙箱；动态取明文（[[re-sandbox]]）按最高原则进沙箱。

python3（基础运行时，必备）

• Linux: apt install python3 / dnf install python3 / pacman -S python
• macOS: brew install python（系统自带）
• Windows: 官网安装包或 choco install python
• 验证: python3 --version

pyinstxtractor（PyInstaller 归档提取）

• 多平台: pip install pyinstxtractor-ng 或 GitHub 脚本 python pyinstxtractor.py
• 验证: pyinstxtractor-ng <目标.exe> 运行无报错（无独立 --help 命令）

PyArmor-Unpacker（PyArmor 加固解包）

• 多平台: git clone https://github.com/Svenskithesource/PyArmor-Unpacker，按 README 按 PyArmor 版本选三方法之一
• 验证: 仓库内 python 脚本可运行

pycdc / pycdas（pyc 反编译）

• Linux/macOS: git clone https://github.com/zrax/pycdc && cd pycdc && cmake . && make
• Windows: 预编译二进制或 WSL 编译
• 验证: ./pycdc --help

file（打包器识别辅助，通用）

• 各系统自带（Linux binutils / macOS / Windows 需额外装或跳过）
• 验证: file --version

操作步骤

按顺序执行，每步产物存档（路径 + sha256，见 [[re-triage]]）。

1. 识别打包器：

   file sample.exe
   strings sample.exe | grep -iE 'PyInstaller|_MEIPASS|pyi-|PyArmor|pyarmor' | head
   

   • PyInstaller 特征：PyInstaller 版本串、_MEI 临时目录名、pyi- 前缀引导器
   • PyArmor 特征：pyarmor runtime 字符串
   • Nuitka/Cython：无 pyc、纯编译产物（file 显示普通可执行，无 Python runtime 打包特征）
   • 识别失败但确认 Python 相关 → 按可疑 PyInstaller 处理

2. PyInstaller 解包：

   • pip 安装用户：pyinstxtractor-ng sample.exe；GitHub 脚本用户：python pyinstxtractor.py sample.exe

   python pyinstxtractor.py sample.exe
   # 输出 sample.exe_extracted/ 目录，含 PYZ-00.pyz（依赖归档）与主脚本 .pyc
   

   • 定位主 .pyc（名字与入口脚本对应）；PYZ 内模块自动解出至 PYZ-00.pyz_extracted/；模块清单可用 archive_viewer.py 查看

3. PyArmor 解包（步骤 1 检测到 PyArmor 时）：

   • 按 PyArmor 版本选 PyArmor-Unpacker 三方法之一（README 判断版本 → 对应方法）
   • 解包产物仍为 pyc 或源码，继续下一步

4. pyc 版本识别：

   python3 -c "import struct,sys; print(struct.unpack('<H', open('main.pyc','rb').read(2))[0])"
   

   • magic 对照（小端 2 字节，常见值；以本机 MAGIC_NUMBER 为准）：
     • 0d33=3.6、0d42=3.7、0d55=3.8、0d61=3.9、0d6f=3.10、0da7=3.11、0dcb=3.12
     • 3.13+：不写死数值，按本机 MAGIC_NUMBER 换算（python3 -c "import importlib.util; print(hex(int.from_bytes(importlib.util.MAGIC_NUMBER[:2],'little')))"）
   • pyc 头布局（3.7+ 统一 16 字节）：magic(4) + flags(4) + mtime(4) + size(4)，code 对象从偏移 16 开始；flags 低 1 位 = hash-based（PEP 552，mtime/size 无意义）；PyInstaller 解出的 pyc 头 flags/mtime/size 全 0（清零是正常现象，不是损坏）
   • 版本决定 marshal 格式：3.14 起 marshal 升到 v5，code 对象内部布局与旧版不同——手写 marshal 解析须按 magic 版本分派；pycdc 等工具对 3.13+ 支持滞后，优先用匹配版本 python 的 dis/marshal 兜底
   • 版本匹配目标则用对应版本 python 或 pycdc 反编译；不匹配先装匹配版本再试

5. 反编译与清理：

   pycdc main.pyc > main_decompiled.py   # 或匹配版本 python 的 dis 模块
   

   • 清理 confusion code：删假函数/死代码（PyArmor 常见的无引用包装函数），定位核心逻辑（加密/网络/外泄）
   • 反编译失败（版本不匹配/混淆）→ 用 dis 字节码级分析关键函数，或转 [[re-binary-core]] 深度还原

跨域联合

• [[re-managed]] 网关：本技能归属（选择树「Python 打包样本」分支）
• [[re-script-deob]]：纯脚本混淆（无打包）场景
• [[re-malware]]：恶意 Python 样本的行为验证与 IOC（解包后转行为分析）
• [[re-binary-core]]：pyc 深度还原 / 混合产物（内嵌 native 模块 [[re-format-elf]]）
• 底座 [[re-triage]]：打包器识别的初勘输入

常见坑与陷阱

• pyc 版本不匹配直接反编译失败：现象——pycdc 输出乱码或报错；原因——magic 版本与目标不符；对策——先做步骤 4 的 magic 识别，按版本选工具
• pyc 头 mtime/size 为 0 不是损坏：现象——PyInstaller 解出的 pyc 用工具打开报错/空白，怀疑解包失败；原因——PyInstaller 写 PYZ 时清零 mtime/size（marshal 本体不受影响）；对策——按 magic 识别版本后跳过 16 字节头，直接 marshal.loads 验证 code 对象，或交给 pycdc
• hash-based pyc（PEP 552）：现象——pyc 头 flags 字段非 0（低 1 位为 1），mtime/size 是哈希或占位；原因——构建方用 hash 校验模式编译；对策——识别只看 magic 与 flags 低 1 位，反编译不受影响（code 对象仍是标准 marshal 流）
• PyArmor 版本差异导致解包器失效：现象——PyArmor-Unpacker 报不支持；原因——PyArmor 版本过新/过旧；对策——按版本换方法，或手动定位 runtime 的加解密逻辑（转 [[re-binary-core]]）
• Cython/Nuitka 无 pyc：现象——找不到 .pyc；原因——编译型产物；对策——直接分析产物（[[re-format-elf]] / [[re-ghidra]]），不找 pyc
• 假函数干扰定位：现象——解包后源码充斥无引用包装函数；原因——PyArmor 的 confusion code；对策——先按调用关系过滤（无调用者即候选），再定位核心逻辑
• strings 找打包器特征被加密隐藏：现象——strings 无 PyInstaller 特征但行为是 Python；原因——字符串加密/壳；对策——按行为线索与扩展名判断，必要时动态侧（[[re-sandbox]]）观察
• 混淆样本整体是"加密数据 + 引导壳 + 原生解密组件"三件套：现象——静态看只有一处引导调用和一段加密字节串常量，找不到正常 pyc，函数字节码在内存里也长期保持密文；原因——整份程序以 marshal 流形态加密后作为一个字节串常量整体内嵌进引导调用，解密密钥由随样本交付的原生扩展内部静态数据派生（密钥材料与配方随构建变化），单个函数执行前才原位解密、返回后立即原位重加密，明文存在的窗口被压到极短；函数常量表还被注入负责进入/离开/完整性校验的原生桩对象，文件里只剩标记字符串，真实对象只能运行期生成；对策——把样本拆成三件套分别处理，函数级明文要么静态还原加解密流程、要么在运行期解密窗口内抓取；注意解密后的函数体仍是普通 CPython 字节码，不存在自定义字节码虚拟机——看起来像 VM 的花哨字节只是加密后的标准字节码
• 密钥材料定位用"盐锚点 + 相对偏移"，别硬编码绝对地址：现象——换一个构建版本的样本，旧的密钥定位脚本全部失效；原因——密钥由多段静态数据拼接后取摘要派生（典型拼段含盐、内嵌公钥、签名许可证描述哈希、一段需先还原的掩码数据），掩码区域靠固定长度区域与重复字节 pad 做 XOR 还原，而文件中的对齐填充同样表现为连续相同字节，全零候选一旦被当 pad 就派生错误密钥；参与拼接的输入还受条件分支控制（外部密钥文件、试用/正式开关）；对策——在原生扩展的原始字节中先搜可见盐锚点字符串，其余密钥材料一律以锚点位置为基准按相对偏移计算，同一套代码可跨多个构建复用；自动找 pad 时排除全零候选；按标志位判断启用哪些输入；静态还原不必让启动期完整性校验（如公钥验签）通过，从分支逻辑复现出密钥派生的输入拼接方式即可
• 解密产物是标准 marshal 流，但重建 CodeType 有格式怪癖：现象——按常规 .pyc 流程解析解密出的字节流时字段错位、常量错乱，个别 Python 版本上还会直接崩溃且异常不可捕获；原因——序列化时常量元组声明的长度可能小于实际写入个数（多余条目无头部直接跟在后），流里还可能出现私有类型字节区间，代表只能由运行时在内存中生成的原生对象（静态读不到本体，占位符不剔除会导致后续常量索引错位），密文字节码直接进反汇编或 CodeType 构造在部分版本上会崩解释器；对策——用一次性模板代码编译后 .replace() 构造 CodeType 而非直接调构造器（构造器参数顺序随版本变化），本地变量数显式传入；原生对象以占位符表示并在构造前剔除；单条记录解析失败时保留已读字段（字节码与常量靠前、通常已拿到），整体降级为逐个报告完整解析的 code 对象而非全盘失败；解密失败用模板占位字节码顶替，密文仅十六进制展示；3.11 起 code 对象布局变化，从 blob 头读目标版本并自动切到匹配版本解释器，不为每个版本各写一套解析规则
• 动态取明文要卡"进入桩解密后"的窗口，导入方式也有讲究：现象——运行时 hook 后抓不到明文，或回调内部崩溃；原因——受保护函数每次调用都经进入桩解密、执行、离开桩重加密三步，明文窗口极短（短函数可能立即离开），事后读取拿不到；进入桩对外是 Python 可调用对象（内建函数对象形态），可从模块常量表辨认，真实原生函数指针藏在 C 函数对象的元数据结构里、经内存布局偏移可读出；首轮导入时回调内部再触发同一钩子会嵌套破坏回调链；以 main 方式运行会走另一条运行时路径、绕过发现机制；对策——拦截模块首次解密后执行的那次调用，从传入 code 对象的常量中读出进入桩指针；首轮导入返回空指针中止、重启一轮等内联钩子就位，后续执行用具名模块方式导入；定位导入槽在数据段内扫描已解析的真实函数地址指针，而不是扫调用点（调用点引用的是槽地址，直接扫容易错）
• 混淆器内部格式不是文档化兼容接口，结论必须标注版本：现象——同一套还原脚本换版本就失效，且说不清坏在哪一步；原因——密钥派生输入、嵌入标记位置、blob 头、函数级描述符、原生入口、marshal 重建行为都可能随版本变化，工具与目标解释器版本也强绑定（code 对象/marshal 布局随版本变）；对策——任何结论标注精确版本，跨版本复用工具不假设可用；对每个新版本逐项重验（密钥配方、标记位置、头部结构、描述符、入口函数、重建行为），未经真实样本验证的分支显式标注未实测；静态重建与动态捕获（运行期真实解密产物）逐字段对照互相验证——动态能暴露静态推断的格式错误（如把原生对象误当普通常量、元组声明长度偏差），静态补足动态够不到的死路径（未调用函数、未触达分支）；试用/正式、有无外部密钥文件等形态差异按标志位与分支逻辑处理，不假设单一形态