{"id":14155594,"url":"https://github.com/wcampbell0x2a/backhand","last_synced_at":"2026-02-14T23:10:52.204Z","repository":{"id":61494300,"uuid":"515420306","full_name":"wcampbell0x2a/backhand","owner":"wcampbell0x2a","description":"Library and binaries for the reading, creating, and modification of SquashFS file systems","archived":false,"fork":false,"pushed_at":"2024-08-07T03:31:58.000Z","size":1603,"stargazers_count":111,"open_issues_count":32,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-08-09T10:02:19.504Z","etag":null,"topics":["compression","filesystem","linux","rust","squashfs"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wcampbell0x2a.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["wcampbell0x2a"]}},"created_at":"2022-07-19T03:25:16.000Z","updated_at":"2024-08-10T20:10:39.382Z","dependencies_parsed_at":"2023-10-24T02:30:57.128Z","dependency_job_id":"bef80fd2-e8d3-4693-9806-f932a0b1652d","html_url":"https://github.com/wcampbell0x2a/backhand","commit_stats":{"total_commits":316,"total_committers":2,"mean_commits":158.0,"dds":"0.24683544303797467","last_synced_commit":"99702923d14c1ef237e8443758f9d8a73c9adb9d"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wcampbell0x2a%2Fbackhand","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wcampbell0x2a%2Fbackhand/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wcampbell0x2a%2Fbackhand/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wcampbell0x2a%2Fbackhand/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wcampbell0x2a","download_url":"https://codeload.github.com/wcampbell0x2a/backhand/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247345856,"owners_count":20924102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compression","filesystem","linux","rust","squashfs"],"created_at":"2024-08-17T08:04:11.053Z","updated_at":"2026-02-14T23:10:52.199Z","avatar_url":"https://github.com/wcampbell0x2a.png","language":"Rust","funding_links":["https://github.com/sponsors/wcampbell0x2a"],"categories":["rust"],"sub_categories":[],"readme":"backhand\n===============================\n\n[\u003cimg alt=\"github\" src=\"https://img.shields.io/badge/github-wcampbell0x2a/backhand-8da0cb?style=for-the-badge\u0026labelColor=555555\u0026logo=github\" height=\"20\"\u003e](https://github.com/wcampbell0x2a/backhand)\n[\u003cimg alt=\"crates.io\" src=\"https://img.shields.io/crates/v/backhand.svg?style=for-the-badge\u0026color=fc8d62\u0026logo=rust\" height=\"20\"\u003e](https://crates.io/crates/backhand)\n[\u003cimg alt=\"docs.rs\" src=\"https://img.shields.io/badge/docs.rs-backhand-66c2a5?style=for-the-badge\u0026labelColor=555555\u0026logo=docs.rs\" height=\"20\"\u003e](https://docs.rs/backhand)\n[\u003cimg alt=\"build status\" src=\"https://img.shields.io/github/actions/workflow/status/wcampbell0x2a/backhand/main.yml?branch=master\u0026style=for-the-badge\" height=\"20\"\u003e](https://github.com/wcampbell0x2a/backhand/actions?query=branch%3Amaster)\n[\u003cimg alt=\"Codecov\" src=\"https://img.shields.io/codecov/c/github/wcampbell0x2a/backhand?style=for-the-badge\" height=\"20\"\u003e](https://app.codecov.io/gh/wcampbell0x2a/backhand)\n\nLibrary and binaries for the reading, creating, and modification\nof [SquashFS](https://en.wikipedia.org/wiki/SquashFS) file systems.\n\n- **Library** — Backhand provides an easy way for programmatic analysis of Squashfs images,\nincluding the extraction and modification of images.\n- **Feature Flags** — Supported compression and decompression are [feature flagged](https://docs.rs/backhand/latest/backhand/#features), so your final binary (or `unsquashfs`)\nonly needs to include code to extract one type of image.\n- **Unconventional Support** — As well as supporting normal linux kernel SquashFS 4.0 and 3.0, we also support\nthe \"wonderful world of vendor formats\" with a [Kind](https://docs.rs/backhand/latest/backhand/kind/index.html) struct.\nThis allows changing the magic bytes, custom compression algorithms, and the Endian-ness of either the Data or Metadata fields.\nThis is controlled from `unsquashfs-backhand` through the use of the `--kind` option.\n\n#### Squashfs Support\n| Kind                                   | `read` | `write` | Feature    |\n|----------------------------------------|:-------:|:------:|:----------:|\n| `be_v4_0`                              | ✓       | ✓      | `default`  |\n| `le_v4_0`                              | ✓       | ✓      | `default`  |\n| `avm_be_v4_0`                          | ✓       | ✓      | `default`  |\n| `be_v3_0`                              | ✓       |        | `v3`       |\n| `le_v3_0`                              | ✓       |        | `v3`       |\n| `be_v3_0_lzma`                         | ✓       |        | `v3_lzma`  |\n| `le_v3_0_lzma`                         | ✓       |        | `v3_lzma`  |\n| `netgear_be_v3_0_lzma`                 | ✓       |        | `v3_lzma`  |\n| `netgear_be_v3_0_lzma_standard`        | ✓       |        | `v3_lzma`  |\n\n\n## Library\n*Compiler support: requires rustc 1.86+*\n\nAdd the following to your `Cargo.toml` file:\n```toml\n[dependencies]\nbackhand = \"0.25.0\"\n```\n\n#### Target Support\nAlthough additional targets may be supported, only the following have been fully tested or confirmed to build successfully.\n\n| Target                                 | `build` | `test` |\n|----------------------------------------|:-------:|:------:|\n| `x86_64-unknown-linux-musl`            | ✓       | ✓      |\n| `aarch64-unknown-linux-musl`           | ✓       | ✓      |\n| `arm-unknown-linux-musleabi`           | ✓       | ✓      |\n| `armv7-unknown-linux-musleabi`         | ✓       | ✓      |\n| `aarch64-unknown-linux-musl`           | ✓       | ✓      |\n| `x86_64-apple-darwin`                  | ✓       | ✓      |\n| `x86_64-pc-windows-gnu`                | ✓       |        |\n\n### Reading/Writing/Modifying Firmware\n```rust,no_run\nuse std::fs::File;\nuse std::io::{Cursor, BufReader};\nuse backhand::{FilesystemReader, FilesystemWriter, NodeHeader};\n\n// read\nlet file = BufReader::new(File::open(\"file.squashfs\").unwrap());\nlet read_filesystem = FilesystemReader::from_reader(file).unwrap();\n\n// convert to writer\nlet mut write_filesystem = FilesystemWriter::from_fs_reader(\u0026read_filesystem).unwrap();\n\n// add file with data from slice\nlet d = NodeHeader::default();\nlet bytes = Cursor::new(b\"Fear is the mind-killer.\");\nwrite_filesystem.push_file(bytes, \"a/d/e/new_file\", d);\n\n// add file with data from file\nlet new_file = File::open(\"dune\").unwrap();\nwrite_filesystem.push_file(new_file, \"/root/dune\", d);\n\n// modify file\nlet bytes = Cursor::new(b\"The sleeper must awaken.\\n\");\nwrite_filesystem.replace_file(\"/a/b/c/d/e/first_file\", bytes).unwrap();\n\n// write into a new file\nlet mut output = File::create(\"modified.squashfs\").unwrap();\nwrite_filesystem.write(\u0026mut output).unwrap();\n```\n\n## Binaries\n*Compiler support: requires rustc 1.86+*\n\nThese are currently under development and are missing features, MR's welcome!\n\nTo install, run `cargo install backhand-cli --locked`, or download from the\n[latest github release](https://github.com/wcampbell0x2a/backhand/releases/latest).\n\nSee ``--help`` for more information.\n\n#### Target Support\nAlthough additional targets may be supported, only the following have been tested and included in our GitHub releases.\n\n| Target                                 | `test`    | `release` |\n|----------------------------------------|:---------:|:---------:|\n| `x86_64-unknown-linux-musl`            | ✓         | ✓         |\n| `aarch64-unknown-linux-musl`           | ✓         | ✓         |\n| `arm-unknown-linux-musleabi`           | ✓         | ✓         |\n| `armv7-unknown-linux-musleabi`         | ✓         | ✓         |\n| `aarch64-unknown-linux-musl`           | ✓         | ✓         |\n| `x86_64-apple-darwin`                  | ✓         | ✓         |\n\n### unsquashfs-backhand\n```no_test\ntool to uncompress, extract and list squashfs filesystems\n\nUsage: unsquashfs-backhand [OPTIONS] [FILESYSTEM]\n\nArguments:\n  [FILESYSTEM]  Squashfs file\n\nOptions:\n  -o, --offset \u003cBYTES\u003e             Skip BYTES at the start of FILESYSTEM [default: 0]\n  -a, --auto-offset                Find first instance of squashfs --kind magic\n  -l, --list                       List filesystem, do not write to DEST (ignores --quiet)\n  -d, --dest \u003cPATHNAME\u003e            Extract to [PATHNAME] [default: squashfs-root]\n  -i, --info                       Print files as they are extracted\n      --path-filter \u003cPATH_FILTER\u003e  Limit filesystem extraction [default: /]\n  -f, --force                      If file already exists then overwrite\n  -s, --stat                       Display filesystem superblock information (ignores --quiet)\n  -k, --kind \u003cKIND\u003e                Kind(type of image) to parse. If not specified, will\n                                   auto-detect by trying all kinds [possible values: le_v4_0,\n                                   be_v4_0, le_v3_0, be_v3_0, le_v3_0_lzma, be_v3_0_lzma,\n                                   netgear_be_v3_0_lzma_standard, netgear_be_v3_0_lzma,\n                                   avm_be_v4_0]\n      --completions \u003cCOMPLETIONS\u003e  Emit shell completion scripts [possible values: bash, elvish,\n                                   fish, powershell, zsh]\n      --quiet                      Silence all progress bar and RUST_LOG output\n  -h, --help                       Print help (see more with '--help')\n  -V, --version                    Print version\n```\n\n### add-backhand\n```no_test\ntool to add a file or directory to squashfs filesystems\n\nUsage: add-backhand [OPTIONS] \u003cINPUT_IMAGE\u003e \u003cFILE_PATH_IN_IMAGE\u003e \u003cOUTPUT_IMAGE\u003e\n\nArguments:\n  \u003cINPUT_IMAGE\u003e         Squashfs input image\n  \u003cFILE_PATH_IN_IMAGE\u003e  Path of file once inserted into squashfs\n  \u003cOUTPUT_IMAGE\u003e        Squashfs output image path\n\nOptions:\n  -d, --dir                     Create empty directory\n  -f, --file \u003cFILE\u003e             Path of file to read, to write into squashfs\n      --mode \u003cMODE\u003e             Override mode read from \u003cFILE\u003e\n      --uid \u003cUID\u003e               Override uid read from \u003cFILE\u003e\n      --gid \u003cGID\u003e               Override gid read from \u003cFILE\u003e\n      --mtime \u003cMTIME\u003e           Override mtime read from \u003cFILE\u003e\n      --pad-len \u003cPAD_LEN\u003e       Custom KiB padding length\n      --no-compression-options  Don't emit compression options\n  -h, --help                    Print help\n  -V, --version                 Print version\n```\n\n### replace-backhand\n```no_test\ntool to replace files in squashfs filesystems\n\nUsage: replace-backhand [OPTIONS] \u003cINPUT_IMAGE\u003e \u003cFILE\u003e \u003cFILE_PATH_IN_IMAGE\u003e \u003cOUTPUT_IMAGE\u003e\n\nArguments:\n  \u003cINPUT_IMAGE\u003e         Squashfs input image\n  \u003cFILE\u003e                Path of file to read, to write into squashfs\n  \u003cFILE_PATH_IN_IMAGE\u003e  Path of file replaced in image\n  \u003cOUTPUT_IMAGE\u003e        Squashfs output image\n\nOptions:\n      --pad-len \u003cPAD_LEN\u003e       Custom KiB padding length\n      --no-compression-options  Don't emit compression options\n  -h, --help                    Print help\n  -V, --version                 Print version\n```\n\n## Development\nAll patches/merge requests are welcome! See the development guide for more details.\n[DEVELOPMENT.md](DEVELOPMENT.md).\n\n## Performance\nSee [BENCHMARK.md](BENCHMARK.md).\n\n## Testing\nSee [backhand-test](backhand-test/README.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwcampbell0x2a%2Fbackhand","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwcampbell0x2a%2Fbackhand","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwcampbell0x2a%2Fbackhand/lists"}