FFPuppet
========
[](https://community-tc.services.mozilla.com/api/github/v1/repository/MozillaSecurity/ffpuppet/master/latest)
[](https://codecov.io/gh/MozillaSecurity/ffpuppet)
[].num_joined_members&suffix=%20users&url=https%3A%2F%2Fmozilla.modular.im%2F_matrix%2Fclient%2Fr0%2FpublicRooms&style=flat&logo=matrix)](https://riot.im/app/#/room/#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:
python -m ffpuppet
```
usage: ffpuppet [-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 | --pernosco | --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. (Linux only)
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)
--pernosco Use rr. Trace intended to be submitted to Pernosco. (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. [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.8",
"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/36/ff/fd789bf1320fa72c308669fb302903252741d07821a4b382ed4e57af7203/ffpuppet-0.11.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[].num_joined_members&suffix=%20users&url=https%3A%2F%2Fmozilla.modular.im%2F_matrix%2Fclient%2Fr0%2FpublicRooms&style=flat&logo=matrix)](https://riot.im/app/#/room/#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 python -m ffpuppet\n\n```\nusage: ffpuppet [-h] [-d] [--log-level LOG_LEVEL] [-e EXTENSION] [-p PREFS]\n [-P PROFILE] [-u URL] [--xvfb] [-a ABORT_TOKEN]\n [--launch-timeout LAUNCH_TIMEOUT] [-l LOGS]\n [--log-limit LOG_LIMIT] [-m MEMORY]\n [--poll-interval POLL_INTERVAL] [--save-all]\n [--gdb | --pernosco | --rr | --valgrind]\n binary\n\nFFPuppet - Firefox process launcher and log collector. Happy bug hunting!\n\npositional arguments:\n binary Firefox binary to launch\n\noptional arguments:\n -h, --help show this help message and exit\n -d, --display-logs Display summary of browser logs on process exit.\n --log-level LOG_LEVEL\n Configure console logging. Options: DEBUG, INFO, WARN,\n ERROR (default: INFO)\n\nBrowser Configuration:\n -e EXTENSION, --extension EXTENSION\n Install extensions. Specify the path to the xpi or the\n directory containing the unpacked extension.\n -p PREFS, --prefs PREFS\n Custom prefs.js file to use (default: profile default)\n -P PROFILE, --profile PROFILE\n Profile to use. This is non-destructive. A copy of the\n target profile will be used. (default: temporary\n profile)\n -u URL, --url URL Server URL or path to local file to load.\n --xvfb Use Xvfb. (Linux only)\n\nIssue Detection & Reporting:\n -a ABORT_TOKEN, --abort-token ABORT_TOKEN\n Scan the browser logs for the given value and close\n browser if detected. For example '-a ###!!!\n ASSERTION:' would be used to detect soft assertions.\n --launch-timeout LAUNCH_TIMEOUT\n Number of seconds to wait for the browser to become\n responsive after launching. (default: 300)\n -l LOGS, --logs LOGS Location to save browser logs. A sub-directory\n containing the browser logs will be created.\n --log-limit LOG_LIMIT\n Browser log file size limit in MBs (default: 0, no\n limit)\n -m MEMORY, --memory MEMORY\n Browser memory limit in MBs (default: 0, no limit)\n --poll-interval POLL_INTERVAL\n Delay between checks for results (default: 0.5)\n --save-all Always save logs. By default logs are saved only when\n an issue is detected.\n\nAvailable Debuggers:\n --gdb Use GDB. (Linux only)\n --pernosco Use rr. Trace intended to be submitted to Pernosco. (Linux only)\n --rr Use rr. (Linux only)\n --valgrind Use Valgrind. (Linux only)\n\n```\n\n##### Replaying a test case\n\n python -m 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 and any log data (stderr, stdout, ASan logs... etc) will be dumped to the console when the browser process terminates. [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.11.2",
"project_urls": {
"Homepage": "https://github.com/MozillaSecurity/ffpuppet"
},
"split_keywords": [
"automation",
"firefox",
"fuzz",
"fuzzing",
"security",
"test",
"testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bed8dad8ccbae379b4d6e7118baace6acdd03365606167447ae3eef8cee0d156",
"md5": "129c0061a01924eda22dfcea6766a7a4",
"sha256": "e46cecc350f9ec6f2caac99c0a85a502cd78ba781c81ff1ff8a7c5f4725a0897"
},
"downloads": -1,
"filename": "ffpuppet-0.11.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "129c0061a01924eda22dfcea6766a7a4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 74227,
"upload_time": "2023-10-12T16:30:01",
"upload_time_iso_8601": "2023-10-12T16:30:01.643990Z",
"url": "https://files.pythonhosted.org/packages/be/d8/dad8ccbae379b4d6e7118baace6acdd03365606167447ae3eef8cee0d156/ffpuppet-0.11.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "36fffd789bf1320fa72c308669fb302903252741d07821a4b382ed4e57af7203",
"md5": "45b7bd0c06df4a6f8e166259df514294",
"sha256": "589bda8b411dbb1de0ab1c8878e0e4facb3409c3a09dc479ce0ba7bf8e602237"
},
"downloads": -1,
"filename": "ffpuppet-0.11.2.tar.gz",
"has_sig": false,
"md5_digest": "45b7bd0c06df4a6f8e166259df514294",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 67643,
"upload_time": "2023-10-12T16:30:04",
"upload_time_iso_8601": "2023-10-12T16:30:04.021230Z",
"url": "https://files.pythonhosted.org/packages/36/ff/fd789bf1320fa72c308669fb302903252741d07821a4b382ed4e57af7203/ffpuppet-0.11.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-12 16:30:04",
"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
