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.

Parameters:
  • 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

Examples

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')
address

The virtual address associated with the function.

Type:int
apis

The APIs called by the function.

Type:list
apply_metadata(data)[source]

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.
comment

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
Type:str
created

True if the annotations were created by user.

Type:bool
creator

The handle of the annotation creator.

Type:str
from_db(data_str)[source]

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.
has_changed

True if function metadata has changed.

Type:bool
id

The FIRST ID associated with the function.

Type:str
is_lib

True if function is a library function.

Type:bool
name

The name of the function

Type:str
offset

The function offset from the start of the segment.

Type:int
original_name

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
Type:str
prototype

The prototype of the function

Type:str
segment

The start address of the function’s segment.

Returns None if no segment can be retrieved

Type:int
signature

The opcodes associated with the function.

Type:str
snapshot()[source]

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.

to_db()[source]

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
update_comment()[source]

Updates IDB DB if comment has changed since last snapshot.

update_db(changed)[source]

Updates the IDB DB with FIRST identifiers.

update_name()[source]

Updates IDB DB if name has changed since last snapshot.

update_prototype()[source]

Updates IDB DB if prototype has changed since last snapshot.