
基于AST的静态代码分析器,配备由Agentic LLM驱动的关系映射,可在AI、LLM、机器人、数据科学、机器学习以及任何类型的Python源代码中发现Python RCE路径和深层反序列化链。

它远不止是一个传统扫描器,而是提供了一个通用、高性能的框架,用于审计 120 多个库和格式——包括 YAML、Msgpack、CBOR 以及自定义 JSON 钩子——在这些地方,对“安全”序列化的传统信任掩盖了基于逻辑的关键 RCE 向量。通过解析导入、别名和复杂的点分属性,该工具充当高保真信号放大器,在现代分布式架构和 AI/ML 仓库中优先标记危险代码路径。
该项目通过模块化、多阶段的工作流运行,从原始检测过渡到深度技术审计。在初始的高速 SAST 扫描之后,生态系统利用专门的关系映射器追踪执行流,并使用结果处理器生成详细的安全报告。这种系统化方法确保每项发现都被置于应用更广泛架构的上下文中,将海量遥测数据转化为可操作的研究资产和结构化里程碑,从而简化基础设施级攻击面的映射。
在其最高级阶段,Deserializer 集成了一个自主 AI 安全代理(第 4 阶段),专门设计用于应对“自我命令注入”限制,并基于 HuggingFace 推理 API、本地 LLM(如 llama.cpp)或兼容 OpenAI API 合成可用的复现指南。
随着项目的发展,它通过弥合抽象语法树静态分析、关系映射、报告以及基于有据可查的研究进行功能性漏洞利用开发之间的差距,持续定义自动化漏洞研究的前沿。
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 环境方面的有效性。
该项目分为四个不同阶段,每个阶段旨在将分析从海量自动化遥测转向深入的功能性安全研究:
| 阶段 | 标题 | 工具 / 引擎 | 目标 |
|---|---|---|---|
| 1 | 高速检测 | deserializer.py(三遍扫描) | 执行大规模 SAST,以识别潜在的反序列化汇聚点。 |
| 2 | 关系映射 | 结果处理器 / 映射器 | 通过追踪执行流和组件相互依赖关系,将发现置于上下文中。 |
| 3 | 技术综合 | 研究文档 | 将发现形式化为技术报告,映射基础设施级攻击面。 |
| 4 | 自主 AI 代理 | AI 安全代理 | 使用 HuggingFace 推理 API、本地 LLM(如 llama.cpp)或兼容 OpenAI API 自动化 0-day 发现,并生成可用的复现指南/漏洞利用。 |
仓库组织的高层地图,以及每个专门目录的技术用途:
agent/docs/exploit_development/modules/reports/research/templates/该扫描器具有基于 Python 的 concurrent.futures.ProcessPoolExecutor 构建的高性能并行执行引擎。它旨在跨所有可用 CPU 核心进行扩展(可通过 -j 或 --concurrency 标志控制),使其能够在几秒内扫描数万个文件。
ctypes 使用原生 SetConsoleCtrlHandler,以确保即使在繁重处理期间,Ctrl+C 也能 100% 响应。ctypes 自动启用虚拟终端处理,以在现代 CMD 和 PowerShell 环境中提供原生 ANSI 颜色支持。[!WARNING] 性能警告:在分析极大或复杂的文件(例如,大小超过 1MB、2MB 或 3MB)时,工具在解析深层 AST 树时可能会显著变慢或看起来“卡住”。如果遇到此类瓶颈,请考虑使用
--timeout(跳过慢速文件)和--max-size(跳过超大文件)标志来保持扫描速度。
pickle.loads()),还识别危险函数引用(例如 func = pickle.load),并在本地命名空间中跟踪赋值。import pickle as p → p.loads(...)import torch as t → t.load(...)pkg.pickle.loads(...) 或 torch.serialization.load(...)lineno、col_offset)module、name、qualified_namecategory(额外字段,向后兼容)parser:元数据,指示是哪个引擎遍次做出的发现(ast、tokenize_fallback 或 regex_fallback)。MAX_FILE_BYTES)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
推荐用法:
python deserializer.py --path cloned-repo --rules-file rules.json -j 4 --out cloned-repo/cloned-repo.jsonl
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
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 安全代理,用于执行深度代码审查并映射复杂的 0-day RCE 向量。该代理分析发现结果,以逆向“自我命令注入”上下文,并生成以多平台为重点的技术复现指南(例如,攻击者 UNIX/Raspberry 对比受害者 Windows)。注意:仅当提供 --agent 标志时,才会执行此阶段。
推理提供方:
.env 文件或环境变量中提供 HF_TOKEN。python deserializer.py --path /path/to/repo --agent --agent-provider huggingfacellama.cpp):使用本地 REST 服务器(llama-server.exe)。
.\llama-server.exe --model .\models\model.gguf --host 127.0.0.1 --port 8181 --ctx-size 600000 --jinjapython deserializer.py --path /path/to/repo --agent --agent-provider local --llm-api-url http://127.0.0.1:8181/v1.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扫描当前目录并将发现结果打印到终端(默认将 JSONL 写入 stdout):
python deserializer.py
扫描特定仓库并将发现结果保存到 JSONL 文件:
python deserializer.py --path /path/to/my-repo --out audit_results.jsonl
使用 8 个并发进程,并为每个文件设置 5 秒超时,以保持扫描持续推进:
python deserializer.py -j 8 --timeout 5 --out findings.jsonl
禁用横幅并将 JSONL 直接流式输出到 stdout 以便管道处理(人类可读日志将输出到 stderr):
python deserializer.py --no-banner --out - | jq .
将处理范围限制在 1MB 以下的文件,并跳过特定的数据目录:
python deserializer.py --max-size 1048576 --skip-dirs "data,samples,tests"
使用专有规则集来检测逻辑特定的调用:
python deserializer.py --rules-file my_custom_rules.json --out legacy_audit.jsonl
在扫描和映射完成后,触发 AI 驱动的深度分析(阶段 4):
python deserializer.py --path /path/to/repo --out findings.jsonl --agent
--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)。
每一行都是一个独立的 JSON 对象。示例发现:
{
"file": "some/path/module.py",
"kind": "call",
"module": "pickle",
"name": "loads",
"qualified_name": "pickle.loads",
"category": "deserialize",
"lineno": 34,
"col_offset": 11
}
错误(解析/读取/stat/限制)也会以 JSONL 对象的形式输出:
{ "file": "bad.py", "error": "syntax_error:..." }
退出码:
01(对 CI 有用)rules.json)规则是一个以逻辑模块名称为键的 JSON 对象,包含:
imports:要跟踪的导入根列表calls:[module, function] 对列表示例: