Deserializer

关于项目

• Deserializer 是一款先进的抽象语法树（AST）静态分析引擎，旨在识别 Python 生态系统中不安全的对象重建与状态持久化汇聚点（sink），重点关注 AI、LLM、机器人技术、数据科学、机器学习与深度学习领域，但不限于此。
• Deserializer 旨在扫描和分析任何基于 Python 源代码的项目，例如应用、脚本、框架、库、Python pip 包等等。

核心技术能力

它远不止是一款传统的扫描器，而是提供了一个通用、高性能的审计框架，可审计超过 120 个库和格式——包括 YAML、Msgpack、CBOR 以及自定义 JSON 钩子——在这些地方，对"安全"序列化的传统信任掩盖了基于逻辑的关键 RCE 攻击向量。通过解析导入、别名和复杂的点分属性，该工具充当高保真信号放大器，优先标记现代分布式架构和 AI/ML 代码库中的危险代码路径。

该项目通过模块化的多阶段工作流运行，从原始检测过渡到深度技术审计。在初始的高速 SAST 扫描之后，生态系统利用专门的关系映射器追踪执行流，并使用结果处理器生成详细的安全报告。这种系统化方法确保每一项发现都被置于应用程序更广泛架构的上下文中，将海量遥测数据转化为可操作的研究资产和结构化里程碑，从而简化基础设施级攻击面的映射。

自主 AI 安全代理

在其最高层级，Deserializer 集成了一个自主 AI 安全代理（第 4 阶段），专门设计用于应对"自我命令注入"限制，并基于 HuggingFace 推理 API、本地 LLM（如 llama.cpp）或 OpenAI API 兼容接口，合成功能性复现指南。

随着项目的发展，它通过弥合抽象语法树静态分析、关系映射、报告与基于文档化研究的功能性漏洞利用开发之间的差距，持续定义自动化漏洞研究的前沿。

研究（AI、机器人技术、数据科学、机器学习与深度学习）

Deserializer 通过定位各类大规模 AI、机器人技术和数据科学项目及环境中的 RCE 和不安全反序列化路径，直接支持安全研究，例如 Genesis World (v0.2.1)、MuJoCo (v3.7.0)、LeRobot (v0.5.1)、Brax (v0.14.2)、TensorFlow (v2.21.0)、LangGraph (v1.1.6)、VibeVoice (v0.0.1)、Hugging Face Hub (v1.11.0)、PyGlove (v0.4.5) 等众多项目。

其能力已直接助力发现行业领先框架中的关键漏洞，证明了其在审计复杂 MLOps 和代理式 AI 环境方面的有效性。

Deserializer 的 4 个阶段

该项目分为四个不同的阶段，每个阶段旨在将分析从海量自动化遥测转向深度、功能性的安全研究：

阶段	标题	工具 / 引擎	目标
1	高速检测	deserializer.py（三遍扫描）	执行大规模 SAST，以识别潜在的反序列化汇聚点。
2	关系映射	结果处理器 / 映射器	通过追踪执行流和组件相互依赖关系，将发现置于上下文中。
3	技术综合	研究文档	将发现形式化为技术报告，映射基础设施级攻击面。
4	自主 AI 代理	AI 安全代理	使用 HuggingFace 推理 API、本地 LLM（如 llama.cpp）或 OpenAI API 兼容接口，自动化 0-day 发现并生成功能性复现指南/漏洞利用。

项目结构

仓库组织的高层映射以及每个专用目录的技术用途：

• agent/
  第 4 阶段 AI 安全代理的实现，包括深度分析、复现指南合成和 LLM 交互的编排逻辑。
• docs/
  项目文档、架构图、品牌资产和支持性高层技术材料的中央仓库。
• exploit_development/
  用于工程化功能性漏洞利用、研究反序列化原语（钩子/方法）以及记录跨平台编排技术的专用空间。
• modules/
  核心逻辑组件、辅助实用函数以及驱动工具链检测和关系映射阶段的扫描器扩展。
• reports/
  存储结构化安全分析输出、遥测数据以及扫描器在多阶段项目评估期间生成的审计结果。
• research/
  高保真漏洞报告、经过验证的概念验证（PoC）脚本以及对现代 AI/ML 框架进行的深度审计的集合。
• templates/
  标准化的报告和研究模板，用于在漏洞报告和关联报告中保持技术一致性。

性能与多进程

