Perl wrapper for the capstone library
C++ Perl XS Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
lib
pkgs
scripts
t
.gitignore
.gitmodules
CHANGES
Capstone.xs
INSTALL
LICENSE
MANIFEST
Makefile.PL
README
README.md
ppport.h
typemap

README.md

NAME

Capstone - Perl extension for capstone-engine

SYNOPSIS

use Capstone ':all';

$cs = Capstone->new(CS_ARCH_X86, CS_MODE_64) || die "Can't init Capstone\n";
@insn = $cs->dis("\x4c\x8d\x25\xee\xa6\x20\x00\x90\xcd\x80", 0x040000a, 0);

foreach(@insn) {
  printf "0x%.16x    %s %s\n", $_->{address}, $_->{mnemonic}, $_->{op_str};
}

DESCRIPTION

This module is a Perl wrapper of the capstone-engine library.

Capstone is a disassembly framework with the target of becoming the ultimate disasm engine for binary analysis and reversing in the security community.

Created by Nguyen Anh Quynh, then developed and maintained by a small community, Capstone offers some unparalleled features:

- Support multiple hardware architectures: ARM, ARM64 (ARMv8), Mips, PPC, Sparc, SystemZ, XCore and X86 (including X86_64).

- Having clean/simple/lightweight/intuitive architecture-neutral API.

- Provide details on disassembled instruction (called \u201cdecomposer\u201d by others).

- Provide semantics of the disassembled instruction, such as list of implicit registers read & written.

- Implemented in pure C language, with lightweight wrappers for C++, C#, Go, Java, Lua, NodeJS, Ocaml, Python, Ruby, Rust & Vala ready (available in main code, or provided externally by the community).

- Native support for all popular platforms: Windows, Mac OSX, iOS, Android, Linux, *BSD, Solaris, etc.

- Thread-safe by design.

- Special support for embedding into firmware or OS kernel.

- High performance & suitable for malware analysis (capable of handling various X86 malware tricks).

- Distributed under the open source BSD license.

Further information is available at http://www.capstone-engine.org

METHODS

  • new(arch, mode)

    $cs = Capstone->new(CS_ARCH_X86, CS_MODE_32);
    

    Create a new capstone object. Take two arguments, the arch (CS_ARCH_*) and the mode (CS_MODE_*). See cs_open() in capstone-engine documentation

  • dis(code, address, num)

    @ins = $cs->dis("\xcd\x80", 0x080480bc, 1);
    

    Disassemble code, and return a list of disassembled instructions.

    See cs_disasm() in capstone-engine documentation.

    foreach(@ins) {
      printf "%.16x  %-32s %s %s\n",
             $_->{address},
             hexlify($_->{bytes}),
             $_->{mnemonic},
             $_->{op_str};
    }
    

    An instruction is represented with a hash ref, with fields :

    • {address}

      The address of the instruction

    • {mnemonic}

      The mnemonic of the instruction

    • {op_str}

      The operand string of the instruction

    • {bytes}

      The raw bytes of the instruction

    • {regs_read}

      If CS_OPT_DETAILS is set, it is a list of implicit registers read.

    • {regs_write}

      If CS_OPT_DETAILS is set, it is a list of implicit registers modified.

    • {groups}

      If CS_OPT_DETAILS is set, it is a list of group the instruction belong to.

  • set_option(type, value)

    $cs->set_option(CS_OPT_SYNTAX, CS_OPT_SYNTAX_ATT);
    

    Change the disassembly behavior.

    See cs_option() in capstone-engine documentation.

FUNCTIONS

  • version()

    ($maj, $min) = Capstone::version();
    

    Return a list of two scalars, the first is the major version, and the second is the minor version

    See cs_version() in capstone-engine documentation.

  • support(value)

    print "CS_ARCH_ALL supported\n" if(Capstone::support(CS_ARCH_ALL));
    

    Test if the library support an architecture. Use CS_ARCH_* constant (see capstone documentation)

    See cs_support() in capstone-engine documentation.

EXAMPLES

#!/usr/bin/perl

use ExtUtils::testlib;
use Capstone ':all';

use strict;
use warnings;

my $CODE = "\x4c\x8d\x25\xee\xa6\x20\x00\x90\x90\xcd\x80";
my $ADDRESS = 0x040000;

printf "Capstone version %d.%d\n", Capstone::version();
print "Support ARCH_ALL : " . Capstone::support(CS_ARCH_ALL) . "\n\n";

print "[+] Create disassembly engine\n";
my $cs = Capstone->new(CS_ARCH_X86, CS_MODE_64)
    || die "[-] Can't create capstone object\n";

print "[+] Set AT&T syntax\n";
$cs->set_option(CS_OPT_SYNTAX, CS_OPT_SYNTAX_ATT)
    || die "[-] Can't set CS_OPT_SYNTAX_ATT option\n";

print "[+] Disassemble some code\n\n";
my @insn = $cs->dis($CODE, $ADDRESS, 0);

foreach(@insn) {
    printf "    0x%.16x  %-30s   %s %s\n",
    $_->{address},
    hexlify($_->{bytes}),
    $_->{mnemonic},
    $_->{op_str};
}

print "[+] " . scalar(@insn) . " instructions disassembled\n";


sub hexlify {
    my $bytes = shift;

    return join ' ', map { sprintf "%.2x", ord($_) } split //, $bytes;
}

SEE ALSO

http://capstone-engine.org/

https://github.com/t00sh/perl-capstone

AUTHOR

Tosh, tosh@t0x0sh.org

CONTRIBUTORS

Vikas N Kumar vikas@cpan.org

COPYRIGHT AND LICENSE

Copyright (C) 2015-2016 by Tosh

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.