* 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>
109 lines
3.7 KiB
TypeScript
109 lines
3.7 KiB
TypeScript
import type {
|
|
CapabilityDescriptor,
|
|
ProviderIdentity,
|
|
} from "../application/AnalysisProvider.js";
|
|
import type { OfficialToolName } from "../contracts/officialToolContracts.js";
|
|
|
|
/** Public identity committed by every Hopper-backed observation. */
|
|
export const HOPPER_PROVIDER_IDENTITY: ProviderIdentity = Object.freeze({
|
|
id: "hopper",
|
|
name: "Hopper Disassembler",
|
|
version: null,
|
|
});
|
|
|
|
/** Analyst operations implemented by REA's private Hopper bridge. */
|
|
export const HOPPER_OPERATIONS = Object.freeze([
|
|
"address_name",
|
|
"comment",
|
|
"current_address",
|
|
"current_procedure",
|
|
"current_document",
|
|
"goto_address",
|
|
"inline_comment",
|
|
"list_bookmarks",
|
|
"list_documents",
|
|
"list_names",
|
|
"list_procedures",
|
|
"list_segments",
|
|
"list_strings",
|
|
"next_address",
|
|
"prev_address",
|
|
"procedure_address",
|
|
"procedure_assembly",
|
|
"procedure_callees",
|
|
"procedure_callers",
|
|
"procedure_info",
|
|
"read_function_instructions",
|
|
"read_bytes",
|
|
"address_to_file_offset",
|
|
"procedure_references",
|
|
"procedure_pseudo_code",
|
|
"resolve_containing_procedure",
|
|
"search_procedures",
|
|
"search_strings",
|
|
"set_address_name",
|
|
"set_addresses_names",
|
|
"set_bookmark",
|
|
"set_comment",
|
|
"set_inline_comment",
|
|
"unset_bookmark",
|
|
"xrefs",
|
|
"analyze_function",
|
|
] as const satisfies readonly (OfficialToolName | "analyze_function")[]);
|
|
|
|
const MUTATING_OPERATIONS = new Set<string>([
|
|
"set_address_name",
|
|
"set_addresses_names",
|
|
"set_bookmark",
|
|
"set_comment",
|
|
"set_inline_comment",
|
|
"unset_bookmark",
|
|
]);
|
|
|
|
/** Source-owned capabilities without acquiring or probing a Hopper session. */
|
|
export const CAPABILITIES: readonly CapabilityDescriptor[] = Object.freeze(
|
|
[...HOPPER_OPERATIONS, "search_bytes" as const].map((operation) =>
|
|
Object.freeze({
|
|
provider: HOPPER_PROVIDER_IDENTITY,
|
|
operation,
|
|
...(operation === "search_bytes"
|
|
? {
|
|
available: false as const,
|
|
reason: "Masked byte search has not been verified for Hopper.",
|
|
}
|
|
: { available: true as const, reason: null }),
|
|
effects: Object.freeze({
|
|
mutatesArtifact: MUTATING_OPERATIONS.has(operation),
|
|
launchesProcess: true,
|
|
mayShowUi: true,
|
|
mayAccessNetwork: false,
|
|
mayWriteFilesystem: MUTATING_OPERATIONS.has(operation),
|
|
changesPermissions: false,
|
|
requiresRoot: false,
|
|
}),
|
|
limitations: Object.freeze([
|
|
"Results depend on Hopper's completed static analysis.",
|
|
...(operation === "address_to_file_offset"
|
|
? [
|
|
"Original-file coordinates require source bytes matching the selected executable digest. A changed, unavailable, or database-only source retains native mapping facts in partial error evidence.",
|
|
]
|
|
: []),
|
|
...(operation === "search_strings" || operation === "search_procedures"
|
|
? [
|
|
"Regex mode uses ECMAScript Unicode semantics in a supervised worker with a five-second matching deadline. Cancellation or deadline failure stops matching without blocking Hopper; literal mode retains native casefold semantics.",
|
|
]
|
|
: []),
|
|
...(operation === "list_strings" ||
|
|
operation === "search_strings" ||
|
|
operation === "analyze_function"
|
|
? [
|
|
"String values cover native typed objects. Hopper may split long literals into adjacent unterminated fragments; string searches match each object independently.",
|
|
"Undecodable typed objects retain native display text with an explicit decoding unknown; these values do not establish decoded source literals.",
|
|
"Reported string encodings are inferred from typed bytes and native display; the original source's intended encoding is unknown.",
|
|
]
|
|
: []),
|
|
]),
|
|
}),
|
|
),
|
|
);
|