attify/firmware-analysis-toolkitFirmware security research platform combining binary analysis, taint tracing, and emulation across IoT, edge AI, mobile devices, and robotics.
# FAT — Firmware Analysis Toolkit [](https://github.com/attify/firmware-analysis-toolkit/releases/latest) [Download the latest release](https://github.com/attify/firmware-analysis-toolkit/releases/latest) · [Changelog](https://github.com/attify/firmware-analysis-toolkit/blob/master/CHANGELOG.md) · [Installation](https://github.com/attify/firmware-analysis-toolkit/blob/master/INSTALL.md) **Firmware Analysis Toolkit** is a security research toolkit for investigating firmware security for IoT, Physical AI, Mobile Devices & Robotics. It is primarily built for the ["Offensive IoT Exploitation"](https://www.attify.com/training) training conducted by [Attify](https://attify.com). It has been built based on actual hands-on field experience of what really matters when it comes to real firmware security investigations that matter. FAT's goal is not just to build an exceptional world-class cutting-edge toolkit for Firmware Security Research, but also forge professionals and practitioners who operate at their peak, where the tool becomes a cognitive superpower if used in certain ways, while being easy enough to be used by those who are new to the field. Some of the features include classifying unknown firmware, extracts filesystems, maps trust-relevant code, traces taint, and coordinating QEMU emulation. ## What FAT can analyze - **Unknown blobs and directories:** containers, compressed members, high-entropy regions, MCU signals, and candidate firmware files - **Firmware images:** headers, update envelopes, partitions, bootloaders, and image-to-image differences - **BMC flash images:** FIT hash/signature metadata, OpenBMC/MegaRAC markers, CRC-valid U-Boot environments, native JFFS2 recovery, and explicit full-flash/vendor-kernel emulation profiles - **Extracted Linux filesystems:** inventory, startup intent, trust-bearing binaries, crypto material, and string evidence - **ELF binaries:** imports, exports, handler tables, stripped-code sinks, decompilation, and source-to-sink taint - **Bare-metal and MCU images:** vector tables, memory maps, peripheral hints, flash-write authority, and boot handoff evidence - **Edge AI artifacts:** MAGIK/JZDL, TFLite, ONNX, and Qualcomm DLC files plus visible inference runtimes - **Android applications:** APK inventory, discovery leads, locality, capability chains, and handoff boundaries - **Source repositories:** invariant queries, patch guidance, and nearby variant searches ## Quick start Download a binary bundle from [Releases](https://github.com/attify/firmware-analysis-toolkit/releases/latest), or build from source with Rust 1.91 or newer: ```bash git clone --branch v2.0.1 --depth 1 https://github.com/attify/firmware-analysis-toolkit.git cd firmware-analysis-toolkit cargo build --release --locked cargo install --path crates/fat_cli --locked python3 scripts/build-runtime-data-bundle.py --output ./dist/fat-data.zip fat data install --archive ./dist/fat-data.zip fat doctor ``` On Arch Linux or Omarchy, start with the [Arch installation steps](https://github.com/attify/firmware-analysis-toolkit/blob/master/INSTALL.md#arch-linux-and-omarchy) for prerequisite packages and optional tools. One-Shot Installer for supported hosts: ```bash ./scripts/install.sh --install-system-deps ``` See [INSTALL.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/INSTALL.md) for installer options and optional tools. For features listed under [Unreleased](https://github.com/attify/firmware-analysis-toolkit/blob/master/CHANGELOG.md#unreleased), use `--branch master` in the clone command above. BMC inspection and native JFFS2 recovery were added after `v2.0.1`. ## Quick Command Ref. - Help : `fat -h` - Identify a firmware: `fat $firmware` or `fat identify --file $firmware` - Inspect BMC flash: `fat inspect bmc --file $firmware` - New Project : `fat new $firmware` - Extract file system : `fat extract $firmware` - Analyze : `fat analyze $firmware` - Emulation : `fat emulate --project $firmware` ### First contact with an unknown file ```bash fat ./firmware.bin fat inspect update --file ./firmware.bin --rootfs ./rootfs --reference ./older.bin ``` `fat ./firmware.bin` is shorthand for `fat identify --file ./firmware.bin`. It gives a compact overview of the file's identity and structure. Add `--details` for supporting tables. For raw MCU images, inspect the mapping, startup, interrupts, and hardware: ```bash fat inspect mcu --file ./firmware.bin fat inspect mcu --file ./firmware.bin --details ``` For BMC flash images, inspect layout, FIT authentication metadata, and stored environments: ```bash fat inspect bmc --file ./flash.mtd fat inspect bmc --file ./flash.mtd --details ``` Both inspection workflows support `--json` for the full structured analysis report. BMC inspection also supports `--sarif --fail-on-warning` for CI. FIT signatures are reported as stored metadata; cryptographic validity and hardware boot enforcement are not tested. Run supported BMC services with `fat emulate --project <project> --pack bmc-romulus` or the explicit ASUS vendor-kernel profile. List profiles with `fat rehost profiles list`; see [BMC emulation](https://github.com/attify/firmware-analysis-toolkit/blob/master/docs/bmc-emulation.md) for input hashes, adaptations, Redfish checks and debugging. For disposable lab accounts, `fat debug redfish-session` checks ReadOnly role enforcement and session revocation with an administrator positive control. `fat debug process` attaches to a guest daemon through SSH and records its identity and cleanup. See [BMC session and process debugging](https://github.com/attify/firmware-analysis-toolkit/blob/master/docs/bmc-session-debugging.md) for setup and the Romulus/ASUS results. Native extraction reconstructs JFFS2 files before inspecting nested compressed content. See [Inspecting BMC firmware](https://github.com/attify/firmware-analysis-toolkit/blob/master/docs/bmc-inspection.md) for the extraction workflow, case-sensitive storage requirements, SARIF output, and environment overrides. ### Image to Runtime The pipeline from Quick start, end to end: ```bash fat new ./firmware.bin fat extract .fat-projects/firmware fat analyze .fat-projects/firmware fat preflight .fat-projects/firmware fat emulate --project .fat-projects/firmware ``` ### Binary triage and data flow ```bash fat r2-triage --file ./usr/sbin/httpd --json fat taint --file ./www/cgi-bin/diag.cgi --summary fat taint-query --file ./www/cgi-bin/diag.cgi fat taint-cross --rootfs ./rootfs fat taint-cross --rootfs ./rootfs --source-profile ./my-target-models.yaml --state-profile ./my-target-state.yaml ``` ### Shell script data flow ```bash fat taint --lang shell --file ./app/init/wifi.sh --summary fat taint --lang shell --rootfs ./extracted-rootfs --json fat taint --lang shell --rootfs ./extracted-rootfs --source-profile ./my-target-shell.yaml --severity high ``` ### Stripped binaries Find sinks statically, then prepare runtime hooks for the same addresses: ```bash fat r2-triage --file ./usr/sbin/httpd --json fat sink-discovery --file ./usr/sbin/httpd --json > sinks.json fat handler-table --file ./usr/sbin/httpd --json > handlers.json fat taint --file ./usr/sbin/httpd --sink-candidates sinks.json --json > taint.json fat instrument-hooks --from-sinks sinks.json --output hooks.yaml fat emulate --project .fat-projects/firmware --instrument hooks.yaml ``` ### Filesystem-wide evidence sweep ```bash fat tree --rootfs ./rootfs --profile inventory --summary --json fat search --rootfs ./rootfs --profile credentials -I --context 2 fat startup-map --rootfs ./rootfs --profile cloud-tls fat crypto-census --rootfs ./rootfs fat trust-map --rootfs ./rootfs ``` ### Source-backed invariant query ```bash fat invariant query \ --fixture tests/fixtures/query/source/invariant-permission \ --rule 'Every privileged override method must call enforcePermission()' fat patch check --help fat verify --help ``` ## Security - Emulation executes untrusted vendor code. - Review [SECURITY.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/SECURITY.md) before processing untrusted images or exposing an emulated service to a network. - It is your responsibility to have authorisation for the targets you work on. ## Detailed Guides | Document | What is in it? | | --- | --- | | [INSTALL.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/INSTALL.md) | External tools and optional component setup | | [docs/commands.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/docs/commands.md) | Full command reference, grouped by task | | [docs/bmc-emulation.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/docs/bmc-emulation.md) | BMC boot profiles, Redfish readiness, debug endpoints, and new-image support | | [docs/bmc-inspection.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/docs/bmc-inspection.md) | Offline BMC inspection, JFFS2 extraction, output formats, and limits | | [docs/capabilities.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/docs/capabilities.md) | Graph export, string search, crypto, Edge AI, startup intent, rehosting packs | | [docs/epistemics.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/docs/epistemics.md) | How to read FAT output: what results do and do not prove | | [docs/architecture.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/docs/architecture.md) | Workspace crates and extension points | | [DEVELOPMENT.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/DEVELOPMENT.md) | Build and test workflow | | [CONTRIBUTING.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/CONTRIBUTING.md) | Setup, PR checklist, and contribution guide | | [RELEASING.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/RELEASING.md) | Version naming and the maintainer release workflow | ## Citation If you use FAT in research, publications, or technical reports, please cite it using the **Cite this repository** option on GitHub. Include the FAT version or commit used so readers can identify the implementation behind your results. See [CITATION.cff](https://github.com/attify/firmware-analysis-toolkit/blob/master/CITATION.cff) for citation metadata. ## Maintainers FAT was authored by [adi0x90](https://github.com/adi0x90), who is also its current maintainer and principal contributor. The project is maintained under [Attify](https://www.attify.com/). ## License FAT 2.0 is source available under [FSL-1.1-ALv2](https://github.com/attify/firmware-analysis-toolkit/blob/master/LICENSE). See [LICENSING.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/LICENSING.md) and [THIRD_PARTY_NOTICES.md](https://github.com/attify/firmware-analysis-toolkit/blob/master/THIRD_PARTY_NOTICES.md) for more details.
