diff options
Diffstat (limited to 'third_party/rust/goblin/README.md')
| -rw-r--r-- | third_party/rust/goblin/README.md | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/third_party/rust/goblin/README.md b/third_party/rust/goblin/README.md new file mode 100644 index 0000000000..d871e843a8 --- /dev/null +++ b/third_party/rust/goblin/README.md @@ -0,0 +1,259 @@ +# libgoblin + +[![Actions][actions-badge]][actions-url] +[![crates.io version][crates-goblin-badge]][crates-goblin] + +<!-- Badges' links --> + +[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 + + + +### 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? + +<!-- Related projects --> + +[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] + +<!-- Contributors --> + +[@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. |