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
This commit is contained in:
morluto authored and GitHub committed 2026-11-14 21:11:59 -05:00
1 parent 47925f3bef
commit 44fedc8fdd
13 files changed
+622 -51

No files matched your search

+15 -9
View File
@@ -6,6 +6,7 @@ import {
} from "./ProcessInspectionCleanup.js";
import { assertProcessOwnershipInspectionActive } from "./ProcessInspectionCancellation.js";
import { ProcessAdmissionError } from "./ProcessAdmissionError.js";
import { nameSpawnedExecutable } from "./launchFailure.js";
import { spawn, type ChildProcess } from "node:child_process";
import type { EventEmitter } from "node:events";
import type { Readable, Writable } from "node:stream";
@@ -331,15 +332,20 @@ export const spawnOwnedProviderProcess = async (
}
if (options.memoryLimitBytes !== undefined)
throw new ProcessAdmissionError("memory_limit_unsupported");
const child = spawn(options.command, [...options.arguments], {
shell: false,
windowsHide: true,
stdio: [options.stdin ?? "ignore", "pipe", "pipe"],
detached: platform !== "win32",
windowsVerbatimArguments: options.windowsVerbatimArguments ?? false,
env: environment,
...(options.cwd === undefined ? {} : { cwd: options.cwd }),
});
let child: ChildProcess;
try {
child = spawn(options.command, [...options.arguments], {
shell: false,
windowsHide: true,
stdio: [options.stdin ?? "ignore", "pipe", "pipe"],
detached: platform !== "win32",
windowsVerbatimArguments: options.windowsVerbatimArguments ?? false,
env: environment,
...(options.cwd === undefined ? {} : { cwd: options.cwd }),
});
} catch (cause: unknown) {
throw nameSpawnedExecutable(cause, options.command);
}
await waitForSpawn(child);
const pid = child.pid;
if (pid === undefined)
+79
View File
@@ -0,0 +1,79 @@
import { expect, it } from "vitest";
import {
classifyLaunchFailure,
classifyLaunchFailureCode,
executableLaunchRefusalOf,
} from "./launchFailure.js";
it.each([
["ENOENT", "missing"],
["ENOTDIR", "missing"],
["ELOOP", "missing"],
["ENAMETOOLONG", "missing"],
["EACCES", "not_executable"],
["EPERM", "not_executable"],
["ENOEXEC", "not_executable"],
["EISDIR", "not_executable"],
])("classifies spawn %s as %s", (code, kind) => {
expect(classifyLaunchFailureCode(code)).toEqual({ kind, code });
expect(
classifyLaunchFailure(Object.assign(new Error(code), { code })),
).toEqual({ kind, code });
});
it.each([["EAGAIN"], ["EMFILE"], ["ETIMEDOUT"], [1], [null], ["toString"]])(
"leaves %j unclassified",
(code) => {
expect(classifyLaunchFailureCode(code)).toBeUndefined();
},
);
it.each([
[
"Node spawn",
{ code: "ENOENT", syscall: "spawn /tool", path: "/tool" },
{ kind: "missing", code: "ENOENT", executable: "/tool" },
],
[
"Windows native launcher",
{
code: "EACCES",
constraint: "Create process atomically inside owned Job Object failed",
requestedPath: "C:\\tools\\tool.exe",
},
{
kind: "not_executable",
code: "EACCES",
executable: "C:\\tools\\tool.exe",
},
],
])("names the executable a %s refusal identifies", (_, fields, expected) => {
expect(
executableLaunchRefusalOf(Object.assign(new Error("refused"), fields)),
).toEqual(expected);
});
it.each([
["an errno without a launcher", { code: "EPERM" }],
[
"a spawn syscall naming another path",
{ code: "ENOENT", syscall: "spawn /other", path: "/tool" },
],
[
"a Windows host-control rejection",
{
code: "EACCES",
constraint: "Create owned Job Object failed",
requestedPath: "C:\\tools\\tool.exe",
},
],
[
"a launcher error whose errno is not a refusal",
{ code: "EAGAIN", syscall: "spawn /tool", path: "/tool" },
],
])("does not read %s as an executable refusal", (_, fields) => {
expect(
executableLaunchRefusalOf(Object.assign(new Error("refused"), fields)),
).toBeUndefined();
});
+99
View File
@@ -0,0 +1,99 @@
import { windowsExecutableLaunchPath } from "../windows/WindowsOwnedProcess.js";
/**
* Why the operating system refused to start a selected executable.
*
* `missing`: nothing runnable resolves at the selected path.
* `not_executable`: something exists there but may not be run, including a
* refusal by an operating-system security policy (EPERM).
*/
export interface LaunchRefusal {
readonly kind: "missing" | "not_executable";
readonly code: string;
}
const LAUNCH_REFUSALS: Readonly<Record<string, LaunchRefusal["kind"]>> = {
ENOENT: "missing",
ENOTDIR: "missing",
ELOOP: "missing",
ENAMETOOLONG: "missing",
EACCES: "not_executable",
EPERM: "not_executable",
ENOEXEC: "not_executable",
EISDIR: "not_executable",
};
/** Classify a spawn errno; undefined when it is not a launch refusal. */
export const classifyLaunchFailureCode = (
code: unknown,
): LaunchRefusal | undefined => {
if (typeof code !== "string" || !Object.hasOwn(LAUNCH_REFUSALS, code))
return undefined;
const kind = LAUNCH_REFUSALS[code];
return kind === undefined ? undefined : { kind, code };
};
/** Classify a spawn failure; undefined when it was not a launch refusal. */
export const classifyLaunchFailure = (
cause: unknown,
): LaunchRefusal | undefined =>
cause instanceof Error && "code" in cause
? classifyLaunchFailureCode(cause.code)
: undefined;
/**
* Name the executable on an errno Node threw synchronously from `spawn`.
* Node emits ENOENT and EACCES as `spawn <path>` with `path`, but throws
* other refusals such as ENOEXEC and ENOTDIR with a bare `spawn` syscall;
* the launcher that passed `command` gives them the emitted shape.
*/
export const nameSpawnedExecutable = (
cause: unknown,
command: string,
): unknown => {
if (
cause instanceof Error &&
Reflect.get(cause, "syscall") === "spawn" &&
Reflect.get(cause, "path") === undefined
) {
Reflect.set(cause, "syscall", `spawn ${command}`);
Reflect.set(cause, "path", command);
}
return cause;
};
/** A launch refusal together with the executable the launcher named. */
export interface ExecutableLaunchRefusal extends LaunchRefusal {
readonly executable: string;
}
/**
* The executable a launcher named when it failed to start it: Node's
* `spawn <path>` error or the Windows native launcher's executable-launch
* constraint. Undefined when the error does not identify a launch.
*/
const launchedExecutableOf = (cause: Error): string | undefined => {
const path = Reflect.get(cause, "path");
if (
typeof path === "string" &&
Reflect.get(cause, "syscall") === `spawn ${path}`
)
return path;
return windowsExecutableLaunchPath(cause);
};
/**
* Classify a failure to start a named executable. Undefined when the errno is
* not a launch refusal or the error does not identify the executable a
* launcher refused, such as an errno from reading a file or preparing
* ownership.
*/
export const executableLaunchRefusalOf = (
cause: unknown,
): ExecutableLaunchRefusal | undefined => {
if (!(cause instanceof Error)) return undefined;
const executable = launchedExecutableOf(cause);
if (executable === undefined) return undefined;
const refusal = classifyLaunchFailure(cause);
return refusal === undefined ? undefined : { ...refusal, executable };
};