* feat(native): search analyzed memory for masked byte patterns The diff adds search_bytes to the CLI, the shared MCP contract, Ghidra inventory, and the headless bridge, and advertises the same operation on Hopper as unavailable until that provider is verified. Patterns are hexadecimal byte pairs with optional ?? wildcards and an optional equal-length bit mask; the TypeScript boundary and the bridge both require a nonempty pattern, equal lengths, and at least one constrained bit. Ghidra walks initialized blocks in address order within inclusive bounds, keeps overlapping matches inside a single block, and returns each hit with its segment, unique source file offset, and containing procedure, continuing through a cursor bound to the target, profile, pattern, mask, and bounds. Each page reports the inclusive ranges examined and the skipped uninitialized blocks; cancellation returns a typed error and discards the active Ghidra database. address_to_file_offset now uses the same unique-offset helper, which rejects a mapping that is missing, ambiguous, or larger than a safe integer. * fix(native): limit unbounded byte search to loaded memory Without start or end, search_bytes walked every Ghidra block, including non-loaded file parts such as .symtab and overlay blocks, which the docs call out of scope. Unbounded searches now skip those blocks and list them in searched.skipped_not_loaded; explicit bounds in their address space still search them. Document that a match must end at or before end. * fix(native): preserve implicit address spaces in range consumers * fix(native): reject present malformed byte search state --------- Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
42 lines
2.0 KiB
TypeScript
42 lines
2.0 KiB
TypeScript
import { z } from "zod";
|
|
import { address, document } from "./toolContractHelpers.js";
|
|
import {
|
|
bytePatternFields,
|
|
validateBytePattern,
|
|
} from "../domain/native/bytePattern.js";
|
|
|
|
/** Hopper memory and file-mapping contracts. */
|
|
export const HOPPER_MEMORY_TOOL_DEFINITIONS = [
|
|
{
|
|
name: "search_bytes",
|
|
description:
|
|
"Find masked byte signatures in initialized analyzed memory. Hex byte pairs and ?? wildcards are supported; an optional equal-length hex mask selects bits. Bounds are inclusive. Matches are ordered by provider address and never span blocks. Coverage describes this page; reuse the same query with next_cursor to continue. Uninitialized blocks are listed separately. Ghidra only; Hopper is unavailable.",
|
|
inputSchema: z
|
|
.strictObject({
|
|
...bytePatternFields,
|
|
document,
|
|
start: address.optional(),
|
|
end: address.optional(),
|
|
limit: z.number().int().min(1).max(1000).default(100),
|
|
cursor: z.string().min(1).optional(),
|
|
})
|
|
.superRefine(validateBytePattern),
|
|
},
|
|
{
|
|
name: "read_bytes",
|
|
description:
|
|
"Read analyzed bytes from one provider-normalized virtual address. The hexadecimal payload reports the exact returned length; incomplete reads remain explicit and unsupported provider APIs return typed capability unavailability.",
|
|
inputSchema: z.object({
|
|
address,
|
|
length: z.number().int().min(1).default(256),
|
|
document,
|
|
}),
|
|
},
|
|
{
|
|
name: "address_to_file_offset",
|
|
description:
|
|
"Map one provider-normalized virtual address to its original nonnegative file offset. Hopper verifies the original bytes against the selected executable digest and translates FAT image-relative offsets using the loaded header. Results preserve the provider coordinate, image base, and source path. Unmapped addresses fail explicitly; changed or unavailable sources return typed errors retaining native mapping facts as partial evidence.",
|
|
inputSchema: z.object({ address, document }),
|
|
},
|
|
] as const;
|