Hopper Script Reference

ckuethe edited this page Apr 22, 2015 · 12 revisions

You will find here all the public classes and methods that you can use to script Hopper with the Python language. Before using the scripting capabilities of Hopper, you have to understand how Hopper considers its documents. The main idea is that a document is a set of segments, each of them containing typed bytes. Indeed, let's consider a standard MachO file. It will contains at least one segment of code (usually named TEXT) containing many bytes. Hopper attach some information to each bytes of each segments. At the loading time, all bytes are set to the type TYPE_UNDEFINED. Then, starting from the entry point, Hopper will starts to set the type for some of them to TYPE_CODE, following the program control flow. When an instruction needs more than one byte, Hopper will set the type of the first byte to TYPE_CODE, and the following bytes to the TYPE_NEXT type.
Using the Python, you'll be able to manipulate the segments of disassembled files, retrieving information on bytes types, write or read data, change or create name of labels, etc... You'll usually starts at retrieving the current document, using the static method Document.getCurrentDocument().

I tried to named the functions in a way that makes it easy to find them. Feel free to contact me if something seems difficult to achieve, or if you have any suggestion. My e-mail address is bsr43@free.fr. Please note that you can use either, the integrated (very) light Python editor, or use a more convenient editor (like the insanely great TextMate editor). To use your own editor, simply click on the wheel, underneath the scripts list. This will open a Finder window where all scripts are. When you add, remove or edit files of this directory, Hopper automatically detects it.

    

Class Instruction

          getArchitecture

          getArgumentCount

          getFormattedArgument

          getInstructionLength

          getInstructionString

          getRawArgument

          isAConditionalJump

          isAnInconditionalJump

          stringForArchitecture


    

Class Segment

          disassembleWholeSegment

          getCommentAtAddress

          getFileOffset

          getFileOffsetForAddress

          getInlineCommentAtAddress

          getInstructionAtAddress

          getLength

          getName

          getNameAtAddress

          getNextAddressWithType

          getReferencesOfAddress

          getStartingAddress

          getTypeAtAddress

          isThumbAtAddress

          markAsCode

          markAsDataByteArray

          markAsDataIntArray

          markAsDataShortArray

          markAsProcedure

          markAsUndefined

          markRangeAsUndefined

          readByte

          setARMModeAtAddress

          setCommentAtAddress

          setInlineCommentAtAddress

          setNameAtAddress

          setThumbModeAtAddress

          setTypeAtAddress

          stringForType

          writeByte


    

Class Document

          ask

          getCurrentAddress

          getCurrentColumn

          getCurrentDocument

          getCurrentSegment

          getCurrentSegmentIndex

          getEntryPoint

          getHighlightedWord

          getNameAtAddress

          getSegment

          getSegmentAtAddress

          getSegmentCount

          getSegmentIndexAtAddress

          getSelectionAddressRange

          is64Bits

          log

          moveCursorAtAddress

          moveCursorAtEntryPoint

          refreshView

          selectAddressRange

          setNameAtAddress


Class Instruction

This class reprents a disassembled instruction. The class defines some constants, like ARCHITECTURE_UNKNOWN, ARCHITECTURE_i386 and ARCHITECTURE_X86_64

stringForArchitecture(t)

[static]

Helper method that converts one of the architecture value (ARCHITECTURE_UNKNOWN, ARCHITECTURE_i386, ARCHITECTURE_X86_64, ARCHITECTURE_ARM or ARCHITECTURE_ARM_THUMB) to a string value.

getArchitecture()

Returns the architecture.

getInstructionString()

Return a strings representing the instruction.

getArgumentCount()

Returns the number of argument.

getRawArgument(index)

Returns the instruction argument, identified by an index. The argument is not modified by Hopper, and represents the raw ASM argument.

getFormattedArgument(index)

Returns the instruction argument, identified by an index. The argument may have been modified according to the user, or by Hopper if a specific pattern has been detected.

isAnInconditionalJump()

Returns True if the instruction represents an inconditional jump.

isAConditionalJump()

Returns True if the instruction represents a conditional jump.

getInstructionLength()

Returns the instruction length in byte.

Class Segment

This class represents a segment of a disassembled file. The class defines some values that are used as the type of bytes of the disassembled file.

    TYPE_UNDEFINED : an undefined byte

    TYPE_NEXT : a byte that is part of a larger data type (ex, the second byte of a 4 bytes integer...)

    TYPE_BYTE : an integer of a single byte

    TYPE_SHORT : an integer of 2 bytes

    TYPE_INT : an integer of 4 bytes

    TYPE_LONG : an integer of 8 bytes

    TYPE_ASCII : an ASCII string

    TYPE_UNICODE : a UTF-8 string

    TYPE_CODE : an instruction

    TYPE_PROCEDURE : a procedure


