Exe Object

Exe

Exe object always points to the currently loaded application.

It provides a bunch of properties and a generous set of functions for accessing its internals and for setting up changes for a patch.

Table of Contents

• Properties
• Functions
  • User Input
  • Patch related
  • Section retrieval
  • Data Directory retrieval
  • Address Conversion
  • Content retrieval
  • Content setters
  • Content insertion
  • Content query

Properties

Name	Description
Exe.PEoffset	The PHYSICAL address of the PE header
Exe.ImageBase	Base Address where the exe is loaded in memory
Exe.BuildDate	The application's build date in the form "yyyymmdd"
Exe.Version	The linker version used for building this app in the form "major.minor"
Exe.Unpacked	Self explanatory
Exe.FileSize	Self explanatory
Exe.FilePath	Self explanatory
Exe.TestMode	Set to true when you are loading the app in the Test Bench

Functions

User Input

• Exe.GetUserInput(varName, dtype, title, prompt, defValue, constraints)

  This function allows you to collect inputs from user. It takes the following arguments:

  • varName

    Every input value needs a way to refer it later, For this purpose, we make use of a 'variable name'.

  • dtype

    DataType of the user input expected. The Dialog shown will differ based on this.

  • title & prompt

    As the name suggests these form the Title & Prompt used in the Dialog that pops up to fetch the user input.

  • defValue

    The default value for the input. This value is displayed in the Dialog that pops up and also as an initial value.

    You can opt to save or ignore default value by means of the saveDefault constraint explained below.

  • constraints

    This is an optional hash map specifying the constraints which vary based on the type of input and therefore it would be of the form

    {
        name1: <value1>,
        name2: <value2>
    }

    Following are the list of constraints currently recognized.

    • saveDefault

      Applicable for all DataTypes. Indicates that the tool should save default values or not (if user chooses them).

      If not specified then only D_InFile & D_OutFile types will save default values.

      In either case, if the default value is not being saved, the function will return false instead.

    • acceptText & rejectText

      Applicable for all DataTypes. Button Texts for the Acceptor (OK) & Rejector (Cancel) Buttons. These are more useful for D_Bool type.

    • min & max

      Lower & Upper limit overrides for numeric DataTypes (i.e. D_Int8, D_Int16, D_Int32, D_Uint8, D_Uint16, D_Uint16 & D_FontSize) respectively.

    • minLen & maxLen

      Length limits for string DataTypes (i.e. D_Text, D_Hex, D_FontName, D_InFile & D_OutFile).

      For D_Hex this corresponds to number of bytes.

      Without maxLen the strings would be limited to length of 32k.

      If a minLen is specified then the result is padded with space (0 for D_Hex) to meet the criterion.

    • align

      Used for string DataTypes as mentioned above.

      The align constraint specifies whether to keep the value aligned to right or left while padding to meet minLen constraint. Default alignment is right.

    • reversed

      Only used for D_Hex. Indicates whether the final value needs the byte order reversed (for little endian).

      By default, no reversal is done.

    • encoding

      Used with string DataTypes other than D_Hex to specify the Encoding desired. By default the string is considered to be ASCII encoded.

    • choices

      Mandatory constraint for D_List. Specifies the list of strings from which the user needs to choose one.

      While you can keep it empty, it will not be looking good.

    • defaultAlpha

      Only used for D_Color. Indicates that the Alpha component of the Default value need to be preserved, i.e. Even if the user selects a different alpha component it will be ignored.

    • ignoreAlpha

      Only used for D_Color. Indicates that the tool should ignore the alpha component while displaying the values in the ColorDialog.

      Makes more sense when used in tandem with defaultAlpha constraint.

    • order

      Only used for D_Color. Specifies the order in which the component bytes need to be saved.

      Need to be a combination of R, G, B & A. For e.g. "ARGB" which is also the default order

    • dataSize

      Only used for D_Bool. Specifies the number of bytes to be used for saving the result internally.

Patch related

• Exe.IsSelected(name)

  Check whether the Patch by the given name is currently selected.

• Exe.SetActivePatch(name)

  Set the Patch by the given name as the active one. All Set* and Add* functions setup changes into the active patch only.

• Exe.ClearPatch(name)

  Clear any setup done for the Patch by the given name i.e. all changes and reservations are gone.

Section retrieval

• Exe.GetSectBegin(stype, [atype])

  Retrieve the starting AddrType (atype) address of specified SectionType (stype).

  atype is optional and if omitted, PHYSICAL address is returned.

  In case of failure, the function returns -1.

