A brief manual for JEB 1.x (Legacy)

Updated on April 8, 2014

JEB is an interactive Android app disassembler and decompiler. It can handle APK or DEX files. Analysis can be saved to JDB files.

JEB comes in two flavors: JEB Full (GUI + Automation) and JEB Automation (Automation only). Most of this manual applies to the UI aspects of JEB Full. The sections Scripts & Automation and beyond apply to both JEB Full and JEB Automation.

JEB requires SWT and Jython packages to work properly. Please visit the Download section.

Looking to set up floating controllers/clients? See the info page about Floating builds.

Want to know what's new in the latest release? Check out the Changelist.

More questions? Post your question on our Google Groups Community Board.

$ jeb --help
JEB full debug v1.3.201309040 (c) PNF Software, 2013
Usage:
  JEB [options] [inputpath] [-- scriptarg1 [scriptarg2 [...]]]
Arguments:
  inputpath                DEX/APK/JDB file
  scriptargX               script arguments
Options:
  --help                   Print this message and exit
  --license                Display license information
  --automation             Automation mode (default: UI, unless the license is automation-only)
  --script=<scriptpath>    Execute a script at startup (default: no input script)
  --config=<configpath>    Set alternate config file (default: jeb-config.txt in JEB directory)
        

The workspace of JEB UI is divided into four areas, as seen on the picture below:

  • 1 - The menu and toolbar, at the top.
  • 2 - The console window and status bar, at the bottom.
  • 3 - The class hierarchy browser.
  • 4 - A tab folder consisting of many important subviews.

Within a workspace, views representing portions of the analyzed file are contained within the tab folder (4). The views can be closed and re-opened via the Window menu. Here's a list of common views:

  • The Assembly view. This view contains the disassembly code of all classes contained in the DEX file. This view is interactive. The assembly can be exact Smali or simplified Dalvik assembly for improved clarity.
    This view also contains the navigation bar. More information on the navigation bar and how to use it efficiently can be found on our blog. Related post: JEB 1.3: How to Sign and Match Third-Party Library Code.
  • The Decompiled view. This view contains the decompiled bytecode of a class, in Java. Switching back and forth with the assembly view can be done by pressing the Tab key, while the caret is positioned on a class.
  • The Strings view. This view contains the list of strings present in the DEX file. Double-clicking on a string switches back to the assembly view and positions the caret on the first occurence where the string is being used.
  • The Constants view. This view contains the list of numerical constants present in the DEX file. Double-clicking on a constant switches back to the assembly view and positions the caret on the first occurence where the constant is being used.
  • The Manifest view. This view represents the decompressed manifest of the application.
  • The Resources view. This tree view allows the user to explore the application's decompressed resources.
  • The Assets view. This view is very similar to the Resources view, and is used to browse an assets files.
  • The Certificates view. This view offers a human-readable representation of the certificates used to sign the APK.
  • The External Classes/Methods/Fields view. These views list the external (outside the DEX file) classes, methods and fields referenced and used within the DEX file.
  • The Notes view. This view is a placeholder for analysis notes.

The class hierarchy view (3) contains the entire list of classes present in the DEX file. Classes are organized by package.
Clicking or double-clicking on a class name will bring up the Assembly view and position the caret on the chosen class.
For the sake of clarity, the user may decide to temporarliy mask inner classes by ticking the appropriate checkbox at the bottom of tree. (Note: classes can be masqueraded as inner classes; keep that in mind when you analyze a file.)
The currently on-caret class is highlighted in red.

The assembly and decompiled code views are the most crucial views when it comes to analyzing an app. These code views are interactive and work hand-in-hand. (The XML views are also interactive, but are not considered code views.)

These views contain interactive items: they can be classes, fields, methods, opcodes, instructions, comments, etc.

The user can take actions on these views via the Action menu, toolbar or keyboard shortcuts. Mastering the (fairly small set of) keyboard shortcuts is essential if you want to work efficiently within JEB.

