Synalyze It!  1.10
Synalyze It! Scripting Reference
Author
Andreas Pehnack

Here you find all classes and methods available in Synalyze It! scripting elements

How to start

To access the objects you need you start with the global currentMapper object of type StructureMapper.

Common task: access parsed value and set endianness

The following code placed in a script element after a number value can access this value and set the dynamic endianness parameter accordingly. All number or offset elements having set their endianness to dynamic will use this setting.

-- get collection with results so far
results = currentMapper:getCurrentResults()
-- get latest added result
lastResult = results:getLastResult()
-- access the parsed value
value = lastResult:getValue()
-- get the value parsed
num = value:getUnsignedNumber()
if (num == 0x4949) then
currentMapper:setDynamicEndianness(synalysis.ENDIAN_LITTLE)
else
currentMapper:setDynamicEndianness(synalysis.ENDIAN_BIG)
end
-- write a message to the log window
logSrc = currentMapper:getCurrentLogSrc()
logSrc:logMessage(_VERSION, 111, synalysis.SEVERITY_INFO, "my message")

Common task: map structure

Depending on conditions you choose you can map different structures either at the current parsing position or at any position inside the file being processed.

-- get currently processed grammar. This may change if another grammar is referenced
currentGrammar = currentMapper:getCurrentGrammar()
-- get the structure we want to apply
structure = currentGrammar:getStructureByName("MappedStruct")
-- map structure at current parsing position and add number of parsed bytes to enclosing structure
bytesProcessed = currentMapper:mapStructure(structure)
-- map structure at position \c 6 with maximum size \c 5
bytesProcessed = currentMapper:mapStructureAtPosition(structure, 6, 5)

Manually add results

Using scripts you can add results for the results tree - structures and their elements. If the script element should be considered failed, return true.

size = 2
-- get results collection
results = currentMapper:getCurrentResults()
-- get currenly processed grammar
grammar = currentMapper:getCurrentGrammar()
-- get byte view on currently processed file
byteView = currentMapper:getCurrentByteView()
-- get current offset
offset = currentMapper:getCurrentOffset()
-- get the structure we want to add to results
structure = grammar:getStructureByName("MappedStruct")
-- get currently processed element (the scripting element)
element = currentMapper:getCurrentStructureElement()
-- add structure start to results with offset \c offset
startResult = results:addStructureStart(structure, 0, "Structure")
-- startResult = results:addStructureStartAtPosition(structure, 10, 0, "Structure")
-- read little endian unsigned integer (4 bytes)
number = byteView:readUnsignedInt(offset, 4, synalysis.ENDIAN_LITTLE)
-- create a value object and set as string
value = synalysis.Value()
value:setString(string.format("%d", number))
-- add element with value to results
results:addStructureElement(element, size, 0, value)
-- add structure end to results with 4 unused (padding) bytes
results:addStructureEnd(offset+size+4)
-- delete added results
-- results:cut(startResult)
-- write a log message
logSrc = currentMapper:getCurrentLogSrc()
logSrc:logMessage("ABC", 111, synalysis.SEVERITY_INFO, "Message from Script")
return false

Modify one byte in reference file

Scripts can modify reference files. These changes can be reverted like the manual ones.

-- get byte array currently processed
byteArray = currentMapper:getCurrentByteArray()
-- insert byte 33 (0x21) at position 2 (3rd byte)
byteArray:insertByte(2, 33)
-- replace byte at position 1 (2nd byte) with 15 (0x0F)
byteArray:replaceByte(1, 15)