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 The following is an example of the simplest scan, and is equivalent to running binwalk on the command line with no additional arguments: import pprint from binwalk import Binwalk with Binwalk() as bw: pprint.PrettyPrinter().pprint(bw.scan('firmware.bin')) The scan() method will return a list of results, and may also be passed a list of files: from binwalk import Binwalk 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'] 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): 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'] with Binwalk() as bw: bw.scan('firmware.bin', callback=my_callback) ADDING FILTERS Include and exclude filters may be specified which operate identically to the --include, and --exclude binwalk command line options: from binwalk import Binwalk binwalk = Binwalk() # Exclusively filters out all signatures except those containing the string 'filesystem' (same as --include) 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. Extraction is automatically enabled when one or more extraction rules are specified. 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 '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')