JEB offers a [rich API](https://www.pnfsoftware.com/jeb/apidoc) that can be used to develop: - **Scripts**: - Python scripts can be used to automate simple tasks - When run within the GUI client, scripts can interact with GUI elements - **Plugins** (aka *back-end extensions*): - ***Processor plugins*** such as disassemblers, file parsers, etc. - ***Engines plugins*** such as second-pass code analyzers, working on results produced by other plugins, or helpers - ***Decompiler plugins*** such as IR optimizer plugins for *dexdec* or *gendec* - Other plugin types include code analysis extensions (to customize native code analysis), contributions (for information overlays), interpreter (command-line processors), etc. - **Front-end clients**, such as: - The official *GUI client* - Headless clients for automation pipelines # Capabilities Only professional licenses offer full API access. However, all licenses allow script and plugin execution from within the GUI client: Licenses Type | GUI client | Other Clients (e.g. command-line) --------------|----------------------|----------------------------------- **Non-Pro** | UI scripts | no **Pro** | UI scripts + plugins | scripts + plugins # High-level Architecture Grasping the high-level concepts of how pieces fit together within JEB will make you a more efficient extensions developer. At the highest-level, JEB is separated into back-end and front-end components: - The back-end components are responsible for processing input artifacts. They provide an execution environment for native and third-party plugins, including processor plugins, such as file parsers. - The front-end components are responsible for processing input commands and rendering back-end results. A variety of front-ends may be created using the API exposed by the back-end. !!! note All JEB distributions ship with the GUI client, which runs on all major desktop operating systems (Windows, Linux, macOS, on AMD64 or ARM64 architectures). The diagram below shows the relationship between back-end and front-end components: [![High-level architecture diagram](img/d86ecb8e-small.png)](img/d86ecb8e.png) Users may develop third-party plugins and instruct the back-end to load them. This enables power users to craft input processors that cater to their specific needs (e.g., a disassembler for an exotic or virtual CPU). You may verify your plugins dev capabilities by starting JEB with the `-c --license` command line flag. # Application Programming Interfaces Clients and extensions (plugins, scripts) use the JEB API. The API reference documentation is [available online](https://www.pnfsoftware.com/jeb/apidoc) as well as offline, within your JEB software package (file `doc/apidoc.zip`). [![](img/jeb-portal-apidoc.png)](https://www.pnfsoftware.com/jeb/apidoc) # Scripts vs Plugins - **Scripts**... - Implement `IScript` - Are called by users to achieve small tasks - Example: modify some code, navigate somewhere, display some info, etc. - Must be written in Python (they are run in a Jython VM) - Ideal for rapid development and prototyping - Are executed by JEB on-demand - In the GUI client, can be executed via the *File* menu - **Plugins**... - Implement a specialized sub-type of `IPlugin` - Can perform a variety of tasks, from input processing, disassembling, decompiling, adding functionality to other plugins, event-triggered actions, etc. - May be compiled as jar; some plugin types may be written as scripts (Java or Python) # Interactive Interpreter In the GUI, JEB API may be accessed directly through an interpreter available in the `Terminal` fragment: [![Terminal with the JEB interpreter](img/b1d24079-small.png)](img/b1d24079.png) The Python interpreter has a global variable named `jeb` referencing the current IClientContext. Example: ``` > help help : help about the master interpreter list : display a list of available console ports use : set the active console associated with this display; -1 for master exit : exit the current interpreter and return to the master interpreter > list 1 interpreter available (0) py: Python Interpreter (built on Jython 2.7) > use py * JEB Python interpreter (EXPERIMENTAL) - uses Jython 2.7 * The current client context (type: com.pnfsoftware.jeb.client.api.IClientContext) is located in the `jeb` global variable * The following folder was auto-added to sys.path: C:\Users\nicol\jeb2\jeb3-rcpclient\scripts * Refer to the API doc (Help menu) and sample scripts and plugins to get started py> jeb.getSoftwareVersion() 5.19.0.202410222128 py> prj = jeb.getMainProject() py> dex = prj.findUnit(IDexUnit) py> print dex Unit:name={af559961_classes4.dex},type={dex} py> print dex.getMethods() [Method:#0,name=,address=Landroid/animation/AnimatorListenerAdapter;->()V, ...] ``` # Executing Scripts While the interpreter is ideal for quick one-offs and experimentation, if a task is to be repeated and potentially shared with other people, you will want to write a full Python script. All versions of JEB can execute *client scripts* within the GUI client. Scripts should be dropped in your `scripts/` directory (or any other directory specified in your `.ScriptsFolder` [client option](client-configuration.md)). Use the *File, Scripts, Script Selector...* menu command to execute, edit, or create a script. You may choose to use the built-in editor, available in the GUI via *File, Script Selector...*, "Edit" or "New". [![Script select dialog](img/afdd7468-small.png)](img/afdd7468.png) [![JEB Python script editor](img/7e736882-small.png)](img/7e736882.png) - Client scripts are written in Python, and are executed within a 2.7 [Jython VM](https://www.jython.org/download) (a Java implementation of the Python VM) - Scripts, like any extension, use the JEB API. - Client scripts executed inside the GUI client also have access to the **UI-API**, located in the package `com.pnfsoftware.jeb.client.ui`. Classes of the UI-API allow graphical manipulation of views, fragments, items, etc. (This API is optionally implemented by clients.) You will find a large collection of sample scripts on our [public GitHub repository](https://github.com/pnfsoftware/jeb-samplecode/tree/master/scripts). # Executing Engines Plugins Engines plugins live within the engines context of the JEB back-end. They may execute code continuously, be event-driven, or even be explicitly called by the user. All third-party plugins must be dropped in your `coreplugins/` directory (or any other directory specified in your `.PluginsFolder` [back-end option](engines-configuration.md)). Use the *File, Engines, Execute, ...* menu command to execute an engines plugin. !!! note "API" *Engines plugins* are JEB plugins that implement the [IEnginesPlugin](https://www.pnfsoftware.com/jeb/apidoc/com/pnfsoftware/jeb/core/IEnginesPlugin.html) interface. The full list of *engines plugins* loaded within your JEB instance context can be seen by running the *File, Engines, Plugins* command. You may double-click a plugin to execute it. [![](img/jeb-list-plugins.png)](img/jeb-list-plugins.png) # Other Plugins A collection of open-source plugins can be found on our [public GitHub repository](https://github.com/pnfsoftware/). # Additional Resources Technical drafts for developers: (available on Google Drive) - [Parser Delegation](https://docs.google.com/document/d/1f9-gXVNhRixKUr02YzB4dttVJIqZefsms-EOVmazLjU/pub) - [MVC and Unit Documents](https://docs.google.com/document/d/1PFCD1GgFrRgs-XqCGUyLcrGVenCPq8Ab7DPBaJodXeM/pub) - [Positioning within Units](https://docs.google.com/document/d/19WDsGf2NbJmKLYC6iE7MT5P9nUJvAOLdGhPsuMeM104/pub) - [Units Hierarchy](https://docs.google.com/document/d/1mk8QQUikpxS3HM2vrOOHCjCQodnis9otJ5XGgJqYVLA/pub) [Join us on Slack](httpd://www.pnfsoftware.com/chat) for interactive discussions if you have questions about the API.