Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(adb): refuse transfers when destination existence is unknown
morluto61e688070f48
diff --git a/docs/adb-device-analysis.md b/docs/adb-device-analysis.mdindex b18e7b4fb..7e10ac33d 100644--- a/docs/adb-device-analysis.md+++ b/docs/adb-device-analysis.md@@ -153,8 +153,10 @@ and during shutdown.- **Mutations are explicit.** `push_adb_file`, `install_adb_package`, and`uninstall_adb_package` declare `mutatesTarget` and never run implicitly:pushes check for existing device files before transfer and refuse them- unless `overwrite` is set. The check is not atomic, so a different process- can create the path before `adb push` writes it. When available, the device's+ unless `overwrite` is set. A failed or unexpected existence probe stops+ transfer even with `overwrite`; only a clean `test -e` exit of 1 with no+ output is interpreted as absence. The check is not atomic, so a different+ process can create the path before `adb push` writes it. When available, the device's`sha256sum` verifies the transfer; installs preserve thedevice's `Failure [...]` reason verbatim.- **Producer identity stays attached.** Every result embeds the producingdiff --git a/src/adb/AdbCommand.test.ts b/src/adb/AdbCommand.test.tsnew file mode 100644index 000000000..63bb5ab0a--- /dev/null+++ b/src/adb/AdbCommand.test.ts@@ -0,0 +1,112 @@+import { expect, it, vi } from "vitest";+import { execFileBytes } from "../process/ExecFileOutput.js";+import { probeAdbPathExistence } from "./AdbCommand.js";++vi.mock("../process/ExecFileOutput.js", async (importOriginal) => ({+ ...(await importOriginal<typeof import("../process/ExecFileOutput.js")>()),+ execFileBytes: vi.fn(),+}));++const probe = (signal?: AbortSignal) =>+ probeAdbPathExistence(+ "push_adb_file",+ "device",+ "/device/path",+ "/host/adb",+ {+ timeoutMs: 100,+ maxOutputBytes: 1024,+ },+ signal,+ );++it("recognizes only the completed empty false result as absence", async () => {+ vi.mocked(execFileBytes).mockRejectedValueOnce(+ Object.assign(new Error("test false"), {+ code: 1,+ stdout: "",+ stderr: "",+ signal: null,+ killed: false,+ }),+ );+ await expect(probe()).resolves.toEqual({ ok: true, value: false });+});++it.each([+ { code: 2 },+ { code: "ENOENT" },+ { signal: "SIGTERM" },+ { collectionFailure: true },+ { stdout: "unexpected" },+ { stderr: " " },+])("keeps nonstandard false completion unknown: %j", async (extra) => {+ vi.mocked(execFileBytes).mockRejectedValueOnce(+ Object.assign(new Error("probe failed"), {+ code: 1,+ stdout: "",+ stderr: "",+ signal: null,+ killed: false,+ ...extra,+ }),+ );+ const result = await probe();+ expect(result).toMatchObject({+ ok: false,+ error: {+ _tag: "AnalysisProtocolError",+ diagnostics: { destination_existence: "unknown" },+ },+ });+});++it.each([+ [{ killed: true }, "AnalysisTimeoutError"],+ [{ outputTruncated: true }, "AnalysisResourceConstraintError"],+ [{ code: "ABORT_ERR" }, "AnalysisCancelledError"],+] as const)(+ "preserves a stopped or incomplete probe: %j",+ async (extra, tag) => {+ vi.mocked(execFileBytes).mockRejectedValueOnce(+ Object.assign(new Error("probe failed"), {+ code: 1,+ stdout: "",+ stderr: "",+ signal: null,+ killed: false,+ ...extra,+ }),+ );+ await expect(probe()).resolves.toMatchObject({+ ok: false,+ error: { _tag: tag },+ });+ },+);++it("recognizes an empty successful probe as existence", async () => {+ vi.mocked(execFileBytes).mockResolvedValueOnce({+ stdout: Buffer.alloc(0),+ stderr: Buffer.alloc(0),+ });+ await expect(probe()).resolves.toEqual({ ok: true, value: true });+});++it.each(["stdout", "stderr"] as const)(+ "retains unexpected successful %s as unknown",+ async (stream) => {+ vi.mocked(execFileBytes).mockResolvedValueOnce({+ stdout: Buffer.alloc(0),+ stderr: Buffer.alloc(0),+ [stream]: Buffer.from("unexpected"),+ });+ await expect(probe()).resolves.toMatchObject({+ ok: false,+ error: {+ _tag: "AnalysisProtocolError",+ capturedOutput: { [stream]: "unexpected", exit_code: 0 },+ },+ });+ },+);diff --git a/src/adb/AdbCommand.ts b/src/adb/AdbCommand.tsnew file mode 100644index 000000000..5ab13e4b5--- /dev/null+++ b/src/adb/AdbCommand.ts@@ -0,0 +1,244 @@+import {+ AnalysisCancelledError,+ AnalysisProtocolError,+ AnalysisResourceConstraintError,+ AnalysisTimeoutError,+ AnalysisUnsupportedTargetError,+} from "../domain/analysisErrorCore.js";+import type { AnalysisError } from "../domain/analysisErrorBase.js";+import { err, ok, type Result } from "../domain/result.js";+import {+ execFileBytes,+ execFileOutputFailure,+ type ExecFileOutputFailure,+} from "../process/ExecFileOutput.js";+import { packageChangeFailureReason } from "./AdbShellOutput.js";++const STDERR_EXCERPT_BYTES = 512;++/** Parsed command failure owned by this adapter, separate from its public tag. */+class AdbProtocolError extends AnalysisProtocolError {+ constructor(+ message: string,+ readonly commandFailure: ExecFileOutputFailure,+ cause: unknown,+ ) {+ super(message, { cause });+ }+}++/** adb joins shell operands into a remote POSIX command; quote at that boundary. */+const quoteShellOperand = (value: string): string =>+ /^[A-Za-z0-9_./:=@+,-]+$/u.test(value)+ ? value+ : "'" + value.replaceAll("'", "'\\''") + "'";++export const adbArguments = (+ serial: string | undefined,+ arguments_: readonly string[],+): readonly string[] => {+ const operands =+ arguments_[0] === "shell"+ ? ["shell", ...arguments_.slice(1).map(quoteShellOperand)]+ : [...arguments_];+ return serial === undefined ? operands : ["-s", serial, ...operands];+};++export interface AdbRunLimits {+ readonly timeoutMs: number;+ readonly maxOutputBytes: number;+}++/** Run one bounded adb invocation and keep its exact failure shape. */+export const runAdbCapture = async (+ operation: string,+ targetPath: string,+ binary: string,+ arguments_: readonly string[],+ limits: AdbRunLimits,+ signal: AbortSignal | undefined,+): Promise<Result<{ stdout: Buffer; stderr: Buffer }, AnalysisError>> => {+ if (signal?.aborted === true)+ return err(new AnalysisCancelledError(operation, { cause: signal.reason }));+ try {+ return ok(+ await execFileBytes(binary, arguments_, {+ timeout: limits.timeoutMs,+ maxBuffer: limits.maxOutputBytes,+ stopSignal: "SIGTERM",+ ...(signal === undefined ? {} : { signal }),+ }),+ );+ } catch (cause) {+ const failure = execFileOutputFailure(cause);+ if (signal?.aborted || failure?.code === "ABORT_ERR")+ return err(new AnalysisCancelledError(operation, { cause }));+ if (failure === undefined)+ return err(+ new AnalysisProtocolError(`adb failed for ${operation}`, { cause }),+ );+ if (failure.outputTruncated)+ return err(+ new AnalysisResourceConstraintError(+ operation,+ "memory",+ `adb output exceeded the ${String(limits.maxOutputBytes)}-byte capture budget`,+ { max_output_bytes: limits.maxOutputBytes },+ { cause },+ ),+ );+ const excerpt = failure.stderr.trim().slice(0, STDERR_EXCERPT_BYTES);+ if (/unauthorized/iu.test(excerpt))+ return err(+ new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {+ cause,+ }),+ );+ if (+ /device[^\n]*not found|device offline|still authorizing|more than one device/iu.test(+ excerpt,+ )+ )+ return err(+ new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {+ cause,+ }),+ );+ if (+ /No such file or directory|Permission denied|read: Permission denied/iu.test(+ excerpt,+ )+ )+ return err(+ new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {+ cause,+ }),+ );+ if (failure.killed)+ return err(+ new AnalysisTimeoutError(operation, limits.timeoutMs, { cause }),+ );+ return err(+ new AdbProtocolError(+ excerpt === ""+ ? `adb exited with code ${String(failure.code)} for ${operation}`+ : excerpt,+ failure,+ cause,+ ),+ );+ }+};++/** Decode textual adb protocols after the shared byte capture and error boundary. */+export const runAdb = async (+ ...arguments_: Parameters<typeof runAdbCapture>+): Promise<+ Result<{ stdout: string; stderr: string; stdoutBytes: number }, AnalysisError>+> => {+ const captured = await runAdbCapture(...arguments_);+ if (!captured.ok) return captured;+ return ok({+ stdout: captured.value.stdout.toString("utf8"),+ stderr: captured.value.stderr.toString("utf8"),+ // Byte count of the captured output before UTF-8 decoding, so malformed+ // sequences replaced by U+FFFD still report their true captured size.+ stdoutBytes: captured.value.stdout.byteLength,+ });+};++/**+ * adb exits nonzero when the device refuses a package change, printing the+ * `Failure [...]` verdict to stderr (install) or stdout (uninstall). Read the+ * refusal from that failed run so it is not reported as unreadable output.+ */+export const packageChangeRefusal = (+ operation: string,+ serial: string,+ error: AnalysisError,+): Result<never, AnalysisError> | undefined => {+ if (!(error instanceof AdbProtocolError)) return undefined;+ const failure = error.commandFailure;+ const reason = packageChangeFailureReason(+ `${failure.stdout}\n${failure.stderr}`,+ );+ return reason === null+ ? undefined+ : err(+ new AnalysisUnsupportedTargetError(operation, serial, reason, {+ cause: error,+ }),+ );+};++/** Only the clean false result of test -e establishes absence. */+export const probeAdbPathExistence = async (+ operation: string,+ serial: string,+ path: string,+ binary: string,+ limits: AdbRunLimits,+ signal: AbortSignal | undefined,+): Promise<Result<boolean, AnalysisError>> => {+ const probed = await runAdbCapture(+ operation,+ path,+ binary,+ adbArguments(serial, ["shell", "test", "-e", path]),+ limits,+ signal,+ );+ if (probed.ok) {+ if (probed.value.stdout.length === 0 && probed.value.stderr.length === 0)+ return ok(true);+ return err(+ new AnalysisProtocolError(+ "The ADB path existence probe returned unexpected output; destination existence is unknown",+ {+ diagnostics: { destination_existence: "unknown" },+ capturedOutput: {+ stdout: probed.value.stdout.toString("utf8"),+ stderr: probed.value.stderr.toString("utf8"),+ stdout_bytes: probed.value.stdout.length,+ stderr_bytes: probed.value.stderr.length,+ exit_code: 0,+ signal: null,+ truncated: false,+ },+ },+ ),+ );+ }+ const error = probed.error;+ if (!(error instanceof AdbProtocolError)) return probed;+ const failure = error.commandFailure;+ if (+ failure.code === 1 &&+ failure.signal === null &&+ !failure.killed &&+ !failure.outputTruncated &&+ failure.collectionFailure !== true &&+ failure.stdout === "" &&+ failure.stderr === ""+ )+ return ok(false);+ return err(+ new AnalysisProtocolError(error.message, {+ cause: error.cause,+ diagnostics: { destination_existence: "unknown" },+ capturedOutput: {+ stdout: failure.stdout,+ stderr: failure.stderr,+ ...(failure.stdoutBytes === undefined+ ? {}+ : { stdout_bytes: failure.stdoutBytes }),+ ...(failure.stderrBytes === undefined+ ? {}+ : { stderr_bytes: failure.stderrBytes }),+ exit_code: typeof failure.code === "number" ? failure.code : null,+ signal: failure.signal,+ truncated: failure.outputTruncated,+ },+ }),+ );+};diff --git a/src/adb/AdbProvider.ts b/src/adb/AdbProvider.tsindex db696e899..60d7b3672 100644--- a/src/adb/AdbProvider.ts+++ b/src/adb/AdbProvider.ts@@ -70,9 +70,13 @@ import {import { ProviderCleanupError } from "../domain/providerCleanupError.js";import { PrivateRuntimeRootUnavailableError } from "../process/PrivateRuntimeRootUnavailableError.js";import {- execFileBytes,- execFileOutputFailure,-} from "../process/ExecFileOutput.js";+ adbArguments,+ runAdb,+ runAdbCapture,+ packageChangeRefusal,+ probeAdbPathExistence,+ type AdbRunLimits,+} from "./AdbCommand.js";import {AdbConfigurationFailure,adbConfigurationAvailability,@@ -102,7 +106,6 @@ import {parseBugreportCopiedPath,parseDumpsysPackageOutput,parseFeatureListOutput,- packageChangeFailureReason,parsePackageChangeOutput,parseProcessListOutput,parsePngDimensions,@@ -144,7 +147,6 @@ const SCREEN_TIMEOUT_MS = 60_000;const SCREEN_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;const BUGREPORT_TIMEOUT_MS = 600_000;const BUGREPORT_MAX_OUTPUT_BYTES = 1024 * 1024;-const STDERR_EXCERPT_BYTES = 512;const UNPARSED_LINES_REPORTED = 10;/** Carry the exact digest owner through caller-specific partial-result mapping. */@@ -364,150 +366,6 @@ const syncStagedAdbFile = async (if (primary !== undefined) throw primary;};-/** adb joins shell operands into a remote POSIX command; quote at that boundary. */-const quoteShellOperand = (value: string): string =>- /^[A-Za-z0-9_./:=@+,-]+$/u.test(value)- ? value- : "'" + value.replaceAll("'", "'\\''") + "'";--const adbArguments = (- serial: string | undefined,- arguments_: readonly string[],-): readonly string[] => {- const operands =- arguments_[0] === "shell"- ? ["shell", ...arguments_.slice(1).map(quoteShellOperand)]- : [...arguments_];- return serial === undefined ? operands : ["-s", serial, ...operands];-};--interface AdbRunLimits {- readonly timeoutMs: number;- readonly maxOutputBytes: number;-}--/** Run one bounded adb invocation and keep its exact failure shape. */-const runAdbCapture = async (- operation: string,- targetPath: string,- binary: string,- arguments_: readonly string[],- limits: AdbRunLimits,- signal: AbortSignal | undefined,-): Promise<Result<{ stdout: Buffer; stderr: Buffer }, AnalysisError>> => {- if (signal?.aborted === true)- return err(new AnalysisCancelledError(operation, { cause: signal.reason }));- try {- return ok(- await execFileBytes(binary, arguments_, {- timeout: limits.timeoutMs,- maxBuffer: limits.maxOutputBytes,- stopSignal: "SIGTERM",- ...(signal === undefined ? {} : { signal }),- }),- );- } catch (cause) {- if (signal?.aborted || execFileOutputFailure(cause)?.code === "ABORT_ERR")- return err(new AnalysisCancelledError(operation, { cause }));- const failure = execFileOutputFailure(cause);- if (failure === undefined)- return err(- new AnalysisProtocolError(`adb failed for ${operation}`, { cause }),- );- if (failure.outputTruncated)- return err(- new AnalysisResourceConstraintError(- operation,- "memory",- `adb output exceeded the ${String(limits.maxOutputBytes)}-byte capture budget`,- { max_output_bytes: limits.maxOutputBytes },- { cause },- ),- );- const excerpt = failure.stderr.trim().slice(0, STDERR_EXCERPT_BYTES);- if (/unauthorized/iu.test(excerpt))- return err(- new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {- cause,- }),- );- if (- /device[^\n]*not found|device offline|still authorizing|more than one device/iu.test(- excerpt,- )- )- return err(- new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {- cause,- }),- );- if (- /No such file or directory|Permission denied|read: Permission denied/iu.test(- excerpt,- )- )- return err(- new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {- cause,- }),- );- if (failure.killed)- return err(- new AnalysisTimeoutError(operation, limits.timeoutMs, { cause }),- );- return err(- new AnalysisProtocolError(- excerpt === ""- ? `adb exited with code ${String(failure.code)} for ${operation}`- : excerpt,- { cause },- ),- );- }-};--/** Decode textual adb protocols after the shared byte capture and error boundary. */-const runAdb = async (- ...arguments_: Parameters<typeof runAdbCapture>-): Promise<- Result<{ stdout: string; stderr: string; stdoutBytes: number }, AnalysisError>-> => {- const captured = await runAdbCapture(...arguments_);- if (!captured.ok) return captured;- return ok({- stdout: captured.value.stdout.toString("utf8"),- stderr: captured.value.stderr.toString("utf8"),- // Byte count of the captured output before UTF-8 decoding, so malformed- // sequences replaced by U+FFFD still report their true captured size.- stdoutBytes: captured.value.stdout.byteLength,- });-};--/**- * adb exits nonzero when the device refuses a package change, printing the- * `Failure [...]` verdict to stderr (install) or stdout (uninstall). Read the- * refusal from that failed run so it is not reported as unreadable output.- */-const packageChangeRefusal = (- operation: string,- serial: string,- error: AnalysisError,-): Result<never, AnalysisError> | undefined => {- if (!(error instanceof AnalysisProtocolError)) return undefined;- const failure = execFileOutputFailure(error.cause);- if (failure === undefined) return undefined;- const reason = packageChangeFailureReason(- `${failure.stdout}\n${failure.stderr}`,- );- return reason === null- ? undefined- : err(- new AnalysisUnsupportedTargetError(operation, serial, reason, {- cause: error,- }),- );-};-const clientIdentityResult = (selection: AdbBinarySelection,identity: AdbClientIdentity,@@ -2535,28 +2393,16 @@ export class AdbProvider {operation,signal,);- // `test -e` exits nonzero with no adb diagnosis when the path is absent.- // Any other probe failure leaves existence unknown, so it is reported as- // such rather than treated as absence or followed by a push.- const existsProbe = await runAdb(+ const existsProbe = await probeAdbPathExistence(operation,+ input.serial,input.device_path,selection.binary,- adbArguments(input.serial, [- "shell",- "test",- "-e",- input.device_path,- ]),{ timeoutMs: SETTINGS_TIMEOUT_MS, maxOutputBytes: 1024 },signal,);- if (- !existsProbe.ok &&- !(existsProbe.error instanceof AnalysisProtocolError)- )- return existsProbe;- const deviceExists = existsProbe.ok;+ if (!existsProbe.ok) return existsProbe;+ const deviceExists = existsProbe.value;if (deviceExists && !input.overwrite)return err(new AnalysisOutputError(diff --git a/tests/boundary/cli/adbCli.test.ts b/tests/boundary/cli/adbCli.test.tsindex 69925565f..e41aeb7e8 100644--- a/tests/boundary/cli/adbCli.test.ts+++ b/tests/boundary/cli/adbCli.test.ts@@ -5,6 +5,10 @@ import { expect, it, onTestFinished } from "vitest";import { z } from "zod";import { toolContract } from "../../../src/contracts/toolContracts.js";+import {+ execFileOutput,+ execFileOutputFailure,+} from "../../../src/process/ExecFileOutput.js";import {expectConfigurationRefusal,serveCli as serve,@@ -14,6 +18,71 @@ import {removeTestWorkspace,} from "../../support/workspace/workspaceFixture.js";+it.skipIf(process.platform === "win32").each([+ { exit: 1, stdout: "", stderr: "adb: error: closed", overwrite: false },+ { exit: 1, stdout: "", stderr: "adb: error: closed", overwrite: true },+ { exit: 1, stdout: "unexpected probe output", stderr: "", overwrite: false },+ { exit: 2, stdout: "", stderr: "", overwrite: false },+])("refuses an ambiguous destination probe before push: %j", async (probe) => {+ const workspace = await createTestWorkspace("rea-adb-probe-cli-");+ onTestFinished(() => removeTestWorkspace(workspace.root));+ const source = await workspace.write("payload.bin", "replacement");+ await workspace.write("device-file", "original");+ const adb = await workspace.write(+ "adb",+ `#!/bin/sh+root=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)+printf '%s\\n' "$3" >> "$root/calls"+if [ "$1" = version ]; then+ printf 'Android Debug Bridge version 1.0.41\\nVersion 34.0.5-cli\\nInstalled as %s\\n' "$0"+ exit 0+fi+if [ "$3" = shell ] && [ "$4" = test ]; then+ printf '%s' '${probe.stdout}'+ printf '%s' '${probe.stderr}' >&2+ exit ${String(probe.exit)}+fi+if [ "$3" = push ]; then cp "$4" "$root/device-file"; exit 0; fi+exit 1+`,+ );+ await chmod(adb, 0o755);+ const result = await execFileOutput(+ process.execPath,+ [+ "scripts/rea.mjs",+ "push-adb-file",+ "device",+ source,+ "/data/local/tmp/payload.bin",+ ...(probe.overwrite ? ["--overwrite"] : []),+ "--json",+ ],+ {+ env: { ...process.env, REA_ADB_PATH: adb },+ timeout: 20_000,+ stopSignal: "SIGTERM",+ maxBuffer: 1024 * 1024,+ },+ ).then(+ (output) => ({ exitCode: 0, stdout: output.stdout }),+ (cause: unknown) => {+ const failure = execFileOutputFailure(cause);+ if (failure === undefined) throw cause;+ return { exitCode: failure.code, stdout: failure.stdout };+ },+ );+ expect(result.exitCode).toBe(1);+ expect(JSON.parse(result.stdout)).toMatchObject({+ code: "unreadable_output",+ });+ if (probe.stderr !== "") expect(result.stdout).toContain(probe.stderr);+ expect(await readFile(workspace.path("device-file"), "utf8")).toBe(+ "original",+ );+ expect(await readFile(workspace.path("calls"), "utf8")).toBe("\nshell\n");+});+it.each([[["inspect-adb-client", "--json"],