Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/rpcclient/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ dependencies = [
"tqdm",
"osstatus>=1.0.2",
"requests",
"protobuf",
"protobuf>=6.31.1",
"inquirer3",
"ipython-smart-await>=0.3.0",
"asgiwebdav>=2.0.1",
Expand Down
8 changes: 4 additions & 4 deletions src/rpcclient/rpcclient/clients/darwin/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@
from rpcclient.core.symbols_jar import LazySymbol
from rpcclient.exceptions import CfSerializationError, MissingLibraryError
from rpcclient.protocol.rpc_bridge import RpcBridge
from rpcclient.protos.rpc_api_pb2 import MsgId
from rpcclient.protos.rpc_api_pb2 import RequestGetClassList, RequestShowClass, RequestShowObject
from rpcclient.utils import cached_async_method


Expand Down Expand Up @@ -216,13 +216,13 @@ async def roots(self) -> list[str]:
return ["/", "/var/root"]

async def showobject(self, object_address: int) -> dict:
return json.loads((await self.rpc_call(MsgId.REQ_SHOW_OBJECT, address=object_address)).description)
return json.loads((await self.rpc_call(RequestShowObject(address=object_address))).description)

async def showclass(self, class_address: int) -> dict:
return json.loads((await self.rpc_call(MsgId.REQ_SHOW_CLASS, address=class_address)).description)
return json.loads((await self.rpc_call(RequestShowClass(address=class_address))).description)

async def get_class_list(self) -> dict[str, objective_c_class.Class]:
ret = await self.rpc_call(MsgId.REQ_GET_CLASS_LIST)
ret = await self.rpc_call(RequestGetClassList())
result = {}
for _class in ret.classes:
result[_class.name] = objective_c_class.Class(self, self.symbol(_class.address), lazy=True)
Expand Down
41 changes: 28 additions & 13 deletions src/rpcclient/rpcclient/core/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
from typing_extensions import Buffer, Self, assert_never

from construct import Container
from google.protobuf.message import Message

from rpcclient.clients.darwin.consts import BLOCK_IS_GLOBAL
from rpcclient.core.capture_fd import CaptureFD
Expand Down Expand Up @@ -73,9 +74,21 @@
RpcResourceTemporarilyUnavailableError,
ServerResponseError,
SpawnError,
UnexpectedReplyError,
)
from rpcclient.protocol.rpc_bridge import RpcBridge
from rpcclient.protos.rpc_api_pb2 import Argument, MsgId
from rpcclient.protos.rpc_api_pb2 import (
Argument,
RequestCall,
RequestCloseClient,
RequestDlclose,
RequestDlopen,
RequestDlsym,
RequestExec,
RequestListDir,
RequestPeek,
RequestPoke,
)
from rpcclient.protos.rpc_pb2 import ProtocolConstants


Expand Down Expand Up @@ -285,7 +298,8 @@ def sysname(self) -> str:
def arch(self) -> int:
return self._bridge.arch

async def rpc_call(self, msg_id: int, **kwargs: Any) -> Any:
async def rpc_call(self, request: Message) -> Any:
"""Send a request message (e.g. `RequestDlopen(filename=..., mode=...)`) and return the server's reply."""
# Pop all hooks here, to prevent hooks from running out of order due to recursion.
hooks, self.pre_rpc_call_hooks[:] = self.pre_rpc_call_hooks[::-1], []
try:
Expand All @@ -297,8 +311,9 @@ async def rpc_call(self, msg_id: int, **kwargs: Any) -> Any:
self.pre_rpc_call_hooks[:0] = hooks

try:
return await self._bridge.rpc_call(msg_id, **kwargs)
except ConnectionError:
return await self._bridge.rpc_call(request)
except (ConnectionError, UnexpectedReplyError):
# After an unexpected reply the stream is out of step with the server, so the connection is unusable too.
self.notifier.notify(ClientEvent.TERMINATED, self.id)
self._bridge.close()
raise
Expand All @@ -307,18 +322,18 @@ async def rpc_call(self, msg_id: int, **kwargs: Any) -> Any:

async def dlopen(self, filename: str, mode: int) -> SymbolT_co:
"""Load a shared library on the remote host and return its handle."""
return self.symbol((await self.rpc_call(MsgId.REQ_DLOPEN, filename=filename, mode=mode)).handle)
return self.symbol((await self.rpc_call(RequestDlopen(filename=filename, mode=mode))).handle)

