Install the Fuzzbuzz CLI
Find your first C/C++ bug
Find your first Python bug
Find your first Go bug
Find your first Rust bug
Seeding your fuzzer
Integrating with libFuzzer
Heartbleed in 5 Minutes
Protocol Generator Reference
Fuzzbuzz can be self-hosted on user-owned, fully on-premises, airgapped machines. This can be useful in situations where your software is too sensitive to be tested outside of your own network, or when the hosted Fuzzbuzz platform doesn't meet your requirements. We always recommend considering the hosted platform before deciding on hosting your own installation of Fuzzbuzz.
On-Premises Installation Overview
The Fuzzbuzz Platform consists of Platform Machines, a single Database, and Worker Machines.
A Platform Machine contains the frontend and backend services necessary to run the platform. It must conform to the Fuzzbuzz system requirements. It is the machine you will run the Fuzzbuzz Installer on, and is the machine that a user (or API client) will access when interacting with the platform. A deployment may consist of a single Platform Machine, or multiple load-balanced Platform Machines. For example, if you have installed Fuzzbuzz on a Platform Machine with the IP address
100.200.300.400, a developer would login to the platform by accessing
http(s)://100.200.300.400/login on your web browser.
All Platform Machines must connect to a single PostgreSQL database. In an ideal installation this database resides on one of the Platform Machines (the Primary Platform Machine), and is managed by the Fuzzbuzz tooling.
A Worker Machine is a machine that executes Fuzz Jobs and other fuzzing-related workloads. Worker machines are only needed for In-Process Fuzzing. Setup of worker machines can be skipped for Protocol Fuzzing.
Operating system requirements
Fuzzbuzz can be provided in the form of a fully set-up Virtual Machine Image (such as a VMDK, QCOW2, etc), or in the form of an installer that must be run on an existing operating system. In the event that you wish to provide a base operating system for Platform and Worker machines rather than using a Virtual Machine Image, the OS must satisfy the following system requirements:
- Operating System: Debian Testing (https://wiki.debian.org/DebianTesting). You can find relevant images at the following link: http://cdimage.debian.org/cdimage/weekly-builds/
We suggest that you refrain from making significant modifications to the operating system or kernel. Modified versions of this operating system are not officially supported, and we will not be able to assist with problems that arise from custom changes or patches made to this operating system.
In addition to requiring a recent Debian/Testing OS, we recommend the following CPU and RAM configurations for a base installation:
Platform Machine: 4 CPUs, 16GB RAM
Worker Machine: 8 CPUs, 16GB RAM
These numbers are recommended minimum requirements, but you can use lower or higher specifications if you'd like. You may find more powerful configurations useful if you have unusually high usage, or a large number of concurrent users. It is especially difficult to estimate the system requirements of worker machines, since required capacity depends on your specific needs. If you have questions, we recommend reaching out to us directly.
In most situations, your Primary Platform Machine will also host your database. It's important that you provide all of your Platform Machines with sufficient hard drive space for database backups and replicas. Specific numbers depend on usage, but we recommend 100GB as a starting point. Worker machines should have enough storage space to accommodate the size of the docker containers you intend to use.
Setting up the first Platform Machine
The Fuzzbuzz Installer will be provided in the form of a signed Debian package, with a filename that looks like
Your Fuzzbuzz contact will provide the installer to you directly. If you are interested in using Fuzzbuzz on-premises, get in touch at email@example.com
Install Fuzzbuzz by copying this tarball to the first Platform Machine you wish to set up, and unpack it by running
sudo dpkg -i <the installer's filename>.
Configure this machine by opening
/opt/fuzzbuzz/var/installer/resources/configuration.yaml, and filling in the
internal_hostname variables. The
dns_zone should be the public name you expect to access the Fuzzbuzz platform with. If you are using multiple backends, this should be the address of your load balancer. If using a single machine, it could be the machine's DNS name. The
internal_hostname should be the hostname or IP address unique to this specific backend. All additional workers and backends will use this address to pull configuration and communicate back to the platform.
To begin the installation process, run
install-fuzzbuzz MACHINE_NAME, where
MACHINE_NAME is a unique name for the Platform Machine (we'd recommend using the node's hostname for this value if it's unique). In general, the following command is sufficient:
The installer will run, and potentially ask for information it needs to complete the install process. If you aren't sure what to provide, quit the installer by pressing
CTRL-c, and ask either your System Administrator, or someone on the Fuzzbuzz team for help. The installer will allow you to pick up from where you left off.
Once the installer has finished running, run the
new-user command to create your first user, specifying the organization and team you wish to place them under:
new-user <organization-name> <team-name> <user-email>
We recommend creating all subsequent users via the UI.
You should now be able to log into the Fuzzbuzz platform by heading to the IP address or Hostname of the machine you just ran the installer on in a web browser. Type in the email address and password you set up in the install process, and you should be able to login to your organization.
Setting up additional Platform Machines
It's possible to setup additional Platform Machines to pair with your first Platform Machine.
First, copy and unpack the same installer tarball on the new Platform Machine.
Then run the
new-backend script on the first Platform Machine (can be found in the resources directory of the tarball), providing an internal hostname and unique machine name for the new backend (we'd recommend using the node's hostname for the machine name if it's unique). The internal hostname should be a unique DNS name that is accessible by the other Fuzzbuzz machines. An example command will look like:
new-backend NEW_INTERNAL_HOSTNAME NEW_MACHINE_NAME
new-backend script will output an
install-fuzzbuzz command. Copy this command and run it on the new Platform Machine to install Fuzzbuzz. An example command will look like:
install-fuzzbuzz -n NEW_INTERNAL_HOSTNAME -b PAIRING_TOKEN NEW_MACHINE_NAME
Updating SSL Certificates on Platform Machines
If you are using the Fuzzbuzz platform with
https enabled, you will need to update the SSL certificates on each of the Platform Machines with a certificate that user machines will recognize.
Copy the SSL certificate and key onto the Platform Machine, then run the
update-public-ssl-certs script (can be found in the resources directory of the tarball) with the certificate and key paths to update the platform SSL information. An example command would look like:
/opt/fuzzbuzz/var/installer/resources/update-public-ssl-certs NEW_SSL_CERT NEW_SSL_KEY
Setting up Worker Machines
It's also possible to setup Worker Machines to run jobs from the Fuzzbuzz platform.
First, copy and unpack the original installer tarball on the new Worker Machine.
Then run the
new-worker script on the first Platform Machine (can be found in the resources directory of the tarball), providing an internal hostname and unique machine name for the new worker (we'd recommend using the node's hostname for the machine name if it's unique). The internal hostname should be a unique DNS name that is accessible by the other Fuzzbuzz machines. An example command will look like:
new-worker NEW_INTERNAL_HOSTNAME NEW_MACHINE_NAME
new-worker script will output an
install-fuzzbuzz command. Copy this command and run it on the new Worker Machine to install Fuzzbuzz. An example command will look like:
install-fuzzbuzz -w -n NEW_INTERNAL_HOSTNAME -b PAIRING_TOKEN NEW_MACHINE_NAME
Updates will be provided by Fuzzbuzz. When provided, they should be unpacked and installed on each Platform Machine and Worker Machine in a similar manner as the installation script.
Updating the first Platform Machine
Run the same
install-fuzzbuzz command as you did initially, that is
The script will automatically detect the existing Fuzzbuzz installation, and only ask for configuration if any new information is needed.
Updating additional Platform Machines
install-fuzzbuzz -u -n INTERNAL_HOSTNAME MACHINE_NAME, providing the original
MACHINE_NAME you used to install the machine.
Updating Worker Machines
install-fuzzbuzz -w -u -n INTERNAL_HOSTNAME MACHINE_NAME, providing the original
MACHINE_NAME you used to install the machine.
Ideal Fuzzbuzz Installation
The Ideal Fuzzbuzz Installation consists of at least a single Platform Machine, which hosts both the frontend and backend software, as well as the database. To set up this machine, follow the Setting up the first Platform Machine instructions above, accepting all configuration defaults (except those that pertain to your specific setup, such as network options or setting up your machine's network name).
Accepting all of the defaults in the installer will result in an optimal installation that Fuzzbuzz can manage with minimal intervention from you and your team.
Depending on the number of people accessing the platform, you may wish to have additional Platform Machines to balance the connection load. For guidance, see the Setting up the first Platform Machine instructions above, as well as the Load Balancing section below.
If you are only using Protocol Fuzzing, there is no need to setup any Worker Machines. However, if you would like to use In-Process Fuzzing, you will need to setup Worker Machines by following the Setting up the first Platform Machine instructions above. The ideal number of Worker Machines is heavily context dependent, feel free to reach out to us directly for a recommendation.
Below you will find playbooks for specific situations, such as how to run backups and set up load balancing. If you have a specific situation that is not covered by this documentation, please reach out to us for specific help.
If you have more than one Platform Machine and you wish to load-balance between all of these machines so that a user can access them all via a single URL, follow the steps below:
We recommend DNS load balancing, specifically A-record load balancing. To achieve this, you should set your DNS server up so that the domain name you wish to access has multiple A records, one for each IP address that points to a Platform Machine.
If you are using a Fuzzbuzz-hosted Database (the default option), Fuzzbuzz will create periodic backups and place them in the
/opt/fuzzbuzz/backup/db directory on the Platform Machine. If you wish to back these up on external storage, you may set up periodic copies of this data to your own storage media.
If you wish to backup the Platform Machines that Fuzzbuzz is running on, you may do so by creating full Virtual Machine Snapshots of the VMs that Fuzzbuzz is running on. In the event of a machine failure, you could restore these snapshots to bring Fuzzbuzz back online without needing to reinstall the platform on fresh machines. Note that in this situation, you may need to reconfigure these machines after restoring if their IP addreesses or DNS names have changed.