# Symbols (analysis.syms)

analysis.syms: malcat.Symbols

  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.a2v(sym.address):x} = {sym.name} ({sym.type})")

    Return type:

      iterator over `Symbol`

  __getitem__(interval)

    Iterate over all the symbols defined in the interval (effective address):

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

    Parameters:

      interval (slice) – effective address interval

    Return type:

      iterator over `Symbol` instances

  __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.a2v(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.a2v(ep_address):x}:")
        for sym in analysis.syms[ep_address]:
            print(f"    * 0x{analysis.a2v(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.syms[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