Getting Started¶

This document is a usage manual for JEB version 2. Last revision: October 25, 2017. The latest version of this manual can be found online on the PNF Software web site.

JEB is a reverse-engineering platform to perform disassembly, decompilation, debugging, and analysis of code and document files, manually or as part of an analysis pipeline.

• The first part of this guide is a user manual that covers basic usage related to analyzing, decompiling and debugging applications (Android apps, as well as native binaries). It is not an exhaustive resource. We recommend visiting our blog for additional, pointed resources describing a variety of use cases.
• The second half is a developer portal for advanced users who will want to use the JEB API to script tasks, develop plugins, or even craft their own front-ends. Alongside these pages, the API reference documentation website will be an indispensable resource.

Note to JEB 1.x users: JEB2 also ships with modules to analyze Android applications. Generally, JEB2 can be seen as a superset of JEB1.

Installation¶

Software Package¶

The software package is distributed as a zip archive, custom-generated for each registered user. It contains the back-end components as well as the reference front-end implementation for desktop platforms, referred to as the "RCP client". This manual focuses mostly on using JEB through the RCP client.

The RCP client client runs on Windows, Linux, and macOS (formerly OS X) operating systems, 32-bit and 64-bit versions.

Requirements¶

Java¶

JEB requires a Java Runtime Environment (JRE) or Java Development Kit (JDK) version 8. (Note that jeb.jar works with older JRE 7, or newer JRE 9; however, the UI desktop client requires a JRE 8.)

UI Support Package¶

The RCP client requires a support package. The support package contains common graphical framework components based on the Eclipse Rich Client Platform framework.

• If you are running JEB on an Internet-connected computer, the latest and most appropriate version of the support package for your system will be downloaded and installed.
• If you are running JEB within a limited connectivity environment, you will need to download the support package manually. See below.

Setup¶

Make sure you have a JRE or JDK installed.

• The java binary must be accessible from the PATH environment variable.
• Optionally, you may also want to set a JAVA_HOME environment variable pointing to your Java installation folder.

64-bit or 32-bit: if you are running on a 64-bit system, we recommend you install and use a 64-bit Java environment. A common source of problems are 64-bit systems having a 32-bit JRE accessible from the PATH. You may have different versions of Java installed, but always make sure that the PATH refers to one that matches your system specifications.

Then, unpack your JEB zip archive into the folder of your choice. Make sure that the folder and its contents are recursively user-writeable.

Optional step: If you are running JEB within a limited connectivity environment, you must download a support package manually:

• Visit the Support Package page
• Download the package appropriate for your environment
• Drop it into the [JEB_FOLDER]/bin/ directory

Startup¶

Next, execute the startup script appropriate for your environment:

• On Windows: execute jeb_wincon.bat
• On Linux: execute jeb_linux.sh.
• On MacOS: execute jeb_macos.sh

If a support package was not found in the bin/ folder, an appropriate one will be downloaded automatically. If your system is not connected to the Internet, you must download one manually! Please read the section above before proceeding.

The startup script will then locate and decrypt the JEB binary file. It may prompt the user and ask for the decryption password, which can be found within your software delivery note, such as update emails received from PNF Software. Enter the password to allow the startup script to finish the installation process. JEB will start and the software logo should pop up:

Registration¶

Upon first run of a JEB, or the controller part of floating build, the user is required to generate a license key:

• For JEB >= 2.2.10, the license key can be automatically generated by clicking on "Generate a Key".

• For JEB < 2.2.10, you have to manually generate the license key by visiting the mentioned URL and input the License data blob:

The possibility to generate a key is conditioned by the number of licenses attached to a given build. The key will be stored in the bin/jeb-client.cfg file, under the .LicenseKey key entry. A key is specific to the user-account and machine configuration on which JEB is running! Do not attempt to reuse a key on another system.

Note: If you need to deprecate an older key (eg, because of a machine replacement, user departure, or else), email support. We handle those queries as quickly as we can, generally within minutes of processing your email.

First use¶

Congratulation! JEB is now running.

Workspace¶

You should be greeted by an empty workspace, using the default 3-part layout:

• Project explorer on the left side
• Logger and Console at the bottom
• Empty area in the center

Starting an Analysis¶

Let's open our first file in JEB. Go ahead and download Raasta.apk, a sample (clean) Android application that will serve as our testing ground for the next couple of chapters.

Open it via the File menu. A new project will be created with a single artifact, Raasta.apk.

The application is processed by various Android analysis plugins:

• The APK plugin takes care of unbundling the app, decoding the manifest and resources
• The DEX plugin performs the analysis and disassembly of the DEX bytecode file (or files)
• The XML parser analyzes XML resources
• The Certificate plugin analyzes the certificate
• ... and so on.

Note: JEB performs recursive analysis on input artifacts and units, using the loaded parser plugins.

The project explorer tree should display a Bytecode node, representing the DEX unit (more on the concept of units later). The DEX views should be opened automatically by the RCP client, as they are detected as the principal views of an APK artifact.

Your workspace should look like:

The workspace can be customized by the user:

• Views can be dragged and dropped, resized, stacked and docked with other views
• Views can be maximized (by double-clicking on the view title bar), minimized, or even detached and placed in separate windows - something particularly particularly useful for multi-monitor setups.
• Users can also fork, customize, and save layouts, via the Window menu. It is particularly useful to create custom layouts when reverse-engineering with many views, such as during a debugging session.

Terminology¶

The Project Explorer contains three types of nodes:

• The top-most entity accessible within the RCP client is a project
  • Currently, the RCP client can only handle a single project per session
• A project contains various artifacts, which represent data to be analyzed
  • Artifacts are usually files read from the local file system
• The analysis of artifacts yield units and sub-units
  • Ex: Analyzing an Android DEX file artifact will yield at least one DEX unit representing the bytecode of that DEX file
• Users interact with units through views that contain fragments representing various aspects of a unit
  • Within the RCP client, fragments are visible as tabs at the bottom of a view
• Most units are interactive. Users can interact with them through a variety of ways, including via Actions, available in the similarly-named menu.
  • Example: an Android Bytecode file artifact (classes.dex), after analysis, will yield a DEX unit that represents the bytecode of that DEX file.

In the next section, we will show what actions can be performed to make the analysis of code interactive.