Perl wrapper for the capstone library
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
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.