Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(hopper): validate annotation destinations and symbol extents

morlutob2d5bc110914
diff --git a/bridge/hopper_bridge.py b/bridge/hopper_bridge.py
index 8f3397e3e..492408342 100644
--- a/bridge/hopper_bridge.py
+++ b/bridge/hopper_bridge.py
@@ -13,6 +13,8 @@ import socket
from typing import Any, Optional, Protocol, Sequence
BAD_ADDRESSES = (-1, 0xFFFFFFFFFFFFFFFF, None)
+# The native label setter truncates NSString names at this UTF-16 extent.
+HOPPER_SYMBOL_NAME_UTF16_UNITS = 1024
_rea_session_document = None
_search_inventory_cache = {}
_pseudocode_cache = {}
@@ -211,6 +213,7 @@ def _validate_name_targets(document, names):
raise InvalidRequestError("Batch rename selects the same address more than once; use one canonical address per target")
labels = set()
for _, address, name in names:
+ _segment(document, address)
if not name:
continue
if name in labels:
@@ -221,6 +224,19 @@ def _validate_name_targets(document, names):
raise InvalidRequestError("Name %s is already assigned to %s; include that address in the batch with a replacement name" % (name, _hex(owner)))
+def _symbol_name(value, field):
+ """Reject native label truncation without altering the caller's name."""
+ value = _api_text(value, field)
+ if len(value.encode("utf-16-le")) // 2 > HOPPER_SYMBOL_NAME_UTF16_UNITS:
+ raise InvalidRequestError("%s exceeds Hopper's %s UTF-16 code-unit symbol-name limit" % (field, HOPPER_SYMBOL_NAME_UTF16_UNITS))
+ return value
+
+
+def _name_matches(document, address, name):
+ observed = _segment(document, address).getNameAtAddress(address)
+ return observed == name or (not name and observed is None)
+
+
def _address(document, value=None):
"""Keep explicit hexadecimal coordinates distinct from symbol names."""
if value is None:
@@ -849,25 +865,25 @@ def _dispatch(method, params):
}
if method == "set_address_name":
address = _address(document, params.get("address"))
- name = _api_text(params["name"], "Name")
+ name = _symbol_name(params["name"], "Name")
_validate_name_targets(document, [(params.get("address"), address, name)])
try:
result = document.setNameAtAddress(address, name)
finally:
_invalidate_search_inventory(document)
_invalidate_pseudocode(document)
- return result
+ return bool(result) and _name_matches(document, address, name)
if method == "set_addresses_names":
# Validate all destinations before applying any annotation. A malformed
# later address must not discard the result of an earlier mutation.
- names = [(key, _address(document, key), _api_text(value, "Name for %s" % key)) for key, value in params["names"].items()]
+ names = [(key, _address(document, key), _symbol_name(value, "Name for %s" % key)) for key, value in params["names"].items()]
_validate_name_targets(document, names)
try:
result = {key: document.setNameAtAddress(address, value) for key, address, value in names}
finally:
_invalidate_search_inventory(document)
_invalidate_pseudocode(document)
- return result
+ return {key: bool(result[key]) and _name_matches(document, address, value) for key, address, value in names}
if method in ("set_comment", "set_inline_comment"):
address = _address(document, params.get("address"))
comment = _api_text(params["comment"], "Comment")
@@ -882,6 +898,7 @@ def _dispatch(method, params):
return [{"address": _hex(item), "name": document.getBookmarkName(item)} for item in document.getBookmarks()]
if method == "set_bookmark":
address = _address(document, params.get("address"))
+ _segment(document, address)
name = params.get("name")
if name is not None:
_api_text(name, "Bookmark name")
@@ -889,6 +906,10 @@ def _dispatch(method, params):
return document.hasBookmarkAtAddress(address)
if method == "unset_bookmark":
address = _address(document, params.get("address"))
+ # Permit removing a legacy orphan bookmark, but do not report success
+ # for an unmapped address with no bookmark to remove.
+ if not document.hasBookmarkAtAddress(address):
+ _segment(document, address)
document.removeBookmarkAtAddress(address)
return not document.hasBookmarkAtAddress(address)
raise InvalidRequestError("Unknown bridge method")
diff --git a/docs/installation.md b/docs/installation.md
index dec6f60d0..7ac8053f3 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -323,7 +323,12 @@ Cursor navigation returns the observed object start when Hopper snaps an interio
address; adjacent-object navigation rejects unmapped inputs and document ends.
Native API text rejects NUL characters and unpaired Unicode surrogates before
annotation changes. Renames preserve unselected label owners; use a batch with
-all affected addresses to move or swap existing labels explicitly.
+all affected addresses to move or swap existing labels explicitly. Every rename
+destination must be mapped, and native symbol names must fit Hopper's 1024 UTF-16
+code-unit limit. Oversized names fail before any batch edits; bookmarks and
+literal string results are not subject to that symbol-name limit. Rename success
+requires exact final readback. New bookmarks must point into mapped memory;
+existing legacy bookmarks outside it can still be removed.
Closing or switching a target closes its bound Hopper document, shuts down REA's
bridge and removes its temporary socket directory while preserving the Hopper
diff --git a/scripts/lib/real-hopper-navigation.mjs b/scripts/lib/real-hopper-navigation.mjs
index 9d1eb1577..3ee47a7a5 100644
--- a/scripts/lib/real-hopper-navigation.mjs
+++ b/scripts/lib/real-hopper-navigation.mjs
@@ -13,144 +13,18 @@ export async function verifyHopperNavigationAndText(call, invalid, address) {
(item) => item.address === address,
);
try {
- const instructions = await call("read_function_instructions", {
- procedure: address,
+ await verifyNavigation(call, invalid, address, {
+ originalName,
+ originalComment,
+ originalInline,
});
- const info = await call("procedure_info", { procedure: address });
- assert.ok(info.locals.length > 0, "fixture omitted real stack locals");
- for (const local of info.locals) {
- assert.equal(typeof local.name, "string");
- assert.match(local.stack_displacement, /^-?\d+$/u);
- assert.ok(local.description.includes(local.name));
- assert.ok(local.description.includes(local.stack_displacement));
- assert.doesNotMatch(local.description, /object at 0x/u);
- }
- const dossier = await call("analyze_function", { procedure: address });
- assert.deepEqual(dossier.procedure.locals, info.locals);
- const coordinates = instructions.instructions.map(
- (line) => /^0x[0-9a-f]+/u.exec(line)?.[0],
- );
- assert.equal(coordinates[0], address);
- assert.ok(coordinates[1], "fixture omitted a second instruction");
- const interior = `0x${(BigInt(address) + 1n).toString(16)}`;
- assert.equal(await call("goto_address", { address: interior }), address);
- assert.equal(await call("current_address"), address);
- assert.equal(
- await call("next_address", { address: interior }),
- coordinates[1],
- );
- assert.equal(await call("prev_address", { address: interior }), address);
- for (const unmapped of ["0x0", "0xfffffffffffffffe"]) {
- for (const operation of ["goto_address", "next_address", "prev_address"])
- await invalid(
- operation,
- { address: unmapped },
- /Address is outside every segment/u,
- );
- assert.equal(await call("current_address"), address);
- }
- const segments = await call("list_segments");
- const first = segments.reduce((left, right) =>
- BigInt(left.start) < BigInt(right.start) ? left : right,
- );
- const last = segments.reduce((left, right) =>
- BigInt(left.end) > BigInt(right.end) ? left : right,
- );
- await invalid(
- "prev_address",
- { address: first.start },
- /No previous address exists in mapped memory/u,
- );
- await invalid(
- "next_address",
- { address: `0x${(BigInt(last.end) - 1n).toString(16)}` },
- /No adjacent analyzed object exists in mapped memory/u,
- );
-
- const comment = "REA representation boundary 测试";
- await call("set_comment", { address, comment });
- await call("set_inline_comment", { address, comment });
- await call("set_bookmark", { address, name: comment });
- for (const [text, reason] of [
- ["before\0after", /contains a NUL character/u],
- ["before\ud800after", /contains an unpaired Unicode surrogate/u],
- ]) {
- for (const operation of ["procedure_info", "read_bytes"])
- await invalid(
- operation,
- operation === "procedure_info"
- ? { procedure: text }
- : { address: text, length: 1 },
- reason,
- );
- for (const operation of ["set_address_name", "set_bookmark"])
- await invalid(operation, { address, name: text }, reason);
- for (const operation of ["set_comment", "set_inline_comment"])
- await invalid(operation, { address, comment: text }, reason);
- await invalid(
- "set_addresses_names",
- { names: { [address]: "must_not_apply", [other.address]: text } },
- reason,
- );
- assert.equal(await call("address_name", { address }), originalName);
- assert.equal(
- await call("address_name", { address: other.address }),
- other.value,
- );
- assert.equal(await call("comment", { address }), comment);
- assert.equal(await call("inline_comment", { address }), comment);
- assert.equal(
- (await call("list_bookmarks")).find((item) => item.address === address)
- ?.name,
- comment,
- );
- }
- await invalid(
- "set_address_name",
- { address, name: other.value },
- /already assigned to/u,
- );
- await invalid(
- "set_addresses_names",
- { names: { [address]: other.value } },
- /already assigned to/u,
- );
- await invalid(
- "set_addresses_names",
- { names: { [address]: "duplicate", [other.address]: "duplicate" } },
- /assigns the same name more than once/u,
- );
- await invalid(
- "set_addresses_names",
- { names: { [address]: "first", [address.slice(2)]: "second" } },
- /selects the same address more than once/u,
- );
- assert.equal(await call("address_name", { address }), originalName);
- assert.equal(
- await call("address_name", { address: other.address }),
- other.value,
- );
- try {
- const swapped = await call("set_addresses_names", {
- names: { [address]: other.value, [other.address]: originalName },
- });
- assert.equal(swapped[address], true);
- assert.equal(swapped[other.address], true);
- assert.equal(await call("address_name", { address }), other.value);
- assert.equal(
- await call("address_name", { address: other.address }),
- originalName,
- );
- } finally {
- await call("set_addresses_names", {
- names: { [address]: originalName, [other.address]: other.value },
- });
- }
+ await verifyAnnotationText(call, invalid, { address, other, originalName });
return {
cursorReadback: true,
interiorObjectNavigation: true,
unmappedNavigationRejected: true,
nativeTextValidationBeforeMutation: true,
+ mappedAnnotationValidationBeforeMutation: true,
unselectedLabelOwnersPreserved: true,
explicitLabelSwap: true,
observedLocalMetadata: true,
@@ -173,3 +47,180 @@ export async function verifyHopperNavigationAndText(call, invalid, address) {
});
}
}
+
+async function verifyNavigation(
+ call,
+ invalid,
+ address,
+ { originalName, originalComment, originalInline },
+) {
+ const instructions = await call("read_function_instructions", {
+ procedure: address,
+ });
+ const info = await call("procedure_info", { procedure: address });
+ assert.ok(info.locals.length > 0, "fixture omitted real stack locals");
+ for (const local of info.locals) {
+ assert.equal(typeof local.name, "string");
+ assert.match(local.stack_displacement, /^-?\d+$/u);
+ assert.ok(local.description.includes(local.name));
+ assert.ok(local.description.includes(local.stack_displacement));
+ assert.doesNotMatch(local.description, /object at 0x/u);
+ }
+ const dossier = await call("analyze_function", { procedure: address });
+ assert.deepEqual(dossier.procedure.locals, info.locals);
+ const coordinates = instructions.instructions.map(
+ (line) => /^0x[0-9a-f]+/u.exec(line)?.[0],
+ );
+ assert.equal(coordinates[0], address);
+ assert.ok(coordinates[1], "fixture omitted a second instruction");
+ const interior = `0x${(BigInt(address) + 1n).toString(16)}`;
+ assert.equal(await call("goto_address", { address: interior }), address);
+ assert.equal(await call("current_address"), address);
+ assert.equal(
+ await call("next_address", { address: interior }),
+ coordinates[1],
+ );
+ assert.equal(await call("prev_address", { address: interior }), address);
+ for (const unmapped of ["0x0", "0xfffffffffffffffe"]) {
+ for (const operation of ["goto_address", "next_address", "prev_address"])
+ await invalid(
+ operation,
+ { address: unmapped },
+ /Address is outside every segment/u,
+ );
+ assert.equal(await call("current_address"), address);
+ for (const operation of [
+ "set_address_name",
+ "set_bookmark",
+ "unset_bookmark",
+ "set_comment",
+ "set_inline_comment",
+ ])
+ await invalid(
+ operation,
+ {
+ address: unmapped,
+ ...(operation === "unset_bookmark"
+ ? {}
+ : operation.endsWith("comment")
+ ? { comment: "must_not_apply" }
+ : { name: "must_not_apply" }),
+ },
+ /Address is outside every segment/u,
+ );
+ await invalid(
+ "set_addresses_names",
+ { names: { [address]: "must_not_apply", [unmapped]: "unmapped" } },
+ /Address is outside every segment/u,
+ );
+ assert.equal(await call("address_name", { address }), originalName);
+ assert.equal(await call("comment", { address }), originalComment);
+ assert.equal(await call("inline_comment", { address }), originalInline);
+ assert.ok(
+ !(await call("list_bookmarks")).some((item) => item.address === unmapped),
+ );
+ }
+ const segments = await call("list_segments");
+ const first = segments.reduce((left, right) =>
+ BigInt(left.start) < BigInt(right.start) ? left : right,
+ );
+ const last = segments.reduce((left, right) =>
+ BigInt(left.end) > BigInt(right.end) ? left : right,
+ );
+ await invalid(
+ "prev_address",
+ { address: first.start },
+ /No previous address exists in mapped memory/u,
+ );
+ await invalid(
+ "next_address",
+ { address: `0x${(BigInt(last.end) - 1n).toString(16)}` },
+ /No adjacent analyzed object exists in mapped memory/u,
+ );
+}
+
+async function verifyAnnotationText(
+ call,
+ invalid,
+ { address, other, originalName },
+) {
+ const comment = "REA representation boundary 测试";
+ await call("set_comment", { address, comment });
+ await call("set_inline_comment", { address, comment });
+ await call("set_bookmark", { address, name: comment });
+ for (const [text, reason] of [
+ ["before\0after", /contains a NUL character/u],
+ ["before\ud800after", /contains an unpaired Unicode surrogate/u],
+ ]) {
+ for (const operation of ["procedure_info", "read_bytes"])
+ await invalid(
+ operation,
+ operation === "procedure_info"
+ ? { procedure: text }
+ : { address: text, length: 1 },
+ reason,
+ );
+ for (const operation of ["set_address_name", "set_bookmark"])
+ await invalid(operation, { address, name: text }, reason);
+ for (const operation of ["set_comment", "set_inline_comment"])
+ await invalid(operation, { address, comment: text }, reason);
+ await invalid(
+ "set_addresses_names",
+ { names: { [address]: "must_not_apply", [other.address]: text } },
+ reason,
+ );
+ assert.equal(await call("address_name", { address }), originalName);
+ assert.equal(
+ await call("address_name", { address: other.address }),
+ other.value,
+ );
+ assert.equal(await call("comment", { address }), comment);
+ assert.equal(await call("inline_comment", { address }), comment);
+ assert.equal(
+ (await call("list_bookmarks")).find((item) => item.address === address)
+ ?.name,
+ comment,
+ );
+ }
+ await invalid(
+ "set_address_name",
+ { address, name: other.value },
+ /already assigned to/u,
+ );
+ await invalid(
+ "set_addresses_names",
+ { names: { [address]: other.value } },
+ /already assigned to/u,
+ );
+ await invalid(
+ "set_addresses_names",
+ { names: { [address]: "duplicate", [other.address]: "duplicate" } },
+ /assigns the same name more than once/u,
+ );
+ await invalid(
+ "set_addresses_names",
+ { names: { [address]: "first", [address.slice(2)]: "second" } },
+ /selects the same address more than once/u,
+ );
+ assert.equal(await call("address_name", { address }), originalName);
+ assert.equal(
+ await call("address_name", { address: other.address }),
+ other.value,
+ );
+ try {
+ const swapped = await call("set_addresses_names", {
+ names: { [address]: other.value, [other.address]: originalName },
+ });
+ assert.equal(swapped[address], true);
+ assert.equal(swapped[other.address], true);
+ assert.equal(await call("address_name", { address }), other.value);
+ assert.equal(
+ await call("address_name", { address: other.address }),
+ originalName,
+ );
+ } finally {
+ await call("set_addresses_names", {
+ names: { [address]: originalName, [other.address]: other.value },
+ });
+ }
+}
diff --git a/src/contracts/officialToolContracts.ts b/src/contracts/officialToolContracts.ts
index 82502e211..0377f4b61 100644
--- a/src/contracts/officialToolContracts.ts
+++ b/src/contracts/officialToolContracts.ts
@@ -203,17 +203,17 @@ export const OFFICIAL_TOOL_CONTRACTS = [
),
official(
"set_address_name",
- "Assign an analyst name to one hexadecimal address and report Hopper's boolean result. Reject names owned by another address; use set_addresses_names to explicitly move or swap labels among selected addresses. This mutates analysis metadata.",
+ "Assign an analyst name to one mapped hexadecimal address and report whether the native edit succeeded and exact readback matched. Hopper rejects symbol names exceeding 1024 UTF-16 code units before mutation, and rejects names owned by another address; use set_addresses_names to explicitly move or swap labels among selected addresses. This mutates analysis metadata.",
z.object({ address, name: z.string(), document }),
),
official(
"set_addresses_names",
- "Assign analyst names to multiple addresses in one call and return per-address success booleans. Hopper validates addresses, native string representations, and unique destinations/names before applying edits. Existing labels may move or swap only among explicitly selected addresses; unselected label owners remain unchanged. This mutates analysis metadata; verify failures individually.",
+ "Assign analyst names to multiple mapped addresses in one call and return per-address edit/readback success booleans. Hopper validates mapped destinations, native string representations, its 1024 UTF-16 code-unit symbol-name limit, and unique destinations/names before applying edits. Existing labels may move or swap only among explicitly selected addresses; unselected label owners remain unchanged. This mutates analysis metadata; verify failures individually.",
z.object({ names: z.record(z.string(), z.string()), document }),
),
official(
"set_bookmark",
- "Create or replace a bookmark at a hexadecimal address and report success. This mutates navigation metadata; bookmarks are analyst-authored navigation aids, not binary evidence.",
+ "Create or replace a bookmark at a mapped hexadecimal address and report success. This mutates navigation metadata; bookmarks are analyst-authored navigation aids, not binary evidence.",
z.object({ address, name: z.string().optional(), document }),
),
official(
@@ -228,7 +228,7 @@ export const OFFICIAL_TOOL_CONTRACTS = [
),
official(
"unset_bookmark",
- "Remove the bookmark at a hexadecimal address and return whether it is absent. This mutates navigation metadata and does not alter binary bytes.",
+ "Remove the bookmark at a mapped hexadecimal address and return whether it is absent. Hopper also permits removing an existing legacy bookmark outside mapped memory. This mutates navigation metadata and does not alter binary bytes.",
z.object({ address, document }),
),
official(