• Exe.GetSectEnd(stype, [atype])
  

  Retrieve the ending AddrType (atype) address of specified SectionType (stype).

  atype is optional and if omitted, PHYSICAL address is returned.

  In case of failure, the function returns -1.

• Exe.GetSectSize(stype, [atype])

  Retrieve the AddrType (atype) address size of specified SectionType (stype). Equivalent to Exe.GetSectEnd - Exe.GetSectBegin.

  atype is optional and if omitted, PHYSICAL address size is returned.

  In case of failure, the function returns 0.

Data Directory retrieval

• Exe.GetDirAddr(dtype, [atype])

  Extract the Starting AddrType (atype) address of the data directory of the specified DirType (dtype).

  If atype is omitted, then the VIRTUAL address is returned.

  In case of failure, the function returns -1.

• Exe.GetDirSize(dtype)

  Extract the Size of the data directory of the specified DirType (dtype).

  In case of failure, it returns 0

Address Conversion

• Exe.Phy2Vir(addr, [stype])

  Convert a PHYSICAL addr ess to a VIRTUAL one and returns it.

  You can provide an optional SectionType (stype) argument to restrict conversion to a specific section (i.e. addr need to be in that section or the function fails).

  In case of failure, the function returns -1.

• Exe.Phy2Rva(addr, [stype])

  Similar to Exe.Phy2Vir, but we get the Relative Virtual Address instead (basically Exe.ImageBase isn't added).

  In case of failure, the function returns -1.

• Exe.Vir2Phy(addr, [stype])

  Does the exact opposite of Exe.Phy2Vir.

  In case of failure, the function returns -1.

• Exe.Rva2Phy(addr, [stype])

  Does the exact opposite of Exe.Phy2Rva.

  In case of failure, the function returns -1.

Content Retrieval

• Exe.GetInt8(from)
  Exe.GetInt16(from)
  Exe.GetInt32(from)

  Extract the next 8/16/32 bits (1/2/4 bytes) of data from the specified address as a signed integer respectively.

  In case of failure, the function returns 0.

• Exe.GetUint8(from)
  Exe.GetUint16(from)
  Exe.GetUint32(from)

  Extract the next 8/16/32 bits (1/2/4 bytes) of data from the specified address as an unsigned integer respectively.

  In case of failure, the function returns 0.

• Exe.GetHex(from, size)

  Extract the next size bytes from the specified address as a hex string.

  If the file doesnt have size bytes after from address, all the bytes after it are extracted.

  In case from is at the end of the file OR Exe doesnt have any file loaded, it returns an empty string.

• Exe.GetText(from, enc)
  Exe.GetText(from, size)
  Exe.GetText(from, enc, size)

  Extract the next size bytes from the specified address as a text string.

  If size isn't provided, then the tool looks for NULL termination to determine the length.

  enc is the Encoding required. If omitted, ASCII is used.

  In case from is at the end of the file OR at a NULL byte OR if Exe doesnt have any file loaded, it returns an empty string.

• Exe.GetTgtAddr(source, atype)
  Exe.GetTgtAddr(source, travel)
  Exe.GetTgtAddr(source, atype, travel)

  Extract the next travel bytes from the specified source address to calculate & return the target address. Used with CALLs & JMPs.

  atype is the expected AddrType of the calculated target address. If omitted, VIRTUAL address is returned.

  Similarly, travel defaults to 4, if omitted.

  In case of failure, returns -1.

Content setters

All the functions listed below stage changes to be applied when generating a target exe. All of them require an active Patch.

Therefore you cannot use these inside Extensions.

• Exe.SetInt8(addr, value)
  Exe.SetInt16(addr, value)
  Exe.SetInt32(addr, value)

  Adds an entry to overwrite 8/16/32 bits (1/2/4 bytes) of data at the specified addr ess with the signed integer value.

  Returns true if successful.

• Exe.SetUint8(addr, value)
  Exe.SetUint16(addr, value)
  Exe.SetUint32(addr, value)

  Adds an entry to overwrite 8/16/32 bits (1/2/4 bytes) of data at the specified addr ess with the unsigned integer value.

  Returns true if successful.

• Exe.SetHex(addr, hexstring)

  Adds an entry to overwrite data at the specified addr ess with a new hexstring.

  No of bytes to alter is determined from the byte count of the hexstring specified.

  Returns the number of bytes affected.

• Exe.SetText(addr, text, [enc])

  Adds an entry to overwrite data at the specified addr ess with a new text string having the specified Encoding (enc).

  If enc is omitted, text is considered to be ASCII encoded.

  No of bytes to alter is determined from the length of the text and the Encoding utilized.

  Returns the number of bytes affected.

• Exe.SetFromVar(addr, varName)

  Adds an entry to overwrite data at the specified addr ess with the user input value previously saved under the varName.

  The value is already saved as a byte array internally and the no of bytes to alter is basically the size of that array.

  Returns the number of bytes affected.

• Exe.SetNOPs(addr, [count])

  Adds an entry to overwrite data at the specified addr ess with NOP instructions.

  If the count is omitted then only 1 NOP is added. Similarly if count > 6, then we add a JMP instruction internally to avoid CPU cycle wastage.

  Returns true if successful.

• Exe.SetJMP(addr)

  Adds an entry to change the conditional jump at the specified addr ess to a JMP.

  Returns true if successful.

• Exe.SetJMP(source, target)
  Exe.SetJMP(source, target, tgtType)
  Exe.SetJMP(source, target, extraNOPs)
  Exe.SetJMP(source, target, tgtType, extraNOPs)

  Adds an entry to create a JMP instruction at the source address to the target address. Short & Long Jumps are taken care of automatically.

  If the AddrType (tgtType) is omitted, then the specified target is expected to be a VIRTUAL address.

  You can also request to add some extraNOPs at the end of the JMP instruction. This helps with meeting alignment sometimes.

  Returns true if successful.

• Exe.SetCALL(source, target)
  Exe.SetCALL(source, target, tgtType)
  Exe.SetCALL(source, target, extraNOPs)
  Exe.SetCALL(source, target, tgtType, extraNOPs)

  Essentially same as above but a CALL instruction is created instead of JMP.

  Returns true if successful.

• Exe.SetTgtAddr(source, target, [tgtType])

Adds an entry to create a delta value at the source address for JMP ing to the target address.

If the AddrType (tgtType) is omitted, then the specified target is expected to be a VIRTUAL address.

Returns true if successful.

• Exe.SetDirAddr(dtype, addr, [atype])

  Adds an entry to change the starting offset of the specified DirType to the specified addr ess.

  If the AddrType (atype) is omitted, the addr is expected to be a VIRTUAL address.

  Returns true if successful.

• Exe.SetDirSize(dtype, size)

  Adds an entry to change the size of the specified DirType.

  Returns true if successful.

Content insertion

These functions are meant to add data to the DIFF section. To do so first we need to allocate the required space using Exe.FindSpace function.

Please ensure you do not do any insertions into random addresses in the DIFF section

The functions behave similar to the Content setters mentioned above but with an additional feature that they reserve the range of addresses being changed (as long as it is inside DIFF section).

These reserved addresses will be kept intact in any future calls to Exe.FindSpace. The range of addresses reserved will depend on both the allocated size & the size of data being added.

Another interesting fact is that since these functions work with DIFF section, they can & will make the patched exe grow in size.

All of them return the range/size of addresses reserved.

• Exe.AddHex(addr, hexstring)

  Adds an entry to insert the specified hexstring string at the specified **addr**ess.

  If addr is not in the DIFF section, then this works identical to Exe.SetHex.

• Exe.AddText(addr, text, [enc])

  Adds an entry to insert the text string at the specified addr ess.

  If addr is not in the DIFF section, then this works identical to Exe.SetText.

  If enc is omitted, then text is considered to be ASCII encoded.

• Exe.AddFromVar(addr, varName)

  Adds an entry to insert the the user input value (previously saved under varName) at the specified addr ess.

  If addr is not in the DIFF section, then this works identical to Exe.SetFromVar.

Content query

• Exe.FindHex(pattern, [from], [to])

  Searches the Exe for the provided hex pattern within the address range specifed. It can contain wildcard characters such as ?, [, . and ].

  See Writing Scripts for more details.

  If the from address is omitted or it is negative, then it starts from the beginning of the CODE section

  Similarly if the to address is omitted or it is negative then search goes on till the end of CODE section.

  Returns -1 if no match is found.

• Exe.FindLastHex(pattern, [from], [to])

  Similar to Exe.FindHex, but the search is done in reverse i.e. the last match is picked up first.

  If the from address is omitted or it is negative, then it starts from the end of the CODE section.

  Similarly if the to address is omitted or it is negative then search goes on till the beginning of the CODE section.

  Returns -1 if no match is found.

• Exe.FindHexN(pattern, [from], [to])
  Exe.FindHexN(pattern, count, [from], [to])

  Similar to Exe.FindHex, but looks for multiple matches to get a list of matching addresses.

  If the from address is omitted or it is negative, then it starts from the beginning of the CODE section

  Similarly if the to address is omitted or it is negative then search goes on till the end of CODE section.

  If the count is omitted, then all matching addresses are retrieved.

  Returns an empty list if no match is found.

• Exe.FindLastHexN(pattern, [from], [to])
  Exe.FindLastHexN(pattern, count, [from], [to])

  Similar to Exe.FindLastHex, but looks for multiple matches to get a list of matching addresses. The list will be in descending order.

  If the from address is omitted or it is negative, then it starts from the end of the CODE section.

  Similarly if the to address is omitted or it is negative then search goes on till the beginning of the CODE section.

  If the count is omitted, then all matching addresses are retrieved.

  Returns an empty list if no match is found.

• Exe.FindText(text, [from], [to])
  Exe.FindText(text, atype, [from], [to])
  Exe.FindText(text, atype, prefixNull, [from], [to])
  Exe.FindText(text, prefixNull, [from], [to])
  Exe.FindText(text, prefixNull, suffixNull, [from], [to])
  Exe.FindText(text, atype, prefixNull, suffixNull, [from], [to])
  Exe.FindText(text, enc, [from], [to])
  Exe.FindText(text, enc, atype, [from], [to])
  Exe.FindText(text, enc, atype, prefixNull, [from], [to])
  Exe.FindText(text, enc, prefixNull, [from], [to])
  Exe.FindText(text, enc, prefixNull, suffixNull, [from], [to])
  Exe.FindText(text, enc, atype, prefixNull, suffixNull, [from], [to])

  Searches the Exe for the provided text string of the specified Encoding (enc) between the address range specifed.

  If the from address is omitted, then the search occurs within both DATA & DATA2 sections.

  Similarly if the to address is omitted, then the search occurs till the end of the file.

  If the AddrType (atype) is omitted then the VIRTUAL address is returned.

  If enc is omitted, then the text string is considered to be ASCII encoded.

  You can also enforce NULL byte boundary checks during the search by specifying prefixNull and suffixNull boolean arguments.

• Exe.FindLastText(text, [from], [to])
  Exe.FindLastText(text, atype, [from], [to])
  Exe.FindLastText(text, atype, prefixNull, [from], [to])
  Exe.FindLastText(text, prefixNull, [from], [to])
  Exe.FindLastText(text, prefixNull, suffixNull, [from], [to])
  Exe.FindLastText(text, atype, prefixNull, suffixNull, [from], [to])
  Exe.FindLastText(text, enc, [from], [to])
  Exe.FindLastText(text, enc, atype, [from], [to])
  Exe.FindLastText(text, enc, atype, prefixNull, [from], [to])
  Exe.FindLastText(text, enc, prefixNull, [from], [to])
  Exe.FindLastText(text, enc, prefixNull, suffixNull, [from], [to])
  Exe.FindLastText(text, enc, atype, prefixNull, suffixNull, [from], [to])

  Similar to Exe.FindText but the search is done in reverse.

  If the from address is omitted, then the search occurs within both DATA & DATA2 sections.

  Similarly if the to address is omitted, then the search occurs till the beginning of the file.

  If the AddrType (atype) is omitted then the VIRTUAL address is returned.

  If enc is omitted, then the text string is considered to be ASCII encoded.

  You can also enforce NULL byte boundary checks during the search by specifying prefixNull and suffixNull boolean arguments.

• Exe.FindTextN(text, [from], [to])
  Exe.FindTextN(text, atype, [from], [to])
  Exe.FindTextN(text, atype, prefixNull, [from], [to])
  Exe.FindTextN(text, prefixNull, [from], [to])
  Exe.FindTextN(text, prefixNull, suffixNull, [from], [to])
  Exe.FindTextN(text, atype, prefixNull, suffixNull, [from], [to])
  Exe.FindTextN(text, enc, [from], [to])
  Exe.FindTextN(text, enc, atype, [from], [to])
  Exe.FindTextN(text, enc, atype, prefixNull, [from], [to])
  Exe.FindTextN(text, enc, prefixNull, [from], [to])
  Exe.FindTextN(text, enc, prefixNull, suffixNull, [from], [to])
  Exe.FindTextN(text, enc, atype, prefixNull, suffixNull, [from], [to])
  Exe.FindTextN(count, text, [from], [to])
  Exe.FindTextN(count, text, atype, [from], [to])
  Exe.FindTextN(count, text, atype, prefixNull, [from], [to])
  Exe.FindTextN(count, text, prefixNull, [from], [to])
  Exe.FindTextN(count, text, prefixNull, suffixNull, [from], [to])
  Exe.FindTextN(count, text, atype, prefixNull, suffixNull, [from], [to])
  Exe.FindTextN(count, text, enc, [from], [to])
  Exe.FindTextN(count, text, enc, atype, [from], [to])
  Exe.FindTextN(count, text, enc, atype, prefixNull, [from], [to])
  Exe.FindTextN(count, text, enc, prefixNull, [from], [to])
  Exe.FindTextN(count, text, enc, prefixNull, suffixNull, [from], [to])
  Exe.FindTextN(count, text, enc, atype, prefixNull, suffixNull, [from], [to])

  Similar to Exe.FindText, but looks for multiple matches to get a list of matching addresses.

  If the from address is omitted, then the search occurs within both DATA & DATA2 sections.

  Similarly if the to address is omitted, then the search occurs till the end of the file.

  If the AddrType (atype) is omitted then the VIRTUAL address is returned.

  If enc is omitted, then the text string is considered to be ASCII encoded.

  You can also enforce NULL byte boundary checks during the search by specifying prefixNull and suffixNull boolean arguments.

  If the count is omitted, then all matching addresses are retrieved.

  Returns an empty list if no match is found.

• Exe.FindLastTextN(text, [from], [to])
  Exe.FindLastTextN(text, atype, [from], [to])
  Exe.FindLastTextN(text, atype, prefixNull, [from], [to])
  Exe.FindLastTextN(text, prefixNull, [from], [to])
  Exe.FindLastTextN(text, prefixNull, suffixNull, [from], [to])
  Exe.FindLastTextN(text, atype, prefixNull, suffixNull, [from], [to])
  Exe.FindLastTextN(text, enc, [from], [to])
  Exe.FindLastTextN(text, enc, atype, [from], [to])
  Exe.FindLastTextN(text, enc, atype, prefixNull, [from], [to])
  Exe.FindLastTextN(text, enc, prefixNull, [from], [to])
  Exe.FindLastTextN(text, enc, prefixNull, suffixNull, [from], [to])
  Exe.FindLastTextN(text, enc, atype, prefixNull, suffixNull, [from], [to])
  Exe.FindLastTextN(count, text, [from], [to])
  Exe.FindLastTextN(count, text, atype, [from], [to])
  Exe.FindLastTextN(count, text, atype, prefixNull, [from], [to])
  Exe.FindLastTextN(count, text, prefixNull, [from], [to])
  Exe.FindLastTextN(count, text, prefixNull, suffixNull, [from], [to])
  Exe.FindLastTextN(count, text, atype, prefixNull, suffixNull, [from], [to])
  Exe.FindLastTextN(count, text, enc, [from], [to])
  Exe.FindLastTextN(count, text, enc, atype, [from], [to])
  Exe.FindLastTextN(count, text, enc, atype, prefixNull, [from], [to])
  Exe.FindLastTextN(count, text, enc, prefixNull, [from], [to])
  Exe.FindLastTextN(count, text, enc, prefixNull, suffixNull, [from], [to])
  Exe.FindLastTextN(count, text, enc, atype, prefixNull, suffixNull, [from], [to])

  Similar to Exe.FindLastText, but looks for multiple matches to get a list of matching addresses. The list will be in descending order.

  If the from address is omitted, then the search occurs within both DATA & DATA2 sections.

  Similarly if the to address is omitted, then the search occurs till the beginning of the file.

  If the AddrType (atype) is omitted then the VIRTUAL address is returned.

  If enc is omitted, then the text string is considered to be ASCII encoded.

  You can also enforce NULL byte boundary checks during the search by specifying prefixNull and suffixNull boolean arguments.

  If the count is omitted, then all matching addresses are retrieved.

  Returns an empty list if no match is found.

• Exe.FindFunc(name)
  Exe.FindFunc(name, dllName)
  Exe.FindFunc(ordinal, dllName)
  Exe.FindFunc(name, ordinal, dllName)

  Finds the VIRTUAL address of the imported function specified by it's name or ordinal or both.

  You can also specify the dllName it got imported from to further restrict the search.

• Exe.FindSpace(size, [snap])

  Allocate the first unreserved size no of bytes in the DIFF section and return the starting PHYSICAL address.

  If the snap is provided, then the starting address needs to be a multiple of it.

• Exe.FindSpace(varName)

  Allocate the first unreserved set of addresses in the DIFF section required to add the user input value (saved under the varName) and return the starting PHYSICAL address.