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

    • ACC_PUBLIC

      static final int ACC_PUBLIC
      Dex access flag for public items.
      See Also:

    • ACC_PRIVATE

      static final int ACC_PRIVATE
      Dex access flag for private items.
      See Also:

    • ACC_PROTECTED

      static final int ACC_PROTECTED
      Dex access flag for protected items.
      See Also:

    • ACC_STATIC

      static final int ACC_STATIC
      Dex access flag for static items.
      See Also:

    • ACC_FINAL

      static final int ACC_FINAL
      Dex access flag for final items.
      See Also:

    • ACC_SYNCHRONIZED

      static final int ACC_SYNCHRONIZED
      Dex access flag for synchronized methods.
      See Also:

    • ACC_VOLATILE

      static final int ACC_VOLATILE
      Dex access flag for volatile fields.
      See Also:

    • ACC_BRIDGE

      static final int ACC_BRIDGE
      Dex access flag for bridge methods.
      See Also:

    • ACC_TRANSIENT

      static final int ACC_TRANSIENT
      Dex access flag for transient fields.
      See Also:

    • ACC_VARARGS

      static final int ACC_VARARGS
      Dex access flag for variable argument methods.
      See Also:

    • ACC_NATIVE

      static final int ACC_NATIVE
      Dex access flag for native methods.
      See Also:

    • ACC_INTERFACE

      static final int ACC_INTERFACE
      Dex access flag for interfaces.
      See Also:

    • ACC_ABSTRACT

      static final int ACC_ABSTRACT
      Dex access flag for abstract items.
      See Also:

    • ACC_STRICT

      static final int ACC_STRICT
      Dex access flag for strict floating-point methods.
      See Also:

    • ACC_SYNTHETIC

      static final int ACC_SYNTHETIC
      Dex access flag for synthetic items.
      See Also:

    • ACC_ANNOTATION

      static final int ACC_ANNOTATION
      Dex access flag for annotation classes.
      See Also:

    • ACC_ENUM

      static final int ACC_ENUM
      Dex access flag for enumeration classes and fields.
      See Also:

    • ACC_CONSTRUCTOR

      static final int ACC_CONSTRUCTOR
      Dex access flag for constructor methods.
      See Also:

    • ACC_DECLARED_SYNCHRONIZED

      static final int ACC_DECLARED_SYNCHRONIZED
      Dex access flag for declared synchronized methods.
      See Also:

    • INLINE_AUTO

      static final int INLINE_AUTO
      Inlining mode: auto-determined. This mode is to be understood as 'limited', that is, inlining is blocked except for trivial cases
      See Also:

    • INLINE_BLOCKED

      static final int INLINE_BLOCKED
      Inlining mode: blocked. The method must not be inlined by code processors.
      See Also:

    • INLINE_ALLOWED

      static final int INLINE_ALLOWED
      Inlining mode: allowed. The method may be inlined by code processors.
      See Also:

    • INLINE_FORCED

      static final int INLINE_FORCED
      Inlining mode: forced. The method should be inlined by code processors if possible.
      See Also:

    • itagItemIdShift

      static final int itagItemIdShift
      Bit shift of the item id in encoded Dex item addresses.
      See Also:

    • itagBitsize

      static final int itagBitsize
      Bits reserved for an encoded Dex item address tag.
      See Also:

    • ITAG_STRING

      static final int ITAG_STRING
      Encoded address tag for strings.
      See Also:

    • ITAG_PACKAGE

      static final int ITAG_PACKAGE
      Encoded address tag for packages.
      See Also:

    • ITAG_TYPE

      static final int ITAG_TYPE
      Encoded address tag for types.
      See Also:

    • ITAG_CLASS

      static final int ITAG_CLASS
      Encoded address tag for classes.
      See Also:

    • ITAG_FIELD

      static final int ITAG_FIELD
      Encoded address tag for fields.
      See Also:

    • ITAG_METHOD

      static final int ITAG_METHOD
      Encoded address tag for methods.
      See Also:

    • ITAG_BYTECODE

      static final int ITAG_BYTECODE
      Encoded address tag for bytecode locations.
      See Also:

    • ITAG_PARAMETER

      static final int ITAG_PARAMETER
      Encoded address tag for parameters.
      See Also:

    • ITAG_VARIABLE

      static final int ITAG_VARIABLE
      Encoded address tag for variables.
      See Also:

    • ITAG_IMMEDIATE

      static final int ITAG_IMMEDIATE
      Encoded address tag for immediates.
      See Also:

    • ITAG_VIRTUAL_VAR

      static final int ITAG_VIRTUAL_VAR
      Encoded address tag for virtual variables.
      See Also:

    • ITAG_CUSTOM

      static final int ITAG_CUSTOM
      Do not use directly - reserved by dex decompilers
      See Also:

    • propnameContextInfoDb

      static final String propnameContextInfoDb
      Unit property name for the context information database path.
      See Also:

  • Method Details

    • getCountOfDexEntries

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

    • getCountOfDexFiles

      @Deprecated default int getCountOfDexFiles()
      Deprecated.
      use getCountOfDexEntries()
      Returns:
      the number of dex entries

    • 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

      @Deprecated default List<IDexFile> getDexFiles()
      Deprecated.
      use getDexEntries()
      Returns:
      a non-empty collection of dex entries

    • getDexEntry

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

    • getDexFile

      @Deprecated default IDexFile getDexFile(int index)
      Deprecated.
      getDexEntry(int)
      Parameters:
      index - dex entry index
      Returns:
      the dex entry

    • 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:
      code strings

    • getString

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

    • getStringCount

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

    • addString

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

    • 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:
      the Dex prototype

    • 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:
      the created Dex prototype

    • getTypes

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

    • getType

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

    • getType

      IDexType getType(String fqname)
      Retrieve a type by its fully-qualified name.
      Parameters:
      fqname - eg, Lcom/foo/Bar;
      Returns:
      the Dex type, or null if none was found

    • 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:
      the created Dex type

    • getBadTypeCount

      int getBadTypeCount()
      Get the number of invalid type descriptors.
      Returns:
      the bad type count

    • 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
      Parameters:
      fqname - fully-qualified class name
      Returns:
      matching class, or null

    • getClasses

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

    • getClass

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

    • findClassByName

      IDexClass findClassByName(String searchedName)
      Find a class by effective name, unambiguously.
      Parameters:
      searchedName - class name, which could be a simple name, e.g. Bar for com.foo.Bar or Inner1 for com.foo.Bar$Inner1
      Returns:
      the class or null if nothing was found or if the searched name was ambiguous

    • findClassByName

      List<IDexClass> findClassByName(String searchedName, int maxCount, boolean alsoCheckOriginalName)
      Find a class by name.
      Parameters:
      searchedName - class name, which could be a simple name, e.g. Bar for com.foo.Bar or Inner1 for com.foo.Bar$Inner1
      maxCount - maximum count of results (-1 means no max)
      alsoCheckOriginalName - if true, the original (pre-renaming) class names are checked as well
      Returns:
      the list of classes

    • getFields

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

    • 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
      Parameters:
      fqname - fully-qualified field name
      Returns:
      matching field, or null

    • getField

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

    • 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:
      the created Dex field

    • 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:
      the created Dex field

    • getMethods

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

    • 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
      Parameters:
      fqname - fully-qualified method name
      Returns:
      matching method, or null

    • getMethod

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

    • 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:
      the created Dex method

    • addMethod

      IDexMethod addMethod(String type, String methodname, String protostring)
      Create a new method reference and add it to the method pool index.
      Parameters:
      type - defining type signature
      methodname - method name
      protostring - method prototype string
      Returns:
      the created Dex method

    • getCallSite

      IDexCallSite getCallSite(int index)
      Retrieve a call site by index.
      Parameters:
      index - call site pool index
      Returns:
      the Dex call site

    • getCallSites

      List<? extends IDexCallSite> getCallSites()
      Get the Dex call site pool.
      Returns:
      the call sites

    • getMethodHandle

      IDexMethodHandle getMethodHandle(int index)
      Retrieve a method handle by index.
      Parameters:
      index - method handle pool index
      Returns:
      the Dex method handle

    • getMethodHandles

      List<? extends IDexMethodHandle> getMethodHandles()
      Get the Dex method handle pool.
      Returns:
      the method handles

    • getPackages

      List<? extends IDexPackage> getPackages()
      Get the Dex package pool.
      Specified by:
      getPackages in interface ICodeUnit
      Returns:
      code packages

    • getPackage

      IDexPackage getPackage(String signature)
      Retrieve a package by signature.
      Specified by:
      getPackage in interface ICodeUnit
      Parameters:
      signature - fully-qualified package name, e.g. com.foo.bar
      Returns:
      the Dex package, or null if none was found

    • addPackage

      IDexPackage addPackage(String signature)
      Create a package and add it to the package pool.
      Parameters:
      signature - fully-qualified package name, e.g. com.foo.bar
      Returns:
      the created Dex package

    • moveTo

      boolean moveTo(IDexItem src, IDexItem dst, boolean skipChecks, boolean neverAnonymous, boolean notify)
      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
      notify - true to notify listeners of the change
      Returns:
      success indicator

    • moveTo

      default 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; when 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:
      the instruction count

    • 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:
      disassembly document

    • 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:
      disassembly text

    • 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:
      a list of cross-reference addresses

    • 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:
      a list of cross-reference addresses

    • getReferenceManager

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

    • 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:
      the renamed identifier map

    • getObjectById

      Object getObjectById(long id)
      Retrieve an object by encoded id.
      Parameters:
      id - encoded object id
      Returns:
      the object, or null if none was found

    • 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 - if the input could not be read or merged

    • 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:
      the constant library

    • 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:
      the context information provider

    • 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:
      the decompiler unit, or null if unavailable

    • getTypeHierarchy

      ICodeNode getTypeHierarchy(String typesig, int maxNodeCount, boolean includeSuperTypes)
      Generate a type hierarchy tree.
      Parameters:
      typesig - root type signature
      maxNodeCount - maximum number of nodes to generate
      includeSuperTypes - true to include supertypes
      Returns:
      the type hierarchy root node

    • setMethodMatch

      MethodMatch setMethodMatch(IDexMethod m, MethodMatch match)
      Attach a method-match object to a dex method.

      This method is thread-safe. Match objects can be attached by any component.

      Parameters:
      m - the target method
      match - a match item
      Returns:
      the previously attached match item, null if none

    • getMethodMatch

      MethodMatch getMethodMatch(IDexMethod m)
      Retrieve the method-match object attached to a dex method.

      This method is thread-safe. Match objects can be attached by any component.

      Parameters:
      m - the target method
      Returns:
      the attached match item, or null if none