Frequently Asked Questions

devttys0 edited this page May 3, 2015 · 5 revisions

Why do I keep getting import errors/warnings?

This most commonly occurs when installing a newer version of binwalk over an older version with an incompatible API (e.g., pre v2.0). To avoid such issues, first uninstall any existing binwalk installations before installing the latest version:

$ sudo python setup.py uninstall

How do I plot entropy graphs without an X server?

The pyqtgraph module that binwalk uses to plot graphs requires an X server; this can be problematic if running binwalk in an automated fashion, particularly on a headless server.

The X virtual framebuffer (xvfb) can be used to graph entropy plots without running a graphical display; the xvfb-run wrapper script provided by most Linux distros is particularly handy:

$ xvfb-run binwalk --entropy --save firmware.bin

Why does binwalk's signature scan report false positive results?

Binwalk does a pretty good job of analyzing potential file signatures and filtering out obvious false positives, but it is not perfect.

Some signatures are more difficult to validate than others, and binwalk will always err on the side of caution; that is, it would rather report a potential false positive so that you can then independently validate or invalidate it, rather than not report a questionably valid result.

Binwalk found an XYZ file, but the XYZ utility can't process it.

This is commonly a result of a false positive result, but not necessarily.

Utilities for extracting or reading certain file types may be improperly implemented or simply don't support some features of the file type; just because your utility can't handle the file does not necessarily mean that it is a false positive.

For example, Zip files found in many firmware images won't extract properly with normal unzip utilities (they often report that the Zip file is missing an end of central directory structure). Java's jar utility however, will extract these files just fine.

Exercising some common sense can usually help determine if binwalk or your utilities are to blame:

  • Did binwalk report a file size? If so, is it a reasonable size, or does it seem too large or too small?
  • Did binwalk report any version information for the file? If so, is it a valid version number for the XYZ file type?
  • Did binwalk report a file name or other string data from the file? If so, are the strings readable or jibberish?

If the additional data provided by binwalk points to it being a valid file, you might want to check your utilities.

Binwalk doesn't recognize XYZ file type.

First, you can check the magic/binwalk file to see if binwalk has a signature for the XYZ file type. If not, you may write your own, or submit the file type for inclusion into binwalk (please provide as much information as possible regarding the file type, as well as a sample file if possible).

If binwalk has a signature for the XYZ file type and that signature is included in the scan, is it being flagged as invalid? Run binwalk with the -I option to show all invalid results:

$ binwalk -I firmware.bin

If XYZ file type is supported and is either not detected, or incorrectly being flagged as invalid, please submit the issue and include a copy of the file in question (or a link to download the file).

Binwalk doesn't recognize XYZ file if only scanning the first few bytes.

This is true of certain files, such as tarballs, whose signature is located at some non-zero offset. The magic bytes for tarball files, for example, are located 257 bytes into the actual tarball file, so you must scan at least the first 257 bytes of a tarball file before binwalk can properly identify it.

Does binwalk work on Windows?

Native Windows support is currently under development. Core functionality has been tested successfully on Windows 7 using the latest code from the master branch .