Elements

Basic elements in IDA are all refered by an ID. This can be the address of the element in the database or a particular ID. For allowing to access easily the correct element from its ID Bip defines a tree of classes with each leaf classes in charge of a particular element.

Three abstract classes are defined in Bip:

For getting a correct element from an ID it is enough to call the GetElt() and GetEltByName() function. As those functions can return diferent types of objects it can be convenient to use isinstance for checking the return type of the object.

Internals

Recuperation of the correct element

For being able to return an object GetElt() (GetEltByName() is simply a wrapper in top of GetElt()) must be able to tell which class should be used. This is done by recursivelly checking the child classes of BipBaseElt, each child classes should implement the class method BipBaseElt._is_this_elt() which take an ID in argument. If this method return True iteration will continue on child classes of this class, if it return False it will stop. When all child classes return False or a leaf as been reach an object of this element is created and returned.

If two subclasses return True at one level of the recursion, one of them will be ignored.

All classes which inherit from BipBaseElt are expected to take only their ID in argument for being able to be instantiated by GetElt() .

Element Functions API

bip.base.GetElt(ea=None)

Return an object inherithed from BipBaseElt which correspond to the element at an id.

Internally this function parcours subclasses of BipBaseElt and call the _is_this_elt() and return the one which match.

Warning

There is a problem if two functions of a sublcass level can return True on the same element.

Parameters:ea (int) – An address at which to get an element. If None the screen address is used.
Raises:RuntimeError – If the address correspond to the error value.
Returns:An object (subclass of BipBaseElt) representing the element. If the address is not mapped a BipElt will be returned.
bip.base.GetEltByName(name)

Same as GetElt() but using a name and not an address.

Parameters:name (str) – The name of the element to get. If a “dummy” name (byte_xxxx, …) is provided the database is not consulted.
Returns:An object representing the element or None if the name was not found.
Return type:Subclass of BipBaseElt.

BipBaseElt API

class bip.base.BipBaseElt(idelt)

Base class for representing an element in IDA which is identified by an id, this should be used as an abstract class and no object of this class should be instantiated.

This is a really generic class which only support the constructor taking an id and the BipBaseElt._is_this_elt() for used in conjonction with GetElt(). Child classes should reimplement the BipBaseElt._is_this_elt() and call this constructor.

Todo

make list of subclasses in this doc. Add to doc a descision tree for which classes should be return by the GetElt.

__init__(idelt)

Consctructor for a BipBaseElt object.

Note

There is no reason to use this constructor, the GetElt() or GetEltByName() functions should be used.

Parameters:idelt (int) – The id for representing the IDA element. In most case this will be the address of the element.
_idelt = None

The id which represent the element in IDA, this will typically be an address.

classmethod _is_this_elt(idelt)

Class method which allow the function GetElt() to know if this the correct type for an address. Only subclasses of an element which return True will be tested by GetElt(), BipBaseElt return always True except if idelt is not of the correct type.

Parameters:idelt (int) – An id representing the element, typically an address.
Returns:True if this is a valid class for constructing this element.
classmethod iter_heads(start=None, end=None)

Class method allowing to iter on all the element defined in the IDB. This means elements which are not defined (considered to not heads) will not be returned by this function.

Note

Internally this function iterate on all the Heads and create the object if the class which is used for it match the element. For example calling BipData.iter_heads() will return only the heads which are BipData object or their children.

Note

This function will work only on mapped object, it is not possible to use it for getting BipStruct for example.

Parameters:
  • start – The address at which to start iterating. If this parameter is None (the default) the minimum mapped address will be used.
  • end – The address at which to stop iterating. If this parameter is None (the default) the maximum mapped address will be used.
Returns:

A generator of object child of BipBaseElt allowing to iter on all the elt define in the idb.
__eq__(other)

Compare the id of 2 BipBaseElt and return True if they are equal.

__ne__(other)

x.__ne__(y) <==> x!=y

__weakref__

list of weak references to the object (if defined)

BipRefElt API

class bip.base.BipRefElt(idelt)

Class which represent element which can be reference through a xref. This include data, instruction and structures. The BipRefElt class provide methods for accessing the references to and from the element represented by the object.

xFrom

Property which allow to get all xrefs generated (from) by the element. This is the equivalent to XrefsFrom from idapython.

