Skip to content

Latest commit

 

History

History
182 lines (139 loc) · 9.22 KB

README.md

File metadata and controls

182 lines (139 loc) · 9.22 KB
Raw

alt text

Build status Build Status

B2R2

B2R2 is a collection of useful algorithms, functions, and tools for binary analysis, written purely in F# (in .NET lingo, it is purely managed code). B2R2 has been named after R2-D2, a famous fictional robot appeared in the Star Wars. In fact, B2R2's original name was B2-R2, but we decided to use the name B2R2 instead, because .NET does not allow dash (-) characters in identifiers (or namespaces). The name essentially represents "binary" or "two": "binary" itself means "two" states anyways. "B" and "2" mean "binary", and "R" indicates reversing.

B2R2?

  1. B2R2 is analysis-friendly: it is written in F#, which provides all the syntactic goodies for writing program analyzers, such as pattern matching, algebraic data types, and etc.

  2. B2R2 is fast: it has a fast and efficient front-end engine for binary analysis, which is written in a functional-first way. Therefore, it naturally supports pure parallelism for binary disassembling, lifting and IR optimization.

  3. B2R2 is easy to play with: there is absolutely no dependency hell for B2R2 because it is a fully-managed library. All you need to do is to install .NET SDK, and you are ready to go! Native IntelliSense support is another plus!

  4. B2R2 is OS-Independent: it works on Linux, Mac, Windows, and etc. as long as .NET core supports it.

  5. B2R2 is interoperable: it is not bound to a specific language. Theoretically, you can use B2R2 APIs with any CLI supported languages.

Features?

B2R2 supports instruction parsing, binary disassembly, assembly, control-flow recovery, and many more. B2R2 also comes with several user-level command-line tools that are similar to readelf and objdump, although our tools are platform-agnostic. B2R2 currently supports four binary file formats: ELF, PE, Mach-O, and WebAssembly.

Below is a list of features that we currently support. Some of them are work in progress, but we look forward to your contributions! Feel free to write a PR (Pull Request) while making sure that you have read our contribution guideline.

Feature x86 x86-64 ARMv7 ARMv8 MIPS32 MIPS64 EVM TMS320C600 AVR PPC SPARC SH4 RISC-V
Instruction Parsing 🌕 🌕 🌕 🌕 🌕 🌕 🌕 🌕 🌕 🌕 🌕 🌔 🌕
Disassembly 🌕 🌕 🌕 🌕 🌕 🌕 🌕 🌕 🌕 🌕 🌕 🌔 🌕
Lifting 🌕 🌕 🌕 🌕 🌕 🌕 🌕 🌑 🌕 🌑 🌕 🌑 🌕
CFG Recovery 🌕 🌕 🌓 🌓 🌓 🌓 🌕 🌑 🌑 🌑 🌑 🌑 🌑
Data-Flow 🌕 🌕 🌕 🌕 🌕 🌕 🌕 🌑 🌑 🌑 🌑 🌑 🌑
Instruction Emulation 🌕 🌕 🌕 🌕 🌕 🌕 🌑 🌑 🌑 🌑 🌑 🌑 🌑
Assembly 🌕 🌕 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑
REPL 🌕 🌕 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑
ROP Compilation 🌕 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑 🌑

Dependencies?

B2R2 relies on a tiny set of external .NET libraries, and our design principle is to use a minimum number of libraries. Below is a list of libraries that we leverage.

API Documentation

We currently use fsdocs to generate our documentation: https://b2r2.org/APIDoc/.

Example

Let's try to use B2R2 APIs.

  1. First we create an empty directory DIRNAME:

    mkdir DIRNAME
cd DIRNAME

  2. We then create an empty console project with dotnet command line:

    $ dotnet new console -lang F#

  3. Add our nuget package B2R2.FrontEnd to the project:

    $ dotnet add package B2R2.FrontEnd.BinInterface

  4. Modify the Program.fs file with your favorite editor as follows:

    open B2R2
open B2R2.FrontEnd.BinInterface

[<EntryPoint>]
let main argv =
  let isa = ISA.OfString "amd64"
  let bytes = [| 0x65uy; 0xffuy; 0x15uy; 0x10uy; 0x00uy; 0x00uy; 0x00uy |]
  let hdl = BinHandle.Init (isa, bytes)
  let ins = BinHandle.ParseInstr (hdl, 0UL)
  ins.Translate hdl.TranslationContext |> printfn "%A"
  0

  5. We then just run it by typing: dotnet run. You will be able see lifted IR statements from your console. That's it! You just lifted an Intel instruction with only few lines of F# code!

Build

Building B2R2 is fun and easy. All you need to do is to install .NET 8 SDK or above. Yea, that's it!

  • To build B2R2 in release mode, type make release or dotnet build -c Release in the source root.

  • To build B2R2 in debug mode, type make, or dotnet build in the source root.

For your information, please visit the official web site of F# to get more tips about installing the development environment for F#: http://fsharp.org/.

Credits

Members in SoftSec Lab. @ KAIST developed B2R2 in collaboration with Cyber Security Research Center (CSRC) at KAIST. See Authors for the full list.

Citation

If you plan to use B2R2 in your own research. Please consider citing our paper:

@INPROCEEDINGS{jung:bar:2019,
  author = {Minkyu Jung and Soomin Kim and HyungSeok Han and Jaeseung Choi and Sang Kil Cha},
  title = {{B2R2}: Building an Efficient Front-End for Binary Analysis},
  booktitle = {Proceedings of the NDSS Workshop on Binary Analysis Research},
  year = 2019
}

Publications

Here are papers using our work. Please create a PR if you want to add yours.

  • FunProbe: Probing Functions from Binary Code through Probabilistic Analysis, FSE 2023
  • How'd Security Benefit Reverse Engineers? The Implication of Intel CET on Function Identification, DSN 2022 (PDF)
  • Smartian: Enhancing Smart Contract Fuzzing with Static and Dynamic Data-Flow Analyses, ASE 2021 (PDF)
  • NTFuzz: Enabling Type-Aware Kernel Fuzzing on Windows with Static Binary Analysis, Oakland 2021 (PDF)