JINGQINLIN/Palimpsest
GitHub: JINGQINLIN/Palimpsest
Palimpsest 是一个利用大模型对 Ghidra 反编译伪代码进行多层语义增强并自动构建 CodeQL 数据库的 IoT 固件分析框架。
Stars: 2 | Forks: 0
一个从 Ghidra 反编译到 CodeQL 数据库构建的语义代码增强框架
English
## 项目概述
Palimpsest 是一个 LLM 辅助的语义代码增强框架，连接了 Ghidra 反编译和 CodeQL 数据库构建。它针对 IoT 设备固件分析以及生成可供 CodeQL 构建的源代码进行了优化。
该项目专注于对 IoT 设备固件的反编译代码进行语义增强，使其适用于后续基于 CodeQL 的固件漏洞追踪、语义查询和软件成分分析。
## 原理与架构
Palimpsest 采用多层 LLM 辅助的语义增强 pipeline。它逐步增强由 Ghidra 生成的伪代码，并自动从增强后的代码中构建 CodeQL 数据库。
整体增强工作流程如下：
```
Ghidra MCP Service
│
│ Extract decompiled pseudocode from firmware functions
▼
LLM-Structure
│
│ Recover code structure, control flow, and function logic
▼
LLM-Naming
│
│ Recover names of variables, functions, and key semantic objects
▼
LLM-Agent review
│
│ Check semantic consistency and improve naming and code expression
▼
CodeQL Database (automatic no-build database creation)
```
各个阶段的职责如下：
| 阶段 | 输入 | 输出 | 目的 |
| --- | --- | --- | --- |
| `Ghidra MCP` | 固件二进制文件或反编译结果 | 函数级伪代码 | 提取反编译代码以供后续处理 |
| `LLM-Structure` | 原始伪代码 | 结构增强代码 | 恢复控制流、函数边界和代码组织结构 |
| `LLM-Naming` | 结构增强代码 | 命名增强代码 | 改善变量、函数和关键语义对象的命名 |
| `LLM-Agent` | 结构和命名增强代码 | 最终增强代码 | 恢复用于污点分析的 source→sink 链；修复跨函数一致性 |
| `CodeQL` | 语义增强代码集合 | CodeQL 数据库 | 支持漏洞追踪、语义查询和软件成分分析 |
## 安装说明
```
git clone https://github.com/JINGQINLIN/Palimpsest.git
cd Palimpsest
```
安装依赖项：
```
pip install -r requirements.txt
```
## 使用方法
运行项目：
```
python main.py
```
示例：
```
python main.py .\samples\udhcpd_dir895.bin
```
## 输出示例
```
(semant) semant_func > python .\main.py .\samples\udhcpd_dir895.bin
1. Raw package
binary samples\udhcpd_dir895.bin
raw output\udhcpd_dir895.bin\raw
Ghidra fetch
binary samples\udhcpd_dir895.bin
output output\udhcpd_dir895.bin\raw
program udhcpd_dir895.bin-41da71
status waiting for analysis
functions 83
0x0000f34c FUN_0000f34c ━━━━━━━━━━━━━━━━━━━━━━━━ 83/83 0:00:03
Ghidra fetch done
functions 83 ok, 0 failed
output output\udhcpd_dir895.bin\raw
2. Semantic reconstruction
functions 78
model glm-5.1
output output\udhcpd_dir895.bin
0x0000f550 FUN_0000f550 ━━━━━━━━━━━━━━━━━━━━━━━━ 78/78 0:31:27
3. CodeQL source
structs 12
files 78 C files
output output\udhcpd_dir895.bin\codeql\src
symbols 143
unresolved 17
4. Agent review
functions 78
model glm-5.1
changes 105 (rename 8, edit 90, rewrite 5, struct 2)
functions edited 38
tool calls 263
tokens in 244.1K | out 21.4K | cache 11.43M | total 11.70M
log output\udhcpd_dir895.bin\reconstruction\agent_review.json
note stopped at tool_use; review may be incomplete (raise _MAX_ITERATIONS)
5. CodeQL database
command D:\Users\Apps\Dev\CodeQL\codeql.exe
source output\udhcpd_dir895.bin\codeql\src
db output\udhcpd_dir895.bin\codeql\db
status created output\udhcpd_dir895.bin\codeql\db
Done
raw funcs 83
skipped 5
functions 78 ok, 0 failed
tokens in 441.5K | out 142.5K | cache 11.46M | total 12.04M
recon output\udhcpd_dir895.bin\reconstruction\functions
registry output\udhcpd_dir895.bin\reconstruction\registry
codeql src output\udhcpd_dir895.bin\codeql\src
codeql db output\udhcpd_dir895.bin\codeql\db
```
每次运行都会从 Ghidra 重新获取数据，并为固件重建输出包。
可选的后处理脚本：
```
python scripts/postprocess.py output/udhcpd_dir895.bin
# 仅运行一个步骤：
python scripts/postprocess.py output/udhcpd_dir895.bin --summarize-only
python scripts/postprocess.py output/udhcpd_dir895.bin --report-only
```
这将为每个函数写入 `summary.json` 文件，并生成 `reports/firmware_report.md`。
验证 CodeQL 查询：
```
$codeql = "path to codeql.exe"
$packs = "path to codeql-queries"
& $codeql query run --quiet --search-path $packs queries\exec_calls.ql --database output\udhcpd_dir895.bin\codeql\db
```
在这里，`queries/exec_calls.ql` 是一个简单的示例查询，用于定位 `system()` / `popen()` / `exec*()` 调用以及用于命令执行的常见固件包装函数。
## 输出结构
```
output//
raw/.json Raw Ghidra-decompiled pseudocode for each function
reconstruction/
functions/0x/
raw.c structured.c named.c naming_map.txt
registry/
symbol_registry.{sqlite3,json,txt} Cross-function symbol naming table
struct_registry.sqlite3 Cross-function structure layout table
unresolved_symbols.txt Placeholders still unresolved after the first two recovery layers
agent_review.json Change records and summary from Agent review
flows.json Ranked sink call chains (Agent review targets)
codeql/
src/
recopilot_stubs.h Header file for Ghidra pseudo-types, macros, and common API declarations
recopilot_types.h Structure header automatically generated from the structure registry
0x_.c Final enhanced source code used for database construction
db/ CodeQL database
reports/firmware_report.md Firmware analysis report from scripts/postprocess.py, optional
```
## 代码结构
```
main.py Entry point; orchestrates the five pipeline steps
config.py Loads local_config.yaml
pipeline/
console.py Rich console output
paths.py Output path constants and resolution
llm.py LLM client and token accounting
outputs.py Disk output utilities
prompts/ Jinja2 templates for structure, naming, and summary prompts, plus the template loader
registry/
naming.py NamingRegistry: cross-function symbol naming table
structs.py StructRegistry: cross-function structure layout table
header.py Deterministically generates recopilot_types.h from the structure registry
stages/
ghidra.py Step 1: Ghidra fetch / raw package loading
reconstruct.py Step 2: two-pass structure recovery and naming
summary.py / report.py Optional post-processing for function summaries and firmware reports
codeql/
stubs.py Emits the static content of recopilot_stubs.h
builder.py Step 3: source export; Step 5: database construction
agent/
runner.py Step 4: tool_runner agent-review loop
flows.py Build ranked source→sink chains before review
tools.py Agent toolset
graph.py Builds a static call graph from source code
playbook.md Agent task objectives and constraints
codeql_guide.md Guidance for Agent review to produce CodeQL-friendly code
benchmark/ Pipeline output evaluation vs open-source gold (see benchmark/README.md)
scripts/ Post-processing entry point (summarize + firmware report)
queries/ Example CodeQL queries
contexts/ RAG domain priors, such as dhcp_server.yaml, injected into prompts
samples/ Example firmware samples
```
## License
本项目基于 MIT License 开源。
简体中文
## 项目简介
Palimpsest 是一个基于大模型辅助的从 Ghidra 反编译工具到可供 CodeQL 建库的代码语义增强框架。重点针对 IoT 设备固件与 CodeQL 建库为目标进行优化。
适用场景主要聚焦于 IoT 设备固件到 CodeQL 建库代码的语义增强，以适配后续基于 CodeQL 的固件漏洞追踪分析与软件成分分析等场景。
## 项目原理与框架
Palimpsest 采用基于大模型辅助的多层语义增强方案，对 Ghidra 反编译工具输出的伪代码进行逐级增强，并进行 CodeQL 的自动建库。
项目整体增强流程如下：
```
Ghidra MCP 服务
│
│ 提取固件函数反编译伪代码
▼
LLM-Structure
│
│ 恢复代码结构，整理控制流与函数逻辑
▼
LLM-Naming
│
│ 恢复变量、函数和关键对象命名
▼
LLM-Agent review
│
│ 校验语义一致性，优化命名与代码表达。
▼
CodeQL Database (已自动跳过编译建库)
```
其中，各阶段的职责如下：
| 阶段 | 输入 | 输出 | 作用 |
| --------------- | ---------------------- | ------------- | ------------------------------------ |
| `Ghidra MCP` | 固件二进制或反编译结果 | 函数级伪代码 | 提取可供后续处理的反编译代码 |
| `LLM-Structure` | 原始伪代码 | 结构增强代码 | 恢复控制流、函数边界和代码组织结构 |
| `LLM-Naming` | 结构增强代码 | 命名增强代码 | 改善变量、函数和关键语义对象命名 |
| `LLM-Agent` | 结构与命名增强代码 | 最终增强代码 | 优先恢复 source→sink 链，修复跨函数一致性 |
| `CodeQL` | 语义增强代码合集 | CodeQL 数据库 | 支持漏洞追踪、语义查询与软件成分分析 |
## 安装方法
```
git clone https://github.com/JINGQINLIN/Palimpsest.git
cd Palimpsest
```
安装依赖：
```
pip install -r requirements.txt
```
## 使用方法
运行项目：
```
python main.py 固件路径
```
示例：
```
python main.py .\samples\udhcpd_dir895.bin
```
## 输出示例
```
(semant) semant_func > python .\main.py .\samples\udhcpd_dir895.bin
1. Raw package
binary samples\udhcpd_dir895.bin
raw output\udhcpd_dir895.bin\raw
Ghidra fetch
binary samples\udhcpd_dir895.bin
output output\udhcpd_dir895.bin\raw
program udhcpd_dir895.bin-41da71
status waiting for analysis
functions 83
0x0000f34c FUN_0000f34c ━━━━━━━━━━━━━━━━━━━━━━━━ 83/83 0:00:03
Ghidra fetch done
functions 83 ok, 0 failed
output output\udhcpd_dir895.bin\raw
2. Semantic reconstruction
functions 78
model glm-5.1
output output\udhcpd_dir895.bin
0x0000f550 FUN_0000f550 ━━━━━━━━━━━━━━━━━━━━━━━━ 78/78 0:31:27
3. CodeQL source
structs 12
files 78 C files
output output\udhcpd_dir895.bin\codeql\src
symbols 143
unresolved 17
4. Agent review
functions 78
model glm-5.1
changes 105 (rename 8, edit 90, rewrite 5, struct 2)
functions edited 38
tool calls 263
tokens in 244.1K | out 21.4K | cache 11.43M | total 11.70M
log output\udhcpd_dir895.bin\reconstruction\agent_review.json
note stopped at tool_use; review may be incomplete (raise _MAX_ITERATIONS)
5. CodeQL database
command D:\Users\Apps\Dev\CodeQL\codeql.exe
source output\udhcpd_dir895.bin\codeql\src
db output\udhcpd_dir895.bin\codeql\db
status created output\udhcpd_dir895.bin\codeql\db
Done
raw funcs 83
skipped 5
functions 78 ok, 0 failed
tokens in 441.5K | out 142.5K | cache 11.46M | total 12.04M
recon output\udhcpd_dir895.bin\reconstruction\functions
registry output\udhcpd_dir895.bin\reconstruction\registry
codeql src output\udhcpd_dir895.bin\codeql\src
codeql db output\udhcpd_dir895.bin\codeql\db
```
每次运行系统都会重新从 Ghidra 抓取，并重建该固件的输出包。
可选的后处理脚本：
```
python scripts/postprocess.py output/udhcpd_dir895.bin
# 或只跑其中一步：
python scripts/postprocess.py output/udhcpd_dir895.bin --summarize-only
python scripts/postprocess.py output/udhcpd_dir895.bin --report-only
```
会生成每函数的 `summary.json`，以及 `reports/firmware_report.md`。
验证 CodeQL 查询：
```
$codeql = "codeql.exe 地址"
$packs = "codeql-queries 地址"
& $codeql query run --quiet --search-path $packs queries\exec_calls.ql --database output\udhcpd_dir895.bin\codeql\db
```
其中，`queries/exec_calls.ql` 是一个简单示例，用于查找 `system()`/`popen()`/`exec*()` 及常见固件封装执行函数。
## 输出结构
```
output//
raw/.json Ghidra 反编译函数原始伪代码
reconstruction/
functions/0x/
raw.c structured.c named.c naming_map.txt
registry/
symbol_registry.{sqlite3,json,txt} 跨函数符号命名表
struct_registry.sqlite3 跨函数结构体布局表
unresolved_symbols.txt 前两层还原仍未解析的占位符
agent_review.json Agent review 的修改记录与总结
flows.json 排序后的 sink 调用链（Agent 审查目标）
codeql/
src/
recopilot_stubs.h Ghidra 伪类型 / 宏 / 常见 API 声明头文件
recopilot_types.h 由结构体表自动生成的结构体头文件
0x_.c 最终建库用的增强源码
db/ CodeQL database
reports/firmware_report.md 固件分析报告，由 scripts/postprocess.py 生成（可选）
```
## 代码结构
```
main.py 入口，编排 5 个步骤
config.py 读取 local_config.yaml
pipeline/
console.py rich 控制台输出
paths.py 输出路径常量与解析
llm.py LLM client 与 token 统计
outputs.py 磁盘写入
prompts/ Jinja2 模板 (structure/naming/summary) 与加载器
registry/
naming.py NamingRegistry：跨函数符号命名表
structs.py StructRegistry：跨函数结构体布局表
header.py 从结构体表确定性生成 recopilot_types.h
stages/
ghidra.py 步骤 1：Ghidra fetch / 读取 raw package
reconstruct.py 步骤 2：结构整理 + 命名两遍
summary.py / report.py 后处理（函数摘要与固件报告生成，可选）
codeql/
stubs.py recopilot_stubs.h 静态内容释放
builder.py 步骤 3: 导出源码 与 步骤 5: 建库
agent/
runner.py 步骤 4：tool_runner agent-review 循环
flows.py Agent 启动前构建 source→sink 链
tools.py agent 工具集
graph.py 从源码静态构建调用图
playbook.md agent 任务目标与约束
codeql_guide.md 用于指引 Agent review 出 CodeQL 友好代码
benchmark/ 对比 pipeline 输出与开源源码 gold（见 benchmark/README.md）
scripts/ 后处理入口（函数摘要 + 固件报告）
queries/ CodeQL 查询示例
contexts/ RAG 领域先验,如 dhcp_server.yaml，会被注入到 prompt 中
samples/ 示例固件
```
## License
本项目基于 MIT License 开源。
标签：C2, DLL 劫持, 云资产清单, 代码增强, 固件分析, 大语言模型, 自动化分析, 跨站脚本, 逆向工具, 逆向工程, 错误基检测, 静态代码分析