Scallop Shell - Debugger and Decompiler for Polymorphic code

Linux, macOS in development

GDB, pwndbg, Ghidra, IDA, are the current industry standards in reverse engineering. They are not well optimized for reverse engineering polymorphic binaries. The debuggers statically disassemble memory instead of displaying currently run instructions. They also aren't supported on Windows, and the windows debuggers are mostly GUI based. The decompilers completely break once you involve polymorphic code.

scallop [OPTIONS]


OPTIONS:
  -h,     --help              Print this help message and exit 
  -f,     --file REQUIRED     Filepath to target binary
  -a,     --arch TEXT         Target Architecture, whatever the suffix of the QEMU binary
                                 is (qemu-riscv64 -> riscv64, qemu-aarch64 -> aarch64)
  -s,     --system BOOLEAN    Is system? 

99% of people should use install.sh which will do the full installation for you, including package dependencies. However, some people may need to do a custom build in case they want to use a different QEMU src or some other reason. If you want to do custom things, follow the instructions below:

Build QEMU from source, make sure the TCG Plugin flags are set. Without this, the Linux native implementation will not work. Then, go to ~/.bashrc,

export QEMU_SRC_DIR= # Source directory for the custom QEMU build (only if building plugin from source!)
export SCALLOP_QEMU_BUILD= # Build path of QEMU
export SCALLOP_QEMU_PLUGIN= # Plugin path for scallop_plugin.so
export SCALLOP_SOURCE= # High level directory for Scallop Shell (where this README is)

Then download the capstone package. WITHOUT THIS THIS WILL NOT FUNCTION. For me in Fedora, it'll be:

sudo dnf install capstone        # Just running the precompiled binary
sudo dnf install capstone-devel  # Compiling from source

For the decompiler, run:

sudo dnf install llvm-devel

But your specific install command may vary, check the documentation for YOUR OS / Distro.

Then, run in the main project directory:

chmod +x ./build.sh
./build.sh

This will compile it using CMake and do all the linking for you.

If you want to add it to your command line, copy paste this into your .bashrc file (located in ~/)

export PATH=$PATH:~/path/to/package

You can also just move it to your /usr/bin/. I don't see a downside to this.

If you don't want to install Keystone, you can specify --no-keystone on install.sh.

The controls right now subject to change. CtrlS will assign you to the CLI, CtrlA to the memory display, CtrlD the disassembly, CtrlI for the I/O display. If you want to patch the bytes in memory or code display, the display must be selected. This is indicated by the window being highlighted. Up and Down arrows do different things in different windows (CLI and I/O display the up arrow lets you go to the memory display, the other displays have scrolling instead). If you want to access the other tabs, you can click to change the window shown.

One feature of Scallop Shell is live patching in the byte displays. If you want to change any of the bytes in the display, just click on the byte you want to change. Of course, the only values you can enter are 0-9 and A-F. Once you're done patching the bytes, hit enter and it'll save. You can hit Shift+Z to undo the edits you made UNTIL you step to the next instruction. Upon stepping, the live patcher will send a request to the emulator to modify the memory you changed. This then clears the history, so undoing is no longer possible. You can still edit it again of course.

In the memory display, there is a button "Autopatch". When this is selected, whatever you have queued up to patch after you step in the binary will automatically patch again when you get to that breakpoint.

You can take notes on the Notepad tab about what you're working on. Ctrl+S to save. When you open up that binary in Scallop Shell again, it'll open your old notes back up.

You can run "step N", with N being the amount of instructions you want to step (this can be left blank for a default of 1). the "focus" command will filter out all memory outside of the low and high argument you specify (for example, "focus 0x400000 0x500000" will only output the instructions inside that range). Hitting enter will run the last command. Currently, all instructions executed outside of the binary range are ignored. This leaves things like mmap() with executable memory unhandled by Scallop Shell. This will be fixed in a later version.

Symbols are stolen from a seperate GDB session. GDB is not used in the instrumentation of this at all. It is only used as a database for symbols. I would certainly make a worse symbol parser than 30 years and a million lines of code from thousands of devs. If you are getting irrelevant symbols (or just want them off), there is a checkmark on the top right of the Disassembly panel (it says "Symbol: " and on by default) which when deactivated will stop displaying all symbols and only show raw assembly.

Scallop Shell shows you the instruction right before it runs. So if you want to patch anything before it runs it'll let you.

Break anywhere you want by putting "break 0x" , followed by the instruction to break at.

break 0x400360

You can also point and click the squares to the left of the disassembled instructions to toggle a breakpoint. Ctrl B over the disassembly display will open up an input box for you to write a path to a Python script. This breakpoint will then show up as blue, and when reached, will automatically execute the target Python script. This could be something like a pwntools script, some shell commands, or network traffic. You are limited by your imagination.

You can monitor all File I/O done by the target binary through the bottom right tab, titled I/O. CtrlF lets you watch what the binary is outputting through selected file descriptors, CtrlAltF lets you send your own data through to a different selection of file descriptors.

There is a built in assembler to make code injection much easier. It is located on the right window. By default the target binary's architecture (if supported by Keystone) is selected, but you can select it to be any language supported and also toggle Endianness and syntax (Intel vs AT&T).

You can select different active vCPUs and threads and instrument them seperately on the CPU tab. Switching between them lets you step through one without touching the other, and swapping back.

Currently very experimental. It reconstructs the binary from the runtime instruction dump CSV, only with the instructions that have been run. The theory is there and the implementation is buggy. For now, please use standard reverse engineering workflows. Development on the decompiler is dynamic, and constant changes will occur until it is at a working stage.

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

You are free to use, modify, and distribute this software. If you offer it as a service or redistribute modified versions, you must make the full source code available under the same license.

Commercial relicensing may be available in the future.

The project name and logo are trademarks of SHUROKO.EXE. Use of the name or logo in commercial offerings requires explicit permission. This project is not affiliated with, endorsed by, or sponsored by any company unless explicitly stated.

Use of this software does not imply endorsement by the author.

By contributing to this project, you agree to the Contributor License Agreement (CLA). The CLA allows the maintainer to relicense contributions while contributors retain copyright to their work.