Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(hopper): validate annotation destinations and symbol extents
morlutob2d5bc110914
diff --git a/bridge/hopper_bridge.py b/bridge/hopper_bridge.pyindex 8f3397e3e..492408342 100644--- a/bridge/hopper_bridge.py+++ b/bridge/hopper_bridge.py@@ -13,6 +13,8 @@ import socketfrom typing import Any, Optional, Protocol, SequenceBAD_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:continueif 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.mdindex 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 interioaddress; adjacent-object navigation rejects unmapped inputs and document ends.Native API text rejects NUL characters and unpaired Unicode surrogates beforeannotation 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'sbridge and removes its temporary socket directory while preserving the Hopperdiff --git a/scripts/lib/real-hopper-navigation.mjs b/scripts/lib/real-hopper-navigation.mjsindex 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.tsindex 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(