FIRST :: MetadataShimΒΆ

class first_plugin_ida.first.FIRST[source]
class MetadataShim(address=0, name='', creator=None)[source]

Shim between interacting with various IDA components and FIRST.

FIRST Metadata Container provides thin shim for interacting with function and affecting IDA’s UI. Changes made from FIRST are updated in the UI and IDA’s IDB DB.

When creating a MetadataShim instance, at least the address should be provided to the constructor. However, it can be useful to create an empty object and populate if with data by calling its from_db method.

  • address (int, optional) – The VA of the function.
  • name (str, optional) – The original name of the function. This should be used to set an original baseline for the function. The default name (sub_X, where X is the function start VA) can be overwritten if this is set.
  • creator (str, optional) – The creator’s handle


Creating MetadataShim instance from function.

>>> m1 = MetadataShim(address=0x401000)

Creating MetadataShim instance from function and setting original name.

>>> m2 = MetadataShim(address=0x401e40, name='memcpy')

Creating MetadataShim instace from a function with a creator.

>>> m3 = MetadataShim(address=0x401330, creator='demonduck#1337')

int – The virtual address associated with the function.


list – The APIs called by the function.


Applies metadata to the function.

The metadata will be applied and become visable in IDA Pro. Updates sample’s IDB DB with the new function annotations.

Parameters:data (MetadataServer) – The metadata result from FIRST server.

str – The repeatable comment associated with the function.

Returns only the first 1024 bytes of the comment. If a comment is longer than that, then it will be truncated to 1024. This mean data could be lost.

Returns:The function’s repeatable comment
Return type:str

bool – True if the annotations were created by user.


str – The handle of the annotation creator.


Converts IDB DB data to MetadataShim object.

Parameters:data_str (str) – JSON data in a string. JSON data keys required: author, changed, original_name, offset, id.

bool – True if function metadata has changed.


str – The FIRST ID associated with the function.


bool – True if function is a library function.


str – The name of the function


int – The function offset from the start of the segment.


str – The orginal name of the function.

Unfortunately, this is a best guess. If the function has been detected as a library function by IDA then we use the current name since there is no way to get any of the previous names it might have had. If it is not a library function then the original name is sub_X, where X is the VA of the function.

Returns:The original name of the function.
Return type:str

str – The prototype of the function


int – The start address of the function’s segment.

Returns None if no segment can be retrieved


str – The opcodes associated with the function.


Saves off current function annotations

Preserves the function name, comment, prototype and FIRST ID currently associated with the function. This will be used to compare with to detect future changes.


Provides data structure for the IDB’s DB.

Returns:FIRST information for the DB.
‘offset’ : int,

‘original_name’ : str,

‘author’ : str,

‘id’ : str,

‘changed’ : bool


Return type:dict

Updates IDB DB if comment has changed since last snapshot.


Updates the IDB DB with FIRST identifiers.


Updates IDB DB if name has changed since last snapshot.


Updates IDB DB if prototype has changed since last snapshot.