async def dlclose(self, lib: int) -> int:
"""Close a previously opened remote library handle."""
return (await self.rpc_call(MsgId.REQ_DLCLOSE, handle=ctypes.c_uint64(lib).value)).res
return (await self.rpc_call(RequestDlclose(handle=ctypes.c_uint64(lib).value))).res

async def dlsym(self, lib: int, symbol_name: str) -> int:
"""Resolve a symbol name in a remote library handle and return its address.

Runs and pops any hooks in `self.pre_dlsym_hooks` first.
"""
return (await self.rpc_call(MsgId.REQ_DLSYM, handle=ctypes.c_uint64(lib).value, symbol_name=symbol_name)).ptr
return (await self.rpc_call(RequestDlsym(handle=ctypes.c_uint64(lib).value, symbol_name=symbol_name))).ptr

@null_pointer_guard
async def call(
Expand Down Expand Up @@ -355,7 +370,7 @@ async def call(
assert_never(arg)
raise ArgumentError(f"Can't serialize object of type {type(arg).__name__}")

ret = await self.rpc_call(MsgId.REQ_CALL, address=address, va_list_index=va_list_index, argv=args)
ret = await self.rpc_call(RequestCall(address=address, va_list_index=va_list_index, argv=args))
if ret.HasField("arm_registers"):
d0 = ret.arm_registers.d0
if return_float32:
Expand All @@ -371,15 +386,15 @@ async def call(
async def peek(self, address: int, size: int) -> bytes:
"""peek data at the given address"""
try:
return (await self.rpc_call(MsgId.REQ_PEEK, address=address, size=size)).data
return (await self.rpc_call(RequestPeek(address=address, size=size))).data
except ServerResponseError as e:
raise ArgumentError() from e

@null_pointer_guard
async def poke(self, address: int, data: bytes) -> Any:
"""poke data at a given address"""
try:
return await self.rpc_call(MsgId.REQ_POKE, address=address, data=data)
return await self.rpc_call(RequestPoke(address=address, data=data))
except ServerResponseError as e:
raise ArgumentError() from e

Expand Down Expand Up @@ -408,7 +423,7 @@ async def listdir(self, path: str | PurePath) -> list[ProtocolDirent]:
"""get an address for a stub block containing nothing"""
entries: list[ProtocolDirent] = []
try:
ret = await self.rpc_call(MsgId.REQ_LIST_DIR, path=str(path))
ret = await self.rpc_call(RequestListDir(path=str(path)))
except ServerResponseError:
await self.raise_errno_exception(f"failed to listdir: {path}")

Expand Down Expand Up @@ -573,14 +588,14 @@ async def freeing(self, symbol: SymbolT) -> AsyncGenerator[SymbolT]:

async def close(self) -> None:
try:
await self.rpc_call(MsgId.REQ_CLOSE_CLIENT)
await self.rpc_call(RequestCloseClient())
finally:
self.notifier.notify(ClientEvent.TERMINATED, self.id)
self._bridge.close()

async def _execute(self, argv: list[str], envp: list[str], background=False) -> int:
try:
return (await self.rpc_call(MsgId.REQ_EXEC, background=background, argv=argv, envp=envp)).pid
return (await self.rpc_call(RequestExec(background=background, argv=argv, envp=envp))).pid
except ServerResponseError as e:
raise SpawnError(f"failed to spawn: {argv}") from e

Expand Down
6 changes: 6 additions & 0 deletions src/rpcclient/rpcclient/exceptions.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,12 @@ class ServerResponseError(RpcClientException):
pass


class UnexpectedReplyError(RpcClientException):
"""Server replied with a message that doesn't answer the request"""

pass


class ServerDiedError(RpcClientException):
"""server became disconnected during an operation"""

Expand Down
118 changes: 34 additions & 84 deletions src/rpcclient/rpcclient/protocol/messages.py
Original file line number Diff line number Diff line change
@@ -1,93 +1,43 @@
import importlib
import logging
from typing import Any
import functools

from google.protobuf import message_factory
from google.protobuf.descriptor import Descriptor
from google.protobuf.message import Message

from rpcclient.protos.rpc_api_pb2 import ReplyError
from rpcclient.protos.rpc_pb2 import ProtocolConstants
from rpcclient.registry import Registry


logger = logging.getLogger(__name__)
def _to_camel(s: str) -> str:
# "DLSYM" -> "Dlsym", "DUMMY_BLOCK" -> "DummyBlock"
return "".join(p.capitalize() for p in s.lower().split("_"))


class RpcMessageRegistry:
@functools.cache
def resolve_request(request_class: type[Message]) -> tuple[int, type[Message]]:
"""
Handles the registration of RPC message mappings.

This class extends the Registry to manage mappings between unique integer
protocol message IDs and their corresponding request/response message
types. It provides utilities for dynamically loading these message
mappings from specified modules, ensuring a streamlined mechanism for
message resolution. The typical usage involves initializing the class,
potentially with module paths, where message definitions are declared.

Methods:
load_by_module: Dynamically loads message ID to class mappings from the provided module.
Get the msg_id and reply class of a request message type.

Both come from the request's own .proto file: `RequestX` is sent as `MsgId.REQ_X` and answered with `ReplyX`.
"""

def __init__(self, init_data: dict | None = None, modules: list[str] | None = None) -> None:
self._messages: Registry[int, type[Any]] = Registry()
self._messages.register(ProtocolConstants.REP_ERROR, ReplyError)
if init_data is None:
init_data = {}
if modules is None:
modules = []
self._messages.update(init_data)
for module in modules:
self.load_from_module(module)

def load_from_module(self, module_path: str) -> None:
mod = importlib.import_module(module_path)

# Use the module descriptor for robust access to enum values
enum_desc = mod.DESCRIPTOR.enum_types_by_name["MsgId"]

def _to_camel(s: str) -> str:
# "DLSYM" -> "Dlsym", "DUMMY_BLOCK" -> "DummyBlock"
return "".join(p.capitalize() for p in s.lower().split("_"))

pair_count = 0
for enum_value in enum_desc.values:
name = enum_value.name
value = enum_value.number
if not name.startswith("REQ_"):
continue
camel = _to_camel(name.split("_", 1)[1])
req_class = getattr(mod, f"Request{camel}", None)
rep_class = getattr(mod, f"Reply{camel}", None)
if req_class is None or rep_class is None:
logger.warning(f"Skipping {name}: missing Request{camel} or Reply{camel} in {module_path}")
continue
pair_count += 1
self.register_pair(value, req_class, rep_class)
logger.debug(f"Loaded {pair_count} bindings from {module_path}")

def register_pair(self, msg_id: int, req_class: type[Any], rep_class: type[Any]) -> None:
if msg_id > ProtocolConstants.RPC_MAX_REQ_MSG_ID:
raise ValueError(f"Invalid msg_id: {msg_id}")
self._messages.register(msg_id, req_class)
self._messages.register(msg_id + ProtocolConstants.RPC_MAX_REQ_MSG_ID, rep_class)

def unregister_pair(self, msg_id: int) -> None:
if msg_id > ProtocolConstants.RPC_MAX_REQ_MSG_ID:
raise ValueError(f"Invalid msg_id: {msg_id}")
self._messages.unregister(msg_id)
self._messages.unregister(msg_id + ProtocolConstants.RPC_MAX_REQ_MSG_ID)

def update(self, data: dict, overwrite: bool = False) -> None:
self._messages.update(data, overwrite)

def clone(self) -> "RpcMessageRegistry":
new_registry = RpcMessageRegistry()
new_registry.update(dict(self._messages.items()), overwrite=True)
return new_registry

def get(self, msg_id: int) -> type[Any]:
msg_class = self._messages.get(msg_id)
if msg_class is None:
raise ValueError(f"Unknown msg_id: {msg_id}")
return msg_class

def clear(self) -> None:
self._messages.clear()
descriptor = request_class.DESCRIPTOR
if not descriptor.name.startswith("Request"):
raise ValueError(f"Not a request message: {descriptor.full_name}")
camel = descriptor.name.removeprefix("Request")

file = descriptor.file
enum_desc = file.enum_types_by_name.get("MsgId")
msg_id = None
for value in enum_desc.values if enum_desc else ():
if value.name.startswith("REQ_") and _to_camel(value.name.removeprefix("REQ_")) == camel:
msg_id = value.number

reply_desc = file.message_types_by_name.get(f"Reply{camel}")
# Descriptor's isinstance() also accepts the upb implementation's descriptors
if msg_id is None or not isinstance(reply_desc, Descriptor):
raise ValueError(f"{descriptor.full_name}: {file.name} has no matching MsgId.REQ_* value or Reply{camel}")

# Same bounds as the server's routine_lookup() (rpcserver/routines.c)
if msg_id <= 0 or msg_id >= ProtocolConstants.RPC_MAX_REQ_MSG_ID:
raise ValueError(f"Invalid msg_id: {msg_id}")

return msg_id, message_factory.GetMessageClass(reply_desc)
44 changes: 23 additions & 21 deletions src/rpcclient/rpcclient/protocol/rpc_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,17 @@
from typing import Any, final
from typing_extensions import Self

from rpcclient.exceptions import InvalidServerVersionMagicError, ServerResponseError
from rpcclient.protocol.messages import RpcMessageRegistry
from google.protobuf.message import Message

from rpcclient.exceptions import InvalidServerVersionMagicError, ServerResponseError, UnexpectedReplyError
from rpcclient.protocol.messages import resolve_request
from rpcclient.protocol.rpc_socket import RpcSocket
from rpcclient.protos.rpc_api_pb2 import ReplyError
from rpcclient.protos.rpc_pb2 import ProtocolConstants, RpcMessage


logger = logging.getLogger(__name__)

BASIC_MESSAGES = RpcMessageRegistry(modules=["rpcclient.protos.rpc_api_pb2"])


def _has_process_exited(process: subprocess.Popen) -> bool:
return process.poll() is not None
Expand All @@ -28,11 +29,9 @@ def __init__(
platform_name: str,
arch: int,
sysname: str,
messages: RpcMessageRegistry | None = None,
owns_socket: bool = True,
local_process: subprocess.Popen | None = None,
) -> None:
self.messages: RpcMessageRegistry = messages or BASIC_MESSAGES.clone()
self.sock: RpcSocket = sock
self.client_id: int = client_id
self.platform: str = platform_name
Expand All @@ -42,33 +41,38 @@ def __init__(
self._local_process: subprocess.Popen | None = local_process

@classmethod
async def connect(cls, raw_sock: socket.socket, messages: RpcMessageRegistry | None = None) -> Self:
async def connect(cls, raw_sock: socket.socket) -> Self:
sock = RpcSocket(raw_sock)
handshake = await sock.rpc_handshake_recv()
if handshake.server_version != ProtocolConstants.SERVER_VERSION:
raise InvalidServerVersionMagicError(
f"got {handshake.magic:x} instead of {ProtocolConstants.SERVER_VERSION:x}"
)
return cls(
sock, handshake.client_id, handshake.platform.lower(), handshake.arch, handshake.sysname.lower(), messages
)
return cls(sock, handshake.client_id, handshake.platform.lower(), handshake.arch, handshake.sysname.lower())

async def rpc_call(self, msg_id: int, **kwargs) -> Any:
async def rpc_call(self, request: Message) -> Any:
"""
Resolve msg_id/reply class from request_msg's type, build RpcMessage, send and, parse reply.
Resolve msg_id/reply class from the request's type, build RpcMessage, send and, parse reply.
"""
req = self.messages.get(msg_id)(**kwargs)
msg_id, reply_class = resolve_request(type(request))
msg = RpcMessage(
client_id=self.client_id,
msg_id=msg_id,
payload=req.SerializeToString(),
payload=request.SerializeToString(),
)

rep_msg = await self.sock.rpc_msg_send_recv(msg)
rep = self.messages.get(rep_msg.msg_id)()
rep.ParseFromString(rep_msg.payload)
if rep_msg.msg_id == ProtocolConstants.REP_ERROR:
logger.error(f"Server error: {rep.message}")
raise ServerResponseError(rep.message)
error = ReplyError()
error.ParseFromString(rep_msg.payload)
logger.error(f"Server error: {error.message}")
raise ServerResponseError(error.message)

elif rep_msg.msg_id != msg_id + ProtocolConstants.RPC_MAX_REQ_MSG_ID:
raise UnexpectedReplyError(f"Unexpected reply msg_id {rep_msg.msg_id} to {request.DESCRIPTOR.full_name}")

rep = reply_class()
rep.ParseFromString(rep_msg.payload)
return rep

def close(self) -> None:
Expand All @@ -94,6 +98,4 @@ def _terminate_local_process(self) -> None:
process.kill()

def clone(self) -> Self:
return type(self)(
self.sock, self.client_id, self.platform, self.arch, self.sysname, self.messages.clone(), owns_socket=False
)
return type(self)(self.sock, self.client_id, self.platform, self.arch, self.sysname, owns_socket=False)
Loading
Loading