FirmWire emulates the baseband instead of the phone

The target is the modem, not the handset

FirmWire is described as a full system baseband firmware analysis platform that supports Samsung and MediaTek, and it enables fuzzing, root cause analysis and debugging of baseband firmware images.

The word baseband is the whole scope of the project. The baseband is the part of a phone that handles the radio, and it is where the firmware lives that talks to the network. It is a very different target from the application processor, and it is a much harder one to work with, because the baseband is normally a closed, signed, isolated piece of hardware that a researcher cannot simply run.

Emulation is the answer, and that is what makes this project interesting. Instead of extracting a function and testing it in isolation, you run the firmware as a system, which means the code executes, the timers run, the interrupts are delivered, and the firmware talks to a modelled environment. From that position you can observe behaviour, drive inputs, and let a fuzzer explore the code paths that matter.

The audience is baseband security researchers. The README frames the project as the result of a multi-year, cross university research effort and points to the NDSS 2022 paper for details, and it also says the project expects FirmWire to be used for commercial purposes such as private baseband vulnerability research and bug bounties, which tells you the maturity level the authors are aiming at rather than a research toy.

The repository topics list confirms the shape of the thing: baseband, emulation, fuzzing, introspection, qemu, mediatek and samsung. Emulation is the substrate, fuzzing is the method, and introspection is the way you see inside.

A lab image with PANDA, AFL and cross compilers baked in

The Dockerfile is the clearest statement of what this project actually needs, and it is a long one.

FROM ubuntu:20.04
LABEL "about"="FirmWire base img"

ARG DEBIAN_FRONTEND=noninteractive
ENV AFL_SKIP_CPUFREQ=1
ENV IS_DOCKER="1"

The base is Ubuntu 20.04, and the environment variables are a hint about the two things that are running inside it. AFL_SKIP_CPUFREQ exists because AFL wants to pin the CPU frequency, which is a problem inside a container, and IS_DOCKER tells the toolchain that it is running in a container.

The apt install list is enormous and deliberate. It includes the build essentials, bison and flex for compiling things that need to be built, clang and clang-tools, the ARM bare metal cross compiler gcc-arm-none-eabi, libtool, libpixman, wireshark-dev and gdb-multiarch for debugging, and qemu-utils. It then installs the MIPS cross compilers, gcc-9-mipsel-linux-gnu and gcc-9-multilib, and wires up mipsel-linux-gnu-gcc through update-alternatives. The comment in the file explains that Ubuntu cannot install the gcc-multilib metapackage with any cross compiler because of conflicts in /usr/include/asm, and points at the launchpad bug.

On top of that the image installs PANDA from a shallow clone of the FirmWire fork of the panda repository, checked out on main, configured with --disable-werror. The comment in the file says PANDA is installed with the dependencies for Shannon Panda, which is the Samsung side.

The practical reading is that a baseband laboratory needs a cross compilation environment for the embedded targets, a dynamic analysis engine for the firmware, and a fuzzing engine, and that none of those are things you can install with pip. Hence the image.

The Python dependencies map the feature set

The requirements file is short and organised by purpose, and the section comments are the documentation.

# Decompressing Shannon modem.bin containers
lz4
# Parsing injectable modules
pyelftools
# Downloading firmware
requests
# MTK required
filetype
rocksdb

That block alone tells you a lot. The Shannon modem.bin containers, the Samsung side of the house, are compressed with LZ4, so the platform can open a stock modem.bin. Injectable modules are ELF files, and pyelftools parses them. Firmware can be fetched over HTTP with requests. The filetype library identifies file types, and rocksdb is listed as required for MTK, which points at how the platform stores the state of an emulated device.

The rest of the file splits into three other groups. The orchestration section is avatar2, which is the platform that runs multiple emulation instances and connects them, and the interactive kernel mode section is a Jupyter stack, ipykernel and ipython with jupyter-client, jupyter-console and jupyter-core, plus ipython-genutils and jedi. That combination is the reason the tool has a notebook front end: you drive a baseband emulator from a Jupyter kernel and watch it execute.

The test dependencies are pytest and pytest-forked, and pytest-forked is worth a second look, because forking is how you run tests that each need their own emulator instance without them interfering with each other.

The last group is marked as required for pypanda, the Python interface to PANDA: cffi, protobuf and colorama. The Dockerfile explains why the newest cffi is installed from a source archive, with the note that pypanda needs the latest cffi, for reasons.

So the dependency set is a map of the feature set: container handling, module injection, firmware download, persistent device state, an interactive notebook front end, a test harness, and the dynamic analysis engine.

Fuzzing, debugging and introspection are three different jobs

The README lists the three uses, and they are worth separating because the platform supports them at different depths.

