Class: Relyze::ExecutableFileModel::Instruction

Inherits:
Object
  • Object
show all
Defined in:
C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb

Defined Under Namespace

Modules: RawDecodedInstructionMixin

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

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

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, :arm or :arm64

  • pc (Integer) (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



1324
1325
1326
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1324

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

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

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, :arm or :arm64

  • pc (Integer) (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



1429
1430
1431
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1429

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

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

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, :arm or :arm64

  • pc (Integer) (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.



1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1476

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

.to_asm(raw) ⇒ String

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.



1437
1438
1439
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1437

def Instruction.to_asm( raw )
    return nil
end

Instance Method Details

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

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

Parameters:

  • operand_num (Integer) —

    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 (Integer) —

    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:



1606
1607
1608
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1606

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

#arch ⇒ Symbol

Get this instructions architecture.

Returns:

  • (Symbol) —

    Either :x86, :x64, :arm or :arm64



1498
1499
1500
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1498

def arch
    return nil
end

#bits ⇒ Integer

Check if this instruction architecture is 32 or 64 bit.

Returns:



1511
1512
1513
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1511

def bits
    return 0
end

#branch? ⇒ true, false

Check if this instruction is a branch instruction.

Returns:

  • (true, false) 


1554
1555
1556
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1554

def branch?
    return false
end

#branch_targets {|rva| ... } ⇒ Array<Integer>?

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 (Integer) —

    A potential branch target RVA location.

Returns:

  • (Array<Integer>, nil) —

    An array of potential branch target RVA locations.



1570
1571
1572
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1570

def branch_targets
    return []
end

#branch_type ⇒ Symbol?

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

Returns:

  • (Symbol, nil) —

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



1561
1562
1563
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1561

def branch_type
    return nil
end

#color ⇒ Integer?

Get this instructions color, if any.

Returns:

  • (Integer, nil) —

    nil if no color set otherwise the color value.



1577
1578
1579
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1577

def color
    return nil
end

#color=(color) ⇒ Integer?

Set or clear this instructions color.

Parameters:

  • color (Integer, nil) —

    If nil then clear the color otherwise set the color.

Returns:

  • (Integer, nil) —

    The color value.



1585
1586
1587
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1585

def color=( color )
    return color
end

#length ⇒ Integer

Get this instructions byte length.

Returns:

  • (Integer) —

    The instructions length.



1525
1526
1527
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1525

def length
    return nil
end

#mode ⇒ Symbol, NilClass

Get this instruction mode, if any.

Returns:

  • (Symbol, NilClass) —

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



1505
1506
1507
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1505

def mode
    return nil
end

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

Get every reference from this instruction.

Parameters:

  • operand_num (Integer, 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:



1595
1596
1597
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1595

def references( operand_num=nil )
    return nil
end

#remove_operand_reference(operand_num) ⇒ true, false

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

Parameters:

  • operand_num (Integer) —

    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) 


1614
1615
1616
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1614

def remove_operand_reference( operand_num )
    return false
end

#rva ⇒ Integer

Get the RVA location of this instruction.

Returns:



1518
1519
1520
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1518

def rva
    return nil
end

#to_raw ⇒ Hash

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

Returns:

  • (Hash) —

    The raw instruction hash.



1539
1540
1541
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1539

def to_raw
    return nil
end

#to_s ⇒ String

Get a string representation of this instruction.

Returns:

  • (String) —

    This instruction as a string.



1532
1533
1534
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1532

def to_s
    return nil
end

#to_tcg {|tinst| ... } ⇒ Object

Translate this instruction into a series of TCG instructions, which describe this instructions semantics.

Yields:

  • (tinst) —

    yields the next TCG instruction to the block.

Yield Parameters:



1547
1548
1549
 
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1547

def to_tcg
    return []
end
ef="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard 0.9.20 (ruby-2.6.5).