DESCRIPTION

	The binwalk python module can be used by any python script to programatically perform binwalk scans and 
	obtain the results of those scans. 

	The classes, methods and objects in the binwalk modules are documented via pydoc, including examples, 
	so those interested in using the binwalk module are encouraged to look there. However, several common usage 
	examples are provided here to help jump-start development efforts.


BASIC SCAN

	This is the simplest scan, and is equivalent to running binwalk on the command line with no additional arguments.
	Note the use of the cleanup() method, which will ensure all temporary files generated by binwalk are cleaned up:

		from binwalk import Binwalk

		binwalk = Binwalk()
		results = binwalk.scan('firmware.bin')
		binwalk.cleanup()

	The scan() method will return a list of tuples, one tuple for each offset in the target file where a matching
	signature was found. The first element of each tuple is the offset into the file at which the match was found. 
	The second tuple is a list of dictionaries (depending on the binwalk options, there may be more than one match 
	for a given offset); each dictionary describes a matching signature:

		results = [
				(0, [{description : "LZMA compressed data..."}]),
				(112, [{description : "gzip compressed data..."}]),
		]

	A callback function may also be specified. The callback function is called as soon as a match is identified. It
	is passed two arguments: the offset at which the match was found, and a list of dictionaries as described above:

		from binwalk import Binwalk

		def my_callback(offset, results):
			print "Found %d results at offset %d:" % (len(results), offset)
			for result in results:
				print " %s" % result['description']

		binwalk = Binwalk(callback=my_callback)
		binwalk.scan('firmware.bin')
		binwalk.cleanup()


ADDING FILTERS

	Include and exclude filters may be specified which operate identically to the --include, --exclude and --search
	binwalk command line options:

		from binwalk import Binwalk
		
		binwalk = Binwalk()
		
		# Adds a normally excluded signature to the existing list of signatures (same as --include)
		binwalk.filter.include('minix', exclusive=False)

		# Exclusively filters out all signatures except those containing the string 'filesystem' (same as --search)
		binwalk.filter.include('filesystem')

		# Excludes all results that contain the string 'jffs2' (same as --exclude)
		binwalk.filter.exclude('jffs2')

		binwalk.scan('firmware')


EXTRACTING FILES

	Extract rules may be specified which operate identically to the --dd and --extract binwalk command line options.
	
	To add a custom extract rule, or a list of extract rules (such as with the --dd option):

		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 'gzip' and 'filesystem' results
		binwalk.extractor.add_rule(['gzip:gz', 'filesystem:fs'])

		binwalk.scan('firmware')

	To load the default extraction rules from the extract.conf file (such as with the --extract 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')

