Android Support for Volatility
==============================

The following plugins are provided:

 - android_find_class_instance
 - android_app_generic

All plugins require a valid profile and lime [1] memory dump. The plugins have been successfully tested on the emulator of the Android SDK (API Lvl 15 - 4.0.3)


Prerequisites
=============

- The Volatility 2.3-devel (or alpha) branch is needed
- sqlite3 for caching functionality
- TkInter for GUI


Detailed plugin description:
============================

android_find_class_instances
----------------------------

This plugin scans the heap of the given app (= a specific dalvik vm) for valid instances of objects. Every identified object is stored in the database under ~/.cache/volatility/<md5-hash of analyzed memory dump>.db for later usage. The database is written only once for each dump and PID unless otherwise specified by the optional argument --write_sql_cache which forces an overwrite. For every subsequent execution with the same dump/PID combination the cached data in the database will be fetched and printed out, no additional processing will be done.

The mechanics are based on the plugin "dalvik_find_class_instance" written by Holger Macht

Usage:
python vol.py -f <dump> --profile=<profile> android_find_class_instances -p <PID>
The PID can be determined by linux_pslist for example and must point to a dalvik vm process.
Execution takes between 1 to 3 hours for an average app.

Optional argument:
--write_sql_cache: a flag to force overwriting of the cache.


android_app_generic
-------------------

Automatically evaluates every object found by android_find_class_instances. Contained values (e.g. basetypes, Strings etc.) are parsed and stored in the previously mentioned database under ~/.cache/volatility/<md5-hash of analyzed memory dump>.db. Additionally all references between those objects are stored aswell. Caching works the same as with android_find_class_instances

For displaying the restored data, the optional argument "--gui" can be specified. This will start a small Python GUI containing all data from the database. The GUI cannot be started unless this plugin has been executed at least once before.

Usage:
python vol.py -f <dump> --profile=<profile> android_app_generic -p <PID>
The PID can be determined by linux_pslist for example and must point to a dalvik vm process.
For the given PID the plugin "android_find_class_instances" has to be run first!
Execution takes between 1 to 3 hours for an average app.

Optional argument:
--write_sql_cache: a flag to force overwriting of the cache.
--gui: a flag to start the GUI for displaying the restored data. Must not be specified in the first run!


Helper modules:
===============

android.py
----------

Helper functions for parsing and caching.

android_app_generic_gui.py
--------------------------

Contains functionality of the GUI.


dalvik.py
---------

Helper functions for handling dalvik vms. Written by Holger Macht


dalvik_vtypes.py (volatility/plugins/overlays/linux/)
-----------------------------------------------------

Data structure definitions and extending helper functions. Written by Holger Macht


List of affected (modified) and newly created files in Volatility 2.3-alpha
================================================================

volatility/obj.py (modified: lines 75 - 77)
volatility/plugins/linux/android.py (newly created)
volatility/plugins/linux/android_find_class_instances.py (newly created)
volatility/plugins/linux/android_app_generic.py (newly created)
volatility/plugins/linux/android_app_generic_gui.py (newly created)
volatility/plugins/linux/dalvik.py (newly created, based on version of Holger Macht)
volatility/plugins/overlays/native_types.py (modified: lines 8 - 26)
volatility/plugins/overlays/linux/dalvik_vtypes.py (newly created, based on version of Holger Macht)


Explanatory Volatility session
==============================

 [...] = --profile=Linux<insert your profile here>x86 -f <insert lime memory dump here>

 $ ./vol.py [...] linux_pslist | grep com.android.mms
 0xd3d71800 com.android.mms      411             10028           Tue, 15 Jan 2013 15:35:21 +0000

 $ ./vol.py [...] android_find_class_instances -p 411
 SystemClass                                        InstanceOffset                                     Descriptor                                        
 -------------------------------------------------- -------------------------------------------------- --------------------------------------------------
 ...
 0x409b21e8                                         0x409cc9e0                                         Ljava/lang/Class;                                 
 0x409b2890                                         0x409cca28                                         Ljava/lang/Object;                                
 0x409cc938                                         0x409cca88                                         Landroid/content/res/AssetFileDescriptor$1;       
 0x409b3928                                         0x409cca98                                         [C                                                
 0x409b30b8                                         0x409ccac8                                         Ljava/lang/String;
 ...

 $ ./vol.py [...] android_app_generic -p 411
 Type       InstanceOffset Descriptor                     Name                           Value                                             
 ---------- -------------- ------------------------------ ------------------------------ --------------------------------------------------
 ...
 Object     0x409cbd78     Landroid/text/format/Time;                                                                                      
 IField     0x4339ce19     Ljava/lang/String;             timezone                                                                         
 IField     0x409cbd84     I                              yearDay                                                                        10
 IField     0x409cbd88     J                              gmtoff                                                                 1091961360
 IField     0x409cbd90     I                              isDst                                                                           0
 IField     0x409cbd94     I                              minute                                                                         35
 IField     0x409cbd98     I                              month                                                                  1083912376
 IField     0x409cbd9c     I                              monthDay                                                                        0
 IField     0x409cbda0     I                              second                                                                 1084014008
 IField     0x409cbda4     Z                              allDay                                                                          1
 IField     0x409cbda8     I                              weekDay                                                                         0
 IField     0x409cbdac     I                              year                                                                            3
 IField     0x409cbdb0     I                              hour                                                                            0
 Object     0x409cbd98     Ljava/lang/String;                                            UTC                                               
 IField     0x409cbdb8     [C                             value                                                                            
 IField     0x409cbda4     I                              hashCode                                                                    84356
 IField     0x409cbda8     I                              offset                                                                          0
 IField     0x409cbdac     I                              count                                                                           3
 Object     0x409cbdb8     [C                                                            U,T,C                                             
 ...

 $ ./vol.py [...] android_app_generic -p 411 --gui
 Starting GUI now
 <Window of Python GUI (TKinter) opens>

[1] http://code.google.com/p/lime-forensics/