alt text

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?

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.
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 various binary analysis tasks, such as instruction lifting, CFG recovery, and etc.
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!
B2R2 is OS-Independent: it works on Linux, Mac, Windows, and etc. as long as .NET core supports it.
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.

<table> <tr> <th width="178px">CPU</th> <th width="96px" class="text-center">Docs</th> <th width="96px" class="text-center">Ins Parsing</th> <th width="96px" class="text-center">Disasm</th> <th width="96px" class="text-center">Lifting</th> <th width="96px" class="text-center">CFG Recovery</th> <th width="96px" class="text-center">Assembly</th> </tr> <tr> <td>x86</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> </tr> <tr> <td>x86-64</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> </tr> <tr> <td>ARMv7</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:first_quarter_moon:</td> <td align="center">:new_moon:</td> </tr> <tr> <td>ARMv8 (AArch64)</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:first_quarter_moon:</td> <td align="center">:new_moon:</td> </tr> <tr> <td>MIPS32</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:first_quarter_moon:</td> <td align="center">:new_moon:</td> </tr> <tr> <td>MIPS64</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:first_quarter_moon:</td> <td align="center">:new_moon:</td> </tr> <tr> <td>EVM</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:new_moon:</td> </tr> <tr> <td>TMS320C6000</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:new_moon:</td> <td align="center">:first_quarter_moon:</td> <td align="center">:new_moon:</td> </tr> <tr> <td>AVR</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:first_quarter_moon:</td> <td align="center">:new_moon:</td> </tr> <tr> <td>PA-RISC</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:new_moon:</td> <td align="center">:first_quarter_moon:</td> <td align="center">:new_moon:</td> </tr> <tr> <td>PPC32</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:first_quarter_moon:</td> <td align="center">:new_moon:</td> </tr> <tr> <td>SPARC</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:first_quarter_moon:</td> <td align="center">:new_moon:</td> </tr> <tr> <td>SH4</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:new_moon:</td> <td align="center">:first_quarter_moon:</td> <td align="center">:new_moon:</td> </tr> <tr> <td>RISC-V</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:first_quarter_moon:</td> <td align="center">:new_moon:</td> </tr> <tr> <td>S390</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:full_moon:</td> <td align="center">:new_moon:</td> <td align="center">:first_quarter_moon:</td> <td align="center">:new_moon:</td> </tr> </table>

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/B2R2/.

Example

Let's try to use B2R2 APIs.

First we create an empty directory DIRNAME:
```
mkdir DIRNAME
cd DIRNAME
```
We then create an empty console project with dotnet command line:
```
$ dotnet new console -lang F#
```
Add our nuget package B2R2.FrontEnd to the project:
```
$ dotnet add package B2R2.FrontEnd.API
```

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

open B2R2
open B2R2.FrontEnd

[<EntryPoint>]
let main argv =
  let isa = ISA "amd64"
  let bytes = [| 0x65uy; 0xffuy; 0x15uy; 0x10uy; 0x00uy; 0x00uy; 0x00uy |]
  let hdl = BinHandle(bytes, isa)
  let lifter = hdl.NewLiftingUnit()
  let ins = lifter.ParseInstruction 0UL // parse the instruction at offset 0
  lifter.LiftInstruction ins |> printfn "%A"
  0

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 9 SDK or above. Yea, that's it!

To build B2R2 in release mode, type dotnet build -c Release in the source root.
To build B2R2 in debug mode, type 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

B2R2

Install / Use

README

B2R2

B2R2?

Features?

Dependencies?

API Documentation

Example

Build

Credits

Citation