Fickling

Fickling 是一个针对 Python pickle 对象序列化的反编译器、静态分析工具和字节码重写器。你可以使用 Fickling 来检测、分析、逆向工程，甚至创建恶意的 pickle 或基于 pickle 的文件，包括 PyTorch 文件。

Fickling 既可以作为 Python 库 使用，也可以作为 命令行工具 使用。

• 安装
• 保护 AI/ML 环境
• 通用恶意文件检测
• 高级用法
  • 跟踪 pickle 执行
  • Pickle 代码注入
  • Pickle 反编译
  • PyTorch 多语言文件
• 更多信息
• 联系方式

安装

Fickling 已在 Python 3.9 到 Python 3.13 上进行了测试，且依赖非常少。库和命令行工具都可以通过 pip 或 uv 进行安装：

# 使用 pip
python -m pip install fickling

# 使用 uv
uv pip install fickling

PyTorch 是 Fickling 的可选依赖。因此，为了使用 Fickling 的 pytorch 和 polyglot 模块，你需要运行以下命令：

# 使用 pip
python -m pip install fickling[torch]

# 使用 uv
uv pip install fickling[torch]

保护 AI/ML 环境

Fickling 可以通过自动扫描模型中包含的 pickle 文件来帮助保护 AI/ML 代码库。Fickling 会钩住 pickle 模块，并在加载模型时验证导入的模块。它只会检查这些导入是否来自被认为是安全的 ML 库的白名单，而阻止包含其他导入的文件。

要启用 Fickling 的安全检查，只需在你的程序中，在加载任何 AI/ML 模型之前运行以下代码一次：

import fickling
# 这会在 pickle 上设置全局钩子
fickling.hook.activate_safe_ml_environment()

要移除保护措施：

fickling.hook.deactivate_safe_ml_environment()

你使用的模型可能包含 Fickling 不允许的导入。如果你仍然想加载该模型，可以使用 also_allow 参数为你的特定用例添加额外的允许导入：

fickling.hook.activate_safe_ml_environment(also_allow=[
    "some.import",
    "another.allowed.import",
])

重要提示：你应始终确保手动添加的导入是安全的，不会使攻击者能够执行任意代码。如果你不确定如何操作，可以在 Fickling 的 GitHub 仓库中提交一个问题，说明相关的导入或模型，我们的团队将对其进行审查，并在可能的情况下将其加入白名单。

通用恶意文件检测

Fickling 可以无缝集成到你的代码库中，以便在运行时检测并阻止恶意文件的加载。

下面我们展示了使用 Fickling 对 pickle 文件强制执行安全检查的不同方式。在底层，它会钩住 pickle 库以添加安全检查，从而使得加载 pickle 文件时，如果检测到恶意内容，就会抛出 UnsafeFileError 异常。

方案 1（推荐）：检查所有加载的 pickle 文件的安全性

# 这会在每次使用 pickle 进行反序列化时强制执行安全检查
fickling.always_check_safety()

# 尝试加载不安全的文件现在会抛出异常
with open("file.pkl", "rb") as f:
    try:
        pickle.load(f)
    except fickling.UnsafeFileError:
        print("不安全的文件！")

方案 2：使用上下文管理器

with fickling.check_safety():
    # 在上下文管理器内加载的所有 pickle 文件都会被检查安全性
    try:
        with open("file.pkl", "rb") as f:
            pickle.load(f)
    except fickling.UnsafeFileError:
        print("不安全的文件！")

# 在上下文管理器之外加载的文件不会被检查
pickle.load("file.pkl")

方案 3：检查并加载单个文件

# 使用 fickling.load() 替代 pickle.load() 来检查安全性并加载单个 pickle 文件
try:
    fickling.load("file.pkl")
except fickling.UnsafeFileError as e:
    print("不安全的文件！")

方案 4：仅检查 pickle 文件的安全性而不加载

# 在不加载的情况下对 pickle 文件进行安全检查
if not fickling.is_likely_safe("file.pkl"):
    print("不安全的文件！")

