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)];
|
||||
};
|
||||
Reference in New Issue
Block a user