该扫描器具有基于 Python 的 concurrent.futures.ProcessPoolExecutor 构建的高性能并行执行引擎。它设计为可跨所有可用 CPU 核心扩展（可通过 -j 或 --concurrency 标志控制），使其能够在数秒内扫描数万个文件。

• 非阻塞 UI：具有稳定、停靠式进度条，并保留一行间隔以实现清晰的结果呈现。
• 原生信号处理：在 Windows 上，它通过 ctypes 利用原生 SetConsoleCtrlHandler，确保即使在繁重处理期间，Ctrl+C 也能 100% 响应。
• 静默回溯：工作进程被静默处理，以确保中断和内部错误不会干扰技术输出。
• 原生 Windows UI 支持：通过 ctypes 自动启用虚拟终端处理，以在现代 CMD 和 PowerShell 环境中提供原生 ANSI 颜色支持。

[!WARNING] 性能警告：在分析极大或复杂的文件（例如超过 1MB、2MB 或 3MB 的文件）时，工具在解析深层 AST 树时可能会显著变慢或看起来"卡住"。如果遇到此类瓶颈，请考虑使用 --timeout（跳过慢文件）和 --max-size（跳过巨大文件）标志以保持扫描速度。

功能说明

• 三遍扫描引擎：实现"牢不可破"的多层方法：
  • 第 1 遍（AST）：高保真语法分解，用于精确分析。
  • 第 2 遍（Token 回退）：遇到语法错误或无法解析的部分时，自动回退到基于流的 tokenizer。
  • 第 3 遍（正则应急）：最终的模式匹配层，确保在极端恶劣或碎片化的源文件中也能覆盖。
• 原生模板中和：内置对 Jinja2 和 Mako 标签的清理支持，使扫描器能够处理 Web 模板和代码生成文件，而不会因非 Python 语法而卡住。
• 调用与引用检测：不仅识别直接执行汇聚点（例如 pickle.loads()），还识别危险函数引用（例如 func = pickle.load），跨本地命名空间追踪赋值。
• 追踪导入/别名以解析如下调用：
  • import pickle as p → p.loads(...)
  • import torch as t → t.load(...)
  • 深层属性如 pkg.pickle.loads(...) 或 torch.serialization.load(...)
• 以 JSONL 格式输出发现，每行一个对象，包括：
  • 文件路径 + 位置（lineno、col_offset）
  • module、name、qualified_name
  • category 和 severity（额外字段，向后兼容）
  • parser：指示由哪个引擎遍次做出发现的元数据（ast、tokenize_fallback 或 regex_fallback）。
• 通过以下方式防范病态输入：
  • 最大文件大小（MAX_FILE_BYTES）
  • 最大访问 AST 节点数（MAX_AST_NODES）
• 可选：从 rules.json 加载自定义规则集，并对格式错误的条目/拼写错误发出警告。

安装

建议最低 Python 版本 3.9+，已测试 3.10+。

python --version
# Python 3.9+ recommended

设置要求：

• 环境：根据您的提供商，在根目录中创建 .env 文件：

  # For Hugging Face provider
  HF_TOKEN=your_token_here
  
  # For OpenAI / Local LLM provider
  HA_LLM_TOKEN=your_jwt_token_here
  

在运行扫描器之前，您必须安装依赖项：

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

用法

推荐用法：

不使用 AI 代理

python deserializer.py --path cloned-repo --rules-file rules.json -j 4 --out cloned-repo/cloned-repo.jsonl

使用 AI 代理（本地 LLM）

python deserializer.py --path cloned-repo --rules-file rules.json -j 4 --out cloned-repo/cloned-repo.jsonl --agent --agent-provider local --llm-api-url http://127.0.0.1:8181/v1

使用 AI 代理（OpenAI / 本地 LLM）

python deserializer.py --path cloned-repo --rules-file rules.json -j 4 --out cloned-repo/cloned-repo.jsonl --agent --agent-provider openai --llm-api-url http://127.0.0.1:8181/v1

使用 AI 安全代理进行 AI 驱动的深度分析（第 4 阶段）

此阶段集成了一个专门的 AI 安全代理，以执行深度代码审查并映射复杂的 0-day RCE 攻击向量。该代理分析发现以逆向"自我命令注入"上下文，并生成具有多平台重点（例如，攻击者 UNIX/Raspberry 对受害者 Windows）的技术复现指南。注意：仅当提供 --agent 标志时才执行此阶段。

