Dan Guido
7ab5da641e
* feat: add minimal pre-commit infrastructure - Add pre-commit configuration with essential checks only - Check YAML, TOML, JSON syntax - Check for merge conflicts and large files - Enforce LF line endings (fix 2 test files with CRLF) - Add debug statement detection - Integrate ruff for Python formatting and linting - Add GitHub workflow for pre-commit CI - No unnecessary Python code changes * fix: add explicit permissions to pre-commit workflow - Set GITHUB_TOKEN permissions to read-only for contents - Follows principle of least privilege - Addresses CodeQL security recommendation - Pre-commit checks only need to read code, not write * fix: exclude test data from line ending modifications - Exclude .proto files and test/data directories from mixed-line-ending hook - Revert changes to test data files (traced_crash.proto, java_stacktrace.txt) - These files need to preserve their original format for test integrity - Binary proto files could be corrupted by line ending changes * docs: add pre-commit hooks documentation to CONTRIBUTING.md - Add pre-commit installation instructions to development setup - Document pre-commit hooks in Code Quality Standards section - Update submission workflow to include pre-commit checks - Provide manual pre-commit run commands for contributors * docs: streamline CONTRIBUTING.md for better readability - Reduce from 214 to 124 lines (42% reduction) while keeping all essential info - Consolidate setup instructions into concise Quick Start section - Convert component descriptions to scannable table format - Streamline testing strategy with clear requirements and timing - Add back critical testing prerequisites (codequery, ripgrep, cscope) - Create actionable Getting Help section with common troubleshooting - Remove redundant command listings and verbose explanations - Maintain all security requirements and essential workflows
Buttercup Cyber Reasoning System (CRS)
Buttercup is a Cyber Reasoning System (CRS) developed by Trail of Bits for the DARPA AIxCC (AI Cyber Challenge). Buttercup finds and patches software vulnerabilities in open-source code repositories like example-libpng. It starts by running an AI/ML-assisted fuzzing campaign (built on oss-fuzz) for the program. When vulnerabilities are found, Buttercup analyzes them and uses a multi-agent AI-driven patcher to repair the vulnerability. Buttercup system consists of several components:
- Orchestrator: Coordinates the overall task process and manages the workflow
- Seed Generator: Creates inputs for vulnerability discovery
- Fuzzer: Discovers vulnerabilities through intelligent fuzzing techniques
- Program Model: Analyzes code structure and semantics for better understanding
- Patcher: Generates and applies security patches to fix vulnerabilities
System Requirements
Minimum Requirements
- CPU: 8 cores
- Memory: 16 GB RAM
- Storage: 100 GB available disk space
- Network: Stable internet connection for downloading dependencies
Note: Buttercup uses third-party AI providers (LLMs from companies like OpenAI, Anthropic and Google), which cost money. Please ensure that you manage per-deployment costs by using the built-in LLM budget setting.
Note: Buttercup works best with access to models from OpenAI and Anthropic, but can be run with at least one API key from one third-party provider (support for Gemini coming soon).
Supported Systems
- Linux x86_64 (fully supported)
- ARM64 (partial support for upstream Google OSS-Fuzz projects)
Required System Packages
Before setup, ensure you have these packages installed:
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y make curl git
# RHEL/CentOS/Fedora
sudo yum install -y make curl git
# or
sudo dnf install -y make curl git
# MacOS
brew install make curl git
Supported Targets
Buttercup works with:
- C source code repositories that are OSS-Fuzz compatible
- Java source code repositories that are OSS-Fuzz compatible
- Projects that build successfully and have existing fuzzing harnesses
Quick Start
- Clone the repository with submodules:
git clone --recurse-submodules https://github.com/trailofbits/buttercup.git
cd buttercup
- Run automated setup (Recommended)
make setup-local
This script will install all dependencies, configure the environment, and guide you through the setup process.
Note: If you prefer manual setup, see the Manual Setup Guide.
- Start Buttercup locally
make deploy-local
- Verify local deployment:
make status
When a deployment is successful, you should see all pods in "Running" or "Completed" status.
- Send Buttercup a simple task
Note: When tasked, Buttercup will start consuming third-party AI resources.
This command will make Buttercup pull down an example repo example-libpng with a known vulnerability. Buttercup will start fuzzing it to find and patch vulnerabilities.
make send-libpng-task
- Access Buttercup's web-based GUI
Run:
make web-ui
Then navigate to http://localhost:31323 in your web browser.
In the GUI you can monitor active tasks and see when Buttercup finds bugs and generates patches for them.
- Stop Buttercup
Note: This is an important step to ensure Buttercup shuts down and stops consuming third-party AI resources.
make undeploy
Accessing Logs
Buttercup includes local SigNoz deployment by default for comprehensive system observability. You can access logs, traces, and metrics through the SigNoz UI:
make signoz-ui
Then navigate to http://localhost:33301 in your web browser to view:
- Distributed traces
- Application metrics
- Error monitoring
- Performance insights
If you configured LangFuse during setup, you can also monitor LLM usage and costs there.
For additional log access methods, see the Quick Reference Guide.
Additional Resources
- Quick Reference Guide - Common commands and troubleshooting
- Manual Setup Guide - Detailed manual installation steps
- AKS Deployment Guide - Production deployment on Azure
- Contributing Guidelines - Development workflow and standards
- Deployment Documentation - Advanced deployment configuration
- Writing Custom Challenges - Custom project configuration and setup