{"id":7249,"library":"frida-tools","title":"Frida CLI Tools","description":"frida-tools provides a set of command-line interface (CLI) utilities for Frida, a dynamic instrumentation toolkit. It allows developers, reverse-engineers, and security researchers to inject JavaScript into native applications on various platforms (Windows, macOS, GNU/Linux, iOS, Android, QNX) to observe and reprogram running programs. The library is actively maintained, with the current version being 14.8.1, and typically follows the release cycle of its core dependency, 'frida'.","status":"active","version":"14.8.1","language":"en","source_language":"en","source_url":"https://github.com/frida/frida-tools","tags":["security","reverse engineering","dynamic analysis","instrumentation","debugger","cli"],"install":[{"cmd":"pip install frida-tools","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dynamic instrumentation library that frida-tools builds upon.","package":"frida","optional":false},{"reason":"Used for colored terminal output.","package":"colorama","optional":false},{"reason":"Provides an interactive command-line interface.","package":"prompt-toolkit","optional":false},{"reason":"Used for syntax highlighting.","package":"pygments","optional":false},{"reason":"Enables WebSocket communication, likely for connecting to frida-server.","package":"websockets","optional":false}],"imports":[{"note":"frida-tools provides CLI utilities, but its Python API relies on the 'frida' package for direct scripting.","symbol":"frida","correct":"import frida"}],"quickstart":{"code":"import frida\n\ndef on_message(message, data):\n    print(f\"[on_message] message: {message}, data: {data}\")\n\ntry:\n    # Attach to a running process, replace 'cat' with a valid process name or PID on your system\n    # For remote devices, use frida.get_usb_device().attach('process_name') or frida.get_device_manager().get_device('id').attach('process_name')\n    session = frida.attach('cat') # Example: a simple running process\n    \n    # Create a JavaScript script to inject\n    script = session.create_script(\"\"\"\n        rpc.exports.enumerateModules = () => {\n            return Process.enumerateModules();\n        };\n    \"\"\")\n    \n    # Set up message handler\n    script.on('message', on_message)\n    \n    # Load the script into the target process\n    script.load()\n    \n    # Call an exported RPC method from Python\n    modules = script.exports_sync.enumerate_modules()\n    print([m['name'] for m in modules])\n    \n    # Keep the script running (or detach when done)\n    input('[*] Press Enter to detach from process\\n')\n    session.detach()\nexcept frida.ProcessNotFoundError:\n    print(\"Error: Process 'cat' not found. Please ensure 'cat' or another process is running.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to use the underlying 'frida' Python binding (which 'frida-tools' uses) to attach to a running process, inject a JavaScript agent, call an RPC method, and process messages. Replace 'cat' with an actual running process on your system or a connected device for a successful execution. For mobile devices, ensure 'frida-server' is running on the device and specify the correct device and process."},"warnings":[{"fix":"Migrate your JavaScript agents to use `Process.findModuleByName().base` for module base addresses and instance methods like `ptr.readU32()` for memory operations. Runtime bridges (Java, ObjC, Swift) are also no longer bundled directly with Frida's GumJS runtime but are baked into `frida-tools` REPL and `frida-trace` agents.","message":"Frida 17 (released May 2025) introduced significant breaking changes in its JavaScript API, affecting static Module and Memory methods, and legacy enumeration APIs. For example, `Module.findBaseAddress()` and `Memory.readU32(ptr)` were removed.","severity":"breaking","affected_versions":"frida >= 17.0.0 (and frida-tools relying on it)"},{"fix":"Always ensure that the `frida-server` version deployed on your target device (e.g., Android, iOS) matches the `frida` Python package version installed on your host system. Download the correct `frida-server` binary from Frida's GitHub releases page.","message":"Mismatch between `frida-tools` and `frida-server` versions on target devices can lead to unexpected behavior or failures. While `frida-tools` is installed on your host, `frida-server` runs on the target device.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Manually add the Python 'Scripts' directory (e.g., `C:\\Users\\<username>\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.<version>_qbz5n2kfra8p0\\LocalCache\\local-packages\\Python<version>\\Scripts`) to your system's PATH environment variable.","message":"On Windows, the `frida` and `frida-tools` CLI commands might not be found in the system PATH after installation, leading to 'command not found' errors.","severity":"gotcha","affected_versions":"All versions on Windows"},{"fix":"Instead of the process name, use the Process ID (PID) which is unique. You can find the PID using `frida-ps -U` for USB devices or `frida-ps -a` for all processes. Example: `session = frida.attach(12345)`.","message":"When attaching to a process by name using `frida.attach('process_name')`, a `ValueError: ambiguous name` error can occur if multiple processes share the same name.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Try running the command with elevated privileges (e.g., `sudo sysctl kernel.yama.ptrace_scope=0` on Linux, ensure Frida is properly signed on macOS, or disable security mechanisms like Magisk Hide/Knox on Android and reboot).","cause":"This error typically indicates insufficient permissions to attach to the target process, often due to security mechanisms (e.g., SELinux policies, Samsung Knox, Google Play Protect) or `ptrace` restrictions.","error":"SystemError: attach_to_process PTRACE_ATTACH failed: 1"},{"fix":"Ensure you are using the correct Python interpreter for the installed `frida` package. If you have multiple Python versions, verify your `pip` installation target and `PYTHONPATH`. It is recommended to use Python 3.7+ with recent Frida versions.","cause":"This error usually arises when trying to use `frida` Python bindings compiled for one Python major version (e.g., Python 2.x) with a different major version (e.g., Python 3.x), or vice versa.","error":"ImportError: dynamic module does not define init function (init_frida)"},{"fix":"Attempt to disable relevant security mechanisms (e.g., Samsung Knox) via `adb shell` commands and reboot the device. For example: `adb shell pm disable-user --user 0 com.samsung.android.knox.attestation`.","cause":"Often seen on Android devices, this indicates an issue with Frida's ability to interact with processes due to stringent security mechanisms like SELinux or other kernel-level protections.","error":"Failed to enumerate applications: unable to perform ptrace pokedata: I/O error"},{"fix":"On Linux/macOS, ensure your user's `~/.local/bin` is in PATH. On Windows, manually add the Python 'Scripts' directory to your system's PATH. Restart your terminal after modifying PATH.","cause":"The `frida-tools` CLI executables are not in your system's PATH environment variable.","error":"frida: command not found"}]}