ffpuppet 0.7.2

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 after cloning the repository

pip install --user -e <ffpuppet_repository>

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

Installing minidump_stackwalk

minidump_stackwalk is used to extract a crash report when the browser crashes without a debugger (GDB/Valgrind) or instrumentation (ASan). If desired, minidump_stackwalk should be installed in the users path after obtaining it from tooltool. Choose the appropriate platform from tooltool-manifests in the mozilla-central tree, then open or download releng.manifest. Either use tooltool.py fetch -m releng.manifest or copy the digest from the file and download it from https://tooltool.mozilla-releng.net/sha512/<digest>. In either case, the file should be renamed to minidump_stackwalk and marked executable (or minidump_stackwalk.exe on Windows).

Browser Builds

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

Taskcluster

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. Or you can use fuzzfetch (recommended) which is very helpful in automation.

Build your own

If you would like to compile your own build instructions can be found here.

Usage

Once installed FFPuppet can be run using the following command:

python -m ffpuppet

usage: __main__.py [-h] [-d] [--log-level LOG_LEVEL] [-e EXTENSION] [-p PREFS]
                   [-P PROFILE] [-u URL] [--xvfb] [-a ABORT_TOKEN]
                   [--launch-timeout LAUNCH_TIMEOUT] [-l LOGS]
                   [--log-limit LOG_LIMIT] [-m MEMORY]
                   [--poll-interval POLL_INTERVAL] [--save-all] [--gdb] [--rr]
                   [--valgrind]
                   binary

FFPuppet - Firefox process launcher and log collector. Happy bug hunting!

positional arguments:
  binary                Firefox binary to launch

optional arguments:
  -h, --help            show this help message and exit
  -d, --display-logs    Display summary of browser logs on process exit.
  --log-level LOG_LEVEL
                        Configure console logging. Options: DEBUG, INFO, WARN,
                        ERROR (default: INFO)

Browser Configuration:
  -e EXTENSION, --extension EXTENSION
                        Install extensions. Specify the path to the xpi or the
                        directory containing the unpacked extension.
  -p PREFS, --prefs PREFS
                        Custom prefs.js file to use (default: profile default)
  -P PROFILE, --profile PROFILE
                        Profile to use. This is non-destructive. A copy of the
                        target profile will be used. (default: temporary
                        profile)
  -u URL, --url URL     Server URL or path to local file to load.
  --xvfb                Use Xvfb

Issue Detection & Reporting:
  -a ABORT_TOKEN, --abort-token ABORT_TOKEN
                        Scan the browser logs for the given value and close
                        browser if detected. For example '-a ###!!!
                        ASSERTION:' would be used to detect soft assertions.
  --launch-timeout LAUNCH_TIMEOUT
                        Number of seconds to wait for the browser to become
                        responsive after launching. (default: 300)
  -l LOGS, --logs LOGS  Location to save browser logs. A sub-directory
                        containing the browser logs will be created.
  --log-limit LOG_LIMIT
                        Browser log file size limit in MBs (default: 0, no
                        limit)
  -m MEMORY, --memory MEMORY
                        Browser memory limit in MBs (default: 0, no limit)
  --poll-interval POLL_INTERVAL
                        Delay between checks for results (default: 0.5)
  --save-all            Always save logs. By default logs are saved only when
                        an issue is detected.

Available Debuggers:
  --gdb                 Use GDB (Linux only)
  --rr                  Use rr (Linux only)
  --valgrind            Use Valgrind (Linux only)

Replaying a test case

python -m 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 and any log data (stderr, stdout, ASan logs... etc) will be dumped to the console when the browser process terminates.

Prefs.js files

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