Getting Started¶
This document is a usage manual for JEB3.
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.
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 "UI client". This manual focuses mostly on using JEB through the UI client.
The UI client client runs on Windows 64-bit, Linux/GTK 64-bit, and macOS 64-bit.
Requirements¶
Java¶
JEB requires a Java Runtime Environment (JRE) or Java Development Kit (JDK) version 8 or above (8.191+).
Setup¶
Make sure you have a JRE or JDK installed.
- The
java
binary must be accessible from thePATH
environment variable. - Optionally, you may also want to set a
JAVA_HOME
environment variable pointing to your Java installation folder.
64-bit OS with 32-bit JRE: 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 your PATH or JAVA_HOME refers to one that matches your system specifications.
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
The startup script will 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 email received from PNF Software. Enter the password to allow the startup script to finish the installation process.
JEB will start.
Registration¶
If it is the first time you are running a non-floating JEB client, you will be asked accept the end-user license agreement, and generate a license key:
If your machine is connected to the Internet, the license key can be automatically generated by clicking "Generate a Key". If need be, you may also configure your Proxy settings.
If your machine is not connected to the Internet, you will need to generate a manual key. Click "Manual Key Generation" and follow the instruction. You will be asked to visit the key generation portal on a separate machine (connected to the Internet), and provide your license data.
The license 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 Licensing.
First use¶
Congratulation! JEB is now running.
Workspace¶
You should be greeted by an empty workspace, using a default three-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 UI 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 detached and placed in separate windows - something particularly useful for multi-monitor setups.
Terminology¶
The Project Explorer contains three types of nodes:
- The top-most entity accessible within the UI client is a project
- Currently, the UI 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 UI 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.