Firmware Extraction Doctor (Binwalk + Friends)
Fix symlink failures, missing extractors, and incomplete filesystems
Firmware extraction fails when binwalk is missing external tools (sasquatch, cramfsck), newer extraction hardening blocks symlinks, or the workspace filesystem doesn't support them. This recipe creates a known-good extraction workspace and a dependency checklist.
INGREDIENTS
PROMPT
Create a skill called "Firmware Extraction Doctor". Inputs I will provide: - OS + filesystem details (is the firmware on FAT/exFAT/NTFS/USB?) - binwalk version and exact error output - The binwalk signature scan offsets (if available) Task: 1) Determine whether failures are due to filesystem symlink limitations, missing extractors, or filesystem variants. 2) Provide the minimum commands to create a safe workspace and install missing helpers. 3) If needed, provide a manual carving plan using dd based on reported offsets. 4) Output should include a reproducibility checklist (commands + hashes + directory tree).
What this fixes
Common symptoms:
- Binwalk fails to initialize extraction directory due to symlink creation errors
- Warnings about symlinks pointing outside the extraction directory
- Extraction yields empty filesystem roots (e.g., squashfs-root empty)
- Missing external tools: `sasquatch`, `cramfsck`, etc.
Prerequisites
- A POSIX filesystem workspace that supports symlinks (avoid FAT/exFAT/NTFS mounts)
- `binwalk` installed
- Ability to install external extraction helpers
- Sufficient disk space (firmware extraction can expand significantly)
Steps and commands
- Create a safe workspace (important):
- Copy the firmware into a local ext4/APFS/Linux-native directory:
`mkdir -p ~/fw && cp /path/on/usb/firmware.bin ~/fw/ && cd ~/fw`
- Run binwalk with recursive extraction:
`binwalk -Me firmware.bin`
- If binwalk fails with "Failed to create symlink ... Operation not permitted":
- Move the workspace to a filesystem that supports symlinks and rerun.
- In WSL, prefer `~/` (Linux filesystem), not `/mnt/c/`.
- Install common external extractors:
- SquashFS tooling:
`sudo apt-get install -y squashfs-tools`
- sasquatch (patched unsquashfs for vendor-modified variants):
`sudo apt-get install -y zlib1g-dev liblzma-dev liblzo2-dev`
`git clone https://github.com/devttys0/sasquatch && (cd sasquatch && ./build.sh)`
- cramfs:
`sudo apt-get install -y cramfsprogs`
- If extraction is still incomplete:
- Manually carve offsets using `dd` based on binwalk's signature output, then run the appropriate extractor (unsquashfs, ubireader, etc.).
- Keep carved files as artifacts for reproducibility.
Expected outputs
- `_firmware.bin.extracted/` directory containing carved components and filesystem roots
- A repeatable command log showing how artifacts were produced
Common errors and troubleshooting
- Symlink warnings ("points outside extraction directory")
- This is binwalk's safety hardening; it may rewrite unsafe links.
- Document it; do not disable the safety check unless you understand the risk.
- Missing sasquatch/cramfsck
- Install the external utility; Debian packaging may omit optional dependencies.
- Binwalk "incomplete extraction"
- Known issue with some filesystem variants; try alternative extractors or manual carving.
References
- https://github.com/ReFirmLabs/binwalk/issues/942
- https://github.com/ReFirmLabs/binwalk/issues/650
- https://www.tarlogic.com/blog/owasp-fstm-stage-4-extracting-the-filesystem/
- https://github.com/ReFirmLabs/binwalk/issues/290
Example inputs
- Firmware file: firmware.bin
- Workspace: ~/fw (ext4)