Compare commits

...
Author SHA1 Message Date
N0zoM1z0factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>Kaoru0822morluto
44457d0990 fix(javascript): integrate Reflect.set receiver mutation coverage
Retain concurrent explicit receiver and opaque argument coverage while
preserving corrected call/apply receiver controls and the public CLI/MCP
fixture. Keep the complete invocation follow-up history without rewriting it.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-10-11 17:06:34 +00:00
N0zoM1z0factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>Kaoru0822morluto
2e860e2823 fix(javascript): integrate intrinsic binding and receiver proofs
Preserve generic binding factories and replaced-intrinsic checks from the
concurrent follow-up. Resolve call/apply by actual callable receiver rather
than nominal property-chain depth. Retain deep invocation, bound receiver,
fresh-target and public CLI/MCP regression coverage.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-10-11 17:01:30 +00:00
morluto c98d326514 fix(javascript): retain Reflect set receiver effects 2026-10-12 01:01:18 +08:00
morluto ad27b8b4ff fix(javascript): prove generic binding and invocation effects 2026-10-12 00:55:02 +08:00
N0zoM1z0factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>Kaoru0822
0285701033 fix(javascript): preserve callable receivers through generic invocations
Follow actual callable receivers for Function.prototype.call and apply,
including bound and rebinding forms. Treat call/apply projections as generic
function values instead of stripping arguments by property-chain depth.
Keep opaque arguments conservative and preserve fresh local target identity.
Cover uncurry, nested chains and the public CLI/MCP boundary.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
2026-10-11 16:50:52 +00:00
morluto 3e9bce6249 fix(javascript): preserve bound receivers for intrinsic invocation 2026-10-12 00:39:01 +08:00
morluto 1e1a611012 fix(javascript): retain bound intrinsic mutation effects 2026-10-12 00:34:35 +08:00
N0zoM1z0factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>Kaoru0822
b60248c462 fix(javascript): integrate current main stability fixes
Include the merged Hopper reconnect-listener readiness fix so local and CI
validation use the same current main recovery boundary.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
2026-10-11 16:25:37 +00:00
N0zoM1z0factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>Kaoru0822
2a9fdde5db fix(javascript): retain stable declarations and bound intrinsic writes
Keep repeated variable declarations with one unconditional initializer while
rejecting assignments, conditional initialization and multiple values.
Normalize known intrinsic calls, aliases and bound argument prefixes at the
semantic owner, retaining opaque targets without tainting unused bindings or
fresh local objects. Cover both regressions through source and CLI/MCP tests.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
2026-10-11 16:25:15 +00:00
morluto 3d1d5b56b2 fix(javascript): preserve proven interop result projections 2026-10-12 00:10:02 +08:00
7c207c7951 feat(native): admit raw binaries with caller-supplied architecture and entry (#1868)
* feat(native): admit raw binaries with caller-supplied architecture and entry

* fix(native): honor raw-binary preparation and entry identity

* fix(ghidra): stream raw snapshot attestation with cancellation

* fix(native): preserve and validate raw lifecycle entries

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-10-12 00:06:29 +08:00
YsopwnableGitHubfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>Kaoru0822
d3e83b0899 fix(test): wait for Hopper reconnect listener readiness (#1885)
The socket path exists after bind but before listen. Wait up to two seconds
for the initial connection on ConnectionRefusedError, closing each failed
socket. Propagate other errors and keep reconnect attempts immediate.
Preserve authentication, lost replies, expiry, cleanup and thread assertions.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
2026-10-12 00:02:01 +08:00
morluto 6b460683d7 fix(javascript): respect hoisted fresh function declarations
Function declarations provide fresh targets before their textual position. Retain initialization-order checks for variable and class values, including aliases. Cover the reviewed regression with source controls and the public CLI/MCP fixture.
2026-10-11 23:56:06 +08:00
29d2624b34 fix(ghidra): report progress while startup is pending (#1877)
Forward Ghidra startup waiting observations through the existing progress reporter. Count emitted MCP status notifications and omit the unknown total to keep progress strictly increasing.

Verified with focused tests, type/lint/docs checks, packaging and actual installed Windows timeout/recovery workflows. Native first-query speed and large-target memory remain open under #1065.

Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
2026-10-11 23:55:39 +08:00
morluto 548a4334c4 fix(javascript): preserve intrinsic alias capture timing
Validate each alias read after initialization and retain the original function capture across copies. Share declaration initializer facts with RPC and Electron analysis, including class declarations used for fresh-target identity. Accept single-statement control blocks while keeping lexical roles and added operations checked. Cover the capture regressions through inert source and public CLI/MCP workflows.
2026-10-11 23:53:55 +08:00
Dery FerdikaandGitHub fa9a7e5ec0 fix(evidence): reject NUL bytes in subject and snapshot paths (#1873)
Evidence subject local_path and analysis-snapshot subject path accepted
any string, so a caller-supplied inline Evidence record could carry a NUL
byte into the observation and bundle output even though every other
selected-path boundary already refuses it. Both fields now use the shared
NUL-free local-path schema: the snapshot path keeps its nonempty rule,
and the Evidence local_path stays free to be empty because network
capture Evidence uses an empty path as a deliberate sentinel.

localPath.ts now exports the NUL-free base schema separately so the
nonempty rule is composed rather than duplicated; the advertised pattern
and minLength for existing localPathStringSchema consumers are unchanged.

Validation: new unit cases reject a NUL local_path and snapshot path while
admitting an empty Evidence path and an ordinary path; domain suite
126 files / 1704 tests pass, evidence bundle and retained-evidence MCP
boundaries pass, localToolContracts NUL harness passes, toolSchemaValidity
passes with a regenerated catalog, typecheck, oxlint, oxfmt.
2026-10-11 23:45:37 +08:00
N0zoM1z0factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>Kaoru0822
b03df22ce4 fix(javascript): retain fresh function and class target identity
Recognize stable local function, undecorated class and RegExp targets before
widening intrinsic mutations. Keep decorated classes opaque because their
binding value can be replaced, and preserve class-initialization writes.
Cover fresh targets and replacement decorators in inert CLI/MCP fixtures.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
2026-10-11 15:41:00 +00:00
YsopwnableGitHubfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>Kaoru0822
efbc25fbea fix(android): preserve executable static initializer evidence (#1876)
Return the exact static initializer disassembly before Java projection can
lose field assignments. Retain byte limits and representation markers, and
verify fully folded and mixed initialization through the real CLI/MCP lane.

Closes #1846

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
2026-10-11 23:40:42 +08:00
pablodiazjorgeandGitHub ea40f717b2 fix(windows): bring the real Windows Ghidra verifiers up to date (#1863) 2026-10-11 23:38:34 +08:00
N0zoM1z0factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>Kaoru0822
5569e96162 fix(javascript): preserve intrinsic projections and fresh target identity
Resolve known mutators through static binding projections and prove stable
identifier chains to fresh literals before widening unknown mutation targets.
Keep reassigned, uninitialized and member-projected targets conservative.
Cover both review regressions through source tests and inert CLI/MCP fixtures.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
2026-10-11 15:22:12 +00:00
N0zoM1z0factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>Kaoru0822
47f8156efe fix(javascript): integrate current provider timeout recovery
Include the main-branch Hopper startup timeout normalization already merged
in #1866 so combined CI retains launcher diagnostics when either timer fires.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
2026-10-11 14:53:16 +00:00
N0zoM1z0factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>Kaoru0822
824728d7ee fix(javascript): retain destructured intrinsic writes
Share one pattern-target walker across lexical definitions, member mutation
tracking and Electron identity writes. Keep overwritten globals unresolved
without treating property keys or shadowed locals as global replacements.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
2026-10-11 14:43:17 +00:00
N0zoM1z0factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>Kaoru0822
ced8778094 refactor(javascript): share AST child field metadata
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
2026-10-11 14:19:51 +00:00
N0zoM1z0andfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> 6d470fc9cb fix(javascript): integrate current managed and stability fixes
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
2026-10-11 14:07:53 +00:00
N0zoM1z0andfactory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> 9788112548 fix(javascript): integrate verified namespace interop with main
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
2026-10-11 14:06:55 +00:00
N0zoM1z0 ebaa639cf8 fix(javascript): prove Electron module namespace conversion 2026-10-11 13:59:19 +00:00
91 changed files with 5178 additions and 621 deletions
@@ -2,7 +2,7 @@
name: reverse-engineer-anything
description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
metadata:
version: "38"
version: "39"
---
# REA
@@ -150,6 +150,13 @@ For headerless DOS COM, explicitly open with `format: "dos-com"` (CLI
analysis: the entry is `0x10100`, file offset zero, with imposed real-mode segment
context. PSP/stack/device state remains unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/ghidra-dos.md).
For other headerless images (embedded firmware without ELF/Mach-O/PE/MZ
headers), open with `format: "raw-binary"`, `architecture` (`x86`, `x86_64`,
`arm`, or `arm64`), and `entry_point` (`0x` hex). File offset 0 is mapped at
that address. Hopper and IDA refuse this interpretation; Ghidra uses
`BinaryLoader` with a little-endian generic language. Big-endian, Thumb-only,
and Cortex-M variants are unsupported. See [raw binary guide](https://github.com/morluto/rea/blob/main/docs/raw-binary.md).
### Function annotations in Ghidra
Use `annotate_native_function` for one function name and/or entry comments, with at least one explicit change. Review its annotation readback and refreshed dossier inline. Changes are atomic and session-scoped; empty comments clear them, omitted fields preserve them. Later MCP calls observe edits until close. CLI `annotate-native-function` returns the updated analysis before discarding the session. Original executable bytes are unchanged; edits invalidate immutable snapshots. Windows P0 does not admit database mutations. For naming only, `set_address_name` / `set_addresses_names` also work with Ghidra: they name function entries or data addresses (primary labels) and return compact per-address success booleans instead of a dossier.
+16 -2
View File
@@ -126,6 +126,20 @@ class ReaJadxBridge {
return result;
}
private JadxSession.SmartCode methodBody(JadxSession current, ClassSnapshot cls,
MethodSnapshot selected, JavaMethod method) {
if (!selected.shortId().equals("<clinit>()V"))
return current.getMethodBodySmart(method, current.getMaxSourceBytes(), true);
// Java code generation can fold all or part of <clinit> into field declarations.
// Its method text cannot establish coverage, even when a static block remains.
JadxSession.MethodSmali smali = current.getMethodSmali(cls.node(), method.getName());
if (!smali.getFound() || smali.getBlocks().size() != 1)
throw new IllegalArgumentException("Static initializer disassembly requires one exact method: " + selected.shortId());
return new JadxSession.SmartCode(
TextUtilKt.truncateToBytes(smali.getBlocks().get(0), current.getMaxSourceBytes()),
"smali", true, List.of("static_initializer_disassembly"));
}
private CallToolResult handle(String name, JsonObject args) {
if (name.equals("rea_jvm_status")) return json(Map.of(
"engine_reported_version", BuildInfo.VERSION,
@@ -150,7 +164,7 @@ class ReaJadxBridge {
int index = integer(args, "overload_index", 0);
if (index >= overloads.size()) throw new InputFailure("overload_index", "overload_index out of range: " + index);
JavaMethod method = method(cls, overloads.get(index));
JadxSession.SmartCode code = current.getMethodBodySmart(method, current.getMaxSourceBytes(), true);
JadxSession.SmartCode code = methodBody(current, cls, overloads.get(index), method);
return json(Map.of("class_name", cls.summary().get("full_name"),
"method_name", overloads.get(index).name(), "full_name", method.getFullName(),
"overload_index", index, "overload_count", overloads.size(),
@@ -211,7 +225,7 @@ class ReaJadxBridge {
String description = switch (name) {
case "list_classes" -> "Indexed pages of all top-level class names, with offset and limit.";
case "get_class_summary" -> "Parsed member metadata for one exact class name; no source generation.";
case "get_method_body" -> "Source for an exact class and stable same-name overload index, with smali fallback.";
case "get_method_body" -> "Source for an exact class and stable same-name overload index; static initializers use smali to preserve folded field initialization.";
default -> "Complete static references to an exact class or unique method; source lines are unresolved.";
};
Tool narrowed = new Tool(name, new ToolSchema(null, new JsonObject(properties),
+11 -4
View File
@@ -182,10 +182,17 @@ public final class ReaGhidraBridge extends HeadlessScript {
}
sessionDefaultAddressSpace =
currentProgram.getAddressFactory().getDefaultAddressSpace();
if (currentProgram.getExecutableFormat().equals("Raw Binary") &&
!currentProgram.getOptions(ghidra.program.model.listing.Program.PROGRAM_INFO)
.getBoolean("REA DOS COM prepared", false)) {
throw new IllegalStateException("REA DOS COM entry/context preparation failed");
if (currentProgram.getExecutableFormat().equals("Raw Binary")) {
boolean dosCom = currentProgram.getLanguageID().getIdAsString()
.equals("x86:LE:16:Real Mode");
String preparation = dosCom ? "REA DOS COM prepared" : "REA raw binary prepared";
if (!currentProgram.getOptions(ghidra.program.model.listing.Program.PROGRAM_INFO)
.getBoolean(preparation, false)) {
throw new IllegalStateException(
dosCom ? "REA DOS COM entry/context preparation failed" :
"REA raw binary entry preparation failed"
);
}
}
if (!Application.getApplicationVersion().equals(descriptor.providerVersion)) {
throw new IllegalStateException("Ghidra provider version does not match the session");
+36
View File
@@ -0,0 +1,36 @@
import ghidra.app.script.GhidraScript;
import ghidra.program.model.address.Address;
import ghidra.program.model.listing.Program;
/** Seed the caller-supplied raw-binary entry before default auto-analysis. */
public final class ReaGhidraPrepareRaw extends GhidraScript {
@Override
public void run() throws Exception {
String[] arguments = getScriptArgs();
if (arguments.length != 2) {
throw new IllegalArgumentException(
"Raw binary preparation requires the committed language and entry address"
);
}
String expectedLanguage = arguments[0];
String entryHex = arguments[1];
if (!currentProgram.getLanguageID().getIdAsString().equals(expectedLanguage) ||
!currentProgram.getExecutableFormat().equals("Raw Binary")) {
throw new IllegalArgumentException(
"Raw binary preparation requires the committed language and BinaryLoader import"
);
}
Address entry = currentProgram.getAddressFactory().getDefaultAddressSpace().getAddress(entryHex);
Address start = currentProgram.getMinAddress();
if (entry == null || !entry.equals(start)) {
throw new IllegalArgumentException(
"Raw binary import must map file offset 0 at the caller-supplied entry"
);
}
addEntryPoint(entry);
if (!disassemble(entry) || createFunction(entry, "entry") == null) {
throw new IllegalStateException("Raw binary entry cannot be decoded as a function");
}
currentProgram.getOptions(Program.PROGRAM_INFO).setBoolean("REA raw binary prepared", true);
}
}
+1
View File
@@ -54,6 +54,7 @@ export default defineConfig({
{ text: "IDA", link: "/ida-provider" },
{ text: "Ghidra on Windows", link: "/windows-ghidra-p0" },
{ text: "Ghidra DOS analysis", link: "/ghidra-dos" },
{ text: "Ghidra raw binary", link: "/raw-binary" },
{ text: "Ghidra NativeAOT", link: "/ghidra-nativeaot" },
{ text: "Ghidra semantics", link: "/ghidra-provider" },
],
+6
View File
@@ -94,6 +94,12 @@ fallback for an overloaded method instead of attributing all bodies to one
selected overload. Native/abstract methods with no decompiled body report
`body_status: "not_available"` without inferring which implementation flag caused it.
Static initializers (`<clinit>`) return smali with the
`static_initializer_disassembly` marker. Java decompilation can move their
instructions into field declarations, leaving an empty or incomplete method
body. The selected method's disassembly preserves those instructions and retains
the same source byte limit and explicit truncation reporting.
## Interpret the result
- Package inspection retains decoded manifest XML, summary declarations,
+2 -1
View File
@@ -59,7 +59,8 @@ alone, use `rea instructions`. A macOS `.app` bundle can be supplied directly.
Run `rea --help` or a command's `--help` for arguments and output options.
The [generated catalog](product-catalog.json) lists all CLI commands and MCP
tools. Provider-specific target support is described in the
[native guide](native-investigation.md), [DOS guide](ghidra-dos.md), and
[native guide](native-investigation.md), [DOS guide](ghidra-dos.md),
[raw binary guide](raw-binary.md), and
[Windows Ghidra guide](windows-ghidra-p0.md).
## Choose a provider
+38 -9
View File
@@ -323,15 +323,44 @@ substitute version-dependent Electron defaults for omitted `webPreferences`.
Dynamic option objects, bridge keys, API objects, and IPC channel expressions
remain unknown and make coverage partial.
Electron API identity follows proven lexical module aliases. Bundled CommonJS
namespace imports are also followed through the interop helpers that bundlers
and compilers emit (`__toESM`, `__importStar`, `_interopRequireWildcard`),
including the `electron = __toESM(electron)` rewrap that Rolldown emits. This
step is inferred: a helper is recognized by its emitted name and a single
program-scope function definition, and its body is not evaluated, so a local
function that reuses one of these names is trusted to pass the module through.
Other reassigned bindings, dynamic selections, and visibly overwritten namespace
members are unresolved.
Electron API identity follows proven lexical module aliases. Namespace interop
also preserves identity when the complete Rolldown helper operations, lexical
roles, live getters, and captured intrinsic origins match, or when a stable
helper simply returns its module parameter. Harmless single-statement control
blocks preserve recognition; added operations still require proof. Literal
member and destructuring projections are retained from proven results.
Omitted or literal node-mode arguments preserve named exports; a module-valued
default projection requires a truthy literal node mode. Computed or extra
arguments remain unresolved.
Recognition uses structure rather than emitted names; other helper bodies and ambiguous
runtime fallbacks remain unresolved. Captured function identities survive later global-property
replacement, including copies through initialized aliases. Reads before an
alias initializer remain unresolved. Visible intrinsic writes before capture or
conversion are checked in their owning callable scope, including identifier leaves in nested/default/rest
destructuring and loop targets. Property keys and shadowed local bindings do not
overwrite the global intrinsic identity. Cross-call side effects, including
writes inside directly invoked local functions, are not evaluated. Other
reassignments, dynamic selections, and visibly overwritten namespace members
are unresolved.
Known Object/Reflect mutators remain recognizable through literal destructuring
of intrinsic objects and stable bound-function aliases. Calls retain bound
argument prefixes and the original bound receiver through `call`, `apply`, and
`Reflect.apply`, including generic `Function.prototype` invocation and binding
creation. Arguments follow each actual callable invocation rather than property
chain depth; rebinding retains the original bound receiver.
Visibly replaced invocation intrinsics produce unknown effects instead
of using their former call semantics; captured function aliases retain their
earlier identity. Unexamined targets remain unresolved. `Reflect.set` examines
its explicit receiver as well as its target, retaining unknown receiver effects.
Creating an unused binding does not itself mutate an intrinsic. Variable
redeclarations retain a single unconditional initializer
when they introduce no assignment or second initializer.
Stable identifier chains to fresh object, array, function,
undecorated class or RegExp syntax keep those targets separate from intrinsic
objects when initialized before use; opaque, decorated, reassigned or
not-yet-initialized targets remain unresolved. Writes during class initialization
are still retained. Function declarations are available before their textual
position; variable and class initializers must precede use.
Direct and destructuring assignment, loop, update, and delete targets are checked
through namespace aliases; unrelated member writes do not discard observed API
identity. This static check does
+23 -8
View File
@@ -150,13 +150,15 @@ structured data and matching text projection. Oversized errors are retained
as Evidence before delivery of a bounded diagnostic with an export reference;
if retention is unavailable or fails, the diagnostic reports that reason.
REA accepts ordinary `tools/call` progress tokens. Updates are monotonic,
rate-bounded to at most one intermediate update per 100 ms, and always allow a
terminal update. Unknown totals are omitted; REA does not fabricate percentages.
REA accepts ordinary `tools/call` progress tokens. The numeric `progress` counts
emitted status observations and strictly increases, including when a waiting
phase has completed no additional work. Updates are rate-bounded to at most one
intermediate update per 100 ms and always allow a terminal update. `total` is
omitted because the number of future status observations is unknown. Read
`message` for the phase and observed work; REA does not fabricate percentages.
`capture_process_scenario` uses that boundary only when the client supplies a
progress token. Notifications set `progress` to the count of collected terminal
frames, process samples, and interaction events, omit `total`, and put the
lifecycle phase, elapsed time, and final cleanup status in `message`. A client
progress token. Notifications put the lifecycle phase, elapsed time, and final
cleanup status in `message`. A client
that does not send a progress token receives no progress notifications. The
tool result is unchanged either way.
Provider calls receive the request cancellation signal. Artifact traversal,
@@ -230,6 +232,18 @@ engine readiness or a percentage of Ghidra auto-analysis. A longer server
startup allowance does not extend the client's deadline; progress also does not
extend it unless the client explicitly implements that policy.
While Ghidra startup is pending, REA sends a waiting notification every ten
seconds when the request has a progress token. Its message gives elapsed waiting
time; import, auto-analysis and bridge readiness may all still be pending.
Waiting notifications stop when startup settles or the caller cancels. They do
not measure engine work completed.
The pinned SDK can reset the request's inactivity timeout on progress with
`resetTimeoutOnProgress: true`. Also set `maxTotalTimeout` to bound the complete
request; the provider's startup deadline still applies. These options belong in
the same second argument of `callTool`. Without that explicit client policy, the
default 60-second request deadline still expires despite waiting notifications.
The 240-second setting is a measured example, not a universal timeout: a
controlled Linux x64/WSL2 fixture took about 64 seconds for its first overview
with Ghidra 12.1.4 on a mounted NTFS installation, native JDK 21, two CPUs, and a
@@ -265,9 +279,10 @@ observed process-family member remained after final close. This was a small
1,024-byte fixture, so the longer request setting remains an example, not a
guarantee for larger targets. No macOS cold-start recovery was exercised.
With a supplied progress token, the Windows run received an operation-start
With a supplied progress token, that earlier Windows run received an operation-start
notification before timeout and start/completion notifications for the
successful retry. It received no intermediate import or auto-analysis progress.
successful retry, before startup waiting notifications were added. It received
no intermediate import or auto-analysis progress.
These operation markers do not measure analysis work completed or extend the
client's deadline. Each new provider session still imports the target into a
fresh temporary project.
+72
View File
@@ -0,0 +1,72 @@
# Headerless raw-binary analysis with Ghidra
REA admits a headerless executable when the caller supplies the CPU family and
the address where file offset 0 should be mapped. That interpretation is not
inferred from a `.bin` suffix or from unrecognized bytes.
## Open and inspect
```bash
rea inspect /absolute/path/to/ecu.bin --target-format raw-binary --architecture arm --entry-point 0x8000000 --provider ghidra --json
rea function /absolute/path/to/ecu.bin 0x8000000 --target-format raw-binary --architecture arm --entry-point 0x8000000 --provider ghidra --json
rea inspect-native-load-image /absolute/path/to/ecu.bin --target-format raw-binary --architecture arm --entry-point 0x8000000 --provider ghidra --json
```
```json
{
"name": "open_binary",
"arguments": {
"path": "/absolute/path/to/ecu.bin",
"format": "raw-binary",
"architecture": "arm",
"entry_point": "0x8000000",
"provider_id": "ghidra"
}
}
```
`architecture` is one of `x86`, `x86_64`, `arm`, or `arm64`. `entry_point` is a
hexadecimal address of the form `0x…`. The complete file is mapped starting at
that address, and Ghidra seeds an `entry` function there before auto-analysis.
ARM and AArch64 entries must be 4-byte aligned; x86 entries may be byte-aligned.
`open_binary` and an open `binary_session` return the canonical `entry_point`
for raw targets so callers can verify the selected mapping directly.
Omitted `format` keeps header-based detection; architecture and entry without
`format=raw-binary` are rejected.
Ghidra imports a private snapshot with `BinaryLoader` and these little-endian
generic languages:
| architecture | language_id |
| ------------ | ------------------- |
| x86 | `x86:LE:32:default` |
| x86_64 | `x86:LE:64:default` |
| arm | `ARM:LE:32:v7` |
| arm64 | `AARCH64:LE:64:v8A` |
Those settings, the caller-supplied entry, and `language_selection:
caller-supplied-v1` are committed in the analysis profile. A different entry
or architecture is a different profile; snapshots from header-detected targets
do not replay.
The mapped start is independent of Ghidra's program image base, which remains
`0x0` for BinaryLoader. Ghidra may report additional language-defined entry
points, including unmapped ARM vectors. Load-image verification requires the
caller-supplied entry and preserves those other entries as observations.
Independent raw verification streams the complete private snapshot digest and
extent with bounded memory and supports cancellation during the read.
Hopper and IDA refuse raw-binary targets. Windows Ghidra P0 continues to admit
PE applications only.
## Limitations
- Headers are not discovered from file bytes. This increment does not guess
load addresses, vector tables, or memory maps.
- Big-endian, Thumb-only, Cortex-M, and other Ghidra processor variants are
unsupported.
- Reset vectors, memory-mapped I/O, and firmware boot sequences are not
emulated.
- Independent load-image verification covers source identity, mapped file
bytes, the bound language, and the caller-supplied entry. Original bytes
stay unchanged.
+8
View File
@@ -793,6 +793,14 @@ truncation constraint, while leading-zero coordinates still resolve correctly.
It has the same Ghidra/JDK prerequisites as the MZ lane. Neither lane claims DOS
runtime or PC-98 device execution.
`npm run verify:ghidra:raw` uses a generated ARM little-endian headerless image
through the compiled CLI and stdio MCP server. With the same Ghidra/JDK
prerequisites, it checks preparation and bridge startup, verified load mappings,
instruction and byte readback, canonical-entry session reuse, replacement when
the entry changes without `provider_id`, unchanged source bytes, and owned
cleanup. Other raw CPU families remain covered by deterministic tests rather
than this real-provider lane. See [raw binary analysis](raw-binary.md).
## Apple Interface Builder archives
`npm run verify:interface-builder` compiles the source-owned AppKit XIB into a
+2
View File
@@ -55,6 +55,7 @@
"bridge/ghidra/ReaGhidraPrepareCom.java",
"bridge/ghidra/ReaGhidraApplySeeds.java",
"bridge/ghidra/ReaGhidraNoReturnFix.java",
"bridge/ghidra/ReaGhidraPrepareRaw.java",
"bridge/android/ReaJadxBridge.java",
"bridge/mitmproxy/capture.py",
"scripts/rea.mjs",
@@ -166,6 +167,7 @@
"verify:ghidra:switch": "npm run build:cached && node scripts/verify-real-ghidra-switch.mjs",
"verify:ghidra:dos": "npm run build:cached && node scripts/verify-real-ghidra-dos.mjs",
"verify:ghidra:com": "npm run build:cached && node scripts/verify-real-ghidra-com.mjs",
"verify:ghidra:raw": "npm run build:cached && node scripts/verify-real-ghidra-raw.mjs",
"verify:ghidra:aarch64-jump-table": "npm run build:cached && node scripts/verify-real-ghidra.mjs --aarch64-jump-table",
"verify:interface-builder": "npm run build:cached && node scripts/verify/apple/interface-builder.mjs",
"verify:ghidra:cross-format": "npm run build:cached && node scripts/verify-real-ghidra.mjs --cross-format",
+9 -5
View File
@@ -177,6 +177,7 @@ const scriptCollisions = [
"ReaGhidraPrepareCom.java",
"ReaGhidraApplySeeds.java",
"ReaGhidraNoReturnFix.java",
"ReaGhidraPrepareRaw.java",
];
await mkdir(callerDirectory);
for (const name of scriptCollisions) await mkdir(join(callerDirectory, name));
@@ -394,15 +395,15 @@ try {
return evidence.normalized_result;
},
);
const expected = (
const { GHIDRA_MUTATING_OPERATIONS, GHIDRA_SESSION_CAPABILITIES } =
await import(
pathToFileURL(join(packageRoot, "dist/ghidra/GhidraSessionValues.js"))
)
).GHIDRA_SESSION_CAPABILITIES.filter(
);
const expected = GHIDRA_SESSION_CAPABILITIES.filter(
(name) =>
name !== "ping" &&
name !== "shutdown" &&
name !== "annotate_native_function",
!GHIDRA_MUTATING_OPERATIONS.has(name),
);
assert.ok(
expected.every((name) => report.mcpOperations.includes(name)),
@@ -440,7 +441,10 @@ try {
token,
"Analysis changed caller token authority.",
);
assert.deepEqual((await readdir(callerDirectory)).sort(), scriptCollisions);
assert.deepEqual(
(await readdir(callerDirectory)).sort(),
[...scriptCollisions].sort(),
);
for (const name of scriptCollisions)
assert.deepEqual(await readdir(join(callerDirectory, name)), []);
report.callerScriptCollisionsPreserved = true;
+219
View File
@@ -0,0 +1,219 @@
import assert from "node:assert/strict";
import { execFile } from "node:child_process";
import { createHash } from "node:crypto";
import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { parseEvidence } from "../dist/domain/evidence.js";
import { inspectGhidraInstallation } from "../dist/ghidra/GhidraInstallation.js";
import { requireMcpOperationResult } from "./lib/mcp-verifier-results.mjs";
import { createVerifierRun, completeVerifierRun } from "./lib/verifier-run.mjs";
if (process.argv.length !== 2)
throw new Error("Usage: node scripts/verify-real-ghidra-raw.mjs");
if (!["linux", "darwin"].includes(process.platform))
throw new Error(
"Raw-binary verification requires a Linux or macOS Ghidra host.",
);
if (process.env.GHIDRA_INSTALL_DIR === undefined)
throw new Error(
"Set GHIDRA_INSTALL_DIR to a bring-your-own Ghidra installation.",
);
const installation = inspectGhidraInstallation({
environment: process.env,
installDir: process.env.GHIDRA_INSTALL_DIR,
...(process.env.JAVA_HOME === undefined
? {}
: { javaHome: process.env.JAVA_HOME }),
});
assert.equal(installation.status, "available", JSON.stringify(installation));
const run = createVerifierRun();
const workspace = await mkdtemp(join(tmpdir(), "rea-raw-proof-"));
const runtime = join(workspace, "runtime");
await mkdir(runtime);
const bytes = Buffer.from("1eff2fe1", "hex"); // ARM little-endian bx lr.
const sha256 = createHash("sha256").update(bytes).digest("hex");
const path = join(workspace, "image.bin");
await writeFile(path, bytes);
const entrypoint = fileURLToPath(new URL("./rea.mjs", import.meta.url));
const env = {
PATH: process.env.PATH ?? "/usr/bin:/bin",
TMPDIR: runtime,
REA_LOG_LEVEL: "silent",
REA_ANALYSIS_PROVIDER: "ghidra",
REA_PROCESS_RUN_ID: run.run_id,
GHIDRA_INSTALL_DIR: process.env.GHIDRA_INSTALL_DIR,
...(process.env.JAVA_HOME === undefined
? {}
: { JAVA_HOME: process.env.JAVA_HOME }),
};
const transport = new StdioClientTransport({
command: process.execPath,
args: [entrypoint, "mcp"],
env,
stderr: "pipe",
});
const client = new Client({ name: "rea-real-raw-proof", version: "1" });
let stderr = "";
transport.stderr?.on("data", (chunk) => {
stderr = (stderr + chunk.toString()).slice(-65536);
});
let report;
try {
await client.connect(transport);
const profiles = [];
const sessions = [];
for (const entryPoint of ["0x08000000", "0x8000000", "0x09000000"]) {
// Omit provider_id to exercise reuse of the current provider route.
const opened = await call("open_binary", {
path,
format: "raw-binary",
architecture: "arm",
entry_point: entryPoint,
});
const entry = `0x${BigInt(entryPoint).toString(16)}`;
assert.equal(opened.entry_point, entry);
const image = await call("inspect_native_load_image");
assert.equal(
image.normalized_result.status,
"verified",
JSON.stringify(image),
);
assert.equal(image.normalized_result.base_address, entry);
assert.equal(image.normalized_result.entry.address, entry);
assert.equal(
image.normalized_result.observations.language_id,
"ARM:LE:32:v7",
);
assert.ok(
image.normalized_result.observations.entry_points.includes(entry),
);
assert.equal(image.analysis_profile.parameters.entry_point, entry);
profiles.push(image.analysis_profile.digest);
const status = await call("binary_session");
assert.equal(status.entry_point, entry);
sessions.push(status.analysis_run.run_id);
const memory = await call("read_bytes", {
address: entry,
length: bytes.length,
});
assert.equal(memory.normalized_result.bytes_hex, bytes.toString("hex"));
const procedures = await call("list_procedures");
assert.ok(
procedures.normalized_result.some(
(procedure) => procedure.address === entry,
),
);
const instruction = await call("inspect_native_instruction", {
address: entry,
});
assert.equal(instruction.normalized_result.address, entry);
}
assert.equal(profiles[0], profiles[1]);
assert.notEqual(profiles[1], profiles[2]);
assert.equal(sessions[0], sessions[1]);
assert.notEqual(sessions[1], sessions[2]);
const rejected = await client.callTool({
name: "open_binary",
arguments: {
path,
format: "raw-binary",
architecture: "arm64",
entry_point: "0x8000001",
},
});
assert.equal(rejected.isError, true);
assert.match(JSON.stringify(rejected.content), /must be 4-byte aligned/);
const unchanged = await call("binary_session");
assert.equal(unchanged.analysis_run.run_id, sessions[2]);
assert.equal(unchanged.entry_point, "0x9000000");
await call("close_binary");
const { stdout } = await promisify(execFile)(
process.execPath,
[
entrypoint,
"inspect-native-load-image",
path,
"--target-format",
"raw-binary",
"--architecture",
"arm",
"--entry-point",
"0x08000000",
"--provider",
"ghidra",
"--json",
],
{ env, timeout: 240000, maxBuffer: 16 * 1024 * 1024 },
);
const cli = parseEvidence(JSON.parse(stdout));
assert.equal(cli.subject.digest.sha256, sha256);
assert.equal(cli.normalized_result.status, "verified");
assert.equal(cli.normalized_result.base_address, "0x8000000");
assert.equal(cli.analysis_profile.digest, profiles[0]);
assert.deepEqual(await readFile(path), bytes);
report = {
ok: true,
mocked: false,
lane: "ghidra-raw",
host: process.platform,
provider: { id: "ghidra", version: installation.providerVersion },
target: {
format: "raw-binary",
architecture: "arm",
sha256,
bytes: bytes.length,
},
transport: { cli: true, stdio_mcp: true },
canonical_entry_reuses_session: true,
changed_entry_replaces_session: true,
lifecycle_entry_preserved: true,
invalid_entry_preserves_active_session: true,
load_images_verified: true,
original_unchanged: true,
};
} catch (error) {
if (stderr.trim()) process.stderr.write(stderr);
throw error;
} finally {
await client.close();
await transport.close();
await rm(workspace, { recursive: true, force: true });
}
const verifierRun = await completeVerifierRun(run);
assert.equal(verifierRun.process_lineage.status, "verified");
assert.deepEqual(verifierRun.process_lineage.descendants, []);
process.stdout.write(
JSON.stringify({
verifier_run: verifierRun,
...report,
cleanup: "complete",
}) + "\n",
);
async function call(name, args = {}) {
const result = await client.callTool(
{ name, arguments: args },
{ timeout: 240000 },
);
assert.notEqual(result.isError, true, JSON.stringify(result));
const projected = requireMcpOperationResult(result, name);
if (
name === "open_binary" ||
name === "close_binary" ||
name === "binary_session"
)
return projected;
const evidence = parseEvidence(result.structuredContent);
assert.equal(evidence.subject.digest.sha256, sha256);
assert.equal(evidence.subject.format, "raw-binary");
return evidence;
}
+7 -6
View File
@@ -21,14 +21,17 @@ import { SUPPORTED_GHIDRA_VERSION } from "../dist/ghidra/GhidraInstallationPolic
import { GhidraHeadlessLauncher } from "../dist/ghidra/GhidraLauncher.js";
import { GHIDRA_PROVIDER_IDENTITY } from "../dist/ghidra/GhidraProviderCapabilities.js";
import { windowsP0Capabilities } from "../dist/ghidra/GhidraProviderCapabilities.js";
import { GHIDRA_SESSION_CAPABILITIES } from "../dist/ghidra/GhidraSessionValues.js";
import {
GHIDRA_MUTATING_OPERATIONS,
GHIDRA_SESSION_CAPABILITIES,
} from "../dist/ghidra/GhidraSessionValues.js";
import { parseBinaryTarget } from "../dist/application/BinaryTargetResolver.js";
import { completeVerifierRun, createVerifierRun } from "./lib/verifier-run.mjs";
import { verifyGhidraCompactReferences } from "./lib/real-ghidra-compact-references.mjs";
const verifierRun = createVerifierRun();
const SESSION_CAPABILITIES = GHIDRA_SESSION_CAPABILITIES.filter(
(name) => name !== "annotate_native_function",
(name) => !GHIDRA_MUTATING_OPERATIONS.has(name),
);
if (process.platform !== "win32" || process.arch !== "x64")
@@ -236,10 +239,8 @@ try {
const expected = [
...GHIDRA_INVENTORY_OPERATIONS,
...GHIDRA_FUNCTION_OPERATIONS.filter(
(name) => name !== "annotate_native_function",
),
];
...GHIDRA_FUNCTION_OPERATIONS,
].filter((name) => !GHIDRA_MUTATING_OPERATIONS.has(name));
if (
observed.size !== expected.length ||
expected.some((operation) => !observed.has(operation))
+14 -3
View File
@@ -7,13 +7,16 @@ import { promisify } from "node:util";
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { parseEvidence } from "../../../dist/domain/evidence.js";
import { hashAndroidFile } from "../../../dist/android/AndroidTargetSnapshot.js";
import { hashAndroidFile } from "./digest.mjs";
import { JADX_RELEASE } from "../../../dist/android/JadxRelease.js";
import fixture from "../../fixtures/android/apidemos.json" with { type: "json" };
import { verifyAndroidCliCancellation } from "./cli-cancellation.mjs";
import { verifyAndroidMetadata } from "./metadata.mjs";
import { verifyAndroidFailureRecovery } from "./failure-recovery.mjs";
import { resolveJadxConfiguration } from "../../../dist/android/JadxConfiguration.js";
import {
resolveJadxConfigurationInputs,
validateJadxConfiguration,
} from "../../../dist/android/JadxConfiguration.js";
import { verifyWindowsAndroidLifecycle } from "./windows-lifecycle.mjs";
const repository = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
@@ -35,10 +38,16 @@ assert.equal(
JADX_RELEASE.sha256,
"Real Android lane requires the audited headless JADX release JAR",
);
const { java, jvmArguments } = await resolveJadxConfiguration(
const configuration = await resolveJadxConfigurationInputs(
process.env,
"inspect_android_package",
);
await validateJadxConfiguration(
configuration,
process.env,
"inspect_android_package",
);
const { java, jvmArguments } = configuration;
const execute = promisify(execFile);
await execute(java, ["-version"], { timeout: 10_000 });
const entrypoint =
@@ -52,6 +61,8 @@ await verifyAndroidMetadata({
repository,
execute,
jvmArguments,
entrypoint,
environment,
bridge: resolve(dirname(entrypoint), "../bridge/android/ReaJadxBridge.java"),
});
const tasks = [
+9
View File
@@ -0,0 +1,9 @@
import { createHash } from "node:crypto";
import { createReadStream } from "node:fs";
/** Verify artifact identity without depending on private runtime snapshot helpers. */
export const hashAndroidFile = async (path) => {
const hash = createHash("sha256");
for await (const bytes of createReadStream(path)) hash.update(bytes);
return hash.digest("hex");
};
+130
View File
@@ -0,0 +1,130 @@
import assert from "node:assert/strict";
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { parseEvidence } from "../../../dist/domain/evidence.js";
import { hashAndroidFile } from "./digest.mjs";
/** Verify folded field assignments and remaining static-block calls through both public adapters. */
export const verifyAndroidInitializers = async ({
apk,
repository,
entrypoint,
environment,
execute,
}) => {
const digest = await hashAndroidFile(apk);
const cases = [
{
class_name: "fixture.InitializationPolicy",
witnesses: [
"declared-policy",
"->singletonList",
"->POLICY:Ljava/util/List;",
],
},
{
class_name: "fixture.MixedInitialization",
witnesses: ["field-value", "->LABEL:Ljava/lang/String;", "->touch()V"],
},
];
const check = (value, scenario) => {
const evidence = parseEvidence(value);
assert.equal(evidence.subject.digest.sha256, digest);
const result = evidence.normalized_result;
assert.equal(result.class_name, scenario.class_name);
assert.equal(result.method.name, "<clinit>");
assert.equal(result.overload_count, 1);
assert.equal(result.body_status, "available");
assert.equal(result.representation, "smali");
assert.equal(result.fell_back, true);
assert.ok(result.markers.includes("static_initializer_disassembly"));
assert.equal(result.source.status, "complete");
for (const witness of scenario.witnesses)
assert.ok(
result.source.text.includes(witness),
`Missing initializer evidence: ${witness}`,
);
return evidence;
};
const cli = new Map();
for (const scenario of cases) {
const response = await execute(
process.execPath,
[
entrypoint,
"inspect-android-method",
apk,
scenario.class_name,
"<clinit>",
"--format",
"json",
],
{
cwd: repository,
env: environment,
timeout: 150_000,
maxBuffer: 8 * 1024 * 1024,
},
);
cli.set(scenario.class_name, check(JSON.parse(response.stdout), scenario));
}
const transport = new StdioClientTransport({
command: process.execPath,
args: [entrypoint, "mcp"],
cwd: repository,
env: environment,
stderr: "pipe",
});
let stderr = "";
transport.stderr?.on("data", (chunk) => {
stderr += chunk.toString();
});
const client = new Client({
name: "rea-real-android-initializers",
version: "1",
});
try {
await client.connect(transport, { timeout: 30_000 });
for (const scenario of cases) {
const response = await client.callTool(
{
name: "inspect_android_method",
arguments: {
path: apk,
class_name: scenario.class_name,
method_name: "<clinit>",
},
},
{ timeout: 150_000 },
);
assert.notEqual(response.isError, true, JSON.stringify(response));
const evidence = check(response.structuredContent, scenario);
assert.deepEqual(
evidence.normalized_result,
cli.get(scenario.class_name).normalized_result,
);
assert.deepEqual(
evidence.parameters,
cli.get(scenario.class_name).parameters,
);
assert.deepEqual(
evidence.provider,
cli.get(scenario.class_name).provider,
);
}
await client.ping();
} catch (cause) {
process.stderr.write(stderr);
throw cause;
} finally {
await client.close();
}
assert.equal(
await hashAndroidFile(apk),
digest,
"Static inspection changed fixture bytes",
);
console.log(
"PASS real CLI/MCP static initializer evidence, identity, parity and unchanged APK",
);
};
+19
View File
@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { delimiter, join, resolve } from "node:path";
import { verifyAndroidInitializers } from "./initializers.mjs";
/** Prove cold metadata stays unmaterialized and overload identities survive code generation. */
export const verifyAndroidMetadata = async ({
@@ -11,6 +12,8 @@ export const verifyAndroidMetadata = async ({
bridge,
repository,
execute,
entrypoint,
environment,
jvmArguments = [],
}) => {
const javac =
@@ -55,6 +58,8 @@ export const verifyAndroidMetadata = async ({
`${classes}${delimiter}${jar}`,
"ReaJadxMetadataRegression",
apk,
resolve(repository, "tests/fixtures/android/static-initializers"),
classes,
],
{ timeout: 120_000, maxBuffer: 8 * 1024 * 1024 },
);
@@ -62,9 +67,23 @@ export const verifyAndroidMetadata = async ({
result.stdout,
/METADATA_REGRESSION_PASS classes=\d+ overloads=3/u,
);
assert.match(
result.stdout,
/INITIALIZER_REGRESSION_PASS folded=2 bounded=true/u,
);
console.log(
"PASS real cold metadata, full generic types and stable overloaded method selection",
);
console.log(
"PASS real folded and mixed static initializers, absent bodies and bounded smali",
);
await verifyAndroidInitializers({
apk: resolve(classes, "initializers.apk"),
repository,
entrypoint,
environment,
execute,
});
} finally {
await rm(classes, { recursive: true, force: true });
}
+16 -3
View File
@@ -13,7 +13,10 @@ import { dirname, join } from "node:path";
import { setTimeout as delay } from "node:timers/promises";
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { resolveJadxConfiguration } from "../../../dist/android/JadxConfiguration.js";
import {
resolveJadxConfigurationInputs,
validateJadxConfiguration,
} from "../../../dist/android/JadxConfiguration.js";
/** Verify real Windows cancellation, disconnect and abrupt CLI owner exit. */
export async function verifyWindowsAndroidLifecycle(options) {
@@ -36,7 +39,12 @@ export async function verifyWindowsAndroidLifecycle(options) {
}
async function verifyJavaSelection(environment) {
const selected = await resolveJadxConfiguration(
const selected = await resolveJadxConfigurationInputs(
environment,
"inspect_android_package",
);
await validateJadxConfiguration(
selected,
environment,
"inspect_android_package",
);
@@ -51,7 +59,12 @@ async function verifyJavaSelection(environment) {
// The owned junction borrows the selected JDK directory without copying it.
await symlink(dirname(selected.java), alias, "junction");
pathEnvironment.Path = `"${alias}"`;
const onPath = await resolveJadxConfiguration(
const onPath = await resolveJadxConfigurationInputs(
pathEnvironment,
"inspect_android_package",
);
await validateJadxConfiguration(
onPath,
pathEnvironment,
"inspect_android_package",
);
+53 -3
View File
@@ -26,6 +26,8 @@ import {
validateDosComLength,
type ExecutableFormatHint,
} from "../domain/dosCom.js";
import { admitRawBinary } from "../domain/rawBinary.js";
import type { BinaryArchitecture } from "../domain/binaryTargetTypes.js";
import { mzWindowsHeaderOffset } from "../domain/dosMz.js";
import {
hasZipSignature,
@@ -45,6 +47,8 @@ export interface BinaryTargetResolverOptions {
readonly hostArchitecture?: NodeJS.Architecture;
readonly targetKind?: BinaryTarget["kind"];
readonly formatHint?: ExecutableFormatHint;
readonly architecture?: BinaryArchitecture;
readonly entryPoint?: string;
readonly signal?: AbortSignal;
}
@@ -61,7 +65,7 @@ export const parseBinaryTarget = async (
> => {
const cwd = options.cwd ?? process.cwd();
const hostArchitecture = options.hostArchitecture ?? process.arch;
const { targetKind, formatHint, signal } = options;
const { targetKind, formatHint, signal, architecture, entryPoint } = options;
const candidate = isAbsolute(input) ? input : resolve(cwd, input);
try {
throwIfTargetResolutionCancelled(signal);
@@ -83,6 +87,40 @@ export const parseBinaryTarget = async (
throwIfTargetResolutionCancelled(signal);
const metadata = await handle.stat();
throwIfTargetResolutionCancelled(signal);
if (formatHint === "raw-binary") {
if (targetKind !== undefined && targetKind !== "executable")
return err(
new BinaryTargetError(
path,
"raw-binary format requires an executable target kind",
),
);
const admitted = admitRawBinary({
architecture,
entryPoint,
fileBytes: metadata.size,
});
if (!admitted.ok)
return err(new BinaryTargetError(path, admitted.error));
return ok({
path,
sourcePath: canonical,
sha256: await sha256Handle(handle, path, metadata, signal),
kind: "executable",
format: "raw-binary",
architecture: admitted.value.architecture,
availableArchitectures: [admitted.value.architecture],
entryPoint: admitted.value.entryPoint,
entryPointSource: admitted.value.entryPointSource,
});
}
if (architecture !== undefined || entryPoint !== undefined)
return err(
new BinaryTargetError(
path,
"architecture and entry_point apply only with format=raw-binary",
),
);
if (formatHint === "dos-com") {
if (targetKind !== undefined && targetKind !== "executable")
return err(
@@ -194,7 +232,13 @@ const detectArtifactFormat = async (
): Promise<
| Exclude<
BinaryTarget["format"],
"analysis-database" | "mach-o" | "elf" | "pe" | "dos-mz" | "dos-com"
| "analysis-database"
| "mach-o"
| "elf"
| "pe"
| "dos-mz"
| "dos-com"
| "raw-binary"
>
| undefined
> => {
@@ -244,7 +288,13 @@ const namedArtifactFormat = (
const isArchiveFormat = (
format: Exclude<
BinaryTarget["format"],
"analysis-database" | "mach-o" | "elf" | "pe" | "dos-mz" | "dos-com"
| "analysis-database"
| "mach-o"
| "elf"
| "pe"
| "dos-mz"
| "dos-com"
| "raw-binary"
>,
): format is Extract<BinaryTarget, { kind: "archive" }>["format"] =>
isZipPackageFormat(format) || ["asar", "dmg", "pkg"].includes(format);
+37
View File
@@ -1,4 +1,5 @@
import type { ExecutableFormatHint } from "../domain/dosCom.js";
import type { BinaryArchitecture } from "../domain/binaryTargetTypes.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { DirectAnalysisDependencies } from "./DirectAnalysisDependencies.js";
import type { BinarySession } from "./binary/BinarySession.js";
@@ -91,6 +92,8 @@ export const runDirectAnalysis = async (
readonly signal?: AbortSignal;
readonly providerId?: AnalysisProviderSelector;
readonly formatHint?: ExecutableFormatHint;
readonly architecture?: BinaryArchitecture;
readonly entryPoint?: string;
} = {},
): Promise<JsonValue> =>
withProcessCancellation(options.signal, (signal) =>
@@ -101,6 +104,12 @@ export const runDirectAnalysis = async (
...(options.formatHint === undefined
? {}
: { formatHint: options.formatHint }),
...(options.architecture === undefined
? {}
: { architecture: options.architecture }),
...(options.entryPoint === undefined
? {}
: { entryPoint: options.entryPoint }),
...(options.providerId === undefined
? {}
: { providerId: options.providerId }),
@@ -187,6 +196,8 @@ const runAnalysis = async (
readonly signal: AbortSignal;
readonly providerId?: AnalysisProviderSelector;
readonly formatHint?: ExecutableFormatHint;
readonly architecture?: BinaryArchitecture;
readonly entryPoint?: string;
},
): Promise<JsonValue> => {
const { logger, signal, snapshotPath } = options;
@@ -203,6 +214,12 @@ const runAnalysis = async (
...(options.formatHint === undefined
? {}
: { formatHint: options.formatHint }),
...(options.architecture === undefined
? {}
: { architecture: options.architecture }),
...(options.entryPoint === undefined
? {}
: { entryPoint: options.entryPoint }),
});
if (!prepared.ok) return cliError(prepared.error);
const { snapshot } = prepared.value;
@@ -214,6 +231,12 @@ const runAnalysis = async (
...(options.formatHint === undefined
? {}
: { formatHint: options.formatHint }),
...(options.architecture === undefined
? {}
: { architecture: options.architecture }),
...(options.entryPoint === undefined
? {}
: { entryPoint: options.entryPoint }),
...(options.providerId === undefined
? {}
: { providerId: options.providerId }),
@@ -246,6 +269,12 @@ const runAnalysis = async (
...(options.formatHint === undefined
? {}
: { formatHint: options.formatHint }),
...(options.architecture === undefined
? {}
: { architecture: options.architecture }),
...(options.entryPoint === undefined
? {}
: { entryPoint: options.entryPoint }),
...(snapshot === undefined ? {} : { snapshot }),
...(options.providerId === undefined
? {}
@@ -440,6 +469,8 @@ const withProcessCancellation = async <Value>(
const prepareSnapshot = async (options: {
readonly path: string;
readonly formatHint?: ExecutableFormatHint;
readonly architecture?: BinaryArchitecture;
readonly entryPoint?: string;
readonly snapshotPath: string | undefined;
readonly signal: AbortSignal;
}): Promise<
@@ -458,6 +489,12 @@ const prepareSnapshot = async (options: {
...(options.formatHint === undefined
? {}
: { formatHint: options.formatHint }),
...(options.architecture === undefined
? {}
: { architecture: options.architecture }),
...(options.entryPoint === undefined
? {}
: { entryPoint: options.entryPoint }),
});
if (!target.ok) return target;
if (!snapshotMatchesTarget(loaded.value.target, target.value))
@@ -1,4 +1,5 @@
import type { ExecutableFormatHint } from "../../domain/dosCom.js";
import type { BinaryArchitecture } from "../../domain/binaryTargetTypes.js";
import type { AnalysisProviderSelector } from "../../contracts/providerSelection.js";
import type { AnalysisProfileCommitment } from "../../domain/analysisProfile.js";
import {
@@ -22,6 +23,8 @@ export interface BinarySessionOpenOptions {
readonly signal?: AbortSignal;
readonly targetKind?: BinaryTarget["kind"];
readonly formatHint?: ExecutableFormatHint;
readonly architecture?: BinaryArchitecture;
readonly entryPoint?: string;
readonly snapshot?: AnalysisSnapshot;
readonly providerId?: AnalysisProviderSelector;
}
@@ -72,6 +75,12 @@ export const resolveSessionOpen = async (
...(options.formatHint === undefined
? {}
: { formatHint: options.formatHint }),
...(options.architecture === undefined
? {}
: { architecture: options.architecture }),
...(options.entryPoint === undefined
? {}
: { entryPoint: options.entryPoint }),
...(options.signal === undefined ? {} : { signal: options.signal }),
});
if (!parsed.ok) return parsed;
+6 -1
View File
@@ -1,6 +1,9 @@
import type { InvestigationRecordPort } from "../investigation/InvestigationRecordPort.js";
import type { ExecutableFormatHint } from "../../domain/dosCom.js";
import type { BinaryTarget } from "../../domain/binaryTargetTypes.js";
import type {
BinaryArchitecture,
BinaryTarget,
} from "../../domain/binaryTargetTypes.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import type { AnalysisSnapshot } from "../../domain/analysisSnapshot.js";
import type { AnalysisProfileCommitment } from "../../domain/analysisProfile.js";
@@ -44,6 +47,8 @@ export interface BinarySessionPort
readonly signal?: AbortSignal;
readonly targetKind?: BinaryTarget["kind"];
readonly formatHint?: ExecutableFormatHint;
readonly architecture?: BinaryArchitecture;
readonly entryPoint?: string;
readonly snapshot?: AnalysisSnapshot;
readonly providerId?: AnalysisProviderSelector;
},
@@ -1,4 +1,5 @@
import type { BinaryTarget } from "../../domain/binaryTargetTypes.js";
import { binaryTargetSummary } from "./BinaryTargetSummary.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import type { ProviderOperationHealth } from "../../domain/providerOperationHealth.js";
import type {
@@ -92,11 +93,7 @@ export const binarySessionStatus = ({
: {
open: true,
...common,
path: target.path,
sha256: target.sha256,
format: target.format,
kind: target.kind,
architecture: target.architecture ?? null,
...binaryTargetSummary(target),
};
};
@@ -0,0 +1,11 @@
import type { BinaryTarget } from "../../domain/binaryTargetTypes.js";
/** Preserve the admitted target interpretation in public lifecycle results. */
export const binaryTargetSummary = (target: BinaryTarget) => ({
path: target.path,
format: target.format,
kind: target.kind,
sha256: target.sha256,
architecture: target.architecture ?? null,
...(target.format === "raw-binary" ? { entry_point: target.entryPoint } : {}),
});
+22 -66
View File
@@ -8,9 +8,8 @@ import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import type { Logger } from "pino";
import {
directAnalysisOptions,
formatSelectionOption,
providerSelectionOption,
directAnalysisOptionsFromCli,
nativeOpenOptionFields,
} from "./options.js";
import type { CliInstance } from "./types.js";
import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
@@ -43,8 +42,7 @@ const registerOverviewCommands = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
});
cli.command(CLI_COMMANDS.analyze, {
description: "Get an overview of an app",
@@ -75,12 +73,7 @@ const registerOverviewCommands = (
args.path,
"binary_overview",
{},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
);
},
@@ -97,12 +90,7 @@ const registerOverviewCommands = (
args.path,
"binary_overview",
{},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -136,8 +124,7 @@ const registerDecompileCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "decompile", () =>
@@ -152,12 +139,7 @@ const registerDecompileCommand = (
"procedure_pseudo_code",
),
},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -168,13 +150,17 @@ const routesToJavaScriptAnalysis = async (
path: string,
options: {
readonly snapshot?: string | undefined;
readonly "target-format"?: "dos-com" | undefined;
readonly "target-format"?: "dos-com" | "raw-binary" | undefined;
readonly architecture?: string | undefined;
readonly "entry-point"?: string | undefined;
readonly provider?: string | undefined;
},
): Promise<boolean> =>
options.provider === undefined &&
options.snapshot === undefined &&
options["target-format"] === undefined &&
options.architecture === undefined &&
options["entry-point"] === undefined &&
(await isJavaScriptApplicationPath(path));
const isJavaScriptApplicationPath = async (path: string): Promise<boolean> => {
@@ -215,8 +201,7 @@ const registerXrefsCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "xrefs", () =>
@@ -231,12 +216,7 @@ const registerXrefsCommand = (
"xrefs",
),
},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -270,8 +250,7 @@ const registerTraceCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "trace", () =>
@@ -287,12 +266,7 @@ const registerTraceCommand = (
),
case_sensitive: options.caseSensitive,
},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -326,8 +300,7 @@ const registerFunctionCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "function", () =>
@@ -342,12 +315,7 @@ const registerFunctionCommand = (
"analyze_function",
),
},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -381,8 +349,7 @@ const registerInstructionsCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.instructions, () =>
@@ -397,12 +364,7 @@ const registerInstructionsCommand = (
"read_function_instructions",
),
},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -448,8 +410,7 @@ const registerSearchCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "search", () =>
@@ -468,12 +429,7 @@ const registerSearchCommand = (
mode: options.mode,
case_sensitive: options.caseSensitive,
},
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
+22 -83
View File
@@ -5,9 +5,8 @@ import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import type { Logger } from "pino";
import {
directAnalysisOptions,
formatSelectionOption,
providerSelectionOption,
directAnalysisOptionsFromCli,
nativeOpenOptionFields,
} from "./options.js";
import type { CliInstance } from "./types.js";
@@ -23,8 +22,7 @@ export const registerCoreNativeCommands = (
"Verify loaded native bytes, source mappings, relocations and entry",
args: z.object({ path: z.string().describe("Local executable path") }),
options: z.object({
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.inspectNativeLoadImage, () =>
@@ -32,12 +30,7 @@ export const registerCoreNativeCommands = (
args.path,
"inspect_native_load_image",
{},
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -54,8 +47,7 @@ export const registerCoreNativeCommands = (
.min(1)
.default(256)
.describe("Requested byte count"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.readBytes, () =>
@@ -63,12 +55,7 @@ export const registerCoreNativeCommands = (
args.path,
"read_bytes",
{ address: args.address, length: options.length },
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -79,8 +66,7 @@ export const registerCoreNativeCommands = (
address: z.string().describe("Exact provider memory address"),
}),
options: z.object({
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.addressToFileOffset, () =>
@@ -88,12 +74,7 @@ export const registerCoreNativeCommands = (
args.path,
"address_to_file_offset",
{ address: args.address },
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -154,8 +135,7 @@ export const registerCoreNativeCommands = (
.max(5000)
.default(1000)
.describe("Maximum nodes on this page"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.traceNativeValues, () =>
@@ -172,12 +152,7 @@ export const registerCoreNativeCommands = (
offset: options.offset,
limit: options.limit,
},
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -189,8 +164,7 @@ export const registerCoreNativeCommands = (
options: z.object({
type: z.string().optional().describe("Exact database type category path"),
address: z.string().optional().describe("Exact native address"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.inspectNativeDataType, () =>
@@ -203,12 +177,7 @@ export const registerCoreNativeCommands = (
? {}
: { address: options.address }),
},
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -226,8 +195,7 @@ export const registerCoreNativeCommands = (
address: z.string().describe("Exact native address"),
}),
options: z.object({
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, command, () =>
@@ -235,12 +203,7 @@ export const registerCoreNativeCommands = (
args.path,
operation,
{ address: args.address },
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -273,8 +236,7 @@ const registerNativeDispatchMetadataCommand = (
.min(1)
.optional()
.describe("Load or update the local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: async ({ args, options }) =>
logCliCommand(logger, "inspect-native-dispatch-metadata", () =>
@@ -282,12 +244,7 @@ const registerNativeDispatchMetadataCommand = (
args.path,
"inspect_native_dispatch_metadata",
{ max_records: options.maxRecords },
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -332,8 +289,7 @@ const registerNativeUiActionCommand = (
.max(5_000)
.default(500)
.describe("Maximum returned graph edges"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: async ({ args, options }) =>
logCliCommand(logger, "trace-native-ui-action", () =>
@@ -346,12 +302,7 @@ const registerNativeUiActionCommand = (
max_nodes: options.maxNodes,
max_edges: options.maxEdges,
},
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -374,8 +325,7 @@ const registerNativeApiCommand = (
.min(1)
.optional()
.describe("Load and update a local analysis snapshot"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, "inspect-native-api", () =>
@@ -383,12 +333,7 @@ const registerNativeApiCommand = (
args.path,
"inspect_native_api",
{ procedure: args.address },
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
@@ -417,8 +362,7 @@ const registerAnnotationCommand = (
.string()
.optional()
.describe("Inline entry comment; empty text clears it"),
"target-format": formatSelectionOption,
provider: providerSelectionOption,
...nativeOpenOptionFields,
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.annotateNativeFunction, () =>
@@ -435,12 +379,7 @@ const registerAnnotationCommand = (
? {}
: { inline_comment: options["inline-comment"] }),
},
directAnalysisOptions(
logger,
undefined,
options.provider,
options["target-format"],
),
directAnalysisOptionsFromCli(logger, options),
),
),
});
+55 -1
View File
@@ -2,6 +2,11 @@ import {
executableFormatHintSchema,
type ExecutableFormatHint,
} from "../domain/dosCom.js";
import type { BinaryArchitecture } from "../domain/binaryTargetTypes.js";
import {
binaryArchitectureSchema,
rawBinaryEntryPointSchema,
} from "../domain/rawBinary.js";
import { analysisProviderSelectorSchema } from "../contracts/providerSelection.js";
import type { AnalysisProviderSelector } from "../contracts/providerSelection.js";
import type { Logger } from "pino";
@@ -15,16 +20,65 @@ export const providerSelectionOption = analysisProviderSelectorSchema
/** Explicit interpretation for headerless native executable formats. */
export const formatSelectionOption = executableFormatHintSchema
.optional()
.describe("Explicit headerless DOS COM interpretation");
.describe(
"Explicit headerless interpretation (dos-com or raw-binary); omission preserves header-based detection",
);
export const architectureSelectionOption = binaryArchitectureSchema
.optional()
.describe(
"Caller-supplied CPU family; required with --target-format raw-binary",
);
export const entryPointSelectionOption = rawBinaryEntryPointSchema
.optional()
.describe(
"Caller-supplied load and entry address (0xhex); required with --target-format raw-binary",
);
/** Shared CLI flags that bind a native target interpretation. */
export const nativeOpenOptionFields = {
"target-format": formatSelectionOption,
architecture: architectureSelectionOption,
"entry-point": entryPointSelectionOption,
provider: providerSelectionOption,
};
/** Native CLI flags consumed when opening a target for one-shot analysis. */
export interface NativeOpenCliFlags {
readonly snapshot?: string | undefined;
readonly provider?: AnalysisProviderSelector | undefined;
readonly "target-format"?: ExecutableFormatHint | undefined;
readonly architecture?: BinaryArchitecture | undefined;
readonly "entry-point"?: string | undefined;
}
export const directAnalysisOptions = (
logger: Logger,
snapshotPath: string | undefined,
providerId: AnalysisProviderSelector | undefined,
formatHint?: ExecutableFormatHint,
architecture?: BinaryArchitecture,
entryPoint?: string,
) => ({
logger,
snapshotPath,
...(formatHint === undefined ? {} : { formatHint }),
...(architecture === undefined ? {} : { architecture }),
...(entryPoint === undefined ? {} : { entryPoint }),
...(providerId === undefined ? {} : { providerId }),
});
/** Map native CLI flags onto the shared one-shot analysis options. */
export const directAnalysisOptionsFromCli = (
logger: Logger,
options: NativeOpenCliFlags,
) =>
directAnalysisOptions(
logger,
options.snapshot,
options.provider,
options["target-format"],
options.architecture,
options["entry-point"],
);
@@ -0,0 +1,50 @@
import { describe, expect, it } from "vitest";
import { openBinaryInputSchema } from "./sessionLifecycleInputs.js";
describe("open_binary raw-binary input contract", () => {
it("accepts header detection without architecture", () => {
expect(
openBinaryInputSchema.safeParse({ path: "/tmp/fixture.bin" }).success,
).toBe(true);
expect(
openBinaryInputSchema.safeParse({
path: "/tmp/legacy.com",
format: "dos-com",
}).success,
).toBe(true);
});
it("accepts raw-binary with architecture and entry", () => {
expect(
openBinaryInputSchema.safeParse({
path: "/tmp/ecu.bin",
format: "raw-binary",
architecture: "arm",
entry_point: "0x8000000",
}).success,
).toBe(true);
});
it("rejects raw-binary without architecture or entry", () => {
const parsed = openBinaryInputSchema.safeParse({
path: "/tmp/ecu.bin",
format: "raw-binary",
});
expect(parsed.success).toBe(false);
expect(
openBinaryInputSchema.safeParse({
path: "/tmp/ecu.bin",
format: "raw-binary",
architecture: "arm",
}).success,
).toBe(false);
});
it("rejects architecture without format=raw-binary", () => {
expect(
openBinaryInputSchema.safeParse({
path: "/tmp/ecu.bin",
architecture: "arm",
entry_point: "0x8000000",
}).success,
).toBe(false);
});
});
+50 -10
View File
@@ -1,6 +1,11 @@
import { isAbsolute } from "node:path";
import { executableFormatHintSchema } from "../domain/dosCom.js";
import { localPathStringSchema } from "../domain/localPath.js";
import {
binaryArchitectureSchema,
rawBinaryEntryPointSchema,
rawBinarySelectionError,
} from "../domain/rawBinary.js";
import { z } from "zod";
import { analysisProviderSelectorSchema } from "./providerSelection.js";
@@ -25,16 +30,51 @@ const binaryTargetPathSchema = localPathStringSchema
);
/** Input contract for opening a target with an optional staged snapshot. */
export const openBinaryInputSchema = z.strictObject({
path: binaryTargetPathSchema,
format: executableFormatHintSchema
.optional()
.describe(
"Explicit headerless DOS COM interpretation; omission preserves header-based detection",
),
provider_id: analysisProviderSelectorSchema.optional(),
snapshot_path: snapshotPathSchema.optional(),
});
export const openBinaryInputSchema = z
.strictObject({
path: binaryTargetPathSchema,
format: executableFormatHintSchema
.optional()
.describe(
"Explicit headerless interpretation: dos-com or raw-binary. Omission preserves header-based detection.",
),
architecture: binaryArchitectureSchema
.optional()
.describe(
"Caller-supplied CPU family. Required with format=raw-binary; rejected otherwise.",
),
entry_point: rawBinaryEntryPointSchema
.optional()
.describe(
"Caller-supplied load and entry address (0xhex). File offset 0 is mapped here. Required with format=raw-binary; rejected otherwise.",
),
provider_id: analysisProviderSelectorSchema.optional(),
snapshot_path: snapshotPathSchema.optional(),
})
.superRefine((value, context) => {
const pairing = rawBinarySelectionError({
...(value.format === undefined ? {} : { format: value.format }),
...(value.architecture === undefined
? {}
: { architecture: value.architecture }),
...(value.entry_point === undefined
? {}
: { entryPoint: value.entry_point }),
});
if (pairing === undefined) return;
context.addIssue({
code: "custom",
path:
value.format === "raw-binary"
? value.architecture === undefined
? ["architecture"]
: ["entry_point"]
: value.architecture === undefined
? ["entry_point"]
: ["architecture"],
message: pairing,
});
});
/** Input contract for closing a target after an optional atomic snapshot. */
export const closeBinaryInputSchema = z.strictObject({
+1 -1
View File
@@ -69,7 +69,7 @@ export const exportEvidenceBundleInputSchema = z.strictObject({
export const SESSION_TOOL_CONTRACTS = [
session(
"open_binary",
"Open a local executable, application bundle, archive, JavaScript, source map, plist, or analysis database after validation. format=dos-com explicitly interprets 1..65280 headerless bytes as a DOS COM analysis image; omission preserves header-based detection. provider_id selects one deep provider or deterministic auto selection; the binding remains stable until close or an explicit switch, with no failure fallback. Reopening the same target and profile retains its active database and metadata edits. An optional analysis snapshot is imported atomically and must match the binary identity, concrete provider, and canonical analysis profile exactly; importing into a session with metadata mutations requires closing and reopening it first.",
"Open a local executable, application bundle, archive, JavaScript, source map, plist, or analysis database after validation. format=dos-com explicitly interprets 1..65280 headerless bytes as a DOS COM analysis image. format=raw-binary interprets headerless bytes with a required architecture and entry_point; file offset 0 maps at that address. Omission preserves header-based detection. provider_id selects one deep provider or deterministic auto selection; the binding remains stable until close or an explicit switch, with no failure fallback. Reopening the same target and profile retains its active database and metadata edits. An optional analysis snapshot is imported atomically and must match the binary identity, concrete provider, and canonical analysis profile exactly; importing into a session with metadata mutations requires closing and reopening it first.",
openBinaryInputSchema,
),
session(
+37 -20
View File
@@ -1,6 +1,10 @@
import { z } from "zod";
import { evidenceBundleSummarySchema } from "../domain/evidenceRecordSummary.js";
import { BINARY_ARCHITECTURES } from "../domain/binaryTargetTypes.js";
import {
binaryArchitectureSchema,
rawBinaryEntryPointSchema,
} from "../domain/rawBinary.js";
import { nativeFunctionAnnotationsSchema } from "../domain/native/nativeFunctionAnnotations.js";
import { nativeLoadImageSchema } from "../domain/native/nativeLoadImage.js";
import { nativeUiResultSchema } from "../domain/native/nativeUiObservation.js";
@@ -409,16 +413,33 @@ export const managedWorkflowOutputSchemas: Readonly<
),
};
const lifecycleTargetFields = {
path: z.string(),
kind: targetKindSchema,
sha256: z.string().regex(/^[a-f0-9]{64}$/u),
architecture: z.enum(BINARY_ARCHITECTURES).nullable(),
};
const detectedLifecycleTargetSchema = z.object({
...lifecycleTargetFields,
format: targetFormatSchema.exclude(["raw-binary"]),
});
const rawLifecycleTargetSchema = z.object({
...lifecycleTargetFields,
format: z.literal("raw-binary"),
kind: z.literal("executable"),
architecture: binaryArchitectureSchema,
entry_point: rawBinaryEntryPointSchema.describe(
"Canonical caller-selected address where raw file offset 0 is mapped and execution is seeded.",
),
});
/** Exact structured-content schemas for target lifecycle operations. */
export const sessionOutputSchemas = {
open_binary: lifecycleResultOf(
z.object({
path: z.string(),
format: targetFormatSchema,
kind: targetKindSchema,
sha256: z.string().regex(/^[a-f0-9]{64}$/u),
architecture: z.enum(BINARY_ARCHITECTURES).nullable(),
}),
z.discriminatedUnion("format", [
detectedLifecycleTargetSchema,
rawLifecycleTargetSchema,
]),
),
close_binary: lifecycleResultOf(
z.union([
@@ -448,19 +469,15 @@ export const sessionOutputSchemas = {
),
binary_session: lifecycleResultOf(
z.union([
z.union([
sessionProvider.extend({
open: z.literal(false),
}),
sessionProvider.extend({
open: z.literal(true),
path: z.string(),
format: targetFormatSchema,
kind: targetKindSchema,
sha256: z.string().regex(/^[a-f0-9]{64}$/u),
architecture: z.enum(BINARY_ARCHITECTURES).nullable(),
}),
]),
sessionProvider.extend({ open: z.literal(false) }),
sessionProvider.extend({
open: z.literal(true),
...detectedLifecycleTargetSchema.shape,
}),
sessionProvider.extend({
open: z.literal(true),
...rawLifecycleTargetSchema.shape,
}),
]),
),
export_evidence_bundle: lifecycleResultOf(
@@ -56,6 +56,7 @@ export const targetFormatSchema = z.enum([
"pe",
"dos-mz",
"dos-com",
"raw-binary",
"zip",
"ipa",
"apk",
+81
View File
@@ -8,6 +8,7 @@ import {
snapshotBinding,
snapshotEvidenceForQuery,
snapshotTarget,
snapshotMatchesTarget,
} from "./analysisSnapshot.js";
import {
ANALYSIS_SNAPSHOT_PROFILE,
@@ -16,6 +17,7 @@ import {
} from "./analysisSnapshot.fixture.js";
import { createEvidence } from "./evidence.js";
import { createEvidenceBundle } from "./evidenceBundle.js";
import type { BinaryTarget } from "./binaryTargetTypes.js";
const snapshotWithHistoricalEvidence = () => {
const target = snapshotTarget(ANALYSIS_SNAPSHOT_TARGET);
@@ -68,6 +70,54 @@ const snapshotWithHistoricalEvidence = () => {
};
describe("analysis snapshot contract", () => {
it("partitions raw snapshots and query identities by the canonical entry", () => {
const target: BinaryTarget = {
path: "/fixture/image.bin",
sha256: ANALYSIS_SNAPSHOT_TARGET.sha256,
kind: "executable",
format: "raw-binary",
architecture: "arm",
availableArchitectures: ["arm"],
entryPoint: "0x8000000",
entryPointSource: "0x08000000",
};
const snapshot = snapshotTarget(target);
const binding = snapshotBinding(ANALYSIS_SNAPSHOT_PROFILE);
const changed = {
...target,
entryPoint: "0x9000000",
entryPointSource: "0x09000000",
};
expect(
snapshotMatchesTarget(snapshot, {
...target,
entryPointSource: "0x8000000",
}),
).toBe(true);
expect(snapshotMatchesTarget(snapshot, changed)).toBe(false);
expect(analysisQueryId(snapshot, binding, "list_procedures", {})).not.toBe(
analysisQueryId(snapshotTarget(changed), binding, "list_procedures", {}),
);
const parsed = analysisSnapshotSchema.parse({
target: snapshot,
binding,
entries: [],
workflow_entries: [],
evidence_bundle: createEvidenceBundle([]),
});
expect(parsed.target).toHaveProperty("entry_point", target.entryPoint);
const { entry_point: _entry, ...legacy } = {
...snapshot,
entry_point: target.entryPoint,
};
expect(
analysisSnapshotSchema.safeParse({ ...parsed, target: legacy }).success,
).toBe(false);
expect(snapshotTarget(ANALYSIS_SNAPSHOT_TARGET)).not.toHaveProperty(
"entry_point",
);
});
it("preserves DOS MZ target and subject formats with the x86 family", () => {
const target = {
path: ANALYSIS_SNAPSHOT_TARGET.path,
@@ -113,6 +163,37 @@ describe("analysis snapshot contract", () => {
expect(parsed.evidence_bundle.records[0]?.subject?.format).toBe("dos-mz");
});
it("rejects a snapshot subject path containing NUL", () => {
const binding = snapshotBinding(ANALYSIS_SNAPSHOT_PROFILE);
const entry = {
query_id: `query_${"0".repeat(64)}`,
operation: "analyze_function",
parameters: {},
execution: {
result: null,
raw_result: null,
provider: binding.provider,
limitations: [],
locations: [],
subject: {
path: "a\u0000b",
sha256: "a".repeat(64),
format: "elf" as const,
architecture: null,
},
},
};
expect(
analysisSnapshotSchema.safeParse({
target: snapshotTarget(ANALYSIS_SNAPSHOT_TARGET),
binding,
entries: [entry],
workflow_entries: [],
evidence_bundle: createEvidenceBundle([]),
}).success,
).toBe(false);
});
it("accepts snapshots with more than ten thousand analysis entries", () => {
const binding = snapshotBinding(ANALYSIS_SNAPSHOT_PROFILE);
const entry = {
+30 -10
View File
@@ -7,6 +7,7 @@ import {
compareUnicodeCodePoints,
compositeKey,
} from "./unicodeCodePointOrder.js";
import { localPathStringSchema } from "./localPath.js";
import {
analysisProfileSchema,
@@ -39,6 +40,7 @@ import { digestSchema } from "./../domain/digests.js";
import { prefixedDigestSchema } from "./../domain/digests.js";
import { canonicalJsonDigestSteps } from "./canonicalJsonDigestSteps.js";
import { freezeJsonSnapshot } from "./immutableJson.js";
import { rawBinaryEntryPointSchema } from "./rawBinary.js";
const architectureSchema = z.enum(BINARY_ARCHITECTURES);
const formatSchema = z.enum([
@@ -48,6 +50,7 @@ const formatSchema = z.enum([
"pe",
"dos-mz",
"dos-com",
"raw-binary",
"zip",
"ipa",
"apk",
@@ -65,7 +68,7 @@ const formatSchema = z.enum([
]);
const kindSchema = z.enum(["executable", "database", "archive", "artifact"]);
const subjectSchema = z.object({
path: z.string().min(1),
path: localPathStringSchema,
sha256: digestSchema,
format: z.enum([
...formatSchema.options,
@@ -79,12 +82,22 @@ const subjectSchema = z.object({
]),
architecture: architectureSchema.nullable(),
});
const targetSchema = z.object({
const targetIdentitySchema = z.object({
sha256: digestSchema,
kind: kindSchema,
format: formatSchema,
architecture: architectureSchema.nullable(),
});
const targetSchema = z.discriminatedUnion("format", [
targetIdentitySchema.extend({
format: z.enum(
formatSchema.options.filter((format) => format !== "raw-binary"),
),
}),
targetIdentitySchema.extend({
format: z.literal("raw-binary"),
entry_point: rawBinaryEntryPointSchema,
}),
]);
const bindingSchema = z
.object({
provider: committedProviderSchema,
@@ -310,12 +323,16 @@ const canonicalJson = (value: unknown): string => {
/** Project a binary into the path-free identity used for cache invalidation. */
export const snapshotTarget = (
target: BinaryTarget,
): AnalysisSnapshotTarget => ({
sha256: target.sha256,
kind: target.kind,
format: target.format,
architecture: target.architecture ?? null,
});
): AnalysisSnapshotTarget => {
const identity = {
sha256: target.sha256,
kind: target.kind,
architecture: target.architecture ?? null,
};
return target.format === "raw-binary"
? { ...identity, format: target.format, entry_point: target.entryPoint }
: { ...identity, format: target.format };
};
/** Build the immutable provider/profile binding used by a cached snapshot. */
export const snapshotBinding = (
@@ -334,7 +351,10 @@ export const snapshotMatchesTarget = (
snapshot.sha256 === target.sha256 &&
snapshot.kind === target.kind &&
snapshot.format === target.format &&
snapshot.architecture === (target.architecture ?? null);
snapshot.architecture === (target.architecture ?? null) &&
(snapshot.format !== "raw-binary" ||
(target.format === "raw-binary" &&
snapshot.entry_point === target.entryPoint));
/** Compare a snapshot binding with the selected concrete analysis profile. */
export const snapshotMatchesProfile = (
+1
View File
@@ -50,6 +50,7 @@ const artifactFormatSchema = z.enum([
"pe",
"dos-mz",
"dos-com",
"raw-binary",
"hopper",
"analysis-database",
"ipa",
+7
View File
@@ -78,6 +78,13 @@ export type BinaryTarget =
readonly executableRole?: never;
readonly managed?: never;
})
| (ExecutableTarget & {
readonly format: "raw-binary";
readonly entryPoint: string;
readonly entryPointSource: string;
readonly executableRole?: never;
readonly managed?: never;
})
| (ExecutableTarget & {
readonly format: "pe";
/** Provider-neutral PE image role observed from COFF characteristics. */
+2 -2
View File
@@ -1,8 +1,8 @@
import { z } from "zod";
import { err, ok, type Result } from "./result.js";
/** Headerless DOS COM interpretation explicitly selected by the caller. */
export const executableFormatHintSchema = z.literal("dos-com");
/** Headerless executable interpretation explicitly selected by the caller. */
export const executableFormatHintSchema = z.enum(["dos-com", "raw-binary"]);
/** Explicit executable interpretation for formats with no identifying header. */
export type ExecutableFormatHint = z.infer<typeof executableFormatHintSchema>;
+16
View File
@@ -291,6 +291,22 @@ describe("analysis evidence identity", () => {
});
});
it("rejects a subject local path containing NUL while admitting an empty path", () => {
const evidence = createEvidence(TARGET, PROVIDER, {
operation: "health",
parameters: {},
result: true,
});
expect(evidence.subject).not.toBeNull();
const withPath = (path: string) => ({
...evidence,
subject: { ...evidence.subject, local_path: path },
});
expect(evidenceSchema.safeParse(withPath("/tmp/fixture")).success).toBe(true);
expect(evidenceSchema.safeParse(withPath("")).success).toBe(true);
expect(evidenceSchema.safeParse(withPath("a\u0000b")).success).toBe(false);
});
it("binds an explicit unknown-subject reason into the semantic Evidence identity", () => {
const reason = "Caller excluded the observed digest.";
const observation = { operation: "health", parameters: {}, result: true };
+3 -1
View File
@@ -2,6 +2,7 @@ import { z } from "zod";
import { digestCanonicalValue } from "./canonicalDigest.js";
import { canonicalJsonDigestSteps } from "./canonicalJsonDigestSteps.js";
import { nulFreeStringSchema } from "./localPath.js";
import {
analysisProfileSchema,
@@ -43,6 +44,7 @@ const subjectSchema = z.object({
"pe",
"dos-mz",
"dos-com",
"raw-binary",
"zip",
"ipa",
"apk",
@@ -65,7 +67,7 @@ const subjectSchema = z.object({
"entitlements",
]),
architecture: z.enum(BINARY_ARCHITECTURES).nullable(),
local_path: z.string(),
local_path: nulFreeStringSchema,
});
/** Source location attached to an evidence observation. */
/** Source-location schema shared by evidence-bearing persistence formats. */
@@ -0,0 +1,664 @@
import { describe, expect, it } from "vitest";
import { analyzeJavaScriptStaticSource } from "./javascriptStaticAnalysis.js";
import { ROLLDOWN_MODULE_INTEROP } from "./javascriptModuleInterop.fixture.js";
const WINDOW =
'new electron.BrowserWindow({webPreferences:{preload:"./preload.js"}});';
const IMPORT = 'let electron = require("electron");';
const WRAP = "electron = __toESM(electron, 1);";
// The upstream runtime uses control-body braces that its bundled printer omits.
// https://github.com/rolldown/rolldown/blob/22a0ab13732d81f2559ad2b7064b688699324889/crates/rolldown/src/runtime/runtime-base.js
const BLOCK_MODULE_INTEROP = ROLLDOWN_MODULE_INTEROP.replace(
'if (from && typeof from === "object" || typeof from === "function") for',
'if (from && typeof from === "object" || typeof from === "function") { for',
)
.replace(
"if (!__hasOwnProp.call(to, key) && key !== except) __defProp",
"if (!__hasOwnProp.call(to, key) && key !== except) { __defProp",
)
.replace(" });", " });\n }")
.replace(" return to;", " }\n return to;");
describe("Electron module interop identity", () => {
it("preserves named APIs through the released Rolldown namespace conversion", () => {
const analysis = analyzeJavaScriptStaticSource(`${ROLLDOWN_MODULE_INTEROP}
${IMPORT} ${WRAP} ${WINDOW}
new electron.BrowserWindow({webPreferences:{preload:runtimePath}});
electron.ipcMain.handle("ping", () => "pong");
electron.contextBridge.exposeInMainWorld("api", {ping:true});
`);
expect(analysis.electron.browser_windows).toMatchObject([
{ preload_path: "./preload.js" },
{ preload_path: null },
]);
expect(analysis.electron.ipc).toMatchObject([
{ channel: "ping", side: "main" },
]);
expect(analysis.electron.context_bridge_apis).toMatchObject([
{ api_key: "api" },
]);
});
it("follows lexical identities when helper and parameter names change", () => {
const source = `${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP} ${WINDOW}`
.replaceAll("__toESM", "namespaceOf")
.replaceAll("__copyProps", "copyNamed")
.replaceAll("mod", "inputModule")
.replaceAll("isNodeMode", "nodeMode")
.replaceAll("target", "namespaceTarget")
.replaceAll("from", "sourceObject");
expect(
analyzeJavaScriptStaticSource(source).electron.browser_windows,
).toMatchObject([{ preload_path: "./preload.js" }]);
});
it("preserves the same operations through control-body braces", () => {
expect(
analyzeJavaScriptStaticSource(
`${BLOCK_MODULE_INTEROP}\n${IMPORT} ${WRAP} ${WINDOW}`,
).electron.browser_windows,
).toMatchObject([{ preload_path: "./preload.js" }]);
});
it("keeps additional operations inside a control block unresolved", () => {
const altered = BLOCK_MODULE_INTEROP.replace(
"{ __defProp",
"{ from = unrelated; __defProp",
);
expect(
analyzeJavaScriptStaticSource(`${altered}\n${IMPORT} ${WRAP} ${WINDOW}`)
.electron.browser_windows,
).toEqual([]);
});
});
const BOUND_INTRINSIC_MUTATIONS: [string, string][] = [
[
"intrinsic changed through aliased prebound arguments",
`const objectAlias = Object; const key = "create"; const define = Object.defineProperty; const mutate = define.bind(null, objectAlias, key); mutate({value:customCreate}); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed through nested prebinding",
`const first = Object.defineProperty.bind(null, Object); const second = first.bind(null, "create"); second({value:customCreate}); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"a replaced bound mutator bind method is unknown",
`const first = Object.defineProperty.bind(null, Object); first.bind = customBind; const second = first.bind(null, "create"); second({value:customCreate}); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed through a computed prebound call",
`const mutate = Object.defineProperty.bind(null, Object, "create"); mutate["call"](null, {value:customCreate}); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed through a computed prebound apply",
`const mutate = Object.defineProperty.bind(null, Object, "create"); mutate["apply"](null, [{value:customCreate}]); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"a replaced bind intrinsic makes a prebound mutator unknown",
`Function.prototype.bind = customBind; const mutate = Object.defineProperty.bind(null, Object, "create"); mutate({value:customCreate}); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
];
describe("Electron module interop uncertainty", () => {
it.each([
...BOUND_INTRINSIC_MUTATIONS,
[
"intrinsic changed through an unresolved mutator target",
`Object.defineProperty(getTarget(), "create", {value:customCreate}); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed via dynamic apply",
`const args = [Object, "getOwnPropertyNames", {value:() => []}]; Object.defineProperty.apply(null, args); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed via spread call",
`const args = [Object, "getOwnPropertyNames", {value:() => []}]; Object.defineProperty.call(null, ...args); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed via Reflect.apply",
`const args = [Object, "getOwnPropertyNames", {value:() => []}]; Reflect.apply(Object.defineProperty, null, args); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed via spread Reflect.apply",
`const args = [null, [Object, "create", {value:customCreate}]]; Reflect.apply(Object.defineProperty, ...args); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed via call",
`Object.defineProperty.call(null, Object, "getOwnPropertyNames", {value:() => []}); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed via apply",
`Object.defineProperty.apply(null, [Object, "getOwnPropertyNames", {value:() => []}]); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed with defineProperty",
`Object.defineProperty(Object, "getOwnPropertyNames", {value:() => []}); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed with Reflect.set",
`Reflect.set(Object, "getOwnPropertyNames", () => []); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed with an aliased mutator",
`const change = Object.defineProperty; change(Object, "create", {value:customCreate}); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed with assign",
`Object.assign(Object, {getOwnPropertyNames:() => []}); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"intrinsic changed with defineProperties",
`Object.defineProperties(Function.prototype, {bind:{value:customBind}}); ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"overwritten Object global",
`Object = customObject; ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"overwritten intrinsic through an alias",
`const objectAlias = Object; objectAlias.create = customCreate; ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"overwritten intrinsic through globalThis",
`globalThis.Object.create = customCreate; ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"helper called before initialization",
`${IMPORT} ${WRAP} ${ROLLDOWN_MODULE_INTEROP}`,
],
[
"fake helper",
`${ROLLDOWN_MODULE_INTEROP}\n__toESM = (mod) => ({BrowserWindow:Fake}); ${IMPORT} ${WRAP}`,
],
[
"changed getter",
`${ROLLDOWN_MODULE_INTEROP.replace("from[k]", "to[k]")}\n${IMPORT} ${WRAP}`,
],
[
"replaced copy helper",
`${ROLLDOWN_MODULE_INTEROP}\n__copyProps = () => ({}); ${IMPORT} ${WRAP}`,
],
[
"replaced intrinsic alias",
`${ROLLDOWN_MODULE_INTEROP}\n__defProp = () => ({}); ${IMPORT} ${WRAP}`,
],
[
"shadowed Object",
`const Object = customObject; ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"overwritten intrinsic",
`Object.create = customCreate; ${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP}`,
],
[
"overwritten alias call",
`${ROLLDOWN_MODULE_INTEROP}\n__hasOwnProp.call = customCall; ${IMPORT} ${WRAP}`,
],
[
"overwritten Function bind",
`${ROLLDOWN_MODULE_INTEROP}\nFunction.prototype.bind = customBind; ${IMPORT} ${WRAP}`,
],
[
"conditional conversion",
`${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} if (flag) { ${WRAP} }`,
],
[
"compound assignment",
`${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} electron ||= __toESM(electron, 1);`,
],
[
"other input",
`${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} electron = __toESM(other, 1);`,
],
[
"later overwrite",
`${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP} electron = unrelated;`,
],
[
"overwritten constructor",
`${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP} electron.BrowserWindow = Fake;`,
],
])("does not infer Electron identity after %s", (_name, setup) => {
expect(
analyzeJavaScriptStaticSource(`${setup}\n${WINDOW}`).electron
.browser_windows,
).toEqual([]);
});
});
describe("Electron module interop helper results", () => {
it.each([
'const {BrowserWindow} = __toESM(require("electron"), 1); new BrowserWindow({});',
'const {BrowserWindow: Window} = __toESM(require("electron"), 1); new Window({});',
'const {default: {BrowserWindow}} = __toESM(require("electron"), 1); new BrowserWindow({});',
'const Window = __toESM(require("electron"), 1).BrowserWindow; new Window({});',
])("preserves a proven result projection: %s", (source) => {
expect(
analyzeJavaScriptStaticSource(`${ROLLDOWN_MODULE_INTEROP}\n${source}`)
.electron.browser_windows,
).toHaveLength(1);
});
it.each([
'const {[key]: Window} = __toESM(require("electron"), 1); new Window({});',
'const {...electron} = __toESM(require("electron"), 1); new electron.BrowserWindow({});',
'let {BrowserWindow} = __toESM(require("electron"), 1); BrowserWindow = Fake; new BrowserWindow({});',
])("keeps an uncertain result projection unresolved: %s", (source) => {
expect(
analyzeJavaScriptStaticSource(`${ROLLDOWN_MODULE_INTEROP}\n${source}`)
.electron.browser_windows,
).toEqual([]);
});
it.each([
"",
", 0",
", false",
", true",
", 1",
', "node"',
', ""',
", null",
])("preserves named exports with a literal node mode: %s", (mode) => {
const analysis = analyzeJavaScriptStaticSource(`${ROLLDOWN_MODULE_INTEROP}
const fresh = __toESM(require("electron")${mode});
new fresh.BrowserWindow({});
const {BrowserWindow} = __toESM(require("electron")${mode});
new BrowserWindow({});
let electron = require("electron");
electron = __toESM(electron${mode}); ${WINDOW}
`);
expect(analysis.electron.browser_windows).toHaveLength(3);
});
it.each(["", ", 0", ", false"])(
"does not assume a module-valued default with node mode: %s",
(mode) => {
const analysis = analyzeJavaScriptStaticSource(`${ROLLDOWN_MODULE_INTEROP}
const original = require("electron");
original.__esModule = true;
original.default = {BrowserWindow: Fake};
const {default: {BrowserWindow}} = __toESM(require("electron")${mode});
new BrowserWindow({});
const other = __toESM(require("electron")${mode}).default;
new other.BrowserWindow({});
new (__toESM(require("electron")${mode}).default.BrowserWindow)({});
`);
expect(analysis.electron.browser_windows).toEqual([]);
},
);
it.each(["__toESM", "identity"])(
"rejects side-effecting extra arguments to %s",
(helper) => {
const analysis = analyzeJavaScriptStaticSource(`${ROLLDOWN_MODULE_INTEROP}
function identity(mod) { return mod; }
const electron = ${helper}(require("electron"), mutate()); ${WINDOW}
`);
expect(analysis.electron.browser_windows).toEqual([]);
},
);
it.each([
"const __toESM = () => ({BrowserWindow:FakeWindow});",
"const __toESM = async (mod) => mod;",
"function* __toESM(mod) { return mod; }",
"const __toESM = (this && this.__toESM) || ((mod) => mod);",
])("keeps an unproven fresh result unresolved: %s", (helper) => {
const analysis = analyzeJavaScriptStaticSource(`${helper}
const electron = __toESM(require("electron"), 1); ${WINDOW}
new (__toESM(require("electron"), 1)).BrowserWindow({});
`);
expect(analysis.electron.browser_windows).toEqual([]);
});
it("preserves a proven fresh namespace and a pure identity helper", () => {
const analysis = analyzeJavaScriptStaticSource(`${ROLLDOWN_MODULE_INTEROP}
const electron = __toESM(require("electron"), 1); ${WINDOW}
new (__toESM(require("electron"), 1)).BrowserWindow({});
function passthrough(value) {return value;}
const plain = passthrough(require("electron"));
new plain.BrowserWindow({});
`);
expect(analysis.electron.browser_windows).toHaveLength(3);
});
});
describe("Electron module interop pattern writes", () => {
it.each([
"({Object} = replacements);",
"[Function] = replacements;",
"({nested:{Object}} = replacements);",
"({replacement:Object = customObject} = replacements);",
"({...Object} = replacements);",
"[...Function] = replacements;",
"for ({Object} of replacements) {}",
"for ([Function] in replacements) {}",
])("rejects an intrinsic replaced through %s", (write) => {
const analysis = analyzeJavaScriptStaticSource(`
${write} ${ROLLDOWN_MODULE_INTEROP} ${IMPORT} ${WRAP} ${WINDOW}
`);
expect(analysis.parse_error_count).toBe(0);
expect(analysis.electron.browser_windows).toEqual([]);
});
it.each([
"({Object:unrelated} = replacements);",
"function decoy(Object) {({Object} = replacements);}",
])("preserves intrinsic identity for an unrelated target: %s", (write) => {
const analysis = analyzeJavaScriptStaticSource(`
${write} ${ROLLDOWN_MODULE_INTEROP} ${IMPORT} ${WRAP} ${WINDOW}
`);
expect(analysis.parse_error_count).toBe(0);
expect(analysis.electron.browser_windows).toHaveLength(1);
});
it("preserves captured operations after later property destructuring", () => {
const analysis = analyzeJavaScriptStaticSource(`
${ROLLDOWN_MODULE_INTEROP} ({create:Object.create} = replacements);
${IMPORT} ${WRAP} ${WINDOW}
`);
expect(analysis.electron.browser_windows).toHaveLength(1);
});
});
describe("Electron module interop intrinsic captures", () => {
it.each([
"var captured = Object.defineProperty;",
"const {defineProperty:captured} = Object;",
"var first = Object.defineProperty; const captured = first;",
])("retains the original function capture through %s", (capture) => {
const runtime = ROLLDOWN_MODULE_INTEROP.replace(
"__defProp = Object.defineProperty",
"__defProp = captured",
);
const analysis = analyzeJavaScriptStaticSource(`
${capture} Object.defineProperty = custom;
${runtime} ${IMPORT} ${WRAP} ${WINDOW}
`);
expect(analysis.electron.browser_windows).toHaveLength(1);
});
it.each(["var", "const"])(
"keeps an intrinsic alias read before its %s initializer unresolved",
(kind) => {
const runtime = ROLLDOWN_MODULE_INTEROP.replace(
"__defProp = Object.defineProperty",
"__defProp = later",
);
const analysis = analyzeJavaScriptStaticSource(`
${runtime} ${kind} later = Object.defineProperty;
${IMPORT} ${WRAP} ${WINDOW}
`);
expect(analysis.electron.browser_windows).toEqual([]);
},
);
it("requires the helper's intrinsic binding to initialize before conversion", () => {
const runtime = ROLLDOWN_MODULE_INTEROP.replace(
"var __defProp = Object.defineProperty;",
"",
);
const analysis = analyzeJavaScriptStaticSource(`
var captured = Object.defineProperty;
${runtime} ${IMPORT} ${WRAP} ${WINDOW}
var __defProp = captured;
`);
expect(analysis.electron.browser_windows).toEqual([]);
});
});
describe("Electron module interop capture and scope", () => {
it.each(["metadata", "alias"])(
"recognizes a hoisted function target through %s",
(target) => {
const analysis = analyzeJavaScriptStaticSource(`
const alias = metadata;
Object.defineProperty(${target}, "x", {value:1});
function metadata() {}
${ROLLDOWN_MODULE_INTEROP} ${IMPORT} ${WRAP} ${WINDOW}
`);
expect(analysis.electron.browser_windows).toHaveLength(1);
},
);
it.each([
"var metadata = function () {};",
"const metadata = () => {};",
"class metadata {}",
])("does not hoist fresh targets from %s", (declaration) => {
const analysis = analyzeJavaScriptStaticSource(`
Object.defineProperty(metadata, "x", {value:1});
${declaration}
${ROLLDOWN_MODULE_INTEROP} ${IMPORT} ${WRAP} ${WINDOW}
`);
expect(analysis.electron.browser_windows).toEqual([]);
});
it.each([
'const {defineProperty:change} = Object; change(Object,"create",{value:customCreate});',
"const objectAlias = Object; const {assign:change} = objectAlias; change(Object,{create:customCreate});",
'const {set:change} = Reflect; change(Object,"create",customCreate);',
'const {Object:{defineProperty:change}} = globalThis; change(Object,"create",{value:customCreate});',
])("rejects a projected intrinsic mutator alias: %s", (write) => {
const source = `${write} ${ROLLDOWN_MODULE_INTEROP}
${IMPORT} ${WRAP} ${WINDOW}
`.replaceAll("__toESM", "namespaceOf");
const analysis = analyzeJavaScriptStaticSource(source);
expect(analysis.parse_error_count).toBe(0);
expect(analysis.electron.browser_windows).toEqual([]);
});
it.each([
"const metadata = {};",
"const metadata = [];",
"const initial = {}; const metadata = initial;",
"const metadata = () => {};",
"const metadata = function () {};",
"const metadata = async () => {};",
"const metadata = function* () {};",
"const metadata = class {};",
"const metadata = /local/;",
"function metadata() {}",
"class metadata {}",
])(
"keeps a fresh mutator target separate from intrinsic identity: %s",
(setup) => {
const analysis = analyzeJavaScriptStaticSource(`
${setup} Object.defineProperty(metadata,"x",{value:1});
${ROLLDOWN_MODULE_INTEROP} ${IMPORT} ${WRAP} ${WINDOW}
`);
expect(analysis.electron.browser_windows).toHaveLength(1);
},
);
it.each([
"const metadata = getMetadata();",
"let metadata = {}; metadata = Object;",
"Object.defineProperty(metadata,'x',{value:1}); const metadata = {};",
"const metadata = {intrinsic:Object}; Object.defineProperty(metadata.intrinsic,'create',{value:customCreate});",
"const metadata = class {static {Object.create = customCreate;}};",
"@(() => Object) class metadata {}",
])("keeps an unproven mutator target unresolved: %s", (setup) => {
const analysis = analyzeJavaScriptStaticSource(`
${setup} Object.defineProperty(metadata,"x",{value:1});
${ROLLDOWN_MODULE_INTEROP} ${IMPORT} ${WRAP} ${WINDOW}
`);
expect(analysis.electron.browser_windows).toEqual([]);
});
it("does not reject unrelated intrinsic property definitions", () => {
const analysis = analyzeJavaScriptStaticSource(`
Object.defineProperty(Object, "unrelated", {value:1});
${ROLLDOWN_MODULE_INTEROP} ${IMPORT} ${WRAP} ${WINDOW}
`);
expect(analysis.electron.browser_windows).toHaveLength(1);
});
it("keeps opaque targets in a generic helper separate from outer module identity", () => {
const analysis = analyzeJavaScriptStaticSource(`
function genericAssign() { Object.assign.apply(null, arguments); }
${ROLLDOWN_MODULE_INTEROP} ${IMPORT} ${WRAP} ${WINDOW}
`);
expect(analysis.electron.browser_windows).toHaveLength(1);
});
it("rejects an opaque intrinsic mutation in the namespace's own callable", () => {
const analysis = analyzeJavaScriptStaticSource(`${ROLLDOWN_MODULE_INTEROP}
function openWindow(args) {
Object.defineProperty.apply(null, args);
${IMPORT} ${WRAP} ${WINDOW}
}
`);
expect(analysis.electron.browser_windows).toEqual([]);
});
it("preserves captured intrinsics across later vendor polyfills and callable writes", () => {
const analysis = analyzeJavaScriptStaticSource(`${ROLLDOWN_MODULE_INTEROP}
Object.create = customCreate;
${IMPORT} ${WRAP}
function runLoop(key) { globalThis[key] = this; }
function polyfill() { Object.create = customCreate; }
${WINDOW}
`);
expect(analysis.electron.browser_windows).toHaveLength(1);
});
it("keeps a shadowed namespace separate from the converted module", () => {
const analysis = analyzeJavaScriptStaticSource(`${ROLLDOWN_MODULE_INTEROP}
${IMPORT} ${WRAP} ${WINDOW}
function decoy(electron) { ${WINDOW} }
`);
expect(analysis.electron.browser_windows).toHaveLength(1);
});
});
describe("Electron module interop generic invocations", () => {
it.each([
'const change = Function.prototype.call.bind(Object.defineProperty); change(null,Object,"create",{value:customCreate});',
'const call = Function.prototype.call; const change = call.bind(Object.defineProperty); change(null,Object,"create",{value:customCreate});',
'const change = Function.prototype.call.bind(Object.defineProperty,null,Object,"create"); change({value:customCreate});',
'Function.prototype.call.call(Object.defineProperty,null,Object,"create",{value:customCreate});',
'Function.prototype.call.apply(Object.defineProperty,[null,Object,"create",{value:customCreate}]);',
'Reflect.apply(Function.prototype.call,Object.defineProperty,[null,Object,"create",{value:customCreate}]);',
'const change = Function.prototype.apply.bind(Object.defineProperty); change(null,[Object,"create",{value:customCreate}]);',
'Function.prototype.apply.call(Object.defineProperty,null,[Object,"create",{value:customCreate}]);',
'Reflect.apply(Function.prototype.apply,Object.defineProperty,[null,[Object,"create",{value:customCreate}]]);',
'const first = Function.prototype.call.bind(Object.defineProperty,null,Object,"create"); const change = first.bind(fake); change({value:customCreate});',
"const change = Function.prototype.call.bind(Object.defineProperty); change(null,...args);",
"const change = Function.prototype.apply.bind(Object.defineProperty); change(null,args);",
'const change = Function.prototype.call.bind(Object.defineProperty,null,...args); change(metadata,"x",{value:1});',
'Function.prototype.call.call.call(Object.defineProperty,null,Object,"create",{value:customCreate});',
'Object.defineProperty.call.call(Object.defineProperty,null,Object,"create",{value:customCreate});',
'Function.prototype.apply.apply(Object.defineProperty,[null,[Object,"create",{value:customCreate}]]);',
'const change = Object.defineProperty.call.bind(Object.defineProperty); change(null,Object,"create",{value:customCreate});',
'const change = Function.prototype.call.call.bind(Object.defineProperty,null,Object,"create"); change({value:customCreate});',
])("follows the callable receiver of a generic invocation: %s", (write) => {
expect(
analyzeJavaScriptStaticSource(
`${write}\n${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP} ${WINDOW}`,
).electron.browser_windows,
).toEqual([]);
});
it.each([
'const change = Function.prototype.call.bind(Object.defineProperty); change(null,metadata,"x",{value:1});',
'const change = Function.prototype.call.bind(Object.defineProperty,null,metadata,"x"); change({value:1});',
'Function.prototype.call.call(Object.defineProperty,null,metadata,"x",{value:1});',
'const change = Function.prototype.apply.bind(Object.defineProperty); change(null,[metadata,"x",{value:1}]);',
'Reflect.apply(Function.prototype.apply,Object.defineProperty,[null,[metadata,"x",{value:1}]]);',
'Function.prototype.call.call.call(Object.defineProperty,null,metadata,"x",{value:1});',
'Function.prototype.apply.apply(Object.defineProperty,[null,[metadata,"x",{value:1}]]);',
'const change = Object.defineProperty.call.bind(Object.defineProperty); change(null,metadata,"x",{value:1});',
])("preserves fresh targets through a generic invocation: %s", (write) => {
expect(
analyzeJavaScriptStaticSource(
`const metadata = {}; ${write}\n${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP} ${WINDOW}`,
).electron.browser_windows,
).toHaveLength(1);
});
});
describe("Electron module interop bound mutators", () => {
it.each([
'const change = Object.defineProperty.bind(null); change(Object,"create",{value:customCreate});',
'const change = Object.defineProperty.bind(null,Object,"create"); change({value:customCreate});',
'const first = Object.defineProperty.bind(null,Object); const change = first; change("create",{value:customCreate});',
'const change = Object.defineProperty.bind(null,Object); change.call(null,"create",{value:customCreate});',
'const change = Object.defineProperty.bind(null,Object); change.apply(null,["create",{value:customCreate}]);',
'const change = Object.defineProperty.bind(null,Object); Reflect.apply(change,null,["create",{value:customCreate}]);',
'Object.defineProperty.bind(null,Object,"create")({value:customCreate});',
'const change = Object.defineProperty.bind(null,...args); change(Object,"create",{value:customCreate});',
'const metadata = {}; Object.defineProperty.call(...args,metadata,"x",{value:1});',
'const metadata = {}; Object.defineProperty.apply(...args,[metadata,"x",{value:1}]);',
'const change = Function.prototype.call.bind(Object.defineProperty,null); change(Object,"create",{value:customCreate});',
'const first = Function.prototype.call.bind(Object.defineProperty,null); const change = first.bind(customReceiver,Object,"create"); change({value:customCreate});',
'const change = Function.prototype.apply.bind(Object.defineProperty,null); change([Object,"create",{value:customCreate}]);',
'Function.prototype.call.call(Object.defineProperty,null,Object,"create",{value:customCreate});',
'Function.prototype.apply.call(Object.defineProperty,null,[Object,"create",{value:customCreate}]);',
'const uncurry = Function.prototype.call.bind(Function.prototype.call); uncurry(Object.defineProperty,null,Object,"create",{value:customCreate});',
'const change = Function.prototype.bind.call(Object.defineProperty,null); change(Object,"create",{value:customCreate});',
'const bind = Function.prototype.call.bind(Function.prototype.bind); const change = bind(Object.defineProperty,null); change(Object,"create",{value:customCreate});',
'const change = Function.prototype.bind.apply(Object.defineProperty,[null,Object,"create"]); change({value:customCreate});',
'const change = Reflect.apply(Function.prototype.bind,Object.defineProperty,[null,Object,"create"]); change({value:customCreate});',
'const first = Object.defineProperty.bind(null,Object); const change = Function.prototype.bind.call(first,null,"create"); change({value:customCreate});',
'Reflect.apply = Object.defineProperty; Reflect.apply(Object,"create",{value:customCreate});',
'const apply = Reflect.apply; Reflect.apply = Object.defineProperty; Reflect.apply(Object,"create",{value:customCreate});',
'const change = Reflect.set.bind(null,Object,"create"); change(customCreate);',
'const change = Object.defineProperty.call; change.call(Object.defineProperty,null,Object,"create",{value:customCreate});',
'const {apply:change} = Object.defineProperty; change.call(Object.defineProperty,null,[Object,"create",{value:customCreate}]);',
'const change = Reflect.apply.call; change.call(Reflect.apply,null,Object.defineProperty,null,[Object,"create",{value:customCreate}]);',
'Reflect.set({},"create",customCreate,Object);',
'const metadata = {}; Reflect.set(metadata,"create",customCreate,Object);',
'const change = Reflect.set.bind(null,{},"create",customCreate); change(Object);',
'Reflect.apply(Reflect.set,null,[{},"create",customCreate,Object]);',
'Reflect.set({},"create",customCreate,...receivers);',
'Reflect.set({},"create",...valuesAndReceivers);',
"Reflect.set({},...keysValuesAndReceivers);",
'Reflect.set({},"create",customCreate,receiver);',
])("rejects intrinsic writes through a bound mutator: %s", (write) => {
expect(
analyzeJavaScriptStaticSource(
`${write}\n${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP} ${WINDOW}`,
).electron.browser_windows,
).toEqual([]);
});
it.each([
'const change = Object.defineProperty.bind(null); change(metadata,"x",{value:1});',
'const change = Object.defineProperty.bind(null,metadata,"x"); change({value:1});',
'const first = Object.defineProperty.bind(null,metadata); const change = first.bind(null,"x"); change({value:1});',
'const change = Function.prototype.call.bind(Object.defineProperty,null); change(metadata,"x",{value:1});',
'const change = Function.prototype.apply.bind(Object.defineProperty,null); change([metadata,"x",{value:1}]);',
'const change = Function.prototype.bind.call(Object.defineProperty,null,metadata,"x"); change({value:1});',
'const bind = Function.prototype.call.bind(Function.prototype.bind); const change = bind(Object.defineProperty,null,metadata,"x"); change({value:1});',
'const change = Function.prototype.bind.apply(Object.defineProperty,[null,metadata,"x"]); change({value:1});',
'const change = Reflect.apply(Function.prototype.bind,Object.defineProperty,[null,metadata,"x"]); change({value:1});',
'const apply = Reflect.apply; Reflect.apply = replacement; apply(Object.defineProperty,null,[metadata,"x",{value:1}]);',
'const change = Object.defineProperty.bind(null,Object,"create");',
'Object.defineProperty.call(null,metadata,"x",{value:1});',
'Object.defineProperty.apply(null,[metadata,"x",{value:1}]);',
'const change = Object.defineProperty.call; change.call(Object.defineProperty,null,metadata,"x",{value:1});',
'const {apply:change} = Object.defineProperty; change.call(Object.defineProperty,null,[metadata,"x",{value:1}]);',
'Reflect.set(metadata,"x",1,{});',
'const receiver = {}; Reflect.set({},"x",1,receiver);',
])("keeps a fresh bound target or unused binding separate: %s", (write) => {
expect(
analyzeJavaScriptStaticSource(
`const metadata = {}; ${write}\n${ROLLDOWN_MODULE_INTEROP}\n${IMPORT} ${WRAP} ${WINDOW}`,
).electron.browser_windows,
).toHaveLength(1);
});
});
it("keeps unrelated exports after an aliased prebound key write", () => {
const analysis = analyzeJavaScriptStaticSource(`
const electron = require("electron");
const key = "Unrelated";
const mutate = Object.defineProperty.bind(null, electron, key);
mutate({value: custom});
new electron.BrowserWindow({});
`);
expect(analysis.electron.browser_windows).toHaveLength(1);
});
@@ -77,7 +77,7 @@ describe("Electron API identity", () => {
it("follows bundler namespace interop helpers without accepting other writes", () => {
const analysis = analyzeJavaScriptStaticSource(`
var __toESM = (mod) => mod;
var __importStar = (this && this.__importStar) || ((mod) => mod);
var __importStar = (mod) => mod;
let electron = require("electron");
electron = __toESM(electron);
new electron.BrowserWindow({ webPreferences: { preload: "./rolldown.js" } });
@@ -120,4 +120,53 @@ describe("Electron API identity", () => {
expect(analysis.electron.browser_windows).toEqual([]);
});
it("follows stable declaration aliases but not an assigned default parameter", () => {
const analysis = analyzeJavaScriptStaticSource(`
const direct = require("electron");
const constAlias = direct;
new constAlias.BrowserWindow({webPreferences:{preload:"./const.js"}});
let letAlias = require("electron");
new letAlias.BrowserWindow({webPreferences:{preload:"./let.js"}});
const { BrowserWindow } = require("electron");
new BrowserWindow({webPreferences:{preload:"./destructured.js"}});
function withDefault(electron = require("./not-electron")) {
if (flag) electron = require("electron");
new electron.BrowserWindow({webPreferences:{preload:"./default.js"}});
}
`);
expect(
analysis.electron.browser_windows.map(({ preload_path }) => preload_path),
).toEqual(["./const.js", "./let.js", "./destructured.js"]);
});
it("preserves one initializer across variable redeclarations without accepting writes", () => {
const analysis = analyzeJavaScriptStaticSource(`
var electron;
var electron = require("electron");
var electron;
new electron.BrowserWindow({webPreferences:{preload:"./redeclared.js"}});
var replaced;
var replaced = require("electron");
replaced = fake;
new replaced.BrowserWindow({webPreferences:{preload:"./replaced.js"}});
var initializedTwice = require("electron");
var initializedTwice = fake;
new initializedTwice.BrowserWindow({});
var conditional;
if (flag) { var conditional = require("electron"); }
new conditional.BrowserWindow({});
`);
expect(
analysis.electron.browser_windows.map(({ preload_path }) => preload_path),
).toEqual(["./redeclared.js"]);
});
});
+8 -4
View File
@@ -86,16 +86,20 @@ export const semanticObjectPatternKeys = (
return key === null ? [] : [key];
});
/** Visit member write targets in direct and destructuring assignment forms. */
export function* semanticMemberWriteTargets(
/** Visit binding and member leaves in direct and destructuring write targets. */
export function* semanticWriteTargets(
root: t.Node,
): Generator<t.MemberExpression | t.OptionalMemberExpression> {
): Generator<t.Identifier | t.MemberExpression | t.OptionalMemberExpression> {
const pending = [root];
while (pending.length > 0) {
const next = pending.pop();
if (next === undefined) break;
const node = unwrapJavaScriptExpression(next).node;
if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node))
if (
t.isIdentifier(node) ||
t.isMemberExpression(node) ||
t.isOptionalMemberExpression(node)
)
yield node;
else if (t.isRestElement(node)) pending.push(node.argument);
else if (t.isAssignmentPattern(node)) pending.push(node.left);
@@ -2,10 +2,9 @@ import * as t from "@babel/types";
import {
semanticStaticPropertyKey,
semanticMemberWriteTargets,
semanticWriteTargets,
unwrapJavaScriptExpression,
} from "./javascriptAstValues.js";
import { SemanticPropertyPathCoverage } from "./javascriptSemanticPropertyPaths.js";
import { traverseJavaScriptAstSteps } from "./javascriptSemanticTraversal.js";
/** Match Electron's supported module entry points. */
@@ -24,7 +23,7 @@ export const electronExportPath = (
/** Static identity recovery cannot establish the absence of Electron usage. */
export const ELECTRON_IDENTITY_LIMITATION =
"Electron API identity follows proven lexical module aliases, including results of namespace interop helpers (__toESM, __importStar, _interopRequireWildcard) recognized by name and a single program-scope function definition; helper bodies are not evaluated. Other reassigned bindings, dynamic selections, and visibly overwritten namespace members are unresolved; missing findings do not establish absence. Arbitrary call side effects and runtime registration are not evaluated.";
"Electron API identity follows proven lexical module aliases and structurally verified module-namespace interop. Other reassignments, dynamic selections, and visibly overwritten namespace members are unresolved; missing findings do not establish absence. Arbitrary call side effects and runtime registration are not evaluated.";
/** Preserve exact property segments instead of flattening literal dotted keys. */
export const electronMemberPath = (
@@ -42,14 +41,98 @@ export const electronMemberPath = (
return { root, members: members.toReversed() };
};
/** Index visible writes through proven Electron aliases, without executing them. */
export function* collectElectronMemberWritesSteps(
/** A known intrinsic callable and its examined positional arguments. */
export interface JavaScriptIntrinsicInvocation {
readonly kind: "known" | "opaque";
/** The original bound receiver; rebinding cannot replace it. */
readonly receiver?: t.Node;
readonly path: readonly string[];
readonly arguments:
| readonly t.CallExpression["arguments"][number][]
| undefined;
}
/** Index member and binding writes through caller-proven lexical identities. */
export function* collectJavaScriptIdentityWritesSteps(
program: t.Program,
origin: (root: t.Node) => readonly string[] | undefined,
): Generator<void, SemanticPropertyPathCoverage> {
const writes = new SemanticPropertyPathCoverage();
origin: (
root: t.Node,
kind: "binding" | "member" | "opaque-call",
) => readonly string[] | undefined,
intrinsicInvocation: (
node: t.CallExpression | t.OptionalCallExpression,
) => JavaScriptIntrinsicInvocation | undefined,
staticString: (node: t.Node | undefined) => string | undefined,
freshObject: (node: t.Node) => boolean,
retain: (node: t.Node, path: readonly (string | null)[]) => void,
): Generator<void> {
const objectMutators = new Set([
"defineProperty",
"defineProperties",
"assign",
"setPrototypeOf",
]);
const reflectMutators = new Set([
"set",
"deleteProperty",
"defineProperty",
"setPrototypeOf",
]);
const keyedMutators = new Set(["set", "deleteProperty", "defineProperty"]);
yield* traverseJavaScriptAstSteps(program, {
enter: (node) => {
if (t.isCallExpression(node) || t.isOptionalCallExpression(node)) {
const invocation = intrinsicInvocation(node);
if (invocation?.kind === "opaque") {
const scope = origin(node, "opaque-call");
if (scope !== undefined) retain(node, scope);
return;
}
const callee = invocation?.path;
const arguments_ = invocation?.arguments;
const method = callee?.at(-1);
const owner = callee?.length === 3 ? callee[1] : undefined;
if (
(owner === "Object" && objectMutators.has(method ?? "")) ||
(owner === "Reflect" && reflectMutators.has(method ?? ""))
) {
// Reflect.set can write through its explicit receiver as well as
// dispatching through its target. Both identities need examination.
const targets =
owner === "Reflect" &&
method === "set" &&
arguments_ !== undefined &&
(arguments_.length >= 4 || arguments_.some(t.isSpreadElement))
? [
arguments_[0],
arguments_.some(t.isSpreadElement)
? undefined
: arguments_[3],
]
: [arguments_?.[0]];
for (const target of targets) {
// A known mutator with an opaque argument list can overwrite any
// captured intrinsic. Do not turn an unexamined target into proof.
if (target === undefined || t.isSpreadElement(target)) {
const scope = origin(node, "opaque-call");
if (scope !== undefined) retain(node, scope);
}
if (t.isNode(target) && !t.isSpreadElement(target)) {
const { root, members } = electronMemberPath(target);
const exported = origin(root, "member");
if (exported !== undefined) {
const key = keyedMutators.has(method ?? "")
? [staticString(arguments_?.[1]) ?? null]
: [];
retain(node, [...exported, ...members, ...key]);
} else if (!freshObject(target)) {
const scope = origin(node, "opaque-call");
if (scope !== undefined) retain(node, scope);
}
}
}
}
}
const target = t.isAssignmentExpression(node)
? node.left
: t.isUpdateExpression(node)
@@ -60,12 +143,16 @@ export function* collectElectronMemberWritesSteps(
? node.left
: undefined;
if (target === undefined) return;
for (const member of semanticMemberWriteTargets(target)) {
const { root, members } = electronMemberPath(member);
const exported = origin(root);
if (exported !== undefined) writes.retain([...exported, ...members]);
for (const leaf of semanticWriteTargets(target)) {
if (t.isIdentifier(leaf)) {
const exported = origin(leaf, "binding");
if (exported !== undefined) retain(node, exported);
continue;
}
const { root, members } = electronMemberPath(leaf);
const exported = origin(root, "member");
if (exported !== undefined) retain(node, [...exported, ...members]);
}
},
});
return writes;
}
@@ -0,0 +1,115 @@
import * as t from "@babel/types";
import type { JavaScriptIntrinsicInvocation } from "./javascriptElectronMemberWrites.js";
import {
semanticStaticPropertyKey,
unwrapJavaScriptExpression,
} from "./javascriptAstValues.js";
const arrayArguments = (array: t.Node | undefined) =>
t.isArrayExpression(array) &&
array.elements.every((element) => t.isExpression(element))
? array.elements.filter((element): element is t.Expression =>
t.isExpression(element),
)
: undefined;
const invocationArguments = (
method: "call" | "apply",
arguments_: JavaScriptIntrinsicInvocation["arguments"],
) =>
t.isSpreadElement(arguments_?.[0])
? undefined
: method === "apply"
? arrayArguments(arguments_?.[1])
: arguments_?.slice(1);
/**
* Normalize known invocation syntax once, retaining bound argument prefixes.
* Binding a function alone is not a write; only its eventual call is examined.
*/
export const resolveJavaScriptIntrinsicInvocation = (
node: t.CallExpression | t.OptionalCallExpression,
intrinsicPath: (node: t.Node) => readonly string[] | undefined,
boundIntrinsic: (node: t.Node) => JavaScriptIntrinsicInvocation | undefined,
intrinsicReadChanged: (node: t.Node, path: readonly string[]) => boolean,
): JavaScriptIntrinsicInvocation | undefined => {
const visited = new Set<t.Node>();
let callee: t.Node = node.callee;
let arguments_: JavaScriptIntrinsicInvocation["arguments"] = node.arguments;
let receiver: t.Node | undefined;
let explicitReceiver = false;
for (;;) {
callee = unwrapJavaScriptExpression(callee).node;
if (visited.has(callee)) return undefined;
visited.add(callee);
let path = intrinsicPath(callee);
if (path !== undefined && intrinsicReadChanged(callee, path))
return { kind: "opaque", path, arguments: undefined };
if (path === undefined) {
if (
t.isMemberExpression(callee) ||
t.isOptionalMemberExpression(callee)
) {
const method = semanticStaticPropertyKey(
callee.property,
callee.computed,
);
if (method === "call" || method === "apply") {
const bound = boundIntrinsic(callee.object);
if (
bound !== undefined &&
intrinsicReadChanged(callee, [...bound.path, method])
)
return { kind: "opaque", path: bound.path, arguments: undefined };
receiver = arguments_?.[0];
explicitReceiver = true;
callee = callee.object;
arguments_ = invocationArguments(method, arguments_);
continue;
}
}
const bound = boundIntrinsic(callee);
if (bound === undefined) return undefined;
if (bound.kind === "opaque") return bound;
path = bound.path;
receiver = bound.receiver;
explicitReceiver = true;
arguments_ =
bound.arguments === undefined
? undefined
: [...bound.arguments, ...(arguments_ ?? [])];
}
const method = path.length > 3 ? path.at(-1) : undefined;
if (method === "call" || method === "apply") {
// These properties hold generic function values. Their receiver selects
// the callable; property-chain depth does not consume more arguments.
const callable: t.Node | undefined = explicitReceiver
? receiver
: t.isMemberExpression(callee) || t.isOptionalMemberExpression(callee)
? callee.object
: undefined;
if (!t.isExpression(callable)) return undefined;
callee = callable;
receiver = arguments_?.[0];
explicitReceiver = true;
arguments_ = invocationArguments(method, arguments_);
continue;
}
if (path.join(".") === "intrinsic.Reflect.apply") {
const callable = arguments_?.[0];
if (!t.isExpression(callable)) return undefined;
callee = callable;
receiver = arguments_?.[1];
explicitReceiver = true;
arguments_ = arrayArguments(arguments_?.[2]);
continue;
}
return {
kind: "known",
path,
arguments: arguments_,
...(receiver === undefined ? {} : { receiver }),
};
}
};
@@ -0,0 +1,24 @@
// Rolldown runtime from the public T3 Code nightly 20261011.2967 main.cjs.
// The input is inert source: none of these helpers or Electron APIs is executed.
export const ROLLDOWN_MODULE_INTEROP = `
var __create = Object.create;
var __defProp = Object.defineProperty;
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
var __getOwnPropNames = Object.getOwnPropertyNames;
var __getProtoOf = Object.getPrototypeOf;
var __hasOwnProp = Object.prototype.hasOwnProperty;
var __copyProps = (to, from, except, desc) => {
if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
key = keys[i];
if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
get: ((k) => from[k]).bind(null, key),
enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
});
}
return to;
};
var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
value: mod,
enumerable: true
}) : target, mod));
`;
@@ -0,0 +1,774 @@
import { parseExpression } from "@babel/parser";
import * as t from "@babel/types";
import type { JavaScriptModuleOrigin } from "./javascriptSemanticIr.js";
import {
isUnshadowedGlobal,
resolveSemanticBindingState,
semanticScopeId,
semanticStableInitializer,
type JavaScriptSemanticAnalysisState,
type JavaScriptSemanticBindingState,
} from "./javascriptSemanticState.js";
import { semanticRequireOrigin } from "./javascriptSemanticRequireOrigin.js";
import {
childNodes,
javaScriptAstChildKeys,
} from "./javascriptSemanticTraversal.js";
import {
electronMemberPath,
type JavaScriptIntrinsicInvocation,
} from "./javascriptElectronMemberWrites.js";
import { resolveJavaScriptIntrinsicInvocation } from "./javascriptIntrinsicInvocation.js";
import { SemanticPropertyPathCoverage } from "./javascriptSemanticPropertyPaths.js";
import {
readExactJavaScriptLiteral,
unwrapJavaScriptExpression,
} from "./javascriptAstValues.js";
// Match the complete Rolldown runtime operations, including its live getters.
// Names and formatting are irrelevant; lexical roles, operators and keys are not.
const TO_ESM = parseExpression(`(mod, isNodeMode, target) => (
target = mod != null ? __create(__getProtoOf(mod)) : {},
__copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default")
? __defProp(target, "default", {value: mod, enumerable: true}) : target, mod)
)`);
const COPY_PROPS = parseExpression(`(to, from, except, desc) => {
if (from && typeof from === "object" || typeof from === "function")
for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
key = keys[i];
if (!__hasOwnProp.call(to, key) && key !== except)
__defProp(to, key, {
get: ((k) => from[k]).bind(null, key),
enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
});
}
return to;
}`);
const INTRINSICS: Readonly<Record<string, readonly string[]>> = {
__create: ["Object", "create"],
__getProtoOf: ["Object", "getPrototypeOf"],
__defProp: ["Object", "defineProperty"],
__getOwnPropNames: ["Object", "getOwnPropertyNames"],
__getOwnPropDesc: ["Object", "getOwnPropertyDescriptor"],
__hasOwnProp: ["Object", "prototype", "hasOwnProperty"],
};
interface IntrinsicDependency {
readonly path: readonly string[];
readonly capturedAt?: t.Node;
}
interface InteropOrigin {
readonly origin: JavaScriptModuleOrigin;
readonly dependencies: readonly IntrinsicDependency[];
readonly defaultIsModule: boolean;
}
interface InteropHelper {
readonly dependencies: readonly IntrinsicDependency[];
readonly readyAfter: number;
readonly identity: boolean;
}
/** Prove one inert namespace conversion without relaxing general assignment semantics. */
export const createSemanticModuleInterop = (
state: JavaScriptSemanticAnalysisState,
) => {
const helpers = new Map<string, InteropHelper | null>();
const origins = new Map<string, InteropOrigin>();
const calls = new WeakMap<t.Node, InteropOrigin>();
const intrinsicBindings = new Map<string, readonly string[] | null>();
const writes: {
readonly scope: string;
readonly offset: number;
readonly coverage: SemanticPropertyPathCoverage;
}[] = [];
const invalidatedBindings = new Map<string, boolean>();
const invalidatedCalls = new WeakMap<t.Node, boolean>();
const opaqueMutationPath = (node: t.Node): readonly string[] => {
let current: t.Node | undefined = node;
while (current !== undefined) {
if (t.isFunction(current))
return ["opaque-intrinsic", semanticScopeId("function", current)];
current = state.parentsByNode.get(current);
}
return ["intrinsic"];
};
const intrinsicPath = (node: t.Node): readonly string[] | undefined => {
let current = node;
const visited = new Set<string>();
const pending: { id: string; suffixLength: number }[] = [];
let suffix: readonly string[] = [];
const finish = (
path: readonly string[] | undefined,
): readonly string[] | undefined => {
for (const binding of pending)
intrinsicBindings.set(
binding.id,
path === undefined
? null
: path.slice(0, path.length - binding.suffixLength),
);
return path;
};
for (;;) {
const { root, members } = electronMemberPath(current);
if (members.some((member) => member === null)) return finish(undefined);
suffix = [...(members as readonly string[]), ...suffix];
for (const global of ["Object", "Function", "Reflect"])
if (isUnshadowedGlobal(root, state, global))
return finish(["intrinsic", global, ...suffix]);
for (const global of ["globalThis", "global", "window", "self"])
if (isUnshadowedGlobal(root, state, global))
return finish(["intrinsic", ...suffix]);
if (!t.isIdentifier(root)) return finish(undefined);
const binding = resolveSemanticBindingState(state, root, root.name);
const cached =
binding === undefined
? undefined
: intrinsicBindings.get(binding.bindingId);
if (cached !== undefined)
return finish(cached === null ? undefined : [...cached, ...suffix]);
const initializer = semanticStableInitializer(binding, state);
if (
binding === undefined ||
initializer === undefined ||
initializer.projection.some((segment) => segment === null) ||
visited.has(binding.bindingId)
)
return finish(undefined);
visited.add(binding.bindingId);
pending.push({ id: binding.bindingId, suffixLength: suffix.length });
suffix = [...initializer.projection.map(String), ...suffix];
current = initializer.node;
}
};
// A nominal alias path is sufficient for conservative mutation lookup, but
// helper proof also needs each read to follow initialization. An alias copy
// retains the earlier function capture; a member read captures it anew.
const capturedIntrinsic = (node: t.Node): IntrinsicDependency | undefined => {
const path = intrinsicPath(node);
if (path === undefined) return undefined;
const visited = new Set<string>();
let current = node;
let capturedAt = node;
let suffixLength = 0;
for (;;) {
const { root, members } = electronMemberPath(current);
suffixLength += members.length;
if (!t.isIdentifier(root)) return undefined;
const binding = resolveSemanticBindingState(state, root, root.name);
if (binding === undefined) return { path, capturedAt };
const initializer = semanticStableInitializer(binding, state);
if (
initializer === undefined ||
(initializer.node.end ?? Infinity) >= (root.start ?? -1) ||
visited.has(binding.bindingId)
)
return undefined;
visited.add(binding.bindingId);
if (suffixLength === 0) capturedAt = initializer.node;
suffixLength += initializer.projection.length;
current = initializer.node;
}
};
const staticString = (node: t.Node | undefined): string | undefined => {
if (node === undefined) return undefined;
const visited = new Set<string>();
let current = node;
for (;;) {
const literal = readExactJavaScriptLiteral(current);
if (literal.found)
return typeof literal.value === "string" ? literal.value : undefined;
const expression = unwrapJavaScriptExpression(current).node;
if (!t.isIdentifier(expression)) return undefined;
const binding = resolveSemanticBindingState(
state,
expression,
expression.name,
);
const initializer = semanticStableInitializer(binding, state);
if (
binding === undefined ||
initializer === undefined ||
initializer.projection.length !== 0 ||
(initializer.node.end ?? Infinity) >= (expression.start ?? -1) ||
visited.has(binding.bindingId)
)
return undefined;
visited.add(binding.bindingId);
current = initializer.node;
}
};
const intrinsicReadChanged = (
node: t.Node,
path: readonly string[],
): boolean => {
const capture = capturedIntrinsic(node)?.capturedAt ?? node;
const scope = opaqueMutationPath(capture).join(".");
const method = path.at(-1);
const invocationMethod =
method === "bind" || method === "call" || method === "apply";
return writes.some(
(write) =>
(write.scope === scope || write.scope === "intrinsic") &&
write.offset < (capture.start ?? -1) &&
(write.coverage.covers(path) ||
(invocationMethod &&
write.coverage.covers([
"intrinsic",
"Function",
"prototype",
method,
]))),
);
};
const resolveBoundIntrinsic = (
node: t.Node,
): JavaScriptIntrinsicInvocation | undefined => {
const visited = new Set<string>();
const argumentGroups: t.CallExpression["arguments"][] = [];
const bindReads: t.Node[] = [];
let opaqueArguments = false;
let receiver: t.Node | undefined;
let current = node;
for (;;) {
current = unwrapJavaScriptExpression(current).node;
if (t.isIdentifier(current)) {
const binding = resolveSemanticBindingState(
state,
current,
current.name,
);
const initializer = semanticStableInitializer(binding, state);
if (
binding === undefined ||
initializer === undefined ||
initializer.projection.length !== 0 ||
(initializer.node.end ?? Infinity) >= (current.start ?? -1) ||
visited.has(binding.bindingId)
)
return undefined;
visited.add(binding.bindingId);
current = initializer.node;
continue;
}
if (!t.isCallExpression(current)) return undefined;
const { root, members } = electronMemberPath(current.callee);
let bindTarget = root;
let bindingArguments: JavaScriptIntrinsicInvocation["arguments"] =
current.arguments;
let captured = capturedIntrinsic(current.callee);
let terminal = captured?.path.at(-1) === "bind";
let path: readonly string[] | undefined = captured?.path.slice(0, -1);
if (members.at(-1) === "bind") {
// A direct .bind may continue a bound callable, without discarding members.
if (!terminal && members.length !== 1) return undefined;
bindReads.push(captured?.capturedAt ?? current.callee);
} else {
// Reuse the invocation owner for generic call/apply/Reflect.apply of bind.
const invocation = resolveJavaScriptIntrinsicInvocation(
current,
intrinsicPath,
boundIntrinsic,
intrinsicReadChanged,
);
if (
invocation?.kind !== "known" ||
invocation.path.join(".") !== "intrinsic.Function.prototype.bind" ||
invocation.receiver === undefined
)
return undefined;
bindTarget = invocation.receiver;
bindingArguments = invocation.arguments;
captured = capturedIntrinsic(bindTarget);
terminal = captured !== undefined;
path = captured?.path;
}
receiver = bindingArguments?.[0];
const ownArguments = bindingArguments?.slice(1) ?? [];
opaqueArguments ||=
bindingArguments === undefined || t.isSpreadElement(receiver);
opaqueArguments ||= ownArguments.some((argument) =>
t.isSpreadElement(argument),
);
argumentGroups.push(ownArguments);
if (!terminal || path === undefined) {
current = bindTarget;
continue;
}
const boundPath = [...path, "bind"];
const functionBind = ["intrinsic", "Function", "prototype", "bind"];
opaqueArguments ||= bindReads.some((capture) => {
const scope = opaqueMutationPath(capture).join(".");
return writes.some(
(write) =>
(write.scope === scope || write.scope === "intrinsic") &&
write.offset < (capture.start ?? -1) &&
(write.coverage.covers(boundPath) ||
write.coverage.covers(functionBind)),
);
});
return {
kind: opaqueArguments ? "opaque" : "known",
path,
...(receiver === undefined ? {} : { receiver }),
// Rebinding appends arguments to the earlier bound argument list.
arguments: opaqueArguments
? undefined
: argumentGroups.toReversed().flat(),
};
}
};
const activeBoundValues = new WeakSet<t.Node>();
const boundIntrinsic = (
node: t.Node,
): JavaScriptIntrinsicInvocation | undefined => {
if (activeBoundValues.has(node)) return undefined;
activeBoundValues.add(node);
try {
return resolveBoundIntrinsic(node);
} finally {
activeBoundValues.delete(node);
}
};
const isFreshObject = (node: t.Node): boolean => {
const visited = new Set<string>();
let current = node;
for (;;) {
current = unwrapJavaScriptExpression(current).node;
if (
t.isObjectExpression(current) ||
t.isArrayExpression(current) ||
t.isFunction(current) ||
(t.isClass(current) && !current.decorators?.length) ||
t.isRegExpLiteral(current)
)
return true;
if (!t.isIdentifier(current)) return false;
const binding = resolveSemanticBindingState(state, current, current.name);
const initializer = unprojectedInitializer(binding, state);
if (
binding === undefined ||
initializer === undefined ||
(!t.isFunctionDeclaration(initializer) &&
(initializer.end ?? Infinity) >= (current.start ?? -1)) ||
visited.has(binding.bindingId)
)
return false;
visited.add(binding.bindingId);
current = initializer;
}
};
const helperProof = (
binding: JavaScriptSemanticBindingState,
): InteropHelper | undefined => {
const cached = helpers.get(binding.bindingId);
if (cached !== undefined) return cached ?? undefined;
helpers.set(binding.bindingId, null);
if (state.scopesById.get(binding.scopeId)?.kind !== "program")
return undefined;
const wrapper = unprojectedInitializer(binding, state);
if (wrapper === undefined) return undefined;
if (identityFunction(wrapper, state)) {
const proof = {
dependencies: [],
readyAfter: t.isFunctionDeclaration(wrapper)
? -1
: (wrapper.end ?? Infinity),
identity: true,
};
helpers.set(binding.bindingId, proof);
return proof;
}
const wrapperRoles = canonicalRoles(wrapper, TO_ESM, state);
const copyBinding = wrapperRoles?.get("__copyProps");
const copy = unprojectedInitializer(copyBinding, state);
const copyRoles =
copy === undefined ? undefined : canonicalRoles(copy, COPY_PROPS, state);
if (
wrapperRoles === undefined ||
copyRoles === undefined ||
copy === undefined
)
return undefined;
const dependencies: IntrinsicDependency[] = [];
let readyAfter = Math.max(wrapper.end ?? Infinity, copy.end ?? Infinity);
for (const roles of [wrapperRoles, copyRoles])
for (const [role, dependency] of roles) {
const expected = INTRINSICS[role];
if (expected === undefined) continue;
const initializer = unprojectedInitializer(dependency, state);
const captured =
initializer === undefined
? undefined
: capturedIntrinsic(initializer);
if (
initializer === undefined ||
captured === undefined ||
JSON.stringify(captured.path) !==
JSON.stringify(["intrinsic", ...expected])
)
return undefined;
readyAfter = Math.max(readyAfter, initializer.end ?? Infinity);
dependencies.push(captured);
if (role === "__hasOwnProp")
dependencies.push({ path: [...captured.path, "call"] });
}
dependencies.push(
{ path: ["intrinsic", "Function", "prototype", "bind"] },
{ path: ["intrinsic", "Function", "prototype", "call"] },
);
const proof = {
dependencies,
identity: false,
readyAfter,
};
helpers.set(binding.bindingId, proof);
return proof;
};
const provenCall = (node: t.Node) => {
if (!t.isCallExpression(node) || !t.isIdentifier(node.callee))
return undefined;
const helper = resolveSemanticBindingState(
state,
node.callee,
node.callee.name,
);
const proof = helper === undefined ? undefined : helperProof(helper);
const input = node.arguments[0];
const mode = node.arguments[1];
const literalMode =
mode === undefined
? { found: true, value: false }
: t.isExpression(mode)
? readExactJavaScriptLiteral(mode)
: { found: false };
if (
proof === undefined ||
proof.readyAfter >= (node.start ?? -1) ||
!t.isExpression(input) ||
node.arguments.length > 2 ||
!literalMode.found
)
return undefined;
return {
input,
// A truthy node mode forces the module-valued default. Other modes
// preserve named exports without proving the source's default property.
defaultIsModule: !proof.identity && Boolean(literalMode.value),
dependencies: proof.dependencies.map((dependency) => ({
...dependency,
capturedAt: dependency.capturedAt ?? node,
})),
};
};
const callOrigin = (node: t.Node): InteropOrigin | undefined => {
const cached = calls.get(node);
if (cached !== undefined) return cached;
const { root, members } = electronMemberPath(node);
if (!members.every((member): member is string => member !== null))
return undefined;
const converted = provenCall(root);
const required =
converted === undefined
? undefined
: semanticRequireOrigin(converted.input, state)?.origin;
if (
converted === undefined ||
required === undefined ||
required.importedPath.length !== 0 ||
(members[0] === "default" && !converted.defaultIsModule)
)
return undefined;
const result = {
origin: { ...required, importedPath: members },
dependencies: converted.dependencies,
defaultIsModule: converted.defaultIsModule,
};
calls.set(node, result);
return result;
};
const origin = (
binding: JavaScriptSemanticBindingState,
): InteropOrigin | undefined => {
const single = semanticStableInitializer(binding, state);
if (single !== undefined) {
if (
!single.projection.every(
(key): key is string => typeof key === "string",
)
)
return undefined;
const converted = callOrigin(single.node);
if (
converted?.origin.importedPath.length === 0 &&
single.projection[0] === "default" &&
!converted.defaultIsModule
)
return undefined;
const result =
converted === undefined
? undefined
: {
...converted,
origin: {
...converted.origin,
importedPath: [
...converted.origin.importedPath,
...single.projection,
],
},
};
if (result !== undefined) origins.set(binding.bindingId, result);
return result;
}
const [initial, converted] = binding.initializers;
if (
binding.definitions.length !== 2 ||
binding.definitions[0]?.kind !== "variable" ||
binding.definitions[1]?.kind !== "assignment" ||
binding.initializers.length !== 2 ||
initial === undefined ||
converted === undefined ||
initial.projection.length !== 0 ||
converted.projection.length !== 0 ||
state.conditionalInitializers.has(initial.node)
)
return undefined;
const call = converted.node;
const assignment = state.parentsByNode.get(call);
const statement =
assignment === undefined
? undefined
: state.parentsByNode.get(assignment);
const declaration = state.parentsByNode.get(initial.node);
const declarationStatement =
declaration === undefined
? undefined
: state.parentsByNode.get(declaration);
if (
!t.isCallExpression(call) ||
!t.isIdentifier(call.callee) ||
!t.isAssignmentExpression(assignment, { operator: "=" }) ||
assignment.right !== call ||
!t.isIdentifier(assignment.left, { name: binding.name }) ||
!t.isExpressionStatement(statement) ||
!t.isVariableDeclarator(declaration) ||
!t.isVariableDeclaration(declarationStatement) ||
state.parentsByNode.get(statement) !==
state.parentsByNode.get(declarationStatement) ||
(initial.node.start ?? Infinity) >= (call.start ?? -1)
)
return undefined;
const convertedCall = provenCall(call);
const input = convertedCall?.input;
if (
!t.isIdentifier(input) ||
resolveSemanticBindingState(state, input, input.name) !== binding
)
return undefined;
const required = semanticRequireOrigin(initial.node, state)?.origin;
if (required === undefined || required.importedPath.length !== 0)
return undefined;
if (convertedCall === undefined) return undefined;
const result = {
origin: required,
dependencies: convertedCall.dependencies,
defaultIsModule: convertedCall.defaultIsModule,
};
origins.set(binding.bindingId, result);
return result;
};
const invalidatedOrigin = (record: InteropOrigin | undefined): boolean =>
record?.dependencies.some(({ path, capturedAt }) => {
if (capturedAt === undefined) return true;
const scope = opaqueMutationPath(capturedAt).join(".");
// Captured function values survive later replacement of global
// properties. Other callable bodies are not execution evidence.
return writes.some(
(write) =>
(write.scope === scope || write.scope === "intrinsic") &&
write.offset < (capturedAt.start ?? -1) &&
write.coverage.covers(path),
);
}) ?? false;
return {
origin,
callOrigin,
intrinsicPath,
intrinsicInvocation: (node: t.CallExpression | t.OptionalCallExpression) =>
resolveJavaScriptIntrinsicInvocation(
node,
intrinsicPath,
boundIntrinsic,
intrinsicReadChanged,
),
boundIntrinsic,
staticString,
isFreshObject,
opaqueMutationPath,
retainWrite: (node: t.Node, path: readonly (string | null)[]) => {
const coverage = new SemanticPropertyPathCoverage();
coverage.retain(path[0] === "opaque-intrinsic" ? ["intrinsic"] : path);
writes.push({
scope: opaqueMutationPath(node).join("."),
offset: node.start ?? Infinity,
coverage,
});
},
invalidated: (binding: JavaScriptSemanticBindingState): boolean => {
const cached = invalidatedBindings.get(binding.bindingId);
if (cached !== undefined) return cached;
const result = invalidatedOrigin(origins.get(binding.bindingId));
invalidatedBindings.set(binding.bindingId, result);
return result;
},
invalidatedCall: (node: t.Node): boolean => {
const cached = invalidatedCalls.get(node);
if (cached !== undefined) return cached;
const result = invalidatedOrigin(calls.get(node));
invalidatedCalls.set(node, result);
return result;
},
};
};
const identityFunction = (
node: t.Node,
state: JavaScriptSemanticAnalysisState,
): boolean => {
if (
!t.isFunction(node) ||
node.async ||
node.generator ||
node.params.length !== 1
)
return false;
const parameter = node.params[0];
const result = t.isBlockStatement(node.body)
? node.body.body.length === 1 && t.isReturnStatement(node.body.body[0])
? node.body.body[0].argument
: undefined
: node.body;
return (
t.isIdentifier(parameter) &&
t.isIdentifier(result) &&
resolveSemanticBindingState(state, parameter, parameter.name) !==
undefined &&
resolveSemanticBindingState(state, parameter, parameter.name) ===
resolveSemanticBindingState(state, result, result.name)
);
};
const unprojectedInitializer = (
binding: JavaScriptSemanticBindingState | undefined,
state: JavaScriptSemanticAnalysisState,
): t.Node | undefined => {
const initializer = semanticStableInitializer(binding, state);
return initializer?.projection.length === 0 ? initializer.node : undefined;
};
/** Match operations and lexical roles, allowing single-statement control blocks. */
const canonicalRoles = (
actual: t.Node,
pattern: t.Node,
state: JavaScriptSemanticAnalysisState,
): ReadonlyMap<string, JavaScriptSemanticBindingState> | undefined => {
const roles = new Map<string, JavaScriptSemanticBindingState>();
const used = new Map<string, string>();
const pending: { actual: t.Node; pattern: t.Node; parent: t.Node | null }[] =
[{ actual, pattern, parent: null }];
while (pending.length !== 0) {
const pair = pending.pop();
if (pair === undefined) return undefined;
const { parent } = pair;
const controlBody =
(t.isIfStatement(parent) &&
(parent.consequent === pair.pattern ||
parent.alternate === pair.pattern)) ||
(t.isForStatement(parent) && parent.body === pair.pattern);
const node = controlBody ? controlBodyOperation(pair.actual) : pair.actual;
const expected = controlBody
? controlBodyOperation(pair.pattern)
: pair.pattern;
if (node.type !== expected.type) return undefined;
const literalKey =
parent !== null &&
((t.isMemberExpression(parent) &&
!parent.computed &&
parent.property === expected) ||
(t.isObjectProperty(parent) &&
!parent.computed &&
parent.key === expected));
if (t.isIdentifier(expected) && t.isIdentifier(node) && !literalKey) {
const binding = resolveSemanticBindingState(state, node, node.name);
if (
binding === undefined ||
(roles.has(expected.name) && roles.get(expected.name) !== binding) ||
(used.has(binding.bindingId) &&
used.get(binding.bindingId) !== expected.name)
)
return undefined;
roles.set(expected.name, binding);
used.set(binding.bindingId, expected.name);
}
const visitorKeys = javaScriptAstChildKeys(expected);
for (const [key, field] of Object.entries(
t.NODE_FIELDS[expected.type] ?? {},
)) {
if (
visitorKeys.includes(key) ||
(t.isIdentifier(expected) && key === "name" && !literalKey)
)
continue;
const fallback: unknown = Reflect.get(field, "default");
if (
JSON.stringify(Reflect.get(node, key) ?? fallback) !==
JSON.stringify(Reflect.get(expected, key) ?? fallback)
)
return undefined;
}
const children = childNodes(node),
expectedChildren = childNodes(expected);
if (children.length !== expectedChildren.length) return undefined;
for (const [index, child] of children.entries()) {
const expectedChild = expectedChildren[index];
if (expectedChild !== undefined)
pending.push({
actual: child,
pattern: expectedChild,
parent: expected,
});
}
}
return roles;
};
// Braces around one control-body statement do not add operations. Keep other
// blocks, directives and extra statements intact; their semantics need proof.
// Lexical declarations/references still pass through canonicalRoles' bijection.
const controlBodyOperation = (node: t.Node): t.Node => {
while (
t.isBlockStatement(node) &&
node.directives.length === 0 &&
node.body.length === 1
) {
const statement = node.body[0];
if (statement === undefined) break;
node = statement;
}
return node;
};
@@ -195,6 +195,32 @@ describe("tRPC binding identity and bundled syntax", () => {
]);
});
it("retains one client initializer across variable redeclarations", () => {
expect(
rpcEndpoints(`
var c;
var c = createTRPCClient({});
var c;
c.users.query();
var replaced;
var replaced = createTRPCClient({});
replaced = pool;
replaced.posts.query();
var initializedTwice = createTRPCClient({});
var initializedTwice = pool;
initializedTwice.comments.query();
var conditional;
if (flag) { var conditional = createTRPCClient({}); }
conditional.groups.query();
`),
).toEqual([
{ kind: "network", value: "users", mechanism: "trpc:procedure:query" },
]);
});
it("recognizes surviving factory names inside bundled call wrappers", () => {
expect(
rpcEndpoints(`
@@ -18,6 +18,7 @@ import {
import {
semanticObjectPatternKeys,
semanticStaticPropertyKey,
semanticWriteTargets,
} from "./javascriptAstValues.js";
import type {
JavaScriptSemanticAnalysisState,
@@ -31,16 +32,14 @@ import {
resolveSemanticBindingFromScope,
semanticBindingId,
semanticScopeId,
semanticStableInitializer,
semanticVariableScope,
} from "./javascriptSemanticState.js";
import {
completeSemanticSteps,
traverseJavaScriptAstSteps,
} from "./javascriptSemanticTraversal.js";
import {
semanticNamespaceInteropOperand,
semanticRequireOrigin,
} from "./javascriptSemanticRequireOrigin.js";
import { semanticRequireOrigin } from "./javascriptSemanticRequireOrigin.js";
import { collectSemanticMemberMutationsSteps } from "./javascriptSemanticMemberMutations.js";
import {
collectSemanticReturns,
@@ -49,7 +48,7 @@ import {
import { collectJavaScriptDerivedSemanticsSteps } from "./javascriptSemanticDerivedAnalysis.js";
import { evaluateSemanticProvenance } from "./javascriptSemanticValues.js";
import {
collectElectronMemberWritesSteps,
collectJavaScriptIdentityWritesSteps,
electronExportPath,
electronMemberPath,
ELECTRON_MODULE,
@@ -64,6 +63,8 @@ import {
} from "./javascriptSourceParser.js";
import { isJavaScriptRpcClientFactory } from "./javascriptRpcEndpoints.js";
import { createSemanticModuleInterop } from "./javascriptModuleInterop.js";
import { SemanticPropertyPathCoverage } from "./javascriptSemanticPropertyPaths.js";
interface BindPatternInput {
readonly pattern: t.Node;
@@ -205,13 +206,10 @@ export function* classifyParsedJavaScriptRpcClientRootsSteps(
if (binding === undefined) return;
let client = clients.get(binding.bindingId);
if (client === undefined) {
const [initializer] = binding.initializers;
const initializer = semanticStableInitializer(binding, state);
client =
initializer !== undefined &&
initializer.projection.length === 0 &&
binding.initializers.length === 1 &&
!binding.definitions.some(({ kind }) => kind === "assignment") &&
!state.conditionalInitializers.has(initializer.node) &&
isJavaScriptRpcClientFactory(initializer.node);
clients.set(binding.bindingId, client);
}
@@ -374,6 +372,9 @@ export function* classifyParsedJavaScriptElectronBindingsSteps(
const facts = new Map<number, readonly string[]>();
const state = createState(file.program);
yield* collectDefinitionsSteps(file.program, state);
const interop = createSemanticModuleInterop(state);
const writes = new SemanticPropertyPathCoverage();
let collectedWrites = false;
const exportsByBinding = new Map<string, readonly string[] | null>();
const rootExport = (root: t.Node): readonly string[] | undefined => {
if (t.isIdentifier(root)) {
@@ -382,23 +383,45 @@ export function* classifyParsedJavaScriptElectronBindingsSteps(
if (binding === undefined) return undefined;
let exported = exportsByBinding.get(binding.bindingId);
if (exported === undefined) {
exported = electronExport(binding, state);
exported = electronExport(binding, state, interop);
exportsByBinding.set(binding.bindingId, exported);
}
return exported ?? undefined;
return collectedWrites && interop.invalidated(binding)
? undefined
: (exported ?? undefined);
}
const origin = semanticRequireOrigin(
semanticNamespaceInteropOperand(root, state) ?? root,
state,
)?.origin;
const wrapped = interop.callOrigin(root);
const origin =
wrapped === undefined
? semanticRequireOrigin(root, state)?.origin
: collectedWrites && interop.invalidatedCall(root)
? undefined
: wrapped.origin;
return origin !== undefined && ELECTRON_MODULE.test(origin.specifier)
? electronExportPath(origin.importedPath)
: undefined;
};
const writes = yield* collectElectronMemberWritesSteps(
yield* collectJavaScriptIdentityWritesSteps(
file.program,
rootExport,
(root, kind) => {
if (kind === "opaque-call") return interop.opaqueMutationPath(root);
const exported = kind === "binding" ? undefined : rootExport(root);
return exported === undefined
? (interop.intrinsicPath(root) ??
(kind === "member"
? interop.boundIntrinsic(root)?.path
: undefined))
: ["electron", ...exported];
},
interop.intrinsicInvocation,
interop.staticString,
interop.isFreshObject,
(node, path) => {
if (path[0] === "electron") writes.retain(path);
else interop.retainWrite(node, path);
},
);
collectedWrites = true;
yield* traverseJavaScriptAstSteps(file.program, {
enter: (node) => {
if (
@@ -409,7 +432,10 @@ export function* classifyParsedJavaScriptElectronBindingsSteps(
return;
const { root, members } = electronMemberPath(node.callee);
const exported = rootExport(root);
if (exported !== undefined && !writes.covers([...exported, ...members]))
if (
exported !== undefined &&
!writes.covers(["electron", ...exported, ...members])
)
facts.set(root.start ?? -1, exported);
},
});
@@ -421,19 +447,16 @@ export function* classifyParsedJavaScriptElectronBindingsSteps(
const electronExport = (
binding: JavaScriptSemanticBindingState,
state: JavaScriptSemanticAnalysisState,
interop: ReturnType<typeof createSemanticModuleInterop>,
): readonly string[] | null => {
const initializers = namespacePreservingInitializers(binding, state);
if (initializers === undefined) return null;
const directOrigin = bindingOrigin(binding, initializers, state);
const [initializer] = initializers;
if (
directOrigin === undefined &&
(initializer === undefined ||
initializers.length !== 1 ||
initializers.length !== binding.initializers.length ||
state.conditionalInitializers.has(initializer.node))
)
return null;
const reassigned = binding.definitions.some(
({ kind }) => kind === "assignment",
);
const converted = interop.origin(binding);
if (reassigned && converted === undefined) return null;
const directOrigin = converted?.origin ?? bindingOrigin(binding, state);
const initializer = semanticStableInitializer(binding, state);
if (directOrigin === undefined && initializer === undefined) return null;
const provenance =
directOrigin === undefined
? evaluateSemanticProvenance(binding, state)
@@ -448,66 +471,17 @@ const electronExport = (
: null;
};
/**
* Return the initializers that can change which module a binding names.
* Bundlers emit `name = __toESM(name)` after a CommonJS require; rewrapping
* the binding's own value keeps every member, so it is not a reassignment.
*/
const namespacePreservingInitializers = (
binding: JavaScriptSemanticBindingState,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticBindingState["initializers"] | undefined => {
const initializers = binding.initializers.filter(
({ node }) => !rewrapsOwnNamespace(binding, node, state),
);
const rewraps = binding.initializers.length - initializers.length;
const assignments = binding.definitions.filter(
({ kind }) => kind === "assignment",
).length;
return assignments === rewraps ? initializers : undefined;
};
const rewrapsOwnNamespace = (
binding: JavaScriptSemanticBindingState,
node: t.Node,
state: JavaScriptSemanticAnalysisState,
): boolean => {
const assignment = state.parentsByNode.get(node);
const operand = semanticNamespaceInteropOperand(node, state);
return (
t.isAssignmentExpression(assignment) &&
assignment.operator === "=" &&
assignment.right === node &&
t.isIdentifier(assignment.left, { name: binding.name }) &&
t.isIdentifier(operand, { name: binding.name }) &&
!semanticResolutionBlocked(state, operand, operand.name) &&
resolveSemanticBindingState(state, operand, operand.name) === binding
);
};
const bindingOrigin = (
binding: JavaScriptSemanticBindingState,
initializers: JavaScriptSemanticBindingState["initializers"],
state: JavaScriptSemanticAnalysisState,
): JavaScriptModuleOrigin | undefined => {
if (binding.directOrigins.length > 0)
return binding.directOrigins.length === 1
? binding.directOrigins[0]
: undefined;
const [initializer] = initializers;
// A var/let declaration permits writes without proving one occurred.
// Require one unconditional initializer and no actual binding writes.
if (
initializer === undefined ||
initializers.length !== 1 ||
state.conditionalInitializers.has(initializer.node)
)
return undefined;
const origin = semanticRequireOrigin(
semanticNamespaceInteropOperand(initializer.node, state) ??
initializer.node,
state,
)?.origin;
const initializer = semanticStableInitializer(binding, state);
if (initializer === undefined) return undefined;
const origin = semanticRequireOrigin(initializer.node, state)?.origin;
const projection = initializer.projection;
return origin === undefined ||
!projection.every((key): key is string => typeof key === "string")
@@ -650,10 +624,11 @@ function* collectDefinitionsSteps(
for (const [index, { body, scope, parameters }] of functionBodies.entries()) {
if (index % 64 === 0) yield;
for (const parameter of parameters)
for (const identifier of assignedPatternIdentifiers(
for (const identifier of semanticWriteTargets(
t.isTSParameterProperty(parameter) ? parameter.parameter : parameter,
))
copyParameterToBody({ identifier, body, scope, state });
if (t.isIdentifier(identifier))
copyParameterToBody({ identifier, body, scope, state });
}
}
@@ -801,16 +776,18 @@ const bindAssignment = (
state,
);
else
for (const identifier of assignedPatternIdentifiers(node.left))
addAssignment(identifier, node, scope, state);
for (const identifier of semanticWriteTargets(node.left))
if (t.isIdentifier(identifier))
addAssignment(identifier, node, scope, state);
} else if (t.isUpdateExpression(node) && t.isIdentifier(node.argument))
addAssignment(node.argument, node, scope, state);
else if (t.isForOfStatement(node) || t.isForInStatement(node))
for (const pattern of t.isVariableDeclaration(node.left)
? node.left.declarations.map(({ id }) => id)
: [node.left]) {
for (const identifier of assignedPatternIdentifiers(pattern))
addAssignment(identifier, node, scope, state);
for (const identifier of semanticWriteTargets(pattern))
if (t.isIdentifier(identifier))
addAssignment(identifier, node, scope, state);
if (t.isForOfStatement(node))
// Keep the loop value unknown, but preserve references yielded into
// each bound slot so writes/escapes can reach their iterable origins.
@@ -825,30 +802,6 @@ const bindAssignment = (
}
};
const assignedPatternIdentifiers = (
pattern: t.Node,
): readonly t.Identifier[] => {
const identifiers: t.Identifier[] = [];
const pending = [pattern];
while (pending.length > 0) {
const node = pending.pop();
if (node === undefined) continue;
if (t.isIdentifier(node)) identifiers.push(node);
else if (t.isRestElement(node)) pending.push(node.argument);
else if (t.isAssignmentPattern(node)) pending.push(node.left);
else if (t.isArrayPattern(node)) {
for (const element of node.elements)
if (element !== null) pending.push(element);
} else if (t.isObjectPattern(node)) {
for (const property of node.properties)
pending.push(
t.isRestElement(property) ? property.argument : property.value,
);
}
}
return identifiers;
};
const nestedScope = (
node: t.Node,
parent: t.Node | null,
@@ -33,7 +33,7 @@ import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
import { traverseJavaScriptAstSteps } from "./javascriptSemanticTraversal.js";
import {
semanticStaticPropertyKey,
semanticMemberWriteTargets,
semanticWriteTargets,
unwrapJavaScriptExpression,
} from "./javascriptAstValues.js";
@@ -401,14 +401,15 @@ export function* collectSemanticMemberMutationsSteps(
markEscaped(expression.object, mutation);
};
const markTarget = (node: t.Node, mutation: t.Node): void => {
for (const target of semanticMemberWriteTargets(node))
markValue(
target.object,
[semanticStaticPropertyKey(target.property, target.computed)],
new Set(),
"write",
mutation,
);
for (const target of semanticWriteTargets(node))
if (!t.isIdentifier(target))
markValue(
target.object,
[semanticStaticPropertyKey(target.property, target.computed)],
new Set(),
"write",
mutation,
);
};
yield* traverseJavaScriptAstSteps(program, {
enter: (node, parent) => {
@@ -5,7 +5,6 @@ import {
resolveSemanticBindingState,
semanticResolutionBlocked,
type JavaScriptSemanticAnalysisState,
type JavaScriptSemanticBindingState,
} from "./javascriptSemanticState.js";
import {
semanticStaticPropertyKey,
@@ -59,73 +58,3 @@ export const semanticRequireOrigin = (
call: current,
};
};
// esbuild/Rolldown, TypeScript, and Babel emit these helpers for namespace
// imports of CommonJS modules; each returns an object exposing every own
// member of its operand, so member paths through the result are unchanged.
// Helper bodies are not evaluated: recognition trusts a single program-scope
// function definition under one of these emitted names.
const NAMESPACE_INTEROP_HELPERS = new Set([
"__importStar",
"__toESM",
"_interopRequireWildcard",
]);
/** Return the module operand of a locally declared namespace interop helper. */
export const semanticNamespaceInteropOperand = (
node: t.Node,
state: JavaScriptSemanticAnalysisState,
): t.Expression | undefined => {
const call = unwrapJavaScriptExpression(node).node;
if (
!t.isCallExpression(call) ||
!t.isIdentifier(call.callee) ||
!NAMESPACE_INTEROP_HELPERS.has(call.callee.name) ||
semanticResolutionBlocked(state, call.callee, call.callee.name)
)
return undefined;
const helper = resolveSemanticBindingState(
state,
call.callee,
call.callee.name,
);
const [operand] = call.arguments;
return helper !== undefined &&
emittedInteropHelper(helper, state) &&
t.isExpression(operand)
? operand
: undefined;
};
// Emitters declare each helper once at program scope as a function, an
// arrow/function expression, or `(this && this.name) || <function>`.
const emittedInteropHelper = (
helper: JavaScriptSemanticBindingState,
state: JavaScriptSemanticAnalysisState,
): boolean => {
const [initializer] = helper.initializers;
if (
initializer === undefined ||
helper.initializers.length !== 1 ||
helper.definitions.length !== 1 ||
(helper.kind !== "function" && helper.kind !== "variable") ||
state.scopesById.get(helper.scopeId)?.kind !== "program"
)
return false;
const value = unwrapJavaScriptExpression(initializer.node).node;
const emitted =
t.isLogicalExpression(value, { operator: "||" }) &&
t.isLogicalExpression(unwrapJavaScriptExpression(value.left).node, {
operator: "&&",
})
? unwrapJavaScriptExpression(value.right).node
: value;
return (
t.isFunctionDeclaration(emitted) ||
t.isFunctionExpression(emitted) ||
t.isArrowFunctionExpression(emitted) ||
(t.isCallExpression(emitted) &&
(t.isFunctionExpression(emitted.callee) ||
t.isArrowFunctionExpression(emitted.callee)))
);
};
@@ -75,6 +75,30 @@ export interface JavaScriptSemanticAnalysisState {
readonly conditionalInitializers: WeakSet<t.Node>;
}
/**
* Return one unconditional source initializer for a declared lexical binding.
* Repeated variable declarations without another initializer do not write it.
* This establishes a stable source fact only; it does not prove immutability or
* that the declaration has executed at a particular program point.
*/
export const semanticStableInitializer = (
binding: JavaScriptSemanticBindingState | undefined,
state: JavaScriptSemanticAnalysisState,
): JavaScriptSemanticBindingState["initializers"][number] | undefined => {
const [initializer] = binding?.initializers ?? [];
const [definition] = binding?.definitions ?? [];
return binding !== undefined &&
((definition?.kind === "variable" &&
binding.definitions.every(({ kind }) => kind === "variable")) ||
(binding.definitions.length === 1 &&
(definition?.kind === "function" || definition?.kind === "class"))) &&
binding.initializers.length === 1 &&
initializer !== undefined &&
!state.conditionalInitializers.has(initializer.node)
? initializer
: undefined;
};
/** Return the active scope from a non-empty construction stack. */
export const currentSemanticScope = (
stack: readonly JavaScriptSemanticScopeState[],
@@ -82,8 +82,7 @@ interface TraversalFrame {
* not be reintroduced (they diverge on loc/comment fields and ordering).
*/
export const childNodes = (node: t.Node): t.Node[] => {
const keys = t.VISITOR_KEYS[node.type];
if (keys === undefined) return [];
const keys = javaScriptAstChildKeys(node);
const children: t.Node[] = [];
for (const key of keys) {
const value: unknown = Reflect.get(node, key);
@@ -98,3 +97,7 @@ export const childNodes = (node: t.Node): t.Node[] => {
}
return children;
};
/** Child-bearing fields; shared by traversal and structural AST comparison. */
export const javaScriptAstChildKeys = (node: t.Node): readonly string[] =>
t.VISITOR_KEYS[node.type] ?? [];
+7 -3
View File
@@ -2,7 +2,9 @@ import { isAbsolute, relative, sep } from "node:path";
import { z } from "zod";
/**
* Preserve selected filesystem names while rejecting OS-invalid NUL bytes.
* Reject OS-invalid NUL bytes in a local filesystem name. This is not a path
* shape check: an empty or relative value is admitted here and narrowed by the
* callers that need a nonempty or absolute path.
*
* The pattern spells NUL as `\x00` rather than `\u0000`. Both accept exactly the
* same strings. The hex form also avoids the short `\0` spelling rejected by
@@ -10,11 +12,13 @@ import { z } from "zod";
* one advertised pattern cannot compile. See `offsetDateTimeSchema` for the
* same hex-escape convention.
*/
export const localPathStringSchema = z
export const nulFreeStringSchema = z
.string()
.min(1)
.regex(/^[^\x00]*$/u, "Local filesystem paths cannot contain NUL");
/** A selected local filesystem path: nonempty and free of NUL bytes. */
export const localPathStringSchema = nulFreeStringSchema.min(1);
/** Test lexical containment on the host platform; callers must resolve symlinks first. */
export const isPathWithinRoot = (root: string, path: string): boolean => {
const value = relative(root, path);
+18 -1
View File
@@ -84,7 +84,7 @@ export const nativeLoadImageCheckSchema = z.strictObject({
});
/** Read-only native image verification; verified applies only to declared coverage. */
export const nativeLoadImageSchema = z.discriminatedUnion("status", [
export const nativeLoadImageSchema = z.union([
z.strictObject({
status: z.literal("unsupported"),
reason: z.string().min(1),
@@ -108,6 +108,23 @@ export const nativeLoadImageSchema = z.discriminatedUnion("status", [
checks: z.array(nativeLoadImageCheckSchema),
limitations: z.array(z.string().min(1)),
}),
z.strictObject({
status: z.enum(["verified", "mismatch"]),
format: z.literal("raw-binary"),
target_sha256: digest,
architecture: z.enum(["x86", "x86_64", "arm", "arm64"]),
language_id: z.string().min(1),
compiler_spec_id: z.string().min(1),
base_address: address,
file_bytes: integer.min(1),
entry: z.strictObject({
address: address,
file_offset: z.literal(0),
}),
observations: nativeLoadImageObservationSchema,
checks: z.array(nativeLoadImageCheckSchema),
limitations: z.array(z.string().min(1)),
}),
]);
/** Provider-neutral native load-image result. */
+135
View File
@@ -0,0 +1,135 @@
import { describe, expect, it } from "vitest";
import { executableFormatHintSchema } from "./dosCom.js";
import {
admitRawBinary,
parseRawBinaryEntryPoint,
rawBinarySelectionError,
validateRawBinaryLength,
} from "./rawBinary.js";
describe("headerless format hints", () => {
it("admits dos-com and raw-binary names only", () => {
expect(executableFormatHintSchema.safeParse("dos-com").success).toBe(true);
expect(executableFormatHintSchema.safeParse("raw-binary").success).toBe(
true,
);
expect(executableFormatHintSchema.safeParse("raw").success).toBe(false);
});
});
describe("raw-binary entry addresses", () => {
it("canonicalizes equivalent hex spellings without dropping the source", () => {
const parsed = parseRawBinaryEntryPoint("0x08000000");
expect(parsed).toEqual({
ok: true,
value: {
source: "0x08000000",
canonical: "0x8000000",
value: 0x8000000n,
},
});
});
it.each(["8000000", "0x", "0xgg", "0X8000000", ""])(
"rejects malformed entry %s",
(value) => {
expect(parseRawBinaryEntryPoint(value).ok).toBe(false);
},
);
});
describe("raw-binary admission", () => {
it("admits a little-endian ARM image mapped at the caller entry", () => {
expect(
admitRawBinary({
architecture: "arm",
entryPoint: "0x8000000",
fileBytes: 4,
}),
).toEqual({
ok: true,
value: {
architecture: "arm",
entryPoint: "0x8000000",
entryPointSource: "0x8000000",
},
});
});
it("rejects an empty file", () => {
expect(validateRawBinaryLength(0).ok).toBe(false);
expect(
admitRawBinary({
architecture: "x86",
entryPoint: "0x1000",
fileBytes: 0,
}).ok,
).toBe(false);
});
it("rejects a 32-bit mapping that exceeds the architecture width", () => {
const result = admitRawBinary({
architecture: "arm",
entryPoint: "0xfffffffc",
fileBytes: 8,
});
expect(result.ok).toBe(false);
if (result.ok) throw new Error("expected overflow rejection");
expect(result.error).toContain("arm address width");
});
it("allows a 64-bit mapping that would overflow 32-bit ARM", () => {
expect(
admitRawBinary({
architecture: "arm64",
entryPoint: "0xfffffffc",
fileBytes: 8,
}).ok,
).toBe(true);
});
it.each(["arm", "arm64"])(
"rejects unaligned %s entries before provider selection",
(architecture) => {
for (const entryPoint of ["0x8000001", "0x8000002", "0x8000003"]) {
expect(
admitRawBinary({ architecture, entryPoint, fileBytes: 4 }),
).toEqual({
ok: false,
error: `raw-binary ${architecture} entry_point ${entryPoint} must be 4-byte aligned`,
});
}
},
);
it.each(["x86", "x86_64"])(
"admits byte-aligned %s entries",
(architecture) => {
const admitted = admitRawBinary({
architecture,
entryPoint: "0x1001",
fileBytes: 1,
});
if (!admitted.ok) throw new Error(admitted.error);
expect(admitted.value.entryPoint).toBe("0x1001");
},
);
});
describe("raw-binary selection pairing", () => {
it("requires architecture and entry with format=raw-binary", () => {
expect(rawBinarySelectionError({ format: "raw-binary" })).toBe(
"format=raw-binary requires architecture and entry_point",
);
expect(
rawBinarySelectionError({
format: "raw-binary",
architecture: "arm",
entryPoint: "0x8000000",
}),
).toBeUndefined();
});
it("rejects architecture or entry without format=raw-binary", () => {
expect(
rawBinarySelectionError({ architecture: "arm", entryPoint: "0x1" }),
).toBe("architecture and entry_point apply only with format=raw-binary");
expect(
rawBinarySelectionError({ format: "dos-com", architecture: "x86" }),
).toBe("architecture and entry_point apply only with format=raw-binary");
});
});
+123
View File
@@ -0,0 +1,123 @@
import { z } from "zod";
import type { BinaryArchitecture } from "./binaryTargetTypes.js";
import type { ExecutableFormatHint } from "./dosCom.js";
import { err, ok, type Result } from "./result.js";
/** Caller-visible CPU families admitted for headerless raw binaries. */
export const BINARY_ARCHITECTURES = [
"x86",
"x86_64",
"arm",
"arm64",
] as const satisfies readonly BinaryArchitecture[];
/** Provider-neutral CPU family for a caller-supplied raw-binary load. */
export const binaryArchitectureSchema = z.enum(BINARY_ARCHITECTURES);
const RAW_BINARY_ENTRY_POINT = /^0x[0-9A-Fa-f]{1,16}$/u;
/** Hexadecimal load and entry address; file offset 0 is mapped here. */
export const rawBinaryEntryPointSchema = z
.string()
.regex(RAW_BINARY_ENTRY_POINT, {
message: "entry_point must be a hexadecimal address of the form 0x…",
});
/** Canonicalized caller-supplied raw-binary entry with the original spelling. */
export interface CanonicalRawBinaryEntry {
readonly source: string;
readonly canonical: string;
readonly value: bigint;
}
/** Parse a caller-supplied hex entry while preserving the source spelling. */
export const parseRawBinaryEntryPoint = (
value: string,
): Result<CanonicalRawBinaryEntry, string> => {
if (!RAW_BINARY_ENTRY_POINT.test(value))
return err("entry_point must be a hexadecimal address of the form 0x…");
const parsed = BigInt(value);
return ok({
source: value,
canonical: `0x${parsed.toString(16)}`,
value: parsed,
});
};
/** Reject empty or non-integral file extents for a headerless image. */
export const validateRawBinaryLength = (
length: number,
): Result<null, string> =>
Number.isSafeInteger(length) && length >= 1
? ok(null)
: err("raw-binary requires at least one file byte");
/** Admitted headerless load identity used by target resolution and profiles. */
export interface RawBinaryAdmission {
readonly architecture: Exclude<BinaryArchitecture, "mips">;
readonly entryPoint: string;
readonly entryPointSource: string;
}
const addressWidth = (architecture: BinaryArchitecture): bigint =>
architecture === "x86" || architecture === "arm"
? 0xffffffffn
: 0xffffffffffffffffn;
/** Validate architecture, entry, and that the mapped image fits the CPU width. */
export const admitRawBinary = (input: {
readonly architecture: unknown;
readonly entryPoint: unknown;
readonly fileBytes: number;
}): Result<RawBinaryAdmission, string> => {
const architecture = binaryArchitectureSchema.safeParse(input.architecture);
if (!architecture.success)
return err(
"raw-binary format requires architecture (x86, x86_64, arm, or arm64)",
);
if (typeof input.entryPoint !== "string")
return err(
"raw-binary format requires entry_point as a hexadecimal address of the form 0x…",
);
const entry = parseRawBinaryEntryPoint(input.entryPoint);
if (!entry.ok) return entry;
if (
(architecture.data === "arm" || architecture.data === "arm64") &&
entry.value.value % 4n !== 0n
)
return err(
`raw-binary ${architecture.data} entry_point ${entry.value.canonical} must be 4-byte aligned`,
);
const length = validateRawBinaryLength(input.fileBytes);
if (!length.ok) return length;
const last = entry.value.value + BigInt(input.fileBytes) - 1n;
const max = addressWidth(architecture.data);
if (entry.value.value > max || last > max)
return err(
`raw-binary mapping from ${entry.value.canonical} must fit in the ${architecture.data} address width`,
);
return ok({
architecture: architecture.data,
entryPoint: entry.value.canonical,
entryPointSource: entry.value.source,
});
};
/** Describe the format/architecture/entry pairing without performing I/O. */
export const rawBinarySelectionError = (input: {
readonly format?: ExecutableFormatHint;
readonly architecture?: unknown;
readonly entryPoint?: unknown;
}): string | undefined => {
const hasArchitecture = input.architecture !== undefined;
const hasEntry = input.entryPoint !== undefined;
if (input.format === "raw-binary") {
if (!hasArchitecture || !hasEntry)
return "format=raw-binary requires architecture and entry_point";
return undefined;
}
if (hasArchitecture || hasEntry)
return "architecture and entry_point apply only with format=raw-binary";
return undefined;
};
+1 -1
View File
@@ -5,5 +5,5 @@ export const PACKAGE_METADATA = {
serverSdkVersion: "2.3.1",
clientSdkVersion: "2.3.1",
coreSdkVersion: "2.3.1",
skillVersion: "38",
skillVersion: "39",
} as const;
+52
View File
@@ -14,6 +14,7 @@ import type { AnalysisError } from "../domain/analysisErrorBase.js";
import { err, ok, type Result } from "../domain/result.js";
import type { GhidraInstallationInspection } from "./GhidraInstallation.js";
import { ghidraMipsProfileParameters } from "./GhidraMipsProfile.js";
import { ghidraRawBinaryLanguage } from "./GhidraRawBinaryLanguage.js";
import {
ghidraProcessorUnsupportedReason,
@@ -69,6 +70,57 @@ export const resolveGhidraAnalysisProfile = async (
: null;
if (pspExtension !== null && !pspExtension.ok) return pspExtension;
const provider = { ...identity, version: installation.providerVersion };
if (target.format === "raw-binary") {
if (languageOverride !== undefined)
return Promise.resolve(
err(
new AnalysisUnsupportedTargetError(
"resolve_analysis_profile",
target.path,
"REA_GHIDRA_LANGUAGE_ID cannot override the admitted raw-binary import.",
),
),
);
const language = ghidraRawBinaryLanguage(target.architecture);
return Promise.resolve(
ok({
profile: createAnalysisProfile(provider, {
target_kind: target.kind,
target_format: target.format,
architecture: target.architecture,
available_architectures: [...target.availableArchitectures].sort(),
import_mode: "ephemeral-source-immutable",
annotation_policy: "atomic-function-entry-metadata-v1",
load_image_observations: "source-mappings-entry-context-v2",
function_body_evidence: "complete-inclusive-ranges-v1",
function_references: "complete-body-and-entry-reference-manager-v2",
string_inventory_evidence: "defined-data-coverage-v1",
location_resolution: "explicit-address-exact-entry-symbol-first-v3",
instruction_flow_evidence: "decoded-return-pcode-v1",
instruction_references: "exact-address-incoming-v1",
function_boundary_observations: "ghidra-terminal-call-limitations-v1",
no_return_repair:
installation.platform === "win32"
? "disabled-windows-p0"
: "returning-imports-decoded-return-v2",
process_launch:
installation.platform === "win32"
? "official-headless-script-v1"
: "inspected-jvm-launch-support-v1",
load_image_evidence: "independent-raw-mapping-context-v2",
jump_table_evidence: "typed-case-default-blocks-v1",
decompiler_jump_loads: true,
loader: "BinaryLoader",
language_id: language.languageId,
compiler_spec_id: language.compilerSpecId,
language_selection: "caller-supplied-v1",
entry_point: target.entryPoint,
entry_seed: "external-entry-and-function-before-analysis-v1",
analyzer_preset: "ghidra-default",
}),
}),
);
}
const dosMz = target.format === "dos-mz";
const dosCom = target.format === "dos-com";
const dos = dosMz || dosCom;
+143 -77
View File
@@ -1,5 +1,8 @@
import { randomBytes, randomUUID } from "node:crypto";
import { createHash, randomBytes, randomUUID } from "node:crypto";
import type { Stats } from "node:fs";
import type { FileHandle } from "node:fs/promises";
import type { Socket } from "node:net";
import type { ProgressReporter } from "../application/ProgressReporter.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import type { JsonValue } from "../domain/jsonValue.js";
@@ -42,11 +45,12 @@ import {
type GhidraSessionInfo,
} from "./GhidraSessionValues.js";
import { createGhidraTargetSnapshot } from "./GhidraTargetSnapshot.js";
import { readFile } from "node:fs/promises";
import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
import {
openRegularFile,
RegularFileChangedError,
RegularFileAdmissionFailure,
sameRegularFileState,
} from "../filesystem/RegularFile.js";
import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
@@ -162,7 +166,12 @@ export class GhidraClient {
}
/** Launch Ghidra once and require its exact post-analysis handshake. */
start(signal?: AbortSignal): Promise<GhidraStartResult> {
start(
signal?: AbortSignal,
progress?: ProgressReporter,
): Promise<GhidraStartResult> {
if (progress !== undefined)
return this.#reportStartupWait(this.start(signal), signal, progress);
if (this.#closePromise !== undefined)
return this.#closePromise.then(
() => this.start(signal),
@@ -216,6 +225,41 @@ export class GhidraClient {
return started;
}
async #reportStartupWait(
started: Promise<GhidraStartResult>,
signal: AbortSignal | undefined,
progress: ProgressReporter,
): Promise<GhidraStartResult> {
const startedAt = performance.now();
let active = true;
let reporting = false;
const timer = setInterval(() => {
if (!active || reporting || signal?.aborted) return;
reporting = true;
void Promise.resolve()
.then(() => {
if (!active || signal?.aborted) return;
return progress.report({
phase: "ghidra_startup",
completed: 0,
total: null,
message: `Waiting for Ghidra startup (${String(Math.floor((performance.now() - startedAt) / 1000))}s elapsed); import, auto-analysis and bridge readiness may still be pending`,
});
})
// Notification failure does not release the owned startup process.
.catch(() => {})
.finally(() => {
reporting = false;
});
}, 10_000);
try {
return await started;
} finally {
active = false;
clearInterval(timer);
}
}
/** Revalidate live bridge, provider, run, and profile metadata. */
async ping(
options: GhidraRequestOptions = {},
@@ -231,9 +275,12 @@ export class GhidraClient {
async callTool(
operation: GhidraOperation,
parameters: Readonly<Record<string, JsonValue>>,
options: { readonly signal?: AbortSignal } = {},
options: {
readonly signal?: AbortSignal;
readonly progress?: ProgressReporter;
} = {},
): Promise<Result<JsonValue, GhidraSessionError>> {
const started = await this.start(options.signal);
const started = await this.start(options.signal, options.progress);
if (!started.ok) return started;
return this.#requestQueue.run(
operation,
@@ -242,12 +289,66 @@ export class GhidraClient {
);
}
/** Read the private immutable source for independent import verification. */
async readTargetSnapshot(
/** Read the private immutable source for format parsers that require captured bytes. */
readTargetSnapshot(
maximumBytes?: number,
signal?: AbortSignal,
): Promise<Result<GhidraTargetSnapshot, GhidraSessionError>> {
if (this.#snapshotPath === undefined)
return this.#withTargetSnapshot(async (handle, initial, path) => {
if (
maximumBytes !== undefined &&
(!Number.isSafeInteger(maximumBytes) || maximumBytes < 0)
)
throw new RangeError("Snapshot byte limit must be a safe integer");
if (maximumBytes !== undefined && initial.size > maximumBytes)
return {
kind: "over-capacity",
sourceBytesAtLeast: initial.size,
maximumBytes,
};
const bytes = await readBoundedFileBytes(
handle,
maximumBytes ?? initial.size,
signal,
initial.size,
);
if (bytes === undefined || bytes.length !== initial.size)
throw new RegularFileChangedError(path);
return { kind: "captured", bytes };
}, signal);
}
/** Measure the complete snapshot identity without retaining its bytes in memory. */
hashTargetSnapshot(
signal?: AbortSignal,
): Promise<
Result<
{ readonly sha256: string; readonly bytes: number },
GhidraSessionError
>
> {
return this.#withTargetSnapshot(async (handle, initial, path) => {
const hash = createHash("sha256");
let bytes = 0;
for await (const chunk of readFileHandleChunks(handle, {
end: initial.size,
signal,
})) {
bytes += chunk.length;
if (bytes > initial.size) throw new RegularFileChangedError(path);
hash.update(chunk);
}
if (bytes !== initial.size) throw new RegularFileChangedError(path);
return { sha256: hash.digest("hex"), bytes };
}, signal);
}
async #withTargetSnapshot<T>(
read: (handle: FileHandle, initial: Stats, path: string) => Promise<T>,
signal?: AbortSignal,
): Promise<Result<T, GhidraSessionError>> {
const path = this.#snapshotPath;
if (path === undefined)
return err(
this.#failure(
"protocol",
@@ -255,77 +356,42 @@ export class GhidraClient {
),
);
try {
if (maximumBytes !== undefined) {
signal?.throwIfAborted();
if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 0)
throw new RangeError("Snapshot byte limit must be a safe integer");
const handle = await openRegularFile(this.#snapshotPath, {
symlinks: "reject",
});
const owner = new OwnedFileHandle(handle);
this.#snapshotOwners.add(owner);
let result: GhidraTargetSnapshot;
let readFailure: unknown;
try {
const metadata = await handle.stat();
signal?.throwIfAborted();
if (metadata.size > maximumBytes)
result = {
kind: "over-capacity",
sourceBytesAtLeast: metadata.size,
maximumBytes,
};
else {
const bytes = await readBoundedFileBytes(
handle,
maximumBytes,
signal,
metadata.size,
);
signal?.throwIfAborted();
const after = await handle.stat();
if (
bytes !== undefined &&
bytes.length === metadata.size &&
sameRegularFileState(metadata, after)
) {
result = { kind: "captured", bytes };
} else if (
bytes === undefined &&
after.isFile() &&
after.size > maximumBytes
) {
result = {
kind: "over-capacity",
sourceBytesAtLeast: after.size,
maximumBytes,
};
} else {
throw new RegularFileChangedError(this.#snapshotPath);
}
}
} catch (cause: unknown) {
readFailure = cause;
}
try {
await owner.close();
this.#snapshotOwners.delete(owner);
} catch (closeFailure: unknown) {
throw new AggregateError(
readFailure === undefined
? [closeFailure]
: [readFailure, closeFailure],
"Ghidra target snapshot read or descriptor cleanup failed",
);
}
if (readFailure !== undefined) throw readFailure;
return ok(result!);
}
return ok({
kind: "captured",
bytes: await readFile(this.#snapshotPath),
const handle = await openRegularFile(path, {
symlinks: "reject",
signal,
});
const owner = new OwnedFileHandle(handle);
this.#snapshotOwners.add(owner);
let result: Result<T, unknown>;
try {
const initial = await handle.stat();
signal?.throwIfAborted();
if (!Number.isSafeInteger(initial.size) || initial.size < 0)
throw new RangeError("Snapshot size must be a safe integer");
const value = await read(handle, initial, path);
signal?.throwIfAborted();
const after = await handle.stat();
signal?.throwIfAborted();
if (!sameRegularFileState(initial, after))
throw new RegularFileChangedError(path);
result = ok(value);
} catch (cause: unknown) {
result = err(cause);
}
try {
await owner.close();
this.#snapshotOwners.delete(owner);
} catch (closeFailure: unknown) {
throw new AggregateError(
result.ok ? [closeFailure] : [result.error, closeFailure],
"Ghidra target snapshot read or descriptor cleanup failed",
);
}
if (!result.ok) throw result.error;
return result;
} catch (cause: unknown) {
if (cause instanceof RegularFileAdmissionFailure)
this.#snapshotOwners.add(cause.owner);
return err(
this.#failure(
signal?.aborted === true ? "cancelled" : "protocol",
+63 -15
View File
@@ -101,6 +101,11 @@ export interface GhidraHeadlessLauncherOptions {
/** Select the admitted 16-bit real-mode MZ import instead of auto-detection. */
readonly dosMz?: true;
readonly dosCom?: true;
readonly rawBinary?: {
readonly languageId: string;
readonly compilerSpecId: string;
readonly baseAddr: string;
};
/** Explicit import language committed by the analysis profile. */
readonly languageOverride?: GhidraLanguageOverride;
/** Caller seeds committed by the analysis profile, applied before analysis. */
@@ -201,6 +206,9 @@ export class GhidraHeadlessLauncher implements GhidraLauncher {
...(this.options.dosMz === undefined
? {}
: { dosMz: this.options.dosMz }),
...(this.options.rawBinary === undefined
? {}
: { rawBinary: this.options.rawBinary }),
...(this.options.languageOverride === undefined
? {}
: { languageOverride: this.options.languageOverride }),
@@ -411,6 +419,11 @@ export interface GhidraHeadlessArgumentOptions {
readonly psp?: true;
readonly dosMz?: true;
readonly dosCom?: true;
readonly rawBinary?: {
readonly languageId: string;
readonly compilerSpecId: string;
readonly baseAddr: string;
};
readonly languageOverride?: GhidraLanguageOverride;
/** Canonical seed snapshot passed to the pre-analysis seed script. */
readonly seedPath?: string;
@@ -426,6 +439,7 @@ export const ghidraHeadlessArguments = (
(options.platform ?? process.platform) === "win32" ? win32 : posix;
const bridgeDirectory = scriptPath.dirname(options.bridgeScriptPath);
const override = options.languageOverride;
const rawBinary = options.rawBinary;
if (
options.psp === true &&
(options.dosMz === true ||
@@ -435,6 +449,10 @@ export const ghidraHeadlessArguments = (
throw new Error(
"A PSP ELF import cannot be combined with DOS or a generic Ghidra language override.",
);
if (options.psp === true && rawBinary !== undefined)
throw new Error(
"A PSP ELF import cannot be combined with a raw-binary import.",
);
if (
override !== undefined &&
(options.dosMz === true || options.dosCom === true)
@@ -442,6 +460,17 @@ export const ghidraHeadlessArguments = (
throw new Error(
"A Ghidra language override cannot be combined with a DOS import.",
);
if (override !== undefined && rawBinary !== undefined)
throw new Error(
"A Ghidra language override cannot be combined with a raw-binary import.",
);
if (
rawBinary !== undefined &&
(options.dosMz === true || options.dosCom === true)
)
throw new Error(
"A raw-binary import cannot be combined with a DOS import.",
);
return [
options.projectRoot,
"rea-project",
@@ -467,24 +496,35 @@ export const ghidraHeadlessArguments = (
"-cspec",
"default",
]
: options.psp === true
? [
"-loader",
"PspElfLoader",
"-processor",
"Allegrex:LE:32:default",
"-cspec",
"default",
]
: override !== undefined
: rawBinary === undefined
? options.psp === true
? [
"-loader",
"PspElfLoader",
"-processor",
override.languageId,
...(override.compilerSpecId === undefined
? []
: ["-cspec", override.compilerSpecId]),
"Allegrex:LE:32:default",
"-cspec",
"default",
]
: []),
: override !== undefined
? [
"-processor",
override.languageId,
...(override.compilerSpecId === undefined
? []
: ["-cspec", override.compilerSpecId]),
]
: []
: [
"-loader",
"BinaryLoader",
"-loader-baseAddr",
rawBinary.baseAddr,
"-processor",
rawBinary.languageId,
"-cspec",
rawBinary.compilerSpecId,
]),
"-readOnly",
"-deleteProject",
"-log",
@@ -499,6 +539,14 @@ export const ghidraHeadlessArguments = (
scriptPath.join(bridgeDirectory, "ReaGhidraPrepareCom.java"),
]
: []),
...(rawBinary === undefined
? []
: [
"-preScript",
scriptPath.join(bridgeDirectory, "ReaGhidraPrepareRaw.java"),
rawBinary.languageId,
rawBinary.baseAddr,
]),
// Seeds follow any loader preparation and precede default auto-analysis.
...(options.seedPath === undefined
? []
+42 -13
View File
@@ -12,17 +12,15 @@ import { err, ok, type Result } from "../domain/result.js";
import {
attestGhidraDosComLoadImage,
attestGhidraDosLoadImage,
attestGhidraRawBinaryLoadImage,
} from "./GhidraLoadImageValues.js";
import type { NativeAotPeResult } from "../domain/native/nativeAotPe.js";
import type { GhidraTargetSnapshot } from "./GhidraClient.js";
import type { GhidraClient } from "./GhidraClient.js";
import type { GhidraSessionError } from "./GhidraSessionError.js";
type LoadImageSnapshotClient = {
readonly readTargetSnapshot?: (
maximumBytes?: number,
signal?: AbortSignal,
) => Promise<Result<GhidraTargetSnapshot, GhidraSessionError>>;
};
type LoadImageSnapshotClient = Partial<
Pick<GhidraClient, "hashTargetSnapshot" | "readTargetSnapshot">
>;
type NativeLoadImageAttestationInput = {
readonly target: BinaryTarget;
@@ -37,7 +35,7 @@ type NativeLoadImageAttestationInput = {
const isSignalAborted = (signal: AbortSignal | undefined): boolean =>
signal?.aborted === true;
/** Independently verify measured load-image observations for admitted DOS targets. */
/** Independently verify measured load-image observations for admitted DOS and raw-binary targets. */
export const attestGhidraNativeLoadImage = async (
input: NativeLoadImageAttestationInput,
): Promise<Result<JsonValue, AnalysisError>> => {
@@ -71,7 +69,7 @@ export const attestGhidraNativeLoadImage = async (
nativeLoadImageSchema.parse({
status: "unsupported",
reason:
"Independent load-image verification currently supports DOS MZ and explicit DOS COM targets only.",
"Independent load-image verification currently supports DOS MZ, explicit DOS COM, and caller-supplied raw-binary targets only.",
observations: {
...observations,
metadata_recovery: [
@@ -98,13 +96,17 @@ export const attestGhidraNativeLoadImage = async (
);
}
}
if (target.format !== "dos-mz" && target.format !== "dos-com") {
if (
target.format !== "dos-mz" &&
target.format !== "dos-com" &&
target.format !== "raw-binary"
) {
return ok(
jsonValueSchema.parse(
nativeLoadImageSchema.parse({
status: "unsupported",
reason:
"Independent load-image verification currently supports DOS MZ and explicit DOS COM targets only.",
"Independent load-image verification currently supports DOS MZ, explicit DOS COM, and caller-supplied raw-binary targets only.",
observations,
limitations: [
"Other formats expose measured mappings and source identities; no format-specific verification was performed.",
@@ -113,6 +115,33 @@ export const attestGhidraNativeLoadImage = async (
),
);
}
if (target.format === "raw-binary") {
if (client.hashTargetSnapshot === undefined)
return err(
new ProviderAdapterError("ghidra", operation, {
diagnostics: {
reason:
"The Ghidra client does not expose its immutable target snapshot identity for independent raw-binary load-image verification.",
},
}),
);
const snapshot = await client.hashTargetSnapshot(signal);
if (!snapshot.ok) return err(mapSessionError(snapshot.error));
if (isSignalAborted(signal))
return err(new AnalysisCancelledError(operation));
const attested = attestGhidraRawBinaryLoadImage(
snapshot.value,
target,
observations,
);
return attested.ok
? ok(jsonValueSchema.parse(attested.value))
: err(
new ProviderAdapterError("ghidra", operation, {
diagnostics: { reason: attested.error },
}),
);
}
if (client.readTargetSnapshot === undefined)
return err(
new ProviderAdapterError("ghidra", operation, {
@@ -122,14 +151,14 @@ export const attestGhidraNativeLoadImage = async (
},
}),
);
const snapshot = await client.readTargetSnapshot();
const snapshot = await client.readTargetSnapshot(undefined, signal);
if (!snapshot.ok) return err(mapSessionError(snapshot.error));
if (snapshot.value.kind !== "captured")
return err(
new ProviderAdapterError("ghidra", operation, {
diagnostics: {
reason:
"The uncapped DOS load-image snapshot was unexpectedly not captured.",
"The uncapped load-image snapshot was unexpectedly not captured.",
},
}),
);
+110
View File
@@ -7,8 +7,10 @@ import {
} from "../domain/native/nativeLoadImage.js";
import { parseDosMzHeader, type DosMzHeader } from "../domain/dosMz.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import { validateDosComLength } from "../domain/dosCom.js";
import { err, ok, type Result } from "../domain/result.js";
import { ghidraRawBinaryLanguage } from "./GhidraRawBinaryLanguage.js";
const sha256 = (bytes: Buffer): string =>
createHash("sha256").update(bytes).digest("hex");
@@ -325,3 +327,111 @@ export const attestGhidraDosComLoadImage = (
}),
);
};
const hexAddress = (value: bigint): string => `0x${value.toString(16)}`;
/** Verify a caller-supplied raw-binary mapping against measured Ghidra import facts. */
export const attestGhidraRawBinaryLoadImage = (
snapshot: { readonly sha256: string; readonly bytes: number },
target: Extract<BinaryTarget, { format: "raw-binary" }>,
observations: NativeLoadImageObservation,
): Result<NativeLoadImage, string> => {
if (snapshot.sha256 !== target.sha256)
return err(
"Ghidra raw-binary snapshot digest does not match the admitted target",
);
const language = ghidraRawBinaryLanguage(target.architecture);
const base = BigInt(target.entryPoint);
const last = hexAddress(base + BigInt(snapshot.bytes) - 1n);
const checks: NativeLoadImageCheck[] = [];
const check = (
name: string,
expected: JsonValue,
observed: JsonValue,
fileOffset: number | null = null,
location: string | null = null,
): void => {
checks.push({
name,
matched: JSON.stringify(expected) === JSON.stringify(observed),
expected,
observed,
file_offset: fileOffset,
address: location,
});
};
const source = observations.source_files[0];
const mapping = observations.mappings[0];
check("executable_format", "Raw Binary", observations.executable_format);
check("language_id", language.languageId, observations.language_id);
check(
"compiler_spec_id",
language.compilerSpecId,
observations.compiler_spec_id,
);
// BinaryLoader's block base is independent of the Program image base.
check("image_base", "0x0", observations.image_base);
check("source_file_count", 1, observations.source_files.length);
check("source_file_size", snapshot.bytes, source?.size ?? null);
check("original_file_sha256", target.sha256, source?.original_sha256 ?? null);
check("modified_file_sha256", target.sha256, source?.modified_sha256 ?? null);
check("mapping_count", 1, observations.mappings.length);
check(
"mapping.file_offset",
0,
mapping?.file_offset ?? null,
0,
mapping?.start ?? null,
);
check(
"mapping.start",
target.entryPoint,
mapping?.start ?? null,
0,
mapping?.start ?? null,
);
check("mapping.end", last, mapping?.end ?? null, 0, mapping?.end ?? null);
check(
"mapping.length",
snapshot.bytes,
mapping?.length ?? null,
0,
mapping?.start ?? null,
);
check(
"mapping.sha256",
snapshot.sha256,
mapping?.sha256 ?? null,
0,
mapping?.start ?? null,
);
check(
"entry_point",
target.entryPoint,
observations.entry_points.find((entry) => entry === target.entryPoint) ??
null,
);
check("relocation_records", [], observations.relocations);
return ok(
nativeLoadImageSchema.parse({
status: checks.every((item) => item.matched) ? "verified" : "mismatch",
format: "raw-binary",
target_sha256: target.sha256,
architecture: target.architecture,
language_id: language.languageId,
compiler_spec_id: language.compilerSpecId,
base_address: target.entryPoint,
file_bytes: snapshot.bytes,
entry: { address: target.entryPoint, file_offset: 0 },
observations,
checks,
limitations: [
"Raw binary is a headerless interpretation explicitly selected by the caller, not format identification from file bytes.",
"Verification covers complete original/modified source identity, mapped file bytes, the caller-supplied entry, and the bound little-endian Ghidra language. File offset 0 is mapped at the entry address.",
"Ghidra may report additional language-defined external entries outside the mapped image. They are preserved as observations; verification requires the caller-supplied entry and does not attest other entries.",
"Reset vectors, memory-mapped I/O, big-endian and Thumb-only variants, and runtime boot behavior are not modeled or verified. No original executable bytes are changed.",
"Mapping ends are inclusive; a mismatching digest identifies its source range, not the first differing byte.",
],
}),
);
};
+127
View File
@@ -10,6 +10,7 @@ import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
import { describe, expect, it } from "vitest";
import { fixtureDosLoadImage } from "./GhidraLoadImage.fixture.js";
import { fixtureRawBinaryLoadImage } from "./GhidraRawBinaryLoadImage.fixture.js";
import {
nativeAotPeDigest,
nativeAotPeFixture,
@@ -177,6 +178,50 @@ describe("Ghidra provider", () => {
});
});
describe("Ghidra raw-binary profile", () => {
it("commits BinaryLoader language and caller-supplied entry", async () => {
const ghidra = provider();
const target: BinaryTarget = {
path: "/tmp/ecu.bin",
sha256: "a".repeat(64),
kind: "executable",
format: "raw-binary",
architecture: "arm",
availableArchitectures: ["arm"],
entryPoint: "0x8000000",
entryPointSource: "0x08000000",
};
expect(ghidra.inspectTargetSupport(target).status).toBe("supported");
const resolved = await ghidra.resolveAnalysisProfile(target);
expect(resolved.ok && resolved.value).toMatchObject({
profile: {
parameters: {
target_format: "raw-binary",
architecture: "arm",
loader: "BinaryLoader",
language_id: "ARM:LE:32:v7",
compiler_spec_id: "default",
language_selection: "caller-supplied-v1",
entry_point: "0x8000000",
},
},
});
const shifted = await ghidra.resolveAnalysisProfile({
...target,
entryPoint: "0x8001000",
entryPointSource: "0x8001000",
});
expect(resolved.ok && shifted.ok).toBe(true);
if (!resolved.ok || !shifted.ok || resolved.value.profile === null)
throw new Error("expected raw-binary profiles");
expect(shifted.value.profile?.digest).not.toBe(
resolved.value.profile.digest,
);
const windows = provider({ ...installationHost(), platform: "win32" });
expect(windows.inspectTargetSupport(target).status).toBe("unsupported");
});
});
describe("Ghidra Mach-O slice support", () => {
it("refuses universal targets whose selected slice cannot be enforced", () => {
const ghidra = provider();
@@ -718,6 +763,88 @@ describe("Ghidra result projection", () => {
});
describe("Ghidra measured load-image projection", () => {
it.each(["verified", "changed-snapshot", "cancelled"] as const)(
"streams raw snapshot identity and preserves %s outcomes",
async (state) => {
const fixture = fixtureRawBinaryLoadImage();
const controller = new AbortController();
const signals: (AbortSignal | undefined)[] = [];
const ghidra = provider(installationHost(), () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: (operation) => {
if (operation !== "inspect_native_load_image")
throw new Error(`unexpected operation ${operation}`);
return Promise.resolve(
ok(jsonValueSchema.parse(fixture.observation)),
);
},
readTargetSnapshot: () => {
throw new Error(
"raw verification must not capture the complete file",
);
},
hashTargetSnapshot: (signal) => {
signals.push(signal);
if (state === "cancelled") {
controller.abort();
return Promise.resolve(
err(
new GhidraSessionError(
"cancelled",
"Snapshot hashing cancelled",
),
),
);
}
return Promise.resolve(
ok({
...fixture.snapshot,
...(state === "changed-snapshot"
? { sha256: "f".repeat(64) }
: {}),
}),
);
},
close: () => Promise.resolve(ok(null)),
}));
const resolved = await ghidra.resolveAnalysisProfile(fixture.target);
if (!resolved.ok) throw resolved.error;
if (resolved.value.profile === null)
throw new Error("expected raw profile");
const client = ghidra.createClient(
fixture.target,
resolved.value.profile,
);
try {
const result = await client.execute(
"inspect_native_load_image",
{},
{ signal: controller.signal },
);
expect(signals).toEqual([controller.signal]);
if (state === "verified") {
if (!result.ok) throw result.error;
expect(result.value.result).toMatchObject({
status: "verified",
observations: fixture.observation,
});
} else {
expect(result).toMatchObject({
ok: false,
error: {
_tag:
state === "cancelled"
? "AnalysisCancelledError"
: "ProviderAdapterError",
},
});
}
} finally {
await client.close();
}
},
);
it.each([
"verified",
"mismatch",
+50 -15
View File
@@ -87,12 +87,18 @@ import {
windowsNativeAuthorityUnavailableReason,
hasWindowsNativeAuthority,
} from "../process/WindowsAuthority.js";
import { ghidraRawBinaryLanguage } from "./GhidraRawBinaryLanguage.js";
/** Production seam for exercising provider projection without a real process. */
export type GhidraProviderClientFactory = (
options: GhidraClientOptions,
) => Pick<GhidraClient, "start" | "callTool" | "close"> &
Partial<Pick<GhidraClient, "runtimeLineage" | "readTargetSnapshot">>;
Partial<
Pick<
GhidraClient,
"runtimeLineage" | "readTargetSnapshot" | "hashTargetSnapshot"
>
>;
type GhidraProviderClientInstance = ReturnType<GhidraProviderClientFactory>;
@@ -440,6 +446,10 @@ export const createGhidraProviderClient = (input: {
let extensionFailure: AnalysisError | undefined;
// Replaced by the reported outcome once the session handshake is checked.
const seedLimitations: string[] = [...ghidraSeedLimitations(seeds)];
const rawLanguage =
target.format === "raw-binary"
? ghidraRawBinaryLanguage(target.architecture)
: undefined;
const targetLimitations = [
...(target.format === "dos-mz"
? [
@@ -447,6 +457,13 @@ export const createGhidraProviderClient = (input: {
"Static DOS analysis does not emulate BIOS, DOS interrupts, device ports, or self-modifying unpacking code. Packed targets require a separately identified unpacked artifact for original-program analysis; appended overlays are not the initialized load module.",
]
: []),
...(target.format === "raw-binary"
? [
"Headerless raw-binary analysis uses the caller-supplied architecture and entry address; file offset 0 is mapped at that address. Headers are not discovered from file bytes.",
"Little-endian generic Ghidra languages are used for x86, x86_64, arm, and arm64. Big-endian, Thumb-only, Cortex-M, and other processor variants are unsupported in this increment.",
"Static analysis does not emulate reset vectors, memory-mapped I/O, or firmware boot sequences.",
]
: []),
...(target.kind === "executable" && target.architecture === "mips"
? (target.mips.limitations ?? [])
: []),
@@ -474,6 +491,15 @@ export const createGhidraProviderClient = (input: {
: {}),
...(target.format === "dos-mz" ? { dosMz: true } : {}),
...(target.format === "dos-com" ? { dosCom: true } : {}),
...(rawLanguage === undefined || target.format !== "raw-binary"
? {}
: {
rawBinary: {
languageId: rawLanguage.languageId,
compilerSpecId: rawLanguage.compilerSpecId,
baseAddr: target.entryPoint,
},
}),
...(languageOverride === undefined ? {} : { languageOverride }),
...(seeds === undefined ? {} : { analysisSeeds: seeds }),
platform: installation.platform,
@@ -495,13 +521,18 @@ export const createGhidraProviderClient = (input: {
expectedLanguageId: "x86:LE:16:Real Mode",
expectedCompilerSpecId: "default",
}
: languageOverride === undefined
? {}
: rawLanguage === undefined
? languageOverride === undefined
? {}
: {
expectedLanguageId: languageOverride.languageId,
...(languageOverride.compilerSpecId === undefined
? {}
: { expectedCompilerSpecId: languageOverride.compilerSpecId }),
}
: {
expectedLanguageId: languageOverride.languageId,
...(languageOverride.compilerSpecId === undefined
? {}
: { expectedCompilerSpecId: languageOverride.compilerSpecId }),
expectedLanguageId: rawLanguage.languageId,
expectedCompilerSpecId: rawLanguage.compilerSpecId,
}),
...(psp
? {
@@ -573,7 +604,7 @@ export const createGhidraProviderClient = (input: {
),
);
if (operation === "health") {
const started = await client.start(options?.signal);
const started = await client.start(options?.signal, options?.progress);
if (!started.ok)
return err(
projectSessionError(
@@ -596,7 +627,7 @@ export const createGhidraProviderClient = (input: {
: parseGhidraInventoryInput(operation, parameters);
if (!input.ok) return input;
if (extensions.length > 0 || seeds !== undefined) {
const started = await client.start(options?.signal);
const started = await client.start(options?.signal, options?.progress);
if (!started.ok)
return err(
projectSessionError(
@@ -608,11 +639,12 @@ export const createGhidraProviderClient = (input: {
const failed = await checkExtensions(operation, started.value);
if (failed !== undefined) return err(failed);
}
const called = await client.callTool(
operation,
input.value,
options?.signal === undefined ? {} : { signal: options.signal },
);
const called = await client.callTool(operation, input.value, {
...(options?.signal === undefined ? {} : { signal: options.signal }),
...(options?.progress === undefined
? {}
: { progress: options.progress }),
});
if (!called.ok)
return err(
projectSessionError(
@@ -637,7 +669,10 @@ export const createGhidraProviderClient = (input: {
const address = input.value.address;
if (typeof address === "string") {
if (target.format === "pe" && nativeAotOwner !== undefined) {
const started = await client.start(options?.signal);
const started = await client.start(
options?.signal,
options?.progress,
);
if (!started.ok)
return err(
projectSessionError(
+26
View File
@@ -0,0 +1,26 @@
import type { BinaryArchitecture } from "../domain/binaryTargetTypes.js";
/** Bound Ghidra language for a caller-supplied raw-binary architecture. */
export interface GhidraRawBinaryLanguage {
readonly languageId: string;
readonly compilerSpecId: "default";
}
/**
* Map the four caller-visible CPU families to little-endian generic Ghidra
* languages. Big-endian, Thumb-only, and Cortex-M variants are out of scope.
*/
export const ghidraRawBinaryLanguage = (
architecture: Exclude<BinaryArchitecture, "mips">,
): GhidraRawBinaryLanguage => {
switch (architecture) {
case "x86":
return { languageId: "x86:LE:32:default", compilerSpecId: "default" };
case "x86_64":
return { languageId: "x86:LE:64:default", compilerSpecId: "default" };
case "arm":
return { languageId: "ARM:LE:32:v7", compilerSpecId: "default" };
case "arm64":
return { languageId: "AARCH64:LE:64:v8A", compilerSpecId: "default" };
}
};
@@ -0,0 +1,62 @@
import { createHash } from "node:crypto";
import type { NativeLoadImageObservation } from "../domain/native/nativeLoadImage.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
const hash = (bytes: Buffer): string =>
createHash("sha256").update(bytes).digest("hex");
export const fixtureRawBinaryLoadImage = (): {
snapshot: { sha256: string; bytes: number };
target: Extract<BinaryTarget, { format: "raw-binary" }>;
observation: NativeLoadImageObservation;
} => {
const bytes = Buffer.from("1eff2fe1", "hex");
const digest = hash(bytes);
return {
snapshot: { sha256: digest, bytes: bytes.length },
target: {
path: "/tmp/ecu.bin",
sha256: digest,
kind: "executable",
format: "raw-binary",
architecture: "arm",
availableArchitectures: ["arm"],
entryPoint: "0x8000000",
entryPointSource: "0x08000000",
},
observation: {
executable_format: "Raw Binary",
language_id: "ARM:LE:32:v7",
compiler_spec_id: "default",
image_base: "0x0",
default_address_space: "ram",
source_files: [
{
name: "ecu.bin",
size: bytes.length,
original_sha256: digest,
modified_sha256: digest,
},
],
mappings: [
{
block: "ram",
start: "0x8000000",
end: "0x8000003",
address_space: "ram",
initialized: true,
loaded: true,
overlay: false,
length: bytes.length,
source_file_index: 0,
file_offset: 0,
sha256: digest,
},
],
relocations: [],
entry_points: ["0x8000000"],
entry_context: [],
},
};
};
@@ -0,0 +1,98 @@
import { describe, expect, it } from "vitest";
import { attestGhidraRawBinaryLoadImage } from "./GhidraLoadImageValues.js";
import { fixtureRawBinaryLoadImage } from "./GhidraRawBinaryLoadImage.fixture.js";
import { ghidraRawBinaryLanguage } from "./GhidraRawBinaryLanguage.js";
describe("raw-binary Ghidra language binding", () => {
it("maps the four admitted families to little-endian generic languages", () => {
expect(ghidraRawBinaryLanguage("x86")).toEqual({
languageId: "x86:LE:32:default",
compilerSpecId: "default",
});
expect(ghidraRawBinaryLanguage("x86_64")).toEqual({
languageId: "x86:LE:64:default",
compilerSpecId: "default",
});
expect(ghidraRawBinaryLanguage("arm")).toEqual({
languageId: "ARM:LE:32:v7",
compilerSpecId: "default",
});
expect(ghidraRawBinaryLanguage("arm64")).toEqual({
languageId: "AARCH64:LE:64:v8A",
compilerSpecId: "default",
});
});
});
describe("raw-binary independent load-image checks", () => {
it("verifies mapped bytes at the caller-supplied entry", () => {
const f = fixtureRawBinaryLoadImage();
const result = attestGhidraRawBinaryLoadImage(
f.snapshot,
f.target,
f.observation,
);
expect(result).toMatchObject({
ok: true,
value: {
status: "verified",
format: "raw-binary",
architecture: "arm",
language_id: "ARM:LE:32:v7",
base_address: "0x8000000",
file_bytes: 4,
entry: { address: "0x8000000", file_offset: 0 },
},
});
});
it("retains mismatch evidence for a drifted language", () => {
const f = fixtureRawBinaryLoadImage();
f.observation.language_id = "x86:LE:32:default";
const result = attestGhidraRawBinaryLoadImage(
f.snapshot,
f.target,
f.observation,
);
expect(result).toMatchObject({
ok: true,
value: { status: "mismatch", observations: f.observation },
});
});
it("preserves additional language entries while requiring the caller entry", () => {
const f = fixtureRawBinaryLoadImage();
f.observation.entry_points = ["0x0", f.target.entryPoint, "0xffff0000"];
expect(
attestGhidraRawBinaryLoadImage(f.snapshot, f.target, f.observation),
).toMatchObject({
ok: true,
value: { status: "verified", observations: f.observation },
});
f.observation.entry_points = ["0x0", "0xffff0000"];
expect(
attestGhidraRawBinaryLoadImage(f.snapshot, f.target, f.observation),
).toMatchObject({
ok: true,
value: {
status: "mismatch",
checks: expect.arrayContaining([
expect.objectContaining({
name: "entry_point",
matched: false,
observed: null,
}),
]),
},
});
});
it("rejects stale snapshot identity", () => {
const f = fixtureRawBinaryLoadImage();
expect(
attestGhidraRawBinaryLoadImage(
f.snapshot,
{ ...f.target, sha256: "f".repeat(64) },
f.observation,
).ok,
).toBe(false);
});
});
+1
View File
@@ -140,6 +140,7 @@ export const hopperLoaderArgsForTarget = (
return ok(["-l", "WinPE", flag]);
case "dos-mz":
case "dos-com":
case "raw-binary":
return err(
new ProviderAdapterError("hopper", "resolve_analysis_profile"),
);
+21
View File
@@ -5,6 +5,27 @@ import { silentLogger } from "../logger.js";
import { HopperProvider } from "./HopperProvider.js";
describe("Hopper provider capabilities", () => {
it("declines headerless raw-binary targets with a Ghidra-directed reason", () => {
const config = parseConfig({});
if (!config.ok) throw new Error("expected valid configuration");
const provider = new HopperProvider(config.value, silentLogger, {});
expect(
provider.inspectTargetSupport({
path: "/tmp/ecu.bin",
sha256: "a".repeat(64),
kind: "executable",
format: "raw-binary",
architecture: "arm",
availableArchitectures: ["arm"],
entryPoint: "0x8000000",
entryPointSource: "0x8000000",
}),
).toMatchObject({
status: "unsupported",
code: "target_format_unsupported",
reason: expect.stringContaining("Ghidra"),
});
});
it("declines DOS MZ targets with a provider-specific support reason", () => {
const config = parseConfig({});
if (!config.ok) throw new Error("expected valid configuration");
+8
View File
@@ -123,6 +123,14 @@ export class HopperProvider implements AnalysisProviderCandidate {
reason: "REA's Hopper adapter does not admit MIPS targets.",
diagnostics,
};
if (target.format === "raw-binary")
return {
status: "unsupported",
code: "target_format_unsupported",
reason:
"Headerless raw-binary analysis requires the Ghidra adapter with a caller-supplied architecture and entry point.",
diagnostics,
};
if (target.format === "dos-mz" || target.format === "dos-com")
return {
status: "unsupported",
+28
View File
@@ -0,0 +1,28 @@
import { describe, expect, it } from "vitest";
import { parseConfig } from "../config/parseConfig.js";
import { IdaProvider } from "./IdaProvider.js";
describe("IDA provider target support", () => {
it("declines headerless raw-binary targets", () => {
const config = parseConfig({});
if (!config.ok) throw new Error("expected valid configuration");
const provider = new IdaProvider(config.value, {});
expect(
provider.inspectTargetSupport({
path: "/tmp/ecu.bin",
sha256: "a".repeat(64),
kind: "executable",
format: "raw-binary",
architecture: "arm",
availableArchitectures: ["arm"],
entryPoint: "0x8000000",
entryPointSource: "0x8000000",
}),
).toMatchObject({
status: "unsupported",
code: "target_format_unsupported",
reason: expect.stringContaining("Ghidra"),
});
});
});
+17 -9
View File
@@ -109,15 +109,23 @@ export class IdaProvider implements AnalysisProviderCandidate {
"REA's IDA adapter has no verified MIPS lane. Select a supported Ghidra profile instead.",
diagnostics,
};
return target.kind === "executable"
? { status: "supported", code: null, reason: null, diagnostics }
: {
status: "unsupported",
code: "target_kind_unsupported",
reason:
"IDA MCP integration admits executable inputs, not analysis databases. Select the original input binary.",
diagnostics,
};
if (target.kind !== "executable")
return {
status: "unsupported",
code: "target_kind_unsupported",
reason:
"IDA MCP integration admits executable inputs, not analysis databases. Select the original input binary.",
diagnostics,
};
if (target.format === "raw-binary")
return {
status: "unsupported",
code: "target_format_unsupported",
reason:
"IDA does not admit headerless raw binaries. Open the target with Ghidra and supply architecture and entry_point.",
diagnostics,
};
return { status: "supported", code: null, reason: null, diagnostics };
}
async resolveAnalysisProfile(
_target: BinaryTarget,
+4 -2
View File
@@ -22,8 +22,10 @@ export const mcpProgressReporter = (
method: "notifications/progress",
params: {
progressToken: token,
progress: update.completed,
...(update.total === null ? {} : { total: update.total }),
// Status phases can repeat their work count while waiting. The
// protocol requires every notification to advance; count emitted
// observations without inventing a total amount of analysis work.
progress: update.sequence,
message: `${update.phase}: ${update.message}`,
},
});
+8 -7
View File
@@ -12,6 +12,7 @@ import { ProcessCaptureResourceScope } from "../process/capture/ProcessCaptureLi
import { ProcessCaptureError } from "../process/capture/ProcessCaptureError.js";
import { toolContract } from "../contracts/toolContracts.js";
import type { AnalysisSnapshot } from "../domain/analysisSnapshot.js";
import { binaryTargetSummary } from "../application/binary/BinaryTargetSummary.js";
import { UnknownRegistryError } from "../domain/unknownRegistryError.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import type { Evidence } from "../domain/evidence.js";
@@ -203,6 +204,12 @@ const registerOpenLifecycleTool = ({
session.open(input.path, {
signal: context.mcpReq.signal,
...(input.format === undefined ? {} : { formatHint: input.format }),
...(input.architecture === undefined
? {}
: { architecture: input.architecture }),
...(input.entry_point === undefined
? {}
: { entryPoint: input.entry_point }),
...(input.provider_id === undefined
? {}
: { providerId: input.provider_id }),
@@ -213,13 +220,7 @@ const registerOpenLifecycleTool = ({
? server.delivery.toCallToolResult(
{
ok: true,
value: {
path: opened.value.path,
format: opened.value.format,
kind: opened.value.kind,
sha256: opened.value.sha256,
architecture: opened.value.architecture ?? null,
},
value: binaryTargetSummary(opened.value),
},
openContract,
)
+4 -2
View File
@@ -67,8 +67,10 @@ describe("derived MCP operation boundary", () => {
);
expect(result).toEqual({ ok: true, value: "complete" });
expect(notifications.map(({ params }) => params?.progress)).toEqual([0, 2]);
expect(notifications.every(({ params }) => params?.total === 2)).toBe(true);
expect(notifications.map(({ params }) => params?.progress)).toEqual([1, 2]);
expect(
notifications.every(({ params }) => params?.total === undefined),
).toBe(true);
});
it("projects synchronous computation failures into a typed result", async () => {
@@ -0,0 +1,186 @@
import { writeFile } from "node:fs/promises";
import { join } from "node:path";
import { expect } from "vitest";
import { z } from "zod";
import { javascriptApplicationAnalysisResultSchema } from "../../../src/domain/javascript/javascriptApplicationAnalysis.js";
import { ROLLDOWN_MODULE_INTEROP } from "../../../src/domain/javascript/javascriptModuleInterop.fixture.js";
import { connectLocalToolsMcp } from "../../fixtures/localToolsMcp.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
import { cliTest } from "../../support/cli/cliFixture.js";
const INTRINSIC_MUTATIONS = [
["poisoned.cjs", "({Object} = replacements);"],
[
"projected.cjs",
'const {defineProperty:change} = Object; change(Object,"create",{value:customCreate});',
],
[
"decorated.cjs",
'@(() => Object) class metadata {}; Object.defineProperty(metadata,"create",{value:customCreate});',
],
[
"uncurried.cjs",
'const change = Function.prototype.call.bind(Object.defineProperty,null); change(Object,"create",{value:customCreate});',
],
[
"generic-bind.cjs",
'const change = Function.prototype.bind.call(Object.defineProperty,null); change(Object,"create",{value:customCreate});',
],
[
"replaced-apply.cjs",
'Reflect.apply = Object.defineProperty; Reflect.apply(Object,"create",{value:customCreate});',
],
[
"bound.cjs",
'const change = Object.defineProperty.bind(null,Object,"create"); change({value:customCreate});',
],
["receiver.cjs", 'Reflect.set({},"create",customCreate,Object);'],
] as const;
const writePoisonedModules = async (root: string): Promise<void> => {
for (const [name, mutation] of INTRINSIC_MUTATIONS)
await writeFile(
join(root, name),
`${mutation}
${ROLLDOWN_MODULE_INTEROP}
let poisoned = require("electron");
poisoned = __toESM(poisoned, 1);
new poisoned.BrowserWindow({});
throw new Error("must not execute poisoned source");`,
);
};
cliTest.for(["CLI", "stdio MCP"] as const)(
"retains converted Electron windows and preload evidence through %s",
async (surface, { cli }) => {
const root = await createTestTempDirectory("rea-electron-interop-");
await writeFile(
join(root, "package.json"),
JSON.stringify({ main: "main.cjs" }),
);
await writeFile(
join(root, "preload.js"),
'throw new Error("must stay inert");',
);
await writePoisonedModules(root);
const source = `const metadata = {};
Object.defineProperty(metadata,"x",{value:1});
const decorateMetadata = Object.defineProperty.bind(null,metadata,"bound");
decorateMetadata({value:1});
const decorateViaCall = Function.prototype.call.bind(Object.defineProperty);
decorateViaCall(null,metadata,"uncurried",{value:1});
const localFunction = () => {};
Object.defineProperty(localFunction,"x",{value:1});
const localClass = class {};
Object.defineProperty(localClass,"x",{value:1});
const localRegExp = /local/;
Object.defineProperty(localRegExp,"x",{value:1});
Object.defineProperty(hoistedFunction,"x",{value:1});
function hoistedFunction() {}
const captured = Object.defineProperty;
Object.defineProperty = custom;
${ROLLDOWN_MODULE_INTEROP.replace("__defProp = Object.defineProperty", "__defProp = captured")}
let electron = require("electron");
electron = __toESM(electron, 1);
new electron.BrowserWindow({webPreferences:{preload:"./preload.js"}});
new electron.BrowserWindow({webPreferences:{preload:runtimePath}});
var direct;
var direct = require("electron");
var direct;
new direct.BrowserWindow({});
const fresh = __toESM(require("electron"), 1);
new fresh.BrowserWindow({});
const {BrowserWindow: ProjectedWindow} = __toESM(require("electron"));
new ProjectedWindow({});
const nonNode = __toESM(require("electron"), 0);
new nonNode.BrowserWindow({});
function identity(mod) {return mod;}
const passthrough = identity(require("electron"));
new passthrough.BrowserWindow({});
const __importStar = () => ({BrowserWindow:FakeWindow});
const fake = __importStar(require("electron"));
new fake.BrowserWindow({});
function decoy(electron) {new electron.BrowserWindow({});}
require("./poisoned.cjs");
require("./projected.cjs");
require("./decorated.cjs");
require("./bound.cjs");
require("./uncurried.cjs");
require("./generic-bind.cjs");
require("./replaced-apply.cjs");
require("./receiver.cjs");
throw new Error("must not execute main");
`;
await writeFile(join(root, "main.cjs"), source);
let document: unknown;
if (surface === "CLI") {
const response = await cli.run({
arguments: ["analyze-javascript-application", root, "--json"],
});
expect(response.exitCode, response.stderr).toBe(0);
document = response.json;
} else {
const { call } = await connectLocalToolsMcp();
const response = await call("analyze_javascript_application", {
input_path: root,
});
expect(response.isError, JSON.stringify(response)).not.toBe(true);
document = response.structuredContent;
}
const result = z
.object({ normalized_result: javascriptApplicationAnalysisResultSchema })
.parse(document).normalized_result;
expect(result.summary).toMatchObject({
browser_windows: 7,
preload_entrypoints: 1,
});
expect(result.statistics.parse_failures).toBe(0);
expect(result.statistics.parsed_javascript_files).toBe(10);
const windows = result.graph.nodes.filter(
({ kind }) => kind === "browser-window",
);
expect(windows).toHaveLength(7);
const expectedLines = source
.split("\n")
.flatMap((line, index) =>
/^\s*new (?:(?:electron|direct|fresh|passthrough|nonNode)\.BrowserWindow|ProjectedWindow)\(/u.test(
line,
)
? [index + 1]
: [],
);
const observedLines = windows.flatMap((window) => {
const location = window.observations[0]?.evidence.location;
return location?.available && location.value.kind === "source-range"
? [location.value.start.line]
: [];
});
expect(observedLines.toSorted()).toEqual(expectedLines.toSorted());
for (const window of windows) {
expect(window.observations[0]?.evidence.location).toMatchObject({
available: true,
value: { kind: "source-range", source: "main.cjs" },
});
}
expect(
windows.flatMap((window) =>
window.observations.map(({ properties }) => properties.web_preferences),
),
).toEqual(
expect.arrayContaining([
expect.arrayContaining([
expect.objectContaining({
name: "preload",
value: {
status: "dynamic",
value: null,
expression: "runtimePath",
},
}),
]),
]),
);
},
);
+103
View File
@@ -0,0 +1,103 @@
import { writeFile } from "node:fs/promises";
import { join } from "node:path";
import { expect } from "vitest";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
import { cliTest } from "../../support/cli/cliFixture.js";
cliTest(
"rejects a headerless image until architecture and entry are supplied",
async ({ cli }) => {
const root = await createTestTempDirectory("rea-raw-cli-");
const path = join(root, "ecu.bin");
await writeFile(path, Buffer.from("1eff2fe1", "hex"));
const before = await cli.run({
arguments: ["inspect", path, "--json"],
environment: {
HOME: root,
XDG_CONFIG_HOME: root,
XDG_CACHE_HOME: root,
},
});
expect(before.exitCode).not.toBe(0);
expect(JSON.stringify(before.json)).not.toContain("raw-binary");
const missing = await cli.run({
arguments: ["inspect", path, "--target-format", "raw-binary", "--json"],
environment: {
HOME: root,
XDG_CONFIG_HOME: root,
XDG_CACHE_HOME: root,
},
});
expect(missing.exitCode).toBe(1);
expect(missing.json).toMatchObject({
code: "target_unavailable",
details: { reason: expect.stringContaining("architecture") },
});
},
);
cliTest(
"rejects an unaligned AArch64 entry before provider startup",
async ({ cli }) => {
const root = await createTestTempDirectory("rea-raw-cli-alignment-");
const path = join(root, "image.bin");
await writeFile(path, Buffer.from("c0035fd6", "hex"));
const result = await cli.run({
arguments: [
"inspect",
path,
"--target-format",
"raw-binary",
"--architecture",
"arm64",
"--entry-point",
"0x8000001",
"--provider",
"ghidra",
"--json",
],
environment: { HOME: root, XDG_CONFIG_HOME: root, XDG_CACHE_HOME: root },
});
expect(result.exitCode).toBe(1);
expect(result.json).toMatchObject({
code: "target_unavailable",
details: { reason: expect.stringContaining("must be 4-byte aligned") },
});
},
);
cliTest(
"stops Hopper from claiming a caller-supplied raw-binary image",
async ({ cli }) => {
const root = await createTestTempDirectory("rea-raw-cli-hopper-");
const path = join(root, "ecu.bin");
await writeFile(path, Buffer.from("1eff2fe1", "hex"));
const result = await cli.run({
arguments: [
"inspect",
path,
"--target-format",
"raw-binary",
"--architecture",
"arm",
"--entry-point",
"0x8000000",
"--provider",
"hopper",
"--json",
],
environment: {
HOME: root,
XDG_CONFIG_HOME: root,
XDG_CACHE_HOME: root,
},
});
expect(result.exitCode).toBe(1);
expect(JSON.stringify(result.json)).toMatch(/Hopper|ghidra|Ghidra|hopper/i);
expect(JSON.stringify(result.json)).not.toMatch(
/unsupported binary format/i,
);
},
);
@@ -0,0 +1,105 @@
import { createHash } from "node:crypto";
import { readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
import { parseBinaryTarget } from "../../../src/application/BinaryTargetResolver.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
describe("raw-binary admission", () => {
it("requires explicit architecture and entry even with a misleading suffix", async () => {
const directory = await createTestTempDirectory("rea-raw-target-");
const path = join(directory, "fixture.js");
const bytes = Buffer.from("1eff2fe1", "hex");
await writeFile(path, bytes);
const target = await parseBinaryTarget(path, {
cwd: directory,
hostArchitecture: "arm64",
formatHint: "raw-binary",
architecture: "arm",
entryPoint: "0x08000000",
});
expect(target).toMatchObject({
ok: true,
value: {
path,
format: "raw-binary",
kind: "executable",
architecture: "arm",
availableArchitectures: ["arm"],
entryPoint: "0x8000000",
entryPointSource: "0x08000000",
sha256: createHash("sha256").update(bytes).digest("hex"),
},
});
expect(await readFile(path)).toEqual(bytes);
const detected = await parseBinaryTarget(path);
expect(detected.ok && detected.value.format).not.toBe("raw-binary");
});
it("rejects raw-binary without architecture and entry", async () => {
const directory = await createTestTempDirectory("rea-raw-missing-");
const path = join(directory, "fixture.bin");
await writeFile(path, Buffer.from("c3", "hex"));
expect(
await parseBinaryTarget(path, {
cwd: directory,
hostArchitecture: "x64",
formatHint: "raw-binary",
}),
).toMatchObject({
ok: false,
error: {
_tag: "BinaryTargetError",
reason: expect.stringContaining("architecture"),
},
});
});
it("rejects architecture without format=raw-binary", async () => {
const directory = await createTestTempDirectory("rea-raw-unpaired-");
const path = join(directory, "fixture.bin");
await writeFile(path, Buffer.from("c3", "hex"));
expect(
await parseBinaryTarget(path, {
cwd: directory,
hostArchitecture: "x64",
architecture: "arm",
entryPoint: "0x8000000",
}),
).toMatchObject({
ok: false,
error: {
_tag: "BinaryTargetError",
reason: expect.stringContaining("format=raw-binary"),
},
});
});
it("rejects an empty image", async () => {
const directory = await createTestTempDirectory("rea-raw-empty-");
const path = join(directory, "fixture.bin");
await writeFile(path, Buffer.alloc(0));
expect(
await parseBinaryTarget(path, {
cwd: directory,
hostArchitecture: "x64",
formatHint: "raw-binary",
architecture: "x86",
entryPoint: "0x1000",
}),
).toMatchObject({ ok: false, error: { _tag: "BinaryTargetError" } });
});
it("rejects a contradictory target kind", async () => {
const directory = await createTestTempDirectory("rea-raw-kind-");
const path = join(directory, "fixture.bin");
await writeFile(path, Buffer.from("c3", "hex"));
expect(
await parseBinaryTarget(path, {
cwd: directory,
hostArchitecture: "x64",
targetKind: "database",
formatHint: "raw-binary",
architecture: "x86",
entryPoint: "0x1000",
}),
).toMatchObject({ ok: false, error: { _tag: "BinaryTargetError" } });
});
});
+5 -2
View File
@@ -415,8 +415,11 @@ it("exposes the target-free static JavaScript application workflow", async () =>
);
expect(analyzed.isError).not.toBe(true);
expect(progress[0]).toBe(0);
expect(progress.at(-1)).toBe(1);
expect(progress[0]).toBe(1);
expect(progress.at(-1)).toBeGreaterThan(1);
progress.forEach((value, index) => {
expect(value).toBeGreaterThan(progress[index - 1] ?? 0);
});
const projected = z
.object({
evidence_id: z.string(),
+33 -9
View File
@@ -1,4 +1,5 @@
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
import { setTimeout as delay } from "node:timers/promises";
import { describe, expect, it } from "vitest";
import type { AnalysisOperationPort } from "../../../src/application/AnalysisProvider.js";
@@ -8,29 +9,52 @@ import { createServer } from "../../../src/server/createServer.js";
import { observed } from "../../fixtures/analysisExecution.js";
describe("ordinary MCP progress and cancellation", () => {
it("emits bounded progress for a normal tool request", async () => {
it("advances MCP progress when provider waiting does not advance completed work", async () => {
const analysis: AnalysisOperationPort = {
execute: () => Promise.resolve(observed("0x1000")),
execute: async (_operation, _parameters, options) => {
for (const message of ["import pending", "analysis pending"]) {
await delay(120);
await options?.progress?.report({
phase: "ghidra_startup",
completed: 0,
total: null,
message,
});
}
return observed("0x1000");
},
};
const server = createServer({ kind: "fixed", analysis });
const client = new Client({ name: "progress-test", version: "1" });
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
const progress: number[] = [];
const progress: {
progress: number;
total?: number | undefined;
message?: string | undefined;
}[] = [];
try {
await server.connect(serverTransport);
await client.connect(clientTransport);
const result = await client.callTool(
{ name: "current_address", arguments: {} },
{ onprogress: (update) => progress.push(update.progress) },
{ onprogress: (update) => progress.push(update) },
);
expect(result.isError).not.toBe(true);
expect(progress[0]).toBe(0);
expect(progress.at(-1)).toBe(1);
progress.forEach((value, index) => {
expect(value).toBeGreaterThanOrEqual(progress[index - 1] ?? 0);
expect(value).toBeLessThanOrEqual(1);
expect(progress[0]?.progress).toBe(1);
expect(progress.map((update) => update.message)).toEqual(
expect.arrayContaining([
"ghidra_startup: import pending",
"ghidra_startup: analysis pending",
]),
);
expect(progress.at(-1)?.message).toContain("completed");
progress.forEach((update, index) => {
expect(update.progress).toBeGreaterThan(
progress[index - 1]?.progress ?? 0,
);
expect(update.total).toBeUndefined();
});
} finally {
await Promise.allSettled([client.close(), server.close()]);
+219
View File
@@ -0,0 +1,219 @@
import { writeFile } from "node:fs/promises";
import { join } from "node:path";
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
import { Ajv2020 } from "ajv/dist/2020.js";
import { expect, it, onTestFinished } from "vitest";
import { z } from "zod";
import { createServer } from "../../../src/server/createServer.js";
import { toolContract } from "../../../src/contracts/toolContracts.js";
import type { AnalysisProvider } from "../../../src/application/AnalysisProvider.js";
import { createAnalysisProfile } from "../../../src/domain/analysisProfile.js";
import { ok } from "../../../src/domain/result.js";
import { observed } from "../../fixtures/analysisExecution.js";
import {
createCacheProvider,
createTestBinarySession,
} from "../../fixtures/binarySession.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
import { silentLogger } from "../../../src/logger.js";
import type { CallToolResult } from "@modelcontextprotocol/server";
const connect = async (
provider: AnalysisProvider = createCacheProvider([]),
) => {
const session = createTestBinarySession(provider);
const server = createServer(
{ kind: "session", session },
{ logger: silentLogger },
);
const client = new Client({ name: "raw-binary-mcp", version: "1" });
onTestFinished(async () => {
await client.close();
await server.close();
await session.close();
});
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
await server.connect(serverTransport);
await client.connect(clientTransport);
return { client, session };
};
const structured = (result: CallToolResult): Record<string, unknown> => {
if (
typeof result.structuredContent !== "object" ||
result.structuredContent === null
)
throw new Error("missing structured result");
return z.record(z.string(), z.unknown()).parse(result.structuredContent);
};
it("opens a headerless image when architecture and entry are supplied", async () => {
const root = await createTestTempDirectory("rea-raw-mcp-");
const path = join(root, "ecu.bin");
await writeFile(path, Buffer.from("1eff2fe1", "hex"));
const { client } = await connect();
const opened = await client.callTool({
name: "open_binary",
arguments: {
path,
format: "raw-binary",
architecture: "arm",
entry_point: "0x08000000",
},
});
expect(opened.isError).not.toBe(true);
expect(structured(opened).result).toMatchObject({
path,
format: "raw-binary",
kind: "executable",
architecture: "arm",
entry_point: "0x8000000",
});
});
it("rejects an unaligned AArch64 entry before selecting or starting a provider", async () => {
const root = await createTestTempDirectory("rea-raw-mcp-alignment-");
const path = join(root, "image.bin");
await writeFile(path, Buffer.from("c0035fd6", "hex"));
const { client, session } = await connect({
...createCacheProvider([]),
resolveAnalysisProfile: () => {
throw new Error("unaligned input must not select a provider");
},
createClient: () => {
throw new Error("unaligned input must not launch a provider");
},
});
const opened = await client.callTool({
name: "open_binary",
arguments: {
path,
format: "raw-binary",
architecture: "arm64",
entry_point: "0x8000001",
},
});
expect(opened.isError).toBe(true);
expect(JSON.stringify(opened.content)).toContain("must be 4-byte aligned");
expect(session.activeTarget()).toBeUndefined();
});
it("rejects raw-binary open requests that omit architecture", async () => {
const root = await createTestTempDirectory("rea-raw-mcp-missing-");
const path = join(root, "ecu.bin");
await writeFile(path, Buffer.from("1eff2fe1", "hex"));
const { client } = await connect();
const opened = await client.callTool({
name: "open_binary",
arguments: { path, format: "raw-binary" },
});
expect(opened.isError).toBe(true);
});
it("reuses a canonical raw entry and replaces the session when the entry changes", async () => {
const root = await createTestTempDirectory("rea-raw-mcp-reopen-");
const path = join(root, "ecu.bin");
await writeFile(path, Buffer.from("1eff2fe1", "hex"));
const fixture = createCacheProvider([]);
const resolved: string[] = [];
const created: string[] = [];
const closed: string[] = [];
const { client, session } = await connect({
...fixture,
resolveAnalysisProfile: (target) => {
if (target.format !== "raw-binary")
throw new Error("expected raw binary");
resolved.push(target.entryPoint);
return Promise.resolve(
ok({
profile: createAnalysisProfile(
{ ...fixture.identity(), version: "1" },
{
entry_point: target.entryPoint,
},
),
}),
);
},
createClient: (target) => {
if (target.format !== "raw-binary")
throw new Error("expected raw binary");
created.push(target.entryPoint);
return {
execute: (operation) => {
if (operation !== "health" && operation !== "address_name")
throw new Error(`unexpected fixture operation: ${operation}`);
return Promise.resolve(observed(target.entryPoint));
},
close: () => {
closed.push(target.entryPoint);
return Promise.resolve(ok(null));
},
};
},
});
const tools = (await client.listTools()).tools;
const validateLifecycle = (
name: "open_binary" | "binary_session",
response: CallToolResult,
) => {
const tool = tools.find((candidate) => candidate.name === name);
if (tool?.outputSchema === undefined)
throw new Error(`missing ${name} output schema`);
const schema = z.record(z.string(), z.unknown()).parse(tool.outputSchema);
const validate = new Ajv2020({
strict: false,
validateFormats: false,
}).compile(schema);
expect(
validate(response.structuredContent),
JSON.stringify(validate.errors),
).toBe(true);
const parsed = toolContract(name).outputSchema.parse(
response.structuredContent,
);
const target = z.record(z.string(), z.unknown()).parse(parsed.result);
const { entry_point: _entry, ...missingEntry } = target;
expect(validate({ ...structured(response), result: missingEntry })).toBe(
false,
);
return target;
};
for (const entryPoint of ["0x08000000", "0x8000000", "0x09000000"]) {
const opened = await client.callTool({
name: "open_binary",
arguments: {
path,
format: "raw-binary",
architecture: "arm",
entry_point: entryPoint,
},
});
expect(opened.isError, JSON.stringify(opened)).not.toBe(true);
const canonical = `0x${BigInt(entryPoint).toString(16)}`;
expect(validateLifecycle("open_binary", opened).entry_point).toBe(
canonical,
);
const status = await client.callTool({
name: "binary_session",
arguments: {},
});
expect(status.isError, JSON.stringify(status)).not.toBe(true);
expect(validateLifecycle("binary_session", status).entry_point).toBe(
canonical,
);
const result = await client.callTool({
name: "address_name",
arguments: { address: entryPoint },
});
expect(result.isError, JSON.stringify(result)).not.toBe(true);
expect(structured(result).normalized_result).toBe(canonical);
}
expect(session.analysisProfile()?.parameters.entry_point).toBe("0x9000000");
expect(resolved).toEqual(["0x8000000", "0x9000000"]);
expect(created).toEqual(["0x8000000", "0x9000000"]);
expect(closed).toEqual(["0x8000000"]);
});
@@ -8,9 +8,11 @@ import { fileURLToPath } from "node:url";
import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest";
import pino from "pino";
import type { Logger } from "pino";
import type { ProgressUpdate } from "../../../../src/application/ProgressReporter.js";
import { ok } from "../../../../src/domain/result.js";
import { GhidraClient } from "../../../../src/ghidra/GhidraClient.js";
import { OwnedFileHandle } from "../../../../src/filesystem/OwnedFileHandle.js";
import { GHIDRA_PROCESS_DIAGNOSTIC_BYTES } from "../../../../src/ghidra/GhidraDiagnostics.js";
import { GhidraHeadlessLauncher } from "../../../../src/ghidra/GhidraLauncher.js";
import type { GhidraDiagnostic } from "../../../../src/ghidra/GhidraClientTypes.js";
@@ -121,12 +123,14 @@ const clientFor = (
readonly transport?: GhidraTransportKind;
readonly runId?: string;
readonly logger?: Logger;
readonly targetPath?: string;
readonly targetSha256?: string;
} = {},
): GhidraClient => {
const client = new GhidraClient({
launcher,
targetPath: fixturePath,
targetSha256: TARGET_SHA256,
targetPath: options.targetPath ?? fixturePath,
targetSha256: options.targetSha256 ?? TARGET_SHA256,
transport: options.transport ?? HOST_TRANSPORT,
providerVersion: PROVIDER_VERSION,
profileDigest: PROFILE_DIGEST,
@@ -146,7 +150,156 @@ afterEach(async () => {
await Promise.all(clients.splice(0).map((client) => client.close()));
});
it("reports unknown startup work and stops notifications when cancellation releases the process", async () => {
vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] });
const launcher = new FixtureLauncher("silent");
const client = clientFor(launcher, { startupTimeoutMs: 30_000 });
const controller = new AbortController();
const updates: ProgressUpdate[] = [];
const started = client.start(controller.signal, {
report: async (update) => {
updates.push(update);
controller.abort();
},
});
const child = await launcher.started;
await vi.advanceTimersByTimeAsync(10_000);
expect(await started).toMatchObject({
ok: false,
error: { kind: "cancelled" },
});
expect(updates).toEqual([
expect.objectContaining({
phase: "ghidra_startup",
completed: 0,
total: null,
message: expect.stringContaining("Waiting for Ghidra startup"),
}),
]);
await client.close();
await expect(waitForChildExit(child, 5_000)).resolves.toBe(true);
await expect(access(launcher.runtimeRoots[0] ?? "")).rejects.toMatchObject({
code: "ENOENT",
});
await vi.advanceTimersByTimeAsync(30_000);
expect(updates).toHaveLength(1);
});
it("keeps one shared startup despite a failed progress sink and stops reports after readiness", async () => {
vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] });
const launcher = new FixtureLauncher();
let releaseLaunch: (() => void) | undefined;
let markLaunchPending: (() => void) | undefined;
const launchPending = new Promise<void>((resolve) => {
markLaunchPending = resolve;
});
const launchGate = new Promise<void>((resolve) => {
releaseLaunch = resolve;
});
const client = clientFor(
{
async launch(session) {
markLaunchPending?.();
await launchGate;
return launcher.launch(session);
},
},
{ startupTimeoutMs: 30_000 },
);
let reports = 0;
const started = client.start(undefined, {
report: async () => {
reports += 1;
throw new Error("notification unavailable");
},
});
const concurrent = client.start();
await launchPending;
await vi.advanceTimersByTimeAsync(10_000);
expect(reports).toBe(1);
releaseLaunch?.();
await expect(started).resolves.toMatchObject({ ok: true });
await expect(concurrent).resolves.toMatchObject({ ok: true });
expect(launcher.processes).toHaveLength(1);
await vi.advanceTimersByTimeAsync(30_000);
expect(reports).toBe(1);
});
describe("GhidraClient captured source snapshot", () => {
it("retains a snapshot descriptor whose close failed until session cleanup succeeds", async () => {
const client = clientFor(new FixtureLauncher());
const started = await client.start();
if (!started.ok) throw started.error;
const close = vi
.spyOn(OwnedFileHandle.prototype, "close")
.mockRejectedValueOnce(new Error("snapshot descriptor close failed"));
try {
await expect(client.hashTargetSnapshot()).resolves.toMatchObject({
ok: false,
error: { kind: "protocol" },
});
const owner = close.mock.contexts[0];
expect(owner).toBeInstanceOf(OwnedFileHandle);
const closed = await client.close();
if (!closed.ok) throw closed.error;
expect(
close.mock.contexts.filter((context) => context === owner),
).toHaveLength(2);
} finally {
close.mockRestore();
}
});
it("hashes complete private snapshots with bounded chunks and abortable reads", async () => {
const root = await createTestTempDirectory("rea-ghidra-hash-");
const source = join(root, "firmware.bin");
const bytes = Buffer.alloc(512 * 1024 + 3, 0xa5);
const sha256 = createHash("sha256").update(bytes).digest("hex");
await writeFile(source, bytes);
const client = clientFor(new FixtureLauncher(), {
targetPath: source,
targetSha256: sha256,
});
await expect(client.hashTargetSnapshot()).resolves.toMatchObject({
ok: false,
error: { kind: "protocol" },
});
const started = await client.start();
if (!started.ok) throw started.error;
// Observe the admitted private snapshot even if the original path changes.
await writeFile(source, "changed original");
const allocate = Buffer.allocUnsafe;
const allocations = vi.spyOn(Buffer, "allocUnsafe");
try {
const identity = await client.hashTargetSnapshot();
if (!identity.ok) throw identity.error;
expect(identity.value).toEqual({ sha256, bytes: bytes.length });
expect(allocations.mock.calls.length).toBeGreaterThan(1);
expect(
Math.max(...allocations.mock.calls.map(([size]) => size)),
).toBeLessThan(bytes.length);
const controller = new AbortController();
allocations.mockImplementationOnce((size) => {
controller.abort();
return allocate(size);
});
await expect(
client.hashTargetSnapshot(controller.signal),
).resolves.toMatchObject({ ok: false, error: { kind: "cancelled" } });
} finally {
allocations.mockRestore();
}
await expect(client.hashTargetSnapshot()).resolves.toMatchObject({
ok: true,
value: { sha256, bytes: bytes.length },
});
await client.close();
await expect(client.hashTargetSnapshot()).resolves.toMatchObject({
ok: false,
error: { kind: "protocol" },
});
});
it("exposes the immutable import snapshot only during the live session", async () => {
const client = clientFor(new FixtureLauncher());
await expect(client.readTargetSnapshot()).resolves.toMatchObject({
@@ -113,6 +113,39 @@ describe("Ghidra COM loader", () => {
});
});
describe("Ghidra raw-binary loader", () => {
it("loads caller-supplied architecture and entry before auto-analysis", () => {
const arguments_ = ghidraHeadlessArguments({
projectRoot: "/tmp/project",
targetPath: "/tmp/ecu.bin",
bridgeScriptPath: "/package/bridge/ReaGhidraBridge.java",
descriptorPath: "/tmp/session.json",
ghidraLogPath: "/tmp/ghidra.log",
scriptLogPath: "/tmp/script.log",
rawBinary: {
languageId: "ARM:LE:32:v7",
compilerSpecId: "default",
baseAddr: "0x8000000",
},
});
expectOptions(arguments_, [
["-loader", "BinaryLoader"],
["-loader-baseAddr", "0x8000000"],
["-processor", "ARM:LE:32:v7"],
["-cspec", "default"],
]);
const prepare = arguments_.indexOf("-preScript");
expect(arguments_[prepare + 1]).toBe(
join("/package/bridge", "ReaGhidraPrepareRaw.java"),
);
expect(arguments_[prepare + 2]).toBe("ARM:LE:32:v7");
expect(arguments_[prepare + 3]).toBe("0x8000000");
expect(prepare).toBeLessThan(arguments_.indexOf("-postScript"));
expect(arguments_).toContain("-readOnly");
expect(arguments_).toContain("-deleteProject");
});
});
describe("Ghidra headless launcher", () => {
it("forces the admitted real-mode language and loader for DOS MZ", () => {
const arguments_ = ghidraHeadlessArguments({
@@ -208,6 +241,20 @@ describe("Ghidra configured import language and seeds", () => {
).toThrow(/cannot be combined with a DOS import/u);
});
it("never combines a configured language with a raw-binary import", () => {
expect(() =>
ghidraHeadlessArguments({
...base,
languageOverride: { languageId: "x86:LE:32:default" },
rawBinary: {
languageId: "ARM:LE:32:v7",
compilerSpecId: "default",
baseAddr: "0x8000000",
},
}),
).toThrow(/cannot be combined with a raw-binary import/u);
});
it.each(["darwin", "win32"] as const)(
"applies seeds after loader preparation and before analysis scripts on %s",
(platform) => {
@@ -31,6 +31,27 @@ describe("Hopper analysis profiles", () => {
});
});
it("does not map caller-supplied raw binaries onto a Hopper loader", () => {
expect(
hopperLoaderArgsForTarget({
path: "/tmp/ecu.bin",
sha256: "a".repeat(64),
kind: "executable",
format: "raw-binary",
architecture: "arm",
availableArchitectures: ["arm"],
entryPoint: "0x8000000",
entryPointSource: "0x8000000",
}),
).toMatchObject({
ok: false,
error: {
_tag: "ProviderAdapterError",
operation: "resolve_analysis_profile",
},
});
});
it.each([
[target("elf", "x86_64"), ["-l", "ELF", "--intel-64"]],
[target("pe", "x86"), ["-l", "WinPE", "--intel-32"]],
@@ -1,11 +1,16 @@
import com.atxx.jhmcp.*;
import com.android.tools.smali.smali.Smali;
import com.android.tools.smali.smali.SmaliOptions;
import com.google.gson.*;
import io.modelcontextprotocol.kotlin.sdk.types.CallToolResult;
import io.modelcontextprotocol.kotlin.sdk.types.TextContent;
import jadx.api.*;
import jadx.core.dex.nodes.*;
import java.lang.reflect.*;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.*;
import java.util.zip.*;
import kotlin.coroutines.EmptyCoroutineContext;
import kotlinx.coroutines.BuildersKt;
@@ -37,6 +42,86 @@ public class ReaJadxMetadataRegression {
return value;
}
private static Path initializerFixture(String sources, String output) throws Exception {
Path directory = Path.of(output);
SmaliOptions options = new SmaliOptions();
options.apiLevel = 28;
options.jobs = 1;
options.outputDexFile = directory.resolve("initializers.dex").toString();
require(Smali.assemble(options, List.of(
Path.of(sources, "InitializationPolicy.smali").toString(),
Path.of(sources, "MixedInitialization.smali").toString())), "Initializer fixture assembly failed");
Path apk = directory.resolve("initializers.apk");
try (ZipOutputStream zip = new ZipOutputStream(Files.newOutputStream(apk))) {
zip.putNextEntry(new ZipEntry("classes.dex"));
Files.copy(Path.of(options.outputDexFile), zip);
zip.closeEntry();
}
return apk;
}
private static JsonObject methodArguments(String className, String methodName) {
JsonObject value = arguments(className);
value.addProperty("method_name", methodName);
value.addProperty("overload_index", 0);
return value;
}
private static void verifyInitializers(SessionHolder holder, SessionConfig config,
Constructor<?> constructor, Method handle, Path apk) throws Exception {
BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
(scope, continuation) -> holder.unload(continuation));
BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
(scope, continuation) -> holder.load(apk.toString(), config, continuation));
Object bridge = constructor.newInstance(holder);
String[] classNames = { "fixture.InitializationPolicy", "fixture.MixedInitialization" };
String[][] witnesses = {
{ "declared-policy", "->singletonList", "->POLICY:Ljava/util/List;" },
{ "field-value", "->LABEL:Ljava/lang/String;", "->touch()V" }
};
for (int index = 0; index < classNames.length; index++) {
JsonObject summary = call(handle, bridge, "get_class_summary", arguments(classNames[index]));
JsonObject input = methodArguments(classNames[index], "<clinit>");
JsonObject body = call(handle, bridge, "get_method_body", input);
String text = body.get("body").getAsString();
for (String witness : witnesses[index]) require(text.contains(witness), "Missing initializer instruction: " + witness);
require(body.get("mode").getAsString().equals("smali"), "Static initializer must preserve DEX instructions");
require(body.get("fell_back").getAsBoolean(), "Disassembly fallback was not reported");
require(body.getAsJsonArray("markers").contains(new JsonPrimitive("static_initializer_disassembly")),
"Static initializer representation reason was not reported");
require(text.contains(".method static constructor <clinit>()V") && text.contains(".end method"),
"Initializer method boundaries missing");
require(body.get("overload_index").getAsInt() == 0 && body.get("overload_count").getAsInt() == 1,
"Initializer identity changed");
require(body.equals(call(handle, bridge, "get_method_body", input)), "Repeated initializer body changed");
require(summary.equals(call(handle, bridge, "get_class_summary", arguments(classNames[index]))),
"Frozen initializer metadata changed after source generation");
}
for (String name : List.of("missing", "originalNative")) {
JsonObject body = call(handle, bridge, "get_method_body", methodArguments(classNames[0], name));
String text = body.get("body").getAsString();
require(body.get("mode").getAsString().equals("java") && !text.contains("{") && !text.contains(".method"),
"Executable body was fabricated for " + name + ": " + text);
}
JsonObject ordinary = call(handle, bridge, "get_method_body", methodArguments(classNames[1], "touch"));
require(ordinary.get("mode").getAsString().equals("java") && ordinary.get("body").getAsString().contains("COUNT"),
"Ordinary executable method no longer produces Java");
SessionConfig bounded = new SessionConfig(96, 0, 90000L, 1, List.of(), List.of(), 64, ResourceMode.FULL);
BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
(scope, continuation) -> holder.unload(continuation));
BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
(scope, continuation) -> holder.load(apk.toString(), bounded, continuation));
JsonObject partial = call(handle, constructor.newInstance(holder), "get_method_body",
methodArguments(classNames[0], "<clinit>"));
require(partial.get("mode").getAsString().equals("smali")
&& partial.get("body").getAsString().contains("[truncated: exceeds 96 bytes, total "),
"Static initializer ignored the source byte limit or omitted its truncation marker");
String prefix = partial.get("body").getAsString().split("\n\n\\.\\.\\. \\[truncated:", 2)[0];
require(prefix.getBytes(StandardCharsets.UTF_8).length <= 96, "Initializer text exceeded its byte limit");
System.out.println("INITIALIZER_REGRESSION_PASS folded=2 bounded=true");
}
public static void main(String[] args) throws Exception {
SessionConfig config = new SessionConfig(1048576, 0, 90000L, 1, List.of(), List.of(), 64, ResourceMode.FULL);
SessionHolder holder = new SessionHolder(config);
@@ -89,6 +174,7 @@ public class ReaJadxMetadataRegression {
"Frozen summary changed after code generation");
require(apiSummary.equals(call(handle, bridge, "get_class_summary", apiArgs)), "Unrelated frozen summary changed");
System.out.println("METADATA_REGRESSION_PASS classes=" + states.size() + " overloads=" + signatures.size());
verifyInitializers(holder, config, constructor, handle, initializerFixture(args[1], args[2]));
} finally {
BuildersKt.runBlocking(EmptyCoroutineContext.INSTANCE,
(scope, continuation) -> holder.unload(continuation));
@@ -0,0 +1,25 @@
.class public abstract Lfixture/InitializationPolicy;
.super Ljava/lang/Object;
.field public static final POLICY:Ljava/util/List;
.method static constructor <clinit>()V
.registers 1
const-string v0, "declared-policy"
invoke-static {v0}, Ljava/util/Collections;->singletonList(Ljava/lang/Object;)Ljava/util/List;
move-result-object v0
sput-object v0, Lfixture/InitializationPolicy;->POLICY:Ljava/util/List;
return-void
.end method
.method public constructor <init>()V
.registers 1
invoke-direct {p0}, Ljava/lang/Object;-><init>()V
return-void
.end method
.method public abstract missing()V
.end method
.method public native originalNative()V
.end method
@@ -0,0 +1,21 @@
.class public Lfixture/MixedInitialization;
.super Ljava/lang/Object;
.field public static final LABEL:Ljava/lang/String;
.field public static COUNT:I
.method static constructor <clinit>()V
.registers 1
const-string v0, "field-value"
sput-object v0, Lfixture/MixedInitialization;->LABEL:Ljava/lang/String;
invoke-static {}, Lfixture/MixedInitialization;->touch()V
return-void
.end method
.method public static touch()V
.registers 1
sget v0, Lfixture/MixedInitialization;->COUNT:I
add-int/lit8 v0, v0, 0x1
sput v0, Lfixture/MixedInitialization;->COUNT:I
return-void
.end method
+17 -6
View File
@@ -45,11 +45,21 @@ def probe(path, socket_path, mode):
assert time.monotonic() < deadline, failures
time.sleep(0.005)
def connect():
client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
client.settimeout(2)
client.connect(socket_path)
return client, client.makefile("rwb")
def connect(wait_until_listening=False):
deadline = time.monotonic() + 2 if wait_until_listening else None
while True:
client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
client.settimeout(2)
try:
client.connect(socket_path)
except OSError as error:
client.close()
if (not isinstance(error, ConnectionRefusedError)
or deadline is None or time.monotonic() >= deadline):
raise
time.sleep(0.005)
else:
return client, client.makefile("rwb")
def send(file, method, token="owned-token", params=None):
file.write((json.dumps({"id": 1, "method": method, "token": token, "params": params or {}}) + "\n").encode())
@@ -63,7 +73,8 @@ def probe(path, socket_path, mode):
if "event" not in value:
return value
client, file = connect()
# bind() creates the socket path before listen() makes it connectable.
client, file = connect(wait_until_listening=True)
send(file, "health", "foreign-token" if mode == "unauthorized" else "owned-token")
if mode == "lost-reply":
assert entered.wait(2)