/* CAT(1) */

By Jeff White (karttoon)

I've been having a lot of fun with Capstone, Keystone, and Unicorn lately. It's such a robust set of tools that's extremely easy to work with and yet super powerful - all the things you really want in tools. More importantly though, they are fantastic learning tools because they force you to think about and understand lower-level interactions more intimately! As such, anytime I run into an issue lately I try to think of whether or not I can write a quick a little program to utilize their Python bindings.

A quick recap but Capstone is a disasembler, Keystone is an assembler, and Unicorn is an emulation enginge. To that end, I wanted to post about two simple tools I've written this week for daily usage that highlight all three of the libraries. I've found myself already using these tools a lot since I wrote them and I feel they've already paid for themselves. Hopefully someone else gets some usage out of 'em!


The asm_buddy program is a small script using Capstone/Keystone to assemble/disassemble x86 and x64 instructions direction from the command line.

You can add the below functions into your .bashrc or .bash_profile for quick access to either.

asma() { python ~/Scripts/OneOffs/asm_buddy.py -f a -i "$@" } asmd() { python ~/Scripts/OneOffs/asm_buddy.py -f d -i "$@" }

Using the functions above, it's pretty straight forward.

For assembling -

$ asma 'jmp esp; inc ecx; call 0x400100' \xFF\xE4\x41\xE8\xF8\x00\x40\x00

For disassembling -

$ asmd 'ffe441e8f8004000' jmp esp inc ecx call 0x1400100

A couple of other options can be used directly for more control over architecture.

usage: asm_buddy.py [-h] [-a {x86,x64}] -i INPUT -f {a,d} Generate ASM or disasemble bytes. ASM should be semi-colon separated (";"). optional arguments: -h, --help show this help message and exit -a {x86,x64}, --arch {x86,x64} Architecture - x86 or x64. -i INPUT, --input INPUT Your input to assemble or disassemble. -f {a,d}, --func {a,d} Assemble [a] or Disassemble [d].



The shellbug program is a basic command-line, text-based, shellcode debugger using Capstone/Unicorn.

I wanted to put together a small tool for stepping forward and backward through basic shellcode interactively. It doesn't currently support external depedencies like API's but it's good for testing assembly you write for exploits or whatever.

The below ASM is a good example 'Hello World' that touches most aspects of the program.

inc eax; dec ecx; add esi, 0x1000041; push 0x6c6c6548; cmp eax, ecx; je 1; xor ecx, ecx; mov dword ptr [esi], 0x2d15622d; xor byte ptr ds:[esi], 0x42; inc esi; inc edi; cmp edi, 4; jle 25; xor esi, esi; add esi, 0x1000045; mov dword ptr [esi], 0x00262e30; pop eax; mov dword ptr [0x100003D], eax; xor edi, edi; jmp 25;

The program takes shellcode from STDIN and then emulates it in a familiar debugging interface.

python shellbug.py '\x40\x49\x81\xC6\x41\x00\x00\x01\x68\x48\x65\x6C\x6C\x39\xC8\x74\xF0\x31\xC9\xC7\x06\x2D\x62\x15\x2D\x80\x36\x42\x46\x47\x83\xFF\x04\x7E\xF6\x31\xF6\x81\xC6\x45\x00\x00\x01\xC7\x06\x30\x2E\x26\x00\x58\xA3\x3D\x00\x00\x01\x31\xFF\xEB\xDE'

Currently it only supports four basic commands but it's a good start.

's' = Step forward in execution one instruction 'b' = Step backwards in execution one instruction 'd <address>' = Change memory dump (botton-left) location to specified address 'q' = Quit the program


It's probably quite buggy as I wrote it over the course of a night but I haven't seen too many issues yet beyond typical emulation problems where the environment wasn't staged correctly.


Older posts...