backhand

Library and binaries for the reading, creating, and modification of SquashFS file systems.

Library — Backhand provides an easy way for programmatic analysis of Squashfs images, including the extraction and modification of images.
Feature Flags — Supported compression and decompression are feature flagged, so your final binary (or unsquashfs) only needs to include code to extract one type of image.
Unconventional Support — As well as supporting normal linux kernel SquashFS 4.0, we also support the "wonderful world of vendor formats" with a Kind struct. This allows changing the magic bytes, custom compression algorithms, and the Endian-ness of either the Data or Metadata fields.

Library

Add the following to your Cargo.toml file:

[dependencies]
backhand = "0.12.0"

Reading/Writing/Modifying Firmware

use std::fs::File;
use std::io::{Cursor, BufReader};
use backhand::{FilesystemReader, FilesystemWriter, NodeHeader};

// read
let file = BufReader::new(File::open("file.squashfs").unwrap());
let read_filesystem = FilesystemReader::from_reader(file).unwrap();

// convert to writer
let mut write_filesystem = FilesystemWriter::from_fs_reader(&read_filesystem).unwrap();

// add file with data from slice
let d = NodeHeader::default();
let bytes = Cursor::new(b"Fear is the mind-killer.");
write_filesystem.push_file(bytes, "a/d/e/new_file", d);

// add file with data from file
let new_file = File::open("dune").unwrap();
write_filesystem.push_file(new_file, "/root/dune", d);

// modify file
let bytes = Cursor::new(b"The sleeper must awaken.\n");
write_filesystem.replace_file("/a/b/c/d/e/first_file", bytes).unwrap();

// write into a new file
let mut output = File::create("modified.squashfs").unwrap();
write_filesystem.write(&mut output).unwrap();

Binaries

These are currently under development and are missing features, MR's welcome!

To install, run cargo install backhand --locked.

unsquashfs-backhand

tool to uncompress, extract and list squashfs filesystems

Usage: unsquashfs [OPTIONS] [FILESYSTEM]

Arguments:
  [FILESYSTEM]  Squashfs file

Options:
  -o, --offset <BYTES>             Skip BYTES at the start of FILESYSTEM [default: 0]
  -l, --list                       List filesystem, do not write to DEST
  -d, --dest <PATHNAME>            Extract to [PATHNAME] [default: squashfs-root]
  -i, --info                       Print files as they are extracted
  -f, --force                      If file already exists then overwrite
  -s, --stat                       Display filesystem superblock information
  -k, --kind <KIND>                Kind(type of image) to parse [default: le_v4_0] [possible values: be_v4_0, le_v4_0, amv_be_v4_0]
      --completions <COMPLETIONS>  Emit shell completion scripts [possible values: bash, elvish, fish, powershell, zsh]
  -h, --help                       Print help
  -V, --version                    Print version

add-backhand

tool to add files to squashfs filesystems

Usage: add [OPTIONS] <IMAGE> <FILE> <FILE_PATH_IN_IMAGE>

Arguments:
  <IMAGE>               Squashfs input image
  <FILE>                Path of file to read, to write into squashfs
  <FILE_PATH_IN_IMAGE>  Path of file once inserted into squashfs

Options:
  -o, --out <OUT>      Squashfs output image [default: added.squashfs]
      --mode <MODE>    Overide mode read from <FILE>
      --uid <UID>      Overide uid read from <FILE>
      --gid <GID>      Overide gid read from <FILE>
      --mtime <MTIME>  Overide mtime read from <FILE>
  -h, --help           Print help
  -V, --version        Print version

replace-backhand

tool to replace files in squashfs filesystems

Usage: replace [OPTIONS] <IMAGE> <FILE> <FILE_PATH_IN_IMAGE>

Arguments:
  <IMAGE>               Squashfs input image
  <FILE>                Path of file to read, to write into squashfs
  <FILE_PATH_IN_IMAGE>  Path of file replaced in image

Options:
  -o, --out <OUT>  Squashfs output image [default: replaced.squashfs]
  -h, --help       Print help
  -V, --version    Print version

Performance

While there is still work to do, in most cases our speed is comparable or better than single-threaded squashfs-tools/unsquashfs. Comparing memory usage, our unsquashfs beats squashfs-tools by using 18.1MB instead of 74.8MB.

Testing

This library is extensively tested with all library features and images from openwrt and extracted from manufacturers devices.

To run basic tests, use cargo test --release. To start fuzzing, run cargo fuzz list then pick one! Then start with cargo fuzz run [NAME].

backhand 0.12.0