推理提供商：

• Hugging Face（默认）：使用基于云的 API 模型，如 MiniMax-M2.5。
  • 需要在 .env 文件或环境变量中提供 HF_TOKEN。
  • 命令：python deserializer.py --path /path/to/repo --agent --agent-provider huggingface
• 本地 LLM（llama.cpp）：使用本地 REST 服务器（llama-server.exe）。
  • 启动服务器的命令示例：.\llama-server.exe --model .\models\model.gguf --host 127.0.0.1 --port 8181 --ctx-size 600000 --jinja
  • 命令：python deserializer.py --path /path/to/repo --agent --agent-provider local --llm-api-url http://127.0.0.1:8181/v1
• OpenAI 兼容：
  • 需要在 .env 中提供 HA_LLM_TOKEN（或 OPENAI_API_KEY）。
  • 命令：python deserializer.py --path /path/to/repo --agent --agent-provider openai --llm-api-url http://127.0.0.1:8181/v1

1. 基本扫描

扫描当前目录并将发现打印到终端（默认将 JSONL 写入 stdout）：

python deserializer.py

2. 定向审计

扫描特定仓库并将发现保存到 JSONL 文件：

python deserializer.py --path /path/to/my-repo --out audit_results.jsonl

3. 涡轮模式（性能调优）

使用 8 个并发进程和每个文件 5 秒超时以保持扫描推进：

python deserializer.py -j 8 --timeout 5 --out findings.jsonl

4. CI/CD 与流水线集成

禁用横幅并将 JSONL 直接流式传输到 stdout 以进行管道处理（人类日志将输出到 stderr）：

python deserializer.py --no-banner --out - | jq .

5. 加固 / 安全扫描

将处理限制为小于 1MB 的文件并跳过特定数据目录：

python deserializer.py --max-size 1048576 --skip-dirs "data,samples,tests"

6. 自定义检测规则

使用专有规则集检测特定逻辑调用：

python deserializer.py --rules-file my_custom_rules.json --out legacy_audit.jsonl

7. AI 深度分析

在扫描和映射完成后触发 AI 驱动的深度分析（第 4 阶段）：

python deserializer.py --path /path/to/repo --out findings.jsonl --agent

CLI 标志

• --path <dir>
  要扫描的根目录。默认：.

• --rules-file <path>
  JSON 规则集的路径。如果提供，它将覆盖内置的 DEFAULT_RULES。

• --out <path|->
  JSONL 结果的输出目标。使用 - 将 JSONL 写入 stdout。默认：-

• -j, --concurrency <int>
  要使用的并发进程数。默认：(CPU 核心数 - 2)。

• -t, --timeout <float>
  每个文件分析的超时时间（秒）。仅在并行模式下有效。默认：None（无超时）。

• --max-size <bytes>
  要处理的最大文件大小（字节）。默认：10,485,760（10 MiB）。

• --skip-dirs <list>
  要忽略的目录名称的逗号分隔列表（例如 tests,.git,env）。

• --no-banner
  禁用 ASCII 品牌横幅，以便在脚本中获得更清晰的输出。

• --agent
  运行 AI 驱动的深度分析（第 4 阶段）。可选；需要在 .env 或本地 LLM 服务器中提供有效凭据（HF_TOKEN 或 HA_LLM_TOKEN）。

• --agent-provider <provider>
  AI 代理的 LLM 推理提供商：huggingface、local 或 openai（默认：huggingface）。

• --llm-api-url <url>
  LLM 推理 API 的基础 URL（默认：http://127.0.0.1:8181/v1）。

输出格式（JSONL）

每行是一个独立的 JSON 对象。示例发现：

{
  "file": "some/path/module.py",
  "kind": "call",
  "module": "pickle",
  "name": "loads",
  "qualified_name": "pickle.loads",
  "category": "deserialize",
  "severity": "high",
  "lineno": 34,
  "col_offset": 11
}

错误（解析/读取/状态/限制）也以 JSONL 对象形式输出：

{ "file": "bad.py", "error": "syntax_error:..." }

退出代码：

• 0 如果扫描期间未发生错误
• 1 如果发生任何 IO/解析/限制错误（对 CI 有用）

规则文件格式（rules.json）

规则是一个以逻辑模块名称为键的 JSON 对象，包含：

• imports：要追踪的导入根列表
• calls：[module, function] 对的列表

示例：