定向模糊测试 sgzeng/pbfuzz

pbfuzz-dsh

PBFuzz（CCS'26 的智能体定向模糊测试器）以插件形式提供给 DeepSeek Harness (DSH)。
把智能体指向目标仓库和一个 bug（CVE、补丁、崩溃堆栈，或者只给 file:line），它就会跑定向模糊测试循环，直到产出一个经过验证的 Proof-of-Vulnerability 输入。

快速开始

Ubuntu 22.04/24.04 x86-64，Node.js ≥ 22，Python ≥ 3.11

1. 配置 DeepSeek Harness —— 参照官方文档安装 DSH，并配置你的 DeepSeek API key。使用这些插件验证过的 DSH 版本（见 HARNESS_COMMIT 里的 DSH_VERSION）；npm 的 latest 可能超出它们的 peer 范围。

2. 从 npm 安装 pbfuzz

npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add @pbfuzz/dsh-pbfuzz

就这些：包里自带 Python 引擎、它的 schema 和 PyYAML。
然后用 npx @deepseek-ai/dsh@0.2.0-rc.2 web 启动 DSH。

可选的静态分析（C/C++ 可达性；需要 LLVM 14 工具链，见 packages/dsh-kanalyzer）：

npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add @pbfuzz/dsh-kanalyzer

用同一个 plugin 命令管理安装（配置档不是 web 时加上 --profile NAME），之后重启 DSH：

npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web list # installed plugins and versions
npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add @pbfuzz/dsh-pbfuzz@0.1.14 # a specific release
npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web remove @pbfuzz/dsh-pbfuzz

要升级到更新的版本，按精确版本号 add 它；npm view @pbfuzz/dsh-pbfuzz version 会打印最新版本号。版本列表见 npmjs.com/package/@pbfuzz/dsh-pbfuzz。

从源码构建

git clone <this-repo-url> pbfuzz-dsh && cd pbfuzz-dsh
./install.sh

这会构建插件和 Python 引擎，并把本地构建加入 DSH。重启 npx @deepseek-ai/dsh@0.2.0-rc.2 web 就完成了。

| 脚本 | 作用 |
| ./install.sh | 构建 + 安装到 DSH（配置档 web；用 --profile NAME 更改） |
| ./install.sh --with-kanalyzer | 同时安装静态分析插件及其 LLVM 14 工具链（较慢，会用到 sudo） |
| ./build.sh | 只构建 —— 不改动你的 DSH 安装 |

使用

在目标仓库里打开一个会话，用大白话描述 bug —— pbfuzz 的技能会自动触发：

There's a bug in src/http/modules/ngx_http_rewrite_module.c:178 (nginx). Reproduce it as a
verified PoV.

智能体会探查仓库，提出一个测试活动方案（目标、构建命令、判定器），并给你一屏摘要，让你批准或修改。批准后它自行驱动 PLAN → IMPLEMENT → EXECUTE → REFLECT —— 写模糊测试计划、写生成器、运行它，并反思结果——直到它报告出触发问题的输入，或者放弃并解释原因。

会话内可用的命令：

| 命令 | 作用 |
| /pbfuzz [notes] | 启动新一轮 campaign，notes 作为 bug 报告 |
| /pbfuzz run <campaign.yaml> | 无头模式：加载手写、已确认的 campaign，直接启动 PIER，不弹任何提示 |
| /pbfuzz status | 打印当前 campaign 的阶段和指标 |
| /pbfuzz selfcheck | 立即运行环境自检（LLVM、tracer、Python） |

设置项（tracer、预算上限、oracle 默认值、开启哪些辅助分析）在 Web UI 的 Plugins → @pbfuzz/dsh-pbfuzz → Configure 下，或者在你配置档 cordis.patch.yml 里 pbfuzz 条目的 config: 下。三个预算——budget.maxPierRounds、budget.campaignWallTimeMin、budget.maxConsecutiveForcedContinues——是无人值守运行时唯一的刹车；触到任意一个，campaign 就真正停止（phase: STOPPED）。

C/C++、Python 和 Java 目标的完整示例在 examples/；Magma 基准 bug 的无头运行在 examples/magma/。

工作原理

- @pbfuzz/dsh-pbfuzz —— campaign 状态机（PLAN → IMPLEMENT → EXECUTE → REFLECT，即「PIER」），它的工具（pbfuzz_campaign、pbfuzz_plan、pbfuzz_fuzz、pbfuzz_reflect……），防止模型篡改引擎自有证据的状态守卫，以及设置/仪表盘 UI。它作为原生 Cordis 插件运行——没有 Claude-Code 风格的钩子，没有兼容层。
- @pbfuzz/dsh-kanalyzer （可选） —— 通用 LLVM 静态分析插件（可达性、调用图），开启静态分析时由 dsh-pbfuzz 调用。
- engine/ —— Python sidecar，真正运行目标：生成输入、执行输入、判定 oracle，并且是 metrics.json 的唯一写入者。它通过 stdio 讲 JSON-RPC，绝不在资源受限沙箱之外运行模型写的代码。

仓库结构

packages/dsh-pbfuzz/ the pbfuzz plugin: src/, skills/, canaries/, tests/
packages/dsh-kanalyzer/ the static-analysis plugin
engine/ the Python fuzzing sidecar (pbfuzz_engine/)
contracts/ JSON Schemas shared by both plugins and the engine (pnpm codegen)
examples/ worked targets: C/C++, Python (atheris), Java (Jazzer)
dsh-tests/ tests that boot the real DSH in-process (no mocks), always on npm's latest
docs/ DSH upgrade playbook, verification records

开发

pnpm -r typecheck
pnpm -r test # vitest, both packages
pnpm run test:engine # pytest, the Python engine
pnpm run test:dsh # the real DSH, newest from npm, booted in-process (needs the network; no API key)
pnpm run check:clients # settings-card ⇔ schema parity, client bundle self-checks
pnpm run codegen:check # contracts/ generated files are up to date
pnpm run codegen 会在 schema 变更后重新生成 contracts/ 下的 TypeScript/Python 类型；把生成的 diff 和 schema 一起提交。

DeepSeek Harness 兼容性

DSH 每个版本都会改插件 API，所以每次 push 和 PR 都会用 npm 上最新的 DSH 跑 dsh-tests/（启动真实的 DSH 进程内运行，没有任何 mock），另外还有一个每周工作流会再检查一遍 pbfuzz 的兼容性，一旦出问题就开 issue（如果设置了 ANTHROPIC_API_KEY，还会附上修复 PR）。
想手动复现或检查，用 scripts/compat-check.sh [version | --current]；0.2 改了什么、下次出问题怎么修，都在 docs/dsh-upgrade.md 里。

License

PolyForm Noncommercial License 1.0.0

Citation

@misc{zeng2025pbfuzzagenticdirectedfuzzing,
title={PBFuzz: Agentic Directed Fuzzing for PoV Generation},
author={Haochen Zeng and Andrew Bao and Jiajun Cheng and Chengyu Song},
year={2025},
eprint={2512.04611},
archivePrefix={arXiv},
primaryClass={cs.CR},
url={https://arxiv.org/abs/2512.04611},
}