This guide is aimed at security testers wanting to start testing Firefox OS; it will help community members audit apps and the Firefox OS platform itself.
Note: If you are not already familiar with Firefox OS security, head over to our Security section to find out all about it. Start by reading the Firefox OS security overview — this article provides a basic background in the terminology and architecture.
This guide includes the following subsections:
- Getting started
- Covers how to get started with a desktop build of Firefox OS, and how to use Marionette to inspect and control apps running on Firefox OS.
- Intercepting Firefox OS traffic using a proxy
- How to use a proxy to intercept network traffic to inspect it.
- Modifying Gaia
- How to run the Firefox OS simulator with a custom profile, as well as how to create and install your privileged apps.
All of our testing will happen against the Firefox OS simulator; a native Firefox OS built for your desktop computer. Start downloading your flavor of nightly build (Linux, Mac OS, Windows) before you read any further.
Getting started
Assuming you've already downloaded the Firefox OS simulator as instructed above, you're ready to proceed, as follows.
Linux
Setting up the Firefox OS simulator is as simple as extracting the archive and running the b2g binary:
tar xf b2g-something-something.tar.bz2 cd b2g ./b2g
Mac
Open the downloaded disk image file, and copy the B2G application to your /Applications directory. Once that's done, launch the Firefox OS simulator by clicking the B2G application icon. Alternatively, you can launch it from Terminal as follows:
/Applications/B2G.app/Contents/MacOS/b2g
Windows
Download and extract the zip file to a convenient location. Double-click on b2g.exe to start the Firefox OS simulator.
Getting started tips
You can now play with a Firefox OS instance running in a desktop window. Go and play around: Open the browser (lower right icon) and visit a web page, or try opening a few apps. You will notice that some device-specific functionality — such as the dialer, camera, and radio — won't work for obvious reasons.
Make yourself comfortable with the Firefox OS simulator; be sure to read Building the Firefox OS simulator to learn how it works.
Now on to the real deal. We want to make JavaScript calls from inside Firefox OS.
Getting a debugging shell for Firefox OS
Marionette is based on the Selenium/WebDriver API, and provides the basis for the debugging shell we use to automate Firefox OS testing. First, set up the marionette client (written in Python) and follow the installation instructions given there.
Note: Recent tests have shown that you may have problems with certain versions of mozbase. The last known-working state of mozbase is at commit 9ee2de.
Note: Since you are using a nightly build, your b2g profile (just like in the Firefox browser, all user settings are stored within a profile) should already have Marionette enabled, via the line user_pref("marionette.defaultPrefs.enabled", true); in gaia/profile/. If not, you might be using the wrong build.prefs.js
At this point, you might be thinking of spinning up a Python console, importing the marionette-client library and creating a debugging session, but we can do something else: Stefan Arentz has created a simple JavaScript console that runs on top of the marionette-client library. So, let's download fxos-repl.py.
For our example, we will remotely control the Browser app. Start it by clicking the browser icon in the Firefox OS home screen's lower right with your mouse. Is the B2G binary showing the browser app? Good. The following commend will return a list of URLs representing the different apps we've got running, and allow us to start debugging them:
$ python fxos-repl.py list app://homescreen.gaiamobile.org/index.html#root app://browser.gaiamobile.org/index.html app://keyboard.gaiamobile.org/index.html
Now let's connect to the browser app and examine it:
$ python fxos-repl.py connect app://browser.gaiamobile.org/index.html Connected to app://browser.gaiamobile.org/index.html
Let's use the document.querySelector() API to find a <menu> tag with the ID toolbar-start, and view its HTML:
>>> document.querySelector("menu#toolbar-start").outerHTML
<menu type="toolbar" id="toolbar-start">
<form id="url-bar" novalidate="">
<input id="ssl-indicator" value="" type="image">
<input id="url-input" placeholder="Enter search or address" data-l10n-id="enter-search-or-address" x-inputmode="verbatim" type="text">
<input style="background-image: url("style/images/go.png");" id="url-button" value="" type="image">
</form>
<span id="tabs-badge">1<span id="more-tabs">›</span></span>
<button id="awesomescreen-cancel-button"></button>
<div id="throbber"></div>
</menu>
Does it look familiar? It's the toolbar that contains the address bar and the new tab button!
Let's use our shell to simulate a click on the new tab button. Its ID is tabs-badge.
>>> document.querySelector("#tabs-badge").click()
The new tab UI should show now. Let's try something else:
>>> alert(location.href)
Now go play!