Returns:A list of BipXref with the src being this element.
xTo

Property which allow to get all xrefs pointing to (to) this element. This is the equivalent to XrefsTo from idapython.

Returns:A list of BipXref with the dst being this element.
xEaFrom

Property which allow to get all addresses referenced (by a xref) by (from) the element.

Returns:A list of address.
xEaTo

Property which allow to get all addresses which referenced this element (xref to).

Returns:A list of address.
xEltFrom

Property which allow to get all elements referenced (by a xref) by (from) this element.

Returns:A list of BipBaseElt (or subclasses of BipBaseElt).
xEltTo

Property which allow to get all elements which referenced this element (xref to).

Returns:A list of BipBaseElt (or subclasses of BipBaseElt).
xCodeFrom

Property which return all instructions which are referenced by the element. This will take into account jmp, call, ordinary flow and “data” references.

Returns:A list of BipInstr referenced by this element.
xCodeTo

Property which return all instructions which referenced this element. This will take into account jmp, call, ordinary flow and “data” references.

Returns:A list of BipInstr referenced by this element.

BipElt API

class bip.base.BipElt(ea=None)

Base class for representing an element in IDA which have an address. This is the basic element on top of which access to instruction and data is built.

__init__(ea=None)

Consctructor for a BipElt object.

Note

There is no reason to use this constructor, the GetElt() function should be used.

Parameters:ea (int) – The address of the element in IDA. If None the screen address is taken.
Raises:ValueError – If the address given in argument is a bad address (idc.BADADDR)
ea = None

The address of the element in the IDA database

__eq__(other)

Equality comparator with another BipElt. Return NotImplemented if the argument is not a BipElt.

__ne__(other)

Inequality comparator with another BipElt. Return NotImplemented if the argument is not a BipElt.

__lt__(other)

Lesser than comparator with another BipElt. Return NotImplemented if the argument is not a BipElt.

__le__(other)

Lesser or equal comparator with another BipElt. Return NotImplemented if the argument is not a BipElt.

__gt__(other)

Greater than comparator with another BipElt. Return NotImplemented if the argument is not a BipElt.

__ge__(other)

Gretter or equal comparator with another BipElt. Return NotImplemented if the argument is not a BipElt.

__hash__()

Compute a unique hash for this ida element. The produce hash is dependant of the type of this object and of its address. This allow to create container using the hash of the object for matching an object of a defined type and with a particular address.

Calculation made is: hash(type(self)) ^ self.ea, in particular it means than child classes will not have the same hash as a parrent classes even if the compare works.

Returns:An integer corresponding to the hash for this object.
flags

Property for getting the flags of the element. Those flags are the one from ida such as returned by ida_bytes.get_full_flags.

Returns:The flags for the element
Return type:int
size

Property which return the size of the elt.

Returns:The size in bytes of the element.
Return type:int
bytes

Property returning the value of the bytes contain in the element.

Returns:A list of the bytes forming the element.
Return type:list(int)
original_bytes

Property returning the value of the bytes contain in the element before their modification. This still use the size of the current element definition.

Returns:A list of the original bytes as integer forming the element.
name

Property which allow to get the name of this element. An element do not always have a name.

Returns:The name of an element or an empty string if no name.
Return type:str
demangle_name

Property which return the demangle name of the element.

Return str:The demangle name of the element or None if there is no demangle version of the name.
is_dummy_name

Property for checking if the current name of this element is a “dummy” name (a name set by default by IDA when it does not know how to call an element) with a special prefix. This function will not recognize the aSTRING naming, see is_auto_name(), and is_ida_name().

Returns:True if the element has a dummy name, False otherwise.
is_auto_name

Property for checking if the current name of this element is an “auto-generated” name, those are the default name generated by IDA but without a special prefix (see is_dummy_name()) such as the one for the string. See also is_ida_name().

Returns:True if the element has an auto-generated name, False otherwise.
is_ida_name

Property for checking if the current name is a default name as generated by IDA. This is an OR condition of is_auto_name() and is_dummy_name().

This is still not perfect and name put some names put by IDA will not be recognize by this function (for example the global for the CFG and probably others).

Returns:True if the element has a name provided by IDA, False otherwise.
is_user_name

