binaryanalysis-ng: unpacking firmware images and labelling what is inside

An unpacker that feeds separate analysis programs

BANG, short for Binary Analysis Next Generation, is a framework for processing binary files such as firmware. The architecture has two halves, and the split is the most important thing to understand before you use it.

The first half is an unpacker that recursively unpacks and classifies or labels files. The second half is a set of separate analysis programs that work on the results of the unpacker. That division is what makes the framework useful at scale. Unpacking a firmware image produces a tree of extracted files with labels, and the analysis programs then interrogate that tree for the questions you care about.

The README names the intended uses directly: provenance detection, meaning what is inside this file, and security scans, meaning whether there are known security risks associated with it. Those two lines are a good description of who the tool is for. Someone who has acquired a router image, a camera firmware blob or an unknown binary and needs to know what they are actually holding, and needs to know whether it contains something they should worry about.

The project is written in Python, licensed GPL-3.0, is not archived, and the last push was on 2026-10-16. There are no GitHub releases, and the repository carries several README files, one for the general project, one for the analysis programs and one for the Nix setup, which tells you the documentation is split along the same lines as the code.

Nix as the intended way to get a working environment

The dependency story is the first practical obstacle, and the project is blunt about its recommendation. The recommended way to use BANG is Nix, and there are four separate shell environments for four different jobs: nix-shell to load all the dependencies for the unpacker, nix-shell maintenance.nix for the maintenance scripts, nix-shell analysis.nix for the analysis scripts, and nix-shell scraper.nix for the firmware scraper. The README states that nix will make sure that everything is downloaded and installed to run BANG.

That split mirrors the architecture. If you only want to unpack, you only need the first environment. If you want to run the analysis programs against an unpacked tree, you need the second. Assuming both are always needed is how people end up with an hour of setup for a task that needed five minutes.

The non-Nix path exists and the README calls it vastly incomplete. The list includes a recent Linux distribution, Fedora 36 or higher or equivalent, Python 3.10.x or higher, and then a long tail of individual packages: pillow for the image formats, GNU binutils for ar, squashfs-tools for unsquashfs, cabextract, 7z, e2tools for e2ls and e2cp, zstd, python-lz4, qemu-img for VMDK files, psycopg2, python-snappy, python-tlsh, dockerfile-parse, openssl, rzip, lzop, defusedxml, icalendar, pyyaml, ncompress, util-linux for fsck.cramfs, lz4 for lz4c, and bzip3, among others. The README points at shell.nix, maintenance.nix and analysis.nix for the full list.

Two tools have to be installed by hand regardless. The Kaitai Struct compiler, described in doc/kaitai-struct.md, and sasquatch from the onekey-sec repository, which handles the vendor specific exotic squashfs variants.

The distribution support statement is careful in a way worth copying. Fedora 35 and earlier and Ubuntu 16.04 and lower are verified unsupported, the latter because the Python version is too old. And the README adds that this does not mean newer Ubuntu versions are supported, they just have not been tested.

A hundred and fourteen formats, each with a caveat

The supported file type list is the substance of the project, and its formatting is unusual in a useful way: almost every entry carries a parenthetical note about what does not work.

The list runs past a hundred entries and covers the formats that turn up in firmware and packaged software. There are the archives, gzip, LZMA, XZ, tar, ZIP with store, deflate and bzip2, and the note that lzma in ZIP still needs more testing, XAR with no compression, gzip, bzip2, XZ and LZMA, 7z requiring external tools, and Microsoft Cabinet archives needing cabextract. There are the filesystems, ISO9660 with RockRidge and zisofs, ext2, 3 and 4 with missing symbolic link support, squashfs with vendor specific exotic variants via sasquatch, cramfs version 2 only, romfs, YAFFS2 including inband tags, FAT16 with 8.3 file names, UBI with fastmap not supported, Minix V1, PFS and bFLT.

There are the Android formats, Android sparse data image with regular and Brotli compression, Android backup files, Android resource files with the note that it is the table type but possibly not all types, the Android bootloader image for Qualcomm Snapdragon, the Android bootloader image also with a Little Kernel based variant, the Android bootloader image for Huawei devices, Android tzdata and Android verified boot image, and Android Dex and Odex with the note that OAT is not supported, just carving.

