Symbols (analysis.syms)

analysis.syms: malcat.CrossReferences: The analysis.syms object is a malcat.Symbols instance that gives you access to all the symbols defined inside the analysis. This class also allows

Note that in addition to this documentation, you can find usage examples in the sample script which is loaded when you hit F8.

Accessing / enumerating / editing symbols 

class malcat.Symbols

This class contains all symbols found by the analysis. It also contains all user labels added by the user, either via the user interface or the python bindings. Note that all addresses used in this class are effective addresses. See Addressing in Malcat for more details.

Navigation

__iter__()

Iterate over all the symbols

for sym in itertools.islice(analysis.syms, 5):
    print(f"* 0x{analysis.map.to_virt(sym.address):x} = {sym.name} ({sym.type})")

Return type:: iterator over Symbol

__getitem__(interval)

Iterate over all the cross-references contained in the interval (effective address):

text = analysis.map[".text"]
for sym in analysis.syms[text.start : text.end]:
    print(f"* 0x{analysis.map.to_virt(sym.address):x} = {sym.name} ({sym.type})")

Parameters:: interval (slice) – effective address interval
Return type:: iterator over References

__getitem__(name)

Returns the effective address of the first symbol named name or None if no symbol named name is defined

ep_address = analysis.syms["EntryPoint"]
print(f"Entry point defined at 0x{ analysis.map.to_virt(ep_address):x}")

Parameters:: name (str) – name of the symbol to query
Return type:: int or None

__getitem__(ea)

Returns the list of Symbol defined at the effective address ea.

ep_address = analysis.syms["EntryPoint"]
print(f"* List of symbols defined at 0x{ analysis.map.to_virt(ep_address):x}:")
for sym in analysis.syms[ep_address]:
    print(f"    * 0x{analysis.map.to_virt(sym.address):x} = {sym.name} ({sym.type})")

Parameters:: ea (int) – effective address
Return type:: List[Symbol]

__contains__(name)

return True iff there is at least one symbol named name defined

Parameters:: name (str) – symbol name to query
Return type:: bool

__contains__(ea)

return True iff there is at least one symbol defined at the effective address ea

Parameters:: ea (int) – address to query
Return type:: bool

__len__()

return the number of addresses where at least one symbol is defined

if len(analysis.syms) == 0:
    raise ValueError("No symbol defined!")

Return type:: int

Adding / deleting user labels

If you want to add (or override) a symbol name at a given address, you can do so using user labels. They are user modifications saved with the Malcat project file. The following functions allow you to do so:

set_label(ea, label_name)

define a new user label at the given address. Returns true on success. Will register the operation into the Undo/redo manager.

address = analysis.v2a(0x401000)
if not analysis.syms.set_label(address, "my_new_symbol"):
    raise ValueError(f"Could not create a user label at {analysis.ppa(address)}")

Parameters:

ea (int) – effective address where the label should be defined
label_name (str) – the name of the label

Return type:

bool

__setitem__(ea, label_name)

shortcut for set_label()

analysis.syms[analysis.v2a(0x401000)] = "my_new_symbol"

Parameters:

ea (int) – effective address where the label should be defined
label_name (str) – the name of the label

unset_label(ea)

remove an existing user label defined at the given address. Returns true on success. Will register the delete operation into the Undo/redo manager.

if not analysis.syms.unset_label(analysis.v2a(0x401000)):
    raise ValueError(f"Could not remove user label at {analysis.ppa(address)}")

Parameters:: ea (int) – the address of the user label to delete
Return type:: bool

__delitem__(ea)

shortcut for unset_label()

del analysis.comments[analysis.v2a(0x401000)]

Parameters:: ea (int) – the address of the user label to delete

Statistics

number_of_imports: int: total number of malcat.Symbol.Type.IMPORT symbols

number_of_exports: int: total number of malcat.Symbol.Type.EXPORT symbols

number_of_functions: int: total number of malcat.Symbol.Type.FUNCTION symbols

number_of_variables: int: total number of malcat.Symbol.Type.VARIABLE symbols

number_of_typedefs: int: total number of malcat.Symbol.Type.TYPEDEF symbols

number_of_entrypoints: int: total number of malcat.Symbol.Type.ENTRY symbols

number_of_labels: int: total number of malcat.Symbol.Type.LABEL symbols

Symbol definition 

In Malcat, symbols are just named addresses. They also have a category, the one you can see in the Symbols list view.

class malcat.Symbol

A single symbol, which is nothing more than a named address

address: int (effective address): effective address of the symbol

name: str: name of the symbol

type: malcat.Symbol.Type

type/category of the symbol. Can be any of:

malcat.Symbol.Type.FUNCTION
malcat.Symbol.Type.ENTRY
malcat.Symbol.Type.EXPORT
malcat.Symbol.Type.IMPORT
malcat.Symbol.Type.LABEL
malcat.Symbol.Type.TYPEDEF
malcat.Symbol.Type.VARIABLE

The type/category of symbols has the following meaning:

class malcat.Symbol.Type

FUNCTION: the start of a function definition. This symbol is only set for functions having a name, set by a FLIRT signature for instance, of via debug information

ENTRY: an entry point of the program. Note that more than one ENTRY symbol can exist (for instance a .NET program has a PE entry point and a .NET entry point symbols)

EXPORT: an exported function definition or exported variable

IMPORT: an imported function address. Note thatfor PE imports, the impport name will be of the form kernel32.VirtualProtect: dll in lowercase without extension followed by a dot and the API name.

LABEL: an arbitary named address, can be anything. can be set by the user.

TYPEDEF: a type definition, e.g. a TypeDef entry in .NET, or an RTTI vtable

VARIABLE: a variable definition