For instance, when the user sets the focus on either one of these views, they can:

  • Rename items (N): classs, fields and methods can be renamed. Changes are reflected in the other view. In the decompiled view, variables and parameters can also be renamed. External items (those not defined in the DEX file) cannot be renamed.
  • Insert comments (C): comments may be specific to a class, a field, a method or a specific method instruction. Comments can be text, audio or both. Audio comments are denoted by a bang character (!) prepended to the optional text comment, as can be seen on the example screenhsot.
  • Examine visual cross references (X): most interactive items can be cross-referenced to see where they are used. The cross-references are listed by order of appearance in the code. Double-click a cross-reference to jump to its location.
  • Examine real cross references (Ctrl+X or Cmd+X): these references are useful only when in the decompiled view. Since the view is limited to the currently analyzed class, visual cross-references are limited to that class. The real (code) cross-references come into play: although not as exhaustive as the visual xrefs in the assembly view, they show a list of global references throughout the file.
  • Navigate (Enter): a user can 'follow' items. In in this context, it means jumping to the definition of that item. For instance, following a method call to foo() means jumping to the location where foo() is defined.
  • More: refer to the Action menu.
  • Even more: a user can add their own "custom actions" to the Action menu.

Within the assembly view, the user can decide to decompile a class by pressing Tab. The current view will switch to the decompiled view for the target class, and the caret will be positioned on the closest high-level Java item that matches the source bytecode instruction. Reciprocally, when positioning the caret on a high-level Java item and switching back to the assembly view, JEB tries to position the caret on the low-level bytecode instruction that most closely matches the source Java statement.

The Assembly view contains the navigation bar. As mentioned above, more information on the navigation bar and how to use it efficiently can be found on JEB's blog. Refer to the following post: JEB 1.3: How to Sign and Match Third-Party Library Code.

Built-in actions

These keyboard shortcuts can be used within the code views. For improved productivity, it is greatly recommended to use them. Experienced reverse-engineers will recognize the shortcuts used by standard disassembler tools.

ShortcutDescription
TabDecompile a class (when on assembly view) / Switch back to assembly (when on decompiled view)
F5 / Cmd+RRefresh / synchronize a view
EnterFollow an interactive item
EscapeGo back to the previous caret position in the follow-history
Ctrl+Enter / Cmd+EnterGo forward to the next caret position in the follow-history
HHTML help for an item (currently works for Dalvik opcodes and external classes and methods of the Android SDK)
IView an item information (eg: for a type, its hierarchy; for a method, the overrides, etc.)
XExamine the visual cross-references of an interactive item (xrefs can be double-clicked and followed)
NRename an internal item (class, field, method, variable)
C (or Slash)Insert an inline comment
BChange the base (octal/decimal/hexadecimal) of a constant, within the decompiled view.
Ctrl+XExamine the real (code) cross-references of an interactive item, within the decompiled view.
Ctrl+F5 / Ctrl+Cmd+RForce a refresh (in the code view: force a re-decompilation)

Custom actions

The Action menu can be customized by a user. Custom actions can be inserted in the "Custom Actions" sub-menu. Custom actions (or plugins) are backed by JEB scripts. Simply put, a plugin is a script that:

  • is dropped in the "plugins" directory. The default plugins directory is %JEBDIR%/plugins. That directory can be configured via the Options menu.
  • has an optional plugin line information, that is, a single-line comment starting with '?'. Example:
    #? name=My Sample Plugin, shortcut=Ctrl+Shift+T, help=This Python script is a JEB plugin
    The shortcut modifiers allowed are Ctrl, Shift, Alt, and Command. The keys allowed are all alphanumeric characters, as well as the F1 to F12 functions keys

Example:

Scripting

Scripts can be used to automate tasks, such as looking for methods, renaming classes, decompiling classes, etc. Refer to the API documentation. (Although the documentation pages look like Java docfiles, the currently supported language is Python.)

Scripts can be called within the UI (via "File/Run Script") or from the command-line (with the --script= flag)

Sample scripts can be found in the Resources area.

API usage tutorials can also be found on our blog.

Plugins

Plugins concern only the UI mode of JEB: they are scripts that can be called from the Action menu. Please refer to the "Actions" documentation.

Automation mode

