feat(native): inspect API boundaries with evidence
This commit is contained in:
@@ -102,6 +102,7 @@ const ENHANCED_REQUIREMENTS: Readonly<Record<string, readonly string[]>> = {
|
||||
"list_strings",
|
||||
],
|
||||
analyze_function: ["analyze_function"],
|
||||
inspect_native_api: ["analyze_function"],
|
||||
trace_feature: [
|
||||
"list_strings",
|
||||
"list_procedures",
|
||||
|
||||
@@ -52,6 +52,7 @@ type DirectAnalysisTool =
|
||||
| "procedure_pseudo_code"
|
||||
| "read_function_instructions"
|
||||
| "analyze_function"
|
||||
| "inspect_native_api"
|
||||
| "search_strings"
|
||||
| "search_procedures"
|
||||
| "xrefs"
|
||||
@@ -341,6 +342,7 @@ const executeAnalysisTool = async (input: {
|
||||
if (
|
||||
tool === "binary_overview" ||
|
||||
tool === "analyze_function" ||
|
||||
tool === "inspect_native_api" ||
|
||||
tool === "trace_feature"
|
||||
) {
|
||||
const result = await new EnhancedTools(session).execute(
|
||||
@@ -438,7 +440,7 @@ const replayProviderFor = (
|
||||
| ManagedToolName
|
||||
| DirectAnalysisTool,
|
||||
) =>
|
||||
tool === "binary_overview" || tool === "trace_feature"
|
||||
isWorkflowEvidenceTool(tool)
|
||||
? REA_WORKFLOW_PROVIDER
|
||||
: session.providerIdentity(tool);
|
||||
|
||||
@@ -450,12 +452,22 @@ const analysisProfileForEvidence = (
|
||||
| ManagedToolName
|
||||
| DirectAnalysisTool,
|
||||
): AnalysisProfileCommitment | undefined => {
|
||||
if (tool !== "binary_overview" && tool !== "trace_feature")
|
||||
return session.analysisProfile(tool);
|
||||
if (!isWorkflowEvidenceTool(tool)) return session.analysisProfile(tool);
|
||||
const upstream = session.analysisProfile();
|
||||
return upstream === undefined ? undefined : workflowAnalysisProfile(upstream);
|
||||
};
|
||||
|
||||
const isWorkflowEvidenceTool = (
|
||||
tool:
|
||||
| NativeToolName
|
||||
| ArtifactToolName
|
||||
| ManagedToolName
|
||||
| DirectAnalysisTool,
|
||||
): boolean =>
|
||||
tool === "binary_overview" ||
|
||||
tool === "inspect_native_api" ||
|
||||
tool === "trace_feature";
|
||||
|
||||
const fileExists = async (path: string): Promise<boolean> => {
|
||||
try {
|
||||
await access(path);
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
import type { z } from "zod";
|
||||
|
||||
import type {
|
||||
AnalysisOperation,
|
||||
AnalysisOperationPort,
|
||||
@@ -12,6 +14,7 @@ import {
|
||||
} from "../domain/errors.js";
|
||||
import {
|
||||
addressDistance,
|
||||
functionDossierSchema,
|
||||
parseDocuments,
|
||||
parseFunctionDossier,
|
||||
parseListCount,
|
||||
@@ -25,7 +28,7 @@ import {
|
||||
discoverObjcProtocols,
|
||||
discoverSwiftClasses,
|
||||
} from "../domain/symbolAnalysis.js";
|
||||
import type { JsonValue } from "../domain/jsonValue.js";
|
||||
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
|
||||
|
||||
import {
|
||||
invalidEnhancedInput,
|
||||
@@ -35,6 +38,7 @@ import {
|
||||
import { readAllAddressed } from "./EnhancedToolPagination.js";
|
||||
import { traceCallPath } from "./CallPathTracing.js";
|
||||
import { traceLiteralFeature } from "./EnhancedLiteralTracing.js";
|
||||
import { projectNativeApiInspection } from "./NativeApiInspection.js";
|
||||
export type { ValidatedEnhancedCall } from "./EnhancedToolTypes.js";
|
||||
|
||||
/**
|
||||
@@ -57,6 +61,8 @@ export class EnhancedTools {
|
||||
name === "trace_call_path"
|
||||
)
|
||||
return this.#executeTracing(name, input, signal);
|
||||
if (name === "analyze_function" || name === "inspect_native_api")
|
||||
return this.#executeFunctionAnalysis(name, input, signal);
|
||||
switch (name) {
|
||||
case "swift_classes": {
|
||||
const parsed = enhancedInputSchemas.swift_classes.safeParse(input);
|
||||
@@ -98,12 +104,6 @@ export class EnhancedTools {
|
||||
? this.executeValidated({ name, input: parsed.data }, signal)
|
||||
: invalidEnhancedInput(name, parsed.error);
|
||||
}
|
||||
case "analyze_function": {
|
||||
const parsed = enhancedInputSchemas.analyze_function.safeParse(input);
|
||||
return parsed.success
|
||||
? this.executeValidated({ name, input: parsed.data }, signal)
|
||||
: invalidEnhancedInput(name, parsed.error);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -131,6 +131,8 @@ export class EnhancedTools {
|
||||
return this.#binaryOverview(call.input, signal);
|
||||
case "analyze_function":
|
||||
return this.#analyzeFunction(call.input, signal);
|
||||
case "inspect_native_api":
|
||||
return this.#inspectNativeApi(call.input, signal);
|
||||
case "trace_feature":
|
||||
return traceLiteralFeature(
|
||||
(name, arguments_, operationSignal) =>
|
||||
@@ -181,6 +183,30 @@ export class EnhancedTools {
|
||||
);
|
||||
}
|
||||
|
||||
#executeFunctionAnalysis(
|
||||
name: "analyze_function" | "inspect_native_api",
|
||||
input: unknown,
|
||||
signal?: AbortSignal,
|
||||
): EnhancedResult {
|
||||
const parsed = enhancedInputSchemas[name].safeParse(input);
|
||||
if (!parsed.success) return invalidEnhancedInput(name, parsed.error);
|
||||
if (name === "analyze_function")
|
||||
return this.executeValidated(
|
||||
{
|
||||
name,
|
||||
input: enhancedInputSchemas.analyze_function.parse(parsed.data),
|
||||
},
|
||||
signal,
|
||||
);
|
||||
return this.executeValidated(
|
||||
{
|
||||
name,
|
||||
input: enhancedInputSchemas.inspect_native_api.parse(parsed.data),
|
||||
},
|
||||
signal,
|
||||
);
|
||||
}
|
||||
|
||||
async #analyzeFunction(
|
||||
input: Readonly<Record<string, JsonValue>>,
|
||||
signal?: AbortSignal,
|
||||
@@ -189,6 +215,24 @@ export class EnhancedTools {
|
||||
return result.ok ? parseFunctionDossier(result.value) : result;
|
||||
}
|
||||
|
||||
async #inspectNativeApi(
|
||||
input: z.output<typeof enhancedInputSchemas.inspect_native_api>,
|
||||
signal?: AbortSignal,
|
||||
): EnhancedResult {
|
||||
const analysisInput = enhancedInputSchemas.analyze_function.parse({
|
||||
procedure: input.procedure,
|
||||
include_assembly: true,
|
||||
max_pseudocode_chars: input.max_pseudocode_chars,
|
||||
max_instructions: input.max_instructions,
|
||||
});
|
||||
const result = await this.#call("analyze_function", analysisInput, signal);
|
||||
if (!result.ok) return result;
|
||||
const parsed = parseFunctionDossier(result.value);
|
||||
if (!parsed.ok) return parsed;
|
||||
const dossier = functionDossierSchema.parse(parsed.value);
|
||||
return ok(jsonValueSchema.parse(projectNativeApiInspection(dossier)));
|
||||
}
|
||||
|
||||
async #swiftClasses(pattern: string, signal?: AbortSignal): EnhancedResult {
|
||||
const procedures = await this.#allAddressed("list_procedures", signal);
|
||||
return procedures.ok
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
import type { FunctionDossier } from "../domain/hopperValues.js";
|
||||
import {
|
||||
nativeApiInspectionResultSchema,
|
||||
type NativeApiBoundary,
|
||||
type NativeApiInspectionResult,
|
||||
} from "../domain/nativeApiBoundary.js";
|
||||
|
||||
const unavailableBoundary = (): NativeApiBoundary => ({
|
||||
available: false,
|
||||
reason:
|
||||
"The selected provider did not expose a structured native API boundary model.",
|
||||
residual_unknowns: [
|
||||
"What are the function's return and parameter boundary types?",
|
||||
"Does this function dispatch through a jump table with recoverable data addresses?",
|
||||
],
|
||||
});
|
||||
|
||||
/** Project one analyzed-function dossier into inspectable native API substeps. */
|
||||
export const projectNativeApiInspection = (
|
||||
dossier: FunctionDossier,
|
||||
): NativeApiInspectionResult => {
|
||||
const boundary = dossier.native_api ?? unavailableBoundary();
|
||||
const unsupportedBranches = boundary.available
|
||||
? []
|
||||
: ["structured-boundary-types", "jump-table-data-mapping"];
|
||||
const residualUnknowns = boundary.available
|
||||
? availableResidualUnknowns(boundary)
|
||||
: boundary.residual_unknowns;
|
||||
return nativeApiInspectionResultSchema.parse({
|
||||
schema_version: 1,
|
||||
procedure: {
|
||||
address: dossier.procedure.address,
|
||||
name: dossier.procedure.name,
|
||||
},
|
||||
boundary,
|
||||
substeps: [
|
||||
{
|
||||
operation: "analyze_function",
|
||||
status: "completed",
|
||||
observations: [
|
||||
"provider function dossier",
|
||||
"provider pseudocode classification",
|
||||
"provider control-flow observations",
|
||||
],
|
||||
},
|
||||
{
|
||||
operation: "project_native_api_boundary",
|
||||
status: boundary.available ? "completed" : "unsupported",
|
||||
observations: boundary.available
|
||||
? [
|
||||
"return and parameter boundary types",
|
||||
"confidence and inference evidence",
|
||||
"jump-table dispatch, data, and target addresses",
|
||||
]
|
||||
: [boundary.reason],
|
||||
},
|
||||
{
|
||||
operation: "preserve_residual_unknowns",
|
||||
status: "completed",
|
||||
observations:
|
||||
residualUnknowns.length === 0
|
||||
? ["no additional structured-boundary unknowns"]
|
||||
: residualUnknowns,
|
||||
},
|
||||
],
|
||||
unsupported_branches: unsupportedBranches,
|
||||
residual_unknowns: residualUnknowns,
|
||||
});
|
||||
};
|
||||
|
||||
const availableResidualUnknowns = (
|
||||
boundary: Extract<NativeApiBoundary, { readonly available: true }>,
|
||||
): readonly string[] => {
|
||||
const unknowns: string[] = [];
|
||||
if (boundary.parameters_truncated)
|
||||
unknowns.push(
|
||||
"Which additional parameters were omitted by the native API boundary limit?",
|
||||
);
|
||||
if (boundary.jump_tables_truncated)
|
||||
unknowns.push(
|
||||
"Which additional jump tables were omitted by the native API boundary limit?",
|
||||
);
|
||||
for (const table of boundary.jump_tables) {
|
||||
if (table.data_sources_truncated || table.mappings_truncated)
|
||||
unknowns.push(
|
||||
`Which additional data sources or targets were omitted for the jump table dispatched at ${table.dispatch_address}?`,
|
||||
);
|
||||
if (table.data_sources.length === 0)
|
||||
unknowns.push(
|
||||
`What backing data address produced the jump table dispatched at ${table.dispatch_address}?`,
|
||||
);
|
||||
if (
|
||||
table.data_sources.some(
|
||||
({ entry_count: count, entry_size_bytes: size }) =>
|
||||
count === null || size === null,
|
||||
)
|
||||
)
|
||||
unknowns.push(
|
||||
`What are the exact entry size and count for candidate jump-table data dispatched at ${table.dispatch_address}?`,
|
||||
);
|
||||
if (table.mappings.some(({ case_value: value }) => value === null))
|
||||
unknowns.push(
|
||||
`Which source-level case values correspond to every target dispatched at ${table.dispatch_address}?`,
|
||||
);
|
||||
}
|
||||
for (const value of [boundary.return_type, ...boundary.parameters]) {
|
||||
if (value.confidence === "low")
|
||||
unknowns.push(
|
||||
`Can the inferred ${value.role} type ${value.data_type} be confirmed with imported metadata or an ABI probe?`,
|
||||
);
|
||||
}
|
||||
return [...new Set(unknowns)];
|
||||
};
|
||||
@@ -16,6 +16,7 @@ export const registerCoreAnalysisCommands = (
|
||||
): void => {
|
||||
registerCoreCommands(cli, logger);
|
||||
registerFunctionCommand(cli, logger);
|
||||
registerNativeApiCommand(cli, logger);
|
||||
registerInstructionsCommand(cli, logger);
|
||||
registerSearchCommand(cli, logger);
|
||||
registerXrefsCommand(cli, logger);
|
||||
@@ -286,6 +287,55 @@ const registerFunctionCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
});
|
||||
};
|
||||
|
||||
const registerNativeApiCommand = (cli: CliInstance, logger: Logger): void => {
|
||||
cli.command(CLI_COMMANDS.inspectNativeApi, {
|
||||
description: "Reconstruct one native function API boundary with evidence",
|
||||
args: z.object({
|
||||
path: z.string().describe("App or program path"),
|
||||
address: z.string().describe("Procedure name or address"),
|
||||
}),
|
||||
options: z.object({
|
||||
maxPseudocodeChars: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(100_000)
|
||||
.default(20_000)
|
||||
.describe("Maximum pseudocode characters to inspect"),
|
||||
maxInstructions: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(5_000)
|
||||
.default(500)
|
||||
.describe("Maximum assembly instructions to inspect"),
|
||||
snapshot: z
|
||||
.string()
|
||||
.min(1)
|
||||
.optional()
|
||||
.describe("Load and update a local analysis snapshot"),
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
alias: {
|
||||
maxPseudocodeChars: "max-pseudocode-chars",
|
||||
maxInstructions: "max-instructions",
|
||||
},
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, "inspect-native-api", () =>
|
||||
runDirectAnalysis(
|
||||
args.path,
|
||||
"inspect_native_api",
|
||||
{
|
||||
procedure: args.address,
|
||||
max_pseudocode_chars: options.maxPseudocodeChars,
|
||||
max_instructions: options.maxInstructions,
|
||||
},
|
||||
directAnalysisOptions(logger, options.snapshot, options.provider),
|
||||
),
|
||||
),
|
||||
});
|
||||
};
|
||||
|
||||
const registerInstructionsCommand = (
|
||||
cli: CliInstance,
|
||||
logger: Logger,
|
||||
|
||||
@@ -12,6 +12,7 @@ export const CLI_COMMANDS = Object.freeze({
|
||||
capabilities: "capabilities",
|
||||
providers: "providers",
|
||||
function: "function",
|
||||
inspectNativeApi: "inspect-native-api",
|
||||
instructions: "instructions",
|
||||
search: "search",
|
||||
importReferenceSource: "import-reference-source",
|
||||
|
||||
@@ -63,6 +63,17 @@ export const enhancedInputSchemas = {
|
||||
basic_blocks: 0,
|
||||
}),
|
||||
}),
|
||||
inspect_native_api: z.object({
|
||||
procedure: z.string().describe("A procedure name or address"),
|
||||
max_pseudocode_chars: z.number().int().min(1).max(100_000).default(20_000),
|
||||
max_instructions: z.number().int().min(1).max(5_000).default(500),
|
||||
unknown_registry_approved: z
|
||||
.literal(true)
|
||||
.optional()
|
||||
.describe(
|
||||
"Explicit approval to record unsupported native API branches durably",
|
||||
),
|
||||
}),
|
||||
trace_feature: traceLiteralInputSchema,
|
||||
find_code_for_string: traceLiteralInputSchema,
|
||||
trace_call_path: z.object({
|
||||
@@ -95,6 +106,7 @@ export const enhancedToolNameSchema = z.enum([
|
||||
"find_xrefs_to_name",
|
||||
"binary_overview",
|
||||
"analyze_function",
|
||||
"inspect_native_api",
|
||||
"trace_feature",
|
||||
"find_code_for_string",
|
||||
"trace_call_path",
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
import { jsonObjectSchema } from "../domain/jsonValue.js";
|
||||
import { enhancedInputSchemas } from "./enhancedInputs.js";
|
||||
import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js";
|
||||
import type { ToolContract } from "./toolContractTypes.js";
|
||||
import { toolContractMetadata } from "./toolEffects.js";
|
||||
import { enhancedOutputSchemas } from "./toolOutputSchemas.js";
|
||||
|
||||
type FunctionWorkflowName = "analyze_function" | "inspect_native_api";
|
||||
|
||||
const functionWorkflow = <Name extends FunctionWorkflowName>(
|
||||
name: Name,
|
||||
description: string,
|
||||
): ToolContract<Name> => {
|
||||
const inputSchema = enhancedInputSchemas[name];
|
||||
const outputSchema = enhancedOutputSchemas[name];
|
||||
if (outputSchema === undefined)
|
||||
throw new Error(`Missing function workflow output schema for ${name}`);
|
||||
return {
|
||||
name,
|
||||
...toolContractMetadata(name),
|
||||
description,
|
||||
kind: "enhanced",
|
||||
inputSchema,
|
||||
outputSchema,
|
||||
examples: [
|
||||
{
|
||||
title: `Example ${name.replaceAll("_", " ")} request`,
|
||||
input: jsonObjectSchema.parse(
|
||||
inputSchema.parse(TOOL_EXAMPLE_OVERRIDES[name] ?? {}),
|
||||
),
|
||||
},
|
||||
],
|
||||
};
|
||||
};
|
||||
|
||||
/** Function dossier and native API reconstruction workflow contracts. */
|
||||
export const FUNCTION_WORKFLOW_TOOL_CONTRACTS = [
|
||||
functionWorkflow(
|
||||
"analyze_function",
|
||||
"Preferred bounded analysis for one procedure symbol or address. Returns identity, provider-specific pseudocode, optional assembly, comments, calls, typed-or-explicitly-unavailable references, referenced strings/names, and local CFG blocks with exact truncation metadata. Providers with a structured decompiler model also expose native API boundary types, confidence, evidence, jump-table data/target addresses, and explicit decompiler-artifact labels.",
|
||||
),
|
||||
functionWorkflow(
|
||||
"inspect_native_api",
|
||||
"Reconstruct one native function boundary through inspectable substeps. Returns structured inferred return/parameter types with confidence and evidence, jump-table dispatch/data/target mappings, explicit decompiler-artifact labels, unsupported branches, and residual unknowns.",
|
||||
),
|
||||
] as const satisfies readonly ToolContract[];
|
||||
@@ -35,6 +35,7 @@ export const TOOL_EXAMPLE_OVERRIDES: Readonly<
|
||||
get_call_graph: { address: "0x1000" },
|
||||
find_xrefs_to_name: { name: "malloc" },
|
||||
analyze_function: { procedure: "main" },
|
||||
inspect_native_api: { procedure: "main" },
|
||||
trace_feature: { query: "license" },
|
||||
find_code_for_string: { query: "authorization failed" },
|
||||
trace_call_path: { start: "0x1000", goal: "0x1100" },
|
||||
|
||||
@@ -41,6 +41,7 @@ import { binarySessionInputSchema } from "./sessionStatusContract.js";
|
||||
import { functionInstructionInputSchema } from "./functionInstructionContract.js";
|
||||
import { HOPPER_MEMORY_TOOL_DEFINITIONS } from "./hopperMemoryContracts.js";
|
||||
import { analysisSearchInput } from "./analysisSearchContract.js";
|
||||
import { FUNCTION_WORKFLOW_TOOL_CONTRACTS } from "./functionWorkflowToolContracts.js";
|
||||
|
||||
export { binarySessionInputSchema } from "./sessionStatusContract.js";
|
||||
|
||||
@@ -354,11 +355,7 @@ export const ENHANCED_TOOL_CONTRACTS = [
|
||||
"Use immediately after opening a target to summarize document, exhaustive procedure/string counts, and a bounded segment sample. detail controls segment fields and limit controls only the returned segment sample.",
|
||||
enhancedInputSchemas.binary_overview,
|
||||
),
|
||||
enhanced(
|
||||
"analyze_function",
|
||||
"Preferred bounded analysis for one procedure symbol or address. Returns identity, provider-specific pseudocode, optional assembly, comments, calls, typed-or-explicitly-unavailable references, referenced strings/names, and local CFG blocks with exact truncation metadata.",
|
||||
enhancedInputSchemas.analyze_function,
|
||||
),
|
||||
...FUNCTION_WORKFLOW_TOOL_CONTRACTS,
|
||||
enhanced(
|
||||
"trace_feature",
|
||||
"Trace a bounded literal feature query through matching strings and procedures, xrefs, and truthful containing-procedure resolution. Returns the operation budget, truncation, and residual unknowns; unknown_registry_approved: true records them durably without inferring reference kinds.",
|
||||
|
||||
@@ -89,6 +89,7 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {
|
||||
find_xrefs_to_name: evidence,
|
||||
binary_overview: evidence,
|
||||
analyze_function: evidence,
|
||||
inspect_native_api: effects({ mutatesSession: true, idempotent: false }),
|
||||
trace_feature: effects({ mutatesSession: true, idempotent: false }),
|
||||
find_code_for_string: effects({ mutatesSession: true, idempotent: false }),
|
||||
trace_call_path: effects({ mutatesSession: true, idempotent: false }),
|
||||
|
||||
@@ -10,6 +10,7 @@ import {
|
||||
functionInstructionWindowSchema,
|
||||
referenceKindSchema,
|
||||
} from "../domain/hopperValues.js";
|
||||
import { nativeApiInspectionResultSchema } from "../domain/nativeApiBoundary.js";
|
||||
import {
|
||||
demangleSwiftSchema,
|
||||
inspectMachoSchema,
|
||||
@@ -272,6 +273,7 @@ export const enhancedOutputSchemas: Readonly<Record<string, z.ZodObject>> = {
|
||||
}),
|
||||
),
|
||||
analyze_function: functionDossierOutput,
|
||||
inspect_native_api: resultOf(nativeApiInspectionResultSchema),
|
||||
trace_feature: literalTraceOutput,
|
||||
find_code_for_string: literalTraceOutput,
|
||||
trace_call_path: callPathTraceOutput,
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import type { JsonValue } from "./jsonValue.js";
|
||||
import { jsonValueSchema, type JsonValue } from "./jsonValue.js";
|
||||
import { AnalysisOutputError, HopperProtocolError } from "./errors.js";
|
||||
import { err, ok, type Result } from "./result.js";
|
||||
import { nativeApiBoundarySchema } from "./nativeApiBoundary.js";
|
||||
|
||||
export interface AddressedName {
|
||||
readonly address: string;
|
||||
@@ -275,6 +276,7 @@ export const functionDossierSchema = z
|
||||
instruction_scan: z
|
||||
.object({ scanned: z.number().int().min(0), truncated: z.boolean() })
|
||||
.strict(),
|
||||
native_api: nativeApiBoundarySchema.optional(),
|
||||
limitations: z.array(z.string()).default([]),
|
||||
})
|
||||
.strict();
|
||||
@@ -288,7 +290,7 @@ export const parseFunctionDossier = (
|
||||
): Result<JsonValue, AnalysisOutputError> => {
|
||||
const parsed = functionDossierSchema.safeParse(value);
|
||||
return parsed.success
|
||||
? ok(parsed.data)
|
||||
? ok(jsonValueSchema.parse(parsed.data))
|
||||
: err(
|
||||
new AnalysisOutputError(
|
||||
"analyze_function",
|
||||
|
||||
@@ -0,0 +1,153 @@
|
||||
import { z } from "zod";
|
||||
|
||||
const inferenceConfidenceSchema = z.enum(["low", "medium", "high"]);
|
||||
|
||||
const inferenceEvidenceSchema = z
|
||||
.object({
|
||||
kind: z.enum([
|
||||
"signature-source",
|
||||
"decompiler-type",
|
||||
"type-lock",
|
||||
"calling-convention",
|
||||
"jump-table",
|
||||
]),
|
||||
source: z.string().min(1),
|
||||
detail: z.string().min(1),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const inferredBoundaryTypeSchema = z
|
||||
.object({
|
||||
role: z.enum(["return", "parameter"]),
|
||||
ordinal: z.number().int().min(0).nullable(),
|
||||
name: z.string().min(1).nullable(),
|
||||
data_type: z.string().min(1),
|
||||
size_bytes: z.number().int().min(0).nullable(),
|
||||
storage: z.string().min(1).nullable(),
|
||||
confidence: inferenceConfidenceSchema,
|
||||
evidence: z.array(inferenceEvidenceSchema).min(1),
|
||||
decompiler_artifacts: z.array(
|
||||
z.enum([
|
||||
"recovered-signature",
|
||||
"register-or-stack-storage",
|
||||
"compiler-generated-variable",
|
||||
]),
|
||||
),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const jumpTableDataSourceSchema = z
|
||||
.object({
|
||||
address: z.string().min(1),
|
||||
provenance: z.enum([
|
||||
"ghidra-decompiler-load-table",
|
||||
"ghidra-dispatch-block-data-reference",
|
||||
]),
|
||||
entry_size_bytes: z.number().int().min(1).nullable(),
|
||||
entry_count: z.number().int().min(0).nullable(),
|
||||
confidence: inferenceConfidenceSchema,
|
||||
evidence: z.array(inferenceEvidenceSchema).min(1),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const jumpTableMappingSchema = z
|
||||
.object({
|
||||
case_value: z.number().int().nullable(),
|
||||
target_address: z.string().min(1),
|
||||
data_addresses: z.array(z.string().min(1)),
|
||||
confidence: inferenceConfidenceSchema,
|
||||
evidence: z.array(inferenceEvidenceSchema).min(1),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const inferredJumpTableSchema = z
|
||||
.object({
|
||||
dispatch_address: z.string().min(1),
|
||||
data_sources: z.array(jumpTableDataSourceSchema),
|
||||
data_sources_truncated: z.boolean(),
|
||||
mappings: z.array(jumpTableMappingSchema),
|
||||
mappings_truncated: z.boolean(),
|
||||
limitations: z.array(z.string()),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const availableNativeApiBoundarySchema = z
|
||||
.object({
|
||||
available: z.literal(true),
|
||||
provenance: z.string().min(1),
|
||||
signature_source: z.string().min(1),
|
||||
calling_convention: z.string().min(1),
|
||||
return_type: inferredBoundaryTypeSchema,
|
||||
parameters: z.array(inferredBoundaryTypeSchema),
|
||||
parameters_truncated: z.boolean(),
|
||||
jump_tables: z.array(inferredJumpTableSchema),
|
||||
jump_tables_truncated: z.boolean(),
|
||||
pseudocode: z
|
||||
.object({
|
||||
classification: z.literal("decompiler-generated-non-source"),
|
||||
compilable: z.literal(false),
|
||||
})
|
||||
.strict(),
|
||||
decompiler_artifacts: z.array(
|
||||
z.enum([
|
||||
"recovered-signature",
|
||||
"register-and-stack-variables",
|
||||
"compiler-generated-control-flow",
|
||||
"pointer-arithmetic",
|
||||
"pseudocode",
|
||||
]),
|
||||
),
|
||||
limitations: z.array(z.string()),
|
||||
})
|
||||
.strict();
|
||||
|
||||
const unavailableNativeApiBoundarySchema = z
|
||||
.object({
|
||||
available: z.literal(false),
|
||||
reason: z.string().min(1),
|
||||
residual_unknowns: z.array(z.string().min(1)).min(1),
|
||||
})
|
||||
.strict();
|
||||
|
||||
/** Provider-neutral native API boundary observations attached to a function dossier. */
|
||||
export const nativeApiBoundarySchema = z.discriminatedUnion("available", [
|
||||
unavailableNativeApiBoundarySchema,
|
||||
availableNativeApiBoundarySchema,
|
||||
]);
|
||||
|
||||
/** One validated provider-neutral native API boundary observation. */
|
||||
export type NativeApiBoundary = z.infer<typeof nativeApiBoundarySchema>;
|
||||
|
||||
const nativeApiInspectionSubstepSchema = z
|
||||
.object({
|
||||
operation: z.enum([
|
||||
"analyze_function",
|
||||
"project_native_api_boundary",
|
||||
"preserve_residual_unknowns",
|
||||
]),
|
||||
status: z.enum(["completed", "unsupported"]),
|
||||
observations: z.array(z.string().min(1)),
|
||||
})
|
||||
.strict();
|
||||
|
||||
/** Agent-facing projection of structured native API reconstruction substeps. */
|
||||
export const nativeApiInspectionResultSchema = z
|
||||
.object({
|
||||
schema_version: z.literal(1),
|
||||
procedure: z
|
||||
.object({
|
||||
address: z.string().min(1),
|
||||
name: z.string().min(1),
|
||||
})
|
||||
.strict(),
|
||||
boundary: nativeApiBoundarySchema,
|
||||
substeps: z.array(nativeApiInspectionSubstepSchema).min(3).max(3),
|
||||
unsupported_branches: z.array(z.string().min(1)),
|
||||
residual_unknowns: z.array(z.string().min(1)),
|
||||
})
|
||||
.strict();
|
||||
|
||||
/** One validated agent-facing native API inspection result. */
|
||||
export type NativeApiInspectionResult = z.infer<
|
||||
typeof nativeApiInspectionResultSchema
|
||||
>;
|
||||
@@ -17,4 +17,4 @@ export const GHIDRA_MAX_QUEUED_REQUESTS = 32;
|
||||
/** Maximum encoded response line accepted from the Java bridge. */
|
||||
export const GHIDRA_MAX_LINE_BYTES = 1024 * 1024;
|
||||
/** Version of REA's Java bridge handshake and request protocol. */
|
||||
export const GHIDRA_BRIDGE_VERSION = 5;
|
||||
export const GHIDRA_BRIDGE_VERSION = 6;
|
||||
|
||||
@@ -11,6 +11,7 @@ import {
|
||||
jsonValueSchema,
|
||||
type JsonValue,
|
||||
} from "../domain/jsonValue.js";
|
||||
import { nativeApiBoundarySchema } from "../domain/nativeApiBoundary.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
import {
|
||||
ghidraBoundedIdentifierSchema,
|
||||
@@ -220,8 +221,40 @@ const procedureInfo = z
|
||||
})
|
||||
.strict();
|
||||
|
||||
const ghidraFunctionDossier = functionDossierSchema.superRefine(
|
||||
const ghidraNativeApiBoundary = nativeApiBoundarySchema.superRefine(
|
||||
(value, context) => {
|
||||
if (!value.available) return;
|
||||
if (value.provenance !== "ghidra-high-function")
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
message:
|
||||
"Ghidra native API observations require HighFunction provenance",
|
||||
});
|
||||
const addresses = value.jump_tables.flatMap((table) => [
|
||||
table.dispatch_address,
|
||||
...table.data_sources.map(({ address }) => address),
|
||||
...table.mappings.flatMap(({ target_address, data_addresses }) => [
|
||||
target_address,
|
||||
...data_addresses,
|
||||
]),
|
||||
]);
|
||||
if (
|
||||
addresses.some(
|
||||
(address) => !ghidraCanonicalAddressSchema.safeParse(address).success,
|
||||
)
|
||||
)
|
||||
context.addIssue({
|
||||
code: "custom",
|
||||
message:
|
||||
"Ghidra native API observation contains a non-canonical address",
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
const ghidraFunctionDossier = functionDossierSchema
|
||||
.extend({ native_api: ghidraNativeApiBoundary })
|
||||
.strict()
|
||||
.superRefine((value, context) => {
|
||||
const addresses = [
|
||||
value.procedure.address,
|
||||
...value.comments.items.map(({ address }) => address),
|
||||
@@ -288,8 +321,7 @@ const ghidraFunctionDossier = functionDossierSchema.superRefine(
|
||||
code: "custom",
|
||||
message: "Ghidra dossier omitted required uncertainty limitations",
|
||||
});
|
||||
},
|
||||
);
|
||||
});
|
||||
const ghidraFunctionInstructionWindow = functionInstructionWindowSchema
|
||||
.extend({ procedure: procedureIdentity })
|
||||
.strict();
|
||||
|
||||
@@ -223,6 +223,12 @@ const ENHANCED_INPUT_PARSERS: {
|
||||
input,
|
||||
"analyze_function",
|
||||
),
|
||||
inspect_native_api: (input) =>
|
||||
safeParseToolInput(
|
||||
enhancedInputSchemas.inspect_native_api,
|
||||
input,
|
||||
"inspect_native_api",
|
||||
),
|
||||
trace_feature: (input) =>
|
||||
safeParseToolInput(
|
||||
enhancedInputSchemas.trace_feature,
|
||||
@@ -293,6 +299,11 @@ const parseEnhancedCall = (
|
||||
ENHANCED_INPUT_PARSERS.analyze_function(input),
|
||||
(value) => ({ name, input: value }),
|
||||
);
|
||||
case "inspect_native_api":
|
||||
return mapEnhancedCall(
|
||||
ENHANCED_INPUT_PARSERS.inspect_native_api(input),
|
||||
(value) => ({ name, input: value }),
|
||||
);
|
||||
case "trace_feature":
|
||||
return mapEnhancedCall(
|
||||
ENHANCED_INPUT_PARSERS.trace_feature(input),
|
||||
@@ -335,9 +346,12 @@ const recordWorkflowUnknowns = ({
|
||||
| ReturnType<BinarySessionPort["recordUnknown"]>
|
||||
| { readonly ok: true; readonly value: null } => {
|
||||
if (
|
||||
!["trace_feature", "find_code_for_string", "trace_call_path"].includes(
|
||||
name,
|
||||
) ||
|
||||
![
|
||||
"trace_feature",
|
||||
"find_code_for_string",
|
||||
"trace_call_path",
|
||||
"inspect_native_api",
|
||||
].includes(name) ||
|
||||
input.unknown_registry_approved !== true ||
|
||||
recordUnknown === undefined ||
|
||||
typeof result !== "object" ||
|
||||
@@ -352,7 +366,7 @@ const recordWorkflowUnknowns = ({
|
||||
approved: true,
|
||||
question,
|
||||
severity: "medium",
|
||||
domain: "control-flow",
|
||||
domain: name === "inspect_native_api" ? "native-api" : "control-flow",
|
||||
supporting_evidence_ids: [evidenceId],
|
||||
contradicting_evidence_ids: [],
|
||||
required_authority: "shipped-artifact",
|
||||
@@ -361,7 +375,10 @@ const recordWorkflowUnknowns = ({
|
||||
recommended_probes: [
|
||||
{
|
||||
operation: name,
|
||||
rationale: "Continue with a larger bounded budget.",
|
||||
rationale:
|
||||
name === "inspect_native_api"
|
||||
? "Confirm the unsupported boundary with a capable provider or ABI probe."
|
||||
: "Continue with a larger bounded budget.",
|
||||
},
|
||||
],
|
||||
relationships: [],
|
||||
|
||||
Reference in New Issue
Block a user