Package com.pnfsoftware.jeb.core.units.code.android

Interface IDexUnit

All Superinterfaces:
IAddressableUnit, ICodeUnit, IEventSource, IInteractiveUnit, IUnit, IUnitCreator, IUserDataSupport
@Ser public interface IDexUnit extends ICodeUnit
Interface for units representing Android Dalvik bytecode containers, aka Dex files. The Dex unit interface is a virtual view of the Dex bytecode contained an Android application (APK).

Dex units use Java-style internal addresses to identify items:
- package: Lcom/abc/
- type: Lcom/abc/Foo;
- method: Lcom/abc/Foo;->bar(I[JLjava/Lang/String;)V
- field: Lcom/abc/Foo;->flag1:Z
More information here.

Note that in the case of multi-Dex APKs, the Dex unit represents a virtual, unified view of the separate Dex files contained in the APK. If required, the individual information about those Dex files can be retrieved via IDexFile.

Like many units, Dex unit objects emit J.UnitChange when the unit contents is being changed. IDexUnit set up event objects such that JebEvent.getData() will return a UnitChangeEventData with fields reasonably populated.

How use the JEB API to interact with those objects?
- Writing JEB client scripts in Python is a great way to ease into the JEB API.
- Visit this public GitHub repository for sample code
- In the JEB client, use F2 to bring up the script manager, and try out some sample scripts

Below is a sample client script that shows how to retrieve a project, find the main dex unit, enumerate dex methods, check the bytecode and search for specific instructions.
File: ListDexMethodsWithXor.py 

#?description=List dex methods making use of xor instructions
#?shortcut=

from com.pnfsoftware.jeb.client.api import IScript
from com.pnfsoftware.jeb.core.units.code.android import IDexUnit

class ListDexMethodsWithXor(IScript):

  def run(self, ctx):
    prj = ctx.getMainProject()
    assert prj, 'Need a project'

    dex = prj.findUnit(IDexUnit)
    assert dex, 'Need a dex unit'

    cnt = 0
    for m in dex.getMethods():
      if m.isInternal():
        ci = m.getData().getCodeItem()
        if ci and self.checkMethod(ci):
          print(m.getSignature(True, False))
          cnt += 1
    print('Found %d methods' % cnt)

  def checkMethod(self, ci):
    for insn in ci.getInstructions():
      if insn.toString().find('xor-') >= 0:
        return True
    return False

  • Field Details

  • Method Details

    • getCountOfDexEntries

      int getCountOfDexEntries()
      Retrieve the count of dex entries managed by this unit.
      Returns:

    • getCountOfDexFiles

      default int getCountOfDexFiles()
      Deprecated.
      use getCountOfDexEntries()

    • getDexEntries

      List<IDexFile> getDexEntries()
      Retrieve the collection of dex entries managed by this dex unit.

      When the unit is the result of processing a multi-dex APK, dex files containing multiple dex entries (container dex, version 41+), or if the unit received additional dex files, this method will return a list with multiple items.

      Returns:
      a non-empty collection of dex entries

    • getDexFiles

      default List<IDexFile> getDexFiles()
      Deprecated.
      use getDexEntries()

    • getDexEntry

      IDexFile getDexEntry(int index)
      Retrieve a dex entry by index.
      Parameters:
      index - an index
      Returns:
      the dex entry

    • getDexFile

      default IDexFile getDexFile(int index)
      Deprecated.
      getDexEntry(int)

    • findStringIndex

      int findStringIndex(String s)
      Retrieve the pool index of a string, by value.
      Parameters:
      s - a string
      Returns:
      an string pool index, -1 if the string was not found

    • getStrings

      List<? extends IDexString> getStrings()
      Get the Dex string pool, including extra strings added via addString.
      Specified by:
      getStrings in interface ICodeUnit
      Returns:

    • getString

      IDexString getString(int index)
      Convenience method to retrieve a string by its Dex string pool index.
      Parameters:
      index -
      Returns:

    • getStringCount

      int getStringCount()
      Get the number of strings present in the aggregated string pools represented by this Dex unit.
      Returns:

    • addString

      IDexString addString(String value)
      Create a new string and add it to the string pool index.
      Parameters:
      value -
      Returns:

    • getPrototypes

      List<? extends IDexPrototype> getPrototypes()
      Get the list of Dex prototypes defined in the Dex file (prototype pool).
      Returns:
      a list of prototypes

    • getPrototype

      IDexPrototype getPrototype(int index)
      Convenience method to retrieve a prototype by its Dex prototype pool index.
      Parameters:
      index - prototype index
      Returns:

    • addPrototype

      IDexPrototype addPrototype(String prototypeString)
      Create a new Dex prototype and add it to the prototype pool index.
      Parameters:
      prototypeString - a full prototype string, such as: (typeParam1,typeParam2,...)typeReturn
      Returns:

    • getTypes

      List<? extends IDexType> getTypes()
      Get the Dex prototype pool
      Specified by:
      getTypes in interface ICodeUnit
      Returns:

    • getType

      IDexType getType(int index)
      Retrieve a type by its Dex type pool index.
      Parameters:
      index -
      Returns:

    • getType

      IDexType getType(String fqname)
      Retrieve a type by its fully-qualified name.
      Parameters:
      fqname - eg, Lcom/foo/Bar;
      Returns:

    • addType

      IDexType addType(String typeString)
      Create a new type and add it to the type pool index.
      Parameters:
      typeString - a fully-qualified type name, using the standard Java internal signature notation (L...;)
      Returns:

    • getBadTypeCount

      int getBadTypeCount()
      Returns:

    • getClass

      IDexClass getClass(String fqname)
      Description copied from interface: ICodeUnit
      Convenience method used to retrieve a class by name.
      Specified by:
      getClass in interface ICodeUnit
      Returns:

    • getClasses

      List<? extends IDexClass> getClasses()
      Get the Dex class pool
      Specified by:
      getClasses in interface ICodeUnit
      Returns:

    • getClass

      IDexClass getClass(int index)
      Convenience method to retrieve a class by its Dex class pool index.
      Parameters:
      index -
      Returns:

    • getFields

      List<? extends IDexField> getFields()
      Get the Dex field pool
      Specified by:
      getFields in interface ICodeUnit
      Returns:

    • getField

      IDexField getField(String fqname)
      Description copied from interface: ICodeUnit
      Convenience method used to retrieve a field by name.
      Specified by:
      getField in interface ICodeUnit
      Returns:

    • getField

      IDexField getField(int index)
      Convenience method to retrieve a field by its Dex field pool index.
      Parameters:
      index -
      Returns:

    • getStaticFieldInitializer

      IDexValue getStaticFieldInitializer(int index)
      Retrieve the initializer for the static field of a class.
      Parameters:
      index - the field index
      Returns:
      the static initializer, or null if there's none

    • addField

      IDexField addField(String signature)
      Create a new field and add it to the field pool index.
      Parameters:
      signature - full, eg Lcom/foo/Bar;->val:I
      Returns:

    • addField

      IDexField addField(String type, String fieldname, String fieldtype)
      Create a new field and add it to the field pool index.
      Parameters:
      type - full, eg Lcom/foo/Bar;->val:I
      fieldname - simple name
      fieldtype - full, eg Lcom/foo/Bar;->val:I
      Returns:

    • getMethods

      List<? extends IDexMethod> getMethods()
      Get the Dex method pool
      Specified by:
      getMethods in interface ICodeUnit
      Returns:

    • getMethod

      IDexMethod getMethod(String fqname)
      Description copied from interface: ICodeUnit
      Convenience method used to retrieve a method by name.
      Specified by:
      getMethod in interface ICodeUnit
      Returns:

    • getMethod

      IDexMethod getMethod(int index)
      Convenience method to retrieve a method by its Dex method pool index.
      Parameters:
      index -
      Returns:

    • addMethod

      IDexMethod addMethod(String signature)
      Create a new method reference and add it to the method pool index.
      Parameters:
      signature - full signature, including type name, eg: La/b/Foo;->bar(ILjava/lang/String;)Z
      Returns:

    • addMethod

      IDexMethod addMethod(String type, String methodname, String protostring)
      Parameters:
      type -
      methodname -
      protostring -
      Returns:

    • getCallSite

      IDexCallSite getCallSite(int index)
      Parameters:
      index -
      Returns:

    • getCallSites

      List<? extends IDexCallSite> getCallSites()
      Returns:

    • getMethodHandle

      IDexMethodHandle getMethodHandle(int index)
      Parameters:
      index -
      Returns:

    • getMethodHandles

      List<? extends IDexMethodHandle> getMethodHandles()
      Returns:

    • getPackages

      List<? extends IDexPackage> getPackages()
      Description copied from interface: ICodeUnit
      Get the list of code packages.
      Specified by:
      getPackages in interface ICodeUnit
      Returns:

    • getPackage

      IDexPackage getPackage(String signature)
      Parameters:
      signature - fully-qualified package name, e.g. com.foo.bar
      Returns:

    • addPackage

      IDexPackage addPackage(String signature)
      Parameters:
      signature - fully-qualified package name, e.g. com.foo.bar
      Returns:

    • moveTo

      boolean moveTo(IDexItem src, IDexItem dst, boolean skipChecks, boolean neverAnonymous)
      Move a class or a package to another package, class, or method.
      Parameters:
      src - an IDexPackage or IDexClass
      dst - an IDexPackage, IDexClass or IDexMethod
      skipChecks - skip extra sanity checks (if applicable)
      neverAnonymous - legal only when moving a class to another method (else N/A); if true, the moved class will never be made an anonymous class of the destination method; if false, an anonymous class will be favored, if it is possible to do so
      Returns:
      success indicator

    • moveTo

      default boolean moveTo(IDexItem src, IDexItem dst)
      Move a class or a package to another package, class, or method. Checks are not skipped; whne moving a class to a method, the class will be made anonymous.
      Parameters:
      src - an IDexPackage or IDexClass
      dst - an IDexPackage, IDexClass or IDexMethod
      Returns:
      success indicator

    • getInstructionCount

      long getInstructionCount()
      Retrieve the total amount of instructions in this Dex unit. Note that if this unit represents the virtual Dex file resulting from the merge of several classesX.dex files, the number of instructions returned is the sum of instructions of each individual Dex file.
      Returns:

    • getDisassemblyDocument

      IDexDisassemblyDocument getDisassemblyDocument()
      Description copied from interface: ICodeUnit
      Convenience method to retrieve the text document representing the disassembly of this code unit.

      The caller is responsible for disposing the returned document after usage.

      Specified by:
      getDisassemblyDocument in interface ICodeUnit
      Returns:

    • getDisassembly

      String getDisassembly()
      This convenience method provides the entire disassembly of the bytecode making up the Dex file. This method is a convenience method: the disassembly text document object can always be retrieved via IUnit.getFormatter().
      Specified by:
      getDisassembly in interface ICodeUnit
      Returns:

    • getCrossReferences

      Collection<IDexAddress> getCrossReferences(DexPoolType poolType, int index, int cap)
      Retrieve a list of addresses referencing the provided pool item. This method is left for convenience and legacy only. Newer scripts should use getReferenceManager().
      Parameters:
      poolType - pool item type; currently supported for xrefs: STRING, TYPE, FIELD, METHOD
      index - pool item index
      cap - max number of references to return (leave to 0 to mean return everything possible)
      Returns:

    • getCrossReferences

      Collection<IDexAddress> getCrossReferences(DexPoolType poolType, int index)
      Retrieve a list of addresses referencing the provided pool item. This method is left for convenience and legacy only. Newer scripts should use getReferenceManager().
      Parameters:
      poolType - pool item type; currently supported for xrefs: STRING, TYPE, FIELD, METHOD
      index - pool item index
      Returns:

    • getReferenceManager

      IDexReferenceManager getReferenceManager()
      Retrieve the cross-references manager.
      Returns:

    • getCommentManager

      DexCommentManager getCommentManager()
      Description copied from interface: IInteractiveUnit
      Get the comment manager. This method is optional. When the unit is disposed, this method must return null. The default implementation returns null.
      Specified by:
      getCommentManager in interface ICodeUnit
      Specified by:
      getCommentManager in interface IInteractiveUnit
      Returns:
      a comment manager, or null if the unit does not have one

    • getRenamedIdentifiers

      Map<IdentifierCoordinates,String> getRenamedIdentifiers()
      Retrieve a map of renamed identifiers. Only renamed identifiers are stored in the returned object.
      Returns:

    • getObjectById

      Object getObjectById(long id)
      Feature preview.
      Parameters:
      id -
      Returns:

    • addDex

      void addDex(IInput dexInput) throws IOException
      Add (merge) an additional Dex file into this Dex unit.
      Parameters:
      dexInput - a Dex input (file input, bytes input, etc.) or a ZIP input containing a single classes.dex entry
      Throws:
      IOException

    • getConstantsLibrary

      DexConstantLibrary getConstantsLibrary()
      Retrieve the constant library object. The constants library holds the constant fields of this dex unit (that is, all static final fields ,regardless of their visibility attributes) as well as values attached to pure field references (external fields)
      Returns:

    • getContextInfoProvider

      IDexContextInfoProvider getContextInfoProvider()
      Retrieve the context information provider. This provider can be used to retrieve methods' context access information (context-sensitivity, side-effect) and fields' effective finality information.
      Returns:

    • getDecompiler

      IDexDecompilerUnit getDecompiler()
      Retrieve or create a decompiler for this unit. If dexdec (the Dex Decompiler module) is not available with your JEB license, null is returned.
      Returns:

    • getTypeHierarchy

      ICodeNode getTypeHierarchy(String typesig, int maxNodeCount, boolean includeSuperTypes)
      Parameters:
      typesig -
      maxNodeCount -
      includeSuperTypes -
      Returns: