== Quick Start Guide ==

=== Important Notice ===

This software is a prototype, it's not heavily tested and it was 
developed in a specific environment. Don't expect everything to 
work out of the box. Be prepared to solve problems related to your 
environment, configuration and defects in this code. If you hit a 
problem you cannot solve, let us know. 

You can find us on IRC at irc.mozilla.org, channel #security.

Or you can write me an email to decoder@mozilla.com.

Furthermore, if you make changes to this code, e.g. bugfixes or
modifications that others would benefit from as well, please be
fair and share them :)


=== Requirements ===

In order to use this software you need:

* The mozdevice module:
  Tested with my fork at 
     https://github.com/choller/mozbase/tree/master/mozdevice
  but changes are regularly merged to main.

* A working Android Development environment (in particular ADB)

* A rooted Android device with Fennec (Firefox Mobile) with
  crash reporter enabled.
 OR
* A non-rooted Android device with your own debuggable Firefox
  Mobile build (see end of this doc) and crash reporter enabled.

* A network connection between your host machine and the Android
  device, e.g. a common LAN/WLAN.

* A Firefox profile on the device with settings as shown in
  the misc/prefs.js file. You can simply copy this file to
  the profile directory while Firefox is not running.
  (DON'T use your productive profile for this!)

* The em-websocket-proxy script (gem install em-websocket-proxy).


=== Configuring the Sample Fuzzer ===

Open the file helloworld.cfg, adjust localHost to match your host's LAN
IP address. If you are attempting to use ADB over TCP/IP, rather than over
a USB connection, also set the remoteHost variable appropriately.


=== Starting the Sample Fuzzer ===

Start the fuzzer with the following command:
 
 python adbfuzz.py helloworld.cfg run

You'll see all sorts of debug messages, but if everything goes right, you
should see Fennec popup on the device, trying to contact the host to load
the fuzzing code.

The sample fuzzer included is just a little demo that makes a pink square
div bounce around using random CSS transformations. It's unlikely that this
alone will find bugs, but I think it's a good demonstration of what you can
do.

=== Reproducing crashes ===

The sample fuzzer sends all commands it executes using websockets. Once the
harness detects a crash, it will copy the logfiles (websocket+syslog) and store
them together with the crash dump. You need to extract the information from the 
log and replace the "start();" call at the end of the fuzzer file with those
commands to replay them.


=== Advanced: Creating a debuggable Firefox build for use with non-rooted devices  ===

The harness supports running on non-rooted devices, given that the "run-as" functionality
is working. Using "run-as" requires the installed target package to be marked in a special
way ("debuggable"), because it allows other apps to access the data of that application,
which would be a security problem. To build your own Fennec debuggable package, perform
the following steps:

1. Get a working build environment for Fennec:
 https://wiki.mozilla.org/Mobile/Fennec/Android

2. Modify the file mobile/android/base/AndroidManifest.xml.in:
 In that file, search for "debuggable", you will find a conditional where it's set to true
 or false based on MOZILLA_OFFICIAL. Make sure it's always true.

3. Use the following .mozconfig to build (make -f client.mk && make -C objdir-droid package):

# Add the correct paths here
ac_add_options --with-android-ndk="/home/build/NVPACK/android-ndk"
ac_add_options --with-android-sdk="/home/build/NVPACK/android-sdk/platforms/android-13"
ac_add_options --with-android-version=5
ac_add_options --with-android-tools="/home/build/NVPACK/android-sdk/tools"
# android options
ac_add_options --enable-application=mobile/android
ac_add_options --target=arm-linux-androideabi
ac_add_options --with-endian=little
ac_add_options --with-ccache
ac_add_options --enable-tests
ac_add_options --disable-elf-hack
ac_add_options --enable-debug-symbols
export MOZ_OLD_LINKER=1
# 32 bit
ac_add_options --host=i386-unknown-linux
HOST_CC="gcc -m32"
HOST_CXX="g++ -m32"
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/objdir-droid
mk_add_options MOZ_MAKE_FLAGS="-j8"
ac_add_options --enable-optimize
ac_add_options --enable-debug
export MOZILLA_OFFICIAL=1

4. Install the resulting package in objdir-droid/dist/ to your device.

5. Verify it's running, using "adb shell run-as org.mozilla.fennec_yourusername ls".

Unfortunately, some (older) Android versions ship a broken version of the "run-as" tool, 
and if that is the case with your device, then there is no other way than rooting it, sorry :(