Class: Relyze::ExecutableFileModel::Instruction

Inherits:
Object
  • Object
show all
Defined in:
../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb

Defined Under Namespace

Modules: RawDecodedInstructionMixin

Class Method Summary (collapse)

Instance Method Summary (collapse)

Class Method Details

+ (String, NilClass) assemble(source, arch, pc = 0, mode = nil, resolver = nil)

Static method to assemble a source buffer.

Examples:

Assemble a simple ARM instruction in Thumb mode

Relyze::ExecutableFileModel::Instruction.assemble( "blx r0", :arm, 0, :thumb )

Assemble a sequence of x86 instructions

Relyze::ExecutableFileModel::Instruction.assemble( "add esp, 0x20; pop eax; ret", :x86 )

Assemble an x64 instruction and resolve a symbol name via a user supplied lambda

resolver = lambda do | name |
    if( name == 'foo' )
        return 0x41424344
    end
    return nil
end
Relyze::ExecutableFileModel::Instruction.assemble( "mov rax, qword ptr [foo]", :x64, 0, nil, resolver )

Parameters:

  • source (String)

    The source to assemble

  • arch (Symbol)

    The architecture to assemble, either :x86, :x64 or :arm

  • pc (FixNum) (defaults to: 0)

    The program counter virtual address to use

  • mode (Symbol, NilClass) (defaults to: nil)

    The instruction mode to use, default to nil. If arch is :arm, mode can be :thumb.

  • resolver (Proc, NilClass) (defaults to: nil)

    The callback to use when resolving unknown symbol names.

Returns:

  • (String, NilClass)

    Returns a string containing the raw bytes or nil on failure



1276
1277
1278
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1276

def Instruction.assemble( source, arch, pc=0, mode=nil, resolver=nil )
    return nil
end

+ (Hash, NilClass) disassemble(buffer, arch, pc = 0, mode = nil)

Static method to disassembles a single instruction and return a hash containing the raw decoded instruction. Same as to_raw but for disassembling arbitrary data.

Examples:

raw = Relyze::ExecutableFileModel::Instruction.disassemble( "\x48\x85\x04\x25\x93\x35\x07\x00", :x64, 0x00400000 )
# raw will be a hash containing the following...
{
    :mnemonic=>:mov, 
    :arch=>:x64, 
    :pc=>4194304, 
    :length=>7, 
    :vendor=>:any, 
    :_rex=>8, 
    :pfx_rex=>72, 
    :pfx_seg=>0, 
    :pfx_opr=>0, 
    :pfx_adr=>0, 
    :pfx_lock=>0, 
    :pfx_str=>0, 
    :pfx_bnd=>0, 
    :pfx_xacquire=>0, 
    :pfx_xrelease=>0, 
    :pfx_rep=>0, 
    :pfx_repe=>0, 
    :pfx_repne=>0, 
    :opr_mode=>64, 
    :adr_mode=>64, 
    :br_far=>0, 
    :br_near=>0, 
    :have_modrm=>1, 
    :modrm=>5, 
    :vex_op=>0, 
    :vex_b1=>0, 
    :vex_b2=>0, 
    :flags=> {
        :of=>:reset, 
        :sf=>:modified, 
        :zf=>:modified, 
        :af=>:undefined, 
        :pf=>:modified,
        :cf=>:reset, 
        :tf=>:unchanged, 
        :if=>:unchanged, 
        :df=>:unchanged, 
        :nf=>:unchanged, 
        :rf=>:unchanged
    },
    :operands=> [
        {
            :read=>false, 
            :write=>true, 
            :type=>:register, 
            :size=>64, 
            :base=>:rax, 
            :index=>nil, 
            :scale=>0, 
            :offset=>0, 
            :lval=> {
                :sbyte=>0, 
                :ubyte=>0, 
                :sword=>0, 
                :uword=>0, 
                :sdword=>0, 
                :udword=>0, 
                :sqword=>0, 
                :uqword=>0, 
                :ptr_seg=>nil, 
                :ptr_off=>nil
            }
        }, 
        {
            :read=>true, 
            :write=>false, 
            :type=>:memory, 
            :size=>64, 
            :base=>:rip, 
            :index=>nil, 
            :scale=>0, 
            :offset=>32, 
            :lval=> {
                :sbyte=>-110, 
                :ubyte=>146, 
                :sword=>13714, 
                :uword=>13714, 
                :sdword=>472466, 
                :udword=>472466, 
                :sqword=>472466, 
                :uqword=>472466, 
                :ptr_seg=>nil, 
                :ptr_off=>nil
            }
        }
    ]
}

