subprojects: Prepare for release

Expose Device.override_option() for overriding backend-specific
options on a device.

Overrides apply when establishing a host session. If one already
exists, changes take effect on the next connection.

examples/child_gating.py

@@ -42,18 +42,16 @@ class Application:
         print("✔ enable_child_gating()")
         session.enable_child_gating()
         print("✔ create_script()")
-        script = session.create_script(
-            """\
-Interceptor.attach(Module.getExportByName(null, 'open'), {
-  onEnter: function (args) {
+        script = session.create_script("""\
+Interceptor.attach(Module.getGlobalExportByName('open'), {
+  onEnter(args) {
     send({
       type: 'open',
-      path: Memory.readUtf8String(args[0])
+      path: args[0].readUtf8String()
     });
   }
 });
-"""
-        )
+""")
         script.on("message", lambda message, data: self._reactor.schedule(lambda: self._on_message(pid, message)))
         print("✔ load()")
         script.load()

examples/inject_library/inject_blob.py

@@ -15,7 +15,7 @@ def on_uninjected(id):
     print("on_uninjected id=%u" % id)
 
 
-(target, library_path) = sys.argv[1:]
+target, library_path = sys.argv[1:]
 
 device = frida.get_local_device()
 device.on("uninjected", on_uninjected)

examples/inject_library/inject_file.py

@@ -15,7 +15,7 @@ def on_uninjected(id):
     print("on_uninjected id=%u" % id)
 
 
-(target, library_path) = sys.argv[1:]
+target, library_path = sys.argv[1:]
 
 device = frida.get_local_device()
 device.on("uninjected", on_uninjected)

examples/rpc.py

@@ -1,8 +1,7 @@
 import frida
 
 session = frida.attach("Twitter")
