# Buttercup CRS: AI-assisted vulnerability discovery and patching

> Buttercup is Trail of Bits' Cyber Reasoning System for fuzzing supported repositories and generating patches through an orchestrated multi-agent workflow. It is aimed at security researchers who can supply substantial infrastructure, compatible fuzzing harnesses, and paid third-party LLM access.

**trailofbits/buttercup** — Buttercup finds and patches software vulnerabilities

- Repository: https://github.com/trailofbits/buttercup
- Stars: 1,727 · Forks: 191
- Language: Python
- License: AGPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/trailofbits-buttercup

## Buttercup's scope for OSS-Fuzz-compatible targets

Buttercup addresses a specific vulnerability research workflow: discover defects in a supported open-source target, analyze the resulting failures, and attempt to produce a security patch. Trail of Bits developed it for the DARPA AI Cyber Challenge, and its example workflow uses `example-libpng`, a repository prepared with a known vulnerability. The intended users are security researchers, challenge teams, and engineers working on repositories that already participate in OSS-Fuzz.

The supported target boundary is important. The README identifies C and Java repositories that are OSS-Fuzz compatible, plus projects that build successfully and already contain fuzzing harnesses. It does not describe support for arbitrary applications written in other languages, repositories without harnesses, or closed binaries. Merely having source code is therefore insufficient for the documented workflow.

This is a Cyber Reasoning System rather than a conventional vulnerability scanner. Its documented starting point is an AI/ML-assisted fuzzing campaign built on oss-fuzz. That makes it most suitable when an organization already understands how its target is compiled and fuzzed and wants to extend the discovery and repair process with multiple AI-assisted components. Teams seeking a lightweight static analysis tool for a small code review will not find that simpler workflow here.

## The orchestrator-to-patcher workflow in Buttercup

Buttercup separates the task into five named components. The Orchestrator coordinates the overall process and manages the workflow. The Seed Generator creates inputs for vulnerability discovery. The Fuzzer uses those inputs to search for failures. The Program Model analyzes code structure and semantics, while the Patcher generates and applies fixes for discovered vulnerabilities.

This division gives each stage a distinct responsibility. Seed generation precedes fuzzing, code analysis supplements discovery, and patching happens after defects are found. The README does not publish the internal message format, agent handoff schema, patch-validation policy, or exact mechanism used to decide that a generated fix is acceptable. It also does not promise that every discovered vulnerability will receive a working patch. The defensible description is that Buttercup attempts an AI-driven repair after analysis, not that it guarantees one.

Deployment also introduces supporting infrastructure. The repository layout includes directories for the orchestrator, seed generator, fuzzer, program model, patcher, Redis, tasks storage, and deployment assets. The local setup includes SigNoz for distributed traces, application metrics, error monitoring, and performance data. If LangFuse is configured during setup, the README also says LLM usage and costs can be monitored there. These observability facilities are relevant to an expensive, long-running workflow because operators need visibility into both pipeline failures and model consumption.

## Installing Buttercup and launching the libpng task

The README's local tutorial begins with system packages. These commands differ by host package manager and install `make`, `curl`, and `git`.

```bash
sudo apt-get update
sudo apt-get install -y make curl git
```

The minimum documented environment is 8 CPU cores, 16 GB RAM, and 100 GB of available storage, with a stable internet connection for dependencies. Linux x86_64 is fully supported. macOS is supported for local development through Docker Desktop or Colima. ARM64 has partial support for upstream Google OSS-Fuzz projects.

Clone the repository with its submodules, enter the directory, and run the automated setup target. The README describes this as installing dependencies, configuring the environment, and guiding the user through setup.

```bash
git clone --recurse-submodules https://github.com/trailofbits/buttercup.git
cd buttercup
make setup-local
```

Before deployment, Docker must be running. The following Colima command is one documented way to start it on macOS or Linux, with the resource values shown by the project.

```bash
colima start --cpu 6 --memory 10 --disk 80
```

Deploy the system and inspect its status. The README says a successful local deployment shows all pods in `Running` or `Completed` state.

```bash
make deploy
make status
```

For the first real exercise, send the libpng task. According to the README, this pulls `example-libpng` and begins fuzzing it to find and patch vulnerabilities. Starting a task causes Buttercup to consume paid third-party AI resources.

```bash
make send-libpng-task
```

Open the web interface through the documented target, then browse to `http://localhost:31323` to monitor tasks, discovered bugs, and generated patches.

```bash
make web-ui
```

Shut the deployment down when the task is complete so that it stops consuming third-party AI resources.

```bash
make undeploy
```

## LLM budgets, operating resources, and observability

Buttercup's operating cost is not limited to infrastructure. It calls third-party models from providers such as OpenAI, Anthropic, and Google, and the README says these services cost money. It recommends managing per-deployment cost through the built-in LLM budget setting. The documentation states that Buttercup works best with access to both OpenAI and Anthropic models, although it can run with at least one API key from one third-party provider.