Parameters:

  • buffer (String)

    The raw bytes to disassemble

  • arch (Symbol)

    The architecture to disassemble, either :x86, :x64 or :arm

  • pc (FixNum) (defaults to: 0)

    The program counter virtual address to use

  • mode (Symbol, NilClass) (defaults to: nil)

    The instruction mode to use, default to nil. If arch is :arm, mode can be :thumb.

Returns:

  • (Hash, NilClass)

    Returns a hash containing the raw disassembly or nil on failure



1381
1382
1383
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1381

def Instruction.disassemble( buffer, arch, pc=0, mode=nil )
    return nil
end

+ (Array<Hash>?) disassemble_all(buffer, arch, pc = 0, mode = nil) {|raw| ... }

Disassembles a sequence of instructions and either yield each raw decoded instruction to a block or return an array of raw decoded instructions if no block is given.

Examples:

buffer = "\x90\x8B\xEC\xCC"
Relyze::ExecutableFileModel::Instruction.disassemble_all( buffer, :x86, 0x00401000 ) do | inst |
    print_message( "0x%08X: %s" % [ inst.pc, inst.to_asm ] )
end

Parameters:

  • buffer (String)

    the raw bytes to disassemble

  • arch (Symbol)

    the architecture to disassemble, either :x86, :x64 or :arm

  • pc (FixNum) (defaults to: 0)

    the program counter offset to use

  • mode (Symbol, NilClass) (defaults to: nil)

    the instruction mode to use, default to nil. If arch is :arm, mode can be :thumb.

Yields:

  • (raw)

    yields the raw decoded instruction to the block.

Yield Parameters:

  • raw (Hash)

    The raw decoded instruction value.

Returns:

  • (Array<Hash>, nil)

    An array of raw decoded instructions or nil.



1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1428

def Instruction.disassemble_all( buffer, arch, pc=0, mode=nil )
    result = nil
    while buffer.length > 0
        inst = Relyze::ExecutableFileModel::Instruction.disassemble( buffer, arch, pc, mode )
        break if inst.nil?
        if( block_given? )
            yield inst
        else
            if( result.nil? )
                result = ::Array.new
            end
            result << inst
        end
        buffer = buffer[inst[:length]..buffer.length]
        pc    += inst[:length]
    end
    result
end

+ (String) to_asm(raw)

Helper method to convert a raw decoded instruction Hash into its assembly String representation.

Parameters:

  • raw (Hash)

    The raw decoded instruction hash.

Returns:

  • (String)

    The instructions assembly text.



1389
1390
1391
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1389

def Instruction.to_asm( raw )
    return nil
end

Instance Method Details

- (Relyze::ExecutableFileModel::Reference?) add_operand_reference(operand_num, target_rva, target, flags = nil)

Add a new reference from an instruction operand to a target location.

Parameters:

  • operand_num (FixNum)

    A 1 based operand number to add this references, e.g. 1 for the first operand, 2 for the second and so on.

  • target_rva (FixNum)

    The RVA location where this reference is to. The target_rva must be inside the target bock.

  • target (BasicBlock)

    The target block where this reference is to.

  • flags (Array<Symbol>, nil) (defaults to: nil)

    Optional flags to describe the reference. May contain :controlflow, :true, :false :unconditional. If :controlflow is used, an implicit reference is created, both the owner (this block) and target must be of type :code. If :controlflow is not used, then an explicit reference is created.

