# libgoblin [![Actions][actions-badge]][actions-url] [![crates.io version][crates-goblin-badge]][crates-goblin] [actions-badge]: https://github.com/m4b/goblin/workflows/CI/badge.svg?branch=master [actions-url]: https://github.com/m4b/goblin/actions [crates-goblin-badge]: https://img.shields.io/crates/v/goblin.svg [crates-goblin]: https://crates.io/crates/goblin ![say the right words](https://s-media-cache-ak0.pinimg.com/736x/1b/6a/aa/1b6aaa2bae005e2fed84b1a7c32ecb1b.jpg) ### Documentation https://docs.rs/goblin/ [changelog](CHANGELOG.md) ### Usage Goblin requires `rustc` 1.56.0 (Rust 2021 edition). Add to your `Cargo.toml` ```toml [dependencies] goblin = "0.6" ``` ### Features * awesome crate name * zero-copy, cross-platform, endian-aware, ELF64/32 implementation - wow! * zero-copy, cross-platform, endian-aware, 32/64 bit Mach-o parser - zoiks! * PE 32/64-bit parser - bing! * a Unix _and_ BSD style archive parser (latter courtesy of [@willglynn]) - huzzah! * many cfg options - it will make your head spin, and make you angry when reading the source! * fuzzed - "I am happy to report that goblin withstood 100 million fuzzing runs, 1 million runs each for seed 1\~100." - [@sanxiyn] * tests `libgoblin` aims to be your one-stop shop for binary parsing, loading, and analysis. ### Use-cases Goblin primarily supports the following important use cases: 1. Core, std-free `#[repr(C)]` structs, tiny compile time, 32/64 (or both) at your leisure. 1. Type punning. Define a function once on a type, but have it work on 32 or 64-bit variants - without really changing anything, and no macros! See `examples/automagic.rs` for a basic example. 1. `std` mode. This throws in read and write impls via `Pread` and `Pwrite`, reading from file, convenience allocations, extra methods, etc. This is for clients who can allocate and want to read binaries off disk. 1. `Endian_fd`. A truly terrible name :laughing: this is for binary analysis like in [panopticon] or [falcon] which needs to read binaries of foreign endianness, _or_ as a basis for constructing cross platform foreign architecture binutils, e.g. [cargo-sym] and [bingrep] are simple examples of this, but the sky is the limit. Here are some things you could do with this crate (or help to implement so they could be done): 1. Write a compiler and use it to [generate binaries][faerie] (all the raw C structs have [`Pwrite`][scroll] derived). 1. Write a binary analysis tool which loads, parses, and analyzes various binary formats, e.g., [panopticon] or [falcon]. 1. Write a [semi-functioning dynamic linker][dryad]. 1. Write a [kernel][redox-os] and load binaries using `no_std` cfg. I.e., it is essentially just struct and const defs (like a C header) - no fd, no output, no std. 1. Write a [bin2json] tool, because why shouldn't binary formats be in JSON? [PyO3/maturin]: https://github.com/PyO3/maturin [occlum]: https://github.com/occlum/occlum [memflow]: https://github.com/memflow/memflow [cargo-sym]: https://github.com/m4b/cargo-sym [bingrep]: https://github.com/m4b/bingrep [faerie]: https://github.com/m4b/faerie [dryad]: https://github.com/m4b/dryad [scroll]: https://github.com/m4b/scroll [redox-os]: https://github.com/redox-os/redox [bin2json]: https://github.com/m4b/bin2json [panopticon]: https://github.com/das-labor/panopticon [falcon]: https://github.com/endeav0r/falcon ### Cfgs `libgoblin` is designed to be massively configurable. The current flags are: * elf64 - 64-bit elf binaries, `repr(C)` struct defs * elf32 - 32-bit elf binaries, `repr(C)` struct defs * mach64 - 64-bit mach-o `repr(C)` struct defs * mach32 - 32-bit mach-o `repr(C)` struct defs * pe32 - 32-bit PE `repr(C)` struct defs * pe64 - 64-bit PE `repr(C)` struct defs * archive - a Unix Archive parser * endian_fd - parses according to the endianness in the binary * std - to allow `no_std` environments # Contributors Thank you all :heart: ! In lexicographic order: - [@2vg] - [@alessandrod] - [@amanieu] - [@anfedotoff] - [@apalm] - [@burjui] - [@connorkuehl] - [@dancrossnyc] - [@dureuill] - [@Evian-Zhang] - [@ExPixel] - [@flanfly] - [@glandium] - [@ibabushkin] - [@jackcmay] - [@jan-auer] - [@jessehui] - [@jdub] - [@johannst] - [@jrmuizel] - [@jsgf] - [@keith] - [@kjempelodott] - [@ko1n] - [@le-jzr] - [@Lichtso] - [@lion128] - [@llogiq] - [@lumag] - [@lzutao] - [@lzybkr] - [@m4b] - [@messense] - [@mitsuhiko] - [@mkroening] - [@mre] - [@Mrmaxmeier] - [n01e0] - [nathaniel-daniel] - [@nick96] - [@nico-abram] - [@npmccallum] - [@pchickey] - [@philipc] - [@Pzixel] - [@quake] - [@raindev] - [@rocallahan] - [@sanxiyn] - [@skdltmxn] - [@sollyucko] - [@Swatinem] - [@SweetVishnya] - [@SquareMan] - [@tathanhdinh] - [@Techno-coder] - [@ticki] - [@Timmmm] - [@Tiwalun] - [@track-5] - [@tux3] - [@wickerwacka] - [@willglynn] - [@woodruffw] - [@wyxloading] - [@xcoldhandsx] [@2vg]: https://github.com/2vg [@alessandrod]: https://github.com/alessandrod [@amanieu]: https://github.com/amanieu [@anfedotoff]: https://github.com/anfedotoff [@apalm]: https://github.com/apalm [@burjui]: https://github.com/burjui [@connorkuehl]: https://github.com/connorkuehl [@dancrossnyc]: https://github.com/dancrossnyc [@dureuill]: https://github.com/dureuill [@Evian-Zhang]: https://github.com/Evian-Zhang [@ExPixel]: https://github.com/ExPixel [@flanfly]: https://github.com/flanfly [@glandium]: https://github.com/glandium [@ibabushkin]: https://github.com/ibabushkin [@jackcmay]: https://github.com/jackcmay [@jan-auer]: https://github.com/jan-auer [@jessehui]: https://github.com/jessehui [@johannst]: https://github.com/johannst [@jdub]: https://github.com/jdub [@jrmuizel]: https://github.com/jrmuizel [@jsgf]: https://github.com/jsgf [@keith]: https://github.com/keith [@kjempelodott]: https://github.com/kjempelodott [@ko1N]: https://github.com/ko1N [@le-jzr]: https://github.com/le-jzr [@Lichtso]: https://github.com/Lichtso [@lion128]: https://github.com/lion128 [@llogiq]: https://github.com/llogiq [@lumag]: https://github.com/lumag [@lzutao]: https://github.com/lzutao [@lzybkr]: https://github.com/lzybkr [@m4b]: https://github.com/m4b [@messense]: https://github.com/messense [@mitsuhiko]: https://github.com/mitsuhiko [@mkroening]: https://github.com/mkroening [@mre]: https://github.com/mre [@Mrmaxmeier]: https://github.com/Mrmaxmeier [n01e0]: https://github.com/n01e0 [nathaniel-daniel]: https://github.com/nathaniel-daniel [@nick96]: https://github.com/nick96 [@nico-abram]: https://github.com/nico-abram [@npmccallum]: https://github.com/npmccallum [@pchickey]: https://github.com/pchickey [@philipc]: https://github.com/philipc [@Pzixel]: https://github.com/Pzixel [@quake]: https://github.com/quake [@raindev]: https://github.com/raindev [@rocallahan]: https://github.com/rocallahan [@sanxiyn]: https://github.com/sanxiyn [@skdltmxn]: https://github.com/skdltmxn [@sollyucko]: https://github.com/sollyucko [@Swatinem]: https://github.com/Swatinem [@SweetVishnya]: https://github.com/SweetVishnya [@SquareMan]: https://github.com/SquareMan [@tathanhdinh]: https://github.com/tathanhdinh [@Techno-coder]: https://github.com/Techno-coder [@ticki]: https://github.com/ticki [@Timmmm]: https://github.com/Timmmm [@Tiwalun]: https://github.com/Tiwalun [@track-5]: https://github.com/track-5 [@tux3]: https://github.com/tux3 [@wickerwacka]: https://github.com/wickerwaka [@willglynn]: https://github.com/willglynn [@woodruffw]: https://github.com/woodruffw [@wyxloading]: https://github.com/wyxloading [@xcoldhandsx]: https://github.com/xcoldhandsx ## Contributing 1. Please prefix commits with the affected binary component; the more specific the better, e.g., if you only modify relocations in the elf module, then do "elf.reloc: added new constants for Z80" 1. Commit messages must explain their change, no generic "changed", or "fix"; if you push commits like this on a PR, be aware [@m4b] or someone will most likely squash them. 1. If you are making a large change to a module, please raise an issue first and lets discuss; I don't want to waste your time if its not a good technical direction, or etc. 1. If your PR is not getting attention, please respond to all relevant comments raised on the PR, and if still no response, ping [@m4b], [@philipc], or [@willglynn] in github and also feel free to email [@m4b]. 1. Please add tests if you are adding a new feature. Feel free to add tests even if you are not, tests are awesome and easy in rust. 1. Once cargo format is officially released, please format your _patch_ using the default settings.