Files
reverse-engineering-anything/src/apktool/ApktoolConfiguration.ts
T
morluto 44fedc8fdd fix(pcap): report a refused tool launch as an unavailable tool (#10553)
* fix(pcap): report a refused tool launch as an unavailable tool

When a capture read's tool launch was refused with EPERM, pcap reported it
as unreadable tool output (AnalysisProtocolError) instead of an unavailable
tool. Pcap also never told "not executable" apart from "missing".

Add classifyLaunchFailure in src/process as the one owner of which spawn
errnos mean missing (ENOENT, ENOTDIR) and which mean present but not
executable (EACCES, EPERM, ENOEXEC, EISDIR). Pcap, apktool and gdb used three
different errno lists; all three now use it.

* refactor(process): classify Java and adb launch refusals with the shared owner (#10598)

The Ghidra and JADX Java probes and adb's version probe now take
missing-versus-not-executable from classifyLaunchFailure instead of their
own errno checks. ELOOP and ENAMETOOLONG join the owner's missing set, so
adb keeps its existing classification and both Java probes now treat a
non-directory path component as a missing runtime.

* fix(pcap): preserve command launch attribution

* test(pcap): expect an unknown failing stage when a limited capture tool exits unsuccessfully

* fix(pcap): attribute a limited capture's exit through the prlimit wrapper

* fix(process): identify the refused executable for every launcher shape

Name the executable on errnos Node throws synchronously from spawn
(ENOEXEC, ENOTDIR, ...) and read the Windows native launcher's
executable-launch constraint, so pcap attributes those refusals to the
selected tool or limiter instead of an unknown stage.

* test(pcap): prove synchronous launch naming with ENOTDIR on every POSIX host
2026-11-14 21:11:59 -05:00

584 lines
21 KiB
TypeScript

import {
processInspectionCancellationError,
processInspectionFailure,
} from "../providers/OwnedCommandCleanup.js";
import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js";
import { capturedApktoolFailureOutput } from "./ApktoolCommandOutput.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { ok, err, type Result } from "../domain/result.js";
import { ApktoolCommandCleanup } from "./ApktoolCommandCleanup.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js";
import { classifyLaunchFailure } from "../process/launchFailure.js";
import {
AnalysisResourceConstraintError,
AnalysisTimeoutError,
cancelledBy,
carriedReason,
} from "../domain/analysisErrorCore.js";
import { isAbsolute, win32 } from "node:path";
import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
import { findWindowsExecutable } from "../process/WindowsExecutable.js";
import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
import { randomUUID } from "node:crypto";
import {
OwnedCommandFailure,
runOwnedCommand,
prepareOwnedCommand,
} from "../process/OwnedCommand.js";
import type { ProviderAvailability } from "../application/AnalysisProvider.js";
import type { ProviderRejectionCode } from "../domain/providerSelection.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { parse } from "semver";
import {
isWindowsBatchFile,
windowsBatchCommand,
WindowsBatchCommandError,
} from "../process/WindowsBatchCommand.js";
/** Environment key selecting the caller's apktool launcher. */
export const APKTOOL_COMMAND_ENV = "REA_APKTOOL_COMMAND";
const VERSION_TIMEOUT_MS = 20_000;
const VERSION_MAX_OUTPUT_BYTES = 64 * 1024;
const apktoolVersionProbeTimeoutGuidance = (): {
readonly userMessage: string;
readonly remediationAction: string;
} => ({
userMessage: `apktool version probe reached its ${String(VERSION_TIMEOUT_MS)} ms deadline (deadlineExpired). This release has no runtime override.`,
remediationAction: `This ${String(VERSION_TIMEOUT_MS)} ms apktool version probe has no runtime override. decode_timeout_ms does not raise it. Allow execution, cleanup and delivery headroom in the outer MCP client deadline. Confirm outstanding work and cleanup before retrying.`,
});
const APKTOOL_VERSION_REMEDIATION = `Set ${APKTOOL_COMMAND_ENV} to an Apktool 2.7.0 or newer launcher whose --version prints its version, or put one on PATH.`;
/** Repair when the selected apktool launcher does not exist. */
const APKTOOL_MISSING_REMEDIATION = `Set ${APKTOOL_COMMAND_ENV} to an absolute apktool launcher (the upstream wrapper or a java -jar script).`;
/** Repair when execution of the selected apktool launcher is denied. */
const APKTOOL_NOT_EXECUTABLE_REMEDIATION = `Check file type and execute permission for ${APKTOOL_COMMAND_ENV} or select an executable apktool launcher.`;
/** How the apktool launcher was selected for this provider instance. */
export interface ApktoolCommandSelection {
readonly command: string;
readonly commandSource: "environment" | "path";
}
/**
* Preserve an explicit launcher, or resolve the default Windows command before
* choosing native versus batch process creation. POSIX keeps execFile's PATH
* lookup. The resolved selection is reused for the version and decode runs.
*/
export const resolveApktoolCommand = async (
environment: Readonly<Record<string, string | undefined>>,
platform: NodeJS.Platform = process.platform,
signal?: AbortSignal,
): Promise<ApktoolCommandSelection> => {
if (signal?.aborted === true)
throw cancelledBy("inspect_apktool_client", signal);
const selectedEnvironment = snapshotEnvironment(environment, platform);
const configured = selectedEnvironment[APKTOOL_COMMAND_ENV];
if (configured !== undefined && configured.trim() !== "") {
if (
!(platform === "win32"
? win32.isAbsolute(configured)
: isAbsolute(configured))
)
throw new ApktoolConfigurationFailure(
"not_absolute",
`${APKTOOL_COMMAND_ENV} must be an absolute path to the apktool launcher`,
`Set ${APKTOOL_COMMAND_ENV} to an absolute apktool launcher path, or unset it to use apktool from PATH.`,
{ configured_command: configured },
);
return { command: configured, commandSource: "environment" };
}
if (platform !== "win32")
return { command: "apktool", commandSource: "path" };
// A single deadline owns the whole PATH search, including filesystem waits.
const deadline = new ProviderStartupDeadline(VERSION_TIMEOUT_MS, signal);
const lookupInterruption = () =>
deadline.interruption === "cancelled"
? cancelledBy("inspect_apktool_client", carriedReason(signal?.reason))
: new AnalysisTimeoutError("inspect_apktool_client", VERSION_TIMEOUT_MS, {
diagnostics: { phase: "windows_path_lookup" },
...apktoolVersionProbeTimeoutGuidance(),
});
try {
const found = await findWindowsExecutable("apktool", selectedEnvironment, {
signal: deadline.signal,
allowBatch: true,
});
if (found.ok) return { command: found.value, commandSource: "path" };
const failure = found.error;
if (failure.kind === "interrupted") throw lookupInterruption();
if (failure.kind === "invalid_extension")
throw new ApktoolConfigurationFailure(
"command_unresolved",
"Windows PATHEXT must contain filename extensions, not paths",
`Correct PATHEXT so it lists filename extensions only, or set ${APKTOOL_COMMAND_ENV} to an absolute apktool launcher.`,
{
selected_command: "apktool",
command_source: "path",
invalid_extension: failure.extension,
},
);
if (failure.kind === "inspection")
throw new ApktoolConfigurationFailure(
"command_unresolved",
`The PATH-selected apktool launcher could not be inspected: ${failure.path}`,
`Make the PATH-selected apktool launcher readable, or set ${APKTOOL_COMMAND_ENV} to an absolute apktool launcher.`,
{
selected_command: "apktool",
command_source: "path",
candidate_path: failure.path,
...(failure.code === null ? {} : { filesystem_error: failure.code }),
},
{ cause: failure.cause },
);
} finally {
deadline.dispose();
}
throw new ApktoolConfigurationFailure(
"command_missing",
"The apktool launcher was not found on the selected Windows PATH/PATHEXT",
`Set ${APKTOOL_COMMAND_ENV} to an absolute apktool launcher, or add its directory and extension to PATH and PATHEXT.`,
{
selected_command: "apktool",
command_source: "path",
},
);
};
export type ApktoolConfigurationFailureCode =
| "not_absolute"
| "command_missing"
| "command_not_executable"
| "command_unresolved"
| "launcher_unsupported"
| "version_unresolved"
| "unsupported_version";
/** Why the selected apktool launcher is unusable, with the owner's repair instruction. */
export class ApktoolConfigurationFailure extends Error {
constructor(
readonly code: ApktoolConfigurationFailureCode,
message: string,
readonly remediation: string,
readonly diagnostics: Readonly<Record<string, JsonValue>> = {},
options?: ErrorOptions,
) {
super(message, options);
}
}
export interface ApktoolClientIdentity {
readonly version: string;
readonly supportsDocumentedVersion: boolean;
readonly limitations: readonly string[];
}
/** Process creation for one apktool run on the selected host. */
export interface ApktoolInvocation {
readonly command: string;
readonly arguments: readonly string[];
readonly windowsVerbatimArguments: boolean;
}
/**
* Run the selected launcher directly, or through cmd.exe when Windows can
* only execute it there (the Chocolatey `apktool.bat` and `java -jar`
* wrapper scripts). Throws WindowsBatchCommandError when a token cannot be
* passed to cmd.exe safely.
*/
export const apktoolInvocation = (
selection: ApktoolCommandSelection,
arguments_: readonly string[],
environment: Readonly<NodeJS.ProcessEnv>,
platform: NodeJS.Platform = process.platform,
): ApktoolInvocation =>
platform === "win32" && isWindowsBatchFile(selection.command)
? {
...windowsBatchCommand({
environment,
batchPath: selection.command,
arguments: arguments_,
}),
windowsVerbatimArguments: true,
}
: {
command: selection.command,
arguments: arguments_,
windowsVerbatimArguments: false,
};
/** Read the version from Apktool's single-line `--version` response. */
export const parseApktoolVersionOutput = (
stdout: string,
platform: NodeJS.Platform = process.platform,
):
| ApktoolClientIdentity
| { readonly version: null; readonly reportedVersion: string | null } => {
const line = stdout
.split(/\r?\n/u)
.map((entry) => entry.trim())
.find((entry) => entry !== "");
const parsed = line === undefined ? null : parse(line);
if (line === undefined || parsed === null)
return { version: null, reportedVersion: line ?? null };
// Debian's exact -dirty marker denotes a downstream release build. Preserve
// the reported spelling; other prereleases remain earlier than their release.
const downstreamRelease =
parsed.prerelease.length === 1 &&
parsed.prerelease[0] === "dirty" &&
parsed.build.length === 0;
const atLeast = (release: string): boolean =>
(downstreamRelease
? parsed.compareMain(release)
: parsed.compare(release)) >= 0;
const limitations: string[] = [];
const discloseAdvisory = (
fix: string,
advisory: string,
slug: string,
): string =>
`Reported apktool version ${JSON.stringify(line)} predates the upstream ${fix} fix for ${advisory} (decoded resource paths could escape the output directory). Verify the selected decoder's patches before decoding untrusted APKs; launcher version alone does not establish engine contents or downstream backports. https://github.com/iBotPeaches/Apktool/security/advisories/${slug}`;
if (!atLeast("2.9.2"))
limitations.push(
discloseAdvisory("2.9.2", "CVE-2024-21633", "GHSA-2hqv-2xv4-5h5w"),
);
if (platform === "win32" && !atLeast("2.9.3"))
limitations.push(
discloseAdvisory(
"2.9.3",
"GHSA-vgwr-4w3p-xmjv on Windows",
"GHSA-vgwr-4w3p-xmjv",
),
);
// Upstream 65dd848 validates ResTypeSpec names in 3.0.2. The tagged 3.0.0
// producer also lacks that check, although the advisory names only 3.0.1.
if (parsed.major === 3 && parsed.minor === 0 && !atLeast("3.0.2"))
limitations.push(
discloseAdvisory("3.0.2", "CVE-2026-39973", "GHSA-m8mh-x359-vm8m") +
(parsed.patch === 0
? " Inclusion of the 3.0.0 release line is source-derived; the advisory lists 3.0.1."
: ""),
);
return {
version: line,
supportsDocumentedVersion: atLeast("2.7.0"),
limitations,
};
};
/** Probe within the caller-admitted command scope; decodes nothing. */
export const inspectApktoolClient = async (
selection: ApktoolCommandSelection,
cleanup: ApktoolCommandCleanup,
options: {
readonly signal?: AbortSignal;
readonly environment?: Readonly<Record<string, string | undefined>>;
readonly platform?: NodeJS.Platform;
} = {},
): Promise<ApktoolClientIdentity> => {
const {
signal,
environment = process.env,
platform = process.platform,
} = options;
const hostEnvironment = snapshotEnvironment(environment, platform);
let invocation: ApktoolInvocation;
try {
invocation = apktoolInvocation(
selection,
["--version"],
hostEnvironment,
platform,
);
} catch (cause) {
if (!(cause instanceof WindowsBatchCommandError)) throw cause;
throw new ApktoolConfigurationFailure(
"launcher_unsupported",
`The selected apktool launcher cannot be run through cmd.exe: ${cause.message}`,
`Set ${APKTOOL_COMMAND_ENV} to a launcher path without cmd.exe metacharacters (" % ^ ! & | < >), or to a native apktool executable.`,
{
selected_command: selection.command,
command_source: selection.commandSource,
},
{ cause },
);
}
let interpreted:
| Result<ApktoolClientIdentity, ApktoolConfigurationFailure>
| undefined;
try {
// The owned process group stops a shell launcher's children with it; a
// child holding inherited output pipes cannot outlive the deadline.
await prepareOwnedCommand(signal);
await runOwnedCommand(
{
command: invocation.command,
arguments: invocation.arguments,
windowsVerbatimArguments: invocation.windowsVerbatimArguments,
// Apktool launchers are commonly interpreter scripts, so ownership is
// proved by the run token rather than the launcher's argv prefix.
expectedCommand: null,
runId: randomUUID(),
hostEnvironment,
},
{
timeoutMs: VERSION_TIMEOUT_MS,
diagnosticBytes: VERSION_MAX_OUTPUT_BYTES,
observeCompleted: (snapshot) => {
try {
interpreted = ok(
interpretApktoolVersion(
snapshot.stdout.text,
snapshot.stderr.text,
selection,
platform,
),
);
} catch (cause) {
if (!(cause instanceof ApktoolConfigurationFailure)) throw cause;
interpreted = err(cause);
}
},
},
signal === undefined ? {} : { signal },
);
} catch (cause) {
const recordedFailure =
interpreted?.ok === false ? interpreted.error : undefined;
const cancellation =
cause instanceof OwnedCommandFailure ? cause.cancellation : undefined;
const failure =
recordedFailure === undefined
? versionProbeFailure(
cause,
selection,
interpreted?.ok === true ? interpreted.value : undefined,
)
: new ApktoolConfigurationFailure(
recordedFailure.code,
recordedFailure.message,
recordedFailure.remediation,
{
...recordedFailure.diagnostics,
...(cancellation === undefined
? {}
: { cancellation_observed: true }),
},
{ cause },
);
const primary =
failure instanceof AnalysisError
? failure
: new ProviderAdapterError("apktool", "inspect_apktool_client", {
cause: failure,
userMessage: failure.message,
diagnostics: failure.diagnostics,
});
const retained = cleanup.retainFailure(
cause,
primary,
"inspect_apktool_client",
);
throw retained === primary ? failure : retained;
}
if (interpreted === undefined)
throw new ApktoolConfigurationFailure(
"version_unresolved",
"The owned version command completed without an output observation",
APKTOOL_VERSION_REMEDIATION,
{ selected_command: selection.command },
);
if (!interpreted.ok) throw interpreted.error;
return interpreted.value;
};
const interpretApktoolVersion = (
stdout: string,
stderr: string,
selection: ApktoolCommandSelection,
platform: NodeJS.Platform,
): ApktoolClientIdentity => {
const identity = parseApktoolVersionOutput(stdout, platform);
if (identity.version === null)
throw new ApktoolConfigurationFailure(
"version_unresolved",
"The selected apktool launcher exited successfully but did not report a recognizable version",
APKTOOL_VERSION_REMEDIATION,
{
selected_command: selection.command,
command_source: selection.commandSource,
version_probe: "unrecognized_output",
reported_version: identity.reportedVersion,
stdout,
stderr,
},
);
if (!identity.supportsDocumentedVersion)
throw new ApktoolConfigurationFailure(
"unsupported_version",
`The selected Apktool version ${identity.version} is older than the supported minimum 2.7.0`,
`Use Apktool 2.7.0 or newer; see docs/guides/android/apktool-resource-analysis.md.`,
{
selected_command: selection.command,
command_source: selection.commandSource,
reported_version: identity.version,
minimum_version: "2.7.0",
},
);
return identity;
};
/** Availability in the shape shared by every provider. */
const rejectionCodeOf = (
code: ApktoolConfigurationFailureCode,
): ProviderRejectionCode =>
code === "command_missing"
? "executable_missing"
: code === "command_not_executable" ||
code === "not_absolute" ||
code === "launcher_unsupported" ||
code === "command_unresolved"
? "not_configured"
: code === "unsupported_version"
? "unsupported_version"
: "version_unresolved";
export const apktoolConfigurationAvailability = (
cause: ApktoolConfigurationFailure,
): ProviderAvailability => ({
status: "unavailable",
code: rejectionCodeOf(cause.code),
reason: cause.message,
remediation: cause.remediation,
diagnostics: { ...cause.diagnostics },
});
/** Interpret the command owner's outcome, without inferring a new failure from a late signal. */
const versionProbeFailure = (
cause: unknown,
selection: ApktoolCommandSelection,
observed: ApktoolClientIdentity | undefined,
): AnalysisError | ApktoolConfigurationFailure => {
if (cause instanceof AnalysisError) return cause;
const preparation = processInspectionFailure(cause);
const output = capturedApktoolFailureOutput(cause);
const inspectionCancellation =
!(cause instanceof OwnedCommandFailure) ||
cause.preparationFailure !== undefined
? processInspectionCancellationError(cause, "inspect_apktool_client")
: undefined;
if (
cause instanceof OwnedCommandFailure &&
cause.reason === "cancelled" &&
cause.cancellation !== undefined
)
return (
inspectionCancellation ??
cancelledBy(
"inspect_apktool_client",
carriedReason(cause.cancellation.reason),
{
...(output === undefined ? {} : { capturedOutput: output }),
...(observed === undefined
? {}
: { diagnostics: { client: { version: observed.version } } }),
},
)
);
if (inspectionCancellation !== undefined) return inspectionCancellation;
if (
preparation !== undefined &&
!(cause instanceof OwnedCommandFailure && cause.reason === "timeout")
)
return new ProviderAdapterError("apktool", "inspect_apktool_client", {
cause,
diagnostics: {
stage: "ownership_preparation",
...(!(preparation instanceof DarwinProcessOwnershipInspectionError) ||
preparation.compilerOutcome === undefined
? {}
: {
compiler_outcome: jsonValueSchema.parse(
preparation.compilerOutcome,
),
}),
},
...(!(preparation instanceof DarwinProcessOwnershipInspectionError) ||
preparation.capturedOutput === undefined
? {}
: { capturedOutput: preparation.capturedOutput }),
});
if (cause instanceof OwnedCommandFailure && cause.reason === "timeout")
return new AnalysisTimeoutError(
"inspect_apktool_client",
VERSION_TIMEOUT_MS,
{
cause,
...(output === undefined ? {} : { capturedOutput: output }),
...apktoolVersionProbeTimeoutGuidance(),
},
);
const refusal = classifyLaunchFailure(cause);
if (refusal !== undefined) {
const execDenied = refusal.kind === "not_executable";
return new ApktoolConfigurationFailure(
execDenied ? "command_not_executable" : "command_missing",
execDenied
? `Execution of the selected apktool launcher was denied: ${selection.command}`
: `The selected apktool launcher was not found: ${selection.command}`,
execDenied
? APKTOOL_NOT_EXECUTABLE_REMEDIATION
: APKTOOL_MISSING_REMEDIATION,
{
filesystem_error: refusal.code,
selected_command: selection.command,
command_source: selection.commandSource,
},
{ cause },
);
}
const snapshot = cause instanceof OwnedCommandFailure ? cause.snapshot : null;
if (cause instanceof OwnedCommandFailure && cause.reason === "output-limit")
return new AnalysisResourceConstraintError(
"inspect_apktool_client",
"memory",
`apktool version output exceeded the ${String(VERSION_MAX_OUTPUT_BYTES)}-byte capture budget`,
{ max_output_bytes: VERSION_MAX_OUTPUT_BYTES },
{
cause,
diagnostics: {
selected_command: selection.command,
command_source: selection.commandSource,
},
...(output === undefined ? {} : { capturedOutput: output }),
...fixedAllowanceOptions(
`The apktool version-output capture allowance of ${String(VERSION_MAX_OUTPUT_BYTES)} bytes (this release has no runtime override; decode_timeout_ms does not raise it)`,
"capture",
),
},
);
return new ApktoolConfigurationFailure(
"version_unresolved",
"The selected apktool launcher did not report a usable version",
APKTOOL_VERSION_REMEDIATION,
{
selected_command: selection.command,
...(observed === undefined
? {}
: { client: { version: observed.version } }),
...(snapshot === null
? {}
: {
exit_code: snapshot.exitCode ?? null,
stderr_excerpt: snapshot.stderr.text.slice(0, 512),
}),
},
{ cause },
);
};