Cross References (analysis.xref)

analysis.xref: malcat.CrossReferences: The analysis.xref object is a malcat.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 analysis.xref object. This object has the following methods and attributes:

class malcat.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 analysis.xref:
    print(f"* 0x{analysis.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 = analysis.map[".text"]
for r in analysis.xref[text.start : text.end]:
    print(f"* 0x{analysis.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 = analysis.fns.find_forward(0)
if first_function is not None and first_function.address in analysis.xref:
    xref = analysis.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 = analysis.fns.find_forward(0)
if not first_function.address in analysis.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 = analysis.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 = analysis.xref.find_backward(analysis.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(analysis.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 malcat.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 = analysis.fns.find_forward(0)
if first_function is not None and first_function.address in analysis.xref:
    xref = analysis.xref[first_function.address]
    print(f"\nFunction {first_function.name} is referenced by:")
    for ref_type, ref_source in xref:
        print(f"    * 0x{analysis.map.to_virt(ref_source):x} ({ref_type})")

Note that for malcat.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 (malcat.References.Type, int)

The reference type can be:

class malcat.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

Cross References (analysis.xref)

Accessing / enumerating cross-references

References object

Accessing / enumerating cross-references 

References object 