访问安全分析结果

你可以从抛出的异常中获取 Fickling 安全分析的详细信息：

>>> try:
...     fickling.load("unsafe.pkl")
... except fickling.UnsafeFileError as e:
...     print(e.info)

{
    "severity": "OVERTLY_MALICIOUS",
    "analysis": "调用 `eval(b'[5, 6, 7, 8]')` 几乎可以肯定是一份恶意 pickle 文件的证据。变量 `_var0` 被赋值为 `eval(b'[5, 6, 7, 8]')`，但之后未被使用；这一点很可疑，表明这是一份恶意 pickle 文件",
    "detailed_results": {
        "AnalysisResult": {
            "OvertlyBadEval": "eval(b'[5, 6, 7, 8]')",
            "UnusedVariables": [
                "_var0",
                "eval(b'[5, 6, 7, 8]')"
            ]
        }
    }
}

如果你使用的是 Python 以外的语言，仍然可以使用 Fickling 的 CLI 来对 pickle 文件进行安全检查：

fickling --check-safety -p pickled.data

高级用法

跟踪 pickle 执行

Fickling 的 CLI 允许安全地跟踪 Pickle 虚拟机的执行过程，而无需执行任何恶意代码：

fickling --trace file.pkl

Pickle 代码注入

Fickling 允许在 pickle 文件中注入任意代码，这些代码将在每次加载文件时执行。

fickling --inject "print('Malicious')" file.pkl > malicious.pkl

Pickle 反编译

Fickling 可以用于反编译 pickle 文件，以便进一步分析。

>>> import ast, pickle
>>> from fickling.fickle import Pickled
>>> fickled_object = Pickled.load(pickle.dumps([1, 2, 3, 4]))
>>> print(ast.dump(fickled_object.ast, indent=4))
Module(
    body=[
        Assign(
            targets=[
                Name(id='result', ctx=Store())],
            value=List(
                elts=[
                    Constant(value=1),
                    Constant(value=2),
                    Constant(value=3),
                    Constant(value=4)],
                ctx=Load()))],
    type_ignores=[])

PyTorch 多格式文件

PyTorch 包含多种文件格式，可以用来创建多格式文件，即能够被正确解析为多种不同文件格式的文件。 Fickling 支持识别、检查和创建以下 PyTorch 文件格式的多格式文件：

• PyTorch v0.1.1：包含 sys_info、pickle、storages 和 tensors 的 tar 文件
• PyTorch v0.1.10：堆叠的 pickle 文件
• TorchScript v1.0：包含 model.json 的 ZIP 文件
• TorchScript v1.1：包含 model.json 和 attributes.pkl 的 ZIP 文件
• TorchScript v1.3：包含 data.pkl 和 constants.pkl 的 ZIP 文件
• TorchScript v1.4：包含 data.pkl、constants.pkl，并且版本号设置为 2 或更高（2 个 pickle 文件和一个文件夹）的 ZIP 文件
• PyTorch v1.3：包含 data.pkl 的 ZIP 文件
• PyTorch 模型归档格式[ZIP]：包含 Python 代码文件和 pickle 文件的 ZIP 文件

>> import torch
>> import torchvision.models as models
>> from fickling.pytorch import PyTorchModelWrapper
>> model = models.mobilenet_v2()
>> torch.save(model, "mobilenet.pth")
>> fickled_model = PyTorchModelWrapper("mobilenet.pth")
>> print(fickled_model.formats)
您的文件最有可能是这种格式： PyTorch v1.3
['PyTorch v1.3']

请查看 我们的示例，了解更多关于如何使用 Fickling 的信息！

更多信息

实际上，pickle 格式的 Python 对象是字节码，由 Python 内置的基于栈的虚拟机“Pickle Machine”来解释执行。Fickling 可以将这些 pickle 数据流反编译成人类可读的 Python 代码，当这些代码被执行时，会反序列化为原始的序列化对象。这是通过 Fickling 自定义实现的 PM 来实现的。Fickling 在处理潜在恶意文件时是安全的，因为它采用符号执行的方式运行代码，而不是直接执行。

