Self-Hosted Fuzzbuzz

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

System Architecture

The Fuzzbuzz Platform consists of Platform Machines, a single Database, and Worker Machines.

Platform 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.

Database

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.

Worker Machines

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.

System Requirements

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:

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.

Hardware requirements

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.

Storage requirements

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.

Installing Fuzzbuzz

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 fuzzbuzz-installer-<version>-<yourname>.deb.

Your Fuzzbuzz contact will provide the installer to you directly. If you are interested in using Fuzzbuzz on-premises, get in touch at [email protected]

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 dns_zone and 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:

install-fuzzbuzz $(hostname)

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

The 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

The 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

Installing Updates

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 install-fuzzbuzz MACHINE_NAME

The script will automatically detect the existing Fuzzbuzz installation, and only ask for configuration if any new information is needed.

Updating additional Platform Machines

Run install-fuzzbuzz -u -n INTERNAL_HOSTNAME MACHINE_NAME, providing the original INTERNAL_HOSTNAME and MACHINE_NAME you used to install the machine.

Updating Worker Machines

Run install-fuzzbuzz -w -u -n INTERNAL_HOSTNAME MACHINE_NAME, providing the original INTERNAL_HOSTNAME and MACHINE_NAME you used to install the machine.

Examples

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.

Playbooks

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.

Load Balancing

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.

Database Backups

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.

Machine Backups

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.

ON THIS PAGE