There are the firmware and boot formats, U-Boot image, Ambarella firmware files, Ambarella romfs, Broadcom TRX, coreboot images, and nb0 Android updates.

And there are the ones where the limitation is about the analysis rather than the extraction. PDF gets simple verification, with no object streams and no incremental updates at the end of the file. Photoshop PSD covers raw bytes and RLE encoding only. Java class file and Java key store version 2 only. FLV is uncompressed, zlib or LZMA. XG3D and ACDB are labelled only. Microsoft DirectDraw Surface gets structure checks and very limited sanity checking. Git index files, pcap and pcapng, and serialized Java are carving and structural checks. Vim swap files are whole file only. Intel Hex and Motorola SREC are text files only.

Reading those caveats as a set is how you decide whether BANG fits your input. A tool that transparently tells you which of its hundred formats are partial is more useful than one that silently mis-parses.

The Docker path, and the hardware assumption underneath it

There is a container option, and the README labels it with a warning that is more useful than a green badge would be: the Docker container section is headed recently untested, assume broken.

The commands are short:

docker image build -t bang .
docker container run --rm -it bang

Or, from the src directory, the Makefile target:

make dockerbuild

Given the label, treat the container as a starting point rather than a supported deployment. If you rely on it, build it and run it before you point your pipeline at it, because the failure mode of an untested container is a broken build step rather than a helpful error.

The other constraint is architectural and permanent. It is assumed that BANG is run on little endian hardware, such as x86 or x86-64, and that assumption reaches deep into the format list, which repeatedly qualifies entries with little endian, such as terminfo, which supports regular and extended storage format but not the extended number format, CPIO in various flavours, little endian, and pcapng carving with structural checks and little endian only.

That is a reasonable trade for a firmware tool. Firmware images are overwhelmingly produced for little endian targets, and a framework that only handles one endianness natively covers the real corpus. But it does mean BANG is not the tool for big endian embedded images, and the caveats in the format list are the ones you have to read before you rely on a result.

What you get for the work of setting it up

The value proposition is the combination of recursion, labelling and separation, and it is worth being concrete about each part.

Recursion is what makes the unpacker useful on firmware. A firmware image is usually a container of containers, with a filesystem holding compressed blobs holding further files. A tool that unpacks one level and stops gives you a directory of compressed files. A recursive unpacker gives you the whole tree, which is where the interesting artifacts live.

Labelling is what makes the output analysable. The unpacker classifies and labels what it finds, so the extracted tree is not just a pile of files with meaningless names but a labelled set that an analysis program can query. The analysis programs then work on those results, and the README keeps them as separate programs for that reason.

Separation means you can use one part without the other, and the four Nix shell environments are the practical expression of that. A provenance question might need only the unpacker. A security scan against a large corpus of images is where the analysis programs earn their keep, and where you want the unpacking stage to be scripted and repeatable across many images.

The repository layout reflects the same split, with src/ for the code, a separate maintenance/ directory, a test/ directory, a util/ directory, a performance-test/ directory, a doc/ directory, and a scraper.nix alongside the analysis.nix, maintenance.nix and shell.nix. The pyproject.toml is minimal, a setuptools build with a pytest configuration pointing at the test directory, and setup.py contains nothing but a call to setuptools.setup(), which means the packaging is thin and the dependency management lives entirely in Nix.

For a security researcher, this is the shape you want: a tool you can script over a corpus, whose per-format limitations are written down next to the format list rather than discovered by trial.

Editorial conclusion

Adopt binaryanalysis-ng if you routinely take apart firmware images or opaque binary blobs and want a recursive unpacker that labels what it finds, with the analysis stage kept separate from the unpacking stage. Do not adopt it for single well-known file types, where a standard unpacker or a library call is cheaper, and do not rely on the Docker image without testing it, because the README marks that path as recently untested. Verify first that the format you care about is in the supported list with its stated caveats, that little endian hardware is what you are running on, and that the Kaitai Struct compiler and sasquatch are installed if your formats need them.

Frequently asked questions

Official sources

1. armijnhemel/binaryanalysis-ng on GitHub
2. Issues
3. License: GPL-3.0
4. README