Security/B2G/GaiaTesting

Quicklinks

• 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 [1])

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 - )

HINTS

• 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)

Marionette provides a mechanism to connect a remote client to a B2G instance, call javascript and get the result. It allows injecting script into any level from chrome right down to web content.
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/'