* feat(ghidra): admit set_address_name and set_addresses_names Ghidra sessions rejected the existing naming tools with "operation is not declared by this provider", so agents had to use annotate_native_function, which returns a complete function dossier per rename and cannot name data addresses. The Java bridge now names a local function entry (namespace-aware, like annotate_native_function) or creates/renames the primary label at any other mapped address, verifying readback. set_addresses_names applies each address in its own transaction and reports per-address booleans. Both are mutating capabilities: excluded from read-only (Windows P0) handshakes and from snapshot replay. * fix(ghidra): normalize qualified symbol names and reject empty leaves Share namespace-aware leaf normalization across functions and primary labels. Invalid qualified leaves now return false for naming operations without marking the provider unavailable; function annotations retain typed invalid-input errors. Extend real CLI/MCP namespace verification with namespaced globals, readback replay, failed-name rollback, mixed batches, and capability checks. Validation: 75 focused tests and npm run check pass. Ghidra 12.1.4/JDK 21 namespace verification passes on macOS arm64 with unchanged source bytes and complete cleanup. The full host lane passes this workflow before the existing entry-alias fixture fails because the compiler places its interior label at the function entry. --------- Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
328 lines
11 KiB
TypeScript
328 lines
11 KiB
TypeScript
import { z } from "zod";
|
|
import { nativeLoadImageObservationSchema } from "../domain/native/nativeLoadImage.js";
|
|
|
|
import {
|
|
type AnalysisInputError,
|
|
AnalysisOutputError,
|
|
} from "../domain/analysisErrorCore.js";
|
|
import {
|
|
functionBodySchema,
|
|
functionBodyEntryAgrees,
|
|
} from "../domain/hopperValues.js";
|
|
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
|
|
import { err, ok, type Result } from "../domain/result.js";
|
|
import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
|
|
|
|
/**
|
|
* Direct inventory operations admitted by the Ghidra adapter. All are reads
|
|
* except the naming operations, which edit the ephemeral session database.
|
|
*/
|
|
export const GHIDRA_INVENTORY_OPERATIONS = [
|
|
"inspect_native_load_image",
|
|
"read_bytes",
|
|
"address_to_file_offset",
|
|
"address_name",
|
|
"list_documents",
|
|
"list_names",
|
|
"list_procedures",
|
|
"list_segments",
|
|
"list_strings",
|
|
"procedure_address",
|
|
"resolve_containing_procedure",
|
|
"search_procedures",
|
|
"search_strings",
|
|
"set_address_name",
|
|
"set_addresses_names",
|
|
] as const;
|
|
|
|
/** Inventory operations that write analyst names into the session database. */
|
|
export const GHIDRA_NAMING_OPERATIONS = [
|
|
"set_address_name",
|
|
"set_addresses_names",
|
|
] as const satisfies readonly GhidraInventoryOperation[];
|
|
|
|
/** One direct inventory operation implemented by the packaged Java bridge. */
|
|
export type GhidraInventoryOperation =
|
|
(typeof GHIDRA_INVENTORY_OPERATIONS)[number];
|
|
|
|
const operationSet: ReadonlySet<string> = new Set(GHIDRA_INVENTORY_OPERATIONS);
|
|
|
|
/** Narrow an application operation to the Ghidra inventory surface. */
|
|
export const isGhidraInventoryOperation = (
|
|
operation: string,
|
|
): operation is GhidraInventoryOperation => operationSet.has(operation);
|
|
|
|
export const ghidraIdentifierSchema = z.string().min(1);
|
|
const identifier = ghidraIdentifierSchema;
|
|
const document = identifier.nullable().default(null);
|
|
/** Caller address spelling; the bridge resolves its space and emits canonical output. */
|
|
export const ghidraInputAddressSchema = z
|
|
.string()
|
|
.regex(
|
|
/^(?:(?:0[xX])?[0-9a-fA-F]+|(?:[A-Za-z0-9._~-]|%[0-9a-fA-F]{2})+:0[xX][0-9a-fA-F]+)$/u,
|
|
"Use hexadecimal digits, optionally prefixed with 0x, or an encoded address-space name followed by :0x and hexadecimal digits",
|
|
);
|
|
const explicitAddress = ghidraInputAddressSchema;
|
|
const filteredAddress = explicitAddress.nullable().default(null);
|
|
const searchInput = {
|
|
pattern: z.string().min(1),
|
|
mode: z.enum(["literal", "regex"]).default("literal"),
|
|
case_sensitive: z.boolean().default(false),
|
|
document,
|
|
};
|
|
|
|
const inputSchemas = {
|
|
inspect_native_load_image: z.strictObject({}),
|
|
read_bytes: z.strictObject({
|
|
document,
|
|
address: explicitAddress,
|
|
length: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).default(256),
|
|
}),
|
|
address_to_file_offset: z.strictObject({
|
|
document,
|
|
address: explicitAddress,
|
|
}),
|
|
address_name: z.object({ document, address: explicitAddress }).strict(),
|
|
list_documents: z.object({}).strict(),
|
|
list_names: z.object({ document, address: filteredAddress }).strict(),
|
|
list_procedures: z.object({ document }).strict(),
|
|
list_segments: z.object({ document }).strict(),
|
|
list_strings: z.object({ document, address: filteredAddress }).strict(),
|
|
procedure_address: z.object({ document, procedure: identifier }).strict(),
|
|
resolve_containing_procedure: z
|
|
.object({ document, address: explicitAddress })
|
|
.strict(),
|
|
search_procedures: z.object(searchInput).strict(),
|
|
search_strings: z.object(searchInput).strict(),
|
|
set_address_name: z
|
|
.object({ document, address: explicitAddress, name: z.string().min(1) })
|
|
.strict(),
|
|
set_addresses_names: z
|
|
.object({
|
|
document,
|
|
names: z.record(explicitAddress, z.string().min(1)),
|
|
})
|
|
.strict()
|
|
.refine(
|
|
(value) => Object.keys(value.names).length > 0,
|
|
"Supply at least one address name",
|
|
),
|
|
} satisfies Readonly<Record<GhidraInventoryOperation, z.ZodType>>;
|
|
|
|
/** Validate and default one provider request before it crosses the socket. */
|
|
export const parseGhidraInventoryInput = (
|
|
operation: GhidraInventoryOperation,
|
|
value: Readonly<Record<string, JsonValue>>,
|
|
): Result<Readonly<Record<string, JsonValue>>, AnalysisInputError> => {
|
|
const parsed = inputSchemas[operation].safeParse(value);
|
|
if (!parsed.success)
|
|
return err(
|
|
analysisInputErrorFromIssues(operation, parsed.error.issues, value, {
|
|
cause: parsed.error,
|
|
}),
|
|
);
|
|
return ok(parsed.data);
|
|
};
|
|
|
|
export const ghidraCanonicalAddressSchema = z
|
|
.string()
|
|
.regex(/^(?:0x[0-9a-f]+|(?:[A-Za-z0-9._~-]|%[0-9A-F]{2})+:0x[0-9a-f]+)$/u);
|
|
const canonicalAddress = ghidraCanonicalAddressSchema;
|
|
const symbolFacts = z
|
|
.object({
|
|
primary: z.boolean(),
|
|
dynamic: z.boolean(),
|
|
external: z.boolean(),
|
|
type: z.string().min(1),
|
|
source: z.enum(["default", "analysis", "ai", "imported", "user_defined"]),
|
|
})
|
|
.strict();
|
|
const procedureFacts = z
|
|
.object({
|
|
external: z.boolean(),
|
|
thunk: z.boolean(),
|
|
thunk_target: canonicalAddress.nullable(),
|
|
})
|
|
.strict();
|
|
/** Ghidra FunctionManager classification, independent of body ownership inference. */
|
|
export const ghidraFunctionClassificationSchema = procedureFacts
|
|
.extend({ provenance: z.literal("ghidra-function-manager") })
|
|
.strict();
|
|
/** Require complete canonical AddressSet evidence on every Ghidra function identity. */
|
|
export const ghidraFunctionBodySchema = functionBodySchema.superRefine(
|
|
(body, context) => {
|
|
if (
|
|
!body.available ||
|
|
body.provenance !== "ghidra-function-body-address-set" ||
|
|
body.ranges.some(
|
|
({ start, end }) =>
|
|
!ghidraCanonicalAddressSchema.safeParse(start).success ||
|
|
!ghidraCanonicalAddressSchema.safeParse(end).success,
|
|
)
|
|
)
|
|
context.addIssue({
|
|
code: "custom",
|
|
message:
|
|
"Ghidra omitted complete canonical function-body AddressSet evidence",
|
|
});
|
|
},
|
|
);
|
|
|
|
/** Strict provider identity shared by inventory and function-analysis results. */
|
|
export const ghidraProcedureIdentitySchema = z
|
|
.object({
|
|
address: ghidraCanonicalAddressSchema,
|
|
name: z.string().min(1),
|
|
classification: ghidraFunctionClassificationSchema,
|
|
body: ghidraFunctionBodySchema,
|
|
})
|
|
.strict()
|
|
.superRefine((value, context) => {
|
|
if (
|
|
!functionBodyEntryAgrees(value.body, value.address) ||
|
|
(value.body.available &&
|
|
!value.classification.external &&
|
|
!value.body.contains_entry)
|
|
)
|
|
context.addIssue({
|
|
code: "custom",
|
|
message: "Ghidra function body disagrees with its entry point",
|
|
});
|
|
});
|
|
|
|
const stringFacts = z
|
|
.object({
|
|
encoding: z.string().min(1),
|
|
termination: z.enum(["missing", "present_or_not_required"]),
|
|
byte_length: z.number().int().min(0),
|
|
})
|
|
.strict();
|
|
const baseItem = {
|
|
address: canonicalAddress,
|
|
value: z.string(),
|
|
};
|
|
const symbolItem = z.object({ ...baseItem, symbol: symbolFacts }).strict();
|
|
const procedureItem = z
|
|
.object({ ...baseItem, procedure: procedureFacts })
|
|
.strict();
|
|
const stringItem = z.object({ ...baseItem, string: stringFacts }).strict();
|
|
const searchItem = z.object(baseItem).strict();
|
|
|
|
const availablePermissions = z
|
|
.object({
|
|
available: z.literal(true),
|
|
source: z.literal("ghidra-memory-block"),
|
|
})
|
|
.strict();
|
|
const memoryRegion = z
|
|
.object({
|
|
name: z.string(),
|
|
start: canonicalAddress,
|
|
end: canonicalAddress,
|
|
readable: z.boolean(),
|
|
writable: z.boolean(),
|
|
executable: z.boolean(),
|
|
permissions: availablePermissions,
|
|
provenance: z.literal("ghidra-memory-block"),
|
|
address_space: z.string().min(1),
|
|
image_base: canonicalAddress,
|
|
initialized: z.boolean(),
|
|
overlay: z.boolean(),
|
|
})
|
|
.strict();
|
|
const segment = memoryRegion
|
|
.extend({ sections: z.array(memoryRegion) })
|
|
.strict();
|
|
const containingProcedure = z.discriminatedUnion("found", [
|
|
z
|
|
.object({
|
|
query_address: canonicalAddress,
|
|
found: z.literal(true),
|
|
procedure: ghidraProcedureIdentitySchema,
|
|
})
|
|
.strict()
|
|
.superRefine((value, context) => {
|
|
const body = value.procedure.body;
|
|
const exactExternalEntry =
|
|
value.procedure.classification.external &&
|
|
value.query_address === value.procedure.address;
|
|
if (
|
|
!exactExternalEntry &&
|
|
body.available &&
|
|
!functionBodyEntryAgrees(
|
|
{ ...body, contains_entry: true },
|
|
value.query_address,
|
|
)
|
|
)
|
|
context.addIssue({
|
|
code: "custom",
|
|
message:
|
|
"Found containing procedure body does not contain the query address",
|
|
});
|
|
}),
|
|
z
|
|
.object({
|
|
query_address: canonicalAddress,
|
|
found: z.literal(false),
|
|
procedure: z.null(),
|
|
reason: z.enum(["outside_segments", "not_in_procedure"]),
|
|
})
|
|
.strict(),
|
|
]);
|
|
|
|
const resultSchemas = {
|
|
inspect_native_load_image: nativeLoadImageObservationSchema,
|
|
read_bytes: z
|
|
.strictObject({
|
|
address: canonicalAddress,
|
|
requested_bytes: z.number().int().min(1),
|
|
returned_bytes: z.number().int().min(0),
|
|
bytes_hex: z.string().regex(/^(?:[a-f0-9]{2})*$/u),
|
|
complete: z.boolean(),
|
|
})
|
|
.superRefine((value, context) => {
|
|
if (
|
|
value.returned_bytes * 2 !== value.bytes_hex.length ||
|
|
value.returned_bytes > value.requested_bytes ||
|
|
value.complete !== (value.returned_bytes === value.requested_bytes)
|
|
)
|
|
context.addIssue({
|
|
code: "custom",
|
|
message: "Read-byte length and completeness disagree",
|
|
});
|
|
}),
|
|
address_to_file_offset: z.strictObject({
|
|
address: canonicalAddress,
|
|
file_offset: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
|
|
}),
|
|
address_name: z.string().nullable(),
|
|
list_documents: z.array(z.string().min(1)).length(1),
|
|
list_names: z.array(symbolItem),
|
|
list_procedures: z.array(procedureItem),
|
|
list_segments: z.array(segment),
|
|
list_strings: z.array(stringItem),
|
|
procedure_address: canonicalAddress,
|
|
resolve_containing_procedure: containingProcedure,
|
|
search_procedures: z.array(searchItem),
|
|
search_strings: z.array(searchItem),
|
|
set_address_name: z.boolean(),
|
|
set_addresses_names: z.record(z.string(), z.boolean()),
|
|
} satisfies Readonly<Record<GhidraInventoryOperation, z.ZodType>>;
|
|
|
|
/** Validate exact Java-bridge output before creating Evidence. */
|
|
export const parseGhidraInventoryResult = (
|
|
operation: GhidraInventoryOperation,
|
|
value: JsonValue,
|
|
): Result<JsonValue, AnalysisOutputError> => {
|
|
const parsed = resultSchemas[operation].safeParse(value);
|
|
return parsed.success
|
|
? ok(jsonValueSchema.parse(parsed.data))
|
|
: err(
|
|
new AnalysisOutputError(
|
|
operation,
|
|
"Ghidra bridge output did not match the inventory contract",
|
|
{ cause: parsed.error },
|
|
),
|
|
);
|
|
};
|