Creating Custom Signatures

Adding Signatures to Binwalk

Custom signatures can be added to binwalk either through a custom signature file specified on the command line via the --magic option, or by adding them to your $HOME/.config/binwalk/magic directory (or $HOME/.binwalk/magic if the previous location doesn't work).

Creating a Simple Signature

Binwalk's signature file format is based on the libmagic file format and is mostly compatible with signatures created for the UNIX file utility. This makes creating, customizing and sharing signatures very easy.

To understand the basic format of a signature, let's create a new signature for a fictitious firmware header. The header structure is:

struct header
{
   char magic[4];        //Magic bytes are: 'SIG0'
   char description[12];
   int32_t header_size;
   int32_t image_size;
   int32_t creation_date;
};

The resulting magic signature for this header format looks like:

# SIG0 firmware signature
0    string    SIG0     SIG0 firmware header,
>4   string    x        description: "%s",
>16  lelong    x        header size: %d,
>20  lelong    x        size: %d,
>24  ledate    x        date: %s

There are four columns for each line:

• The first column is the data offset.
• The second column is the data type.
• The third column is the expected data (x is a wildcard matching anything).
• The fourth column is the optional text and data formatting to display.

The first line of any signature contains the actual "magic bytes" which uniquely identify that signature (the string SIG0 in the above example).

All comments begin with the pound sign #.

False Positive Detection

Each signature is responsible for providing false positive detection via the invalid tag. For example, it wouldn't make sense for our fictitious firmware header to have a size of less than 1 byte, so if this is the case we can mark the signature result as invalid:

# SIG0 firmware signature
0    string    SIG0     SIG0 firmware header,
>4   string    x        description: "%s",
>16  lelong    x        header size: %d,
>20  lelong    <1       {invalid}
>20  lelong    x        size: %d,
>24  ledate    x        date: %s

Advanced Signatures

Binwalk supports most libmagic signature features, as well as some custom features of its own. See the Signature File Format page for more details.