1# libgoblin [![Build status][travis-badge]][travis-url] [![crates.io version][crates-goblin-badge]][crates-goblin] 2 3<!-- Badges' links --> 4 5[travis-badge]: https://travis-ci.org/m4b/goblin.svg?branch=master 6[travis-url]: https://travis-ci.org/m4b/goblin 7[crates-goblin-badge]: https://img.shields.io/crates/v/goblin.svg 8[crates-goblin]: https://crates.io/crates/goblin 9 10![say the right words](https://s-media-cache-ak0.pinimg.com/736x/1b/6a/aa/1b6aaa2bae005e2fed84b1a7c32ecb1b.jpg) 11 12### Documentation 13 14https://docs.rs/goblin/ 15 16[changelog](CHANGELOG.md) 17 18### Usage 19 20Goblin requires `rustc` 1.36.0. 21 22Add to your `Cargo.toml` 23 24```toml 25[dependencies] 26goblin = "0.1" 27``` 28 29### Features 30 31* awesome crate name 32* zero-copy, cross-platform, endian-aware, ELF64/32 implementation - wow! 33* zero-copy, cross-platform, endian-aware, 32/64 bit Mach-o parser - zoiks! 34* PE 32/64-bit parser - bing! 35* a Unix _and_ BSD style archive parser (latter courtesy of [@willglynn]) - huzzah! 36* many cfg options - it will make your head spin, and make you angry when reading the source! 37* fuzzed - "I am happy to report that goblin withstood 100 million fuzzing runs, 1 million runs 38 each for seed 1\~100." - [@sanxiyn] 39* tests 40 41`libgoblin` aims to be your one-stop shop for binary parsing, loading, and analysis. 42 43### Use-cases 44 45Goblin primarily supports the following important use cases: 46 471. Core, std-free `#[repr(C)]` structs, tiny compile time, 32/64 (or both) at your leisure. 48 491. Type punning. Define a function once on a type, but have it work on 32 or 64-bit variants - 50 without really changing anything, and no macros! See `examples/automagic.rs` for a basic example. 51 521. `std` mode. This throws in read and write impls via `Pread` and `Pwrite`, reading from file, 53 convenience allocations, extra methods, etc. This is for clients who can allocate and want to 54 read binaries off disk. 55 561. `Endian_fd`. A truly terrible name :laughing: this is for binary analysis like in [panopticon] 57 or [falcon] which needs to read binaries of foreign endianness, _or_ as a basis for 58 constructing cross platform foreign architecture binutils, e.g. [cargo-sym] and [bingrep] are 59 simple examples of this, but the sky is the limit. 60 61Here are some things you could do with this crate (or help to implement so they could be done): 62 631. Write a compiler and use it to [generate binaries][faerie] (all the raw C structs have 64 [`Pwrite`][scroll] derived). 651. Write a binary analysis tool which loads, parses, and analyzes various binary formats, e.g., 66 [panopticon] or [falcon]. 671. Write a [semi-functioning dynamic linker][dryad]. 681. Write a [kernel][redox-os] and load binaries using `no_std` cfg. I.e., it is essentially just 69 struct and const defs (like a C header) - no fd, no output, no std. 701. Write a [bin2json] tool, because why shouldn't binary formats be in JSON? 71 72<!-- Related projects --> 73 74[cargo-sym]: https://github.com/m4b/cargo-sym 75[bingrep]: https://github.com/m4b/bingrep 76[faerie]: https://github.com/m4b/faerie 77[dryad]: https://github.com/m4b/dryad 78[scroll]: https://github.com/m4b/scroll 79[redox-os]: https://github.com/redox-os/redox 80[bin2json]: https://github.com/m4b/bin2json 81[panopticon]: https://github.com/das-labor/panopticon 82[falcon]: https://github.com/endeav0r/falcon 83 84### Cfgs 85 86`libgoblin` is designed to be massively configurable. The current flags are: 87 88* elf64 - 64-bit elf binaries, `repr(C)` struct defs 89* elf32 - 32-bit elf binaries, `repr(C)` struct defs 90* mach64 - 64-bit mach-o `repr(C)` struct defs 91* mach32 - 32-bit mach-o `repr(C)` struct defs 92* pe32 - 32-bit PE `repr(C)` struct defs 93* pe64 - 64-bit PE `repr(C)` struct defs 94* archive - a Unix Archive parser 95* endian_fd - parses according to the endianness in the binary 96* std - to allow `no_std` environments 97 98# Contributors 99 100Thank you all :heart: ! 101 102In lexicographic order: 103 104- [@amanieu] 105- [@burjui] 106- [@flanfly] 107- [@ibabushkin] 108- [@jan-auer] 109- [@jdub] 110- [@jrmuizel] 111- [@jsgf] 112- [@kjempelodott] 113- [@le-jzr] 114- [@lion128] 115- [@llogiq] 116- [@lzutao] 117- [@lzybkr] 118- [@m4b] 119- [@mitsuhiko] 120- [@mre] 121- [@pchickey] 122- [@philipc] 123- [@Pzixel] 124- [@raindev] 125- [@rocallahan] 126- [@sanxiyn] 127- [@tathanhdinh] 128- [@Techno-coder] 129- [@ticki] 130- [@wickerwacka] 131- [@willglynn] 132- [@wyxloading] 133- [@xcoldhandsx] 134 135<!-- Contributors --> 136 137[@amanieu]: https://github.com/amanieu 138[@burjui]: https://github.com/burjui 139[@flanfly]: https://github.com/flanfly 140[@ibabushkin]: https://github.com/ibabushkin 141[@jan-auer]: https://github.com/jan-auer 142[@jdub]: https://github.com/jdub 143[@jrmuizel]: https://github.com/jrmuizel 144[@jsgf]: https://github.com/jsgf 145[@kjempelodott]: https://github.com/kjempelodott 146[@le-jzr]: https://github.com/le-jzr 147[@lion128]: https://github.com/lion128 148[@llogiq]: https://github.com/llogiq 149[@lzutao]: https://github.com/lzutao 150[@lzybkr]: https://github.com/lzybkr 151[@m4b]: https://github.com/m4b 152[@mitsuhiko]: https://github.com/mitsuhiko 153[@mre]: https://github.com/mre 154[@pchickey]: https://github.com/pchickey 155[@philipc]: https://github.com/philipc 156[@Pzixel]: https://github.com/Pzixel 157[@raindev]: https://github.com/raindev 158[@rocallahan]: https://github.com/rocallahan 159[@sanxiyn]: https://github.com/sanxiyn 160[@tathanhdinh]: https://github.com/tathanhdinh 161[@Techno-coder]: https://github.com/Techno-coder 162[@ticki]: https://github.com/ticki 163[@wickerwacka]: https://github.com/wickerwaka 164[@willglynn]: https://github.com/willglynn 165[@wyxloading]: https://github.com/wyxloading 166[@xcoldhandsx]: https://github.com/xcoldhandsx 167 168## Contributing 169 1701. Please prefix commits with the affected binary component; the more specific the better, e.g., 171 if you only modify relocations in the elf module, then do "elf.reloc: added new constants for Z80" 1721. Commit messages must explain their change, no generic "changed", or "fix"; if you push commits 173 like this on a PR, be aware [@m4b] or someone will most likely squash them. 1741. If you are making a large change to a module, please raise an issue first and lets discuss; 175 I don't want to waste your time if its not a good technical direction, or etc. 1761. If your PR is not getting attention, please respond to all relevant comments raised on the PR, 177 and if still no response, ping [@m4b], [@philipc], or [@willglynn] in github and also feel free 178 to email [@m4b]. 1791. Please add tests if you are adding a new feature. Feel free to add tests even if you are not, 180 tests are awesome and easy in rust. 1811. Once cargo format is officially released, please format your _patch_ using the default settings. 182