refactor(process): give POSIX PATH search order one owner (#10891)

* refactor(process): give POSIX PATH search order one owner

Program lookup, the packet-tool locator and Jadx's Java lookup each split
PATH and resolved empty and relative entries themselves. They now take the
candidates from posixPathCandidates in src/process/executableSearch and keep
only their own probe and failure reporting. A counted architecture guard
keeps new PATH splits from returning; the remaining Windows and Ghidra
searches are baselined.

* refactor(process): move the colon-split PATH searches onto the search owner

REA's launcher-alias lookup and Ghidra's macOS Java lookup split PATH on
":" and skipped relative entries themselves; they now use
posixPathCandidates with relativeEntries: "skip", and the guard counts
colon splits of PATH as well.

* fix(process): produce PATH candidates lazily so an unused entry cannot fail an earlier match

* refactor(process): give Windows PATH/PATHEXT search order the executable search owner (#10916)

* refactor(process): give Windows PATH/PATHEXT search order the executable search owner

* fix(process): keep later PATH entries searchable after a stray quote or a removed working directory

* fix(reverse): refuse a Windows objdump or Rizin command that PATH does not find (#10953)

* fix(reverse): refuse an objdump or Rizin command Windows PATH does not find instead of launching the bare name

* fix(reverse): report a Windows lookup refusal after cancellation and to capability discovery

* fix(desktop): search a Windows host's PATH as Windows does when doctor looks up a program

programOnPath sent every host through the POSIX PATH search, so on Windows a
relative PATH entry reached absoluteCallerPath with platform linux and the
Windows working directory, which resolved against itself until the stack
overflowed. programOnPath now searches PATH and PATHEXT through
windowsPathCandidates on a Windows host, and absoluteCallerPath refuses a
non-POSIX working directory with a TypeError instead of recursing.
This commit is contained in:
morluto authored and GitHub committed 2026-11-15 18:24:04 +08:00
1 parent 659772952d
commit 422cff00ab
23 files changed
+912 -330

No files matched your search

@@ -10,7 +10,7 @@ import {
javaScriptRuntime,
type JavaScriptRuntime,
} from "../domain/runtimeVersion.js";
import { absoluteCallerPath } from "../filesystem/callerPath.js";
import { posixPathCandidates } from "../process/executableSearch.js";
import { PRODUCT_IDENTITY } from "../identity.js";
/** Package runners recognized for invocation guidance and legacy registrations. */
@@ -166,9 +166,11 @@ const sameFileExecutableAlias = (
environment: Readonly<NodeJS.ProcessEnv>,
identify: typeof entrypointIdentity,
): string => {
for (const directory of (environment.PATH ?? "").split(":")) {
if (!isAbsolute(directory)) continue;
const candidate = absoluteCallerPath(`${directory}/${name}`);
for (const { path: candidate } of posixPathCandidates(
name,
environment.PATH ?? "",
{ relativeEntries: "skip" },
)) {
if (identify(candidate, selected) !== "owned") continue;
try {
accessSync(candidate, constants.X_OK);
@@ -1,4 +1,5 @@
import type { EvidenceProvider } from "../../domain/evidence.js";
import type { Result } from "../../domain/result.js";
import type {
ObjdumpSelection,
RizinInput,
@@ -19,8 +20,27 @@ export interface ReverseEngineeringProviderCommand {
readonly environmentOverrides?: Readonly<NodeJS.ProcessEnv>;
}
/**
* A configured bare command the host search did not find, so nothing is
* launched: handing Windows the bare name would also search the current
* directory.
*/
export interface ReverseEngineeringCommandUnavailable {
readonly identity: EvidenceProvider;
/** The command as configured. */
readonly command: string;
readonly reason:
| { readonly kind: "not_found" }
| { readonly kind: "invalid_pathext"; readonly extension: string };
}
export type ReverseEngineeringCommandSelection = Result<
ReverseEngineeringProviderCommand,
ReverseEngineeringCommandUnavailable
>;
/** Provider-specific command construction stays outside the application layer. */
export interface ReverseEngineeringCommandPort {
objdump(input: ObjdumpSelection): ReverseEngineeringProviderCommand;
rizin(input: RizinInput): ReverseEngineeringProviderCommand;
objdump(input: ObjdumpSelection): ReverseEngineeringCommandSelection;
rizin(input: RizinInput): ReverseEngineeringCommandSelection;
}
@@ -49,6 +49,8 @@ import {
} from "../../domain/reverseEngineering.js";
import type {
ReverseEngineeringCommandPort,
ReverseEngineeringCommandSelection,
ReverseEngineeringCommandUnavailable,
ReverseEngineeringProviderCommand,
} from "./ReverseEngineeringCommandPort.js";
import {
@@ -172,6 +174,51 @@ interface ReverseCommandObservation {
readonly outputBudgetBytes: number;
}
/** The provider a reverse command runs and how a caller repairs its command. */
const reverseCommandRepair = (
operation: ReverseEngineeringOperation,
): { readonly provider: string; readonly remediationAction: string } => {
const objdump = operation === "inspect_with_objdump";
return {
provider: objdump ? "objdump" : "rizin",
remediationAction: `Set ${objdump ? "REA_OBJDUMP_COMMAND" : "REA_RIZIN_COMMAND"} to an installed executable ${objdump ? "GNU objdump" : "Rizin"} command, or make that command available on PATH. Check execute permission on the command and search permission on its parent directories before retrying.`,
};
};
/** A configured command the host search did not find; nothing was launched. */
const reverseCommandUnavailable = (
operation: ReverseEngineeringOperation,
unavailable: ReverseEngineeringCommandUnavailable,
): AnalysisCapabilityUnavailableError => {
const { provider, remediationAction } = reverseCommandRepair(operation);
const { command, reason } = unavailable;
return new AnalysisCapabilityUnavailableError(
unavailable.identity.id,
operation,
reason.kind === "not_found"
? "Configured command was not found on PATH"
: `Configured command could not be searched on PATH (invalid PATHEXT entry ${JSON.stringify(reason.extension)})`,
{
userMessage:
reason.kind === "not_found"
? `Could not find the selected ${provider} command ${JSON.stringify(command)} on PATH; REA did not search the current directory.`
: `Could not search PATH for the selected ${provider} command ${JSON.stringify(command)}: PATHEXT entry ${JSON.stringify(reason.extension)} is not a filename extension.`,
remediationAction:
reason.kind === "not_found"
? remediationAction
: `Remove ${JSON.stringify(reason.extension)} from PATHEXT, or ${remediationAction.charAt(0).toLowerCase()}${remediationAction.slice(1)}`,
diagnostics: {
boundary: "provider-lookup",
command,
lookup_failure: reason.kind,
...(reason.kind === "invalid_pathext"
? { pathext_entry: reason.extension }
: {}),
},
},
);
};
/** Shared application workflow for caller-selected local analysis commands. */
export class ReverseEngineeringService {
readonly #environment: Readonly<NodeJS.ProcessEnv>;
@@ -286,6 +333,29 @@ export class ReverseEngineeringService {
return created;
}
/**
* Record that this dispatch could not run the configured command, unless a
* later dispatch has already succeeded or failed.
*/
#recordUnavailable(
operation: ReverseEngineeringOperation,
dispatch: number,
failure: AnalysisCapabilityUnavailableError,
): void {
const outcome = this.#outcome(operation);
if (
(outcome.failure === undefined || dispatch > outcome.failure.dispatch) &&
dispatch > outcome.succeeded
)
outcome.failure = {
dispatch,
reason: failure.userMessage ?? failure.message,
remediation:
failure.remediationAction ??
reverseCommandRepair(operation).remediationAction,
};
}
/** Current launch failures observed for caller-configured standalone tools. */
observedLaunchFailures(): CommandProviderLaunchFailures {
const result: Partial<
@@ -358,7 +428,7 @@ export class ReverseEngineeringService {
);
if (!ready.ok) return ready;
}
const command = this.#commands.objdump(input);
const selection = this.#commands.objdump(input);
let parameters: Readonly<Record<string, JsonValue>>;
if (input.operation === "disassemble") {
const { symbol, ...base } = input;
@@ -370,7 +440,7 @@ export class ReverseEngineeringService {
parameters = { ...parameters, max_output_bytes: maxOutputBytes };
const observed = await this.#observe({
operation: "inspect_with_objdump",
profile: command,
selection,
path: input.operation === "architectures" ? undefined : input.path,
parameters,
signal: options.signal,
@@ -402,10 +472,9 @@ export class ReverseEngineeringService {
max_output_bytes: maxOutputBytes,
...input
} = request;
const command = this.#commands.rizin(input);
return this.#observe({
operation: "execute_rizin_command",
profile: command,
selection: this.#commands.rizin(input),
path: input.path,
parameters: request,
signal: options.signal,
@@ -414,9 +483,12 @@ export class ReverseEngineeringService {
});
}
#observe(
request: ReverseCommandObservation,
): Promise<Result<Evidence, AnalysisError>> {
#observe({
selection,
...request
}: Omit<ReverseCommandObservation, "profile"> & {
readonly selection: ReverseEngineeringCommandSelection;
}): Promise<Result<Evidence, AnalysisError>> {
const { operation, signal, outputBudgetBytes } = request;
if (signal?.aborted)
return Promise.resolve(
@@ -431,6 +503,13 @@ export class ReverseEngineeringService {
),
),
);
// A command the host search did not find is this dispatch's outcome:
// discovery reports it like a launch failure until a later success.
if (!selection.ok) {
const refusal = reverseCommandUnavailable(operation, selection.error);
this.#recordUnavailable(operation, ++this.#dispatched, refusal);
return Promise.resolve(err(refusal));
}
if (
this.#activeOperations.size >=
MAX_CONCURRENT_REVERSE_ENGINEERING_OPERATIONS ||
@@ -470,6 +549,7 @@ export class ReverseEngineeringService {
this.#reservedOutputBytes += outputBudgetBytes;
const running = this.#observeProvider({
...request,
profile: selection.value,
signal: operationSignal,
});
const tracked = running
@@ -902,12 +982,8 @@ export class ReverseEngineeringService {
...reverseCommandTimeoutGuidance(timeoutMs),
});
else {
const provider =
operation === "inspect_with_objdump" ? "objdump" : "rizin";
const setting =
provider === "objdump"
? "REA_OBJDUMP_COMMAND"
: "REA_RIZIN_COMMAND";
const { provider, remediationAction } =
reverseCommandRepair(operation);
earlyFailure = new AnalysisCapabilityUnavailableError(
profile.identity.id,
operation,
@@ -915,7 +991,7 @@ export class ReverseEngineeringService {
{
cause,
userMessage: `Could not launch the selected ${provider} executable ${JSON.stringify(command)} (${String(code ?? "unknown error")}).`,
remediationAction: `Set ${setting} to an installed executable ${provider === "objdump" ? "GNU objdump" : "Rizin"} command, or make that command available on PATH. Check execute permission on the command and search permission on its parent directories before retrying.`,
remediationAction,
diagnostics: {
boundary: "provider-launch",
command,
@@ -1018,20 +1094,7 @@ export class ReverseEngineeringService {
earlyFailure.diagnostics?.boundary === "provider-launch" &&
earlyFailure.providerId === profile.identity.id
) {
const outcome = this.#outcome(operation);
if (
(outcome.failure === undefined ||
dispatch > outcome.failure.dispatch) &&
dispatch > outcome.succeeded
) {
outcome.failure = {
dispatch,
reason: earlyFailure.userMessage ?? earlyFailure.message,
remediation:
earlyFailure.remediationAction ??
`Set ${operation === "inspect_with_objdump" ? "REA_OBJDUMP_COMMAND" : "REA_RIZIN_COMMAND"} to an installed executable command.`,
};
}
this.#recordUnavailable(operation, dispatch, earlyFailure);
}
return err(this.#registerCleanupFailure(earlyFailure, cleanupOwner));
}