"JEB Full" as well as "JEB Automation" can be used for back-end automation. This mode is not interactive (no UI) and does not offer all the powerful visualization and refactoring features that the UI offers, but it is also leaner and faster, and well suited for bulk processing of files.

Start JEB with the --automation switch.

Use the switch --script= to provide an input script to the engine.

The Edit/Options menu (or Preferences menu on OS X) allows users to customize various aspects and styles of JEB.

The options are grouped into various categories. Most options are self-explanatory.



General notes

Be careful with the "Verify certificates" option. If disabled, you will be able to examine APKs that are improperly signed (such as repacked APKs.) However, the Certificates tab will disappear. Remember to tick the option back if you need to examine certificates, when the APK you are analyzing is signed.

The "Validate chechsum/access flags ..." should be disabled, as many protected APKs contain random header checksum as well as partially invalid access flags for classes, fields, and methods.

The "Parse extended opcodes" option instructs the DEX parse to parse the extended opcodes introduced in ICS - and removed in ICS. These opcodes generalize the jumbo concept to all instructions that make references to pool items (strings, methods, fields, types) and are normally unused.

The decompiler engine option "Aggressive substitutions" is very effective, but can introduce nasty side effects, such as out-of-order function calls. The user should be well aware of these current limitations when the option is enabled.

The decompiler engine option "Parse exception blocks" allows the engine to reconstruct the try-catch blocks and display them in the decompiled view. One current limitation is the order of the catch blocks, which may not accurately reflect the true order. A look at the original bytecode is necessary to precisely determine it.

The "Show debug directives/line numbers" options show the specific metadata in the assembly code. The user should be aware that such metadata can be easily forged, and therefore, should not be trusted.

Enabling the "Port debug parameter names" option presents the same potential issues: these names can be forged. However, the option is enabled by default, and allows the user to manipulate 'real' parameter names in the Java view. So far, this benefit outweighs the drawbacks of potential name forgery.

The "Keep Smali compatibility" option will try to produce assembly code compliant with Smali. Compliance in this context means, for instance: invoke- instructions with parameters first, fully-qualified method names and class names, specific switch structures, etc. By disabling the Smali compatibility, a user can greatly improve the readability of the assembly code.

Style options

Style options include font selection (which affect various views) and color styles.

The default font is set to a standard fixed font, usually Courier New. This may vary from system to system. Recent versions of Courier New have a good amount of Unicode glyphs. However, yours may not have the CJK glyphs, which are essential when dealing with asian locale apps. Should that happen, other fonts may be used, such as FangSong on Windows, or Sans on Ubuntu. These fonts offer a good BMP support, including CJK, Russian, Thai and Arabic.

Note: on MacOS systems, it seems the default fixed font presents a rendering issue within the class hierarchy tree: the underscore is rendered as a space. One solution to fix this issue is to use a different fixed font, for instance Consolas or Monaco.

The "Style manager" button allows a user to customize colors and aspects of various interactive items. This affects the code views as well as the XML views used to render the manifest and other XML resources. Foreground and background colors as well as font attributes for interactive items can be customized.

Most configuration settings can be set from within the UI.

Users of "JEB Automation" (no UI) or advanced users may want to manually edit JEB's configuration file, jeb-config.txt, located in the program's folder.

Note that the default configuration file location can be overriden using the --config= command-line switch.

If you decide to edit this file manually, we recommend you:

  • 1 - Quit JEB.
  • 2 - Make a backup config of jeb-config.txt.


Here is a non-exhaustive list of useful options:


