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



1319
1320
1321
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1319

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



1424
1425
1426
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1424

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.



1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1471

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.



1432
1433
1434
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1432

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:



1601
1602
1603
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1601

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

#archSymbol

Get this instructions architecture.

Returns:

  • (Symbol)

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



1493
1494
1495
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1493

def arch
    return nil
end

#bitsInteger

Check if this instruction architecture is 32 or 64 bit.

Returns:



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

def bits
    return 0
end

#branch?true, false

Check if this instruction is a branch instruction.

Returns:

  • (true, false)


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

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.



1565
1566
1567
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1565

def branch_targets
    return []
end

#branch_typeSymbol?

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.



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

def branch_type
    return nil
end

#colorInteger?

Get this instructions color, if any.

Returns:

  • (Integer, nil)

    nil if no color set otherwise the color value.



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

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.



1580
1581
1582
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1580

def color=( color )
    return color
end

#lengthInteger

Get this instructions byte length.

Returns:

  • (Integer)

    The instructions length.



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

def length
    return nil
end

#modeSymbol, NilClass

Get this instruction mode, if any.

Returns:

  • (Symbol, NilClass)

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



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

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:



1590
1591
1592
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1590

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)


1609
1610
1611
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1609

def remove_operand_reference( operand_num )
    return false
end

#rvaInteger

Get the RVA location of this instruction.

Returns:



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

def rva
    return nil
end

#to_rawHash

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

Returns:

  • (Hash)

    The raw instruction hash.



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

def to_raw
    return nil
end

#to_sString

Get a string representation of this instruction.

Returns:

  • (String)

    This instruction as a string.



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

def to_s
    return nil
end

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

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

Yields:

  • (rinst)

    yields the next TCG instruction to the block.

Yield Parameters:



1542
1543
1544
# File 'C:/Program Files/Relyze/lib/relyze/core/executable_file_model.rb', line 1542

def to_tcg
    return []
end