diff --git a/src/frida/FridaInstrumentationManager.test.ts b/src/frida/FridaInstrumentationManager.test.ts index 8d49bf4def..225c84668e 100644 --- a/src/frida/FridaInstrumentationManager.test.ts +++ b/src/frida/FridaInstrumentationManager.test.ts @@ -394,6 +394,60 @@ describe("FridaInstrumentationManager", () => { await manager.closeAll(); }); + it.each(["attach", "spawn"] as const)( + "names the refused ptrace seize request when %s injection cannot start", + async (mode) => { + const bindings = new FakeDeviceManager(); + const reason = "Unable to perform ptrace seize: Operation not supported"; + bindings.device.attach = async () => { + throw new Error(reason); + }; + const manager = new FridaInstrumentationManager({ + deviceManager: bindings, + }); + const started = await manager.startSession( + mode === "attach" + ? { mode, deviceId: "local", pid: 512 } + : { mode, deviceId: "local", program: "/bin/echo" }, + ); + expect(started.ok).toBe(false); + if (started.ok) return; + const projected = projectAnalysisError(started.error); + expect(projected).toMatchObject({ + code: "capability_unavailable", + details: { reason, provider_id: "frida" }, + }); + expect(projected.remediation.action).toContain("PTRACE_SEIZE"); + expect(projected.remediation.action).toContain("PRoot"); + expect(projected.remediation.action).not.toContain( + "Choose another analysis or target", + ); + expect(projected.message).toContain("ptrace seize"); + await manager.closeAll(); + }, + ); + + it("keeps the generic remediation for other Frida startup refusals", async () => { + const bindings = new FakeDeviceManager(); + bindings.device.attach = async () => { + throw new Error("Unable to access process with pid 512"); + }; + const manager = new FridaInstrumentationManager({ + deviceManager: bindings, + }); + const started = await manager.startSession({ + mode: "attach", + deviceId: "local", + pid: 512, + }); + expect(started.ok).toBe(false); + if (started.ok) return; + expect( + projectAnalysisError(started.error).remediation.action, + ).not.toContain("PTRACE_SEIZE"); + await manager.closeAll(); + }); + it("retains a failed startup's spawn and remote lease until cleanup succeeds", async () => { const bindings = new FakeDeviceManager(); bindings.device.attach = async () => { diff --git a/src/frida/FridaInstrumentationManager.ts b/src/frida/FridaInstrumentationManager.ts index 1a37209423..ce0b36d94a 100644 --- a/src/frida/FridaInstrumentationManager.ts +++ b/src/frida/FridaInstrumentationManager.ts @@ -1617,6 +1617,39 @@ const sanitizeError = ( ), ).value; +/** + * Frida reports a refused ptrace seize with this prefix. Only that request + * is recognized: the reason carries no errno, so it does not identify the + * environment, and discovery can succeed where injection is refused. + */ +const PTRACE_SEIZE_REFUSAL = /^Unable to perform ptrace seize\b/i; + +/** + * Guidance for the Frida failures whose generic "choose another target" + * remediation would send the operator the wrong way. + */ +const providerFailureGuidance = ( + reason: string, + remote: boolean, +): { + readonly userMessage?: string; + readonly remediationAction?: string; +} => { + if (remote && reason === "Unable to connect to remote frida-server") + return { + remediationAction: + "Confirm the selected Frida server is reachable and its connection options are correct, then retry.", + }; + if (PTRACE_SEIZE_REFUSAL.test(reason)) + return { + userMessage: + "Frida could not start tracing the target because its ptrace seize request was refused.", + remediationAction: + "Injection is unavailable here whatever the target: the operating system refused Frida's PTRACE_SEIZE request (see details.reason). Emulated environments such as PRoot-Distro on Android do not implement it, although device and process discovery still succeed, and restrictive ptrace policies can also refuse it. Run REA on a host with native ptrace support, or select a Frida server running on one with the remote options, then retry.", + }; + return {}; +}; + const providerError = ( operation: string, cause: unknown, @@ -1686,14 +1719,9 @@ const providerError = ( return new AnalysisCapabilityUnavailableError("frida", operation, reason, { cause: remote === undefined ? cause : new Error(reason), diagnostics, - ...(selector?.remote === undefined || - cleanupReason !== undefined || - reason !== "Unable to connect to remote frida-server" + ...(cleanupReason !== undefined ? {} - : { - remediationAction: - "Confirm the selected Frida server is reachable and its connection options are correct, then retry.", - }), + : providerFailureGuidance(reason, selector?.remote !== undefined)), ...(cleanupReason === undefined ? {} : {