Scripted API

Scripted API

Table of Contents

• Strings & Error Messages
• Hex Codes
• Common Instructions
• Misc Items
• Classes
• Functions
  • Debug Functions
  • Testers
  • Filler Functions
  • Converters
  • Calculators
  • Extractors
  • Utilities
  • Syntax Identifiers
• Addons
  • Testers
  • Converters
  • Transformers
  • Calculators
  • Utilities
• Generators

Strings & Error Messages

Name	Description
YMLFILTER	Filter string for YAML files. Used with user inputs of D_InFile [DataType]
TAB	4 blank spaces used in console object methods
NO_ALLOC	Error message to use when Exe.FindSpace returns -1
NO_EXE	Error message to use in extensions after testing Exe.FileSize == 0
NO_OUTPUT	Error message to use when TextFile.Open & BinFile.Open fails

Hex Codes

Name	Description
WC	Wild Card byte ??
WCp	Positive Wild Card byte
WCn	Negative Wild Card byte
ALLWC	DWORD with all Wild Cards
ALLWCp	DWORD with all Wild Cards having +ve sign bit
ALLWCn	DWORD with all Wild Cards having -ve sign bit
ALL00	DWORD with all zeroes
POS1WC	Positive DWORD with 1 Lower Wild Card bytes
POS2WC	Positive DWORD with 2 Lower Wild Card bytes
POS3WC	Positive DWORD with 3 Lower Wild Card bytes
POS4WC	Positive DWORD with 3 Lower Wild Card bytes & partial Wild Card MSB
ALLFF	DWORD for -1
NEG1WC	Negative DWORD with 1 Lower Wild Card bytes
NEG2WC	Negative DWORD with 2 Lower Wild Card bytes
NEG3WC	Negative DWORD with 3 Lower Wild Card bytes
NEG4WC	Negative DWORD with 3 Lower Wild Card bytes & partial Wild Card MSB

Common Instructions

• PUSH_0
• PUSH_1
• PUSH_2
• PUSH_R (PUSH Reg32)
• PUSH_EAX
• POP_R (POP Reg32)

Misc Items

• OpCodeList

  Mapping of various opcodes. Used internally by Instr class.

• OpTypes

  Collection of Operand types. It has the following keys. Used by Instr class & Generators

  Key	Description
  OpTypes.ERR	Illegal operation
  OpTypes.A	Acc <, Imm>
  OpTypes.R	Reg <, Imm>
  OpTypes.I	<Imm>
  OpTypes.R_R	Reg, Reg <, Imm>
  OpTypes.D_A	Ptr [Disp], Acc <, Imm>
  OpTypes.P_R	Ptr [*], Reg <, Imm>
  OpTypes.A_D	Acc, Ptr [Disp] <, Imm>
  OpTypes.R_P	Reg, Ptr [*] <, Imm>

  Reg refers to a Register object.
  Imm ediate values are all optional and depends on the instruction whether they will be present or not.
  Acc can refer to any primary Register not just Accumulator.

Classes

Following classes are available. Only Instr is usually used for the creation of new objects in code.

• Register - Represents various CPU registers.
• PtrSize - Represents data size of Memory Pointers.
• IPrefix - Represents instruction prefixes
• ModRM - Represents ModRM byte
• SIBase - Represents SIB byte
• Instr - Represents a CPU instruction

Register, PtrSize & IPrefix classes already have pre-made objects covering all known values, so ideally we would be using those instead of creating new objects from these classes. Click the links to know more.

There is also an OpData class used for parsing Instruction arguments internally, but of no use elsewhere.

Functions

Following functions have been provided in addition to the classes.

Debug Functions

console.* functions always send texts to the Output view (inside Script Window or Results Tab of TestBench) as well as the terminal/console where the tool was invoked.

The functions listed below help with sending specific types of values or sending texts in specific formats using the console.* functions and/or to an external log file.

Whenever we mention Output view below, it also means the same is sent to the invoking terminal.

