# 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