FAT — Firmware Analysis Toolkit

Download the latest release · Changelog · Installation

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" training conducted by Attify.

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, or build from source with Rust 1.91 or newer:

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 for prerequisite packages and optional tools.

One-Shot Installer for supported hosts:

./scripts/install.sh --install-system-deps

See INSTALL.md for installer options and optional tools.

For features listed under 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

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:

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:

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 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 for setup and the Romulus/ASUS results.

Native extraction reconstructs JFFS2 files before inspecting nested compressed content. See Inspecting BMC firmware for the extraction workflow, case-sensitive storage requirements, SARIF output, and environment overrides.

Image to Runtime

The pipeline from Quick start, end to end:

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

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

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:

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

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

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 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	External tools and optional component setup
docs/commands.md	Full command reference, grouped by task
docs/bmc-emulation.md	BMC boot profiles, Redfish readiness, debug endpoints, and new-image support
docs/bmc-inspection.md	Offline BMC inspection, JFFS2 extraction, output formats, and limits
docs/capabilities.md	Graph export, string search, crypto, Edge AI, startup intent, rehosting packs
docs/epistemics.md	How to read FAT output: what results do and do not prove
docs/architecture.md	Workspace crates and extension points
DEVELOPMENT.md	Build and test workflow
CONTRIBUTING.md	Setup, PR checklist, and contribution guide
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 for citation metadata.

Maintainers

FAT was authored by adi0x90, who is also its current maintainer and principal contributor. The project is maintained under Attify.

License

FAT 2.0 is source available under FSL-1.1-ALv2. See LICENSING.md and THIRD_PARTY_NOTICES.md for more details.