That requirement creates an operational dependency. API keys and budget policy are part of a valid deployment, not optional finishing touches. An unavailable provider can affect execution, and an unconstrained run can continue consuming paid resources. The README does not define token ceilings, patch-attempt limits, default budget values, or a complete accounting formula, so those details require checking in the setup and deployment documentation before assigning a fixed budget.

Local observability is bundled through SigNoz. Open its interface with the documented Make target.

```bash
make signoz-ui
```

The UI is then available at `http://localhost:33301`. The README associates it with distributed traces, application metrics, error monitoring, and performance insights. LangFuse can cover LLM usage and cost monitoring when configured. This instrumentation helps distinguish failures in the fuzzer or deployment from model-related activity, although it does not itself establish patch correctness.

The last repository push was on 2026-09-28, and the repository is not archived. Its sole listed release is `v1.0`, dated 2025-08-14 and described as the initial standalone release. The repository is therefore not a static archive, but the documented release history does not establish a schedule of frequent upgrades. Operators should expect deployment and dependency changes to require attention rather than treating the release count as a compatibility guarantee.

## Why Buttercup differs from conventional fuzzers and patch review

A conventional fuzzer executes a target with generated inputs and reports crashes or sanitizer failures. Buttercup includes that discovery phase but extends the documented system with a Program Model, a Patcher, an Orchestrator, and a Seed Generator. Its distinguishing approach is the combination of fuzzing, code analysis, and multi-agent patch generation within one managed task.

That makes Buttercup closer to an experimental end-to-end vulnerability repair pipeline than to a standalone fuzz target. The difference is also a source of risk in evaluation. A patch should still be assessed for correctness, scope, compatibility with the target's tests, and unintended behavior. The README says the Patcher applies patches, but it does not document a guarantee of human review, formal verification, or universal build and test validation after patching.

A manual security team using OSS-Fuzz plus separate analysis and patch-review workflows has more control over each gate. Buttercup reduces the need to assemble those stages into one orchestrated system, but it also adds model providers, containers, substantial hardware requirements, and paid inference. It is the wrong tool for an unsupported repository, a target without a working build and fuzzing harness, or a short patch task where the setup cost cannot be justified.

The repository is licensed under `AGPL-3.0`. That identifier imposes source-availability and license obligations when the licensed software is distributed or networked in circumstances covered by the license, but the repository excerpt does not provide legal analysis. Operators modifying or offering the system should review the actual `LICENSE` file and applicable obligations with qualified counsel rather than infer that the license removes deployment or attribution duties.

## Scoping a first Buttercup evaluation

A defensible first evaluation starts with a target that already satisfies the project's documented prerequisites. Use a C or Java OSS-Fuzz-compatible repository with an existing harness, a reliable build, and a failure mode suitable for investigation. Do not begin with an unfamiliar binary or assume that source availability alone makes a project eligible.

The project's `make validate` target is documented in the Makefile as validation of the current setup and configuration. It is distinct from deployment status because it checks configuration before operating the system.

```bash
make validate
```

Set an LLM budget before sending a task, and retain the documented shutdown path. `make undeploy` removes the deployment and cleans up resources. This matters both for cost control and for preventing a forgotten local deployment from remaining active.

For developers, the Makefile also exposes targeted Python linting with a component selector. The value must name a project component, and the help text gives `orchestrator` as the example.

```bash
make lint-component COMPONENT=orchestrator
```

The README does not document rollback for a generated patch or a command for restoring a target repository after a failed run. It also does not provide success thresholds for judging generated patches. Those omissions matter when defining an evaluation. The first assessment should therefore center on harness compatibility, observed task completion, patch review against the target's tests, and the behavior of the configured LLM budget rather than assuming that discovery implies a correct repair.

## Conclusion

Buttercup is appropriate for security researchers evaluating AI-assisted patching against OSS-Fuzz-compatible repositories with usable build and fuzzing harnesses. It is not a general patch assistant for arbitrary source trees. Before adoption, verify target compatibility, the required 8-core, 16 GB RAM, and 100 GB resource baseline, API expenditure controls, and whether shutdown through `make undeploy` fits the intended workflow.

## FAQ

### What kinds of repositories can Buttercup analyze?

The README identifies C and Java repositories that are compatible with OSS-Fuzz. It also requires the project to build successfully and to have an existing fuzzing harness.

### How do I install and start Buttercup locally?

Clone the repository with submodules, run `make setup-local`, ensure Docker is running, and use `make deploy`. The README points to `guides/MANUAL_SETUP.md` for manual installation.

### Does Buttercup use paid external services, and what resources does it require?

Buttercup uses paid LLMs from providers such as OpenAI, Anthropic, and Google, so operators must control per-deployment spending. The README states a minimum of 8 CPU cores, 16 GB RAM, and 100 GB of available storage.

## Sources

- [Issues](https://github.com/trailofbits/buttercup/issues)
- [License: AGPL-3.0](https://github.com/trailofbits/buttercup/blob/main/LICENSE)
- [README](https://github.com/trailofbits/buttercup/blob/main/README.md)
- [Releases](https://github.com/trailofbits/buttercup/releases)
- [trailofbits/buttercup on GitHub](https://github.com/trailofbits/buttercup)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/trailofbits-buttercup