• Log.start([filename])

  Start logging of messages sent by $* functions mentioned below to an external file

  If filename is not provided, Uses Comment_Log_<timestamp>.txt

• Log.stop()

  Stops logging of messages to the file.

• Log.show()

  Opens the file being used for logging messages. Does nothing if no file is open.

• Log.cc([state])

  Enable/Disable (based on state) sending of messages to the Output view from $* functions mentioned below.

• $$(txt)

  Logs txt messages (ideally comments in Patch & Extension functions) to file and/or Output view.

• $$$(txt)

  Similar to above, but always sends to Output view.

• $_([tee], msg, [bold], [chr])

  Used for Writing out header msg to log files and/or Output view with underline character chr.

  tee enables/disables sending to Output view

  bold controls whether to display with bold font or not.

  chr defaults to '+' .

• $__(msg, [bold], [chr])

  Same as above with tee always true.

• _$_([tee], msg, [bold], [chr])

  Same as $_ but the line is added on both top and bottom.

• Debug(...)

  Alias of console.log .

• Info(...)

  Alias of console.info .

• NewLine()

  Add a new line to Output view.

• Dump([name], obj)

  Dump the properties of an object as key and value pairs to Output view.

• ShowArr([useInfo], [indent], [name], arr)

  Display the elements in the array hierarchically in Output view.

  useInfo controls whether to use console.info or console.log (the default).

  indent indicates number of tabs to prefix (default is 0).

  An explicit name can be provided to display instead of 'Array'.

• ShowVar({variable})

  Display the variable name and its value in Output view. The variable need to be sent wrapped inside { }

• ShowAddr([prompt], address, [type])

  Display the PHYSICAL & VIRTUAL counterparts of an address in Output view.

  The address type if not provided is assumed to be PHYSICAL.

  You can specify an explicit prompt to display instead of 'Addr'

• ShowAddrs([prompt], addrs, [type])

  Same as ShowAddr but used for a list of addresses.

• ResetC()

  Reset the internal counter. Can be used with ShowC to identify various stages in code execution.

• ShowC()

  Increment & display the current count along with Version & Build Date.

Testers

• IsNum(v)

  Check whether the value specified is a number.

• IsStr(v)

  Check whether the value specified is a string.

• IsBool(v)

  Check whether the value specified is a boolean.

• IsArr(v)

  Check whether the value specified is an Array or atleast derived from it.

• IsNumOrStr(v)

  Check whether the value specified is a number or a string.

• IsWord(v, [signed])

  Check whether the value specified is a number or hex string with 2 bytes.

  signed if true (which is the default) makes the function treat this as a signed number.

• IsByte(v, [signed])

  Check whether the value specified is a number or hex string with 1 byte.

  signed if true (which is the default) makes the function treat this as a signed number.

Filler Instructions

• Filler(index, [bytecount])

  Create a filler hex string with the provided index & bytecount (default is 4). Fillers are generated using ? character.

• SwapFiller(str, index, data, [count], [bytecount])

  Swaps out count of occurrences of the filler hex string generated using the specified index

  and bytecount with the actual data in the provided source str ing and returns the result.

  Default values for count is -1 && for bytecount is 4. If count is negative, all occurrences are replaced.

  If the data is an array then each value gets substituted at the nth match i.e. 1st value replaces the 1st occurrence of the filler and so forth.

• SwapFillers(str, map, [count], [bytecount])

  Similar to SwapFiller but does multiple swaps for all the key (index) & value (data) pairs in the map.

Converters

• Wrap(v)

  Wrap the value in an array unless it's already one and return the result.

Calculators

• BitWidth(v)

  Calculate the bit width of the value which can be a number, hex string, or Register object.

• Distance(tgt, src)

  Calculate the distance from src to tgt. If either of them isn't a number then tgt itself gets returned.

Extractors

