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 4.0 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

Minimum supported rust version: 1.65.0

Add the following to your Cargo.toml file: toml [dependencies] backhand = "0.13.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, or download from the latest github release.

See --help for more information.

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] -a, --auto-offset Find first instance of squashfs --kind magic -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 --path-filter Limit filesystem extraction [default: /] -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, avmbev4_0] --completions Emit shell completion scripts [possible values: bash, elvish, fish, powershell, zsh] -h, --help Print help (see more with '--help') -V, --version Print version ```

add-backhand

```no_test tool to add a file or directory to squashfs filesystems

Usage: add [OPTIONS]

Arguments: Squashfs input image Path of file once inserted into squashfs

Options: -d, --dir Create empty directory -f, --file Path of file to read, to write into squashfs -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

See ./benches using cargo bench to benchmark the library, or run ./bench.bash to benchmark against system squashfs-tools/unsquashfs. While there is still work to do, in most cases our speed is comparable to single-threaded squashfs-tools/unsquashfs. Comparing memory usage, our unsquashfs beats squashfs-tools by using 18.1MB instead of 74.8MB in the case of test_re815_xev160/870D97.squashfs.

Testing

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

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