DarkAngel-0x0/pwntemplate
GitHub: DarkAngel-0x0/pwntemplate
pwntemplate 是一款基于 pwntools 的二进制漏洞利用自动化分析工具，能验证利用技术可行性、恢复 gadgets 并借助 AI 自动生成和修复 exploit。
Stars: 5 | Forks: 0
### pwn 分析 · 经验证的技术 · AI 构建的 exploit
[](https://www.python.org/)
[](https://github.com/Gallopsled/pwntools)
[](LICENSE)
[](#contributing)
*将它指向一个 binary。它会总结保护机制，证明哪些利用*
*技术真正可行，挖掘出你所需的确切 gadgets，并且 —— 如果你*
*要求的话 —— 编写并**自我修复**出一个可用的 exploit。*
## 适用范围与预期用途
`pwntemplate` 是一个二进制漏洞利用研究工具。它专为以下场景构建：
- **CTF 比赛** —— 本地或远程，练习或竞赛
- **授权的渗透测试** —— 你拥有明确书面测试许可的
系统
- **你自己的 binary** —— 针对你拥有或控制的软件进行漏洞
研究、课程作业或 exploit 开发
练习
它**不**适用于你未拥有或缺乏明确授权的系统、
网络或 binary。AI 辅助的起草和
`--repair` 功能会自动生成并执行 payload —— 请以
你手动运行任何 exploit 时相同的谨慎态度来对待这种
能力，并且仅将其指向你已获授权攻击的
目标。
如果你不确定某个目标是否在适用范围内，那它就不在范围内 —— 先获得
许可。
## 一屏展示差异
大多数工具会告诉你 *"ret2csu 看起来可行。"* 而 `pwntemplate` 会在分析过程中
恢复 `__libc_csu_init` 的寄存器布局，并为你提供一个单行命令，
它已经知道**该**用哪个函数进行泄漏，并为你构建好栈帧。
| 传统的 Ret2CSU（手动） | 使用 pwntemplate |
|---|
|
```
# 自己找到两个 gadget
csu_pop = 0x40119a # pop rbx;rbp;r12;r13;r14;r15;ret
csu_call = 0x401180 # mov rdx,r15; mov rsi,r14;
# mov edi,r13d; call [r12+rbx*8]
def csu(fnptr, edi, rsi, rdx, ret):
p = p64(csu_pop)
p += p64(0) # rbx=0 -> [r12+rbx*8]
p += p64(1) # rbp=1 -> loop exits
p += p64(fnptr) # r12 = ptr to call
p += p64(edi) # r13 -> edi
p += p64(rsi) # r14 -> rsi
p += p64(rdx) # r15 -> rdx
p += p64(csu_call)
p += b'A'*0x38 # <- get THIS exactly right
p += p64(ret)
return p
# 你也可以选择 leak fn 及其 GOT slot，
# 了解 calling convention，thread main 回溯
pl = b'A'*OFFSET
pl += csu(elf.got['write'], 1,
elf.got['write'], 8, elf.sym['main'])
```
|
```
# CSU 布局在
# 分析过程中已自动恢复；你只需说“leak，然后返回
# 到 main”——它会选择 fn 并构建它
payload, fn, got = Ret2Csu_leak(
main_addr=elf.sym['main'])
io.sendline(b'A'*OFFSET + payload)
leak = u64(io.recv(6).ljust(8, b'\x00'))
libc.address = leak - libc.sym[fn]
# fn == 它使用的任意 GOT fn
```
*需要显式调用而不是泄漏？*
```
Ret2Csu(elf.plt['func'], rdi=a, rsi=b, rdx=c)
```
`0x38` 的填充、`rbx=0`/`rbp=1` 的循环
条件，以及寄存器→参数映射（即使
编译器重新排列了 pops 操作）都通过
恢复的 `CSU_LAYOUT` 自动处理。
|
## 演示
▶ pwntemplate ./demo —— banner + 已验证的技术清单
```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ __ __ __ ┃
┃ ______ ______ / /____ ____ ___ ____ / /___ _/ /____ ┃
┃ / __ \ | /| / / __ \/ __/ _ \/ __ `__ \/ __ \/ / __ `/ __/ _ \ ┃
┃ / /_/ / |/ |/ / / / / /_/ __/ / / / / / /_/ / / /_/ / /_/ __/ ┃
┃ / .___/|__/|__/_/ /_/\__/\___/_/ /_/ /_/ .___/_/\__,_/\__/\___/ ┃
┃/_/ /_/ ┃
┃ v1.0.0 pwn analysis • verified techniques • AI-built exploits ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
Exploitation Technique Checklist (verified)
Technique Status Why / what's missing
───────────────────────────────────────────────────────────────────────
ret2libc ✔ YES needs libc leak via puts() then system from libc
ret2plt leak ✔ YES leak puts(got) → libc base
ret2csu ✘ NO __libc_csu_init popper/caller not both found
SROP ✘ NO no syscall/int 0x80 gadget; no pop rax/eax
one_gadget ✔ YES 4 candidate(s): 0xe1e6f, 0xff54a, … + constraints
Shellcode (NX off) ✘ NO NX enabled — stack/heap not executable
mprotect RWX ✘ NO no mprotect+read and no syscall+POP_RAX path
ORW chain ✘ NO no syscall gadget; no open+read+write via PLT
GOT overwrite ✘ NO no write-what-where gadget and no format string
ret2dlresolve ✔ YES forge reloc → _dl_runtime_resolve(system) @ 0x404e00
Format String ✘ NO no printf(non-literal) call site found
```
完整记录请见：[`docs/demos/analyze.txt`](docs/demos/analyze.txt)。
▶ POC —— ret2csu 的两种解法：solve_pwntemplate.py（自动生成）对比 manual.py（手写），两者均成功获取 shell
## 功能特性
- **按挑战划分的工作目录** —— 复制 binary + libc；缓存所有产出物
（`analysis.json`、反汇编、反编译、gadgets、one_gadget、seccomp）。
- **严格的技术验证** —— 仅当所有前置条件确实具备时，才会将 11 种
技术标记为可行，并各自附上理由。杜绝 RELRO/`printf("%s")`
误报。
- **智能 gadget 挖掘** —— 多 pop 链、write-what-where 算术
gadget，以及为 ret2csu 自动恢复的 `__libc_csu_init` 布局。
- **带约束的 one_gadget** —— 确切的 `[r15]==NULL …` 条件，而
不仅仅是一个数量，以便你选择可满足的项。
- **格式化字符串自动 fuzzer** —— 查找 `%N$p` 输入偏移量并对
每次泄漏（canary/libc/PIE/stack/heap）进行分类。这是一个独立工具，并拥有自己的
[完整手册](docs/FUZZER.md)。
- **libc 爆破辅助工具** —— `find_libc_rip()` 返回*所有*候选 libc，并提供
解析出的 `system`/`binsh`，以便你识别远程
环境。
- **AI 助手 + 自我修复** —— 将缓存的分析结果喂给 Claude，编写
`xploit_ai.py`，然后运行并修复它，直到成功获取 shell。支持官方 API 或
自定义中继。
## 支持的架构
`pwntemplate` 面向 **x86 Linux ELF** binary：
| 架构 | 支持 |
|--------------|---------|
| **x86-64 (amd64)** | ✅ 完整 —— 所有技术，包括 ret2csu, SROP, gadget 挖掘 |
| **x86 (i386, 32位)** | ✅ 支持 —— fuzzer, SROP/`int 0x80`, ret2libc/plt/dlresolve, leak 解析（ret2csu 本质上仅限 x86-64） |
| **ARM / AArch64 / MIPS / RISC-V** | ❌ 不支持 —— gadget、寄存器约定和模板都假定基于 x86 |
非 x86 binary 不会被直接拒绝，但恢复出的 gadget 和
生成的模板将毫无意义 —— 请将 amd64 视为主要目标，
而 i386 受到良好支持。
## 安装
```
git clone https://github.com/DarkAngel-0x0/pwntemplate
cd pwntemplate
make install # pip-installs the package AND the external tools below
# └── 等同于： pip install -e . && ./scripts/install-deps.sh
```
仅运行 `pip install -e .` 就能为你提供 `pwntemplate` 命令及其 Python 依赖
（`pwntools`、`rich`、`requests`、`ROPgadget`）。而**外部 CLI 工具** ——
`radare2`、`one_gadget`、`seccomp-tools`、`checksec`、`objdump`、`gdb` —— 则由
[`scripts/install-deps.sh`](scripts/install-deps.sh)（通过 apt + gem）进行安装，
该脚本是**幂等**的，会跳过任何已存在的工具。随时可通过 `make deps` 单独运行它。
缺失工具只会降低相关功能的可用性；核心功能
依然有效。
```
pip install -e ".[ai]" # optional: the anthropic SDK (raw-HTTP path needs no SDK)
```
## 快速开始
```
pwntemplate ./chall # analyze + generate xploit.py
pwntemplate ./chall --host 1.2.3.4 --port 1337
pwntemplate ./chall --ai --api-key sk-... # let Claude draft xploit_ai.py
pwntemplate ./chall --repair # draft + auto-fix until it pops a shell
```
在捆绑的示例上立即尝试：
```
cd examples && make && pwntemplate ./demo
```
所有产出物都会存入 `pwn_challenge_
/` 中。完整指南：
**[docs/MANUAL.md](docs/MANUAL.md)**。
### 本地与远程 —— `--host/--port` 的实际作用
它们处于**两个不同的阶段**，并且互不冲突：
- **生成时的 `--host/--port`** 仅用于**将默认目标固化到
脚本中**，例如 `args.HOST or "1.2.3.4"`。它*不会运行*任何内容 —— 这只是意味着
你以后无需重新输入地址。
- **运行时的 `REMOTE [host] [port]`** 才是真正进行连接的操作。如果不带
参数，exploit 将在**本地**运行；添加 `REMOTE` 可指向内置的默认目标，
或者通过传入 host/port 来当场覆盖它。
```
pwntemplate ./chall --host 1.2.3.4 --port 1337 # bakes default into xploit.py
python3 xploit.py # LOCAL process
python3 xploit.py REMOTE # -> 1.2.3.4:1337 (the baked default)
python3 xploit.py REMOTE other.host 31337 # -> override for this run
```
如果你从不传入 `--host/--port`，默认值就是 `127.0.0.1:1337`，并且你
始终可以在运行时使用 `REMOTE host port` 进行覆盖。
### AI 后端 —— 不局限于 Anthropic
助手使用的是 **Anthropic Messages API**（`/v1/messages`）。这意味着：
- **默认：** 官方 Anthropic API —— `--api-key`（或 `ANTHROPIC_API_KEY`）。
- **任何其他模型：** 将 `--base-url`（或 `ANTHROPIC_BASE_URL`）指向一个
暴露了 Anthropic 兼容 endpoint 的网关。像
[**LiteLLM**](https://github.com/BerriAI/litellm) 这样的网关会在 `/v1/messages` 背后代理 **OpenAI、Gemini、
本地 Ollama、Groq 等**，因此你可以使用想要的任何模型来驱动 `pwntemplate`
—— 只需将 `--model` 设置为该网关的 model id 即可。
- **锁定官方客户端的中继会被自动处理：** 如果设置了 `--base-url`
并且安装了 `claude` CLI，调用将自动通过其路由。
```
# 官方 Anthropic
pwntemplate ./chall --ai --api-key sk-ant-...
# 通过 LiteLLM（或类似）gateway 使用任何 model
pwntemplate ./chall --ai \
--base-url http://localhost:4000 \
--api-key sk-litellm-... \
--model gpt-4o # or gemini-1.5-pro, ollama/llama3, ...
```
后端会按以下顺序尝试：**claude CLI**（设置了中继时） → **anthropic
SDK** → **原生 HTTP**（仅需 `requests`）。
### 关于 `--repair` 可靠性的说明
`--repair` 会起草 exploit、运行它，并根据失败情况进行迭代 ——
但**不保证**成功，且结果因
模型而异：
- **模型能力影响巨大。** `--repair` 依赖于模型阅读
反汇编代码、推断偏移量/gadget，以及在多次迭代中
调试自身错误的能力。前沿模型（Claude、GPT-4 级别等）
能较好地处理这些。较小或较旧的模型 —— 量化的本地
Ollama 模型、较旧的开源权重 checkpoint 等 —— 可能会陷入循环而无法
收敛、误读缓存的分析，或者生成看起来合理
但实际上错误的 payload。
- **它可能会以隐蔽的方式静默失败。** 较弱的模型可能会通过修改与
实际 bug 无关的内容来“修复”
exploit，生成一个运行无误但无法弹出 shell 的
脚本，或者在
重试预算耗尽后放弃，且没有说明原因。
- **务必审查生成的脚本。** 将 `xploit_ai.py`（以及任何
`--repair` 的输出）视为**草稿**，而不是已完成的
exploit。在信任它之前请先阅读，尤其是针对
远程目标时。
- **经过验证的技术清单与此无关。**
`pwntemplate ./chall` 生成的清单是确定性的，不依赖于
任何 AI 模型 —— 只有 `--ai`/`--repair` 的*起草*步骤
才会用到。
如果修复循环无法收敛，切换到更强大的模型（或
官方 Anthropic API）通常比调整重试次数能更快解决
问题。
## 贡献
欢迎提交 Issues 和 PR。在提交之前，请运行示例和独立 fuzzer
（`python3 -m pwntemplate.fuzzer ./demo`）作为冒烟测试。
## 许可证
MIT © DarkAngel-0x0。基于 [pwntools](https://github.com/Gallopsled/pwntools) 构建。标签：AI辅助, Go语言工具, Python, Web报告查看器, 二进制分析, 云安全运维, 无后门, 逆向工具