Returns:



1550
1551
1552
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1550

def add_operand_reference( operand_num, target_rva, target, flags = nil)
    return nil
end

- (Symbol) arch

Get this instructions architecture.

Returns:

  • (Symbol)

    Either :x86, :x64 or :arm



1450
1451
1452
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1450

def arch
    return nil
end

- (FixNum) bits

Check if this instruction architecture is 32 or 64 bit.

Returns:

  • (FixNum)

    Either 32 or 64.



1463
1464
1465
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1463

def bits
    return 0
end

- (true, false) branch?

Check if this instruction is a branch instruction.

Returns:

  • (true, false)


1498
1499
1500
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1498

def branch?
    return false
end

- (Array<FixNum>?) branch_targets {|rva| ... }

If this instruction is a branch instruction, get every known potential branch RVA, if ant.

Yields:

  • (rva)

    yields the rva to the block.

Yield Parameters:

  • rva (FixNum)

    A potential branch target RVA location.

Returns:

  • (Array<FixNum>, nil)

    An array of potential branch target RVA locations.



1514
1515
1516
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1514

def branch_targets
    return []
end

- (Symbol?) branch_type

If this instruction is a branch instruction, get the type of branch.

Returns:

  • (Symbol, nil)

    Either :return, :call, :conditional_jump, :unconditional_jump, :interrupt or nil if not a branch.



1505
1506
1507
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1505

def branch_type
    return nil
end

- (FixNum?) color

Get this instructions color, if any.

Returns:

  • (FixNum, nil)

    nil if no color set otherwise the color value.



1521
1522
1523
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1521

def color
    return nil
end

- (FixNum?) color=(color)

Set or clear this instructions color.

Parameters:

  • color (FixNum, nil)

    If nil then clear the color otherwise set the color.

Returns:

  • (FixNum, nil)

    The color value.



1529
1530
1531
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1529

def color=( color )
    return color
end

- (FixNum) length

Get this instructions byte length.

Returns:

  • (FixNum)

    The instructions length.



1477
1478
1479
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1477

def length
    return nil
end

- (Symbol, NilClass) mode

Get this instruction mode, if any.

Returns:

  • (Symbol, NilClass)

    The instructions mode. If arch is :arm, mode can be either :arm or :thumb.



1457
1458
1459
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1457

def mode
    return nil
end

- (Array<Relyze::ExecutableFileModel::Reference>?) references(operand_num = nil) {|ref| ... }

Get every reference from this instruction.

Parameters:

  • operand_num (FixNum, nil) (defaults to: nil)

    Either nil for every reference or a 1 based operand number for the references for that operand, e.g. 1 for the first operand, 2 for the second and so on.

Yields:

  • (ref)

    yields the ref to the block.

Yield Parameters:

Returns:



1539
1540
1541
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1539

def references( operand_num=nil )
    return nil
end

- (true, false) remove_operand_reference(operand_num)

Remove a reference from an instruction operand and destroy the reference.

Parameters:

  • operand_num (FixNum)

    A 1 based operand number for the reference to remove, e.g. 1 for the first operand, 2 for the second and so on.

Returns:

  • (true, false)


1558
1559
1560
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1558

def remove_operand_reference( operand_num )
    return false
end

- (FixNum) rva

Get the RVA location of this instruction.

Returns:

  • (FixNum)

    An RVA location.



1470
1471
1472
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1470

def rva
    return nil
end

- (Hash) to_raw

Get a Hash containing the raw decoded instruction. See disassemble.

Returns:

  • (Hash)

    The raw instruction hash.



1491
1492
1493
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1491

def to_raw
    return nil
end

- (String) to_s

Get a string representation of this instruction.

Returns:

  • (String)

    This instruction as a string.



1484
1485
1486
# File '../Source/Plugin/RubyLib/relyze/core/executable_file_model.rb', line 1484

def to_s
    return nil
end