Keystone.js

Port of the Keystone assembler framework for JavaScript/WASM. Powered by Emscripten.

Requirements: JavaScript environment with WebAssembly and BigInt support.

Notes: Keystone is a lightweight multi-architecture assembler framework originally developed by Nguyen Anh Quynh et al. and released under a dual GPLv2 and commercial license. More information about contributors and license terms can be found in the files AUTHORS.TXT, CREDITS.TXT, COPYING, EXCEPTIONS-CLIENT and LICENSE-COM.TXT of the keystone submodule in this repository.

Installation

To add Keystone.js to your web application, include it with:

<script src="keystone.js"></script>

or install it with the NPM command:

npm install @alexaltea/keystone-js

Usage

// Input: Assembly
const assembly =
   `inc   rax
    call  0x10040
    mov   rax, qword ptr[rdx + 4]
    sub   esp, 0x100
    pop   rbx`;

MKeystone().then((ks) => {
    // Initialize the encoder
    var a = new ks.Keystone(ks.ARCH_X86, ks.MODE_64);

    // Choose preferred syntax
    a.option(ks.OPT_SYNTAX, ks.OPT_SYNTAX_INTEL);

    // Assemble instructions
    var result = a.asm(assembly);
    console.log(result.failed); // false
    console.log(result.count); // 5
    console.log(result.mc); // Uint8Array([0x48, 0xFF, 0xC0, ...])

    // Delete encoder
    a.close();
});

Building

To build the Keystone.js library:

1. Clone this repository including its submodules:

   git clone --recursive https://github.com/AlexAltea/keystone.js

2. Install the latest Python 3.x, CMake and the Emscripten SDK. Follow the corresponding instructions and make sure all environment variables are configured correctly.

3. Run the build script:

   python3 build.py

Build artifacts will be saved to dist.

[!TIP] Pass architecture names to produce a smaller, single-architecture bundle (e.g. python3 build.py x86), or python3 build.py --release to build every variant.