Debugging and security testing with Firefox OS

  • Revision slug: Mozilla/Firefox_OS/Security/Debugging_and_security_testing
  • Revision title: Debugging and security testing with Firefox OS
  • Revision id: 372319
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment more tweaks

Revision Content

{{Next("Mozilla/Firefox_OS/Security/Intercepting_traffic_using_a_proxy")}}

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. If you haven't already done so, start by reading the Firefox OS security overview; that will provide a basic background in the the terminology and architecture used below.

This guide includes the following chapters:

{{anch("Getting started")}}
Covers how to get started with a desktop build of Firefox OS, and how to use Marinette 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 B2G desktop with a custom profile, as well as how to create and install your own privileged apps.

All of our testing will happen against B2G Desktop, a native Firefox OS built for your desktop computer. Start downloading your flavor of nightly build (Linux, Mac OS, Windows) before you read on.

Getting started

Assuming you've already download your flavor of nightly build (Linux, Mac OS, Windows), you're ready to proceed, as follows.

Linux

Setting up B2G Desktop 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 B2G Desktop by clicking the B2G aplication 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 B2G Desktop.

At the time of writing, there is an issue running B2G Desktop on windows. You might be able to try the Firefox OS simulator instead.

Getting started tips

You can now play with a Firefox OS in a desktop window. Go 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, radio etc won't work for obvious reasons.

Make yourself comfortable with B2G Desktop; be sure to read Using the B2G desktop client to learn how it works.

Now to the real deal. We want to make JavaScript calls from inside Firefox OS.

Marionette: A JavaScript debugging shell for Firefox OS

