FFPuppet
========
[](https://community-tc.services.mozilla.com/api/github/v1/repository/MozillaSecurity/ffpuppet/master/latest)
[](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/9a/46/36cff468949786fe59084979b9a8561632e5ddea6c239c0043a02015a280/ffpuppet-0.16.2.tar.gz",
"platform": null,
"description": "FFPuppet\n========\n\n[](https://community-tc.services.mozilla.com/api/github/v1/repository/MozillaSecurity/ffpuppet/master/latest)\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.16.2",
"project_urls": {
"Homepage": "https://github.com/MozillaSecurity/ffpuppet"
},
"split_keywords": [
"automation",
"firefox",
"fuzz",
"fuzzing",
"security",
"test",
"testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "420270050b89d9b0c8e36ed353b01d82ac486956a04fc17207c3f7de3076aacd",
"md5": "53708a64920fe8db82d0164880ee7c8f",
"sha256": "20329734991cf5be39c607bce7bbf32bf37e00064f0933abddf2569f4abe05f2"
},
"downloads": -1,
"filename": "ffpuppet-0.16.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53708a64920fe8db82d0164880ee7c8f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 84381,
"upload_time": "2025-02-13T22:40:45",
"upload_time_iso_8601": "2025-02-13T22:40:45.486352Z",
"url": "https://files.pythonhosted.org/packages/42/02/70050b89d9b0c8e36ed353b01d82ac486956a04fc17207c3f7de3076aacd/ffpuppet-0.16.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9a4636cff468949786fe59084979b9a8561632e5ddea6c239c0043a02015a280",
"md5": "fc7504d4daed3d10372d3cdb1152e981",
"sha256": "91cf211681bb4c875761b5776e0ec4ab8f83ff9c040880eb6fc76d09fe7a387f"
},
"downloads": -1,
"filename": "ffpuppet-0.16.2.tar.gz",
"has_sig": false,
"md5_digest": "fc7504d4daed3d10372d3cdb1152e981",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 73806,
"upload_time": "2025-02-13T22:40:49",
"upload_time_iso_8601": "2025-02-13T22:40:49.759464Z",
"url": "https://files.pythonhosted.org/packages/9a/46/36cff468949786fe59084979b9a8561632e5ddea6c239c0043a02015a280/ffpuppet-0.16.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-13 22:40:49",
"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
