- 1 Quicklinks
- 2 Old Guidance (needs updating)
- 2.1 Setting up B2G Desktop
- 2.2 Testing the B2G Browser App (Web Content)
- 2.3 Testing as a Web App (App Content)
- 2.4 Testing with Marionette (Inject code into any context, including System App, and Chrome)
- Latest simulator: https://ftp.mozilla.org/pub/mozilla.org/labs/r2d2b2g/?C=M;O=D
- Latest b2g desktop: http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/
Old Guidance (needs updating)
Testing Gaia with B2G desktop Gaia is a collection of web apps which make up the UI for the Boot to Gecko project. It consists of a system app, which performs most runtime functions and loads all of the other Web Apps, such as apps for the Browser, Dialer, SMS, Contacts etc. When running, Gaia can be thought of as one large HTML document as shown below:
<window> Gecko chrome | +--> <iframe> Gaia system app | +--> <iframe> homescreen app | +--> <iframe> keyboard | +--> <iframe> Web Apps (one per each app) | +--> <iframe> browser app (when it is loaded) | <iframe> Web content
So when performing Gaia security testing, we mainly was to test from two perspectives (from least to most privileged):
- Web Content loaded in the Gaia Browser App
- Installed Web Apps
- The System App (in case of attack from content)
- Gecko chrome code (in case of further privilege escalation)
This post will go through the basics of executing script at each of these levels.
Setting up B2G Desktop
When testing gaia, you have 4 options:
- a b2g device
- b2g in an emulator
- b2g compiled to run on desktop (b2g desktop or the simulator)
- load Gaia inside nightly
Testing on b2g desktop is the sweet spot for ease of use vs completeness. Obviously some things don't work (dialing, sms etc) but for just testing Gaia as a whole this is a great place to start. (more detail on this )
The following are condensed instructions for how to install and run b2g desktop. For a more detailed explanation and further information, see https://wiki.mozilla.org/Gaia/Hacking.
Step 1. Install B2G desktop
Download and install the appropriate binary for your system here: http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-b2g18/
Step 2. Download and build Gaia
You need to download Gaia, and then build it, which builds a profile which you can load with b2g desktop. This can be achieved with the following commands:
$ git clone https://github.com/mozilla-b2g/gaia $ cd gaia $ make
Step 3. Load B2G desktop using the profile created by gaia
Load the b2g executable, supplying the -profile option with the path to the gaia location
$ b2g -profile /path/to/gaia/profile
On a Mac the command to launch from the gaia directory:
$ /Applications/B2G.app/Contents/MacOS/b2g -profile `pwd`/profile
Assuming it all works, you should see the lock screen: http://imgur.com/yKxqN
- Useful switches when running b2g:
- Launch B2G desktop with a specific screen resolution: --screen (e.g. --screen 800x600)
- Enable the error console: -jsconsole (note the single - )
- Exit an app using esc or home key (fn + left, mac users)
- This is a phone; the screen will sleep! Wake from sleep (black screen) using home key command only (fn + left, mac users)
Testing the B2G Browser App (Web Content)
Webpages are the least privileged content on b2g and the easiest to test. Just open the browser app and load a web page.
Testing as a Web App (App Content)
The easiest way to test as a web app is to create your web app. This is made easy since there is already a template in gaia which you can copy. Below are instructions to copy http://www.squarefree.com/shell/shell.html into an app so you have a nice shell to execute commands as an app (again assuming current in gaia directory).
Step 1. Make a copy of the template app
$ cp -R test_apps/template test_apps/shell
Step 2. Put some content in index.html
$ curl http://www.squarefree.com/shell/shell.html >test_apps/shell/index.html
Step 3. Change the name in manifest.webapp
$ sed -e '/Template/s//Shell/' test_apps/shell/manifest.webapp
Step 4. Rebuild and relaunch
Rebuild gaia (DEBUG=1 make) and relaunch as described above. You should now have a new app installed called "shell". Running it should look something like this: http://imgur.com/nW8Gw
You might want to launch b2g with a larger screen (use --screen ###x###) res so you can see what you are typing. Or click and drag to zoom the page.
Testing with Marionette (Inject code into any context, including System App, and Chrome)
To install and get started with Marionette, follow the instructions here: https://developer.mozilla.org/en/Mozilla/Boot_to_Gecko/Setting_Up_Marionette_for_B2G
Important: Since we are running b2g desktop instead of on a device or emulator, you do not need to use adb to forward port 2828. Just skip this step.
Once you have it all working, the following commands will get you started.
>>> from marionette import Marionette >>> marionette = Marionette('localhost', 2828) >>> marionette.start_session() u'8-b2g'
At this point we are connected and can start issuing commands.
>>> marionette.execute_script("return document.location.href") u'http://system.gaiamobile.org:8080/'
By default, we are executing script inside the top level content frame, which is the Gaia "System" app. To switch to chrome perform use the set_context command:
>>> marionette.set_context("chrome") True >>> marionette.execute_script("return document.location.href") u'chrome://browser/content/shell.xul'
To switch back, use the same command:
>>> marionette.set_context("content") True >>> marionette.execute_script("return document.location.href") u'http://system.gaiamobile.org:8080/'
Now lets open the browser app (note the use of wrappedJSObject for non-DOM entities):
>>> marionette.execute_script("return window.wrappedJSObject.WindowManager.launch('http://browser.gaiamobile.org:8080')")
To switch to the browser, we need the id of the frame, which should be 4 if you haven't launched anything else:
>>> marionette.switch_to_frame(4) True >>> marionette.execute_script('return document.location.href') u'http://browser.gaiamobile.org:8080/'
Now you can execute script inside a running app. To switch back to the system or another app you need to reset marionette back to the top frame by:
>>> marionette.switch_to_frame() True >>> marionette.execute_script('return document.location.href') u'http://system.gaiamobile.org:8080/'