mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 19:53:50 +00:00
* refactor(browser): take the host in Chromium, Electron and capture adapters chromiumSandboxEnabled and safeElectronEnvironment take a required platform. The scenario browser, native module resolver, Electron provider and capture cleanup, mitmproxy adapter and web script artifacts take an optional platform seam (default HOST_PLATFORM); Electron fuses read the host architecture from HOST_PLATFORM. Their tests inject the platform instead of redefining process.platform. src/browser no longer reads process.platform or process.arch. * refactor(pcap): take the host platform in the packet tools, native bound and batch launch (#11141) * refactor(pcap): take the host platform in the packet tools, native bound and batch launch * test(pcap): cover the selected host in batch launch and capture-host support * refactor(apktool): take the host platform in launcher selection, version probe and decode (#11164) * refactor(apktool): take the host platform in launcher selection, version probe and decode * test(apktool): cover the provider's selected host in launcher selection * refactor(hopper): give the launcher the provider's host platform * refactor(native): inject the host into the pwntools decoders and native capability defaults (#11173) * refactor(native): inject the host into the pwntools decoders and native capability defaults * fix(native): give composed pwntools services the capability host and drop empty test hooks * refactor(adb): take the host platform in binary selection and pulled file names (#11176) * refactor(adb): take the host platform in binary selection and pulled file names * refactor(cli): pass the resolved host platform through rea mcp add (#11179) * refactor(cli): pass the resolved host platform through rea mcp add * refactor(composition): default composition entry points to HOST_PLATFORM and pass it to Hopper and IDA (#11183) * refactor(kuna): require the host platform in admission and installation, and give it to the session client (#11186) * refactor(kuna): require the host platform in admission and installation, and give it to the session client * fix(kuna): pass the host platform from the JavaScript installation callers verify-real-kuna, both native oracle helpers and the command-lifetime child script call inspectKunaInstallation from dist, where TypeScript cannot see the now-required platform. They passed undefined and got unsupported_host on supported hosts. * refactor(server): give createServer a host option and pass it to session tools, sigrok and EVM (#11203) * refactor(server): give createServer a host option and pass it to session tools, sigrok and EVM createServer read process.platform and process.arch live for its capability services, and registerSessionTools read process.platform for process capture. A host option (default HOST_PLATFORM) now selects both, and composition passes the capability host to the sigrok provider and the EVM provider (execution gate, limiter probe and environment rules), as it does for pwntools. hostRestrictedAvailabilityMcp selects its host through the option instead of redefining process.platform and process.arch, and moves to the MCP boundary lane since it no longer touches process-global state. evmCleanupRetry passes SIMULATED_LINUX_X64 to the provider instead of 52 property redefinitions; the fixture moves to tests/fixtures/simulatedHost.ts. * refactor(desktop): require the host platform in build computer and secret folder paths (#11210) * refactor(desktop): require the host platform in build computer and secret folder paths buildComputerArchiveDirectory, defaultBuildComputerArchive, resolveBuildComputerEnvironment and buildSecretsDirectory defaulted to process.platform. Every caller but DesktopBuildComputers' secret folder already passed the platform; it now passes HOST_PLATFORM.platform, which it reads for the build environment. * refactor(filesystem): default caller paths and ChangeTime settling to HOST_PLATFORM (#11212) appendCallerPath, absoluteCallerPath and the ChangeTime settle seams defaulted to a live process.platform read. Their defaults now come from HOST_PLATFORM: the 59 callers that omit the platform join or settle paths they open on this host, and callers describing another host's layout already pass it. The webScriptExport case that redefined process.platform to reach the Windows settle budget moves to its own file, which selects Windows by mocking HostPlatform. * fix(server): report process capture availability for the server's host sessionAvailabilityPolicy imported platform from node:process, so with a selected host binary_session reported capture_process_scenario from the running host while planning and capture used the selected one. It takes the platform from createServer and registerSessionTools. hostRestrictedAvailabilityMcp checks discovery against a dry-run plan on win32 and linux hosts. * build(guards): count platform and arch imports from node:process and node:os as ambient host reads sessionAvailabilityPolicy's named import of platform from node:process escaped the ambient-host-platform guard. The guards now also match named platform/arch imports from node:process or node:os and os.platform()/os.arch(). The one other site, DesktopApplicationCapture's os.arch(), records the capturing host and now reads HOST_PLATFORM.architecture. * refactor(config): take the host platform in parseConfig and give debugger managers the capability host (#11237) * refactor(config): take the host platform in parseConfig and give debugger managers the capability host parseConfig read process.platform for the default Hopper launcher; it takes the platform (default HOST_PLATFORM). GdbSessionManager and RizinDebugSessionManager default their platform to HOST_PLATFORM, and composition passes the capability host that already decides their availability. GDB's /proc descriptor check reads HOST_PLATFORM explicitly: it inspects this host's /proc whatever host the manager models. * refactor(firmware): give the firmware and Wakaru providers the capability host (#11239) * refactor(firmware): give the firmware and Wakaru providers the capability host resolveFirmwareCommand and resolveWakaruCommand read process.platform (and process.arch) for their host gate. They take the platform or host as a parameter; FirmwareProvider and WakaruProvider take a host (default HOST_PLATFORM) for the gate and their environment snapshots, and composition passes the capability host that already decides their availability. The JavaScript analysis source transfer defaults to HOST_PLATFORM. artifactSelectedCommand passes SIMULATED_LINUX_X64 to both providers instead of redefining process.platform and process.arch, and the Wakaru limiter configuration cases now run on any POSIX host. * refactor(captures): give tshark the capability host and default Cutter to HOST_PLATFORM (#11240) * refactor(captures): give tshark the capability host and default Cutter to HOST_PLATFORM TsharkCaptureProvider and CutterBridgeClient defaulted their platform to process.platform. Both default to HOST_PLATFORM now, and composition passes the capability host to the packet capture service, which already decides its availability. * refactor(platform): read HOST_PLATFORM explicitly in host-only path checks (#11241) * refactor(platform): read HOST_PLATFORM explicitly in host-only path checks Electron's readlink target split, IDA's host path comparison, the inspector's reported runtime path, the server identity check and WABT's executable names all describe paths on the running host. They read HOST_PLATFORM instead of process.platform. * test(native): select the native UI verifier's host through HostPlatform (#11242) verify-native-ui.mjs reads its macOS requirement from HOST_PLATFORM, and its action test resolves the script's HostPlatform import to a simulated darwin host instead of redefining process.platform in the child preload. Simulating linux there fails the macOS requirement, so the redirect is effective. * test(mcp): check that composition forwards the selected host to execution hostRestrictedAvailabilityMcp ran execution only on darwin, where the runner's own host also refuses. The new case calls the firmware, Wakaru, tshark, sigrok and EVM tools under a darwin and a linux x64 host and requires different outcomes, so dropping a provider's host forwarding fails on any runner (checked by removing the firmware forwarding). * fix(composition): give the pcap, Apktool and ADB providers the capability host createServer's selected host decided pcap capture discovery, but the default pcap, Apktool and ADB factories built their providers with HOST_PLATFORM. The factories take the platform (default HOST_PLATFORM) and capabilityServices passes its context platform, so availability and execution follow one host. * test: import moved resources owners in host-platform fixtures * refactor(config): drop the unused host parameter from parseConfig
881 lines
30 KiB
JavaScript
881 lines
30 KiB
JavaScript
#!/usr/bin/env node
|
|
// Real Kuna provider lane. Requires a caller-supplied kuna (REA_KUNA_COMMAND)
|
|
// and a host C compiler; REA installs neither. The default run builds a
|
|
// source-owned fixture, with symbols and stripped, and verifies the public MCP
|
|
// workflow: cold single-function pseudocode, the project export, warm reuse
|
|
// from a fresh server, and cleanup. `--targets DIR --functions a,b` adds
|
|
// caller-built binaries (DIR/<flavor>/<name> plus <name>.stripped).
|
|
// `--compare-ghidra` runs the same functions through a bring-your-own Ghidra
|
|
// and reports latency, CPU, memory, output size and simple quality signals.
|
|
import assert from "node:assert/strict";
|
|
import { execFile } from "node:child_process";
|
|
import { createHash } from "node:crypto";
|
|
import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
|
|
import { join, resolve } from "node:path";
|
|
import { fileURLToPath } from "node:url";
|
|
import { parseArgs, promisify } from "node:util";
|
|
import { Client } from "@modelcontextprotocol/client";
|
|
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
|
|
import { inspectKunaInstallation } from "../dist/kuna/KunaInstallation.js";
|
|
import { HOST_PLATFORM } from "../dist/platform/HostPlatform.js";
|
|
import {
|
|
KUNA_RELEASE_VERIFICATION_EXPLANATION,
|
|
KUNA_UNVERIFIED_VERSION_REMEDIATION,
|
|
KUNA_VERIFIED_VERSION,
|
|
} from "../dist/kuna/KunaRelease.js";
|
|
import { ArtifactResourceScope } from "../dist/resources/ArtifactResourceScope.js";
|
|
import { AnalysisCleanupLease } from "../dist/resources/AnalysisCleanupLease.js";
|
|
import {
|
|
KUNA_XREF_MISSING_NAME_REMEDIATION,
|
|
missingKunaXrefNameMessage,
|
|
} from "../dist/kuna/KunaSelectorGuidance.js";
|
|
import {
|
|
requireMcpOperationResult,
|
|
requireMcpToolError,
|
|
} from "./lib/mcp-verifier-results.mjs";
|
|
import { verifyKunaReferences } from "./lib/kuna-reference-verifier.mjs";
|
|
import {
|
|
nativeKunaStrings,
|
|
verifyKunaStrings,
|
|
} from "./lib/kuna-string-verifier.mjs";
|
|
import { nativeKunaIncomingSites } from "./lib/kuna-native-reference-verifier.mjs";
|
|
import {
|
|
assertVerifierCleanupComplete,
|
|
completeVerifierRun,
|
|
createVerifierRun,
|
|
} from "./lib/verifier-run.mjs";
|
|
import { VerifierFixture } from "./lib/verifier-fixture.mjs";
|
|
|
|
const exec = promisify(execFile);
|
|
const { values } = parseArgs({
|
|
options: {
|
|
targets: { type: "string" },
|
|
functions: { type: "string" },
|
|
"compare-ghidra": { type: "boolean", default: false },
|
|
report: { type: "string" },
|
|
entrypoint: { type: "string" },
|
|
},
|
|
});
|
|
const entrypoint =
|
|
values.entrypoint === undefined
|
|
? fileURLToPath(new URL("./rea.mjs", import.meta.url))
|
|
: resolve(values.entrypoint);
|
|
const kuna = process.env.REA_KUNA_COMMAND;
|
|
assert.ok(
|
|
kuna !== undefined && kuna.startsWith("/"),
|
|
"Kuna lane prerequisite missing: REA_KUNA_COMMAND must name a caller-supplied kuna by absolute path (bring your own)",
|
|
);
|
|
if (values["compare-ghidra"]) {
|
|
// The comparison runs on caller-built targets only; the fixture has none.
|
|
assert.ok(
|
|
values.targets !== undefined && values.functions !== undefined,
|
|
"--compare-ghidra compares caller-built targets: pass --targets DIR --functions a,b as well",
|
|
);
|
|
assert.ok(
|
|
process.env.GHIDRA_INSTALL_DIR,
|
|
"Ghidra comparison prerequisite missing: GHIDRA_INSTALL_DIR (bring your own Ghidra 12.1.4 and JDK 21)",
|
|
);
|
|
}
|
|
const run = createVerifierRun();
|
|
const inspectionResources = new ArtifactResourceScope();
|
|
const resourceScope = {
|
|
retain: (owner, resource) =>
|
|
inspectionResources.retain({
|
|
kind: "lease",
|
|
resource,
|
|
lease: AnalysisCleanupLease.forCloseOwner(owner, resource),
|
|
}),
|
|
run: (operation) => inspectionResources.run(operation),
|
|
};
|
|
// Kuna children cache under the root; a plain root admits them on every host.
|
|
const workspaceFixture = await VerifierFixture.open({
|
|
prefix: "rea-kuna-lane-",
|
|
private: false,
|
|
});
|
|
const workspace = workspaceFixture.path;
|
|
const cacheRoot = join(workspace, "cache");
|
|
// A server retains its workspace until both provider and transport cleanup
|
|
// have positively completed, even if later lineage observation is empty.
|
|
const pendingServers = new Set();
|
|
// Unproven native-oracle stops retain their supervisors and this workspace.
|
|
const retainedNative = new Set();
|
|
let kunaVersion;
|
|
|
|
const FIXTURE_SOURCE = String.raw`
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
static const char rea_kuna_utf8[] __attribute__((used)) = "_φ( °-°)/ REA unicode marker";
|
|
/* The leading NUL unit ends any UTF-16 run that bytes before this array would
|
|
start: the UTF-8 marker's last byte and NUL decode as the unit 'r', so on
|
|
layouts where it precedes this array Kuna reports "rREA wide marker". */
|
|
static const unsigned short rea_kuna_wide[] __attribute__((used)) = {
|
|
0,'R','E','A',' ','w','i','d','e',' ','m','a','r','k','e','r',0
|
|
};
|
|
#include <string.h>
|
|
__attribute__((noinline)) unsigned rea_checksum(const unsigned char *p, size_t n) {
|
|
unsigned h = 2166136261u;
|
|
for (size_t i = 0; i < n; i++) h = (h ^ p[i]) * 16777619u;
|
|
return h;
|
|
}
|
|
__attribute__((noinline)) int rea_classify(int c) {
|
|
switch (c) {
|
|
case 'a': return 1; case 'e': return 2; case 'i': return 3;
|
|
case 'o': return 4; case 'u': return 5; default: return c > 'z' ? -1 : 0;
|
|
}
|
|
}
|
|
int main(int argc, char **argv) {
|
|
if (argc < 2) return 2;
|
|
size_t length = strlen(argv[1]);
|
|
printf("%u %u %d\n", rea_checksum((const unsigned char *)argv[1], length),
|
|
rea_checksum((const unsigned char *)argv[1], length ? length - 1 : 0),
|
|
rea_classify(argv[1][0]));
|
|
return 0;
|
|
}
|
|
`;
|
|
|
|
/** Resolve function entry addresses from a symbol-bearing build. */
|
|
const symbolAddresses = async (binary, names) => {
|
|
const { stdout } = await exec(process.env.REA_NM ?? "nm", [binary]);
|
|
const found = new Map();
|
|
for (const line of stdout.split("\n")) {
|
|
const [address, type, symbol] = line.trim().split(/\s+/u);
|
|
if (symbol === undefined || !/^[tT]$/u.test(type ?? "")) continue;
|
|
const plain = symbol.startsWith("_") ? symbol.slice(1) : symbol;
|
|
for (const name of names)
|
|
if ((symbol === name || plain === name) && !found.has(name))
|
|
found.set(name, `0x${BigInt(`0x${address}`).toString(16)}`);
|
|
}
|
|
return found;
|
|
};
|
|
|
|
/** Sum the resident memory and CPU time of a process and its descendants. */
|
|
const sampleTree = async (root) => {
|
|
const { stdout } = await exec("ps", ["-A", "-o", "pid=,ppid=,rss=,time="]);
|
|
const rows = stdout
|
|
.trim()
|
|
.split("\n")
|
|
.map((line) => line.trim().split(/\s+/u))
|
|
.map(([pid, ppid, rss, time]) => ({
|
|
pid: Number(pid),
|
|
ppid: Number(ppid),
|
|
rssKiB: Number(rss),
|
|
cpuSeconds: (time ?? "0:0")
|
|
.split(/[:-]/u)
|
|
.map(Number)
|
|
.reduce((total, part) => total * 60 + part, 0),
|
|
}));
|
|
const members = new Set([root]);
|
|
for (let grew = true; grew;) {
|
|
grew = false;
|
|
for (const row of rows)
|
|
if (!members.has(row.pid) && members.has(row.ppid)) {
|
|
members.add(row.pid);
|
|
grew = true;
|
|
}
|
|
}
|
|
const tree = rows.filter(({ pid }) => members.has(pid));
|
|
return {
|
|
rssKiB: tree.reduce((total, row) => total + row.rssKiB, 0),
|
|
cpu: new Map(tree.map((row) => [row.pid, row.cpuSeconds])),
|
|
};
|
|
};
|
|
|
|
/** One MCP server with a selected provider, sampled while it runs. */
|
|
const openServer = async (provider, kunaSettings = {}) => {
|
|
const owner = Symbol(provider.id);
|
|
pendingServers.add(owner);
|
|
const transport = new StdioClientTransport({
|
|
command: process.execPath,
|
|
args: [entrypoint, "--mcp"],
|
|
env: {
|
|
PATH: process.env.PATH ?? "/usr/bin:/bin",
|
|
HOME: process.env.HOME ?? workspace,
|
|
REA_LOG_LEVEL: "silent",
|
|
REA_PROCESS_RUN_ID: run.run_id,
|
|
REA_KUNA_COMMAND: kuna,
|
|
REA_KUNA_CACHE_DIR: cacheRoot,
|
|
...kunaSettings,
|
|
...(process.env.GHIDRA_INSTALL_DIR === undefined
|
|
? {}
|
|
: { GHIDRA_INSTALL_DIR: process.env.GHIDRA_INSTALL_DIR }),
|
|
...(process.env.JAVA_HOME === undefined
|
|
? {}
|
|
: { JAVA_HOME: process.env.JAVA_HOME }),
|
|
},
|
|
stderr: "ignore",
|
|
});
|
|
const client = new Client({ name: "rea-real-kuna", version: "1" });
|
|
let peakKiB = 0;
|
|
const cpu = new Map();
|
|
const sampleOnce = async () => {
|
|
const pid = transport.pid;
|
|
if (pid === null) return;
|
|
const observed = await sampleTree(pid).catch(() => undefined);
|
|
if (observed === undefined) return;
|
|
peakKiB = Math.max(peakKiB, observed.rssKiB);
|
|
for (const [member, seconds] of observed.cpu)
|
|
cpu.set(member, Math.max(cpu.get(member) ?? 0, seconds));
|
|
};
|
|
let sampling;
|
|
const sample = () => {
|
|
sampling ??= sampleOnce().finally(() => {
|
|
sampling = undefined;
|
|
});
|
|
return sampling;
|
|
};
|
|
let timer;
|
|
const call = async (name, arguments_ = {}) => {
|
|
const started = performance.now();
|
|
const result = await client.callTool(
|
|
{ name, arguments: arguments_ },
|
|
{ timeout: 3_600_000 },
|
|
);
|
|
const ms = Math.round(performance.now() - started);
|
|
const bytes = Buffer.byteLength(JSON.stringify(result));
|
|
return {
|
|
ms,
|
|
bytes,
|
|
value: requireMcpOperationResult(result, name),
|
|
structured: result.structuredContent,
|
|
};
|
|
};
|
|
const callError = async (name, arguments_ = {}) =>
|
|
requireMcpToolError(
|
|
await client.callTool(
|
|
{ name, arguments: arguments_ },
|
|
{ timeout: 3_600_000 },
|
|
),
|
|
);
|
|
const close = async (priorFailure) => {
|
|
clearInterval(timer);
|
|
await sample();
|
|
const failures = priorFailure === undefined ? [] : [priorFailure];
|
|
// Attempt each cleanup independently. Disposing a transport is not proof
|
|
// that close_binary released retained provider processes or files.
|
|
for (const cleanup of [
|
|
() => call("close_binary"),
|
|
() => client.close(),
|
|
() => transport.close(),
|
|
])
|
|
try {
|
|
await cleanup();
|
|
} catch (cause) {
|
|
failures.push(cause);
|
|
}
|
|
// A prior verification error must survive successful cleanup. Only the
|
|
// cleanup failures retain this server's files.
|
|
if (failures.length > (priorFailure === undefined ? 0 : 1))
|
|
throw new AggregateError(
|
|
failures,
|
|
"MCP server cleanup was not confirmed",
|
|
);
|
|
pendingServers.delete(owner);
|
|
if (priorFailure !== undefined) throw priorFailure;
|
|
return {
|
|
peak_rss_mib: Math.round(peakKiB / 1024),
|
|
cpu_seconds: [...cpu.values()].reduce((total, value) => total + value, 0),
|
|
};
|
|
};
|
|
try {
|
|
await client.connect(transport);
|
|
timer = setInterval(() => void sample(), 200);
|
|
await call("open_binary", {
|
|
path: provider.path,
|
|
provider_id: provider.id,
|
|
});
|
|
const session = (await call("binary_session")).value;
|
|
assert.equal(
|
|
session.analysis_provider_candidates_observed,
|
|
"target_selection",
|
|
);
|
|
if (provider.id === "kuna") {
|
|
const binding = session.analysis_provider_binding;
|
|
const verification = binding.release_verification;
|
|
assert.equal(verification.basis, "reported_version");
|
|
assert.equal(verification.verified_version, KUNA_VERIFIED_VERSION);
|
|
assert.equal(
|
|
verification.reported_version,
|
|
binding.analysis_profile.parameters.kuna_version,
|
|
);
|
|
assert.equal(
|
|
verification.status,
|
|
binding.analysis_profile.parameters.kuna_version ===
|
|
KUNA_VERIFIED_VERSION
|
|
? "verified"
|
|
: "unverified",
|
|
);
|
|
assert.equal(
|
|
verification.explanation,
|
|
KUNA_RELEASE_VERIFICATION_EXPLANATION,
|
|
);
|
|
if (verification.status === "unverified")
|
|
assert.equal(
|
|
verification.remediation,
|
|
KUNA_UNVERIFIED_VERSION_REMEDIATION,
|
|
);
|
|
else assert.equal(verification.remediation, null);
|
|
}
|
|
} catch (cause) {
|
|
// A rejected connection/target still owns its transport and workspace.
|
|
await close(cause);
|
|
}
|
|
return { call, callError, close };
|
|
};
|
|
|
|
/** Verify a forced inventory timeout can be retried without changing jobs. */
|
|
const verifyProjectTimeoutRecovery = async (path, address) => {
|
|
const before = createHash("sha256")
|
|
.update(await readFile(path))
|
|
.digest("hex");
|
|
const settings = {
|
|
REA_KUNA_JOBS: "2",
|
|
REA_KUNA_TIMEOUT_MS: "60000",
|
|
REA_KUNA_PROJECT_TIMEOUT_MS: "1",
|
|
};
|
|
const timed = await openServer({ path, id: "kuna" }, settings);
|
|
let timedFailure;
|
|
try {
|
|
const failure = await timed.callError("procedure_assembly", {
|
|
procedure: address,
|
|
});
|
|
assert.equal(failure.code, "capability_unavailable");
|
|
assert.match(failure.message, /kuna functions/u);
|
|
assert.match(failure.remediation.action, /REA_KUNA_PROJECT_TIMEOUT_MS/u);
|
|
assert.doesNotMatch(failure.remediation.action, /REA_KUNA_JOBS/u);
|
|
} catch (cause) {
|
|
timedFailure = cause;
|
|
} finally {
|
|
await timed.close(timedFailure);
|
|
}
|
|
const retry = await openServer(
|
|
{ path, id: "kuna" },
|
|
{ ...settings, REA_KUNA_PROJECT_TIMEOUT_MS: "60000" },
|
|
);
|
|
let retryFailure;
|
|
try {
|
|
const assembly = await retry.call("procedure_assembly", {
|
|
procedure: address,
|
|
});
|
|
assert.equal(typeof assembly.value, "string");
|
|
assert.ok(assembly.value.length > 0);
|
|
assert.equal(assembly.structured.analysis_profile.parameters.jobs, 2);
|
|
} catch (cause) {
|
|
retryFailure = cause;
|
|
} finally {
|
|
await retry.close(retryFailure);
|
|
}
|
|
assert.equal(
|
|
createHash("sha256")
|
|
.update(await readFile(path))
|
|
.digest("hex"),
|
|
before,
|
|
"Kuna timeout recovery changed the target",
|
|
);
|
|
return { forced_deadline_ms: 1, retry_deadline_ms: 60000, jobs: 2 };
|
|
};
|
|
|
|
/** Count structuring and diagnostic markers in provider pseudocode. */
|
|
const quality = (text) => ({
|
|
bytes: text === null ? 0 : Buffer.byteLength(text),
|
|
gotos: text === null ? 0 : (text.match(/\bgoto\b/gu) ?? []).length,
|
|
warnings:
|
|
text === null ? 0 : (text.match(/WARNING|\/\/ warn:/gu) ?? []).length,
|
|
});
|
|
|
|
/** Verify Kuna on one binary and measure its cold and warm answers. */
|
|
const verifyKuna = async (
|
|
path,
|
|
functions,
|
|
{
|
|
expectedCaller,
|
|
expectedStrings = [],
|
|
verifyNamedTrace = false,
|
|
minimumTraceReferences = {},
|
|
} = {},
|
|
) => {
|
|
const sha256 = createHash("sha256")
|
|
.update(await readFile(path))
|
|
.digest("hex");
|
|
const cold = await openServer({ path, id: "kuna" });
|
|
const answers = [];
|
|
let coldFailure;
|
|
try {
|
|
const status = await cold.call("binary_session", { detail: "complete" });
|
|
if (status.value.format === "elf") {
|
|
const availability = status.value.tool_availability;
|
|
const dispatch = availability.find(
|
|
({ name }) => name === "inspect_native_dispatch_metadata",
|
|
);
|
|
const trace = availability.find(
|
|
({ name }) => name === "trace_native_ui_action",
|
|
);
|
|
assert.equal(dispatch?.available, false);
|
|
assert.equal(
|
|
trace?.modes?.find(({ name }) => name === "native_seed_call_trace")
|
|
?.available,
|
|
false,
|
|
);
|
|
if (process.platform === "darwin") {
|
|
const { MULTI_MODE_REMEDIATION } =
|
|
await import("../dist/application/CapabilityInventory.js");
|
|
const authored = trace?.modes?.find(
|
|
({ name }) => name === "authored_ui_dispatch",
|
|
);
|
|
const nativeSeed = trace?.modes?.find(
|
|
({ name }) => name === "native_seed_call_trace",
|
|
);
|
|
assert.equal(trace?.remediation, MULTI_MODE_REMEDIATION);
|
|
assert.notEqual(authored?.remediation, nativeSeed?.remediation);
|
|
assert.ok(
|
|
authored?.missing_operations.includes("decode_interface_builder"),
|
|
);
|
|
assert.ok(nativeSeed?.missing_operations.includes("list_names"));
|
|
}
|
|
}
|
|
answers.push({
|
|
strings: await verifyKunaStrings({
|
|
call: cold.call,
|
|
cacheRoot,
|
|
expectedStrings,
|
|
nativeStrings: () =>
|
|
nativeKunaStrings({
|
|
executable: kuna,
|
|
cacheRoot,
|
|
workspace,
|
|
binary: path,
|
|
retain: (owner) => retainedNative.add(owner),
|
|
resourceScope,
|
|
}),
|
|
}),
|
|
});
|
|
const listed = await cold.call("list_procedures");
|
|
if (verifyNamedTrace) {
|
|
const missing = await cold.callError("xrefs", {
|
|
address: "rea_missing_xref_inventory_name",
|
|
});
|
|
assert.equal(missing.code, "invalid_request");
|
|
assert.equal(
|
|
missing.message,
|
|
missingKunaXrefNameMessage("rea_missing_xref_inventory_name"),
|
|
);
|
|
assert.equal(
|
|
missing.remediation.action,
|
|
KUNA_XREF_MISSING_NAME_REMEDIATION,
|
|
);
|
|
assert.ok(missing.message.includes("rea_missing_xref_inventory_name"));
|
|
assert.equal(missing.recovery, undefined);
|
|
const procedure = await cold.callError("procedure_address", {
|
|
procedure: "rea_missing_procedure_name",
|
|
});
|
|
assert.equal(procedure.code, "invalid_request");
|
|
assert.equal(procedure.recovery, undefined);
|
|
assert.match(procedure.remediation.action, /search_procedures/u);
|
|
assert.ok(
|
|
procedure.details.issues.some(
|
|
(issue) => issue.observed?.procedure === "rea_missing_procedure_name",
|
|
),
|
|
);
|
|
const missingAddress = await cold.callError("procedure_address", {
|
|
procedure: "0x00000001",
|
|
});
|
|
assert.equal(missingAddress.code, "invalid_request");
|
|
assert.equal(missingAddress.recovery, undefined);
|
|
assert.match(missingAddress.remediation.action, /list_procedures/u);
|
|
assert.ok(
|
|
missingAddress.details.issues.some(
|
|
(issue) => issue.observed?.procedure === "0x00000001",
|
|
),
|
|
);
|
|
}
|
|
for (const [name, address] of functions) {
|
|
assert.ok(
|
|
listed.value.some((entry) => entry.address === address),
|
|
`${name} at ${address} is missing from Kuna's procedure list for ${path}`,
|
|
);
|
|
const references = await verifyKunaReferences({
|
|
call: cold.call,
|
|
cacheRoot,
|
|
name,
|
|
address,
|
|
expectedCaller,
|
|
verifyNamedTrace,
|
|
minimumTraceReferences: minimumTraceReferences[name],
|
|
nativeIncoming: (targetAddress) =>
|
|
nativeKunaIncomingSites({
|
|
executable: kuna,
|
|
cacheRoot,
|
|
workspace,
|
|
binary: path,
|
|
address: targetAddress,
|
|
retain: (outcome) => retainedNative.add(outcome),
|
|
resourceScope,
|
|
}),
|
|
});
|
|
const pseudocode = await cold.call("procedure_pseudo_code", {
|
|
procedure: address,
|
|
});
|
|
assert.equal(pseudocode.structured.subject.digest.sha256, sha256);
|
|
assert.equal(pseudocode.structured.provider.id, "kuna");
|
|
const source = pseudocode.structured.raw_result?.source?.kind;
|
|
// A fast export can finish before the first request reaches the
|
|
// decompile path; both sources are valid answers. The single-function
|
|
// fallback itself is covered by the provider's boundary tests.
|
|
assert.ok(
|
|
source === "single-function" || source === "project-export",
|
|
`Unexpected pseudocode source ${String(source)}`,
|
|
);
|
|
const assembly = await cold.call("procedure_assembly", {
|
|
procedure: address,
|
|
});
|
|
assert.equal(
|
|
assembly.structured.raw_result.source.kind,
|
|
"project-export",
|
|
);
|
|
assert.match(assembly.value, new RegExp(`: ; ${address}\\n`, "u"));
|
|
const exported = await cold.call("procedure_pseudo_code", {
|
|
procedure: address,
|
|
});
|
|
const recorded = exported.structured.raw_result.source;
|
|
assert.equal(recorded.kind, "project-export");
|
|
const block = (await readFile(join(recorded.directory, recorded.file)))
|
|
.subarray(
|
|
recorded.byte_offset,
|
|
recorded.byte_offset + recorded.byte_length,
|
|
)
|
|
.toString("utf8");
|
|
assert.ok(
|
|
exported.value === null || block.includes(exported.value),
|
|
"Served pseudocode differs from the recorded export span",
|
|
);
|
|
const dossier = await cold.call("analyze_function", {
|
|
procedure: address,
|
|
detail: "complete",
|
|
});
|
|
assert.deepEqual(
|
|
dossier.structured.relationship_coverage,
|
|
references.relationship_coverage,
|
|
"Function dossier lost the directional call coverage",
|
|
);
|
|
const combined = dossier.structured.raw_result.source;
|
|
assert.equal(combined.kind, "project-export");
|
|
assert.deepEqual(
|
|
combined.files.map(({ facet }) => facet),
|
|
["pseudocode", "assembly"],
|
|
);
|
|
for (const file of combined.files) {
|
|
const bytes = await readFile(join(combined.directory, file.file));
|
|
assert.equal(
|
|
createHash("sha256").update(bytes).digest("hex"),
|
|
file.file_sha256,
|
|
);
|
|
const span = bytes
|
|
.subarray(file.byte_offset, file.byte_offset + file.byte_length)
|
|
.toString("utf8");
|
|
const facet = dossier.value[file.facet];
|
|
assert.ok(
|
|
span.includes(Array.isArray(facet) ? facet.join("\n") : facet),
|
|
);
|
|
}
|
|
answers.push({
|
|
name,
|
|
address,
|
|
cold_source: source,
|
|
cold_ms: pseudocode.ms,
|
|
export_wait_ms: assembly.ms,
|
|
warm_same_session_ms: exported.ms,
|
|
response_bytes: exported.bytes,
|
|
dossier_response_bytes: dossier.bytes,
|
|
...quality(exported.value),
|
|
references,
|
|
});
|
|
}
|
|
if (functions.length > 0) {
|
|
const trace = await cold.call("trace_native_values", {
|
|
procedure: functions[0][1],
|
|
max_depth: 0,
|
|
max_functions: 1,
|
|
});
|
|
const bundle = await cold.call("get_evidence_bundle", {
|
|
detail: "complete",
|
|
});
|
|
for (const source of [
|
|
...trace.value.procedures,
|
|
...trace.value.nodes,
|
|
...trace.value.edges,
|
|
]) {
|
|
assert.ok(trace.structured.evidence_links.includes(source.evidence_id));
|
|
assert.equal(
|
|
bundle.value.records.find(
|
|
(record) => record.evidence_id === source.evidence_id,
|
|
)?.operation,
|
|
"analyze_function",
|
|
`Missing source Evidence ${source.evidence_id}`,
|
|
);
|
|
}
|
|
}
|
|
} catch (cause) {
|
|
coldFailure = cause;
|
|
} finally {
|
|
answers.push({ cold_server: await cold.close(coldFailure) });
|
|
}
|
|
const staging = await readdir(join(cacheRoot, "staging"));
|
|
assert.deepEqual(staging, [], "Kuna staging survived a completed export");
|
|
// A fresh server reuses the export immediately.
|
|
const warm = await openServer({ path, id: "kuna" });
|
|
let warmFailure;
|
|
try {
|
|
for (const answer of answers)
|
|
if (answer.address !== undefined) {
|
|
const reread = await warm.call("procedure_pseudo_code", {
|
|
procedure: answer.address,
|
|
});
|
|
assert.equal(
|
|
reread.structured.raw_result.source.kind,
|
|
"project-export",
|
|
);
|
|
answer.warm_fresh_server_ms = reread.ms;
|
|
}
|
|
} catch (cause) {
|
|
warmFailure = cause;
|
|
} finally {
|
|
answers.push({ warm_server: await warm.close(warmFailure) });
|
|
}
|
|
return answers;
|
|
};
|
|
|
|
/** Measure Ghidra on the same functions through the same public workflow. */
|
|
const measureGhidra = async (path, functions) => {
|
|
const server = await openServer({ path, id: "ghidra" });
|
|
const answers = [];
|
|
let failure;
|
|
try {
|
|
for (const [name, address] of functions) {
|
|
const cold = await server.call("procedure_pseudo_code", {
|
|
procedure: address,
|
|
});
|
|
const warm = await server.call("procedure_pseudo_code", {
|
|
procedure: address,
|
|
});
|
|
answers.push({
|
|
name,
|
|
address,
|
|
first_call_ms: cold.ms,
|
|
repeat_ms: warm.ms,
|
|
response_bytes: cold.bytes,
|
|
...quality(cold.value),
|
|
});
|
|
}
|
|
} catch (cause) {
|
|
failure = cause;
|
|
} finally {
|
|
answers.push({ server: await server.close(failure) });
|
|
}
|
|
return answers;
|
|
};
|
|
|
|
const describeFailure = (cause) => ({
|
|
message: cause instanceof Error ? cause.message : String(cause),
|
|
...(cause instanceof AggregateError
|
|
? { causes: cause.errors.map(describeFailure) }
|
|
: {}),
|
|
});
|
|
|
|
/** Inspect symbol-bearing caller binaries, retaining both selected and unmatched inputs. */
|
|
const targetPairs = async (root, names, selection) => {
|
|
const pairs = [];
|
|
for (const flavor of (await readdir(root)).sort()) {
|
|
const directory = join(root, flavor);
|
|
if (!(await stat(directory)).isDirectory()) continue;
|
|
for (const file of (await readdir(directory)).sort()) {
|
|
if (file.endsWith(".stripped")) continue;
|
|
let symbols;
|
|
try {
|
|
symbols = await symbolAddresses(join(directory, file), names);
|
|
} catch (cause) {
|
|
selection.examined.push({
|
|
binary: `${flavor}/${file}`,
|
|
status: "inspection_failed",
|
|
error: describeFailure(cause),
|
|
});
|
|
throw cause;
|
|
}
|
|
selection.examined.push({
|
|
binary: `${flavor}/${file}`,
|
|
status: symbols.size > 0 ? "selected" : "no_matching_text_symbols",
|
|
matched_functions: [...symbols.keys()],
|
|
});
|
|
if (symbols.size > 0) pairs.push({ flavor, directory, file, symbols });
|
|
}
|
|
}
|
|
return pairs;
|
|
};
|
|
|
|
/** Verify Kuna, and optionally measure Ghidra, on one binary of a pair. */
|
|
const verifyVariant = async ({ flavor, directory, symbols }, variant) => {
|
|
const path = join(directory, variant);
|
|
const entry = { binary: `${flavor}/${variant}` };
|
|
entry.kuna = await verifyKuna(path, [...symbols]);
|
|
if (values["compare-ghidra"])
|
|
entry.ghidra = await measureGhidra(path, [...symbols]);
|
|
process.stderr.write(`verified ${entry.binary}\n`);
|
|
return entry;
|
|
};
|
|
|
|
const results = [];
|
|
let timeoutRecovery;
|
|
const failures = [];
|
|
const callerTargetSelection =
|
|
values.targets === undefined
|
|
? undefined
|
|
: {
|
|
directory: values.targets,
|
|
functions_argument: values.functions ?? null,
|
|
requested_functions: (values.functions ?? "")
|
|
.split(",")
|
|
.filter(Boolean),
|
|
symbol_scan_complete: false,
|
|
examined: [],
|
|
};
|
|
let inspectionResourcesClean = true;
|
|
try {
|
|
const installation = await inspectKunaInstallation(
|
|
{ REA_KUNA_COMMAND: kuna, REA_KUNA_CACHE_DIR: cacheRoot },
|
|
{ platform: HOST_PLATFORM.platform, resourceScope },
|
|
);
|
|
assert.ok(
|
|
installation.ok,
|
|
installation.ok ? undefined : installation.error.reason,
|
|
);
|
|
kunaVersion = `kuna ${installation.value.version}`;
|
|
let callerPairs = [];
|
|
if (callerTargetSelection !== undefined) {
|
|
const names = callerTargetSelection.requested_functions;
|
|
assert.ok(names.length > 0, "--targets requires --functions");
|
|
callerPairs = await targetPairs(
|
|
callerTargetSelection.directory,
|
|
names,
|
|
callerTargetSelection,
|
|
);
|
|
callerTargetSelection.symbol_scan_complete = true;
|
|
assert.ok(
|
|
callerPairs.length > 0,
|
|
`No caller-built targets contain the requested functions in ${callerTargetSelection.directory}`,
|
|
);
|
|
const found = new Set(
|
|
callerPairs.flatMap(({ symbols }) => [...symbols.keys()]),
|
|
);
|
|
const missing = names.filter((name) => !found.has(name));
|
|
assert.deepEqual(
|
|
missing,
|
|
[],
|
|
"Requested functions were not found in any caller-built target",
|
|
);
|
|
}
|
|
|
|
// Source-owned fixture: always built and verified.
|
|
const fixtureDir = join(workspace, "fixture");
|
|
await mkdir(fixtureDir);
|
|
const source = join(fixtureDir, "fixture.c");
|
|
await writeFile(source, FIXTURE_SOURCE);
|
|
const built = join(fixtureDir, "rea-kuna-fixture");
|
|
await exec(process.env.REA_CC ?? "cc", ["-O2", "-o", built, source]);
|
|
const stripped = `${built}.stripped`;
|
|
await writeFile(stripped, await readFile(built));
|
|
await exec(process.env.REA_STRIP ?? "strip", [stripped]);
|
|
const fixtureFunctions = await symbolAddresses(built, [
|
|
"rea_checksum",
|
|
"rea_classify",
|
|
"main",
|
|
]);
|
|
assert.equal(fixtureFunctions.size, 3, "Fixture symbols were not found");
|
|
const fixtureMain = fixtureFunctions.get("main");
|
|
fixtureFunctions.delete("main");
|
|
for (const binary of [built, stripped])
|
|
results.push({
|
|
binary: binary.slice(workspace.length + 1),
|
|
kuna: await verifyKuna(binary, [...fixtureFunctions], {
|
|
expectedCaller: fixtureMain,
|
|
expectedStrings: ["_φ( °-°)/ REA unicode marker", "REA wide marker"],
|
|
verifyNamedTrace: binary === built,
|
|
minimumTraceReferences: { rea_checksum: 2 },
|
|
}),
|
|
});
|
|
|
|
timeoutRecovery = await verifyProjectTimeoutRecovery(
|
|
built,
|
|
fixtureFunctions.get("rea_checksum"),
|
|
);
|
|
|
|
// Caller-built matrix.
|
|
for (const pair of callerPairs)
|
|
for (const variant of [pair.file, `${pair.file}.stripped`])
|
|
results.push(await verifyVariant(pair, variant));
|
|
} catch (cause) {
|
|
failures.push(cause);
|
|
}
|
|
// Failure paths need the same process evidence as successful verification.
|
|
for (const retained of [...retainedNative]) {
|
|
try {
|
|
const stopped = await retained.owner?.stop();
|
|
if (stopped !== undefined && stopped.status !== "incomplete")
|
|
retainedNative.delete(retained);
|
|
} catch (cause) {
|
|
failures.push(cause);
|
|
}
|
|
}
|
|
try {
|
|
await inspectionResources.close();
|
|
} catch (cause) {
|
|
inspectionResourcesClean = false;
|
|
failures.push(cause);
|
|
}
|
|
const lifecycle = await completeVerifierRun(run);
|
|
let cleanupComplete =
|
|
pendingServers.size === 0 &&
|
|
retainedNative.size === 0 &&
|
|
inspectionResourcesClean;
|
|
try {
|
|
assertVerifierCleanupComplete(lifecycle.process_lineage);
|
|
} catch (cause) {
|
|
cleanupComplete = false;
|
|
failures.push(cause);
|
|
}
|
|
if (cleanupComplete)
|
|
try {
|
|
await workspaceFixture.release();
|
|
} catch (cause) {
|
|
cleanupComplete = false;
|
|
failures.push(cause);
|
|
}
|
|
const report = {
|
|
lane: "kuna",
|
|
status: failures.length === 0 ? "passed" : "failed",
|
|
kuna_version: kunaVersion,
|
|
platform: `${process.platform}/${process.arch}`,
|
|
verifier_run: lifecycle,
|
|
...(callerTargetSelection === undefined
|
|
? {}
|
|
: { caller_target_selection: callerTargetSelection }),
|
|
results,
|
|
...(timeoutRecovery === undefined
|
|
? {}
|
|
: { timeout_recovery: timeoutRecovery }),
|
|
limitations: [
|
|
"Targets are analyzed statically; they are never executed.",
|
|
"Memory is the sampled peak resident set of the MCP server process tree; CPU is its sampled cumulative time. A short-lived peak between 200 ms samples is not observed.",
|
|
"Quality signals count gotos and warning markers only; they are not a correctness judgement and not a DecBench reproduction.",
|
|
"Response bytes are UTF-8 serialization sizes. Model token usage, tool schema costs and agent task completion were not measured.",
|
|
],
|
|
cleanup: cleanupComplete ? "complete" : "incomplete",
|
|
...(cleanupComplete ? {} : { retained_workspace: workspace }),
|
|
...(failures.length === 0 ? {} : { failures: failures.map(describeFailure) }),
|
|
};
|
|
if (values.report !== undefined)
|
|
await writeFile(values.report, `${JSON.stringify(report, null, 2)}\n`);
|
|
process.stdout.write(`${JSON.stringify(report)}\n`);
|
|
if (failures.length > 0)
|
|
throw new AggregateError(
|
|
failures,
|
|
"Kuna verification failed; see the report for cleanup evidence",
|
|
);
|