Support for opcodes + doc + new tests + static attribute loading from init()

.gitignore

@@ -1,2 +1,3 @@
 *.pyc
+.pytest_cache
 .idea

README.md

@@ -1,20 +1,43 @@
 # Smali Emulator
 
-This software will emulate a [**smali**](https://github.com/JesusFreke/smali) source file generated by apktool, it is intended to be used as a quick and dirty way to defeat various types of encryption and obfuscation while reversing an APK.
+This software will emulate a [**smali**](https://github.com/JesusFreke/smali) source file 
+generated by apktool, it is intended to be used as a quick and dirty way to defeat various 
+types of encryption and obfuscation while reversing an APK.
 
-You'll find some examples in the `examples` folder of this project.
+This project is very much a work in progress, feel free to submit a patch.
 
-[Explanation of the "why" and "how" can be found here.](https://www.evilsocket.net/2016/04/18/how-i-defeated-an-obfuscated-and-anti-tamper-apk-with-some-python-and-a-home-made-smali-emulator/)
+As an example, you can run:
+
+```shell
+cd utils;
+./exec.py -i decryptor.smali -m field5 \
+-p '{"p0":[-62,-99,-106,-125,-123,-105,-98,-37,-105,-97,-103,-41,-118,-97,-113,-103,-109,-104,-115,111,98,103,35,52],"p1": 19}'
+```
+
+# Testing
+
+The project has recently be migrated to pytest for infrastructure of tests.
+To run tests, do:
 
-#### Note
+```shell
+pytest -v
+```
+
+The py3 compatibility has moved up, you should use pytest-3 whenever possible.
+However, python2 retrocompatibility should not be discarded, so use the two 
+test suites (pytest-2, pytest-3) to check the retrocompatibility in your changes.
+
+# Note
+
+[Explanation of the "why" and "how" can be found here.](https://www.evilsocket.net/2016/04/18/how-i-defeated-an-obfuscated-and-anti-tamper-apk-with-some-python-and-a-home-made-smali-emulator/)
 
 This is highly experimental, a very small subset of the Dalvik opcodes is currently supported, see the `smali/opcodes.py` file for more details.
 
 OpCodes List (Feel free to request access)
 
 https://docs.google.com/spreadsheets/d/1RfB_LsBoYnJxOh-lDCSMR0mfLBl1UlwdW9eKw2p03DY/edit?usp=sharing
 
-#### License
+# License
 
 Copyright (c) 2016 Simone Margaritelli | [Twitter](https://twitter.com/evilsocket) | [Blog](http://www.evilsocket.net)  
 Released under the GPL 3 license.

TODO.md

@@ -0,0 +1,46 @@
+# Ultimate goal
+
+The ultimate goal is to be able to load any .smali class file in python
+and to instanciate objects of that class as python objects.
+
+Example:
+
+```python
+import smali.bridge
+
+>>> ClassToLoad = smali.bridge.loadClass('ClassToLoad.smali')  # get the class
+>>> myObject = ClassToLoad()  # instanciate it
+>>> myObjects.methods()  # get the list of available methods
+['init', 'methodA', 'methodB']
+>>> myObjects.fields()  # get the list of fields
+['fieldA', 'fieldB']
+```
+
+However the current architecture is not really oriented toward this goal, because
+`smali_emulator` was at the beginning a simple script-like (quite complex for a script)
+application, but advanced use cases were not anticipated.
+
+Although there is a lack of long-term anticipation, the architecture is nevertheless quite
+useable and it is veryy possible to make it evolve without too much rewriting.
+
+The building block are already existing.
+
+    - ObjectMapping class is a dictionary with {className: methodList} functions.
+    - VM is storing the current execution status of the virtual machine.
+    - Emulator is running the source code
+
+We should add a support in ObjectMapping for Class objects that are analogous to the 
+corresponding smali files.
+
+See `smali/objects/metaclass.py`.
+
+One of the problem is that methods in java are all encapsulated into classes, there
+is no global variables shared through the code (in principle).
+
+So we need a global state that will map all classes in a package with a specific
+context for smali source code.
+
+
+
+
+

doc/ARCHITECTURE.md

@@ -0,0 +1,45 @@
+# Dalvik Virtual Machine
+
+The Dalvik Virtual Machine is register based.
+
+It means that, in a given frame, all the registers have a given value.
+
+This documentation may not be necessary up-to-date as we are trying to update
+our architecture to answer to more demanding challenges.
+
+# Implementation of static private fields read/write operations
+
+What the capability is of smali_emulator right now is
+
+- take a smali file
+- execute a method in that file by passing the argument dict
+- get back the result
+
+So far, the behaviour of the emulator has been perfect in this framework. Absolutely
+no errors, the software behaves very well. However, we lack many features in order 
+to be absolutely able to execute arbitrary smali code:
+
+- Cross references through the file are _not_ supported.
+- Instanciation of objects is _not_ supported.
+
+There is a real need to be able to instanciate classes « live ». Let 
+us assume that the class is self-contained.
+
+The need would be then to 
+
+- Instanciate the class using its `<init>` method
+- Execute some static methods on the object
+
+Problem is:
+
+  - how to dynamically create a class at runtime in python
+
+Solution would be:
+  - use the metaclass capability of python
+
+Process would be:
+  - parse the smali code
+  - create dynamically the class object
+  - 
+
+

doc/SCRIPTING.md

@@ -0,0 +1,87 @@
+# Scripting with smali emulator
+
+Ultimately, scripting the emulator to run methods of a `.smali` file
+from a python shell is a desirable goal.
+
+Here we attempt to write a self-explaining document, some of the features
+described here may not have been implemented yet, but we are working on it :)
+
+## Script 1
+
+Current state of scripting API allows us to do the following:
+
+```python
+
+import os.path
+import smali
+import smali.source
+import smali.emulator
+
+static_class_path = os.path.join(
+    os.path.dirname(smali.__file__), 
+    os.pardir, os.pardir, 'tests', 'staticmethod', 'value_cannot_be_null.smali'
+)
+
+# create a new emulator
+emulator = smali.emulator.Emulator()
+
+# run the *only* method in that file
+result = emulator.run_file(static_class_path, {'p0': 1, 'p1': 1, 'p2': -1})
+
+# display the result
+print(result)
+```
+
+## Script 2
+
+What we would like is to do:
+
+```python
+
+import os.path
+import smali
+import smali.source
+import smali.emulator
+
+static_class_path = os.path.join(
+    os.path.dirname(smali.__file__), 
+    os.pardir, os.pardir, 'tests', 'staticmethod', 'value_cannot_be_null.smali'
+)
+
+# create a new emulator
+emulator = smali.emulator.Emulator()
+
+# load all the methods in that file
+emulator.load_class(static_class_path)
+
+# exec the method
+emulator.exec_method('a', args={'p0': 1, 'p1': 1, 'p2': -1})
+
+# display the result
+print(result)
+```
+
+# Script 3: invoke init and subsequent methods
+
+We want ultimately the possibility to exec methods on the fly,
+especially to call the init method initializing members,
+then to call method for the sget/sput/iget/iput support to be really effective.
+
+This is possible through this example (see also `test_scripting_api.py`
+for details)
+
+
+```python
+"""Test two successive calls: 
+- first on '<clinit>' for initializing static fields
+- second on 'a' for deciphering some string
+"""
+emulator = smali.emulator.Emulator()
+emulator.load_class(get_file_path('completeclass', 'full_static_class.smali'))
+res = emulator.exec_method('<clinit>', args=None)  # call the static constructor
+res = emulator.exec_method(
+     'a', args={'p0': p0, 'p1': p1, 'p2': p2},
+     vm=emulator.vm  # need to propagate the vm because it contains
+                     # the static fields initialized from call to <clinit>
+)
+```

pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+addopts = --doctest-modules --ignore=utils