Keystone Engine Assembler

0.9.2 · active · verified Fri Apr 17

Keystone Engine is a lightweight multi-architecture assembler framework, providing Python bindings to its powerful C core. It supports various architectures including X86, ARM, ARM64, MIPS, PowerPC, SPARC, SystemZ, and more. The current version is 0.9.2, and it maintains a stable release cadence focused on feature enhancements and bug fixes.

Common errors

```
ImportError: No module named 'keystone'
```
cause The Python package is named `keystone-engine` on PyPI, but its internal module is `keystone`. This error usually occurs if the package was not installed or if there's a virtual environment issue.

fix Ensure `keystone-engine` is installed correctly: `pip install keystone-engine`. If in a virtual environment, ensure it's activated.
```
keystone.KeystoneError: Invalid architecture (KS_ERR_ARCH)
```
cause The architecture specified during `Ks` initialization is invalid or not supported by Keystone.

fix Verify that you are using a valid `KS_ARCH_*` constant (e.g., `KS_ARCH_X86`, `KS_ARCH_ARM`). Refer to the `keystone` module for available constants.
```
keystone.KeystoneError: Syntax error (KS_ERR_ASM_SYNTAX)
```
cause The provided assembly instruction string is syntactically incorrect for the chosen architecture and mode.

fix Review the assembly instruction for typos, incorrect registers, or unsupported mnemonics. Ensure it conforms to the target architecture's assembly syntax.

Warnings

gotcha Incorrectly specifying the architecture (KS_ARCH_*) or mode (KS_MODE_*) can lead to assembly failures or incorrect output. Always ensure these constants match the target CPU and instruction set.
Fix: Carefully select the `KS_ARCH_*` and `KS_MODE_*` constants when initializing `Ks`. For example, `Ks(KS_ARCH_ARM, KS_MODE_ARM + KS_MODE_THUMB)` for ARM Thumb mode.
gotcha Assembly instructions are case-insensitive for most architectures, but the syntax must be correct for the chosen architecture. Malformed instructions will raise `KeystoneError: Syntax error`.
Fix: Double-check the assembly instruction string against the target architecture's syntax. Use `try...except KeystoneError` to gracefully handle assembly failures.
gotcha The `Ks.asm()` method expects a byte string (e.g., `b"inc eax"`) for the instruction. Passing a regular string might work on some Python versions or implicitly convert, but explicit byte strings are safer and more consistent.
Fix: Always provide assembly instructions as byte strings, e.g., `ks.asm(b"mov rax, 0")`.

Install

pip install keystone-engine Install Python package

Imports

Ks
```
from keystone import Ks
```
The main assembler class.
KS_ARCH_X86
```
from keystone import KS_ARCH_X86, KS_MODE_32
```
Constants for architecture and mode selection. Typically imported along with Ks.
KeystoneError
```
from keystone import KeystoneError
```
The base exception class for Keystone operations.

Quickstart

This quickstart demonstrates how to initialize the Keystone assembler for a specific architecture and mode (X86-32bit) and then assemble a simple assembly instruction string into its corresponding bytecode. It also shows basic error handling.

from keystone import * 

try:
    # Initialize Keystone for X86-32bit architecture
    ks = Ks(KS_ARCH_X86, KS_MODE_32)
    
    # Assemble a simple instruction
    opcode, count = ks.asm(b"inc eax")
    
    print(f"Assembled instruction bytes: {opcode}")
    print(f"Number of instructions assembled: {count}")
    
    # Example with multiple instructions
    opcode_multi, count_multi = ks.asm(b"add ecx, 10; mov eax, ebx")
    print(f"Assembled multiple instructions bytes: {opcode_multi}")
    print(f"Number of instructions assembled: {count_multi}")

except KeystoneError as e:
    print(f"Keystone error: {e}")

view raw JSON →