backhand =============================== [github](https://github.com/wcampbell0x2a/backhand) [crates.io](https://crates.io/crates/backhand) [docs.rs](https://docs.rs/backhand) [build status](https://github.com/wcampbell0x2a/backhand/actions?query=branch%3Amaster) [Codecov](https://app.codecov.io/gh/wcampbell0x2a/backhand) Library and binaries for the reading, creating, and modification of [SquashFS](https://en.wikipedia.org/wiki/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 *Compiler support: requires rustc 1.72.1+* Add the following to your `Cargo.toml` file: ```toml [dependencies] backhand = "0.18.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 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 *Compiler support: requires rustc 1.74+* These are currently under development and are missing features, MR's welcome! To install, run `cargo install backhand-cli --locked`, or download from the [latest github release](https://github.com/wcampbell0x2a/backhand/releases/latest). See ``--help`` for more information. ### unsquashfs-backhand ```no_test tool to uncompress, extract and list squashfs filesystems Usage: unsquashfs-backhand [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 (ignores --quiet) -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 (ignores --quiet) -k, --kind Kind(type of image) to parse [default: le_v4_0] [possible values: be_v4_0, le_v4_0, avm_be_v4_0] --completions Emit shell completion scripts [possible values: bash, elvish, fish, powershell, zsh] --quiet Silence all progress bar and RUST_LOG output -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-backhand [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 Override mode read from --uid Override uid read from --gid Override gid read from --mtime Override mtime read from -h, --help Print help -V, --version Print version ``` ### replace-backhand ```no_test tool to replace files in squashfs filesystems Usage: replace-backhand [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 [BENCHMARK.md](BENCHMARK.md). ## Testing See [backhand-test](backhand-test/README.md).