Cross References (malcat.xref)

malcat.xref: bindings.CrossReferences

The malcat.xref object is a bindings.CrossReferences instance that gives you access to all the cross references (both code xref and data xref) found by the Cross References Scanner algorithm.

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 cross-references

Malcat keeps a list of all code and data references of every address through the malcat.xref object. This object has the following methods and attributes:

class bindings.CrossReferences

This class contains all cross-references identified by the Cross References Scanner. Note that all addresses used in this class are effective addresses. See Addressing in Malcat for more details.

__iter__()

Iterate over all the cross-references

for r in malcat.xref:
    print(f"* 0x{malcat.map.to_virt(r.address):x} is referenced {r.count} times")
Return type

iterator over References

__getitem__(interval)

Iterate over all the cross-references contained in the interval (effective address):

text = malcat.map[".text"]
for r in malcat.xref[text.start : text.end]:
    print(f"* 0x{malcat.map.to_virt(r.address):x} is referenced {r.count} times")
Parameters

interval (slice) – effective address interval

Return type

iterator over References

__getitem__(ea)

Returns the References to the effective address ea.

first_function = malcat.fns.find_forward(0)
if first_function is not None and first_function.address in malcat.xref:
    xref = malcat.xref[first_function.address]
    print(f"\nFunction {first_function.name} is referenced {len(xref)}: times")
Parameters

ea (int) – effective address

Return type

iterator over the References

Raises

KeyError if ea does not belong to the file’s effective address space

__contains__(ea)

return True iff the effective address ea is referenced by some code and/or data

first_function = malcat.fns.find_forward(0)
if not first_function.address in malcat.xref:
    print("First function is not referenced")
Parameters

ea (int) – address to query

Return type

bool

find(ea)

return the References at the effective address ea, or None if address ea is not referenced.

Parameters

ea (int) – effective address for the query

Return type

References or None

find_forward(ea)

return the References to the first effective address >= ea being referenced, or None if no cross-reference at or past ea can be found.

first_xref = malcat.xref.find_forward(0)
if first_xref is None:
    raise ValueError("No cross ref in program!")
Parameters

ea (int) – effective address for the query

Return type

References or None

find_backward(ea)

return the References to the last effective address <= ea being referenced, or None if no cross-reference at or before ea can be found

last_xref = malcat.xref.find_backward(malcat.map.end)
if last_xref is None:
    raise ValueError("No cross ref in program!")
Parameters

ea (int) – effective address for the query

Return type

References or None

__len__()

return the number of cross references in the file

if len(malcat.xref) == 0:
    raise ValueError("No cross ref found!")
Return type

int

References object

A References python object lists all incoming references for a given address. It offers the following interface:

class bindings.References
address: int (effective address)

referenced address, aka target address

count: int

number of different locations referencing this address

__len__()

same as count

Return type

int

__iter__()

iterate over all incoming references for the given address.

first_function = malcat.fns.find_forward(0)
if first_function is not None and first_function.address in malcat.xref:
    xref = malcat.xref[first_function.address]
    print(f"\nFunction {first_function.name} is referenced by:")
    for ref_type, ref_source in xref:
        print(f"    * 0x{malcat.map.to_virt(ref_source):x} ({ref_type})")

Note that for bindings.References.Type.CODE references, the incoming address is the start address of the referencing instruction.

Returns

iterator over pairs of (incoming reference type, incoming reference effective address)

Return type

iterator over pairs (bindings.References.Type, int)

The reference type can be:

class bindings.References.Type
CODE

this is a code reference. It means that there is an instruction that references the location, e.g.: mov eax, <location>

DATA

this is a data reference. It means that a pointer in the file references the location: dd <location>

STRUCT

this is a structure reference, an identifed structure field (see File parsers) points to this location

SYMBOL

this is a structure reference,, a named symbol points to this location