frida-server 1.0.0__py3-none-any.whl

frida_server/__init__.py

@@ -0,0 +1,73 @@
+"""frida-server — zero-config Frida server deployment for Android.
+
+Detects a connected Android device, matches the ``frida-server`` binary to the
+Frida version installed on your PC, downloads it, pushes it, and launches it —
+all in one command.
+
+Typical use is via the ``frida-server`` command-line tool. The object model can
+also be driven programmatically::
+
+    from frida_server import Deployer
+
+    Deployer().run()          # interactive: pick a device and deploy
+
+or, for the common case, the module-level convenience wrapper::
+
+    from frida_server import setup
+
+    setup(serial="emulator-5554", update=False)
+
+See :class:`frida_server.deployer.Deployer` for the orchestration entry point.
+"""
+
+from __future__ import annotations
+
+from .exceptions import (
+    AdbError,
+    DeviceError,
+    DownloadError,
+    FridaServerError,
+    RootAccessError,
+)
+
+__all__ = [
+    "__version__",
+    "setup",
+    "Deployer",
+    "FridaServerError",
+    "AdbError",
+    "DeviceError",
+    "DownloadError",
+    "RootAccessError",
+]
+
+__version__ = "1.0.0"
+__author__ = "S. SHAJON"
+__license__ = "GPL-3.0-or-later"
+
+
+def setup(
+    *,
+    serial: str | None = None,
+    update: bool = True,
+    port: int = 27042,
+    force: bool = False,
+) -> bool:
+    """Convenience wrapper around :meth:`frida_server.deployer.Deployer.run`.
+
+    Deploys and starts ``frida-server`` on a connected Android device, returning
+    ``True`` if the server ends up running. See :meth:`Deployer.run` for the
+    full argument reference.
+    """
+    from .deployer import Deployer
+
+    return Deployer().run(serial=serial, update=update, port=port, force=force)
+
+
+def __getattr__(name: str):
+    # Lazily expose Deployer so ``import frida_server`` stays cheap.
+    if name == "Deployer":
+        from .deployer import Deployer
+
+        return Deployer
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

frida_server/__main__.py

@@ -0,0 +1,10 @@
+"""Enable ``python -m frida_server``."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

frida_server/checksums.py

@@ -0,0 +1,71 @@
+"""Local cache of known-good ``frida-server`` SHA-256 digests.
+
+Because several devices of different architectures may be used from the same
+machine, the cache is **grouped by architecture** — each arch keeps its own map
+of Frida version → digest::
+
+    {
+      "android-arm64":  { "17.17.0": "55ef78c3…" },
+      "android-x86_64": { "17.17.0": "b34a33bd…" }
+    }
+
+When a binary is downloaded and pushed, its SHA-256 is recorded under that
+device's arch. On later runs the on-device binary's digest is compared against
+the entry for its arch to detect a corrupt, tampered, or foreign server and
+trigger a re-deploy — going beyond a plain version-string check.
+
+The store lives at ``~/.frida-server/checksums.json`` and degrades gracefully:
+a missing, corrupt, or legacy-format file is treated as empty.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+
+class ChecksumStore:
+    """A JSON-backed map of ``arch`` → (``version`` → SHA-256 hex digest)."""
+
+    _PATH = Path.home() / ".frida-server" / "checksums.json"
+
+    def __init__(self, path: Path | None = None) -> None:
+        self._path = path or self._PATH
+
+    @staticmethod
+    def file_sha256(path: str | Path) -> str:
+        """Return the SHA-256 hex digest of a local file."""
+        digest = hashlib.sha256()
+        with open(path, "rb") as fh:
+            for block in iter(lambda: fh.read(1 << 20), b""):
+                digest.update(block)
+        return digest.hexdigest()
+
+    def _load(self) -> dict[str, dict[str, str]]:
+        try:
+            with open(self._path, encoding="utf-8") as fh:
+                data = json.load(fh)
+        except (FileNotFoundError, json.JSONDecodeError, OSError):
+            return {}
+        # Keep only well-formed ``arch -> {version: digest}`` buckets; anything
+        # else (e.g. a legacy flat layout) is ignored and re-established on use.
+        return {
+            arch: bucket
+            for arch, bucket in data.items()
+            if isinstance(bucket, dict)
+        } if isinstance(data, dict) else {}
+
+    def get(self, version: str, arch: str) -> str | None:
+        """Return the cached digest for ``version`` on ``arch``, or ``None``."""
+        return self._load().get(arch, {}).get(version)
+
+    def set(self, version: str, arch: str, digest: str) -> None:
+        """Record ``digest`` for ``version`` on ``arch``, creating the store if needed."""
+        data = self._load()
+        data.setdefault(arch, {})[version] = digest
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._path.with_suffix(".json.tmp")
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, indent=2, sort_keys=True)
+        tmp.replace(self._path)  # atomic on the same filesystem

frida_server/cli.py

@@ -0,0 +1,101 @@
+"""Command-line interface for ``frida-server``.
+
+:class:`Cli` is a thin wrapper around :class:`~frida_server.deployer.Deployer`:
+parse arguments, translate :class:`~frida_server.exceptions.FridaServerError`
+into a clean exit code, and keep ``Ctrl-C`` quiet.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .console import Console
+from .deployer import Deployer
+from .exceptions import FridaServerError
+
+_DESCRIPTION = "Deploy and start frida-server on a connected Android device."
+_EPILOG = (
+    "examples:\n"
+    "  frida-server                                   # pick a device and deploy\n"
+    "  frida-server -s emulator-5554                  # pick a device and deploy\n"
+    "  frida-server --no-update --port 27043          # pick a device and deploy\n"
+    "  frida-server --force                           # re-download even if versions match\n"
+)
+
+
+class Cli:
+    """Parses arguments and drives a :class:`Deployer` run."""
+
+    def __init__(self) -> None:
+        self._console = Console()
+
+    def build_parser(self) -> argparse.ArgumentParser:
+        """Construct the argument parser (kept separate for testing)."""
+        parser = argparse.ArgumentParser(
+            prog="frida-server",
+            description=_DESCRIPTION,
+            epilog=_EPILOG,
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+        )
+        parser.add_argument(
+            "-s",
+            "--serial",
+            metavar="SERIAL",
+            help="target a specific device serial (default: prompt when several)",
+        )
+        parser.add_argument(
+            "-p",
+            "--port",
+            type=int,
+            default=27042,
+            metavar="PORT",
+            help="TCP port to forward after start (default: 27042)",
+        )
+        parser.add_argument(
+            "--no-update",
+            dest="update",
+            action="store_false",
+            help="skip the host-side Frida update check",
+        )
+        parser.add_argument(
+            "--force",
+            action="store_true",
+            help="re-download and re-push even if a matching server is present",
+        )
+        parser.add_argument(
+            "-V",
+            "--version",
+            action="version",
+            version=f"%(prog)s {__version__}",
+        )
+        return parser
+
+    def run(self, argv: list[str] | None = None) -> int:
+        """Entry point. Returns a process exit code."""
+        args = self.build_parser().parse_args(argv)
+        try:
+            ok = Deployer(self._console).run(
+                serial=args.serial,
+                update=args.update,
+                port=args.port,
+                force=args.force,
+            )
+            return 0 if ok else 1
+        except FridaServerError as exc:
+            self._console.error(str(exc))
+            return 1
+        except KeyboardInterrupt:
+            print()
+            self._console.info("Interrupted.")
+            return 130
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Console-script entry point: run the CLI and return an exit code."""
+    return Cli().run(argv)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

frida_server/console.py

@@ -0,0 +1,54 @@
+"""Console output.
+
+A single :class:`Console` object owns all terminal output for a run, keeping the
+``[*] / [+] / [!] / [-] / [?]`` status style in one place. ANSI colour
+auto-disables when stdout is not a TTY (or when ``NO_COLOR`` is set), so piped
+output stays clean.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+class Console:
+    """Renders status lines with consistent markers and optional colour."""
+
+    _COLORS = {
+        "info": "36",     # cyan
+        "success": "32",  # green
+        "warn": "33",     # yellow
+        "error": "31",    # red
+        "prompt": "35",   # magenta
+    }
+
+    def __init__(self, *, color: bool | None = None) -> None:
+        if color is None:
+            color = sys.stdout.isatty() and os.environ.get("NO_COLOR") is None
+        self._color = color
+
+    def _paint(self, kind: str, text: str) -> str:
+        if not self._color:
+            return text
+        return f"\033[{self._COLORS[kind]}m{text}\033[0m"
+
+    def info(self, message: str) -> None:
+        """Neutral progress line, e.g. ``[*] Doing a thing``."""
+        print(f"{self._paint('info', '[*]')} {message}")
+
+    def success(self, message: str) -> None:
+        """Positive outcome, e.g. ``[+] Done``."""
+        print(f"{self._paint('success', '[+]')} {message}")
+
+    def warn(self, message: str) -> None:
+        """Non-fatal warning, e.g. ``[!] Heads up``."""
+        print(f"{self._paint('warn', '[!]')} {message}")
+
+    def error(self, message: str) -> None:
+        """Failure line, written to stderr, e.g. ``[-] Broke``."""
+        print(f"{self._paint('error', '[-]')} {message}", file=sys.stderr)
+
+    def prompt(self, message: str) -> str:
+        """Ask the user a question and return the stripped answer."""
+        return input(f"{self._paint('prompt', '[?]')} {message}").strip()

frida_server/deployer.py

@@ -0,0 +1,210 @@
+"""High-level orchestration: the full deploy-and-run flow.
+
+:class:`Deployer` ties the layers together — resolve the host Frida version,
+pick a device, compare against what is already on the device, download only when
+needed, then push and launch. It is the single entry point the CLI and library
+users share.
+"""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+
+from .checksums import ChecksumStore
+from .console import Console
+from .device import Device, DeviceManager
+from .downloader import Downloader
+from .exceptions import DeviceError
+from .host import FridaHost
+
+
+class Deployer:
+    """Deploys and starts ``frida-server`` on a connected Android device."""
+
+    def __init__(self, console: Console | None = None) -> None:
+        self._console = console or Console()
+        self._host = FridaHost(self._console)
+        self._manager = DeviceManager(self._console)
+        self._checksums = ChecksumStore()
+
+    def run(
+        self,
+        *,
+        serial: str | None = None,
+        update: bool = True,
+        port: int = 27042,
+        force: bool = False,
+    ) -> bool:
+        """Deploy and start ``frida-server`` on a connected Android device.
+
+        Args:
+            serial: target a specific device serial; when ``None`` and several
+                are connected, the user is prompted to choose.
+            update: when ``True``, offer to update the host Frida install first.
+            port: TCP port to forward from PC to device after a successful start.
+            force: re-download and re-push even if a matching server exists.
+
+        Returns:
+            ``True`` if ``frida-server`` ends up running on the device.
+
+        Raises:
+            FridaServerError: (or a subclass) on any unrecoverable failure.
+        """
+        console = self._console
+        console.info("Starting Frida server setup...")
+
+        # 1. Host Frida version — the server binary must match it exactly.
+        version = self._host.maybe_update(interactive=update)
+
+        # 2. Device discovery / selection.
+        self._manager.ensure_adb()
+        serials = self._manager.serials()
+        if not serials:
+            raise DeviceError(
+                "No devices connected. Connect an Android device with USB debugging on."
+            )
+        if serial is not None:
+            device = self._manager.get(serial)
+        else:
+            console.info(f"Found {len(serials)} device(s): {', '.join(serials)}")
+            device = self._select_device(self._manager.devices())
+
+        console.info(f"Selected device: {device.describe()}")
+        console.info(f"Using Frida version: {version} (matched to host install).")
+
+        # 3. Root access up front — every later privileged step depends on it.
+        device.ensure_root()
+
+        # 4. Decide whether the on-device binary can be reused: the version must
+        #    match AND its SHA-256 must match the digest we cached when we last
+        #    deployed this version/arch. A mismatch (corrupt/tampered/foreign
+        #    binary) forces a fresh deploy.
+        if not force and self._can_reuse(device, version):
+            console.info(f"frida-server v{version} already present — reusing it.")
+            return self._finish(device, port, ask_restart=True)
+
+        # 5. Download + push the matching binary, recording its checksum, then start.
+        with tempfile.TemporaryDirectory(prefix="frida-server-") as workdir:
+            binary = Downloader(console).download(version, device.arch, workdir)
+            digest = ChecksumStore.file_sha256(binary)
+            device.push_server(str(binary))
+            self._verify_pushed(device, digest)
+            self._checksums.set(version, device.arch, digest)
+
+        return self._finish(device, port)
+
+    def _can_reuse(self, device: Device, version: str) -> bool:
+        """Return True if the on-device server matches by version and checksum."""
+        console = self._console
+        existing = device.installed_server_version()
+        if existing is None:
+            console.info("frida-server not found on device.")
+            return False
+        if existing != version:
+            console.info(
+                f"On-device v{existing} differs from host v{version} — replacing."
+            )
+            return False
+
+        expected = self._checksums.get(version, device.arch)
+        if expected is None:
+            # No cached digest means we can't prove the on-device binary is
+            # genuine — re-deploy a fresh verified copy and establish the cache.
+            console.info(
+                "No cached checksum for this version — re-deploying to verify."
+            )
+            return False
+
+        actual = device.server_sha256()
+        if actual is None:
+            console.warn("Could not read on-device checksum — reusing by version.")
+            return True
+        if actual != expected:
+            console.warn(
+                f"On-device checksum mismatch (sha256:{actual[:12]}… vs "
+                f"{expected[:12]}…) — re-deploying."
+            )
+            return False
+        console.success(f"Checksum verified (sha256:{actual[:12]}…).")
+        return True
+
+    def _confirm_restart(self, pid: str) -> bool:
+        """Ask whether to restart an already-running server. Defaults to no."""
+        try:
+            answer = self._console.prompt(
+                f"frida-server is already running (PID {pid}). Restart? (y/N): "
+            ).lower()
+        except (KeyboardInterrupt, EOFError):
+            print()
+            return False
+        return answer == "y"
+
+    def _verify_pushed(self, device: Device, digest: str) -> None:
+        """Confirm the freshly pushed binary hashes to the expected digest."""
+        actual = device.server_sha256()
+        if actual is None:
+            return  # sha256sum unavailable — cannot verify, but push reported OK
+        if actual == digest:
+            self._console.success(f"Pushed binary verified (sha256:{digest[:12]}…).")
+        else:
+            self._console.warn(
+                f"Pushed binary checksum mismatch (sha256:{actual[:12]}… vs "
+                f"{digest[:12]}…) — the transfer may be corrupt."
+            )
+
+    def _select_device(self, devices: list[Device]) -> Device:
+        """Return the chosen device, prompting the user when several are present."""
+        if len(devices) == 1:
+            return devices[0]
+
+        self._console.info("Multiple devices detected. Select one:\n")
+        for index, device in enumerate(devices, 1):
+            print(f"    {index}. {device.describe()}")
+        print()
+
+        while True:
+            try:
+                choice = self._console.prompt(f"Select device (1-{len(devices)}): ")
+                idx = int(choice) - 1
+                if 0 <= idx < len(devices):
+                    return devices[idx]
+                self._console.error(f"Enter a number between 1 and {len(devices)}.")
+            except ValueError:
+                self._console.error("Please enter a valid number.")
+            except (KeyboardInterrupt, EOFError):
+                self._console.info("Cancelled.")
+                sys.exit(0)
+
+    def _finish(self, device: Device, port: int, *, ask_restart: bool = False) -> bool:
+        """Start the server (or keep a running one), forward the port, and report.
+
+        When ``ask_restart`` is set and a ``frida-server`` is already running, the
+        user is asked whether to restart it. The default answer is *no* (an empty
+        line, EOF, or Ctrl-C all mean "keep the running server"), so the existing
+        process is left untouched and only the port forward is (re)applied.
+        """
+        console = self._console
+
+        if ask_restart:
+            running = device.running_pids()
+            if running and not self._confirm_restart(running[0]):
+                console.info("Keeping the running frida-server.")
+                device.forward_port(port)
+                console.success("Frida server is ready! You can now attach with Frida.")
+                return True
+
+        if device.start_server():
+            device.forward_port(port)
+            console.success("Frida server is ready! You can now attach with Frida.")
+            return True
+
+        console.error("frida-server may not have started correctly.")
+        log = device.read_server_log()
+        if log:
+            console.error(f"Server output:\n{log}")
+        console.error(
+            f"Try manually: adb -s {device.serial} shell "
+            "/data/local/tmp/frida-server  (to see the error output)"
+        )
+        return False