The class defines the constant BAD_ADDRESS that is returned by some methods when the requested information is incorrect.

stringForType(t)

[static]

Helper method that converts one of the type value (TYPE_UNDEFINED, TYPE_NEXT, ...) to a string value.

getName()

Returns the name of the segment.

getStartingAddress()

Returns the starting address of the segment.

getLength()

Returns the length, in bytes, of the segment.

getFileOffset()

Returns the file offset of the beginning of the segment.

getFileOffsetForAddress(addr)

Returns the file offset of a particular address.

readByte(addr)

Read a byte at a given address. Returns 0 if the byte is read outside of the segment.

writeByte(addr,value)

Write a byte at a given address. Return True if the writting has succeed.

markAsUndefined(addr)

Mark the address as being undefined.

markRangeAsUndefined(addr,length)

Mark the address range as being undefined.

markAsCode(addr)

Mark the address as being code.

markAsProcedure(addr)

Mark the address as being a procedure.

markAsDataByteArray(addr,count)

Mark the address as being byte array.

markAsDataShortArray(addr,count)

Mark the address as being a short array.

markAsDataIntArray(addr,count)

Mark the address as being an int array.

isThumbAtAddress(addr)

Returns True is instruction at address addr is ARM Thumb mode.

setThumbModeAtAddress(addr)

Set the Thumb mode at the given address.

setARMModeAtAddress(addr)

Set the ARM mode at the given address.

getTypeAtAddress(addr)

Returns the type of the byte at a given address. The type can be TYPE_UNDEFINED, TYPE_NEXT, TYPE_BYTE, TYPE_SHORT, TYPE_INT, TYPE_LONG, TYPE_ASCII, TYPE_UNICODE, TYPE_CODE or TYPE_PROCEDURE. The method will returns -1 if the address is outside the segment.

setTypeAtAddress(addr,length,typeValue)

Set the type of a byte range. The type must be TYPE_UNDEFINED, TYPE_BYTE, TYPE_SHORT, TYPE_INT, TYPE_LONG, TYPE_ASCII, or TYPE_UNICODE.

getNextAddressWithType(addr,typeValue)

Returns the next address of a given type. The search begins at the given address, so the returned value can be the given address itself. If no address are found, the returned value is BAD_ADDRESS.

disassembleWholeSegment()

Disassemble the whole segment.

setNameAtAddress(addr,name)

Set the label name at a given address.

getNameAtAddress(addr)

Get the label name at a given address.

getCommentAtAddress(addr)

Get the prefix comment at a given address.

setCommentAtAddress(addr,comment)

Set the prefix comment at a given address.

getInlineCommentAtAddress(addr)

Get the inline comment at a given address.

setInlineCommentAtAddress(addr,comment)

Set the inline comment at a given address.

getInstructionAtAddress(addr)

Get the disassembled instruction at a given address.

getReferencesOfAddress(addr)

Get the list of address that reference a given address.

Class Document

This class represents the disassembled document. A document is a set of segments.

getCurrentDocument()

[static]

Returns the current document.

ask(msg)

[static]

Open a window containing a text field, and wait for the user to give a string value. Returns the string, or returns None if the Cancel button is hit.

log(msg)

Display a string message into the log window of the document.

getSegmentCount()

Returns the number of segment the document contains.

getSegment(index)

Returns a segment by index. The returned object is an instance of the Segment class. If the index of not in the range [0;count[, the function returns None.

getCurrentColumn()

Returns the column where the cursor currently is.

getSegmentIndexAtAddress(addr)

Returns the segment index for a particular address.

getSegmentAtAddress(addr)

Returns the segment for a particular address.

getCurrentSegmentIndex()

Returns the segment index where the cursor is. Returns -1 if the current segment cannot be located.

getCurrentSegment()

Returns the segment where the cursor is. Returns None if the current segment cannot be located.

getCurrentAddress()

Returns the address where the cursor currently is.

getSelectionAddressRange()

Returns a list, containing two addresses. Those address represents the range of bytes covered by the selection.

moveCursorAtAddress(addr)

Move the cursor at a given address.

selectAddressRange(addrRange)

Select a range of byte. The awaited argument is a list containing exactly two address.

is64Bits()

Returns True if the disassembled document is interpreted as a 64 bits binary.

getEntryPoint()

Returns the entry point of the document.

moveCursorAtEntryPoint()

Move the cursor at the entry point.

getHighlightedWord()

Returns the word that is currently highlighted in the assembly view.

setNameAtAddress(addr,name)

Set the label name at a given address.

getNameAtAddress(addr)

Get the label name at a given address.

refreshView()

Force the assembly view to be refresh.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.