Property for checking if the current name is a “user name”. In practice this check a flag that the API can avoid setting, so there is no garantee it is an actual user name. See is_ida_name() for checking if a name was generated by IDA.

Returns:True if the name is marked as set by a user, False otherwise.
color

Property which return the color of the item.

Returns:The coloration of the element in IDA.
Return type:int
comment

Property which return the comment of the item.

Returns:The value of the comment or None if there is no comment.
Return type:str
rcomment

Property which return the repeatable comment of the item.

Returns:The value of the comment or None if there is no repeatable comment.
Return type:str
has_comment

Property which allow to check if the item as a comment (normal or repeatable.

Returns:True if the item as a comment, False otherwise
is_code

Property indicating if this element is some code. Wrapper on idc.is_code .

Returns:True if current element is code, False otherwise.
Return type:bool
is_data

Property indicating if this element is considered as data. Wrapper on idc.is_data .

Returns:True if current element is data, False otherwise.
Return type:bool
is_unknown

Property indicating if this element is considered as unknwon. Wrapper on idc.is_unknown .

Returns:True if current element is unknwon, False otherwise.
Return type:bool
is_head

Property indicating if the element is an head in IDA. An head element is the beggining of an element in IDA (such as the beginning of an instruction) and can be named. Wrapper on idc.is_head .

Returns:True if the current element is an head, False otherwise.
Return type:bool
has_data

Property which indicate if an element has a value. If an element has no value a default value of 0xFF will be returned in general. This correspond to element in IDA which are marked with a ? in value. Wrapper on idc.has_value.

Returns:True if the current element has a value, False otherwise.
goto()

Method which allow to move the screen to the position of this element. Wrapper on ida_kernwin.jumpto (old idc.Jump).

classmethod iter_all(start=None, end=None)

Class method allowing to iter on all mapped elements of the IDB.

This will return only the elements which are handle by the class or one of this subclasses. For example calling BipData.iter_heads() will return only the heads which are BipData object or children of that class. This use GetElt() for determining the correct object to return.

Parameters:
  • start – The address at which to start iterating. If this parameter is None (the default) the minimum mapped address will be used.
  • end – The address at which to stop iterating. If this parameter is None (the default) the maximum mapped address will be used.
Returns:

A generator of object child of BipBaseElt allowing to iter on all the elt in the idb.
static is_mapped(ea=None)

Static method which allow to know if an address is mapped or not.

Parameters:ea – The address to test for being mapped or not. If None the screen address will be used.
Returns:True if the address is mapped, False otherwise.
static next_data_addr(ea=None, down=True)

Static method which allow to find the address of the next data element.

Parameters:
  • ea – The address at which to start the search. If None the screen address will be used.
  • down – If True (the default) search below the given address, if False search above.
Returns:

The address of the next data or None if the search did not find any match.
static next_data(ea=None, down=True)

Static method which allow to find the next data element.

Parameters:
  • ea – The address at which to start the search. If None the screen address will be used.
  • down – If True (the default) search below the given address, if False search above.
Returns:

An object which ibherit from BipBaseElt or None if the search did not find any match.
static next_code_addr(ea=None, down=True)

Static method which allow to find the address of the next code element.

Parameters:
  • ea – The address at which to start the search. If None the screen address will be used.
  • down – If True (the default) search below the given address, if False search above.
Returns:

The address of the next code or None if the search did not find any match.
static next_code(ea=None, down=True)

Static method which allow to find the next code element.

Parameters:
  • ea – The address at which to start the search. If None the screen address will be used.
  • down – If True (the default) search below the given address, if False search above.
Returns:

An object which ibherit from BipBaseElt or None if the search did not find any match.
static next_unknown_addr(ea=None, down=True)

Static method which allow to find the address of the next unknown element. An unknown element is an element for which IDA does not know the type.

Parameters:
  • ea – The address at which to start the search. If None the screen address will be used.
  • down – If True (the default) search below the given address, if False search above.
Returns:

The address of the next unknown element or None if the search did not find any match.
static next_unknown(ea=None, down=True)

Static method which allow to find the next unknown element. An unknown element is an element for which IDA does not know the type.

Parameters:
  • ea – The address at which to start the search. If None the screen address will be used.
  • down – If True (the default) search below the given address, if False search above.
Returns:

An object which ibherit from BipBaseElt or None if the search did not find any match.
static next_defined_addr(ea=None, down=True)

Static method which allow to find the address of the next defined element. An defined element is the opposite of unknown, meaning or a data with a known type or code.

Parameters:
  • ea – The address at which to start the search. If None the screen address will be used.
  • down – If True (the default) search below the given address, if False search above.
Returns:

The address of the next defined element or None if the search did not find any match.
static next_defined(ea=None, down=True)

Static method which allow to find the next defined element. An defined element is the opposite of unknown, meaning or a data with a known type or code.

Parameters:
  • ea – The address at which to start the search. If None the screen address will be used.
  • down – If True (the default) search below the given address, if False search above.
Returns:

An object which ibherit from BipBaseElt or None if the search did not find any match.
static search_bytes_addr(byt, start_ea=None, end_ea=None, down=True, nxt=True)

Static method for searching a sequence of bytes. This will search for the bytes which ever the data type is.

This is a wrapper on the ida_search.find_binary (previously FindBinary) function from IDA with a radix of 16.

The byte should be represented in hexadecimal seperated by space. A ? can be put for replacing a byte, for example: 41 8B 44 ? 20.

Parameters:
  • byt – A string representing a sequence of byte.
  • start_ea – The address at which to start the search, if None the current address will be used.
  • end_ea – The address at which to stop the search, if None the maximum or minimum (depending of searching up or down) will be used.
  • down – If True (the default) search below the given address, if False search above.
  • nxt – If True (the default) the current element will not be included in the search.
Returns:

The address at which the byte sequence is present or None if no element were found during the search.
static search_bytes(byt, start_ea=None, end_ea=None, down=True, nxt=True)

Static method for searching a sequence of bytes. This will search for the bytes which ever the data type is.

This is a wrapper on the ida_search.find_binary (previously FindBinary) function from IDA with a radix of 16.

The byte should be represented in hexadecimal seperated by space. A ? can be put for replacing a byte, for example: 41 8B 44 ? 20.

Parameters:
  • byt – A string representing a sequence of byte.
  • start_ea – The address at which to start the search, if None the current address will be used.
  • end_ea – The address at which to stop the search, if None the maximum or minimum (depending of searching up or down) will be used.
  • down – If True (the default) search below the given address, if False search above.
  • nxt – If True (the default) the current element will not be included in the search.
Returns:

An object which inherit from BipBaseElt representing the element at the address at which the byte sequence is present or None if no element were found during the search.
static search_str_addr(s, start_ea=None, end_ea=None, down=True, nxt=True)

Static method for searching a string. In practice this perform a search_bytes on the binary by encoding correctly the string passed in argument and returning only reference to data elements.

Warning

This is different from idapython FindText method as this will only search for bytes in the binary (and more precisely the data)! It should also be way faster.

Todo

this should allow to handle encoding.

Parameters:
  • s (str) – The C string for which to search. If the string is NULL terminated the NULL byte must be included.
  • start_ea – The address at which to start the search, if None the current address will be used.
  • end_ea – The address at which to stop the search, if None the maximum or minimum (depending of searching up or down) will be used.
  • down – If True (the default) search below the given address, if False search above.
  • nxt – If True (the default) the current element will not be included in the search.
Returns:

The address at which the string was found. It will always be data. If no matching element was found None will be return.
static search_str(s, start_ea=None, end_ea=None, down=True, nxt=True)

Static method for searching a string. In practice this perform a search_bytes on the binary by encoding correctly the string passed in argument and returning only reference to data elements.

Warning

This is different from idapython FindText method as this will only search for bytes in the binary (and more precisely the data)! It should also be way faster.

Todo

this should allow to handle encoding.

Parameters:
  • s (str) – The C string for which to search. If the string is NULL terminated the NULL byte must be included.
  • start_ea – The address at which to start the search, if None the current address will be used.
  • end_ea – The address at which to stop the search, if None the maximum or minimum (depending of searching up or down) will be used.
  • down – If True (the default) search below the given address, if False search above.
  • nxt – If True (the default) the current element will not be included in the search.
Returns:

An object which inherit from BipBaseElt representing the element at the address at which the string was found. The element will always have BipElt.is_data() as True. If no matching element was found None will be return.