Hacking

Digging Deeper into Objection

So you want to dig a little deeper into the project and its source code. Maybe to test out some changes, or better yet, for a pull request! This article aims to give you an overview on the project structure. This article provides a detailed overview of the project’s structure and serves as a starting point for developers who want to better understand how everything fits together.

A Bird's Eye View

At its core, objection relies heavily on Frida to handle much of the heavy lifting. Together with purpose-built hooks and a Python-powered REPL (Read-Eval-Print Loop), objection orchestrates these components to provide a powerful yet simple interface for dynamic mobile instrumentation.

The command flow works as follows: when a user enters a command in the objection REPL, the Python runtime processes the command, identifies whether arguments are required, and determines the appropriate method to invoke. If needed, the appropriate method communicates with the Frida RPC mechanism to interact with the dynamically injected agent code.

The injection and execution pipeline ensures that commands entered in the explore REPL translate into Frida hooks and instrumentation in the target mobile application.

Project Structure

Here's a breakdown of key areas of the codebase and their roles in the project:

External Libraries

objection makes use of several important external libraries:

• Click is used for command-line argument parsing.
• python-prompt-toolkit powers the REPL, enabling dynamic and interactive command input.
• The agent is written in TypeScript and compiled to JavaScript for runtime execution within Frida.

Code Locations

The objection project is split into multiple self-contained components, each fulfilling specific responsibilities:

Python

• Commands: Python methods that correspond to commands are located in objection/commands.
• REPL and CLI Interface: Classes and methods responsible for the command-line interface and REPL behavior reside in objection/console.
• Agent Communication: Python utilities responsible for communicating with the remote Frida agent live in objection/utils/agent.py.

Frida Agent

• Agent Code: The core Frida hooks and runtime code exist in the objection/agent directory. These are written in TypeScript and compiled into the final JavaScript code, which is loaded into the target application at runtime.
• RPC Definition: The main RPC entry points used by the Frida agent are defined in agent/src/rpc and exposed via the Frida rpc.exports declaration in agent/src/index.ts.

Additional Notes

• The compiled agent JavaScript code is injected into the target application upon the REPL’s initialization, allowing dynamic runtime commands to interface with the Frida runtime seamlessly.

REPL (Read-Evaluate-Print Loop) Command Flow

The objection REPL forms the heart of the user interface, processing commands in real-time and orchestrating interactions with Frida. Here’s how it operates:

1. Command Handling: When a user enters a command in the objection explore REPL, the run_command() method handles the input. This method leverages prompt_toolkit to process and split the input string into commands and arguments.

2. Command Resolution: The REPL uses the _find_command_exec_method() helper to locate the appropriate Python method to invoke for the given command. Any additional tokens from the user input are forwarded as arguments to the Python function.

3. Command Repository: Commands are registered in a repository located in the COMMANDS variable of repository.py. Each command’s exec key specifies the corresponding Python method to call.

4. Agent Communication: If the command involves interacting with the Frida agent, communication occurs through the utilities defined in agent.py. The agent is dynamically injected into the target application via the attach() method. Frida’s RPC mechanism handles calls to and from the agent.

5. Frida RPC: Within the Frida agent, entry points for RPC communication are located in the agent's rpc directory. The main rpc.exports in the agent script exposes these entry points to Python via Frida’s runtime. Note that the exports are defined in CamelCase (ts), while they are invoked using snake_case (python) - e.g. memoryListExports is called using api.memory_list_exports.

Getting Started as a Developer

If you're looking to contribute to the objection project:

• Start by setting up a development environment.
• Use the -d flag for additional debug info and --debugger to enable the chrome debugger and also use the v8 JS engine which provides more verbose stack traces.