# BigEye
BigEye 并不是一个全新的 fuzzing 引擎。它为需要让有价值的 fuzzing 在生成第一个 harness 后仍能持续运行的维护者、安全研究人员、产品安全工程师和应用安全团队管理 AFL++ 和 libFuzzer。
传统的 fuzzing 自动化通常在生成可编译的 harness 后就停止了。一场真正的活动仍然需要有人去解读微弱的覆盖率、在运行时反馈后修复目标、改进语料库、在进展停滞时更改配置、调查不可达的代码、消除冗余工作，并区分产品缺陷与 harness 错误。Fuzzer 进程可以无人值守运行；但测试策略通常不行。
BigEye 自动化了这种持续运行的策略。给它一个 HTTP(S) Git 仓库以及确切的分支、标签或版本号。它只会对该 commit 解析一次，准备可复用的 `linux/amd64` 构建层，创建有证据支持的活动，并随着已验证的覆盖率和崩溃证据的出现，不断对其进行调整。
BigEye 是一个在 macOS 或 Linux 上本地运行的单用户应用程序。FastAPI 后端和 React 界面运行在主机上。Docker 仅用于 PostgreSQL 以及隔离的构建、fuzzing、重放和覆盖率任务。
## 目录
- [组件与全系统活动](#component-and-whole-system-campaigns)
- [演示](#demo)
- [快速入门](#getting-started)
- [BigEye 的功能](#what-bigeye-does)
- [BigEye 如何管理活动](#how-bigeye-manages-a-campaign)
- [GPT-5.6 和 Codex 的使用方式](#how-gpt-56-and-codex-were-used)
- [平台对比](#platform-comparison)
- [支持的平台与前置条件](#supported-platforms-and-prerequisites)
- [许可证](#licence)
## 组件与全系统活动
BigEye 使用两种互补的活动类型：
- **组件级 fuzzing** 使用 libFuzzer 在进程内对库、解析器或独立组件进行测试。这对于完整应用程序无法有效触及的代码非常有用。
- **全系统 fuzzing** 使用 AFL++ 针对真实的可执行文件运行。它保留了依赖于命令行配置、协议状态、文件格式、多个交互组件或可选功能的行为。当一个可执行文件通过标志或构建选项展现出截然不同的行为时，BigEye 可以并行运行不同的配置。
执行引擎的重要性次于活动目标。BigEye 会决定哪些有证据支持的工作是有用的，以增量方式准备并修复它，并根据干净的源码构建来衡量这两种活动类型。
## 演示
## 快速入门
要求：Python 3.14，Node.js `^20.19.0 || >=22.12.0`，Git，Docker 和 Docker Compose v2。
```
git clone https://github.com/marcellomaugeri/BigEye.git
cd BigEye
cp .env_example .env
```
在 `.env` 中设置 `OPENAI_API_KEY`，然后运行：
```
scripts/setup.sh
scripts/start.sh
```
BigEye 将在 [http://127.0.0.1:8000/](http://127.0.0.1:8000/) 打开。在没有桌面会话的 Linux 主机上，请使用 `scripts/start.sh --no-browser`。
### 开始一项活动
选择 **+ New project** 并提供一个公开的 HTTP(S) Git 仓库、确切的分支、标签或 commit，以及并发编译或 fuzzing 任务的最大数量。对于私有仓库，可以提供一个特定于项目的只读 token。
#### 推荐的演示项目
为了进行简短的演示，请使用以下内容创建一个项目：
- **Repository:** `https://github.com/libexpat/libexpat`
- **Revision:** `R_2_7_1`
- **Concurrent jobs:** `4`
Expat 是一个紧凑的 C 语言 XML 解析器，具有现有的组件级 fuzzing 入口点和 `xmlwf` 命令行可执行文件。其专注的代码库和构建配置使其成为演示 BigEye 的一个易于访问的第三方项目。大约一小时的运行可以展示仓库准备、目标选择、确定性构建和探针验证、干净的覆盖率编译以及实时的活动过程。具体的覆盖率和发现取决于可用的计算资源以及在该运行过程中发现的证据。
提交后，BigEye 会自动启动。首次活动可能需要一些时间：BigEye 必须了解仓库，准备缓存的项目层，编译 fuzzing 和 clean-coverage 变体，并在允许其持续运行之前对每个目标进行探测。
## BigEye 的功能
- 解析不可变的仓库版本，并在整个活动过程中保持该 commit 不变。
- 选择有证据支持的入口路径，而不是将每个函数都视为同等有用的目标。
- 运行全系统 AFL++ 活动和组件级 libFuzzer 活动。
- 生成并增量修复 harness、构建配置、补丁和初始语料库，且不修改源码检出。
- 从兼容的 ASan 和 UBSan 插桩开始，并使用确定性探针验证每个目标。
- 监控覆盖率、语料库机会、活动健康度和平台期，仅在需要做出决策时唤醒管理器。
- 衡量干净构建的行、函数和分支覆盖率，保留首次命中的测试用例，并将累积的容器 CPU 暴露归因于已达源码。
- 最小化语料库，检测重叠策略并避免冗余工作，同时保留发现的复现能力。
- 在对发现进行分类和确定优先级之前，重放、最小化、指纹识别并分组崩溃。
- 通过一个本地界面展示项目活动、模型和工具轨迹、构建与 fuzzer 日志、活动逻辑、覆盖率证据和发现结果。
## BigEye 如何管理活动
```
flowchart LR
R["Repository and fixed revision"] --> B["Reusable project layers"]
B --> T["Target preparation"]
T --> P["Deterministic build and probe"]
P --> F["Continuous fuzzing"]
F --> E["Clean coverage, corpus and crash evidence"]
E --> D["Repair, adapt, prioritise or wait"]
D --> F
```
1. **固定源码身份。** BigEye 将请求的版本解析为一个 commit，并保持检出不可变。
2. **准备可复用层。** 维护的工具链、仓库和项目依赖被独立缓存，因此微小的目标更改不需要重新构建所有内容。
3. **选择有界限的工作。** 管理器分配独立的任务，例如准备入口路径、修复构建失败或调查微弱的可达性。
4. **在推广前进行验证。** 确定性服务会编译每个提案并运行有界限的探针。模型的声明永远不能证明目标可以正常工作。
5. **持续运行。** 经过验证的全系统和组件活动作为普通的 fuzzer 进程运行，而不是作为 agent 运行。
6. **衡量干净证据。** 语料库输入将针对单独的干净构建进行重放，以收集行、函数和分支覆盖率，而不会因仅用于 fuzzing 的插桩或补丁导致结果失真。
7. **仅在有用时进行调整。** 新的可达性、平台期、失败的目标、有用的语料库证据、持续的重叠、重放的崩溃或管理器选择的截止时间都可能触发另一次审查。健康的 fuzzer 将继续运行，无需模型轮询。
8. **展示发现，而非原始崩溃。** BigEye 在对不确定性进行分类、分配优先级并保留可复现的输入之前，会对崩溃进行重放、最小化、指纹识别和分组。
### 可复用构建层
1. 维护的基础镜像包含 LLVM 18、Clang、libFuzzer、AFL++ 4.40c 和覆盖率工具。
2. 仓库层包含确切解析出的 commit。
3. 依赖项和项目构建层在其输入保持不变的情况下会被复用。
4. 目标层包含生成的 harness、补丁、配置和种子。
5. 单独的 clean-coverage 层用于衡量未修改的源码路径。
每次镜像构建和活动容器都明确请求 `linux/amd64` 架构。BigEye 不使用 OSS-Fuzz 或 OSS-Fuzz-Gen 的镜像或源代码。
### 可检查的证据
- **Overview** 展示当前重点、活动策略、重放的发现结果以及衡量的源码可达性。
- **Fuzzing** 显示每个目标和配置、当前活动、近期的覆盖率变动、总可达性和 CPU 暴露。
- **Coverage** 将覆盖的代码行与达成覆盖的策略以及每个目标保留的首个测试用例联系起来。
- **Findings** 展示分组的重放证据、优先级、不确定性、最小输入和包含的复现输出。
- **Activity** 记录决策、动机、工具调用、模型使用情况和经过脱敏处理的运行时日志。
Overview 将干净的全项目覆盖率与仅限活动的可达性区分开来，并绘制出随时间变化的绝对行覆盖率。
Coverage 视图高亮显示已覆盖和未覆盖的源码行，同时保留检查可复现性所需的 CPU 暴露和首个测试用例。
CPU 暴露是归因于活动的 clean-coverage 重放所达到代码行的累积容器 CPU 时间。它不是墙上时间（wall-clock time），也不意味着穿过某一行的每条路径都经过了测试。
## GPT-5.6 和 Codex 的使用方式
### 用于开发
该项目始于一个单独的头脑风暴聊天。我在一份文档中提供了最初的意图，并要求 Codex 通过多达 200 个明确的澄清问题对其进行挑战，涵盖范围、用户旅程、agent、fuzzing 基础设施、技术和文件组织。第一轮实现随后在 GPT-5.6 Sol 的 Extra High 推理努力下连续运行了 18 个小时。
开发使用了 Jesse Vincent 的 [Superpowers](https://github.com/obra/superpowers) 插件：
- [Writing Plans](https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md) 在实现之前将批准的决策转化为明确的、针对特定文件的任务。
- [Test-Driven Development](https://github.com/obra/superpowers/blob/main/skills/test-driven-development/SKILL.md) 要求行为更改必须从展示缺失行为的测试开始，然后进行最小的实现并运行确认测试。
- [Subagent-Driven Development](https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md) 将专注的实现和审查工作分配给独立的 agent，以便独立模块能够并行推进。
Codex 提供了开发环境和多 agent 工具；GPT-5.6 负责推理并执行实现和审查工作。这些开发工作流程与 BigEye 的运行时 agent 是分开的。
### 在项目中
- **GPT-5.6 Terra** 管理一个项目的长期运行活动，并决定接下来哪些有界限的工作是有用的。
- **GPT-5.6 Luna** 执行首次有界限的工作尝试；真正困难的工作可以升级给 Terra。
- **OpenAI Agents SDK** 提供类型化的 agent、结构化输出、追踪以及作为委派边界的 `Agent.as_tool()`。
- 独立的目标或调查任务可以并行运行，而对同一生成资产的编辑则保持串行且增量进行。
- Agent 负责源码解读和技术判断。仓库克隆、构建、探针、fuzzing、覆盖率分析、语料库处理、重放、分组、调度和唤醒截止时间仍然是确定性的应用程序服务。
- Fuzzer 进程不是 agent，在运行期间不消耗模型 token。
## 平台对比
| 平台 | Harness 生成 | 运行时反馈后的 Harness 修复 | 全系统 fuzzing | 解释为何特定代码未被触及 | 在进展停滞时停止或更改工作 | 真实 Bug 与 Harness 错误对比 | 发现优先级划分 | 开源 |
|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| [OSS-Fuzz-Gen](https://github.com/google/oss-fuzz-gen) | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ |
| [PromeFuzz](https://github.com/TCA-ISCAS/PromeFuzz-ccs-2025) | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ |
| [FuzzAgent](https://arxiv.org/abs/2605.14431) | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
| [CI Fuzz](https://www.code-intelligence.com/product-ci-fuzz/ci-fuzz-vs-libfuzzer-afl-hongfuzz) | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ |
| **BigEye** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
该表比较的是 fuzzing 平台和活动管理系统，而不是执行引擎。叉号（❌）并不意味着该平台在技术上无法支持该行为。BigEye 的独特之处在于，它将组件执行与全系统执行、运行时驱动的修复、对未达代码的调查、活动适应、对 harness 引起故障的分类以及发现优先级划分整合到了一个可检查的仓库级活动中。开源可用性增强了该工作流程的普及度；但这并不是主要的技术差异。
## 支持的平台与前置条件
BigEye 支持配备 Docker Desktop 的 macOS，以及配备 Docker Engine 和 Docker Compose v2 的 Linux。不支持 Windows。
所需的主机工具：
- 可通过 `python3.14` 使用的 Python 3.14；
- Node.js `^20.19.0 || >=22.12.0` 及 npm；
- Git；
- 带有 Compose v2 的 Docker，以及支持 `linux/amd64` 的构建器。
基于 LLVM 的流水线是为兼容 LLVM 的目标设计的，目前已通过受控的 C/C++ 固定装置进行了验证。BigEye 仍然是一个本地、单用户版本，而不是托管的多租户服务。有关确切的观察证据以及待定的外部项目和 Linux 主机边界，请参阅[发布验证](
)。
## 许可证
BigEye 基于 [Apache License 2.0](LICENSE) 提供授权。
## 个人备注
BigEye 最初是我在一段时间前设计的一个项目，但一直没找到合适的时机去实现它。我想感谢一位非常亲密的朋友，是他给了我一个借口，让我终于能够着手开发它。