ffpuppet 1.0.0

A Python module that aids in the automation of Firefox at the process level

FFPuppet

FFPuppet is a Python module that automates browser process related tasks to aid in fuzzing. Happy bug hunting!

Are you fuzzing the browser? Grizzly can help.

Installation

To install the latest version from PyPI

pip install ffpuppet

Xvfb on Linux

On Linux xvfb can be used in order to run headless (this is not the same as Firefox's -headless mode).

To install xvfb on Ubuntu run:

apt-get install xvfb

Install minidump-stackwalk

minidump-stackwalk is used to collect crash reports from minidump files. More information can be found here.

Browser Builds

If you are looking for builds to use with FFPuppet there are a few options.

Download a build

fuzzfetch is the recommended method for obtaining builds and is also very helpful in automation.

Taskcluster has a collection of many different build types for multiple platforms and branches. An index of the latest mozilla-central builds can be found here.

Create your own build

If you would like to compile your own, build instructions can be found here. When using minidump-stackwalk breakpad symbols are required for symbolized stacks.

Usage

Once installed FFPuppet can be run using the following command:

ffpuppet <firefox_binary>

Replaying a test case

ffpuppet <firefox_binary> -p <custom_prefs.js> -d -u <testcase>

This will open the provided test case file in Firefox using the provided prefs.js file. Any log data (stderr, stdout, ASan logs... etc) will be dumped to the console if a failure is detected. Grizzly Replay is recommended for replaying test cases.

Prefs.js files

prefs.js files that can be used for fuzzing or other automated testing can be generated with PrefPicker.