Updated API documentation

API

@@ -8,101 +8,77 @@ DESCRIPTION
 	examples are provided here to help jump-start development efforts.
 
 
-BASIC SCAN
+BINWALK SCRIPTING
 
-	The following is an example of the simplest scan, and is equivalent to running binwalk on the command line 
-	with no additional arguments:
+	Each of binwalk's features (signature scans, entropy analysis, etc) are implemented as separate modules.
+	These modules can be invoked via the binwalk.core.module.Modules class, which makes scripting trivial 
+	through its execute method.
 
-		import pprint
-		from binwalk import Binwalk
+	In fact, the binwalk command line utility can be duplicated nearly entirely with just two lines of code:
 
-		with Binwalk() as bw:
-			pprint.PrettyPrinter().pprint(bw.scan('firmware.bin'))
+		import binwalk
+		binwalk.Modules().execute()
 
-	The scan() method will return a list of results, and may also be passed a list of files:
+	The Modules class constructor as well as the execute method accept both Python args and kwargs corresponding
+	to the normal command line options accepted by the binwalk command line utility, providing a large amount of
+	freedom in how you choose to specify binwalk options (if none are specified, sys.argv is used by default).
 
-		from binwalk import Binwalk
+	For example, to execute a signature scan, you at the very least have to specify the --signature command line 
+	option, as well as a list of files to scan. This can be done in a number of ways:
 
-		with Binwalk() as bw:
-			for (filename, file_results) in bw.scan(['firmware1.bin', 'firmware2.bin']).iteritems():
-			print "Results for %s:" % filename
-			for (offset, results) in file_results:
-				for result in results:
-					print offset, result['description']
+		binwalk.Modules().execute('firmware1.bin', 'firmware2.bin', signature=True)
 
-	Alternatively, a callback function may be specified. The callback function is called as soon as a valid signature is found. 
-	It is passed two arguments: the offset at which the match was found, and a list of results dictionaries (one dictionary 
-	per result found at that offset):
+		binwalk.Modules().execute('firmware1.bin', 'firmware2.bin', **{'signature' : True})
 		
-		from binwalk import Binwalk
+		binwalk.Modules().execute(*['firmware1.bin', 'firmware2.bin'], signature=True)
 		
-		def my_callback(offset, results):
-			print "Found %d results at offset %d:" % (len(results), offset)
-			for result in results:
-				print " %s" % result['description']
+		binwalk.Modules().execute(*['--signature', 'firmware1.bin', 'firmware2.bin',])
 
-		with Binwalk() as bw:
-			bw.scan('firmware.bin', callback=my_callback)
+		binwalk.Modules().execute('--signature', 'firmware1.bin', 'firmware2.bin')
 
+	All args and kwargs keys/values correspond to binwalk's command line options. Either args or kwargs, or a combination
+	of the two may be used, with the following caveats:
 
-ADDING FILTERS
+		o All command line switches passed via args must be preceeded by hyphens (not required for kwargs)
+		o All file names must be passed via args, not kwargs
 
-	Include and exclude filters may be specified which operate identically to the --include, and --exclude binwalk
-	command line options:
+ACCESSING SCAN RESULTS
 
-		from binwalk import Binwalk
+	binwalk.core.module.Modules.execute returns a list of objects. Each object corresponds to a module that was run.
+	For example, if you specified --signature and --entropy, then both the Signature and Entropy modules would be executed
+	and you would be returned a list of two objects.
 
-		binwalk = Binwalk()
+	The two attributes of interest for each object are the 'results' and 'errors' objects. Each is a list of binwalk.core.module.Result
+	or binwalk.core.module.Error objects respectively. Each Result or Error object may contain custom attributes set by each module, 
+	but are guarunteed to have at least the following attributes (though modules are not required to populate all attributes):
 
-		# Exclusively filters out all signatures except those containing the string 'filesystem' (same as --include)
-		binwalk.filter.include('filesystem')
+		o offset      - The file offset of the result/error (usually unused for errors).
+		o description - The result/error description, as displayed to the user.
+		o module      - Name of the module that generated the result/error.
+		o file        - The file object of the scanned file.
+		o valid       - Set to True if the result if value, False if invalid (usually unused for errors).
+		o display     - Set to True to display the result to the user, False to hide it (usually unused for errors).
+		o extract     - Set to True to flag this result for extraction (not used for errors).
+		o plot        - Set to Flase to exclude this result from entropy plots (not used for errors).
 
