feat(ghidra): add private headless provider session

This commit is contained in:
N0zoM1z0
2026-07-16 01:27:54 +09:00
committed by N0zoM1z0
parent ed17e76473
commit f0e625d7ee
234 changed files with 8968 additions and 513 deletions
+5
View File
@@ -101,6 +101,7 @@ const SOURCE_PATHS = {
electronContracts: "dist/contracts/electronToolContracts.js",
supportedClients: "dist/application/SupportedClients.js",
hopperProvider: "dist/hopper/HopperProvider.js",
ghidraProvider: "dist/ghidra/GhidraProvider.js",
nativeProvider: "dist/native/NativeMacOSProvider.js",
artifactProviders: "dist/application/InvestigationProviders.js",
browserProvider: "dist/browser/CdpBrowserProvider.js",
@@ -194,6 +195,10 @@ const providerCatalog = (sources) =>
identity: sources.hopperProvider.HOPPER_PROVIDER_IDENTITY,
contracts: sources.hopperProvider.HOPPER_PROVIDER_TOOL_CONTRACTS,
},
{
identity: sources.ghidraProvider.GHIDRA_PROVIDER_IDENTITY,
contracts: sources.ghidraProvider.GHIDRA_PROVIDER_TOOL_CONTRACTS,
},
{
identity: sources.nativeProvider.NATIVE_MACOS_PROVIDER_IDENTITY,
contracts: sources.nativeContracts.NATIVE_TOOL_CONTRACTS,
+7 -1
View File
@@ -9,7 +9,13 @@ const root = resolve(import.meta.dirname, "..");
// Native globSync is available throughout the Node versions in package.engines.
// Its exclusion option is `exclude`; `ignore` and `nodir` belong to npm glob.
const sourceFiles = globSync(
["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.mjs", "bridge/**/*.py"],
[
"src/**/*.ts",
"tests/**/*.ts",
"scripts/**/*.mjs",
"bridge/**/*.py",
"bridge/**/*.java",
],
{
cwd: root,
exclude: (path) => path.split(/[\\/]/u).includes("node_modules"),
+20 -3
View File
@@ -1,9 +1,11 @@
import { execFile } from "node:child_process";
import { readFile } from "node:fs/promises";
import { join } from "node:path";
import { promisify } from "node:util";
const exec = promisify(execFile);
const packedBridge = "package/bridge/hopper_bridge.py";
const packedHopperBridge = "package/bridge/hopper_bridge.py";
const packedGhidraBridge = "package/bridge/ghidra/ReaGhidraBridge.java";
/** Verify that the packed production bridge rejects a catastrophic regex. */
export async function verifyPackedBridge({
@@ -12,14 +14,29 @@ export async function verifyPackedBridge({
tarball,
packedFiles,
}) {
if (!packedFiles.includes(packedBridge))
if (!packedFiles.includes(packedHopperBridge))
throw new Error("package omitted the Hopper bridge");
if (!packedFiles.includes(packedGhidraBridge))
throw new Error("package omitted the Ghidra bridge");
await exec("tar", ["-xf", join(root, tarball), "-C", workspace]);
const ghidraSource = await readFile(
join(workspace, packedGhidraBridge),
"utf8",
);
for (const commitment of [
"extends HeadlessScript",
'request.method.equals("ping")',
'request.method.equals("shutdown")',
'result.addProperty("read_only", true)',
"analysisTimeoutOccurred()",
])
if (!ghidraSource.includes(commitment))
throw new Error(`packaged Ghidra bridge omitted ${commitment}`);
const probe = JSON.parse(
(
await exec("python3", [
join(root, "tests/fixtures/bridgeRegexProbe.py"),
join(workspace, packedBridge),
join(workspace, packedHopperBridge),
JSON.stringify({
action: "match",
pattern: "(a|aa){1,35}b",
+141
View File
@@ -0,0 +1,141 @@
#!/usr/bin/env node
import { access } from "node:fs/promises";
import { isAbsolute } from "node:path";
import { fileURLToPath } from "node:url";
import { resolveGhidraAnalysisProfile } from "../dist/ghidra/GhidraAnalysisProfile.js";
import { GhidraClient } from "../dist/ghidra/GhidraClient.js";
import {
inspectGhidraInstallation,
SUPPORTED_GHIDRA_VERSION,
} from "../dist/ghidra/GhidraInstallation.js";
import { GhidraHeadlessLauncher } from "../dist/ghidra/GhidraLauncher.js";
import { GHIDRA_PROVIDER_IDENTITY } from "../dist/ghidra/GhidraProvider.js";
import { parseBinaryTarget } from "../dist/domain/binaryTarget.js";
const installDir = process.env.GHIDRA_INSTALL_DIR;
if (installDir === undefined || !isAbsolute(installDir))
throw new Error(
"Set GHIDRA_INSTALL_DIR to the absolute root of an extracted Ghidra 12.1.2 release.",
);
const targetPath = process.env.GHIDRA_TARGET_PATH ?? "/usr/bin/true";
const installation = inspectGhidraInstallation({
installDir,
...(process.env.JAVA_HOME === undefined
? {}
: { javaHome: process.env.JAVA_HOME }),
});
if (!installation.available || installation.analyzeHeadlessPath === null)
throw new Error(
`Ghidra installation is unavailable: ${JSON.stringify(installation)}`,
);
if (installation.providerVersion !== SUPPORTED_GHIDRA_VERSION)
throw new Error("Ghidra provider version commitment drifted");
const parsedTarget = await parseBinaryTarget(targetPath);
if (!parsedTarget.ok) throw parsedTarget.error;
const profile = await resolveGhidraAnalysisProfile(
parsedTarget.value,
GHIDRA_PROVIDER_IDENTITY,
installation,
);
if (!profile.ok || profile.value.profile === null)
throw new Error("Ghidra analysis profile could not be committed");
const client = new GhidraClient({
launcher: new GhidraHeadlessLauncher({
analyzeHeadlessPath: installation.analyzeHeadlessPath,
...(process.env.JAVA_HOME === undefined
? {}
: { javaHome: process.env.JAVA_HOME }),
bridgeScriptPath: fileURLToPath(
new URL("../bridge/ghidra/ReaGhidraBridge.java", import.meta.url),
),
}),
targetPath: parsedTarget.value.path,
providerVersion: SUPPORTED_GHIDRA_VERSION,
profileDigest: profile.value.profile.digest,
});
let runtimeCoordinates;
let observedSession;
try {
const started = await client.start();
if (!started.ok) throw started.error;
assertSession(started.value, profile.value.profile.digest);
const pinged = await client.ping();
if (!pinged.ok) throw pinged.error;
assertSession(pinged.value, profile.value.profile.digest);
observedSession = pinged.value;
runtimeCoordinates = client.diagnostics();
for (const name of ["runtime_root", "socket_path", "project_root"])
if (typeof runtimeCoordinates[name] !== "string")
throw new Error(`Ghidra verifier did not observe ${name}`);
if (typeof runtimeCoordinates.process_id !== "number")
throw new Error("Ghidra verifier did not observe its process ID");
} finally {
await client.close();
}
if (runtimeCoordinates === undefined)
throw new Error("Ghidra runtime coordinates were not captured");
if (observedSession === undefined)
throw new Error("Ghidra session metadata was not captured");
for (const name of ["runtime_root", "socket_path", "project_root"]) {
const path = runtimeCoordinates[name];
if (typeof path === "string" && (await exists(path)))
throw new Error(`Ghidra cleanup left ${name}: ${path}`);
}
const pid = runtimeCoordinates.process_id;
if (typeof pid === "number" && processExists(pid))
throw new Error(`Ghidra cleanup left process ${String(pid)}`);
process.stdout.write(
`${JSON.stringify({
ok: true,
provider: { id: "ghidra", version: SUPPORTED_GHIDRA_VERSION },
target_path: parsedTarget.value.path,
target_sha256: parsedTarget.value.sha256,
analysis_profile_digest: profile.value.profile.digest,
language_id: observedSession.target.language_id,
compiler_spec_id: observedSession.target.compiler_spec_id,
cleanup: "complete",
})}\n`,
);
function assertSession(session, expectedDigest) {
if (
session.provider.id !== "ghidra" ||
session.provider.version !== SUPPORTED_GHIDRA_VERSION ||
session.profile_digest !== expectedDigest ||
session.read_only !== true ||
session.analysis_complete !== true ||
session.analysis_timed_out !== false ||
session.capabilities.join(",") !== "ping,shutdown"
)
throw new Error(
`Ghidra session commitment drifted: ${JSON.stringify(session)}`,
);
}
async function exists(path) {
try {
await access(path);
return true;
} catch {
return false;
}
}
function processExists(pid) {
try {
process.kill(pid, 0);
return true;
} catch (cause) {
return !(
cause instanceof Error &&
"code" in cause &&
cause.code === "ESRCH"
);
}
}