Anthropic-Cybersecurity-Skills/skills/performing-firmware-extraction-with-binwalk/references/api-reference.md

API Reference: Binwalk Firmware Extraction Tools

binwalk - Firmware Analysis Tool

Signature Scan

binwalk firmware.bin                      # Basic signature scan
binwalk -v firmware.bin                   # Verbose output
binwalk -B firmware.bin                   # Explicit signature scan flag
binwalk -A firmware.bin                   # Opcode/architecture scan
binwalk -R "string" firmware.bin          # Raw string search

Extraction

binwalk -e firmware.bin                   # Extract known file types
binwalk -Me firmware.bin                  # Recursive (matryoshka) extraction
binwalk -Me -d 5 firmware.bin             # Recursive with depth limit
binwalk -C /output/dir -e firmware.bin    # Custom output directory
binwalk -D "type:ext:cmd" firmware.bin    # Custom extraction rule

Entropy Analysis

binwalk -E firmware.bin                   # Entropy analysis with plot
binwalk -E -K 256 firmware.bin            # Custom block size
binwalk -BE firmware.bin                  # Combined signature + entropy

Key Flags

Flag	Description
-B, --signature	Scan for file signatures
-e, --extract	Extract identified file types
-M, --matryoshka	Recursive extraction
-d, --depth=N	Matryoshka recursion depth (default: 8)
-E, --entropy	Entropy analysis
-K, --block=N	Entropy block size in bytes
-A, --opcodes	Scan for CPU opcode signatures
-R, --raw=STR	Search for raw byte string
-y, --include=STR	Include only matching results
-x, --exclude=STR	Exclude matching results
-m, --magic=FILE	Use custom magic signature file
-C, --directory=DIR	Output directory for extraction
-v, --verbose	Verbose output
--threads=N	Number of worker threads

unsquashfs - SquashFS Extraction

Syntax

unsquashfs -d /output/dir image.squashfs          # Extract to directory
unsquashfs -l image.squashfs                       # List contents
unsquashfs -ll image.squashfs                      # Long listing
unsquashfs -s image.squashfs                       # Show superblock info
unsquashfs -f -d /output image.squashfs            # Force overwrite

Key Flags

Flag	Description
-d DIR	Extract to specified directory
-l	List filesystem contents
-ll	Detailed listing with permissions
-s	Display superblock information
-f	Overwrite existing files
-n	No progress bar
-e FILE	Extract only specified files

jefferson - JFFS2 Extraction

Syntax

jefferson image.jffs2 -d /output/dir              # Extract JFFS2
jefferson -v image.jffs2 -d /output/dir            # Verbose extraction

sasquatch - Vendor SquashFS

Syntax

sasquatch -d /output/dir image.squashfs            # Extract non-standard SquashFS
sasquatch -p 1 -d /output image.squashfs           # Single-threaded extraction

Handles vendor-modified SquashFS variants from TP-Link, D-Link, Netgear, and others that use non-standard compression or block sizes.

strings - String Extraction

Syntax

strings firmware.bin                               # Default (4+ chars)
strings -n 12 firmware.bin                         # Minimum 12 chars
strings -a firmware.bin                            # Scan entire file
strings -t x firmware.bin                          # Show hex offsets
strings -e l firmware.bin                          # Little-endian 16-bit

Key Flags

Flag	Description
-n N	Minimum string length
-a	Scan entire file (not just data sections)
-t x	Print offset in hexadecimal
-t d	Print offset in decimal
-e l	16-bit little-endian encoding
-e b	16-bit big-endian encoding

dd - Manual Extraction

Syntax

dd if=firmware.bin of=output.bin bs=1 skip=OFFSET count=SIZE
dd if=firmware.bin of=output.bin bs=1 skip=$((0x120000)) count=$((0x2A0000))

Key Parameters

Parameter	Description
if=FILE	Input file
of=FILE	Output file
bs=N	Block size (use 1 for byte-precise extraction)
skip=N	Skip N blocks from input start
count=N	Copy only N blocks

Python binwalk Module (v2 API)

Programmatic Usage

import binwalk

# Signature scan
for module in binwalk.scan(firmware_path, signature=True, quiet=True):
    for result in module.results:
        print(f"0x{result.offset:08X}  {result.description}")

# Extract files
binwalk.scan(firmware_path, signature=True, extract=True, quiet=True)

# Entropy analysis
for module in binwalk.scan(firmware_path, entropy=True, quiet=True):
    for result in module.results:
        print(f"0x{result.offset:08X}  entropy={result.entropy}")

# Recursive extraction
binwalk.scan(firmware_path, signature=True, extract=True,
             matryoshka=True, depth=5, quiet=True)