14 releases (8 breaking)

0.8.0 Apr 10, 2021
0.7.0 Apr 12, 2020
0.6.0 Apr 17, 2019
0.5.0 Sep 21, 2018
0.0.3 Apr 5, 2015

#1 in #disassemble

Download history 346/week @ 2020-12-25 2208/week @ 2021-01-01 2037/week @ 2021-01-08 1118/week @ 2021-01-15 2247/week @ 2021-01-22 3052/week @ 2021-01-29 1233/week @ 2021-02-05 1622/week @ 2021-02-12 971/week @ 2021-02-19 1627/week @ 2021-02-26 2614/week @ 2021-03-05 1510/week @ 2021-03-12 2265/week @ 2021-03-19 1590/week @ 2021-03-26 1805/week @ 2021-04-02 1368/week @ 2021-04-09

7,731 downloads per month
Used in 22 crates (10 directly)

MIT license

6MB
158K SLoC

C 52K SLoC // 0.1% comments Rust 32K SLoC // 0.0% comments Python 21K SLoC // 0.1% comments C# 19K SLoC // 0.1% comments Java 15K SLoC // 0.0% comments OCaml 14K SLoC // 0.0% comments VB6 3K SLoC // 0.2% comments Shell 787 SLoC // 0.1% comments PowerShell 516 SLoC // 0.3% comments C++ 484 SLoC // 0.1% comments Visual Studio Project 310 SLoC Batch 290 SLoC // 0.0% comments RPM Specfile 121 SLoC // 0.0% comments Visual Studio Solution 68 SLoC Prolog 28 SLoC

capstone-rs

Crates.io Badge

Linux/MacOS Travis CI Badge | Windows Appveyor CI Badge | FreeBSD Cirrus CI Badge

codecov

API Documentation

Bindings to the capstone library disassembly framework.

Requirements

capstone-rs uses the capstone-sys crate to provide the low-level bindings to the Capstone C library.

See the capstone-sys page for the requirements and supported platforms.

  • Minimum Rust Version: 1.36.0

Example

extern crate capstone;

use capstone::prelude::*;

const X86_CODE: &'static [u8] =
    b"\x55\x48\x8b\x05\xb8\x13\x00\x00\xe9\x14\x9e\x08\x00\x45\x31\xe4";

/// Print register names
fn reg_names<T, I>(cs: &Capstone, regs: T) -> String
where
    T: Iterator<Item = I>,
    I: Into<RegId>,
{
    let names: Vec<String> = regs.map(|x| cs.reg_name(x.into()).unwrap()).collect();
    names.join(", ")
}

/// Print instruction group names
fn group_names<T, I>(cs: &Capstone, regs: T) -> String
where
    T: Iterator<Item = I>,
    I: Into<InsnGroupId>,
{
    let names: Vec<String> = regs.map(|x| cs.group_name(x.into()).unwrap()).collect();
    names.join(", ")
}

fn example() -> CsResult<()> {
    let cs = Capstone::new()
        .x86()
        .mode(arch::x86::ArchMode::Mode64)
        .syntax(arch::x86::ArchSyntax::Att)
        .detail(true)
        .build()?;

    let insns = cs.disasm_all(X86_CODE, 0x1000)?;
    println!("Found {} instructions", insns.len());
    for i in insns.iter() {
        println!("");
        println!("{}", i);

        let detail: InsnDetail = cs.insn_detail(&i)?;
        let output: &[(&str, String)] =
            &[
                ("read regs:", reg_names(&cs, detail.regs_read())),
                ("write regs:", reg_names(&cs, detail.regs_write())),
                ("insn groups:", group_names(&cs, detail.groups())),
            ];

        for &(ref name, ref message) in output.iter() {
            println!("    {:12} {}", name, message);
        }
    }
    Ok(())
}

fn main() {
    if let Err(err) = example() {
        println!("Error: {}", err);
    }
}

Produces:

Found 4 instructions

0x1000: pushq %rbp
    read regs:   rsp
    write regs:  rsp
    insn groups: mode64

0x1001: movq 0x13b8(%rip), %rax
    read regs:
    write regs:
    insn groups:

0x1008: jmp 0x8ae21
    read regs:
    write regs:
    insn groups: jump

0x100d: xorl %r12d, %r12d
    read regs:
    write regs:  rflags
    insn groups:

To see more demos, see the examples/ directory. More complex demos welcome!

Features

  • use_bindgen: run bindgen to generate Rust bindings to Capstone C library instead of using pre-generated bindings (not recommended).

Reporting Issues

Please open a Github issue

Author

You may find a full list of contributors on Github.

License

MIT

Dependencies