keystone
Keystone assembler framework: Core (Arm, Arm64, Hexagon, Mips, PowerPC, Sparc, SystemZ & X86) + bindings
Top Related Projects
Unicorn CPU emulator framework (ARM, AArch64, M68K, Mips, Sparc, PowerPC, RiscV, S390x, TriCore, X86)
Capstone disassembly/disassembler framework for ARM, ARM64 (ARMv8), Alpha, BPF, Ethereum VM, HPPA, LoongArch, M68K, M680X, Mips, MOS65XX, PPC, RISC-V(rv32G/rv64G), SH, Sparc, SystemZ, TMS320C64X, TriCore, Webassembly, XCore and X86.
UNIX-like reverse engineering framework and command-line toolset
edb is a cross-platform AArch32/x86/x86-64 debugger.
Quick Overview
Keystone is a lightweight multi-platform, multi-architecture assembler framework. It offers high performance and flexibility, supporting various architectures including ARM, ARM64, MIPS, PPC, SPARC, SystemZ, and x86/x64.
Pros
- Multi-architecture support, allowing for versatile assembly across different platforms
- High performance and lightweight design
- Customizable syntax for specific assembly dialects
- Bindings available for multiple programming languages
Cons
- Limited to assembly tasks, not a full-featured disassembler or emulator
- May require additional tools for more complex reverse engineering tasks
- Learning curve for users unfamiliar with assembly languages
- Documentation could be more comprehensive for advanced use cases
Code Examples
- Basic x86 assembly:
from keystone import *
# Initialize engine for x86 32-bit
ks = Ks(KS_ARCH_X86, KS_MODE_32)
# Assemble a string
encoding, count = ks.asm("mov eax, 1")
print("%s = %s (number of statements: %u)" % ("mov eax, 1", encoding, count))
- ARM assembly with custom syntax:
from keystone import *
# Initialize engine for ARM
ks = Ks(KS_ARCH_ARM, KS_MODE_ARM)
# Set ARM syntax to alternative syntax (e.g., UAL)
ks.syntax = KS_OPT_SYNTAX_NASM
# Assemble a string
encoding, count = ks.asm("MOV r0, #1")
print("%s = %s (number of statements: %u)" % ("MOV r0, #1", encoding, count))
- Error handling:
from keystone import *
try:
# Initialize engine for MIPS
ks = Ks(KS_ARCH_MIPS, KS_MODE_MIPS32)
# Try to assemble an invalid instruction
encoding, count = ks.asm("invalid instruction")
except KsError as e:
print("ERROR: %s" % e)
Getting Started
To get started with Keystone:
-
Install Keystone:
pip install keystone-engine
-
Import and use in your Python script:
from keystone import * # Initialize an x86-64 engine ks = Ks(KS_ARCH_X86, KS_MODE_64) # Assemble some x86-64 code code = "mov rax, 0x1122334455667788" encoding, count = ks.asm(code) print("Assembled %d instruction(s)" % count) print("Encoding: %s" % ''.join('{:02x}'.format(x) for x in encoding))
This example initializes Keystone for x86-64 architecture and assembles a simple instruction, printing the resulting encoding.
Competitor Comparisons
Unicorn CPU emulator framework (ARM, AArch64, M68K, Mips, Sparc, PowerPC, RiscV, S390x, TriCore, X86)
Pros of Unicorn
- More comprehensive emulation capabilities, supporting full system emulation
- Wider architecture support, including ARM, MIPS, SPARC, and more
- Larger and more active community, with frequent updates and contributions
Cons of Unicorn
- Higher resource consumption due to full emulation capabilities
- Steeper learning curve for beginners compared to Keystone's simpler assembly focus
- Potentially slower performance for basic assembly tasks
Code Comparison
Unicorn (emulating x86 code):
from unicorn import *
from unicorn.x86_const import *
code = b"\x41\x4a" # INC ecx; DEC edx
mu = Uc(UC_ARCH_X86, UC_MODE_32)
mu.mem_map(0x1000, 0x1000)
mu.mem_write(0x1000, code)
mu.emu_start(0x1000, 0x1000 + len(code))
Keystone (assembling x86 code):
from keystone import *
code = "INC ecx; DEC edx"
ks = Ks(KS_ARCH_X86, KS_MODE_32)
encoding, count = ks.asm(code)
print("Encoded bytes:", encoding)
The code examples demonstrate Unicorn's focus on emulation and Keystone's emphasis on assembly, highlighting their different primary use cases.
Capstone disassembly/disassembler framework for ARM, ARM64 (ARMv8), Alpha, BPF, Ethereum VM, HPPA, LoongArch, M68K, M680X, Mips, MOS65XX, PPC, RISC-V(rv32G/rv64G), SH, Sparc, SystemZ, TMS320C64X, TriCore, Webassembly, XCore and X86.
Pros of Capstone
- More mature and widely adopted disassembly framework
- Supports a broader range of architectures (x86, ARM, MIPS, PowerPC, etc.)
- Extensive documentation and community support
Cons of Capstone
- Focused solely on disassembly, lacking assembly capabilities
- Can be more resource-intensive for large-scale disassembly tasks
- Steeper learning curve for beginners due to its comprehensive feature set
Code Comparison
Capstone (disassembly):
from capstone import *
CODE = b"\x55\x48\x8b\x05\xb8\x13\x00\x00"
md = Cs(CS_ARCH_X86, CS_MODE_64)
for i in md.disasm(CODE, 0x1000):
print("%x:\t%s\t%s" %(i.address, i.mnemonic, i.op_str))
Keystone (assembly):
from keystone import *
CODE = "mov rax, 0x1122334455667788"
ks = Ks(KS_ARCH_X86, KS_MODE_64)
encoding, count = ks.asm(CODE)
print("%s = %s (number of statements: %d)" %(CODE, encoding.hex(), count))
Keystone focuses on assembly, while Capstone specializes in disassembly. Keystone is newer and less mature but offers complementary functionality to Capstone. Both projects are maintained by the same team, providing a comprehensive solution for assembly and disassembly needs when used together.
UNIX-like reverse engineering framework and command-line toolset
Pros of radare2
- More comprehensive toolkit for reverse engineering and binary analysis
- Extensive command-line interface with powerful scripting capabilities
- Large and active community with frequent updates and contributions
Cons of radare2
- Steeper learning curve due to its complexity and vast feature set
- Can be resource-intensive for large binaries or complex analysis tasks
Code Comparison
radare2:
r2 -A binary
[0x00000000]> pdf @ main
Keystone:
from keystone import *
ks = Ks(KS_ARCH_X86, KS_MODE_32)
encoding, count = ks.asm("mov eax, 1")
Key Differences
Radare2 is a comprehensive reverse engineering framework, while Keystone is primarily an assembler library. Radare2 offers a wide range of features for binary analysis, disassembly, and debugging, making it suitable for complex reverse engineering tasks. Keystone, on the other hand, focuses on providing a lightweight and efficient assembler engine for various architectures.
Radare2's command-line interface allows for interactive analysis and scripting, whereas Keystone is typically used as a library integrated into other tools or projects. While Radare2 has a steeper learning curve, it offers more flexibility and power for advanced users. Keystone's simplicity makes it easier to integrate into existing projects but with a more limited scope.
edb is a cross-platform AArch32/x86/x86-64 debugger.
Pros of edb-debugger
- Full-featured graphical debugger with a user-friendly interface
- Supports multiple architectures and operating systems
- Includes advanced features like memory searching and editing
Cons of edb-debugger
- More complex to set up and use compared to Keystone
- Limited to debugging and reverse engineering tasks
- Larger codebase and resource footprint
Code Comparison
edb-debugger (C++):
void Debugger::step() {
if (attached()) {
ptrace(PTRACE_SINGLESTEP, active_thread(), 0, 0);
wait_debug_event();
}
}
Keystone (C):
ks_engine *ks;
ks_open(KS_ARCH_X86, KS_MODE_32, &ks);
ks_asm(ks, "mov eax, 1", 0, &encoded, &size, &count);
ks_close(ks);
Summary
edb-debugger is a comprehensive graphical debugger suitable for complex reverse engineering tasks, while Keystone is a lightweight assembler library focused on code generation. edb-debugger offers a more user-friendly interface but requires more setup, whereas Keystone provides a simple API for assembly tasks but lacks debugging capabilities. The choice between them depends on the specific needs of the project, with edb-debugger being better for in-depth analysis and Keystone for quick assembly operations.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Keystone Engine
Keystone is a lightweight multi-platform, multi-architecture assembler framework. It offers some unparalleled features:
- Multi-architecture, with support for Arm, Arm64 (AArch64/Armv8), Ethereum Virtual Machine, Hexagon, Mips, PowerPC, RISC-V, Sparc, SystemZ & X86 (include 16/32/64bit).
- Clean/simple/lightweight/intuitive architecture-neutral API.
- Implemented in C/C++ languages, with bindings for Java, Masm, C#, PowerShell, Perl, Python, NodeJS, Ruby, Go, Rust, Haskell, VB6 & OCaml available.
- Native support for Windows & *nix (with Mac OSX, Linux, *BSD & Solaris confirmed).
- Thread-safe by design.
- Open source - with a dual license.
Keystone is based on LLVM, but it goes much further with a lot more to offer.
Further information is available at http://www.keystone-engine.org
License
Keystone is available under a dual license:
-
Version 2 of the GNU General Public License (GPLv2). (I.e. Without the "any later version" clause.). License information can be found in the COPYING file and the EXCEPTIONS-CLIENT file.
This combination allows almost all of open source projects to use Keystone without conflicts.
-
For commercial usage in production environments, contact the authors of Keystone to buy a royalty-free license.
See LICENSE-COM.TXT for more information.
Compilation & Docs
See COMPILE.md file for how to compile and install Keystone.
More documentation is available in docs/README.md.
Contact
Contact us via mailing list, email or twitter for any questions.
Contribute
Keystone is impossible without generous support from our sponsors. We cannot thank them enough!
CREDITS.TXT records other important contributors of our project.
If you want to contribute, please pick up something from our Github issues.
We also maintain a list of more challenged problems in a TODO list.
Top Related Projects
Unicorn CPU emulator framework (ARM, AArch64, M68K, Mips, Sparc, PowerPC, RiscV, S390x, TriCore, X86)
Capstone disassembly/disassembler framework for ARM, ARM64 (ARMv8), Alpha, BPF, Ethereum VM, HPPA, LoongArch, M68K, M680X, Mips, MOS65XX, PPC, RISC-V(rv32G/rv64G), SH, Sparc, SystemZ, TMS320C64X, TriCore, Webassembly, XCore and X86.
UNIX-like reverse engineering framework and command-line toolset
edb is a cross-platform AArch32/x86/x86-64 debugger.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot