public interface

IDexUnit

implements ICodeUnit
com.pnfsoftware.jeb.core.units.code.android.IDexUnit

Class Overview

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 UnitChange when the unit contents is being changed. IDexUnit set up event objects such that 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

Summary

Constants
int ACC_ABSTRACT
int ACC_ANNOTATION
int ACC_BRIDGE
int ACC_CONSTRUCTOR
int ACC_DECLARED_SYNCHRONIZED
int ACC_ENUM
int ACC_FINAL
int ACC_INTERFACE
int ACC_NATIVE
int ACC_PRIVATE
int ACC_PROTECTED
int ACC_PUBLIC
int ACC_STATIC
int ACC_STRICT
int ACC_SYNCHRONIZED
int ACC_SYNTHETIC
int ACC_TRANSIENT
int ACC_VARARGS
int ACC_VOLATILE
int INLINE_ALLOWED Inlining mode: allowed.
int INLINE_AUTO Inlining mode: auto-determined.
int INLINE_BLOCKED Inlining mode: blocked.
int INLINE_FORCED Inlining mode: forced.
int ITAG_BYTECODE
int ITAG_CLASS
int ITAG_CUSTOM Do not use directly - reserved by dex decompilers
int ITAG_FIELD
int ITAG_IMMEDIATE
int ITAG_METHOD
int ITAG_PACKAGE
int ITAG_PARAMETER
int ITAG_STRING
int ITAG_TYPE
int ITAG_VARIABLE
int ITAG_VIRTUAL_VAR
int itagBitsize
int itagItemIdShift
String propnameContextInfoDb
Public Methods
abstract void addDex(IInput dexInput)
Add (merge) an additional Dex file into this Dex unit.
abstract IDexField addField(String type, String fieldname, String fieldtype)
Create a new field and add it to the field pool index.
abstract IDexField addField(String signature)
Create a new field and add it to the field pool index.
abstract IDexMethod addMethod(String type, String methodname, String protostring)
abstract IDexMethod addMethod(String signature)
Create a new method reference and add it to the method pool index.
abstract IDexPackage addPackage(String signature)
abstract IDexPrototype addPrototype(String prototypeString)
Create a new Dex prototype and add it to the prototype pool index.
abstract IDexString addString(String value)
Create a new string and add it to the string pool index.
abstract IDexType addType(String typeString)
Create a new type and add it to the type pool index.
abstract int findStringIndex(String s)
Retrieve the pool index of a string, by value.
abstract int getBadTypeCount()
abstract IDexCallSite getCallSite(int index)
abstract List<? extends IDexCallSite> getCallSites()
abstract IDexClass getClass(int index)
Convenience method to retrieve a class by its Dex class pool index.
abstract IDexClass getClass(String fqname)
Convenience method used to retrieve a class by name.
abstract List<? extends IDexClass> getClasses()
Get the Dex class pool
abstract DexCommentManager getCommentManager()
Get the comment manager.
abstract DexConstantLibrary getConstantsLibrary()
Retrieve the constant library object.
abstract IDexContextInfoProvider getContextInfoProvider()
Retrieve the context information provider.
abstract int getCountOfDexFiles()
Retrieve the count of dex files that make up this dex unit.
abstract Collection<IDexAddress> getCrossReferences(DexPoolType poolType, int index)
Retrieve a list of addresses referencing the provided pool item.
abstract Collection<IDexAddress> getCrossReferences(DexPoolType poolType, int index, int cap)
Retrieve a list of addresses referencing the provided pool item.
abstract IDexDecompilerUnit getDecompiler()
Retrieve or create a decompiler for this unit.
abstract IDexFile getDexFile(int index)
Retrieve a dex file by index.
abstract List<IDexFile> getDexFiles()
Retrieve the collection of dex files that make up this dex unit.
abstract String getDisassembly()
This convenience method provides the entire disassembly of the bytecode making up the Dex file.
abstract IDexDisassemblyDocument getDisassemblyDocument()
Convenience method to retrieve the text document representing the disassembly of this code unit.
abstract IDexField getField(String fqname)
Convenience method used to retrieve a field by name.
abstract IDexField getField(int index)
Convenience method to retrieve a field by its Dex field pool index.
abstract List<? extends IDexField> getFields()
Get the Dex field pool
abstract long getInstructionCount()
Retrieve the total amount of instructions in this Dex unit.
abstract IDexMethod getMethod(String fqname)
Convenience method used to retrieve a method by name.
abstract IDexMethod getMethod(int index)
Convenience method to retrieve a method by its Dex method pool index.
abstract IDexMethodHandle getMethodHandle(int index)
abstract List<? extends IDexMethodHandle> getMethodHandles()
abstract List<? extends IDexMethod> getMethods()
Get the Dex method pool
abstract Object getObjectById(long id)
Feature preview.
abstract IDexPackage getPackage(String signature)
abstract List<? extends IDexPackage> getPackages()
Get the list of code packages.
abstract IDexPrototype getPrototype(int index)
Convenience method to retrieve a prototype by its Dex prototype pool index.
abstract List<? extends IDexPrototype> getPrototypes()
Get the list of Dex prototypes defined in the Dex file (prototype pool).
abstract IDexReferenceManager getReferenceManager()
Retrieve the cross-references manager.
abstract Map<IdentifierCoordinates, String> getRenamedIdentifiers()
Retrieve a map of renamed identifiers.
abstract IDexValue getStaticFieldInitializer(int index)
Retrieve the initializer for the static field of a class.
abstract IDexString getString(int index)
Convenience method to retrieve a string by its Dex string pool index.
abstract int getStringCount()
Get the number of strings present in the aggregated string pools represented by this Dex unit.
abstract List<? extends IDexString> getStrings()
Get the Dex string pool, including extra strings added via addString.
abstract IDexType getType(int index)
Retrieve a type by its Dex type pool index.
abstract IDexType getType(String fqname)
Retrieve a type by its fully-qualified name.
abstract ICodeNode getTypeHierarchy(String typesig, int maxNodeCount, boolean includeSuperTypes)
abstract List<? extends IDexType> getTypes()
Get the Dex prototype pool
abstract boolean moveTo(IDexItem src, IDexItem dst)
Move a class or a package to another package, class, or method.
abstract boolean moveTo(IDexItem src, IDexItem dst, boolean skipChecks, boolean neverAnonymous)
Move a class or a package to another package, class, or method.
abstract boolean moveToPackage(IDexItem src, IDexPackage dst)
This method is deprecated. use moveTo(IDexItem, IDexItem, boolean, boolean)
[Expand]
Inherited Methods
From interface com.pnfsoftware.jeb.core.IUnitCreator
From interface com.pnfsoftware.jeb.core.IUserDataSupport
From interface com.pnfsoftware.jeb.core.units.IAddressableUnit
From interface com.pnfsoftware.jeb.core.units.IInteractiveUnit
From interface com.pnfsoftware.jeb.core.units.IUnit
From interface com.pnfsoftware.jeb.core.units.code.ICodeUnit
From interface com.pnfsoftware.jeb.util.events.IEventSource

Constants

public static final int ACC_ABSTRACT

Constant Value: 1024 (0x00000400)

public static final int ACC_ANNOTATION

Constant Value: 8192 (0x00002000)

public static final int ACC_BRIDGE

Constant Value: 64 (0x00000040)

public static final int ACC_CONSTRUCTOR

Constant Value: 65536 (0x00010000)

public static final int ACC_DECLARED_SYNCHRONIZED

Constant Value: 131072 (0x00020000)

public static final int ACC_ENUM

Constant Value: 16384 (0x00004000)

public static final int ACC_FINAL

Constant Value: 16 (0x00000010)

public static final int ACC_INTERFACE

Constant Value: 512 (0x00000200)

public static final int ACC_NATIVE

Constant Value: 256 (0x00000100)

public static final int ACC_PRIVATE

Constant Value: 2 (0x00000002)

public static final int ACC_PROTECTED

Constant Value: 4 (0x00000004)

public static final int ACC_PUBLIC

Constant Value: 1 (0x00000001)

public static final int ACC_STATIC

Constant Value: 8 (0x00000008)

public static final int ACC_STRICT

Constant Value: 2048 (0x00000800)

public static final int ACC_SYNCHRONIZED

Constant Value: 32 (0x00000020)

public static final int ACC_SYNTHETIC

Constant Value: 4096 (0x00001000)

public static final int ACC_TRANSIENT

Constant Value: 128 (0x00000080)

public static final int ACC_VARARGS

Constant Value: 128 (0x00000080)

public static final int ACC_VOLATILE

Constant Value: 64 (0x00000040)

public static final int INLINE_ALLOWED

Inlining mode: allowed. The method may be inlined by code processors.

Constant Value: 2 (0x00000002)

public 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

Constant Value: 0 (0x00000000)

public static final int INLINE_BLOCKED

Inlining mode: blocked. The method must not be inlined by code processors.

Constant Value: 1 (0x00000001)

public static final int INLINE_FORCED

Inlining mode: forced. The method should be inlined by code processors if possible.

Constant Value: 3 (0x00000003)

public static final int ITAG_BYTECODE

Constant Value: 7 (0x00000007)

public static final int ITAG_CLASS

Constant Value: 4 (0x00000004)

public static final int ITAG_CUSTOM

Do not use directly - reserved by dex decompilers

Constant Value: 16 (0x00000010)

public static final int ITAG_FIELD

Constant Value: 5 (0x00000005)

public static final int ITAG_IMMEDIATE

Constant Value: 10 (0x0000000a)

public static final int ITAG_METHOD

Constant Value: 6 (0x00000006)

public static final int ITAG_PACKAGE

Constant Value: 2 (0x00000002)

public static final int ITAG_PARAMETER

Constant Value: 8 (0x00000008)

public static final int ITAG_STRING

Constant Value: 1 (0x00000001)

public static final int ITAG_TYPE

Constant Value: 3 (0x00000003)

public static final int ITAG_VARIABLE

Constant Value: 9 (0x00000009)

public static final int ITAG_VIRTUAL_VAR

Constant Value: 11 (0x0000000b)

public static final int itagBitsize

Constant Value: 8 (0x00000008)

public static final int itagItemIdShift

Constant Value: 56 (0x00000038)

public static final String propnameContextInfoDb

Constant Value: "ContextInfoDb"

Public Methods

public abstract void addDex (IInput dexInput)

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

public abstract 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

public abstract 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

public abstract IDexMethod addMethod (String type, String methodname, String protostring)

public abstract 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

public abstract IDexPackage addPackage (String signature)

public abstract 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

public abstract IDexString addString (String value)

Create a new string and add it to the string pool index.

public abstract 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...;)

public abstract 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

public abstract int getBadTypeCount ()

public abstract IDexCallSite getCallSite (int index)

public abstract List<? extends IDexCallSite> getCallSites ()

public abstract IDexClass getClass (int index)

Convenience method to retrieve a class by its Dex class pool index.

public abstract IDexClass getClass (String fqname)

Convenience method used to retrieve a class by name.

public abstract List<? extends IDexClass> getClasses ()

Get the Dex class pool

public abstract DexCommentManager getCommentManager ()

Get the comment manager. This method is optional. When the unit is disposed, this method must return null. The default implementation returns null.

Returns
  • a comment manager, or null if the unit does not have one

public abstract 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)

public abstract 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.

public abstract int getCountOfDexFiles ()

Retrieve the count of dex files that make up this dex unit.

public abstract 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

public abstract 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)

public abstract 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.

public abstract IDexFile getDexFile (int index)

Retrieve a dex file by index.

When the dex unit is the result of processing an APK, the first entry (index 0) represents the primary dex file, classes.dex; entries 1...N represent additional classesN.dex of the APK is a multi-dex; additional dex files, dynamically added via addDex(IInput)}, are found at index N+1 and beyond.

Parameters
index a dex file index
Returns
  • the dex file

public abstract List<IDexFile> getDexFiles ()

Retrieve the collection of dex files that make up this dex unit.

When the dex unit is the result of processing an APK, the first entry (index 0) represents the primary dex file, classes.dex; entries 1...N represent additional classesN.dex of the APK is a multi-dex; additional dex files, dynamically added via addDex(IInput)}, are found at index N+1 and beyond.

Returns
  • a non-empty collection of dex files; when restoring pre-JEB 2.3 JDB2, this list will be null

public abstract 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 getFormatter().

public abstract IDexDisassemblyDocument getDisassemblyDocument ()

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.

public abstract IDexField getField (String fqname)

Convenience method used to retrieve a field by name.

public abstract IDexField getField (int index)

Convenience method to retrieve a field by its Dex field pool index.

public abstract List<? extends IDexField> getFields ()

Get the Dex field pool

public abstract 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.

public abstract IDexMethod getMethod (String fqname)

Convenience method used to retrieve a method by name.

public abstract IDexMethod getMethod (int index)

Convenience method to retrieve a method by its Dex method pool index.

public abstract IDexMethodHandle getMethodHandle (int index)

public abstract List<? extends IDexMethodHandle> getMethodHandles ()

public abstract List<? extends IDexMethod> getMethods ()

Get the Dex method pool

public abstract Object getObjectById (long id)

Feature preview.

public abstract IDexPackage getPackage (String signature)

public abstract List<? extends IDexPackage> getPackages ()

Get the list of code packages.

public abstract IDexPrototype getPrototype (int index)

Convenience method to retrieve a prototype by its Dex prototype pool index.

Parameters
index prototype index

public abstract List<? extends IDexPrototype> getPrototypes ()

Get the list of Dex prototypes defined in the Dex file (prototype pool).

Returns
  • a list of prototypes

public abstract IDexReferenceManager getReferenceManager ()

Retrieve the cross-references manager.

public abstract Map<IdentifierCoordinates, String> getRenamedIdentifiers ()

Retrieve a map of renamed identifiers. Only renamed identifiers are stored in the returned object.

public abstract 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

public abstract IDexString getString (int index)

Convenience method to retrieve a string by its Dex string pool index.

public abstract int getStringCount ()

Get the number of strings present in the aggregated string pools represented by this Dex unit.

public abstract List<? extends IDexString> getStrings ()

Get the Dex string pool, including extra strings added via addString.

public abstract IDexType getType (int index)

Retrieve a type by its Dex type pool index.

public abstract IDexType getType (String fqname)

Retrieve a type by its fully-qualified name.

Parameters
fqname eg, Lcom/foo/Bar;

public abstract ICodeNode getTypeHierarchy (String typesig, int maxNodeCount, boolean includeSuperTypes)

public abstract List<? extends IDexType> getTypes ()

Get the Dex prototype pool

public abstract 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

public abstract 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

public abstract boolean moveToPackage (IDexItem src, IDexPackage dst)

This method is deprecated.
use moveTo(IDexItem, IDexItem, boolean, boolean)

Move a class or a package to a destination package.@return

Parameters
src a class or a package item
dst the destination package item