dynamic binary analysis via platform emulation
Clone or download

README.md

usercorn

Build Status GoDoc Slack

Building

Usercorn depends on Go 1.6 or newer, as well as the latest unstable versions of Capstone, Unicorn, and Keystone.

make deps (requires cmake) will attempt to install all of the above dependencies into the source tree under deps/.

make will update Go packages and build usercorn

Example Commands

usercorn run bins/x86.linux.elf
usercorn run bins/x86_64.linux.elf
usercorn run bins/x86.darwin.macho
usercorn run bins/x86_64.darwin.macho
usercorn run bins/x86.linux.cgc
usercorn run bins/mipsel.linux.elf

usercorn run -trace bins/x86.linux.elf
usercorn run -trace -to trace.uc bins/x86.linux.elf
usercorn trace -pretty trace.uc
usercorn run -repl bins/x86.linux.elf

What.

  • Usercorn is an analysis and emulator framework, with a base similar to qemu-user.
  • It can run arbitrary binaries on a different host kernel, unlike qemu-user.
  • While recording full system state at every instruction.
  • to a serializable compact format capable of rewind and re-execution.
  • It's useful out of the box for debugging and dynamic analysis.
  • With an arch-neutral powerful lua-based scripting language and debugger.
  • It's also easy to extend and use to build your own tools.

Usercorn could be used to emulate 16-bit DOS, 32-bit and 64-bit ARM/MIPS/x86/SPARC binaries for Linux, Darwin, BSD, DECREE, and even operating systems like Redux.

Right now, x86_64 linux and DECREE are the best supported guests.

Why?

  • Usercorn aims to be a framework to simplify emulating and deeply hooking a userspace environment for many target architectures and kernel ABIs.
  • Debug stubborn binaries. I had a binary gdb refused to debug ("Program exited during startup."). No problem. Usercorn can single-step into the program for you.
  • Debug foreign architecture and OS binaries. You don't need a MIPS box. You don't need qemu-user. You don't even need Linux.
  • Write tools, like fuzzers, static analyzers, recompilers, memory and register analysis, overlay code coverage and machine state into IDA/Binary Ninja.
  • Selectively call functions from within a binary. Usercorn will map a binary and emulate the kernel for you.
  • Whatever you want. Open an issue if you have a cool debugging / reverse engineering idea I didn't think about - I may just implement it.

Caveats

  • Your userspace might be incredibly confusing to the target binary.
  • No API for memory mapped files yet (kinda, if mmap() currently gets a file descriptor argument it will manually copy the file into memory).
  • I only have maybe 20% of the posix syscalls implemented, which is enough to run basic binaries. Busybox works great.

See Also (credit: XKCD)

Universal converter