Add brief example descriptions to README (#120)

* Added brief example descriptions to README
* Update config script
* Update sym.py API usage
* Remove individual example descriptions
* fix mcore init
* consistently document examples
* make basic_sym runnable
* More path fixes
* cleanup; update api

README.md

@@ -109,6 +109,10 @@ def hook(state):
 m.run()
 ```
 
+### Examples
+
+Some example scripts using the Manticore API can be found in `examples/script`.
+
 ## FAQ
 
 ### How does Manticore compare to angr?

examples/script/lads-baby-re.py

@@ -1,12 +1,11 @@
-'''
-API v0.1.0
-Solves modified version of baby-re, compiled for arm.
-'''
-
 import sys
 
 from manticore import Manticore
 
+'''
+Solves modified version of baby-re, compiled for arm.
+'''
+
 if __name__ == '__main__':
     path = sys.argv[1]
     m = Manticore(path)
@@ -26,4 +25,3 @@ if __name__ == '__main__':
         m.terminate()
 
     m.run()
-    print 'done'

examples/script/manticore_config.py

@@ -1,34 +0,0 @@
-#!/usr/bin/env python
-
-import sys
-from manticore import Manticore
-
-# This example demonstrates the basic high level config
-# interface
-
-def get_args():
-    class Args(object): pass
-    args = Args()
-    args.replay = None; args.data = ''; args.dumpafter = 0; args.maxstates = 0;
-    args.maxstorage = 0; args.stats = True; args.verbose = False; args.log = '-';
-    return args
-
-if __name__ == '__main__':
-    path = sys.argv[1]
-    args = get_args()
-
-    args.programs = sys.argv[1:]
-    # Create a new Manticore object
-    m = Manticore(None, path, args)
-
-    # Set a few settings
-    m.procs = 4
-    m.solver = 'z3'
-
-    # Start path exploration. start() returns when Manticore
-    # finishes
-    m.run()
-
-    # Print high level statistics
-    m.dump_stats()
-

examples/script/multi_arch_sym.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python
+
+import sys
+from manticore import Manticore
+
+'''
+Minimal example demonstrating setting execution hooks, the ability to target
+multiple target architectures, and symbolicating memory.
+'''
+
+if __name__ == '__main__':
+
+    if len(sys.argv) < 2:
+        print "Usage: {} [binary] [arguments]".format(sys.argv[0])
+        sys.exit(1)
+
+    # Create a new Manticore object
+    m = Manticore(sys.argv[1], sys.argv[2:])
+
+    if m.arch == 'arm':
+        target = (0x1082c, 'R4')
+    else:
+        target = (0x400a83, 'EBX')
+
+    @m.hook(target[0])
+    def entered_func(state):
+        '''
+        For ARM, Make R4 symbolic at 0x1082c, as r4 is used in a branch right
+        after.
+        '''
+        sym_var = state.new_symbolic_value(32, label='from_callback')
+        state.cpu.write_register(target[1], sym_var)
+
+    # Start path exploration. start() returns when Manticore finishes
+    m.verbosity = 2
+    m.run()
+
+    # Print high level statistics
+    m.dump_stats()
+

examples/script/run_hook.py

@@ -3,7 +3,10 @@
 import sys
 from manticore import Manticore
 
-# This example demonstrates a basic hook (PC register)
+'''
+Demonstrates the ability to set a basic hook on a specific program counter and
+the ability to read from memory.
+'''
 
 if __name__ == '__main__':
     path = sys.argv[1]

examples/script/state_explore.py

@@ -2,6 +2,10 @@
 import sys
 from manticore import Manticore
 
+'''
+Demonstrates guiding Manticore's state exploration. 
+'''
+
 if __name__ == '__main__':
     if len(sys.argv) < 3:
         sys.stderr.write("Usage: %s [binary] [address]\n"%(sys.argv[0],))
@@ -17,6 +21,6 @@ if __name__ == '__main__':
         print "Abandoning state at PC: ", hex(state.cpu.PC)
         state.abandon()
 
-    print "Adding hook to: ", hex(to_abandon)
+    print "Adding hook to: {:x}".format(to_abandon)
 
     m.run()

examples/script/sym.py

@@ -1,52 +0,0 @@
-#!/usr/bin/env python
-
-import sys
-from core.smtlib.expression import *
-from capstone.arm import *
-from capstone.x86 import *
-from manticore import Manticore
-
-# This example demonstrates creating hooks on arbitrary values of the program
-# counter.
-
-def get_args():
-    class Args(object): pass
-    args = Args()
-    args.replay = None; args.data = ''; args.dumpafter = 0; args.maxstates = 0;
-    args.maxstorage = 0; args.stats = True; args.verbose = False; args.log = '-';
-    return args
-
-if __name__ == '__main__':
-    path = sys.argv[1]
-    args = get_args()
-
-    args.programs = sys.argv[1:]
-    # Create a new Manticore object
-    m = Manticore(None, path, args)
-
-    if m.arch == 'arm':
-        target = (0x1082c, 'R4')
-    else:
-        target = (0x400a83, 'EBX')
-
-    def entered_func(state):
-        '''For ARM, Make R4 symbolic at 0x1082c, as r4 is used in a branch right
-           after.
-        '''
-
-        cpu = state.cpu
-
-        sym_var = BitVecVariable(32, 'from_callback', taint=())
-
-        # Make destination register symbolic
-        setattr(cpu, target[1], sym_var)
-
-
-    m.add_pc_hook(target[0], entered_func)
-
-    # Start path exploration. start() returns when Manticore finishes
-    m.run()
-
-    # Print high level statistics
-    #m.dump_stats()
-