Local instance of ClusterFuzz

You can run a local instance of ClusterFuzz to test core functionality. Note that some features (e.g. crash and fuzzer statistics) are disabled to due to lack of Google Cloud emulators.

• Local instance of ClusterFuzz
  • Running a local server
  • Running a local bot instance
    • Viewing logs
  • Local Google Cloud Storage

Running a local server

# If you run the server for the first time or want to reset all data.
python butler.py run_server --bootstrap

# In all the other cases, do not use "--bootstrap" flag.
python butler.py run_server

This may take a few seconds to start. Once you see an output line like INFO <timestamp> admin_server.py:<num>] Starting admin server, you should be able to navigate to http://localhost:9000 to view the web interface. Note: the local instance may use ports other than 9000, such as 9008, for things like uploading files. Therefore, using the local instance may break if the needed ports are unavailable or if you can only access some of the needed ports from your browser (for example: because of port forwarding or firewall rules when accessing from another host).

Running a local bot instance

python butler.py run_bot --name my-bot /path/to/my-bot  # rename my-bot to anything

This creates a copy of ClusterFuzz source under /path/to/my-bot/clusterfuzz and runs the bot using it. Most of the bot artifacts like logs, fuzzers, corpora, etc are created inside the bot subdirectory.

If you plan to fuzz native GUI applications, it is advisable to run this command in a virtual framebuffer (e.g. Xvfb). Otherwise, you will see GUI dialogs while fuzzing and will be unable to use the machine with ease.

Viewing logs

cd /path/to/my-bot/clusterfuzz/bot/logs
tail -f bot.log

Until you set up the fuzzing jobs, you will see a harmless error in the logs - Failed to get any fuzzing tasks.

Local Google Cloud Storage

We simulate Google Cloud Storage using your local filesystem. By default, this is stored at local/storage/local_gcs in your ClusterFuzz checkout. You can override it using --storage-path when running run_server command and then specifying the same path using --server-storage-path when running run_bot command.

Under this location, objects are stored in <bucket>/objects/<object path> and metadata is stored in <bucket>/metadata/<object path>.