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

int – The virtual address associated with the function.

apis

list – The APIs called by the function.

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

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
created

bool – True if the annotations were created by user.

creator

str – The handle of the annotation creator.

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

bool – True if function metadata has changed.

id

str – The FIRST ID associated with the function.

is_lib

bool – True if function is a library function.

name

str – The name of the function

offset

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

original_name

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
prototype

str – The prototype of the function

segment

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

Returns None if no segment can be retrieved

signature

str – The opcodes associated with the function.

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.