-script = session.create_script(
-    """\
+script = session.create_script("""\
 rpc.exports = {
   hello: function () {
     return 'Hello';
@@ -11,8 +10,7 @@ rpc.exports = {
     oops;
   }
 };
-"""
-)
+""")
 script.load()
 api = script.exports_sync
 print("api.hello() =>", api.hello())

examples/session_persist_timeout.py

@@ -22,8 +22,7 @@ class Application:
         self._session = session
         session.on("detached", lambda *args: self._reactor.schedule(lambda: self._on_detached(*args)))
 
-        script = session.create_script(
-            """
+        script = session.create_script("""
 let _puts = null;
 
 Interceptor.attach(DebugSymbol.getFunctionByName('f'), {
@@ -48,8 +47,7 @@ function puts(s) {
   }
   _puts(Memory.allocUtf8String(s));
 }
-"""
-        )
+""")
         self._script = script
         script.on("message", lambda *args: self._reactor.schedule(lambda: self._on_message(*args)))
         script.load()

examples/spawn_gating.py

@@ -0,0 +1,78 @@
+import threading
+
+from frida_tools.application import Reactor
+
+import frida
+
+
+class Application:
+    def __init__(self):
+        self._stop_requested = threading.Event()
+        self._reactor = Reactor(run_until_return=lambda reactor: self._stop_requested.wait())
+
+        self._device = frida.get_usb_device()
+        self._sessions = set()
+        self._sessions_lock = threading.Lock()
+
+        self._device.on("spawn-added", lambda spawn: self._reactor.schedule(lambda: self._on_spawn_added(spawn)))
+        self._device.on("spawn-removed", lambda spawn: self._reactor.schedule(lambda: self._on_spawn_removed(spawn)))
+
+    def run(self):
+        self._reactor.schedule(lambda: self._start())
+        self._reactor.run()
+
+    def _start(self):
+        self._device.enable_spawn_gating()
+
+    def _instrument(self, pid):
+        print(f"✔ attach(pid={pid})")
+        session = self._device.attach(pid)
+        session.on("detached", lambda reason: self._reactor.schedule(lambda: self._on_detached(pid, session, reason)))
+        print("✔ create_script()")
+        script = session.create_script("""\
+const puts = new NativeFunction(Module.getGlobalExportByName('puts'), 'int', ['pointer']);
+puts(Memory.allocUtf8String('Hello from Frida agent'));
+Interceptor.attach(Module.getGlobalExportByName('open'), {
+  onEnter(args) {
+    send({
+      type: 'open',
+      path: args[0].readUtf8String()
+    });
+  }
+});
+""")
+        script.on("message", lambda message, data: self._reactor.schedule(lambda: self._on_message(pid, message)))
+        print("✔ load()")
+        script.load()
+        print(f"✔ resume(pid={pid})")
+        self._device.resume(pid)
+        with self._sessions_lock:
+            self._sessions.add(session)
+
+    def _on_spawn_added(self, spawn):
+        print(f"⚡ spawn_added: {spawn}")
+        t = threading.Thread(target=self._handle_spawn, args=(spawn,))
+        t.start()
+
+    def _handle_spawn(self, spawn):
+        if "/bin/ls" in spawn.identifier:
+            self._instrument(spawn.pid)
+        else:
+            pid = spawn.pid
+            print(f"✔ resume(pid={pid})")
+            self._device.resume(pid)
+
+    def _on_spawn_removed(self, spawn):
+        print(f"⚡ spawn_removed: {spawn}")
+
+    def _on_detached(self, pid, session, reason):
+        print(f"⚡ detached: pid={pid}, reason='{reason}'")
+        with self._sessions_lock:
+            self._sessions.remove(session)
+
+    def _on_message(self, pid, message):
+        print(f"⚡ message: pid={pid}, payload={message['payload']}")
+
+
+app = Application()
+app.run()

frida/__init__.py

@@ -23,6 +23,7 @@ Relay = _frida.Relay
 PortalService = core.PortalService
 EndpointParameters = core.EndpointParameters
 Compiler = core.Compiler
+PackageManager = core.PackageManager
 FileMonitor = _frida.FileMonitor
 Cancellable = core.Cancellable
 

frida/_frida/__init__.pyi

@@ -754,8 +754,13 @@ class Compiler(Object):
         self,
         entrypoint: str,
         project_root: Optional[str] = None,
+        output_format: Optional[str] = None,
+        bundle_format: Optional[str] = None,
+        type_check: Optional[str] = None,
         source_maps: Optional[str] = None,
         compression: Optional[str] = None,
+        platform: Optional[str] = None,
+        externals: Optional[Sequence[str]] = None,
     ) -> str:
         """
         Build an agent.
@@ -766,12 +771,107 @@ class Compiler(Object):
         self,
         entrypoint: str,
         project_root: Optional[str] = None,
+        output_format: Optional[str] = None,
+        bundle_format: Optional[str] = None,
+        type_check: Optional[str] = None,
         source_maps: Optional[str] = None,
         compression: Optional[str] = None,
+        platform: Optional[str] = None,
+        externals: Optional[Sequence[str]] = None,
     ) -> None:
         """
         Continuously build an agent.
         """
         ...
 
+class PackageManager(Object):
+    @property
+    def registry(self) -> str:
+        """
+        The registry being used.
+        """
+        ...
+
+    @registry.setter
+    def registry(self, value: str) -> None:
+        """
+        Change the registry to use.
+        """
+        ...
+
+    def search(
+        self,
+        query: str,
+        offset: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> PackageSearchResult:
+        """
+        Search for packages to install.
+        """
+        ...
+
+    def install(
+        self,
+        project_root: Optional[str] = None,
+        role: Optional[str] = None,
+        specs: Optional[Sequence[str]] = None,
+        omits: Optional[Sequence[str]] = None,
+    ) -> PackageInstallResult:
+        """
+        Install one or more packages.
+        """
+        ...
+
+class Package(Object):
+    @property
+    def name(self) -> str:
+        """
+        Package name.
+        """
+        ...
+
+    @property
+    def version(self) -> str:
+        """
+        Package version.
+        """
+        ...
+
+    @property
+    def description(self) -> Optional[str]:
+        """
+        Package description.
+        """
+        ...
+
+    @property
+    def url(self) -> Optional[str]:
+        """
+        Package URL.
+        """
+        ...
+
+class PackageSearchResult(Object):
+    @property
+    def packages(self) -> List[Package]:
+        """
+        Batch of matching packages.
+        """
+        ...
+
+    @property
+    def total(self) -> int:
+        """
+        Total matching packages.
+        """
+        ...
+
+class PackageInstallResult(Object):
+    @property
+    def packages(self) -> List[Package]:
+        """
+        The toplevel packages that are installed.
+        """
+        ...
+
 __version__: str

frida/core.py

@@ -33,10 +33,15 @@ if sys.version_info >= (3, 8):
 else:
     from typing_extensions import Literal, TypedDict
 
-if sys.version_info >= (3, 11):
-    from typing import NotRequired
+if sys.version_info >= (3, 10):
+    from typing import ParamSpec
 else:
-    from typing_extensions import NotRequired
+    from typing_extensions import ParamSpec
+
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, cast
+else:
+    from typing_extensions import NotRequired, cast
 
 from . import _frida
 
@@ -72,15 +77,18 @@ def _filter_missing_kwargs(d: MutableMapping[Any, Any]) -> None:
             d.pop(key)
 
 
-R = TypeVar("R")
+P = ParamSpec("P")
+R = TypeVar("R", covariant=True)
 
 
-def cancellable(f: Callable[..., R]) -> Callable[..., R]:
+def cancellable(f: Callable[P, R]) -> Callable[P, R]:
+    # currently there is no way to type properly the extended callable with optional cancellable parameter
+    # ref: https://github.com/python/typing/discussions/1905#discussioncomment-11696995
     @functools.wraps(f)
-    def wrapper(*args: Any, **kwargs: Any) -> R:
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
         cancellable = kwargs.pop("cancellable", None)
         if cancellable is not None:
-            with cancellable:
+            with cast(Cancellable, cancellable):
                 return f(*args, **kwargs)
 
         return f(*args, **kwargs)
@@ -351,9 +359,6 @@ class Script:
     @overload
     def on(self, signal: Literal["message"], callback: ScriptMessageCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Add a signal handler
@@ -370,9 +375,6 @@ class Script:
     @overload
     def off(self, signal: Literal["message"], callback: ScriptMessageCallback) -> None: ...
 
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def off(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Remove a signal handler
@@ -693,34 +695,22 @@ class Session:
         _filter_missing_kwargs(kwargs)
         return PortalMembership(self._impl.join_portal(address, **kwargs))
 
-    @overload
     def on(
         self,
         signal: Literal["detached"],
         callback: SessionDetachedCallback,
-    ) -> None: ...
-
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
-    def on(self, signal: str, callback: Callable[..., Any]) -> None:
+    ) -> None:
         """
         Add a signal handler
         """
 
         self._impl.on(signal, callback)
 
-    @overload
     def off(
         self,
         signal: Literal["detached"],
         callback: SessionDetachedCallback,
-    ) -> None: ...
-
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
-    def off(self, signal: str, callback: Callable[..., Any]) -> None:
+    ) -> None:
         """
         Remove a signal handler
         """
@@ -763,9 +753,6 @@ class Bus:
     @overload
     def on(self, signal: Literal["message"], callback: BusMessageCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Add a signal handler
@@ -782,9 +769,6 @@ class Bus:
     @overload
     def off(self, signal: Literal["message"], callback: BusMessageCallback) -> None: ...
 
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def off(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Remove a signal handler
@@ -842,9 +826,6 @@ class Service:
     @overload
     def on(self, signal: Literal["message"], callback: ServiceMessageCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Add a signal handler
@@ -858,9 +839,6 @@ class Service:
     @overload
     def off(self, signal: Literal["message"], callback: ServiceMessageCallback) -> None: ...
 
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def off(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Remove a signal handler
@@ -905,6 +883,14 @@ class Device:
 
         return self._impl.is_lost()
 
+    @cancellable
+    def override_option(self, name: str, value: Any) -> None:
+        """
+        Override a backend-specific option
+        """
+
+        self._impl.override_option(name, value)
+
     @cancellable
     def query_system_parameters(self) -> Dict[str, Any]:
         """
@@ -1144,9 +1130,6 @@ class Device:
     @overload
     def on(self, signal: Literal["lost"], callback: DeviceLostCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Add a signal handler
@@ -1178,9 +1161,6 @@ class Device:
     @overload
     def off(self, signal: Literal["lost"], callback: DeviceLostCallback) -> None: ...
 
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def off(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Remove a signal handler
@@ -1298,9 +1278,6 @@ class DeviceManager:
     @overload
     def on(self, signal: Literal["changed"], callback: DeviceManagerChangedCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Add a signal handler
@@ -1317,9 +1294,6 @@ class DeviceManager:
     @overload
     def off(self, signal: Literal["changed"], callback: DeviceManagerChangedCallback) -> None: ...
 
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def off(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Remove a signal handler
@@ -1344,7 +1318,7 @@ class EndpointParameters:
         _filter_missing_kwargs(kwargs)
 
         if authentication is not None:
-            (auth_scheme, auth_data) = authentication
+            auth_scheme, auth_data = authentication
             if auth_scheme == "token":
                 kwargs["auth_token"] = auth_data
             elif auth_scheme == "callback":
@@ -1490,9 +1464,6 @@ class PortalService:
     @overload
     def on(self, signal: Literal["message"], callback: PortalServiceMessageCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Add a signal handler
@@ -1554,10 +1525,17 @@ CompilerFinishedCallback = Callable[[], None]
 CompilerOutputCallback = Callable[[str], None]
 CompilerDiagnosticsCallback = Callable[[List[CompilerDiagnostic]], None]
 
+CompilerOutputFormat = Literal["unescaped", "hex-bytes", "c-string"]
+CompilerBundleFormat = Literal["esm", "iife"]
+CompilerTypeCheck = Literal["full", "none"]
+CompilerSourceMaps = Literal["included", "omitted"]
+CompilerCompression = Literal["none", "terser"]
+CompilerPlatform = Literal["neutral", "gum", "browser"]
+
 
 class Compiler:
     def __init__(self) -> None:
-        self._impl = _frida.Compiler(get_device_manager()._impl)
+        self._impl = _frida.Compiler()
 
     def __repr__(self) -> str:
         return repr(self._impl)
@@ -1567,10 +1545,24 @@ class Compiler:
         self,
         entrypoint: str,
         project_root: Optional[str] = None,
-        source_maps: Optional[str] = None,
-        compression: Optional[str] = None,
+        output_format: Optional[CompilerOutputFormat] = None,
+        bundle_format: Optional[CompilerBundleFormat] = None,
+        type_check: Optional[CompilerTypeCheck] = None,
+        source_maps: Optional[CompilerSourceMaps] = None,
+        compression: Optional[CompilerCompression] = None,
+        platform: Optional[CompilerPlatform] = None,
+        externals: Optional[Sequence[str]] = None,
     ) -> str:
-        kwargs = {"project_root": project_root, "source_maps": source_maps, "compression": compression}
+        kwargs: dict[str, Any] = {
+            "project_root": project_root,
+            "output_format": output_format,
+            "bundle_format": bundle_format,
+            "type_check": type_check,
+            "source_maps": source_maps,
+            "compression": compression,
+            "platform": platform,
+            "externals": externals,
+        }
         _filter_missing_kwargs(kwargs)
         return self._impl.build(entrypoint, **kwargs)
 
@@ -1579,10 +1571,24 @@ class Compiler:
         self,
         entrypoint: str,
         project_root: Optional[str] = None,
-        source_maps: Optional[str] = None,
-        compression: Optional[str] = None,
+        output_format: Optional[CompilerOutputFormat] = None,
+        bundle_format: Optional[CompilerBundleFormat] = None,
+        type_check: Optional[CompilerTypeCheck] = None,
+        source_maps: Optional[CompilerSourceMaps] = None,
+        compression: Optional[CompilerCompression] = None,
+        platform: Optional[CompilerPlatform] = None,
+        externals: Optional[Sequence[str]] = None,
     ) -> None:
-        kwargs = {"project_root": project_root, "source_maps": source_maps, "compression": compression}
+        kwargs: dict[str, Any] = {
+            "project_root": project_root,
+            "output_format": output_format,
+            "bundle_format": bundle_format,
+            "type_check": type_check,
+            "source_maps": source_maps,
+            "compression": compression,
+            "platform": platform,
+            "externals": externals,
+        }
         _filter_missing_kwargs(kwargs)
         return self._impl.watch(entrypoint, **kwargs)
 
@@ -1598,10 +1604,11 @@ class Compiler:
     @overload
     def on(self, signal: Literal["diagnostics"], callback: CompilerDiagnosticsCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
+        """
+        Add a signal handler
+        """
+
         self._impl.on(signal, callback)
 
     @overload
@@ -1616,10 +1623,86 @@ class Compiler:
     @overload
     def off(self, signal: Literal["diagnostics"], callback: CompilerDiagnosticsCallback) -> None: ...
 
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def off(self, signal: str, callback: Callable[..., Any]) -> None:
+        """
+        Remove a signal handler
+        """
+
+        self._impl.off(signal, callback)
+
+
+PackageManagerInstallProgressCallback = Callable[
+    [
+        Literal[
+            "initializing",
+            "preparing-dependencies",
+            "resolving-package",
+            "fetching-resource",
+            "package-already-installed",
+            "downloading-package",
+            "package-installed",
+            "resolving-and-installing-all",
+            "complete",
+        ],
+        float,
+        Optional[str],
+    ],
+    None,
+]
+
+PackageRole = Literal["runtime", "development", "optional", "peer"]
+
+
+class PackageManager:
+    def __init__(self) -> None:
+        self._impl = _frida.PackageManager()
+
+    def __repr__(self) -> str:
+        return repr(self._impl)
+
+    @property
+    def registry(self):
+        return self._impl.registry
+
+    @registry.setter
+    def registry(self, value):
+        self._impl.registry = value
+
+    @cancellable
+    def search(
+        self,
+        query: str,
+        offset: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> _frida.PackageSearchResult:
+        kwargs = {
+            "offset": offset,
+            "limit": limit,
+        }
+        _filter_missing_kwargs(kwargs)
+        return self._impl.search(query, **kwargs)
+
+    @cancellable
+    def install(
+        self,
+        project_root: Optional[str] = None,
+        role: Optional[PackageRole] = None,
+        specs: Optional[Sequence[str]] = None,
+        omits: Optional[Sequence[PackageRole]] = None,
+    ) -> _frida.PackageInstallResult:
+        kwargs: Dict[str, Any] = {
+            "project_root": project_root,
+            "role": role,
+            "specs": specs,
+            "omits": omits,
+        }
+        _filter_missing_kwargs(kwargs)
+        return self._impl.install(**kwargs)
+
+    def on(self, signal: Literal["install-progress"], callback: PackageManagerInstallProgressCallback) -> None:
+        self._impl.on(signal, callback)
+
+    def off(self, signal: Literal["install-progress"], callback: PackageManagerInstallProgressCallback) -> None:
         self._impl.off(signal, callback)
 
 

subprojects/frida-core.wrap

@@ -1,6 +1,6 @@
 [wrap-git]
 url = https://github.com/frida/frida-core.git
-revision = 16.7.8
+revision = 17.9.11
 depth = 1
 
 [provide]