Fuzzing is the one the toolchain is built around. The AFL environment variable in the image, the AFL_SKIP_CPUFREQ setting, all point at coverage guided fuzzing of the firmware running inside the emulator. A fuzzer needs a fast, deterministic, restartable target, and a full system emulation of a baseband is exactly that, provided you can snapshot and restore the machine state. That is why the platform needs an introspection mechanism rather than only a debugger.

Debugging is the second use, and it is what the Jupyter interface with ipykernel and jupyter-console supports. Driving a baseband emulator from a notebook means you can single step, set breakpoints, watch memory and watch the emulated modem state change as the firmware runs, all in one place.

Root cause analysis is the third, and it is the one that pulls the whole project together. A crash in a baseband is a symptom that can have many causes, a timing bug, a corrupted message from the host, a missing configuration, a firmware assertion. A platform that can reproduce the crash on demand, in an environment you control, with the device state visible, turns a crash report into a diagnosis.

The topics list includes introspection, which is the term for reading the internal state of the emulated system rather than only its externally visible behaviour. For baseband work that is the difference between watching a log line and understanding why the line appeared.

The research pedigree is documented, with citations

This is a project where the academic output is part of the artefact, and the README handles it well.

FirmWire is the result of a multi-year, cross university research effort, with the paper linked from the README and the description of the work as transparent dynamic analysis for cellular baseband firmware. For reproducible research and experimental data, there is a separate NDSS 2022 repository, ndss22_experiments, which is where the artefacts behind the paper's results live.

The README also gives a BibTeX entry to cite if you use FirmWire in an academic paper:

@inproceedings{hernandez_firmwire_2022,
  title = {{FirmWire: Transparent Dynamic Analysis for Cellular Baseband Firmware}},
  shorttitle = {{FirmWire}},
  booktitle = {{ Symposium on Network and Distributed System Security (NDSS) }},
  author = {Hernandez, Grant and Muench, Marius and Maier, Dominik and Milburn, Alyssa and Park, Shinjo and Scharnowski, Tobias and Tucker, Tyler and Traynor, Patrick and Butler, Kevin R. B.},
  year = {2022}
}

For an engineer, the practical value of that separate experiments repository is that it is a set of known good configurations. When you set the platform up, you are recreating a research environment, and having the exact firmware and configuration the authors used is the difference between a working environment and an afternoon of debugging.

The documentation is hosted at firmwire.github.io/docs, with the README pointing at the installation page to get started, and the project home page is firmwire.github.io/docs/ as well. The repository has a CHANGELOG.md at the root and a _version.py file, plus the main firmwire.py entry point, a firmwire/ package, a modkit/ directory, a tests/ directory and a requirements.txt.

BSD-3 with a request that commercial users announce themselves

The licence section is the most unusual part of the README, and it is worth reading carefully.

FirmWire is licensed under BSD-3 and developed by Team FirmWire, which currently consists of the authors on the NDSS paper unless stated otherwise. The licence permits commercial use, and the team says they expect the tool to be used commercially, for private baseband vulnerability research and for bug bounties.

What they ask in return is disclosure. Users in those settings are asked to notify the team, publicly through issues or privately by email or Signal, about their use. The stated reason is curiosity, and a second request follows: if FirmWire or derived work helped you find a vulnerability, the team would like to know, in order to add it to the FirmWire trophy wall. The licence also notes that one or more members of the team may be willing to provide consulting services such as training, custom extensions to FirmWire and advice.

None of that is a licence condition. BSD-3 does not require notification, and the README is explicit that the licence permits the commercial use, so this is a request rather than a restriction. That distinction matters if you are making a compliance decision, and it is worth being precise about, because a request attached to a permissive licence is easy to misread as a clause.

The licence file is LICENSE.txt at the repository root, and the top level also has a .dockerignore and a .gitignore alongside the .github/ directory.

On maintenance, the releases are v1.1.0 on 2023-08-16 and v1.0 on 2022-03-11, and the last push to the repository was on 2026-08-20. The repository is not archived, so work continues on the main branch, but the tagged release line is old, and a platform that depends on a specific PANDA fork and a set of cross compilers is sensitive to that kind of drift.

Editorial conclusion

Adopt FirmWire if you are doing baseband firmware research and you want a full system emulation environment for Samsung or MediaTek images, with introspection, fuzzing and debugging rather than static analysis alone, and if you can afford the container image and the host resources it needs. Do not adopt it for a quick look at a firmware image, since the setup is a laboratory rather than a tool, and do not expect it to cover every vendor, since the README names Samsung and MediaTek only. Before you start, read the installation documentation at firmwire.github.io/docs, expect to build the image with the cross compilers and PANDA in it, and note that the project asks commercial users, including bug bounty work, to tell the team how they are using it.

Frequently asked questions

Official sources

1. FirmWire/FirmWire on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases