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: toml [dependencies] backhand = "0.12.0"

Reading/Writing/Modifying Firmware

```rust,no_run 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 readfilesystem = FilesystemReader::fromreader(file).unwrap();

// convert to writer let mut writefilesystem = FilesystemWriter::fromfsreader(&readfilesystem).unwrap();

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

// add file with data from file let newfile = File::open("dune").unwrap(); writefilesystem.pushfile(newfile, "/root/dune", d);

// modify file let bytes = Cursor::new(b"The sleeper must awaken.\n"); writefilesystem.replacefile("/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

```no_test tool to uncompress, extract and list squashfs filesystems

Usage: unsquashfs [OPTIONS] [FILESYSTEM]

Arguments: [FILESYSTEM] Squashfs file

Options: -o, --offset Skip BYTES at the start of FILESYSTEM [default: 0] -l, --list List filesystem, do not write to DEST -d, --dest 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(type of image) to parse [default: lev40] [possible values: bev40, lev40, amvbev4_0] --completions Emit shell completion scripts [possible values: bash, elvish, fish, powershell, zsh] -h, --help Print help -V, --version Print version ```

add-backhand

```no_test tool to add files to squashfs filesystems

Usage: add [OPTIONS]

Arguments: Squashfs input image Path of file to read, to write into squashfs Path of file once inserted into squashfs

Options: -o, --out Squashfs output image [default: added.squashfs] --mode Overide mode read from --uid Overide uid read from --gid Overide gid read from --mtime Overide mtime read from -h, --help Print help -V, --version Print version ```

replace-backhand

```no_test tool to replace files in squashfs filesystems

Usage: replace [OPTIONS]

Arguments: Squashfs input image Path of file to read, to write into squashfs Path of file replaced in image

Options: -o, --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].