作者并未对 Fickling 中的“F”赋予特定含义；它可以代表“fickle”（善变的），也可以是其他意思。解读其具体含义是一次个人的判断之旅，留给读者自行思考。

您可以在我们的 博客文章 以及 DEF CON AI Village 2021 演讲 中了解更多关于 Fickling 的信息。

联系方式

如果您想提交 bug 报告或功能请求，请使用我们的 issues 页面。 您也可以随时联系我们，或在 Empire Hacking 中寻求帮助，以使用或扩展 Fickling。

许可证

本工具由 Trail of Bits 开发。它根据 GNU Lesser General Public License v3.0 进行许可。 如果您希望获得条款的例外，请联系 [opensource@trailofbits.com]。

© 2021, Trail of Bits。

Fickling 快速上手指南

Fickling 是一款针对 Python pickle 序列化数据的反编译器、静态分析器和字节码重写工具。它主要用于检测、分析、逆向工程甚至创建恶意的 pickle 文件（包括 PyTorch 模型文件），是保障 AI/ML 环境安全的重要工具。

环境准备

• 操作系统：支持 Linux, macOS, Windows。
• Python 版本：Python 3.9 至 3.13。
• 前置依赖：
  • 基础功能仅需极少依赖。
  • 若需使用 PyTorch 相关模块（如 pytorch 和 polyglot），需预先安装 PyTorch 或直接安装带 torch 扩展的 fickling。

安装步骤

推荐使用 pip 或 uv 进行安装。国内开发者如遇网络问题，可配置清华或阿里镜像源加速。

1. 安装基础版

仅包含核心库和命令行工具，适用于通用的 pickle 文件安全检测。

# 使用 pip (推荐配置国内镜像)
python -m pip install fickling -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或使用 uv
uv pip install fickling

2. 安装完整版（含 PyTorch 支持）

如果您需要分析 PyTorch 模型文件或处理多格式混合文件（Polyglots），请安装此版本。

# 使用 pip (推荐配置国内镜像)
python -m pip install "fickling[torch]" -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或使用 uv
uv pip install "fickling[torch]"

基本使用

Fickling 既可作为 Python 库在代码中调用，也可作为命令行工具（CLI）直接使用。

场景一：在代码中自动拦截恶意文件加载

这是保护 AI/ML 环境最推荐的方式。启用后，任何尝试加载包含不安全导入（如任意代码执行）的 pickle 文件的操作都会抛出 UnsafeFileError 异常。

import pickle
import fickling

# 激活全局安全钩子，限制只允许安全的 ML 库导入
fickling.hook.activate_safe_ml_environment()

# 此时加载恶意文件将直接报错
try:
    with open("suspicious_model.pkl", "rb") as f:
        data = pickle.load(f)
except fickling.UnsafeFileError as e:
    print("检测到不安全文件！")
    # 可查看详细的分析报告
    print(e.info)

若需临时允许特定的非标准导入，可使用 also_allow 参数：

fickling.hook.activate_safe_ml_environment(also_allow=["my_custom.safe_module"])

场景二：使用命令行快速检测文件

无需编写代码，直接通过终端检查单个 pickle 文件的安全性。

# 检查文件安全性
fickling --check-safety -p suspicious_model.pkl

场景三：反编译 pickle 文件

将 pickle 字节码还原为可读的 Python AST 代码，用于逆向分析。

import ast
import pickle
from fickling.fickle import Pickled

# 加载 pickle 数据
data = pickle.dumps([1, 2, 3])
fickled_object = Pickled.load(data)

# 输出反编译后的 Python 代码结构
print(ast.dump(fickled_object.ast, indent=4))

场景四：追踪执行流程（沙箱模式）

安全地追踪 pickle 虚拟机的执行过程，而不会实际执行其中的恶意代码。

fickling --trace suspicious_model.pkl