Marionette is based on the Selenium/WebDriver API to automate Firefox OS testing. This helps us get a JavaScript shell within Firefox OS or a running app. First, get the marionette client from github (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.

Setting up B2G Desktop with Marionette is easy; just be sure your b2g profile (just like in the Firefox browser, all user settings are stored within a profile) has Marionette enabled. To do so, add the following line to your prefs.js file in gaia/profile/.

user_pref("marionette.force-local", true);

This will let marionette-debugging listen on port 2828 and allow the installed client to connect. This will suffice to get started, but if you want to know more look at the full Marionette docs. After we have enabled marionette-debugging, restart B2G Desktop. You will see no difference in the B2G window, but it is already listening on port 2828.

Now, instead of spinning up a Python console, importing the marionette-client library and creating a debugging session, 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 remote-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, here we go debugging it:

$ python fxos-repl.py list
app://homescreen.gaiamobile.org/index.html#root
app://browser.gaiamobile.org/index.html
app://keyboard.gaiamobile.org/index.html

Aha, these are the running apps and their URIs. Now let's connect to the browser app and examine it:

$ python fxos-reply.py connect app://browser.gaiamobile.org/index.html
Connected to app://browser.gaiamobile.org/index.html

Let's use the {{domxref("document.querySelector()")}} API to find a {{HTMLElement("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(&quot;style/images/go.png&quot;);" 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)

This is it for executing your JavaScript code with in a running application's scope.

Now go play!

{{Next("Mozilla/Firefox_OS/Security/Intercepting_traffic_using_a_proxy")}}

Revision Source

<p>{{Next("Mozilla/Firefox_OS/Security/Intercepting_traffic_using_a_proxy")}}</p>
<p>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. If you haven't already done so, start by reading the <a href="/en-US/docs/Mozilla/Firefox_OS/Security/Security_model" title="/en-US/docs/Mozilla/Firefox_OS/Security/Security_model">Firefox OS security overview</a>; that will provide a basic background in the the terminology and architecture used below.</p>
<p>This guide includes the following chapters:</p>
<dl>
  <dt>
    {{anch("Getting started")}}</dt>
  <dd>
    Covers how to get started with a desktop build of Firefox OS, and how to use Marinette to inspect and control apps running on Firefox OS.</dd>
  <dt>
    <a href="/en-US/docs/Mozilla/Firefox_OS/Security/Intercepting_traffic_using_a_proxy" title="/en-US/docs/Mozilla/Firefox_OS/Security/Intercepting_traffic_using_a_proxy">Intercepting Firefox OS traffic using a proxy</a></dt>
  <dd>
    How to use a proxy to intercept network traffic to inspect it.</dd>
  <dt>
    <a href="/en-US/docs/Mozilla/Firefox_OS/Apps/Testing_in_a_privileged_context" title="/en-US/docs/Mozilla/Firefox_OS/Apps/Testing_in_a_privileged_context">Modifying Gaia</a></dt>
  <dd>
    How to run B2G desktop with a custom profile, as well as how to create and install your own privileged apps.</dd>
</dl>
<p>All of our testing will happen against <a href="/en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_desktop_client" title="/en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_desktop_client">B2G Desktop</a>, a native Firefox OS built for your desktop computer. Start downloading your <a data-mce-="" href="http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-b2g18/">flavor of nightly build (Linux, Mac OS, Windows)</a> before you read on.</p>
<h2 id="Getting_started_with_b2g-desktop">Getting started</h2>
<p>Assuming you've already download your <a data-mce-="" href="http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-b2g18/">flavor of nightly build (Linux, Mac OS, Windows)</a>, you're ready to proceed, as follows.</p>
<h3 id="Linux">Linux</h3>
<p>Setting up B2G Desktop is as simple as extracting the archive and running the <code>b2g</code> binary:</p>
<pre>
tar xf b2g-something-something.tar.bz2
cd b2g
./b2g</pre>
<h3 id="Mac">Mac</h3>
<p>Open the downloaded disk image file, and copy the B2G application to your <code>/Applications</code> directory. Once that's done, launch B2G Desktop by clicking the B2G aplication icon. Alternatively you can launch it from Terminal as follows:</p>
<pre>
/Applications/B2G.app/Contents/MacOS/b2g</pre>
<h3 id="Windows">Windows</h3>
<p>Download and extract the zip file to a convenient location. Double-click on <code>b2g.exe</code> to start B2G Desktop.</p>
<p>At the time of writing, there is an issue running B2G Desktop on windows. You might be able to try the <a href="https://addons.mozilla.org/en-US/firefox/addon/firefox-os-simulator/" title="https://addons.mozilla.org/en-US/firefox/addon/firefox-os-simulator/">Firefox OS simulator</a> instead.</p>
<h3 id="Getting_started_tips">Getting started tips</h3>
<p>You can now play with a Firefox OS in a desktop window. Go 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, radio etc won't work for obvious reasons.</p>
<p>Make yourself comfortable with B2G Desktop; be sure to read <a href="/en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_desktop_client" title="/en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_desktop_client">Using the B2G desktop client</a> to learn how it works.</p>
<p>Now to the real deal. We want to make JavaScript calls from inside Firefox OS.</p>
<h2 id="Marionette.3A_Getting_a_JavaScript_debugging_shell_for_Firefox_OS">Marionette: A JavaScript debugging shell for Firefox OS</h2>
<p><a href="/en-US/docs/Marionette" title="/en-US/docs/Marionette">Marionette</a> is based on the Selenium/WebDriver API to automate Firefox OS testing. This helps us get a JavaScript shell within Firefox OS or a running app. First, get the <a data-mce-="" href="https://github.com/mozilla/marionette_client">marionette client from github</a> (written in Python) and follow the installation instructions given there.</p>
<div class="note">
  <p><strong>Note:</strong> Recent tests have shown that you may have problems with certain versions of mozbase. The last known-working state of mozbase is at <a href="https://github.com/mozilla/mozbase/tree/9ee2dee5fdde6cf5d6bf7caac4db6673112df79d/" title="https://github.com/mozilla/mozbase/tree/9ee2dee5fdde6cf5d6bf7caac4db6673112df79d/">commit 9ee2de</a>.</p>
</div>
<p>Setting up B2G Desktop with Marionette is easy; just be sure your b2g profile (just like in the Firefox browser, all user settings are stored within a profile) has Marionette enabled. To do so, add the following line to your <code>prefs.js</code> file in <code>gaia/profile/</code>.</p>
<pre>
user_pref("marionette.force-local", true);</pre>
<p>This will let marionette-debugging listen on port 2828 and allow the installed client to connect. This will suffice to get started, but if you want to know more look at the <a data-mce-="" href="https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Platform/Testing/Setting_up_Marionette">full Marionette docs.</a> After we have enabled marionette-debugging, restart B2G Desktop. You will see no difference in the B2G window, but it is already listening on port 2828.</p>
<p>Now, instead of spinning up a Python console, importing the marionette-client library and creating a debugging session, 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 <a data-mce-="" href="https://raw.github.com/st3fan/fxos-repl/master/fxos-repl.py">fxos-repl.py</a>.</p>
<p>For our example, we will remote-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, here we go debugging it:</p>
<pre>
$ <strong>python fxos-repl.py list</strong>
app://homescreen.gaiamobile.org/index.html#root
app://browser.gaiamobile.org/index.html
app://keyboard.gaiamobile.org/index.html</pre>
<p>Aha, these are the running apps and their URIs. Now let's connect to the browser app and examine it:</p>
<pre>
$ <strong>python fxos-reply.py connect app://browser.gaiamobile.org/index.html</strong>
Connected to app://browser.gaiamobile.org/index.html</pre>
<p>Let's use the {{domxref("document.querySelector()")}} API to find a {{HTMLElement("menu")}} tag with the ID <code>toolbar-start</code>, and view its HTML:</p>
<pre>
&gt;&gt;&gt; <strong>document.querySelector("menu#toolbar-start").outerHTML</strong>
&lt;menu type="toolbar" id="toolbar-start"&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;form id="url-bar" novalidate=""&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;input id="ssl-indicator" value="" type="image"&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;input id="url-input" placeholder="Enter search or address" data-l10n-id="enter-search-or-address" x-inputmode="verbatim" type="text"&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;input style="background-image: url(&amp;quot;style/images/go.png&amp;quot;);" id="url-button" value="" type="image"&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;/form&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;span id="tabs-badge"&gt;1&lt;span id="more-tabs"&gt;›&lt;/span&gt;&lt;/span&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;button id="awesomescreen-cancel-button"&gt;&lt;/button&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;div id="throbber"&gt;&lt;/div&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;/menu&gt;</pre>
<p>Does it look familiar? It's the toolbar that contains the address bar and the new tab button!</p>
<p>Let's use our shell to simulate a click on the new tab button. Its ID is <code>tabs-badge</code>.</p>
<pre>
&gt;&gt;&gt; <strong>document.querySelector("#tabs-badge").click()</strong></pre>
<p>The new tab UI should show now. Let's try something else:</p>
<pre>
&gt;&gt;&gt; <strong>alert(location.href)</strong></pre>
<p>This is it for executing your JavaScript code with in a running application's scope.</p>
<p>Now go play!</p>
<p>{{Next("Mozilla/Firefox_OS/Security/Intercepting_traffic_using_a_proxy")}}</p>
Revert to this revision