Creating Custom Plugins

Binwalk Plugins

Users may customize and extend binwalk through Python plugins. Plugins are often useful when validating complex data structures which may be difficult or impossible to create full signatures for, or when binwalk's actions need to be modified on a conditional basis.

Writing a Plugin

Binwalk plugins are easiest to understand by looking at an example plugin:

import binwalk.core.plugin

# Each plugin must be subclassed from binwalk.core.plugin.Plugin
class MyPlugin(binwalk.core.plugin.Plugin):
    '''
    A sample binwalk plugin module.
    '''

    # A list of module names that this plugin should be enabled for (see self.module.name).
    # If not specified, the plugin will be enabled for all modules.
    MODULES = ['Signature']

    # The init method is invoked once, during module initialization. 
    # At this point the module has been initialized, so plugins have access to the self.module object.
    # The self.module object is the currently running module instance; data from it can be read, but
    # should not be modified.
    def init(self):
        print ("MyPlugin initialized for module '%s'!" % self.module.name)

    # The pre_scan method is invoked once, after the module has been loaded, but before any files
    # have been processed.
    def pre_scan(self):
        print ("Module '%s' is about to be run!" % self.module.name)

    # The new_file method is invoked once per file, after the file has been opened, but before
    # the module has processed the file. It is passed an instance of binwalk.core.common.BlockFile.
    def new_file(self, fp):
        print ("Module '%s' is about to scan file '%s'!" % (self.module.name, fp.path))

    # The scan method is invoked each time the module registers a result during the file scan.
    # The plugin has full read/write access to the result data.
    def scan(self, result):
        if result.valid:
            print ("Module '%s' has reported a valid result:" % self.module.name)
            print ("\tFile: %s" % result.file.name)
            print ("\tOffset: 0x%X" % result.offset)
            print ("\tDescription: %s" % result.description)

    # The post_scan method is invoked once, after the module has finished scanning a file
    def post_scan(self):
        print ("Module '%s' has finished!" % self.module.name)

Note that not all methods (init, pre_scan, new_file, scan, post_scan) must be declared; only use them as necessary.

Each plugin will be instantiated once per module, thus you should indicate which module(s) your plugin is intended for via the self.MODULES list. Valid module names for use in self.MODULES are:

Name	Description
Signature	Scans input files for known code and data signatures
Entropy	Calculates input file entropy and generates entropy graphs
Disasm	Analyzes files for executable code using the Capstone disassembler engine
RawCompression	Identifies raw compression streams in the input files
Extractor	Performs data carving and extraction

Plugin Activation

Activating a plugin is as simple as dropping it in binwalk's plugin directory $HOME/.config/binwalk/plugins/. The plugin will then be loaded on all subsequent binwalk scans.