Value nameDescriptionTypeDefault
ctl_check_updateController should check for update on startupbooleanfalse
ctl_interfaceController interface (address or hostname)string
ctl_portController portinteger23477
preferred_languagePreferred languagestring
path_pluginsPlugins directory (custom actions)stringplugins
path_sigsSignatures directory (library signatures)stringsigs
path_javadocURL or path to Android SDK Javadocstringhttps://developer.android.com/
path_dalvikdocURL or path to Dalvik opcodes informationstringhttps://www.pnfsoftware.com/help/dalvik-bytecode.html
proxyNetwork proxy settings (type|address|port)string
check_updateCheck for update on startupbooleantrue
check_update_autoCheck for update on startup (automation mode)booleantrue
check_javaCheck Java version on startupbooleanfalse
compress_dbCompress database itemsbooleantrue
db_autosave_timeout_minutesAuto-save database (timeout in minutes)integer0
apk_parse_dex_onlyParse the DEX file onlybooleanfalse
apk_verifyVerify the certificatesbooleanfalse
dex_check_versionValidate the DEX version numberbooleanfalse
dex_check_hashesValidate checksum and signaturesbooleanfalse
dex_check_access_flagsValidate access flagsbooleanfalse
dex_parse_extended_opcodesParse extended opcodesbooleantrue
dex_trymerge_multidexAttempt to merge the DEX files of a MultiDex APKs into a single DEX filebooleantrue
decomp_method_timeoutTime-out before method decompilation fails (in seconds)integer30
decomp_parse_trycatchesParse exception blocks (try-catch)booleantrue
decomp_parse_debuginfoParse debug informationbooleanfalse
decomp_aggressive_substitutionsAggressive substitutionsbooleantrue
decomp_identname_from_typeGenerate identifier names from their typesbooleanfalse
decomp_ast_opt_string_concatAllow string concatenationbooleantrue
decomp_ast_opt_inline_synth_access_callsInline synthetic accessorsbooleantrue
decomp_ast_opt_create_for_loopsCreate for-loopsbooleantrue
decomp_ast_opt_create_varargsCreate variable-arguments callsbooleantrue
decomp_ast_opt_create_multidimarraysCreate multidimensional arrays instantiationbooleantrue
decomp_ast_opt_create_condassignsCreate conditional assignmentsbooleantrue
asm_mthreshold_disable_interactivityDisable interactivity if the method count exceeds the thresholdinteger30000
asm_show_bytecodeShow bytecodebooleanfalse
asm_show_addressesShow addressesbooleantrue
asm_show_annotationsShow annotationsbooleantrue
asm_show_debugShow debug directivesbooleantrue
asm_show_linenumsShow debug line numbersbooleanfalse
asm_use_p_for_paramsDisplay parameter registers as pXbooleantrue
asm_insert_blanksInsert blank lines after basic blocksbooleanfalse
asm_smali_compatKeep Smali compatibilitybooleanfalse
asm_comment_on_residAdd comments when integers look like resource IDsbooleantrue
asm_separator_charCharacter used to build class separatorsinteger45
asm_separator_lengthLength of the class separator commentinteger80
java_wordwrap_lengthWord wrap lines (length)integer100
java_numbers_hexaGenerate numbers in hexadecimalbooleanfalse
java_port_debug_param_namesPort debug parameter namesbooleantrue
java_display_private_methods_lastDisplay private methods lastbooleanfalse
java_keep_parenthesesKeep the parentheses (safer)booleantrue
java_insert_blanksInsert blank lines after compoundsbooleantrue
java_gen_synth_fieldsGenerate synthetic fieldsbooleanfalse
java_gen_synth_methodsGenerate synthetic methodsbooleantrue
java_gen_annotationsGenerate annotationsbooleantrue
xml_wordwrap_lengthWord wrap lines (length)integer0

Note regarding the network proxy settings

proxy=type|address|port
Used to set up a network proxy, if no direct Internet connection is available. It is optional, and used to check for the availability of a newer version.
Type can be: 'http' or 'socks'.
Example: proxy=http|proxy.lab.company.com|8080


Deprecated fields

The intmethodcount_asm_warning option is deprecated. It is now settable from the UI: see Options (or Preferences) / Assembly / Visualization / Disable interactivity if the method count exceeds the threshold.

Name filters

JEB may take regular expressions of Dalvik items as filters. The syntax is the one defined by the DEX specifications.

Example for classes (used by the decompiled class exporter, accessible from the File menu):
Lpackage1/package2/ClassName;
Example for methods (currenlty not used):
Lpackage1/package2/ClassName;->methodName(II)V
Example for fields (currenlty not used):
Lpackage1/package2/ClassName;->fieldName:I