FFPuppet
========
[](https://github.com/MozillaSecurity/ffpuppet/actions/workflows/ci.yml)
[](https://codecov.io/gh/MozillaSecurity/ffpuppet)
[](https://matrix.to/#/#fuzzing:mozilla.org)
[](https://pypi.org/project/ffpuppet)
FFPuppet is a Python module that automates browser process related tasks to aid in fuzzing. Happy bug hunting!
Are you [fuzzing](https://firefox-source-docs.mozilla.org/tools/fuzzing/index.html) the browser? [Grizzly](https://github.com/MozillaSecurity/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](https://lib.rs/crates/minidump-stackwalk).
Browser Builds
--------------
If you are looking for builds to use with FFPuppet there are a few options.
##### Download a build
[fuzzfetch](https://github.com/MozillaSecurity/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](https://firefox-ci-tc.services.mozilla.com/tasks/index/gecko.v2.mozilla-central.latest.firefox/).
##### Create your own build
If you would like to compile your own, build instructions can be found [here](https://firefox-source-docs.mozilla.org/setup/index.html). When using `minidump-stackwalk`
breakpad [symbols](https://firefox-source-docs.mozilla.org/setup/building_with_debug_symbols.html#building-with-debug-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](https://github.com/MozillaSecurity/grizzly/wiki/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](https://github.com/MozillaSecurity/prefpicker).
Raw data
{
"_id": null,
"home_page": "https://github.com/MozillaSecurity/ffpuppet",
"name": "ffpuppet",
"maintainer": "Mozilla Fuzzing Team",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "fuzzing@mozilla.com",
"keywords": "automation firefox fuzz fuzzing security test testing",
"author": "Tyson Smith",
"author_email": "twsmith@mozilla.com",
"download_url": "https://files.pythonhosted.org/packages/46/d0/0ce15cf63d728713a30a28af8f4682d854b4ea14c381873ab97475bd4b35/ffpuppet-0.18.4.tar.gz",
"platform": null,
"description": "FFPuppet\n========\n\n[](https://github.com/MozillaSecurity/ffpuppet/actions/workflows/ci.yml)\n[](https://codecov.io/gh/MozillaSecurity/ffpuppet)\n[](https://matrix.to/#/#fuzzing:mozilla.org)\n[](https://pypi.org/project/ffpuppet)\n\nFFPuppet is a Python module that automates browser process related tasks to aid in fuzzing. Happy bug hunting!\n\nAre you [fuzzing](https://firefox-source-docs.mozilla.org/tools/fuzzing/index.html) the browser? [Grizzly](https://github.com/MozillaSecurity/grizzly) can help.\n\nInstallation\n------------\n\n##### To install the latest version from PyPI\n\n pip install ffpuppet\n\n##### Xvfb on Linux\n\nOn Linux `xvfb` can be used in order to run headless (this is not the same as Firefox's `-headless` mode).\n\nTo install `xvfb` on Ubuntu run:\n\n apt-get install xvfb\n\n##### Install minidump-stackwalk\n\n`minidump-stackwalk` is used to collect crash reports from minidump files. More\ninformation can be found [here](https://lib.rs/crates/minidump-stackwalk).\n\nBrowser Builds\n--------------\n\nIf you are looking for builds to use with FFPuppet there are a few options.\n\n##### Download a build\n\n[fuzzfetch](https://github.com/MozillaSecurity/fuzzfetch) is the recommended method for obtaining builds and is also very helpful in automation.\n\nTaskcluster has a collection of many different build types for multiple platforms and branches.\nAn index of the latest mozilla-central builds can be found [here](https://firefox-ci-tc.services.mozilla.com/tasks/index/gecko.v2.mozilla-central.latest.firefox/).\n\n##### Create your own build\n\nIf you would like to compile your own, build instructions can be found [here](https://firefox-source-docs.mozilla.org/setup/index.html). When using `minidump-stackwalk`\nbreakpad [symbols](https://firefox-source-docs.mozilla.org/setup/building_with_debug_symbols.html#building-with-debug-symbols) are required for symbolized stacks.\n\nUsage\n-----\n\nOnce installed FFPuppet can be run using the following command:\n\n ffpuppet <firefox_binary>\n\n##### Replaying a test case\n\n ffpuppet <firefox_binary> -p <custom_prefs.js> -d -u <testcase>\n\nThis 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](https://github.com/MozillaSecurity/grizzly/wiki/Grizzly-Replay) is recommended for replaying test cases.\n\n##### Prefs.js files\n\nprefs.js files that can be used for fuzzing or other automated testing can be generated with [PrefPicker](https://github.com/MozillaSecurity/prefpicker).\n",
"bugtrack_url": null,
"license": "MPL 2.0",
"summary": "A Python module that aids in the automation of Firefox at the process level",
"version": "0.18.4",
"project_urls": {
"Homepage": "https://github.com/MozillaSecurity/ffpuppet"
},
"split_keywords": [
"automation",
"firefox",
"fuzz",
"fuzzing",
"security",
"test",
"testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2199af039660a427d632c6b74bce38d4fdd469e1bdcfcc31e3e7f9c9b971c545",
"md5": "e452154d0bb95e469b324c9589edb418",
"sha256": "ead2006665b86c8e1ffccd7688a727b5c6f77f9201ab792c38ecf23fe770b441"
},
"downloads": -1,
"filename": "ffpuppet-0.18.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e452154d0bb95e469b324c9589edb418",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 99072,
"upload_time": "2025-08-05T21:43:58",
"upload_time_iso_8601": "2025-08-05T21:43:58.900580Z",
"url": "https://files.pythonhosted.org/packages/21/99/af039660a427d632c6b74bce38d4fdd469e1bdcfcc31e3e7f9c9b971c545/ffpuppet-0.18.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "46d00ce15cf63d728713a30a28af8f4682d854b4ea14c381873ab97475bd4b35",
"md5": "293ec40e33d953ddb1094421c249b4e0",
"sha256": "f078e3b3dc0dc55cf932c43a20859a06b0ba368bc94f26d4044f5d3d5ae7740e"
},
"downloads": -1,
"filename": "ffpuppet-0.18.4.tar.gz",
"has_sig": false,
"md5_digest": "293ec40e33d953ddb1094421c249b4e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 86373,
"upload_time": "2025-08-05T21:44:00",
"upload_time_iso_8601": "2025-08-05T21:44:00.188007Z",
"url": "https://files.pythonhosted.org/packages/46/d0/0ce15cf63d728713a30a28af8f4682d854b4ea14c381873ab97475bd4b35/ffpuppet-0.18.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 21:44:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MozillaSecurity",
"github_project": "ffpuppet",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "ffpuppet"
}
JSON