• CaseAddr(num, movzxAddr, retnType, jmpDpAddr)

  Extract the switch jump address for the specified switch case.

  movzxAddr and jmpDpAddr are optional, but not together. i.e. atleast one needs to be a valid address.

  If only movzxAddr is specified, jmpDpAddr is assumed to be the address of the instruction after it.

  retnType specifies the AddrType required and num refers to either the case number if movzxAddr is provided or the index in the table otherwise.

Utilities

• ParseData(data, scaled)

  Used by ModRM & SIBase classes to parse the data provided into their 3 parts. Not much of use elsewhere.

• FindInstr(testFn, from, [to])

  Search for a particular instruction using the testFn function within the specified address range. to address is optional and defaults to the end of CODE section.

  testFn should accept an Instr object as argument and return true if it matches the expectation.

  The function returns the Instr object that satisfied the testFn otherwise it returns false. Invalid arguments can also result in false.

• Cancel(arg, [defVal])

  Throws a cancellation warning with specified arg.

  If defVal is specified then a <name> reverted to <value> message is thrown.

Syntax Identifiers

All the following functions identify items to the Script Editor (inside Script Window or Results Tab of TestBench)

• Identify(v)

  Identifies the string provided.

• IdentifyClass(type)

  Identifies the class, its properties & its methods.

• IdentifyObj(name)

  Identifies the object specified by its name along with its properties & its methods.

• IdentifyMany(...)

  Runs IdentifyObj for all object names provided as arguments.

• Assign(name, code)

  Evaluates the code and assigns the result to the variable name. Also identifies the variable to the Script Editor.

• AssignStr(name, value)

  Same as above but we provide a string value instead.

Addons

A handful of functions (shown below) have been added to Primitive prototype s to assist in various ways while writing scripts.

The type to which each function belongs is shown within < >

Testers

• <array>.isEmpty()

  Check whether the array is empty.

• <array>.isRegPtr()

  Check if the array is of the form [Reg] where Reg is a Register object.

• <array>.isDispPtr()

  Check if the array is of the form [displacement]. The displacement can be number or hex string.

• <string>.isEmpty()

  Check for empty string.

• <string>.isHex()

  Check if the string only has valid characters for hex (including the wild card characters).

Converters

• <number>.toBits([count])

  Convert the integer to bit string and return the result.

  count is optional and can go upto 32. Default is also 32.

• <number>.toHex([bytecount], [bigEndian])
  <number>.toHex([bigEndian])

  Convert the integer to hex string and return the result.

  The bytecount is optional and goes upto 4 (default is also 4).

  bigEndian if true makes the function return the result in Big Endian form (bytes don't get reversed and spaces are removed). Default is Little endian form.

• <number>.toIEEE([bigEndian])

  Convert the floating point number to IEEE format hex string and return the result.

  bigEndian works the same way as above.

• <string>.toInt([bytecount], [signed])
  <string>.toInt([signed])

  Convert the little endian hex string to equivalent integer and return the result.

  signed indicates whether to consider this as a signed number (default is true).

• <string>.toHex()

  Convert the ascii string to equivalent hex string and return the result.

• <string>.le2be()

  Convert the little endian hex string to it's big endian form and return the result.

Transformers

• <string>.remove(str)

  Remove the sub str ing provided and return the result.

• <string>.replaceAt(index, str, [len])

  Replace len characters at specified index with str and return the result.

  len is -1 by default. If len is negative then the length of str is used instead.

• <string>.insertAt(index, str)

  Insert str at specified index and return the result.

• <string>.appendAsHex(data, [bytecount], [bigEndian])

  Append the provided data as a hex string and return the result. If data is a number then bytecount and bigEndian are utilized to convert it toHex.

Calculators

• <string>.byteCount()

  Calculate the hex string's byte count and return it. If not a valid hex string then -1 is returned.

Utilities

• <array>.last()

  Retrieve the last value of the array.

• <array>.take_if(typename, defVal)

  Pull out the first value of the array if the type matches typename provided.

  If it doesn't match or the array is empty, then defVal is returned.