Cross References (analysis.xrefs)

analysis.xrefs: malcat.CrossReferences: The analysis.xrefs object is a malcat.CrossReferenceList instance that gives you access to all the cross references (both code xref and data xref) found by the /analysis.xrefs 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.xrefs object. This object has the following methods and attributes:

class malcat.CrossReferences

This class contains all cross-references identified by the /analysis.xrefs. 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.xrefs:
    print(f"* 0x{analysis.a2v(r.address):x} is referenced {r.count} times")

Return type:: iterator over ReferenceList

__getitem__(interval)

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

text = analysis.map[".text"]
for ref_list in analysis.xrefs[text.start : text.end]:
    print(f"* {analysis.ppa(ref_list.target)} is referenced {len(ref_list)} times")

Parameters:: interval (slice) – effective address interval
Return type:: iterator over ReferenceList

__getitem__(ea)

Returns a ReferenceList object that contains all the references to the effective address ea.

first_function = analysis.fns.find_forward(0)
if first_function is not None:
    ref_list = analysis.xrefs[first_function.address]
    for source in ref_list:
        print(f"\nFunction {first_function.name} is referenced by {analysis.ppa(source.address)}")

Parameters:: ea (int) – effective address
Return type:: a ReferenceList object that contains the list of incoming references

__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.xrefs:
    print("First function is not referenced")

Parameters:: ea (int) – address to query
Return type:: bool

find(ea)

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

Parameters:: ea (int) – effective address for the query
Return type:: ReferenceList or None

find_forward(ea)

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

first_xref = analysis.xrefs.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:: ReferenceList or None

find_backward(ea)

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

last_xref = analysis.xrefs.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:: ReferenceList or None

__len__()

return the number of cross references in the file

if len(analysis.xrefs) == 0:
    raise ValueError("No cross ref found!")

Return type:: int

Reference objects 

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

class malcat.ReferenceList

address: int (effective address): referenced address, aka target address

target: int (effective address): sane as address

count: int: number of different locations referencing this address

__len__()

same as count

Return type:: int

__iter__()

iterate over all incoming Reference for the given address.

first_function = analysis.fns.find_forward(0)
if first_function is not None and first_function.address in analysis.xrefs:
    reflist = analysis.xrefs[first_function.address]
    print(f"\nFunction {first_function.name} is referenced by:")
    for source in reflist:
        print(f"    * {analysis.ppa(source.address)} ({source.type})")

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

Returns:: iterator over Reference
Return type:: iterator over Reference

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

class malcat.Reference

address: int (effective address): reference address: source address for incoming references (like in this module), but can be target address for outgoing references (like in malcat.BasicBlock.outrefs)

type: malcat.Reference.Type: type of reference

is_code: bool: true iff reference is from an instruction, i.e. self.type == malcat.Reference.Type.CODE

is_data: bool: true iff reference is from a data pointer, a struct or a symbol, i.e. self.type != malcat.Reference.Type.CODE

r: bool: for code reference only, is the referenced address read (e.g. mov eax, [<referenced>])

w: bool: for code reference only, is the referenced address written (e.g. mov [<referenced>], eax)

x: bool

for code reference only, is the referenced address executed (e.g. jmp <referenced>)

Note that for indirect jumps (e.g. call [<referenced>]), both r and x are set

The reference type can be:

class malcat.Reference.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.xrefs)

Accessing / enumerating cross-references

Reference objects

Accessing / enumerating cross-references 

Reference objects 