-		# Excludes all results that contain the string 'jffs2' (same as --exclude)
-		binwalk.filter.exclude('jffs2')
+	binwalk.core.module.Error has the additional guarunteed attribute:
 
-		binwalk.scan('firmware')
+		o exception   - Contains the Python execption object if the encountered error was an exception
 
+	Thus, scan results and errors can be programatically accessed rather easily:
 
-EXTRACTING FILES
+		for module in binwalk.Modules().execute('firmware1.bin', 'firmware2.bin', signature=True):
+			print ("%s Results:" % module.name)
+			for result in module.results:
+				print ("\t%s    0x%.8X    %s" % (result.file.name, result.offset, result.description))
 
-	Extract rules may be specified which operate identically to the --dd and --extract binwalk command line options.
-	Extraction is automatically enabled when one or more extraction rules are specified.
+MODULE EXCEPTIONS
 
-	To add a custom extract rule, or a list of extract rules (such as with the --dd option):
+	The only expected exception that should be raised by binwalk.Modules is that of binwalk.ModuleException. This exception
+	is thrown only if a required module encountered a fatal error (e.g., one of the specified target files could not be opened):
 
-		from binwalk import Binwalk
-
-		binwalk = Binwalk()
-
-		# Extract results containing the string 'gzip' with a file extension of 'gz' and run the gunzip command
-		binwalk.extractor.add_rule('gzip:gz:gunzip %e')
-
-		# Extract 'lzma' and 'filesystem' results
-		binwalk.extractor.add_rule(['lzma:7z', 'filesystem:fs'])
-
-		binwalk.scan('firmware')
-
-	To load the default extraction rules from the extract.conf file (such as with the -e command line option):
-	
-		from binwalk import Binwalk
-		
-		binwalk = Binwalk()
-		binwalk.extractor.load_defaults()
-		binwalk.scan('firmware.bin')
-
-	To enabled delayed file extraction (such as with the --delay option):
-
-		from binwalk import Binwalk
-		
-		binwalk = Binwalk()
-		binwalk.extractor.enable_delayed_extract(True)
-		binwalk.scan('firmware.bin')
-
-	To enable file cleanup after extraction (such as with the --rm option):
-
-		from binwalk import Binwalk
-		
-		binwalk = Binwalk()
-		binwalk.extractor.cleanup_extracted_files(True)
-		binwalk.scan('firmware.bin')
+		try:
+			binwalk.Modules().execute()
+		except binwalk.ModuleException as e:
+			print ("Critical failure:", e)
 

INSTALL

 BEFORE YOU START
 ----------------------------------
 
-Although binwalk supports Python 3, Python 2.7 is recommended.
+Binwalk supports Python 2.7 - 3.x.
 
 The following installation procedures assume that you are installing binwalk to be run using Python 2.7.
 If you want to use binwalk in Python 3, some package names and installation procedures may differ slightly.
 
-You will also need to have a C compiler installed to build some of the supporting libraries.
+You will also need to have a C compiler installed to build the supporting C libraries.
 
 
 
@@ -43,7 +43,7 @@ Next, you'll need to install the dependencies for pyqtgraph (you may also need t
 	
 	$ sudo apt-get install python-opengl python-qt4 python-qt4-gl python-numpy python-scipy
 
-Most distros don't have pyqtgraph in their repositories, so you'll need to build it from source:
+Most distros don't have pyqtgraph in their default repositories, so it's best to build it from source:
 
 	$ wget http://www.pyqtgraph.org/downloads/pyqtgraph-0.9.8.tar.gz
 	$ tar -zxvf pyqtgraph-0.9.8.tar.gz
@@ -59,6 +59,7 @@ Binwalk can be installed using the included setup.py installer in the src/ direc
 	$ sudo python ./setup.py install
 
 The installer will check for core dependencies and warn you if any are missing or not compatible.
+Note that setup.py also builds and installs the included C libraries.
 
 
 

src/binwalk/core/module.py

@@ -326,7 +326,7 @@ class Module(object):
 		exception_header_width = 100
 
 		e = Error(**kwargs)
-		e.module = self
+		e.module = self.__class__.__name__
 
 		self.errors.append(e)