* fix(mcp): advertise object roots for union input schemas
Anthropic tool input schemas reject anyOf, oneOf, and allOf at the root.
Since 63bf9140 removed root flattening, compare_web_captures,
inspect_web_page, inspect_electron_page, and
project_managed_application_graph advertised root unions: Claude Desktop
disabled compare_web_captures and Claude Code exposed the tools without
parameters.
Present a root union of plain-reference object branches as one strict
object with the union of properties, shared required fields, a
minProperties bound, and a description of the accepted input groups. The
canonical Zod union still validates every call, so mixed input groups are
rejected before the handler runs. Branches whose reference siblings cannot
be merged keep their root alternatives.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(browser): keep comparison input boundary within lint limits
Express advertised and runtime expectations as one case table so the
boundary test stays under the 150-line function limit.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(mcp): preserve input group dependencies in object schemas
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
The dense jump-table oracles (inspect-native-api CLI and the
analyze_function dossier) ran against the -O0 debug fixture, which
assumes the host compiler lowers dense switches to tables at -O0. GCC 16
and later expand them as compare chains instead, so on those hosts the
lane rejected a correct provider and Ghidra build with empty
jump_tables.
Build the same inventory source once more at -O2 as a dedicated
jump-table variant, run both strict dense oracles there, and keep the
debug dossier at its complete generic shape. The dedicated switch lane
already compiles at -O2 for the same reason.
* fix(javascript): preserve uncertainty after references escape to calls
* fix(javascript): track iterator root escapes and preserve static captures
* fix(javascript): scope comparison unknowns to their evidence
* fix(javascript): track parameter origins at function body entry
---------
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
Select residual unknown histories as complete units and retain referenced registry mutation Evidence regardless of the active target at edit time. Prune incompatible dependency histories atomically instead of retaining stale dispositions.
Verify public MCP save/read/reopen for verified, withdrawn, and out-of-scope resolutions, and document target scope rules.
* fix(javascript): decline source-map UNC references with an unusable host
A source map can name a Windows share whose host a file URL cannot carry,
such as `\\bad host\share\a.js`. On the Node builds `engines` admits,
`pathToFileURL(path, { windows: true })` fails a native assertion and calls
`abort()` on Node 22.19-22.22, 24.11-24.15 and 26.0, so the process dies
with exit 134 instead of declining the reference. Node 22.23 and 24.16 raise
`ERR_INVALID_URL` instead, and older builds silently drop the host, so the
same reference resolves three different ways depending on the runtime.
Validate the UNC host before handing the path to Node. A host carrying a
forbidden host code point, a percent escape or nothing at all now resolves as
`unresolved` on every admitted build, and `npm test` passes the existing
`\\bad host\share\a.js` row everywhere. Well-formed UNC hosts and
drive-letter paths are untouched.
* fix(javascript): validate UNC hosts through IDNA before conversion
Reject Unicode source-map UNC hosts that URL/IDNA processing cannot use or normalizes to an empty hostname before calling Windows pathToFileURL. Keep the original source identity and preserve usable normalized hosts.
Exercise the built reference resolver in owned subprocesses, including U+00AD and U+200C as source names and source roots. The original PR implementation aborts under Node 22.22.2; the new regression isolates those signals from the test runner. Add this test to the existing Node 22 Windows CI step.
Validation: 64 focused tests pass on Node 22.22.2 and 24.18.0; npm run check and test discovery pass. Local verification ran on macOS; Windows verification remains with CI.
---------
Co-authored-by: Yi-111-a <yi-111-a@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
compareJavaScriptApplicationVersions built the change graph with
createJavaScriptApplicationGraph, which validates it and re-derives
every node, observation, edge and graph ID, then parsed the result
with a schema that embeds the full graph schema, repeating all of
that work. Seal the change graph with the owned immutable factory and
accept that exact sealed graph in the result parse, as owned analysis
results already do. Items, coverage and the public result schema are
unchanged; output is byte-identical.
Route ordinary CLI results through the bounded JSON writer after command registration, including managed member inspection. Remove JavaScript-specific output plumbing while preserving filters, envelopes, cancellation, and failure exits.
Measure formatted UTF-16 expansion before Incur token counting and return resource_constraint above the runtime string limit, with recovery guidance.
Validate output above the real V8 string limit by SHA-256 and exercise the compiled managed provider. Clean-worktree validation: npm run check; 76 focused tests passed, with 2 optional-provider skips; test discovery passed.
Fixes#1371.
Keep unknown element coverage on arrays whose length may have changed, preserving intrinsic length presence and subsequent slot mutations through semantic graph and export-return consumers.
Retain primitive and nested array types with typed paths, and compare only mutually observed body shapes while preserving selected coverage uncertainty. Return full untrusted WebMCP input declarations with canonical digests, without resolving references or invoking tools.
BREAKING CHANGE: JSON shape paths now contain typed property and array-element segments. WebMCP input_schema_shape is replaced by input_schema and input_schema_sha256, retaining declared examples and defaults.
Verify captured container bytes against their inventoried digest before listing or reading packed members. Isolate per-reader ASAR metadata, preserve original unpacked companions, and retain complete inventories when snapshot cleanup fails.
The real-Hopper navigation probe derived its interior coordinate as
anchor + 1, which assumes the fixture procedure's first instruction is
longer than one byte. Host toolchains without endbr64-style prologue
padding (Kali gcc 16, or any build with -fcf-protection=none) compile
rea_entry to start with the one-byte push rbp, so anchor + 1 is itself
an instruction boundary: goto_address correctly observes that boundary
and the boundary-contract run rejects a correct bridge.
Advance the probe to the first instruction followed by a coordinate gap
larger than one byte and derive the interior-coordinate assertions from
that instruction, so the probed coordinate is never an analyzed-object
boundary on either prologue encoding.
Share parser modes and collision-free composite keys, enforce architecture guards, and consolidate redundant unit assertions into filesystem, CLI, MCP, and producer-backed workflows. Preserve concurrent upstream boundary fixes and exclude legacy Objective-C class-name bookkeeping labels.
Validation: source/composition suites (3358 passing), focused canonical digest and MCP checks, typecheck/lint, Knip, formatting, architecture guards, and real Foundation archive and Apple legacy simulator CLI/MCP verification. No real Hopper, Ghidra, or IDA verification claim.
Preserve canonical distinct-source and unique-native-observation refinements after resolving inline or retained JavaScript workflow inputs. The shared application entry points now return structured invalid_request errors before graph parsing and computation, avoiding another complete graph capture.
Six focused tests, actual compiled CLI/SDK stdio workflows, JSON Schema dialect checks, static/document checks, and a real Notion ASAR analysis/recovery/trace/close workflow passed. All 20 final-head checks, including real JavaScript recovery, passed. Native-provider acceptance is not claimed for this provider-neutral validation change.
Fixes#1364
Refs #1065
Stream large CLI JSON files through a strict UTF-8 decoder and standard JSON parser using the same admitted regular-file handle. Preserve native parsing for small inputs, typed malformed-input/resource/access-denied errors, cancellation, and complete Evidence.
Verified with focused public CLI regressions, a 768 MB whitespace-padded valid request, and the Windows native decoder boundary. Individual strings and the assembled object graph remain subject to native runtime limits. All 27 final-head checks passed.
Refs #1331
Reject positively identified foreign-only Ghidra decompiler binaries and non-regular native prerequisites before provider startup, while retaining unknown classifications for incomplete or unrecognized headers.
Verified with 54 focused tests and real Linux Ghidra CLI/MCP admission, decompilation, cleanup, wrong-host PE rejection, and non-blocking FIFO rejection. All 19 final-head checks passed.
Fixes#1192
Co-authored-by: Dery Ferdika <114888155+DeryFerd@users.noreply.github.com>
Fixes#1338.
Use canonical product identity for bundled command versions and keep build-cache fixtures aligned. Verified 10 focused tests, actual CLI installation/repair/uninstall scenarios and all 19 final-head CI checks.
Co-authored-by: Yi-111-a <97448247+Yi-111-a@users.noreply.github.com>
BREAKING CHANGE: Filesystem digest omission entries now require system_code; budget and changed-file omissions use null, and unavailable-file omissions preserve the operating-system error code.
Reject omitted segment bounds, procedure classification and body facts, unresolved-call observations, dossier facets, and Ghidra parameter flow metadata. Providers emit explicit nulls for unsupported facets. Verify those unknowns in the real Hopper workflow.
BREAKING CHANGE: Provider analysis outputs must explicitly supply metadata previously repaired with defaults; unsupported nullable facets must be reported as null.
Intern shared provenance in a graph-scoped context registry while retaining exact locations on every fact. Semantic traces carry their referenced context subset, and portable graph validation rejects stale or dangling commitments.
BREAKING CHANGE: Semantic graph facts now store evidence context IDs and locations. Graph and semantic trace results require an inline evidence_contexts table.
BREAKING CHANGE: source-map URLs now live in target observations selected by declared_url_sha256, and doctor skill identity no longer emits installed_catalog_digest. Use the documented observation join and identity.skill.state instead.
The generated skill rewrote `rea-agents@latest` to the version it ships with, so a pinned install no longer needs a local edit that `doctor --skill` reports as stale.
Co-Authored-By: OpenCode <opencode@opencode.ai>
relationshipSignature rebuilt a node map and scanned every graph edge
for each side of each matched pair, so comparison cost grew as
pairs x (nodes + edges). Build node and adjacency indexes once per
graph in ItemContext; signatures, sorting and output are unchanged.
At 4000 matched modules, end-to-end compare: 5.7s -> 2.9s (2 edges
per node) and 10.4s -> 5.8s (6 edges per node); 8000: 3.3x and 2.5x.
Output JSON is byte-identical on the base commit.
Use the equivalent hex NUL spelling in named public contracts while preserving current path and reserved-name validation. Verify converted JSON Schema and real stdio catalog consumers.
Closes#1329
Co-authored-by: Yi-111-a <97448247+Yi-111-a@users.noreply.github.com>
Verify selected files through a nonblocking opened handle before reading. Preserve regular-file symlinks and return actionable CLI/MCP diagnostics without publishing output.
Co-authored-by: YouWish <29498139+Y0UW1SH@users.noreply.github.com>
list_architectures ran lipo on every admitted target. For a PE DLL, ELF
binary or plist, lipo's refusal surfaced as execution_failure with
"Retry once; if it continues, run rea doctor", which neither can fix.
Refuse non-Mach-O targets as capability_unavailable before running
lipo, as inspect_macho already does.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
The streamed JSON encoder delegated every token through one recursive
generator per nesting level and yielded each token separately. Writing
analyze-javascript-application output for Typora (873 MB) spent 22 of
66 s there. Encode with an explicit stack into bounded 16 KiB parts:
identical bytes, 3-6x faster encoding, and the same laziness, error
and surrogate-pair guarantees.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
BREAKING CHANGE: Objective-C attribute tokens now contain only name and value. Properties report nullable atomicity and readonly facts; class flags, ivar counts, and method requirement flags are nullable when unobserved.
After #1301 merged, main's duplicated-line share rose to 2.503%, over
jscpd's 2.5% threshold, so Static checks fail on every PR. The new OMP
test repeated the dialect test's imports and npx registration command.
Export that command from the shared client test fixture instead.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* feat(setup): register OMP during setup
Add OMP (oh-my-pi) as a setup, doctor and uninstall client. Setup writes
a type: stdio entry to the user-level agent mcp.json that OMP reads,
following PI_CONFIG_DIR, an absolute PI_CODING_AGENT_DIR and the
OMP_PROFILE/PI_PROFILE named profile. It removes rea from OMP's
disabledServers denylist, which would otherwise hide the registration,
and doctor reports a listed registration as stale.
Closes#1257
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(setup): honor OMP's enabledServers allowlist in doctor
OMP's user enabledServers allowlist forces an entry with enabled: false
on, unless disabledServers also lists it. Doctor reported such a working
registration as stale. Also format the FAQ client list.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(setup): keep OMP's allowlisted entry in update maintenance
rea update skipped an owned OMP entry with enabled: false even when
OMP's enabledServers allowlist runs it. Apply the same forced-enable rule
as doctor. Share the client-location environment reset across the client
tests instead of repeating it in each file.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Remove forwarding wrappers and shadow aliases, migrate callers and verification scripts to their owners, and share one exhaustive semantic resource-bound projection.
Require process retention accounting, browser network transaction identity, and all web comparison dimensions. Remove obsolete omission repairs and derive completeness from the owning producer facts.
BREAKING CHANGE: Historical captures without current producer accounting or transaction identity, and web diffs missing accessibility or storage dimensions, are rejected.
trace_dylib_resolution roots and capture_process_scenario environment
names still advertised negative look-ahead patterns. RE2 and Rust schema
validators reject look-around, so a client using one refuses the whole
tools request, as #1282 reported for the NUL escape. Spell both
constraints as equivalent look-around-free patterns and assert that no
advertised pattern uses look-around or backreferences.
Closes#1282
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both reported failures were fixed by 63bf9140, which moved kind and
executable facts from content nodes to occurrences, but neither
reproduction had a regression test. Pin the direct-file Mach-O root kind
and permission against its bundle occurrence, and the Apple JavaScript
component and runtime family next to byte-identical text resources.
Refs #1234
Refs #1235
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
\w is ASCII-only even with the u flag, so "port: 8080.β" was treated as
a sentence-ending port. Use Unicode letter and number classes for the
port boundary checks.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PTY chunks are normalized independently. A period that ends a chunk may
begin a decimal continued in the next chunk ("port: 80." then "5"), so
leave such a port unnormalized instead of masking the decimal.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#1287 removes URL tabs and newlines from an HTML script URL before
percent-decoding. A declaration such as %2<newline>fapp.js passed the
raw admission check and then decoded to a separator, resolving to a
file the encoded-separator rule must refuse. Apply canonical path
admission again to the parsed URL text.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The malformed process-choice acceptance test spawned 26 CLI processes one
after another. On CI it took 45-59 s against its 60 s deadline and timed
out on unrelated PRs. Run the independent cases concurrently, each with
its own scenario file; every assertion is unchanged.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
parseProcessCapture accepted terminal retention accounting that its
retained frames contradict: any retained_bytes within budget, and
observed_bytes above retained_bytes with no omitted frame. A malformed
capture could therefore report truncated: false while its terminal
evidence was incomplete. Recompute retained raw and rendered bytes from
the frames, and require equal observed and retained bytes when no frame
was omitted.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contextual port normalization refused any port followed by a period, so
common log lines such as "Listening on port: 8080." or
"http://localhost:8080." kept their run-specific port and equivalent
captures compared as changed. Accept a sentence-ending period while
still refusing a period that continues a decimal, version, or host name,
and bump the committed port-normalization version.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Since #1277 an MCP tool error carries no structuredContent, so the real
Ghidra address-boundary verifier threw a TypeError on its first expected
rejection and never checked the remaining representations or the
alias-preservation control. Assert that the error carries no structured
payload instead.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Since #1277 an error result reaches the client without structuredContent,
but toErrorToolResult and the transport recovery still budgeted it as
structured JSON plus escaped text. An error whose text fit between about
half and all of the response budget was replaced by resource_constraint,
and without Evidence retention the original diagnostic was lost.
Count only the escaped text for errors. The boundary, process-global and
real Ghidra large-result probes now use diagnostics that exceed the
text-only budget.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(mcp): deliver tool errors within advertised schema contracts
Retain complete typed JSON error content while omitting non-conforming
structured errors at the public transport boundary. Recover oversized
diagnostics into Evidence before removing their private structured carrier.
Update schema-validated client readers and cover actual stdio delivery.
Closes#1261
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
* test(mcp): read typed errors in canonical Evidence regressions
* test(mcp): validate public error diagnostics in acceptance workflows
An HTML script src or base href with percent-encoded letters or
surrounding whitespace was looked up literally, so an inventoried script
was reported as not-found. Apply HTML attribute and URL parser
whitespace handling, then percent-decode the path as the URL standard
does. Encoded dot and separator bytes are still rejected, and paths that
decode to NUL or non-UTF-8 bytes are rejected explicitly.
Closes#1236
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Document the Python preview environment, automatic sitemap updates, canonical URLs, generated sharing card and Search Console checks after publication. Apply the website's clear, concise writing standard to search and sharing metadata.
Prefer rea.tools in page canonicals and search listings. Generate the sitemap from current HTML indexing directives and render a shared PNG preview from SVG before verification and manual deployment.
Refs #1283
Ghidra validates every project path element with NamingUtilities.checkName and aborts the headless analyzer on any element starting with '.', so an inherited TMPDIR such as ~/.cache/<tool> failed every Ghidra operation with a generic analysis failure. Select the session root through a helper that prefers the inherited base, then a dot-free platform temp directory, then the nearest dot-free ancestor.
Support owned JADX stdio on Windows x64, preserve protocol input errors through cancellation, and verify native stdin and Android CLI/MCP lifecycle on the real Windows host.
Closes#1262
Remove getter, enum, cloned-projection, cache-identity, and obsolete profile assertions along with the shadow JSON Schema engine and dead test-only APIs. Retain producer, filesystem, SDK, lifecycle, integrity, and malformed-format coverage.
Document the priority of real end-to-end workflows, boundary integration, and producer goldens.
Retain complete typed JSON error content while omitting non-conforming
structured errors at the public transport boundary. Recover oversized
diagnostics into Evidence before removing their private structured carrier.
Update schema-validated client readers and cover actual stdio delivery.
Closes#1261
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
Compare complete function dossiers directly, remove unreachable truncation and collection wrappers, and preserve deterministic Unicode ordering. Require real external reference targets instead of display placeholders.
BREAKING CHANGE: function comparison results no longer advertise the unreachable truncated state or counter.
Use one explicit object/array slot model and JSON-pointer property identity across mutation analysis, return projection, and semantic graphs. Require observed presence for discriminants and resolve writes only through retained object or array receivers.
BREAKING CHANGE: projected return fields require explicit presence and semantic object operations carry full property paths.
Deliver complete Evidence directly through MCP with required nullable analysis profiles and immutable per-server delivery settings. Bind selected environments at construction and require typed cleanup outcomes with retained retry ownership.
Remove test-only routing, duplicate session and snapshot metadata, producer-field repairs, and ambiguous provider arguments. Separate artifact byte identity from occurrence classification and retain typed source-map and partial native facts across CLI, MCP, and verifier consumers.
BREAKING CHANGE: obsolete Evidence envelopes, session aliases, incomplete snapshots, and missing normalized producer facts are no longer accepted.
Remove v3 capture conversion and require explicit executable identity and event journals. Preserve cancellation, execution diagnostics, snapshots, and cleanup outcomes from preparation through CLI delivery.
Separate exhausted path enumeration from hash coverage and preserve known
effects outside incomplete roots or unfollowed symlink subtrees. Return
explicit unknown effects through capture Evidence and comparison workflows.
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
Propagate CLI interrupts to capture and interrupt post-exit settlement
without cancelling owned-resource cleanup or discarding prior observations.
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
* perf(hopper): resolve string search records once per query
search_strings called _string_inventory(document) once per match, and each
call sorts every string address and rebuilds the record dict, so a query cost
O(matches x strings log strings). Resolve the inventory once per search.
Warm search, 50% matches, fake document, best of 7: 1000 strings 186 -> 0.5 ms,
4000 strings 3161 -> 2.1 ms, 8000 strings 13121 -> 4.9 ms; output byte-identical.
* perf(hopper): skip record resolution for empty string searches
Resolving the full string inventory for a query with no matches added a sort
of every string address that the previous code never performed. Return early
when nothing matches. Zero-match search on a warm document, best of 7:
64000 strings 35.9 ms before this change, 4.0 ms after (main: 3.9 ms).
* fix(javascript): match source-map originals that name parent directories
* fix(javascript): resolve parent segments against the source map's directory
* fix(javascript): resolve source originals against their map location
* fix(javascript): preserve URI and empty source map path semantics
* fix(javascript): separate source URL paths from opaque URI payloads
* fix(javascript): preserve filesystem names during URI classification
* style(javascript): format source URI presence guard
* fix(javascript): resolve source map references with URL semantics
* fix(javascript): preserve literal UNC source map paths
---------
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
rea inspect-plist takes the target as its positional path and selects a
plist with --relative-path, so "Pass path" pointed CLI callers at the
wrong argument. Name the MCP path input and the CLI flag.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A CLI workflow given a JSON input file that cannot be read (missing, a
directory, or permission denied) returned invalid_request with
input_reason "read-failed" but no details. The remediation "Correct the
listed arguments and retry." therefore listed nothing, and the system
error that separates a typo from a permission denial was dropped.
Add an invalid_value issue naming the system error code and the path.
The envelope, code and input_reason are unchanged.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
inspect_plist on a target without a readable default Contents/Info.plist
(for example a bare Mach-O) reported the generic "This analysis is
unavailable for the current target. Choose another analysis or target."
as message and remediation. The specific reason, including "Pass path to
inspect another plist", appeared only in details.reason, although
selecting another plist in the same target is the available workflow.
Pass that reason as the refusal's user message.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An EvidenceFileError for a missing evidence file, a selected path that is
not a regular file, or an output that already exists projected code and
category execution_failure. The message already told the caller to
correct the path, but agents branching on code or category saw a tool
failure.
Project those three reasons as invalid_request with category
invalid_input. An unreadable file (io) and invalid JSON keep their
codes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The acceptance test uses a missing input path only to produce a streamed
JSON failure with a nonzero exit. The missing path is now an invalid
input_path rather than an artifact io failure.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Preserve NUL rejection while avoiding the short escape rejected by strict
schema consumers. Guard the entire advertised input/output catalog and all
three JavaScript regexp modes.
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
export_web_scripts reported a missing capture, a directory selected as
the capture, and an unreadable capture as an artifact io failure ("Script
export failed for <capture> -> <output>: ENOENT ..."), unlike its sibling
inspect_web_network_capture, which already reports these as invalid
input or access_denied.
Read the selected capture in its own step: ENOENT, ENOTDIR and EISDIR
become an invalid capture_path issue, and EACCES or EPERM becomes
access_denied. Failures while writing the export keep their existing
classification.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
analyze_javascript_application reported every input-selection problem as
an artifact fault:
- a missing input path: "Artifact could not be read or written", with no
path or reason;
- an unreadable selected directory: the same generic io failure;
- a regular file that is neither a directory nor an .asar, and a
--artifact-format that contradicts the selection: "Artifact is invalid
or has changed. Get a fresh copy and try again."
Report a missing path as an invalid input_path, an unreadable selection
as access_denied, a non-directory non-.asar file as unsupported_target
with the accepted inputs as remediation, and a contradicting format as an
invalid format with the observed kind as expected value. Failures inside
a selected artifact keep their existing classification.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* refactor(schemas): share identifier and canonical base64 patterns
* test: hold the offset datetime schema to the validator it replaces
The module documents that its accepted set matches z.string().datetime({ offset: true }), and nothing in the suite checked that claim. Adds table-driven accept and reject cases (leap years including the 1900/2000 century pair, month, day, hour and offset ranges, fractional and omitted seconds, missing offset, basic format) plus a differential assertion that classifies every case exactly as the replaced validator does, and asserts the emitted pattern compiles under u and v while the replaced pattern does not compile under v.
---------
Co-authored-by: felipeatp <felipe.troncosopt@gmail.com>
inspect_keyed_archive runs on every host, but its remediation for an
ordinary property list pointed to inspect_plist, which only macOS
supports. On Linux that sent callers to a workflow the capability layer
rejects.
The domain error now names what the file is. The artifact reader picks
the remediation from the provider's host: inspect_plist on macOS, and
elsewhere the selection of an NSKeyedArchiver archive, with a note that
inspect_plist requires macOS. decode_interface_builder, which is
portable, stays the NIBArchive remediation.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
inspect_keyed_archive reported a selected ordinary property list or a
compiled NIBArchive as a damaged artifact: "Artifact is invalid or has
changed. Get a fresh copy and try again." The file is intact; it is
another kind of file, and the workflow that reads it (inspect_plist or
decode_interface_builder) appeared only in details.detail.
Report a NIBArchive, or a plist whose $archiver is not NSKeyedArchiver,
as unsupported_target with that workflow as the remediation. An
NSKeyedArchiver archive that fails to decode stays a format failure.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Node's execFile timeout contract differs by supported runtime: Node 22
and 24 accept any non-negative integer (their timers clamp anything
above 2^31-1 to 1 ms), while Node 26 caps it at Number.MAX_SAFE_INTEGER.
Mirroring either left stoppable and plain commands disagreeing on one
runtime. Validate a safe non-negative integer before spawning in both
modes, so every supported runtime gives the same answer.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix: emit v-mode-compatible patterns for tool schemas
Character classes in emitted patterns carried unescaped '-', '/' and '['. Annex-B and u-mode accept them, so REA's own Zod validation (u) and every u-based validator never saw a defect, but v-mode rejects ClassSetSyntaxCharacters and Ruby rejects [^s[]]. With 6.1.0 tools/list, 117 pattern fields across 11 tools were rejected under v.
The characters are escaped as \x2d, \x2f, \x5b and \x5d rather than \-/\//\[, because oxlint --fix removes an escaped '-' inside a character class as a useless escape, so an escape-only change does not survive the pre-commit hook. \x2d-style escapes are valid under Annex B, u and v, are matched identically, and are not useless-escape candidates.
22 pattern literals in 18 files are touched; no other token changes.
* fix: replace the Zod offset pattern and guard the advertised catalog
The offset datetime site projected Zod's offset class as [ +- ], which no escape in this repository's sources can reach, so evaluate_reconstruction_coverage stayed unreachable for exactly the clients this change targets. It now uses offsetDateTimeSchema in src/domain/offsetDateTime.ts: the same accepted set with the offset class escaped as [ +\x2d ].
Adds tests/boundary/mcp/advertisedPatternsVMode.test.ts, which performs the real tools/list projection, traverses every advertised input and output schema, compiles each pattern under v, and asserts the inventory it walked so a silent traversal collapse fails instead of passing vacuously.
The version-mismatch reason ends with the tool's complete stderr, which
is too long for a caller-facing message. The message now names the
expected and reported version and exit code; details.reason keeps the
stderr.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Since a stoppable command keeps its own deadline, execFile no longer
validated its timeout. A negative, NaN, fractional or infinite value
then started the command with no deadline (or one setTimeout coerced)
instead of failing with ERR_OUT_OF_RANGE as execFile does.
Apply execFile's unsigned-integer contract before spawning.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The real-lipo slice test pinned the byte offsets and sizes of one macOS
release's /bin/ls, so it failed on any host whose /bin/ls differs
(macOS 26.7.1: x86_64 48128 bytes, arm64e 88672, versus the pinned 48112
and 89088). Read the expected layout from the binary's FAT header
instead.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Host and tool-configuration refusals from the pwntools, EVMole, firmware,
mitmproxy, Wakaru, LLDB and xcrun adapters carried no userMessage, so CLI
and MCP callers saw the generic "This analysis is unavailable for the
current target. Choose another analysis or target." as both message and
remediation. Choosing another target cannot satisfy a Linux-only profile
or an unset REA_*_COMMAND. The actual requirement appeared only in
details.reason.
Pass each refusal's reason as its userMessage, as the adapters' other
configuration refusals (EVMole limits, JADX, pwndbg) already do.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(ghidra): classify modern Swift manglings in swift type analysis
Categorize modern Swift 4.2+ manglings ($s, _$s) instead of dropping them
in analyze_swift_types. The classifier only accepted the legacy _Tt marker,
so procedure names reported by current providers produced an empty inventory.
Legacy _Tt families and behavior are unchanged. Fixes#1187.
* fix(swift): retain provider aliases and category unknowns
---------
Co-authored-by: Saim Shafique <sx4imm@gmail.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
The installation inspection rejected a relative JAVA_HOME, but only after
it had already probed `<JAVA_HOME>/bin/java` with spawnSync. `rea doctor`
and `rea setup` therefore ran whatever `jdk/bin/java` (or `bin/java` for
an empty JAVA_HOME) the current directory held, while reporting the
setting as rejected.
Skip the probe when JAVA_HOME is not absolute on the inspected platform.
The configuration check still reports the rejection.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
execFileOutput forwarded stopSignal only together with an AbortSignal, so
a caller with just a timeout (the native UI helper's swiftc build) still
got Node's SIGTERM. When the timeout did send the stop signal, nothing
killed a process that ignored it, and a process that exited cleanly
after the signal resolved as a success.
A stoppable command now owns its timeout: it sends the stop signal,
kills the process after the grace period, and rejects with ETIMEDOUT
and killed: true.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Move whole-graph commitment and batched integrity checks into owned domain steps while retaining eager input capture, canonical IDs, full validation and completion-only immutable proofs.
Verified complete real Notion identity parity and actual stdio MCP cancellation, Evidence retention and connection reuse.
Refs #1065.
Add explicit summary, facet, item and paged views of retained analysis Evidence without repeating analysis. Preserve captured observations, graph validation, artifact identity, coverage and complete default results.
Fixes#1050
Verified with focused source, CLI, pinned-SDK schema and MCP tests, serial static checks, and one complete native Windows Notion ASAR workflow. Real Hopper/Ghidra verification was not performed for this provider-independent projection change.
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
* fix: Handle relayed SIGINT gracefully in withProcessCancellation
Changes `process.once` to `process.on` for SIGINT in `DirectAnalysis.ts`.
When REA is launched via npx, a single process-group SIGINT triggers two
SIGINT events (one direct, one relayed). Previously, the first event would
consume the handler and the second would abruptly terminate the Node process,
abandoning Ghidra resource cleanup.
This change ensures subsequent SIGINTs idempotently request cancellation
without crashing the process, matching the behaviour of `withCommandCancellation`.
* fix(cli): keep termination guards through provider cleanup
* test(cli): exercise repeated analysis signals on macOS
---------
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
When removing Ghidra's private runtime directory failed, close_binary
reported only a generic `provider-client` resource, and a later close,
after the permission was restored, returned success while the directory
and its contents remained. The client dropped its reference to the root
before removing it, and PrivateRuntimeRoot cached the rejected removal.
Keep each runtime or socket root until its removal succeeds, report a
failure as a ProviderCleanupError naming the leftover paths, let
PrivateRuntimeRoot retry a failed removal, and pass such typed cleanup
failures through closeAnalysisClient instead of replacing them.
Fixes#1190
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A relative GHIDRA_INSTALL_DIR (or JAVA_HOME) that resolved from the current
directory passed doctor's Ghidra inspection, so doctor reported a healthy
provider and setup wrote the relative path into the MCP registration, but
REA's configuration parser rejects relative paths, so `providers`,
`capabilities` and the registered MCP server all failed.
The installation inspection's configuration check now applies the same
absolute-path rule, judged by the inspected platform's path syntax, and
names the relative setting. Doctor reports the provider unavailable with
that reason, and setup, which registers only an available inspection's
environment, no longer writes the path.
Fixes#1183
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An unsupported-target error always projected the generic "select a target"
remediation, which hid the adapter's available workflows (omit
REA_GHIDRA_NATIVEAOT_JAR for ordinary analysis, or use
inspect_managed_artifact). AnalysisUnsupportedTargetError accepts a
refusal-specific remediation, as AnalysisResourceConstraintError does, and
the NativeAOT refusal supplies its reason.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every configuration failure projected the same message, "REA configuration
is invalid. Run `rea doctor` and fix the reported setting.", with no
details. The environment parser discarded the issue that names the variable
(for example `REA_GHIDRA_NATIVEAOT_JAR must be absolute`), and doctor can
report healthy for that environment, so neither the CLI, the MCP startup
message, nor doctor told callers which setting to correct.
ConfigurationError now carries the rejected settings and their constraints
(never their values). The projection names them in its message, lists them
in `details.settings`, and asks the caller to correct those settings where
REA is started. Errors without a named setting keep the previous message.
Fixes#1184
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
resolveHopperMachOImage built its BinaryTargetError without the open
failure as its cause, so a target that became unreadable after admission
still projected as `target_unavailable` instead of `access_denied`.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With REA_GHIDRA_NATIVEAOT_JAR set on a host other than Linux, Ghidra
analysis was refused before Ghidra started, as intended, but the refusal
was a ProviderAdapterError: `execution_failure` with advice to retry and
run doctor, neither of which can change the host.
Adapters now say whether a refusal concerns the host or the target. A host
refusal is `capability_unavailable` whose message and remediation are the
adapter's reason (omit the JAR for ordinary analysis); a target refusal is
`unsupported_target` with the target path. Missing or malformed JARs on a
supported host remain provider failures.
Fixes#1185
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Opening a target the current user cannot read returned
`target_unavailable`, the same code as a missing target, although the
reason named EACCES. Clients that branch on the error code could not choose
read-access recovery, contrary to the boundary contract that separates host
permission denial from unavailable targets.
A BinaryTargetError whose cause is an OS EACCES or EPERM now records that
system code and projects as `access_denied` with `system_code`, the
filesystem-read boundary, and read-access remediation, while keeping its
specific reason and path. This covers target files, app bundle paths and
Info.plist reads, and selected plist reads, since every site passes the OS
error as the cause.
Fixes#1188
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Target admission accepted a thin Mach-O after reading only its magic and
CPU type, so a 12-byte prefix opened as a valid arm64 executable and the
first provider query failed as a generic execution failure. ELF headers
were likewise accepted after 20 bytes, and a FAT file whose selected slice
lies beyond its end was admitted.
Require the complete fixed header (Mach-O 28 or 32 bytes, ELF 52 or 64),
Mach-O load commands that fit in the file, and a selected FAT slice within
the file, checking commitments against the file size rather than the
probed prefix. Each refusal names the failed constraint.
Fixes#1189
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A selected package exports target names one file, and Node tries no
extension or directory index for it. REA still resolved it like a relative
specifier, so `exports: "./file"` with only `file.js` present, or
`"./folder"` with only `folder/index.js`, reported a resolved import that
Node rejects under both import and require.
Resolve an exports target only to its exact file and otherwise report
not-found with a limitation naming the target. Legacy main entries keep
their extension and index fallbacks.
Fixes#1174
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Cancelling the macOS process-ownership helper build left swiftc object files
in TMPDIR. Node's execFile sends SIGTERM on abort and rejects before the
child exits, and swift-driver runs each frontend job in its own process
group: on SIGTERM the driver exits while a job keeps writing, so REA removed
its root while objects were still being written outside and inside it.
Add an opt-in `stopSignal` to execFileOutput that stops the process with the
caller's signal on abort or timeout and settles only after it exits. Swift
helper builds stop swiftc with SIGINT, on which swift-driver stops its jobs
and deletes their objects, and point TMPDIR inside the root cleanup removes.
Fixes#1173
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`rea doctor`, documented as strictly read-only, ran
`brew --prefix --cask hopper-disassembler` when Hopper was not in a
standard location. Current Homebrew rejects that option combination, but
any brew command naming a cask first fetches the cask API, so each doctor
run wrote about 600 files (36 MB) into the user's Homebrew cache.
Ask brew only for its Caskroom, which brew answers without loading the
cask API, and read the application directory Homebrew recorded in the
Hopper cask's install receipt.
Fixes#1165
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
binary_session read the client's identity, protocol revision, and
capabilities only from the 2026-era per-request envelope. A 2025-era
connection sends none, so every such client was reported as `client: null`
with no negotiated protocol and no features, although it declared them in
`initialize`.
When a request carries no envelope, read the values the SDK keeps from the
connection's initialize handshake. An envelope still takes precedence.
Fixes#1167
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A configuration that passes the preflight can still fail when uninstall
rereads it to edit, for example when it changes concurrently. Rereading
keeps that edit from overwriting the newer file; stopping at the failure
keeps later clients, the skill, and REA data from being removed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Setup and uninstall rewrote the whole Codex config.toml with a fresh TOML
serializer, which dropped every comment and respelled unrelated values,
although the plan promises to preserve unrelated configuration. Grok Build
already edited only REA's server tables.
Share that table editor with Codex, without Grok's root
disabled_mcp_servers handling, keep the original final line break, and
fall back to the full rewrite only when the edited text would not parse to
the requested document.
Fixes#1163
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Incur derives `--schema`, the `--llms` manifests, and help synopses from
Zod's output view, where a defaulted field always has a value, so every
defaulted argument and option was listed as required even though the CLI
accepts its omission. Wrap each field that fills an omitted value as
optional after registration, keeping its default, constraints, metadata,
and parsed value.
Fixes#1169
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
The installation guide says malformed client configuration stops
`rea uninstall`, but uninstall reported that client as failed and still
removed other clients' registrations, the bundled skill, and with
--purge-data REA's cache and state.
Inspect every client configuration first, using the conditions setup
already treats as blocking (unsafe path, unreadable file, malformed
document), and stop before any removal when one fails. Purge paths that are
symbolic links are still retained and reported per item, as the guide now
states.
Fixes#1164
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
binary_session reported native and artifact operations available whenever
their provider declared them, although these operations run on the active
target: in a closed session every call failed with target_unavailable, and
Mach-O-only operations stayed available with a ZIP or ELF target open.
Report target_required for every session-bound contract kind in a closed
session, and target_unsupported for Mach-O-only operations unless the open
target is a Mach-O executable. A host limitation is reported before target
selection, since opening a target cannot fix it; composed operations keep
deciding from their requirements.
Fixes#1166
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Newer lipo names arm64e ABI variants `arm64e.<variant>`: `arm64e.v1` for
pointer-auth ABI version 1 on freshly built universal binaries, and
`arm64e.x1` on recent macOS system binaries such as /bin/ls. The
structural FAT parser names the same slice `arm64e`, so the exact name
comparison failed and inspect_artifact reported a valid, unmodified
universal binary as an integrity mismatch ("Artifact is invalid or has
changed").
Accept `arm64e.<variant>` for an `arm64e` FAT slice. Offset, size, CPU
type, subtype (including the pointer-auth version bits when lipo prints
them) and alignment are still compared field by field. The slice keeps
lipo's name in its logical path.
Fixes#1168
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Two follow-ups to #1161 from its post-merge review:
- The new format preflight ran before scanArtifactInventory, which was
the first cancellation check. An already-cancelled extraction of a
DMG or PKG therefore reported unsupported_target instead of
cancellation. Check the signal before the preflight.
- The unsupported-format and encrypted-entry refusals reported the
realpath. When the caller selected the target through a symlink,
junction, or other alias, the diagnostic named a different path.
Report the caller's input path; I/O still uses the canonical path.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
extract_artifact on a ZIP containing a password-protected entry failed
the whole extraction with "Artifact is invalid or has changed. Get a
fresh copy" and named only an opaque occurrence ID. The archive was
intact; REA does not decrypt entries, so complete extraction is
unsupported for this target.
Raise AnalysisUnsupportedTargetError naming the encrypted entry's path.
Other unextractable occurrences keep their format failure but now name
the logical path alongside the occurrence ID.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
extract_artifact on a format without an extraction reader, such as a
DMG, first ran the full inventory scan (mounting the image) and then
failed with an `unavailable` artifact failure: "Check artifact support
and required tools". The target format, not the host, is unsupported.
Check the format before any inventory or output work and raise
AnalysisUnsupportedTargetError, which the provider now keeps, as it does
for the other target-kind checks in this PR.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Outside Darwin the session reports inspect_asset_catalog as unavailable
on the host before the provider checks the target kind, so the Linux
test shards would see capability_unavailable rather than
unsupported_target.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
decode_interface_builder, inspect_asset_catalog, inspect_keyed_archive
and trace_dylib_resolution refused a target of the wrong kind (for
example a plain Mach-O for the asset catalog, or a plist for dyld
tracing) as an `unavailable` artifact failure: "Artifact processing is
unavailable for the current target or host. Check artifact support and
required tools." Nothing was missing on the host; the operation does not
support that kind of target.
Raise AnalysisUnsupportedTargetError for these checks and let
translateFailure keep it. The result is now `unsupported_target`, naming
the operation, the target path and the requirement, with advice to pick
a supported target or another operation.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
trace_dylib_resolution blamed the artifact for the caller's root
selection. A missing root, a directory, or a symlink leading outside the
bundle got "Artifact contains an unsafe or conflicting internal path ...
correct the artifact". A non-Mach-O file such as Contents/Info.plist got
"Artifact is invalid or has changed. Get a fresh copy". Any schema
failure, including a bad architecture, was reported as "roots must be
normalized paths".
Report a caller-selected root that cannot be traced as an
invalid_request issue on roots[i] with the failed constraint, and
project schema failures through their real issues. The normalized-path
rule now carries a readable message. Roots REA derives itself (bundle
executables or the active target) keep reporting artifact failures.
This matches what #1070 did for inspect_keyed_archive.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(javascript): omit self-referential static references with disclosure
A bundled module that requires its own key (`r(50)` inside webpack
module 50) resolved, through the static-reference composer, to its own
module node. The resulting self-referential imports edge failed result
validation and lost the entire analysis ("Result schema rejected 1
issue ... (custom)"). This is the same invariant as #1146; #1152 fixed
the bundler async-chunk composer, and this is the remaining adjacent
composer.
Skip a reference whose resolved target is its own source, count it, and
disclose the omission the way #1152 discloses async-chunk references.
Sibling requires are kept.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* refactor(javascript): share the self-reference omission disclosure
The self-import (#1130), async-chunk (#1152) and static-reference
disclosures repeated one sentence template in three composers, and the
new test repeated the analyze-and-check sequence of its neighbour. That
put jscpd at its 2.5% threshold. Share the template through
selfReferenceOmissions with identical wording, and share one test helper
for the graph-wide self-reference invariants.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(artifacts): recheck failed DMG detaches before reporting cleanup failure
NativeDmgArtifactReader.close() detached each device once and, when a
detach failed, asked `hdiutil info` once whether the device was still
attached. On APFS images, detaching the synthesized container ejects the
image disk too. `hdiutil info` can still list that ejected device
briefly, and a just-read volume can report busy. Either way a real
cleanup succeeded but close() reported "DMG detach or mount-root cleanup
failed" and kept the mount root.
macOS CI hit this intermittently in verify:macos-bundle: `hdiutil
detach /dev/disk23` failed with "No such file or directory" (already
ejected) and the device was still counted as attached. The #1103
review also raised the missing recheck.
After the first pass, recheck the remaining devices up to three times
with 250/500/1000 ms settle delays. Drop any that hdiutil no longer
lists, retry the detach of any still listed, and fail only for devices
that stay attached. The host seam gains an optional delay so tests run
without real waits.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(artifacts): share DMG detach fixtures to stay under the duplication gate
The new busy-device and recheck cases copied the fake hdiutil host and
the APFS close sequence from neighbouring tests, which pushed jscpd to
its 2.5% threshold in Static checks. Share one single-device host
between the busy and retained-attachment cases and one APFS close
helper between the ejected-device cases.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
`rea analyze PATH` routes a JavaScript directory or ASAR to the same
static analysis as `rea analyze-javascript-application`, but it passed
no signal and was not wrapped in withCommandCancellation. On SIGINT the
process was killed with no output (signal SIGINT, empty stdout).
The dedicated command returns a typed `cancelled` result and exits 130.
The #1098 review raised this route.
Decide the route first. A JavaScript target now runs exactly like the
dedicated command: cancellation wraps logging, so the cancelled exit
code is not replaced by the logged failure status. The binary route is
unchanged and keeps its own SIGINT handling in runDirectAnalysis.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Adds README_fr.md, translated from the current English README with the
same commands, links, heading structure and FAQ entries. Links Français
from every README language selector and registers it in the README
consistency matrix.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Recognize exit code 134 without a signal when the HAR decoder reports
V8 heap exhaustion. Preserve the observed termination in the memory
failure and cover Windows, POSIX, and unrelated decoder failures.
Commit 5ac3dc96 re-added application workflow scenarios under tests/acceptance/applications that are already covered under tests/boundary (mcp, filesystem, process) via the shared tests/fixtures/applicationMcpHarness.js fixture, per the boundary classification in 0e0b386d. The duplicates added no new coverage and pushed the jscpd duplication gate over its 2.5% threshold, failing CI static checks.
Parses rea mcp doctor arguments against one zod option schema that is also the help renderer's source of truth, answering --help/-h in any position without starting a diagnostic session and keeping actionable errors for unknown options and invalid formats. Updates the landed help assertion to the schema-rendered format list and adds boundary coverage for help positioning and --format edge cases.
Adds an owned in-memory MCP harness plus acceptance coverage for trace/compare/export-shape workflows over inline and recorded Evidence, including rejection of mismatched evidence references and spoofed providers. All 16 scenarios pass on the current base.
* feat(ghidra): make the startup deadline configurable
Large binaries (an 8 MB PE with about 20,000 functions) need more than the
fixed 330 s for import and full auto-analysis, so every first request timed
out. REA_GHIDRA_STARTUP_TIMEOUT_MS overrides the deadline in milliseconds;
absent, empty or invalid values keep the 330 s default.
* docs(ghidra): document REA_GHIDRA_STARTUP_TIMEOUT_MS
* fix(ghidra): parse startup deadlines through runtime configuration
---------
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
Integrate the numeric precision correction from #1135 with complete supplemental
metadata handling. Keep decoded numbers with an explicit limitation for mixed XML
content or unclassified integer text, rather than assigning another literal's
exact decimal. Project nonnumeric UID and CF$UID dictionary values recursively
while preserving numeric references, graph identity and original byte digests.
Add filesystem, built CLI and MCP regressions for the review findings, adjacent
XML representations and numeric reference controls. Retain the original native
Foundation qualification fixtures and verifier.
Verification: 84 focused tests; npm run check; npm run docs:check;
npm run verify:test-discovery; npm run verify:keyed-archive (real Foundation,
CLI and stdio MCP). No real Hopper or Ghidra verification was needed or run.
Co-authored-by: Rudy Mizrahi Celekli <47457359+rudycelekli@users.noreply.github.com>
Signed-off-by: morluto <76467478+morluto@users.noreply.github.com>
* fix(javascript): omit self-referential import edges with disclosure
A specifier that resolves back to the importing module itself produced an
imports edge from a module to itself, which the application graph schema
forbids; one such specifier failed result validation and lost the whole
analysis. Skip those edges at composition time and disclose the omission
count in the graph limitations.
Fixes#1129
* test(javascript): verify self-import behavior through the compiled CLI
---------
Co-authored-by: BaaRai <baarai@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
* test(browser): pin DOM and source-map URL policy classifications
Cover the unsupported DOM scope, credentialed destinations, and the source-map fetcher's pre-request filtering of credentials, other origins and non-http(s) URLs, so a later vocabulary unification can show exactly what changes.
Refs #829
* test(browser): assert exact sanitized credentialed DOM URL
---------
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
* fix(hopper): enforce caller-supplied request deadlines
* fix(hopper): correct idle deadline state and name timeout bound
Zero-ms deadlines never enter the FIFO, so report providerState
not_started instead of busy; the busy wording tells callers to wait
for an active request that does not exist. Name the Node timer
ceiling once and reuse it in validation and the error message.
* fix(hopper): enforce elapsed deadlines before dispatch and replies
* fix(hopper): distinguish unsent requests in timeout diagnostics
* test(hopper): exercise request deadlines against native Hopper
---------
Co-authored-by: Vilmer Frost <frost.vilmer@gmail.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
* fix(hopper): preserve owned basic-block endpoint instructions
* test(hopper): share probe runner and restore fixture hashability
Reuse one probe helper with the facade test's execFile options
(encoding, timeout, maxBuffer) instead of repeating the invocation.
Give the fixture Block a hash consistent with its equality so the
equality-based ownership doubles stay hashable.
* fix(hopper): align owned instruction walks with normalized block ranges
---------
Co-authored-by: Vilmer Frost <frost.vilmer@gmail.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
Adds README_fa.md (Persian/Farsi) contributed via PR #1140, keeps onboarding commands, links, and structure aligned with English, links فارسی from every translated selector, and registers fa in the readme consistency matrix.
Co-authored-by: Arad Ashkan <65897590+AradAshkan@users.noreply.github.com>
* fix(setup): treat empty client config files as new documents
An empty MCP config file (for example Antigravity's mcp_config.json, which
the client can create with zero bytes) was reported as malformed, which
blocked rea setup from configuring every other detected agent. Parse a
whitespace- or BOM-only JSON/JSONC file as an empty document and write a
fresh document over it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(setup): use explicit unicode escape for BOM-only empty config case
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
* fix(update): accept npm 12 release metadata
(cherry picked from commit aa400d18c9)
* fix(update): classify npm release metadata without a spawn mock
Keep the npm 11 string and npm 12 one-element array accepted by the
cherry-picked lookup, and separate invalid metadata from a failed
registry command.
---------
Co-authored-by: Dapo Olaomo <penielgold@gmail.com>
Read source digests, FAT tables and embedded headers from one opened source stream before translating native offsets. Preserve native mapping observations through changed, missing, nonregular and access-denied source failures; keep filesystem work outside the Hopper API thread.
Exercise source drift, relocated slices, missing files, permissions and recovery through real Hopper CLI/MCP verification for thin, FAT32 and FAT64 inputs.
* feat(clients): register Grok Build and Grok Bot during setup
Detect both clients and install the local REA MCP registration the same
way setup already handles the other agents. Grok Build edits only the
REA tables in its TOML config and sets startup_timeout_sec to 30. Grok
Bot writes the mcpServers.rea entry into mcp.json. That file is the
registration to add to the signed-in account; setup does not call the
account API.
Filed by Grok.
* fix(clients): clear a disabled Grok Build registration during setup
Grok Build keeps a server suppressed when its name stays in
disabled_mcp_servers, and setup was treating that file as already aligned.
Setup now removes only that name, doctor reports the registration stale until
it is gone, and uninstall keeps comments in an inline table whose only server
was REA. Split the lifecycle suite and reflow the get-started page so static
checks pass.
* fix(verify): check packed Hopper search as literal-only
The package verifier still called a regex probe that main deleted. The
native bridge refuses regex and joins string hits with typed records, so
the restored probe stubs that inventory and the check asserts the literal
matches and the regex refusal. The new README translations also name
Grok Build and Grok Bot.
* fix(clients): stop treating a Grok Bot data directory as registered
Grok Bot stores connectors in the signed-in account and runs them on its
hosted computer. Setup no longer writes mcp.json or reports that file as
aligned. Doctor and setup tell the caller to add the server from the
Grok Bot chat.
* fix(clients): drop multiline Grok disable-list entries
Decode disabled_mcp_servers strings with the document parser so a
multiline basic or literal string that loads as rea is removed.
---------
Co-authored-by: Grok <eugene.ray@gmail.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <morluto@users.noreply.github.com>
Collect references from the complete owned function body and exact entry,
including instruction-interior destinations and embedded-data sources.
Bind the corrected semantics to the analysis profile so legacy snapshots
cannot replay incomplete results. Preserve snapshot mismatch reasons and
recovery advice through CLI and MCP without disturbing live sessions.
Return exact entry candidates for ambiguous function names. Expand the
real-provider regression workflow and replace redundant parser assertions
with malformed-output coverage through the pinned MCP client.
Verified with Ghidra 12.1.4 on macOS arm64: full host-native lane, real
CLI/MCP boundary probes, 30 focused tests, and typecheck/lint.
Validate native annotation text before mutation and escape surrogate code units in Java bridge JSON replies. Reject unsupported text with field and index diagnostics while preserving supported Unicode and line endings.
Probe real CLI/MCP annotation, transport, mapping, rollback and cleanup behavior; replace seven redundant unit tests with E2E and SDK boundary coverage.
Preserve boundary diagnostics, resolve procedure names before bare hex addresses, and launch the inspected JVM directly on macOS for verifiable startup cancellation. Keep private socket paths within host limits and retain ownership when cleanup is incomplete.
Exercise the fixes through real CLI/MCP Ghidra workflows and provider-boundary integration tests, replacing redundant unit coverage.
Preserve native document identity, nullable bookmark labels, address diagnostics, segment-end byte prefixes, and verified file mappings. Validate batch rename addresses before mutation.
BREAKING CHANGE: remove set_current_document. Use open_binary to switch targets; document arguments are scoped to the active target.
* test(browser): verify native nested source-map coordinates
Qualify valid compiler-produced nested index maps through actual owned Chrome and the built public analyze-web-bundle CLI. Preserve same-line and zero-column controls, physical UTF-16 mapping positions and the independently correct dedicated decoder control. No production or workflow changes.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
* test(browser): retain native source-map failure receipts
Serialize the already-created phase and proof fields for failed native source-map owners. Preserve all producer inputs, scenarios, commands and assertions; first native two-failure/two-control evidence remains unchanged.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
* test(browser): preserve nested source-map boundary contracts
Qualify ordinary maps, nested offsets, sibling clipping, parent gaps, empty sections and deeper composition against the actual browser fetcher. Compare the existing dedicated decoder only for its valid non-overlapping profile. Preserve the four frozen compiler/Chrome/public CLI scenarios.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
* fix(browser): compose nested source-map column offsets
Normalize indexed sections to absolute leaf offsets before upstream flattening. Apply enclosing column offsets only for same-line child sections and retain parent clipping boundaries for gaps and empty sections. Preserve raw map evidence, source identities, transport budgets and the dedicated decoder profile.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
---------
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
* test(javascript): reproduce TypeScript source dialect loss
Add native directory/ASAR and built public CLI owners with actual locked native TypeScript syntax/emit and independent Babel source-range oracles. Production and every workflow remain unchanged.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
* test(javascript): admit isolated native compiler inputs
Use the actual TypeScript7 producer-requested --ignoreConfig flag when supplying isolated source filenames. Preserve every graph input, owning assertion, control and production file.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
* fix(javascript): parse plain TypeScript artifacts without JSX
Select the plain .ts dialect using the artifact source path so valid angle-bracket assertions retain syntax-derived graph facts. Preserve existing JSX defaults and all other dialects. Document the inert artifact parser contract.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
---------
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
An empty script_id also marks a script-type initiator, such as a module
import, whose url is the importing script file. Its position is a real
script position without a session-script association. The previous
wording called every empty-ID callsite parser markup with "no script
position" and excluded it from the external-script conversion. Describe
the empty ID as a missing session-script association, which only rules
out joining captured source or resource_start, and keep the
external-script conversion for script-file positions.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
observe_web_execution also derives callsites from a request's reported
initiator, such as an image the parser found in HTML or a module import,
with an empty script_id. Those positions point into the initiating
resource, not a script, so the "script's enclosing resource" wording and
source-map conversion did not apply to them. Describe the coordinates as
relative to the resource named by url, explain empty script IDs, and
limit the documented conversion to positions with a script_id.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* test(javascript): reproduce omitted NodeNext artifact sources
Tests only: qualify current .mts/.cts artifact selection through real directory and ASAR reconstruction and the built public CLI.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
* fix(javascript): retain NodeNext artifact source facts
Read .mts and .cts artifact files through the existing inert TypeScript parser, preserving selected file identities and analysis facts in directory and ASAR inputs. Document source selection and format the existing regression assertion.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
---------
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
* fix(hopper): diagnose MCP provider failures with stage, state, and request context
* fix(hopper): retain health at the actual provider lifecycle boundary
* test(hopper): distinguish socket loss from later observed process exit
* test(hopper): cover observed exit separately from socket-first replies
---------
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
compareCodePoints documented a Unicode code-point comparison but used
</> operators, which compare UTF-16 code units. For astral code points
(above U+FFFF) the lead surrogate 0xD800-0xDBFF is numerically below the
BMP tail U+E000-U+FFFF, so those characters sorted before it.
Delegate to the existing compareUnicodeCodePoints, which the domain
already uses elsewhere, so the two canonical comparators agree. All call
sites use only the sign, so sort and '< 0' checks are unaffected.
Adds the missing regression coverage for canonicalOrdering.
Co-authored-by: TahsinArafat <TahsinArafat@users.noreply.github.com>
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
* fix(browser): advertise zero-based units for runtime source coordinates
inspect_web_event_listeners and observe_web_execution return CDP
callsite, listener and resource_start line_number/column_number values
unchanged: zero-based lines and UTF-16 columns. Neither the advertised
output schema nor docs/web-runtime.md said so. trace_web_source_location
takes one-based lines, so a caller chaining a listener location into it
lands one line early.
Describe the units on the shared schema fields, which reach both tools'
advertised output schemas, and document the conversion.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(browser): describe runtime positions relative to the enclosing resource
For an inline <script>, CDP reports listener and callsite positions
relative to the HTML document, and resource_start is where the script
text starts in that document. A real headless Chromium 155 page showed
this: a listener on HTML line 6 came back as line_number 5, with
resource_start {3, 8}. Describe all positions as relative to the
enclosing resource. Document that inline-script positions must have
resource_start subtracted, plus one added to the line, before
trace_web_source_location.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(browser): clarify runtime-to-source coordinate conversion
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
* test(javascript): reproduce HTML carriage return source coordinates
Compare actual resolved and unresolved artifact graph evidence with parse5 source locations across HTML line terminators and UTF-16 columns. Exercise both public built CLI analysis commands. Tests only; production and workflows unchanged.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
* fix(javascript): preserve HTML carriage return source ranges
Treat LF, CRLF, and bare CR as HTML line endings when projecting actual script opening-tag offsets to retained source ranges. Preserve UTF-16 column semantics and document the source-coordinate contract.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
---------
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
* fix(artifacts): guard Windows device 0 in directory open integrity check
On Windows, Node.js fs.lstat reports dev as 0 without opening a handle. When DirectoryArtifactReader.open inspects the opened handle using handle.stat(), stat.dev is populated with the volume serial number.
Consequently, the TOCTOU check observed.dev !== entry.sourceIdentity.device evaluated to true on Windows for every regular file, throwing an ArtifactReaderFailure integrity error.
Relax the device comparison when running on Windows or when the inventoried device is 0, while maintaining strict inode verification to ensure the target has not been replaced.
* test(artifacts): verify native directory identity without device bypasses
---------
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
* test(javascript): reproduce BOM source range drift
Compare original UTF-8 source bytes and their retained digests with direct Babel and parse5 source-location oracles through actual directory and ASAR artifact reconstruction and both built public CLI analysis commands. Preserve no-BOM, structured-BOM and invalid UTF-8 controls. Tests only; production and workflows unchanged.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
* fix(javascript): preserve original BOM source coordinates
Retain the initial UTF-8 BOM for JavaScript and HTML source text so graph ranges refer to the original digest-bound bytes. Preserve structured-text BOM handling and fatal UTF-8 decoding.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
* style(javascript): format BOM decoder option
Apply the locked Oxfmt line wrapping to the approved decoder option; no behavior or test changes.
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
---------
Signed-off-by: Rudy Celekli <rudy@gradiahq.com>
* fix(process): name the reason two captures cannot be compared
compare-process-captures rejected captures whose comparison contracts
differ, but the reason never reached the caller. The CLI printed
"Process command could not complete... run `rea doctor`". MCP wrapped
the error in an AnalysisInputError with no issues ("Analysis input is
invalid. Check the arguments"). A stale capture under
max_capture_age_ms got the same treatment.
Throw typed input issues that name the differing contract fields, or
the stale side with its completion time and age, and let
runDerivedOperation pass AnalysisInputError through unchanged. Document
what the comparison contract covers.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(process): report CLI trace-spec issues under the MCP input path
The CLI reported an invalid trace specification under operation
"compare-process-captures" with root-relative issue paths such as
["events"]. MCP reports the same input as compare_process_captures with
paths under trace_spec. Use the canonical operation name and prefix
trace_spec so both surfaces describe the same input identically.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(process): name the side and constraint for unusable capture Evidence
Adjacent compare_process_captures failures still lost their reason.
Over MCP, Evidence from another workflow, tampered Evidence and an
invalid capture result all became "Evidence is invalid or has changed".
The CLI said only "Capture evidence is malformed".
Parse each side separately. Evidence from another workflow is an input
issue on left or right that names the operation and predicate it has.
Tampered Evidence and invalid capture results stay integrity
mismatches, and their message now carries the validation detail.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* fix(managed): keep caller-input details in managed workflow errors
The managed workflows wrapped every rejected input as
`new AnalysisInputError(op, { cause })` with no issues. The projected
result said "Correct the listed arguments and retry" and listed nothing:
- `rea import-managed-reconstruction`,
`rea project-managed-application-graph` and
`rea verify-managed-native-boundaries` lost every schema issue for
malformed JSON;
- domain checks such as a reconstruction text hash mismatch, or Evidence
from the wrong operation, lost their message on CLI and MCP;
- `rea compare-managed-members` with a missing file did not say which
path failed.
Add managedInputError, which projects Zod issues with their paths and
keeps a domain TypeError's message, as the JavaScript workflows already
do. Return the BinaryTargetError from an unopenable comparison path
unchanged, with details.path, as every other path-based command does.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(managed): keep nested Evidence schema issues off request paths
A ZodError raised after the request parsed comes from a nested
Evidence result, so its issue paths are relative to that result.
Projecting it against the whole request reported, for example,
artifact.sha256 as a missing request field. Keep request-relative
projection for the raw request's schema failures. Report nested schema
failures as root issues whose message names the nested location.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(managed): type the malformed nested Evidence fixture
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(workflows): keep input details in the remaining workflow services
Inventory projection (project_android_application_graph and
project_apple_application_graph), build_reconstruction_obligation_ledger
and evaluate_reconstruction_coverage had the same issue-less
`AnalysisInputError({ cause })` as the managed services. For example,
evaluating coverage for an unknown boundary returned "Correct the listed
arguments" with no issues, dropping "Unknown reconstruction boundary: X"
on CLI and MCP.
Move the helpers to src/application/workflowInputError.ts and use them
for these services: requestInputError for raw request schema failures,
workflowInputError for nested schema and domain constraint failures.
Classification is unchanged.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Retain complete authenticated application Evidence when the repeated MCP representation exceeds the default receive frame or Node string limit. Return a typed transport constraint, keep useful followup queries available, and stream full canonical bundles to atomic destinations.
Verify complete Notion and Obsidian workflows on Linux and native Windows, full CLI/Evidence parity, and real large Chrome screenshot recovery. Preserve complete success contracts and caller-selected evidence paths.
Refs #1065, #1053.
Restore ignored generated inputs before deterministic test shards consume the downloaded build. Preserve verified cleanup assertions and explicitly check residual unknowns for unrelated processes.
A malformed bundle that merely has an evidence_id field was described
as one Evidence record. Use the single-record message only when the
input matches the Evidence record schema; otherwise report the bundle
schema failure.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reading a nonexistent Evidence bundle or snapshot, or exporting into a
directory that does not exist, failed as reason "io" with "Evidence
file could not be accessed. Check file permissions", and with no path.
In `rea compare` the caller could not tell which of the two files
failed.
Map ENOENT and ENOTDIR to a new "missing" reason with read- and
write-specific advice. Every EvidenceFileError now carries the resolved
caller path in its projected details. Permission and other I/O failures
keep the existing advice.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(process): stop failing captures on tokens macOS cannot expose
On a busy macOS 26 host the residual process sweep fails every capture:
KERN_PROCARGS2 omits the environment of Apple platform binaries for any
caller and fails with EINVAL for processes owned by another account, so an
unrelated process created after the capture baseline escalates to a hard
cleanup failure with cleanup_incomplete.
Report environment withholding distinctly from the Darwin token reader by
reading the platform-binary flag through csops, carry the effective uid in
the process table, and re-read unresolved tokens with a bounded retry plus a
final liveness confirmation so transient exec and exit states settle.
Candidates whose token the OS provably withholds, foreign-uid candidates,
and candidates that exited during validation are now recorded as unverified
processes instead of failing an otherwise clean capture or being signaled.
Related candidates and every other unreadable candidate stay fail-closed.
* test(process): align ownership lanes with the uid-aware process table
The Darwin sweep reads the effective uid through ps, so the offline
verification lanes' syscall allowlists must accept the new argv in
verify-binary-layout and verify-evm-interface. The foreign-uid ownership
test requires POSIX process uids; skip it where the platform has none
(the curated Windows lane).
* fix(verify): recognize UID-bearing ownership process tables
---------
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
evidence-import, evidence-export, compare and the MCP bundle tools gave
every rejected file the same message: "Evidence is invalid or has
changed. Recreate or re-import it". That included a single Evidence
record, which is what every command prints, so `rea compare a.json
b.json` on two command results looked like tampering.
Report a single record as such and point to export_evidence_bundle.
Locate the first schema issue, and keep thrown constraint messages such
as a semantic identifier mismatch. EvidenceIntegrityError now accepts
the userMessage option that other typed errors already use.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A symlink or directory named Assets.car is skipped by the
non-following directory reader. When no regular catalog remains, fail
with the skipped paths instead of reporting an empty inventory. When
catalogs were read, list the skipped entries in the limitations. The
absence limitation now says that symlinks are not followed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
inspect_asset_catalog failed with an "unavailable" artifact error for an
app bundle that has no compiled Assets.car. Its advice was "Check
artifact support and required tools", which does not apply: assetutil
was present, and the absence of a catalog is itself an observation.
decode_interface_builder already returns an empty graph for an app
without NIBs.
Return the empty page with an explicit limitation. Interface Builder
resource keys are still decoded and reported as unmatched.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
inspect_keyed_archive reported caller selection failures as artifact
faults. A missing named root became "Artifact is invalid or has changed.
Get a fresh copy" and lost its reason, and a missing, non-canonical, or
directory archive path became "unsafe or conflicting internal path ...
correct the artifact".
Report these as invalid_request issues on `path` or `root`, listing the
available $top roots or the active plist basename. Decode failures keep
the decoder's reason, and a compiled NIBArchive points to
decode_interface_builder.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(domain): preserve prototype-named JSON members through Evidence boundaries
Zod's z.json() record projection drops own __proto__ members as a
prototype-pollution guard, so provider replies carrying them lost evidence
before hashing/serialization and CLI/MCP output. The shared schema now
validates with z.json() as before, then rebuilds the value keeping
prototype-named own members as ordinary data properties (__proto__ via
Object.defineProperty, so the prototype is never mutated).
parseHarJson no longer rejects __proto__ members; the explicit unsupported
case from #992 is replaced with a preservation regression, and the
inspect_web_network_capture contract text is updated to match.
Fixes#1036
* fix(domain): bound JSON depth and oversized payloads at parsing boundaries
jsonValueSchema re-walked hostile input through z.json()'s recursive core, so a deeply nested payload from an MCP tool argument, inline evidence, provider result, or keyed archive threw RangeError: Maximum call stack size exceeded instead of a validation issue. The schema now runs an iterative depth guard first and keeps z.json() for full JSON semantics behind it, which also turns cyclic values into validation errors. The 1000-edge limit stays far below the range where the recursive core overflows its stack (measured between 2000 and 3000 on Node 24) while leaving room for legitimately deep target-derived trees such as compiled NIB view hierarchies, and the guard narrows with a typed record check instead of any or unchecked casts. The non-recursive JSON Schema advertisement stays intact on both the public and standard projection paths. Two payload sizes get explicit budgets tied to their producer constraints: web text artifacts reject beyond the 16 MiB source budget the web tooling already advertises, and native UI screenshot base64 beyond the 64 MiB helper output budget. Regenerated product catalog, skill catalog digest, and completion-ledger manifest follow the schema-boundary change.
* fix(validation): preserve depth diagnostics across process inputs
---------
Co-authored-by: DeryFerd <deryferdikao125@gmail.com>
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
* fix(domain): bound JSON depth and oversized payloads at parsing boundaries
jsonValueSchema re-walked hostile input through z.json()'s recursive core, so a deeply nested payload from an MCP tool argument, inline evidence, provider result, or keyed archive threw RangeError: Maximum call stack size exceeded instead of a validation issue. The schema now runs an iterative depth guard first and keeps z.json() for full JSON semantics behind it, which also turns cyclic values into validation errors. The 1000-edge limit stays far below the range where the recursive core overflows its stack (measured between 2000 and 3000 on Node 24) while leaving room for legitimately deep target-derived trees such as compiled NIB view hierarchies, and the guard narrows with a typed record check instead of any or unchecked casts. The non-recursive JSON Schema advertisement stays intact on both the public and standard projection paths. Two payload sizes get explicit budgets tied to their producer constraints: web text artifacts reject beyond the 16 MiB source budget the web tooling already advertises, and native UI screenshot base64 beyond the 64 MiB helper output budget. Regenerated product catalog, skill catalog digest, and completion-ledger manifest follow the schema-boundary change.
* fix(validation): preserve depth diagnostics across process inputs
---------
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
Audit actual first-parent ancestry instead of trusting the release bot
chronological cutoff, and block mismatched versions before tag creation.
Sync the published 6.0.0 baseline without dropping newer main changes.
Fixes#1063
Assisted-by: Sakuya (gensokyo-skills:sakuya-checkpointed-execution)
* chore(release/6.0.0): release rea-agents 5.1.0
* chore: normalize release product catalog
* chore(release): correct 6.0.0 candidate and migration notes
Keep the recorded application checkpoint unchanged. The upstream history walk
stops at the merged side-branch release commit and omits older unreleased main
commits; restore the missing notes and absolute-path migration instructions.
Set all release metadata to the agreed SemVer 6.0.0.
Assisted-by: Sakuya (gensokyo-skills:sakuya-checkpointed-execution)
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
The MCP SDK reconverts every registered Zod schema on each tools/list.
With 139 tools that is ~45 ms of Zod JSON Schema work per listing, for a
catalog that cannot change after registration. Memoize the advertised
input and output projections per target on the registration clones.
Listings are byte-identical; repeated tools/list drops from ~62 ms to
~18 ms on the stdio server.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* feat(native): inspect recorded crashes through pwntools and pwndbg
* fix(native): bind core note semantics to raw owner bytes
* fix(native): validate recorded core ABI and evidence scalars
* fix(native): require complete recorded note interpretations
* fix(native): bind physical core notes to original headers
main now carries #1037 (skill version 30, reworded native binary row):
- README_ja/ar/ko/zh: take main's tables and count
trace_dylib_resolution in the artifact graph row (5 -> 6).
- Skill: move to version 31.
- Regenerate the product catalog, conformance manifest, skill digest and
package metadata (137 tools).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
main now carries #964 (skill version 29, macOS native row 7 -> 8):
- README_ja/ar/ko/zh: take main's tables and count
trace_dylib_resolution in the artifact graph row (5 -> 6).
- Skill: move to version 30.
- Regenerate the product catalog, conformance manifest, skill digest and
package metadata (136 tools).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolve conflicts against main:
- package.json: ship both the LLDB tracer bridge and main's process run
token reader sources.
- README.md: take main's simplified English README, which no longer has
the tool-family table.
- README_ja.md: take main's reworded table and count
observe_native_calls in the macOS native row (7 -> 8).
- Skill: the references gain the observe_native_calls paragraph, so the
version moves to 29 (main already uses 28).
- Regenerate the product catalog, conformance manifest, skill digest and
package metadata (135 tools). The MCP tool catalog is now built rather
than committed (#997), so it is removed here.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolve conflicts against main:
- README.md: take main's simplified English README, which no longer has
the tool-family table.
- README_ja.md: take main's reworded table and count
trace_dylib_resolution in the artifact graph row (5 -> 6).
- Skill: the references gain the trace_dylib_resolution paragraph, so
the version moves to 29 (main already uses 28).
- Regenerate the product catalog, conformance manifest, skill digest and
package metadata (135 tools). The MCP tool catalog is now built rather
than committed (#997), so it is removed here.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(mcp): advertise JSON values without recursive schemas
`z.json()` projects a self-referential `$defs/__schema0` entry. Twenty
tool input schemas and 123 output schemas carried it, and clients or
model APIs that reject recursive JSON Schemas refuse the whole tool
list. Every JSON value satisfies `{}`, so the shared JSON value schema
now advertises that. Runtime parsing still admits only JSON values.
Refs #919
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(mcp): keep advertised input schemas within model function-calling limits
Some model providers reject the whole tool list when any input schema
contains a recursive $ref or nests deeper than 10 levels (fixes#919).
Sanitize the advertised wire projection: break cyclic $refs, bound nesting
depth, and drop unreachable $defs. Canonical Zod contracts are untouched.
---------
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: sx4im <sx4im@users.noreply.github.com>
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
`z.json()` projects a self-referential `$defs/__schema0` entry. Twenty
tool input schemas and 123 output schemas carried it, and clients or
model APIs that reject recursive JSON Schemas refuse the whole tool
list. Every JSON value satisfies `{}`, so the shared JSON value schema
now advertises that. Runtime parsing still admits only JSON values.
Refs #919
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
* docs: simplify the English README
Preserve the opening and add the official skills.sh badge. Move setup diagnostics and CLI/Evidence details into guides, add three website showcases, and check setup-client facts in the installation guide.
Refs #1017
* docs: add README workflow and FAQ
Restore the original Disclaimer verbatim, invite community showcases, reuse the website investigation figure, and answer six common questions.
* docs: clarify README updates and collapse FAQ
* docs: welcome contributions in the README
* docs: highlight website guidance before quick start
* docs: keep README capability links aligned with main
* fix(docs): preserve README backlinks and release checks
fix(release): support built-in credentials and refresh release boundary
GitHub now creates approval-required PR workflows for GITHUB_TOKEN-authored
opened/synchronize/reopened events. Restore optional custom credentials and
cover prepare/publish without a separate secret. Record the verified 5.0.0
checkpoint, public 133-tool catalog and package update in the installation guide.
Assisted-by: Sakuya (gensokyo-skills:sakuya-checkpointed-execution)
* fix(snapshot): bind replay to validated cache entry
* fix(snapshot): persist composed workflow results
* fix(snapshot): enforce workflow replay identity
* fix(snapshot): honor cancellation after route resolution
* test(snapshot): make cancellation race deterministic
* fix(snapshot): replay all composed workflow evidence
* fix(snapshot): index workflow evidence once per snapshot
Validate workflow entries against a query and content index instead of scanning the evidence bundle for every entry.
* fix(snapshot): reuse previewed routes and bound workflow cache
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
* fix(javascript): bound semantic node projection for resource safety
analyze_javascript_application exhausted the heap or failed serialization on
ordinary inputs. A small extracted tree crashed outright, and a larger
application tree failed at both the default heap and an 8 GB heap.
Cause: the semantic projection emits one node per AST expression, call site,
binding and property slot, with no ceiling. A five-file tree already yields on
the order of 170,000 nodes, and the whole result is serialized after the object
graph is built and validated. Result ceilings were deliberately removed upstream,
so nothing bounded this growth.
Apply two resource-safety ceilings and report them through the graph's own
coverage contract rather than dropping data silently:
- SEMANTIC_GRAPH_NODE_CEILING bounds retained nodes per tree (100,000, roughly
300 MB serialized, below V8's 512 MB string limit).
- SEMANTIC_GRAPH_FILE_NODE_CEILING bounds each source file (20,000) so one
bundled library cannot starve the application's own modules.
Exhausting either marks coverage truncated with a partial status and records the
ceiling in coverage.limits. A small application stays complete and untruncated.
Verified: a previously-crashing application tree now returns Evidence in under a
minute, while a small tree stays complete. Existing tests and check:fast pass.
* fix(javascript): report semantic graph truncation accurately
---------
Co-authored-by: REA Contributor <contributor@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
* fix(release): publish from explicit source checkpoints
Dispatch preparation and publication against a frozen release branch.
Bind package builds and provenance to the same tagged commit, enable
release-branch PR CI, and document the maintainer workflow.
Assisted-by: Sakuya (gensokyo-skills:sakuya-checkpointed-execution)
* fix(release): stop publication when the checkpoint has moved
Reject unknown phases and a release-branch tip that differs from the
dispatch SHA before Release Please creates a tag. Keep registry jobs and
catalog pushes on their own phase, and run website checks for release PRs.
* fix(release): require a token that can trigger release CI
Stop falling back to GITHUB_TOKEN, which cannot start workflow runs for the release pull request it creates.
* test(release): require the CI-capable release token
Lock the workflow to RELEASE_PLEASE_TOKEN and fail preparation when that secret is missing.
* style(release): format the release-token test
---------
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
* fix(release): publish from explicit source checkpoints
Dispatch preparation and publication against a frozen release branch.
Bind package builds and provenance to the same tagged commit, enable
release-branch PR CI, and document the maintainer workflow.
Assisted-by: Sakuya (gensokyo-skills:sakuya-checkpointed-execution)
* fix(release): drive checkpoint releases from frozen branches
Use branch pushes for Release Please preparation and reviewed-merge publication.
Reject moved source refs before tagging and bind registry provenance to the
triggering release commit. Remove phase inputs and document the three steps.
Assisted-by: Sakuya (gensokyo-skills:sakuya-checkpointed-execution)
Assisted-by: Cirno (gensokyo-skills:cirno-radical-simplification)
* fix(browser): preserve authorized redirect hops
* fix(browser): compare redirect semantics without event times
* fix(browser): classify missing redirect predecessors
* fix(browser): distinguish malformed redirect URLs
* fix(browser): preserve evidence on malformed redirect envelopes
* fix(browser): freeze evidence after malformed redirect
* docs: regenerate catalogs after main integration
* fix(browser): account for skipped redirect body shapes
* fix(browser): mark skipped redirect response shapes unavailable
When a malformed redirect keeps a JSON predecessor, record that its response body shape was not captured.
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Use branch pushes for Release Please preparation and reviewed-merge publication.
Reject moved source refs before tagging and bind registry provenance to the
triggering release commit. Remove phase inputs and document the three steps.
Assisted-by: Sakuya (gensokyo-skills:sakuya-checkpointed-execution)
Assisted-by: Cirno (gensokyo-skills:cirno-radical-simplification)
* fix(contracts)!: require absolute local paths for remaining caller-supplied file inputs
Follow-up to the session snapshot/export tightening: the same invisible server-cwd resolution applied to open_binary target paths (parseBinaryTarget(path, process.cwd())), import_evidence_bundle bundle reads, firmware input files (resolve(raw)), browser executable launch paths (resolve-then-spawn), Electron executable/application/root paths (realpath on raw input), and the expected server path check.
Each field gains the shared isAbsoluteLocalPath refinement plus a catalog-visible description, since JSON Schema cannot express the rule. Examples, scenario fixtures, and contract tests updated to absolute paths; new schema cases cover rejection/acceptance/omission per field.
Explicitly unchanged (verified rooted or out of scope): inspect_plist paths (resolved against the target bundle dir), firmware output_directory (already provider-enforced), filesystem observation paths (resolved against the caller-supplied working_directory), keyed-archive member paths (archive-relative), JS evidence member paths (evidence-relative under root_alias), provider-internal execution schemas, CLI-only doctor flows, and CLI options (own resolve against the operator cwd).
* fix(cli): resolve operator-relative paths before shared absolute-path validation
The contract tightening rejects relative paths, but three CLI commands forward operator-relative input into the shared schemas: firmware commands pass raw args to FirmwareAnalysisService, and the Electron/browser scenario commands validate parsed scenario JSON directly. CLI paths are relative to the operator shell, so resolve them against the working directory first: resolve() in firmwareCommands, and a shared resolveCliJsonPaths JSON key-path helper (cliJsonInput) applied in electronCommands and cliBrowserScenarioCommands. MCP behavior is unchanged — MCP callers must still send absolute paths.
Covers the regression with a relative-path firmware CLI acceptance test (asserts provider-stage capability_unavailable, not a validation error) and unit tests for the helper.
Dispatch preparation and publication against a frozen release branch.
Bind package builds and provenance to the same tagged commit, enable
release-branch PR CI, and document the maintainer workflow.
Assisted-by: Sakuya (gensokyo-skills:sakuya-checkpointed-execution)
fix(contracts): require absolute local paths for session filesystem inputs
Snapshot, evidence-bundle export, and managed-target inputs accepted any non-empty string, so relative paths were resolved against the MCP server working directory instead of the caller's intent. Refine these contract fields to absolute host paths (Windows drive and forward-slash forms included), advertise the constraint on the property descriptions, and regenerate the derived catalog, product catalog, and skill catalog digest. Relative CLI options are unaffected because CLI flows do not parse these MCP contracts.
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
* fix(release): extend npm propagation window and improve diagnostics
The release verification step polls npm for up to 20 minutes (80 attempts
× 15s), but npm registry propagation can take longer. When the version
doesn't appear within the window, the workflow fails even though the
package was already published successfully.
Changes:
- Extend polling window from 20 to 30 minutes (120 attempts × 15s)
- Add --force flag to npm view to bypass cache on each poll
- Report full retry window in diagnostics (attempts × sleep time)
- Distinguish propagation delay from CLI verification failure in error message
Fixes#621
* fix(release): drop no-op --force from npm propagation polling
npm view --force is accepted but only prints a protections warning on a read-only command; --prefer-online already forces fresh registry metadata on each poll.
---------
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
The shared stale-file hint told developers to commit regenerated output, which is wrong for the gitignored build catalog. mcp-catalog:generate no longer re-runs the generator after build:cached since build:unlocked already produces it.
src/generatedMcpToolCatalog.ts had zero runtime importers and churned on every contract edit, guaranteeing merge conflicts on long-lived branches. It is now gitignored and regenerated by build:unlocked; typecheck and knip depend on build via turbo. Tests consume the build output unchanged. Adds a regen-generated CI workflow that pushes tracked generated metadata (product catalog, skill frontmatter, verification manifest/ledger, package metadata, error schema) to same-repo PR branches.
Correct statements that drifted from the English README: IDA Pro was
missing, the diagram labeled Ghidra read-only although Linux/macOS
support annotations, Android verification named Linux instead of macOS
arm64, and the security model described only Unix sockets. Add scoped
doctor checks, provider selection, the Ghidra/Java FAQ, and Hopper
request behavior, and polish phrasing and terminology throughout.
Refs #958
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(artifacts): stream ASAR members without full buffering
* fix(artifacts): close unopened ASAR member streams
* fix(artifacts): preserve unpacked ASAR mismatch digests
* fix(artifacts): preserve ASAR read failures
* fix(artifacts): retain unpacked ASAR stat failures
* fix(artifacts): validate ASAR entry producer identity
Long guides and case studies now have a small `↑ Top` link at the bottom right. It appears after scrolling, returns smoothly to the page header, and moves keyboard focus back to navigation. Reduced-motion users return immediately; the native `#top` link also works without JavaScript.
The link is shared by all 11 styled website pages. The README and style guide document it, and the evidence notes retain the original browser-example digest alongside its later navigation addition.
Validation:
- Website preparation and verification: 12 HTML pages, 195 local references, SVG XML, the six-file ZIP and the sole manual Pages publisher.
- Oxfmt, `git diff --check` and `npm run check:fast` with Node.js 24.18.0.
- Focused browser checks at `/` and `/rea/`: 22 routes, 21 pointer returns, six keyboard returns, five viewport widths, smooth scrolling, reduced motion, focus return and the no-JavaScript anchor.
- Existing site interactions: 24 routes, 68 copy buttons, 20 comparison steps, two CSV exports, two ZIP downloads and eight viewport widths from 320px to 1440px. Code excerpts are unchanged.
- Desktop and mobile rendering reviewed. Downloadable Electron source and CSV export source/data are unchanged.
Publication continues through the existing manual Pages workflow after merge.
Several guides use broad headings and repeat their summaries, making the main example harder to follow. This change names each task directly, keeps Notion's clipboard investigation in the main reading path, and moves the Markdown example and longer provenance into expandable details. The browser guide now opens the hosted example, and the first native CLI query works without a global install.
The existing figures, prompts, source excerpts and comparison controls remain the teaching material. Provider details now fit narrow screens. The repository README links to all Showcases, and the website authoring docs share a signed design principle: a good website is like a good paper—easy to follow, clear and concise, with a clean, refined presentation. A new style guide and scoped AGENTS.md explain how to maintain that approach.
Closes#985.
Validation:
- `python3 scripts/prepare-website.py` and `python3 scripts/verify-website.py`: 12 HTML pages, 183 local references, SVG XML, the six-file ZIP and the sole manual Pages publisher.
- Oxfmt checks and `git diff --check`; `npm run check:fast` with Node.js 24.18.0.
- Browser checks at both `/` and `/rea/`: 24 routes, 68 copy buttons, 20 comparison steps, two CSV exports, two ZIP downloads and eight viewport widths from 320px to 1440px.
- Existing code excerpts, expanded details, keyboard access, no-JavaScript content, continuous cursor animation and reduced motion checked.
Existing analysis and compiler-check evidence is retained; real native-provider verification and compiler replay were not rerun for these copy and layout changes. The homepage content and publication triggers are unchanged.
Follow #973's native ownership: the call-observation schemas move to
src/domain/native/, and the contract now lives in src/contracts/native/.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
observe-native-calls now runs through composition/directAnalysis, where #965
moved runProviderAnalysis.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds a TH04 case study showing how its original 16-bit PC-98 DOS code spaces a bullet ring and aims it at the player. Fresh REA instructions are paired with a five-step C++ comparison and a ring diagram; homepage and showcase-index entries link to the new page and the requested reconstruction repository.
The page credits TH04's maintained source and recorded compiler checks separately from the new REA inspection. Public provenance pins the target, source checkpoint and evidence. No original game assets, executables, private paths or raw result bundles are included. Pages remains manually dispatched.
Validation:
- Website verifier: 12 HTML pages, 185 local references, SVG XML and downloadable ZIP.
- Browser: root and `/rea/`, 32 copy checks, five comparison steps, eight viewport widths, keyboard, reduced motion and no-JavaScript content.
- Fresh real Ghidra verification through published REA 4.1.0: DOS load image verified, all 84 checks match; shown instructions match the function dossier. No Hopper verification was needed or run.
- Independent claims/privacy reviews passed; seven immutable public source links match the local TH04 checkpoint.
- `npm run check:fast`.
The two clean compiler replays and 2,139 matching bytes are recorded TH04 checks, reviewed against their retained receipt and source hashes; the website update does not rerun the compiler or game.
Weak and lazy unresolved-load findings on edges whose loader loads only
conditionally now say that they apply only if that loader loads, as the
required-load finding already did.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A file with a recognized Mach-O or FAT magic but fewer than 8 bytes is a
malformed image, so it stays visible in coverage and root diagnostics.
- Canonicalize the analyzed root and target inside the translated region,
so a permission revoked after open_binary keeps its reason and path.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Follow #952's Apple ownership: the Mach-O load-command reader, dylib
resolution adapter and fixture move to src/artifacts/apple/, the resolver,
dyld path semantics and findings to src/domain/apple/, and the dylib lane
helper to scripts/verify/apple/.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add observe_native_calls (CLI: observe-native-calls <path> <input-json>). It
launches the active Mach-O as an owned process under `lldb --batch`, stops at
caller-selected functions or Objective-C methods, records each entry and
auto-continues:
- thread, image, symbol, load and file address;
- raw integer argument registers and optional caller frames;
- for methods, the selector read from _cmd and the receiver's dynamic class,
from LLDB's runtime reader without running target code.
No expression is evaluated and no existing process is attached. The run ends
on exit, max_events or duration_ms; REA then kills the process and confirms
that it is gone. The result also carries exit status, bounded stdout/stderr,
breakpoint resolution with partial coverage for unresolved requests, and
limitations. A target LLDB may not debug fails with a debugger-attach-denied
reason and remediation.
verify:native-calls checks the tool through the CLI and stdio MCP against a
compiled fixture, compares breakpoint addresses with nm, exercises every
outcome, and checks hardened-runtime targets with and without get-task-allow.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Electron guide currently uses a teaching fixture. Add a real Notion clipboard case with REA findings, short source excerpts and responsive figures, alongside the existing DX-Ball reconstruction.
- Trace the saved Notion 7.6.1 preload API through its wrappers to the clipboard receiver. Attribute the separate web-cache module probes to their original harness. Public content uses relative source locations and generic example data; packages and complete captures stay local.
- Add a Showcases index and links from the homepage and JavaScript guide. Simplify homepage copy while preserving the approved headline and closing question.
- Show copyable agent installation prompts and the direct setup command. Keep terminal cursors blinking consistently and respect reduced-motion settings.
- Provide one Notes example ZIP. Generate it from the six public source files before website checks and manual Pages deployment; verify its contents against the source. Pages remains manual-only.
Validation:
- `npm run check:fast`
- `python3 scripts/prepare-website.py` and `python3 scripts/verify-website.py`
- Browser checks at `/` and `/rea/`: downloads, prompt/command copying, responsive layouts, keyboard navigation, reduced motion and DX-Ball comparison controls.
- Published REA 4.1.0 preload analysis and feature traces; source/claim/privacy review.
- Real Hopper/Ghidra verification: not performed (website-only change).
- Edges below a conditional fallback now carry loader_conditional, reuse of
a conditional image by install name is conditional, and their findings say
they apply only if that image loads.
- Hash each traced image only if it is still the file whose headers were
parsed (device, inode, size and change times), before and after hashing.
- Resolve explicit roots segment by segment, so a root below a symlinked
directory that points outside the analyzed root is rejected.
- Require a complete 16-byte LC_CODE_SIGNATURE command.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Treat the target as a bundle only when it was opened from an app bundle
directory (it carries the bundle's Info.plist); a regular Mach-O file whose
name ends in .app is traced from its parent directory.
- Classify a FAT header with zero architecture records as malformed, so it
stays visible in unclassified roots and coverage.
- State that dylib compatibility versions are not compared.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
inspect_native_dispatch_metadata read pointer fields as stored bytes, so
chained-fixup images (the default since Xcode 13) decoded no classes, and
superclasses from other images were always unresolved.
- Decode LC_DYLD_CHAINED_FIXUPS pointer formats 64, 64_OFFSET, ARM64E,
ARM64E_USERLAND and ARM64E_USERLAND24 with import formats 1-3, and
interpret LC_DYLD_INFO bind, weak-bind and lazy-bind opcode streams.
- Name external superclasses from their _OBJC_CLASS_$_ binds.
- Decode class_ro_t baseProperties and __objc_catlist category_t records
(instance/class methods, protocols, properties) into objc_categories;
category methods carry their category name.
- Report the fixup encoding in a pointer_fixups coverage facet.
- verify:apple-dispatch builds the fixture with dyld-info and chained
fixups, plus arm64e on Apple silicon.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* perf(setup): reuse initial diagnostics during planning
* test(setup): verify post-configuration doctor refresh
* style(setup): remove extra test spacing
Address review findings in trace_dylib_resolution:
- Resolve LC_LAZY_LOAD_DYLIB dependencies without traversing them, since
dyld loads them on first use. An unresolved one becomes
`lazy-load-unresolved`, not a launch failure.
- Accept FAT tables up to 128 records, as target opening does. A table
that names no Mach-O CPU type, such as a Java class file, is not
Mach-O.
- Require 8-byte load-command alignment in 64-bit images. 1,508 real
slices still match otool.
- Report EACCES/EPERM while probing, reading, or hashing as an
`unavailable` failure naming the code and path, rather than generic
io.
Findings and limitations move to dylibResolutionFindings.ts to keep the
resolver under the module size limit.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A file such as Versions/.DS_Store beside the only real version made the
framework look multi-versioned, so its Info.plist became unknown with a
misleading limitation. Version directories are now limited to entries
observed as directories or implied by deeper paths.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Address review findings in trace_dylib_resolution:
- Choose child slices by dyld's graded architectures, so an x86_64h
process loads a generic x86_64 slice instead of reporting
architecture-missing.
- Read FAT containers with the byte-swapped FAT_CIGAM and FAT_CIGAM_64
magics, which target opening already accepts.
- Report string-bearing load commands too short to hold their string
offset as malformed instead of failing with a RangeError.
- Keep recognized but unsupported images as an `unsupported` candidate
outcome. It is undeterminable like an outside-root path, not
malformed.
- List Mach-O files that do not parse during root enumeration as
unparsed images, so coverage is partial rather than silently complete.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(artifacts): accept the bundle subject when extracting an app bundle
For a .app target the session target is the bundle's executable, while the
artifact provider reports the bundle itself as the subject. The subject
check exempted inventory_artifact and inspect_artifact but not
extract_artifact, so extracting any .app failed with execution_failure after
the output tree had already been written, and the output path was never
reported.
* refactor(binary): rename artifact bundle subject helper
isArtifactInventorySubject also covers extract_artifact for .app
bundles, so name it for the shared bundle-subject exemption.
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
* fix(javascript): resolve bare source-map and worker URLs next to the script
A sourceMappingURL like `main.js.map` (the default of webpack, esbuild,
rollup, Vite and rolldown) and `new Worker("worker.js")` were resolved as
module specifiers, so the bare name was looked up as an npm package and the
map or worker script was never linked. Resolve them as URLs relative to the
declaring script.
* fix(javascript): tighten url-reference resolution edge cases
Use looksExternal for non-module contexts so protocol-relative URLs
cannot be misread as root-absolute paths, cover url-reference unit
cases, and assert bare service-worker script resolution.
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
A ZIP or DMG holding two applications produced bridge candidates from
scripts in one app to native code in the other. Candidates now pair only
components owned by the same application root; components outside every
root pair only with each other.
A versioned framework with several real version directories now keeps
its Info.plist unknown even when only one version has a plist, because
Versions/Current, which is not inventoried, decides which applies.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(pages): reserve publishing for the REA website
* docs(website): add worked guides and agent prompt examples
* ci(website): check relevant PRs and publish only on demand
* docs(website): clarify IDA coverage and analysis session lifetime
Add trace_dylib_resolution (CLI trace-dylib-resolution) to the artifact
family. For the active Mach-O, or every executable in the active .app
(the main app, XPC services, extensions, login items, helpers), it
reports which file each dylib load reaches and how.
A pure TypeScript reader decodes FAT and Mach-O load commands:
LC_LOAD/WEAK/REEXPORT/LAZY/UPWARD_DYLIB, including the newer
dylib_use_command encoding with weak, re-export, upward and delayed-init
flags, plus LC_ID_DYLIB, LC_RPATH, LC_DYLD_ENVIRONMENT and code-signature
presence. Malformed tables are reported with the failing command instead
of being guessed.
Resolution follows dyld:
- @executable_path comes from each process root;
- @loader_path comes from the loading image, or from the owner of the
LC_RPATH entry being expanded;
- @rpath searches the loader's rpaths first, then up the load chain;
- dependencies load dependents-first in load-command order, once per
process, and a matching install name reuses an already loaded image;
- symlinks are followed inside the analyzed root, and escapes stop.
Every candidate path is reported with its outcome. Each edge resolves to
resolved, conditional (an outside-root candidate such as /usr/lib/swift
precedes), unresolved, or undetermined. Absolute and shared-cache system
paths are never checked against the host. Derived findings cover
unresolved required or weak loads, absent earlier @rpath candidates (with
library validation left unknown), and LC_DYLD_ENVIRONMENT.
verify:macos-bundle now also:
- checks every traced image against otool -l;
- asserts each resolution status on a clang-built fixture that adds a
missing Overrides rpath, an absolute rpath, and a delay-init library;
- compares the predicted load order of two process roots with what dyld
loads under DYLD_PRINT_LIBRARIES.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Directory, ZIP, and DMG inventories can hold installers, disk-image
extras, and AppleDouble sidecars beside the app. Those components were
classified as the application's frameworks, libraries, JavaScript, and
metadata, and fed runtime families and bridge candidates. For these
formats, components outside every application root are now left out,
with a limitation that counts them. IPA projection is unchanged.
A selected directory whose name ends in .app is now its own root by
identity, so an empty or partial inventory still reports it. iOS is
claimed only for shallow roots that have an Info.plist, so an empty root
reports no platform.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The inventory snapshot captures reader provenance before close() runs,
so a `hdiutil info -plist` entry recorded during cleanup never reached
CLI or MCP results. Detach entries already share that timing. Record
neither instead of implying the query is observable.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(artifacts): read AppKit connectors from flat keyed-archive NIBs
Flat AppKit NIBs archive NSNibOutletConnector and NSNibControlConnector
endpoints and the outlet or selector name under NSSource, NSDestination,
and NSLabel. The keyed-archive parser read only source, destination,
and label, so it skipped every such connector: XLD.app's 64 decoded NIBs
had no outlet or target-action edges. The NS-prefixed keys now follow the
same source and destination convention as compiled NIBArchive documents.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(artifacts): read AppKit control connectors from the control to its target
NSNibControlConnector archives NSSource as the sending control and
NSDestination as the action target. The previous commit inverted them
like the unprefixed fields, so every flat AppKit action ran from the
target to the control. The action trace selects a control and follows
control -> action, and the graph keys the selector by its target, so
neither could resolve these actions. The NS-prefixed keys are now read
as source and destination for outlets and actions alike.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(artifacts): key AppKit connector endpoints by their node identity
An NSSource or NSDestination object with an identifier field was
referenced by that identifier, but its node is keyed by its authored
object ID or archive UID. The connector then pointed at a synthetic
unknown node. NS-prefixed endpoints now use the referenced object's
node identity.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
project_apple_application_graph accepted only IPA inventories. It now
also projects macOS .app directories and ZIP or DMG inventories that
contain applications. It reports application roots, platforms, and
every nested bundle with its path-convention role, layout, parent,
Info.plist path, executable candidates, and signing paths:
- roles: app extensions, XPC services (including inside frameworks),
frameworks, login items, system and driver extensions, plug-ins,
resource bundles, and helper or nested applications;
- privileged helpers in Contents/Library/LaunchServices and launchd
plists in Contents/Library/LaunchAgents or LaunchDaemons;
- direct files of Contents/Helpers;
- symlinks by path. Their targets are not inventoried, so versioned
frameworks are described through their real Versions/<version>/
directories.
AppleDouble sidecars (._* and __MACOSX/) are excluded from roles. A DMG
whose contents could not be inventoried is reported as partial. Other
inventory formats remain input errors. The projection still reads no
plist or CMS semantics; it points callers at inspect_plist.
The result schema is additive. projection_id now covers the new fields,
so IPA projection IDs differ from earlier versions.
verify:macos-bundle compiles a source-owned app with clang (CLT only).
It packs it as a directory, a ditto ZIP, and an APFS DMG, and checks
identical anatomy through the CLI with stdio MCP parity. It runs in the
macOS CI job.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An APFS disk image attaches as an image disk plus a synthesized APFS
container, and hdiutil reports both as whole disks. Detaching the
container also ejects the image disk, so the reverse-order detach then
failed with "No such file or directory" and every APFS DMG inventory
ended in "DMG detach or mount-root cleanup failed". APFS is the default
format of `hdiutil create` on current macOS.
When a detach fails, ask `hdiutil info -plist` whether the device is
still attached. A device that is gone counts as detached; one that is
still listed, or whose state cannot be read, remains a cleanup failure.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(artifacts): project compiled AppKit actions from the control to its target
NSNibControlConnector archives the sending control as NSSource and the
action target as NSDestination; a nil target is the first responder. The
NIBArchive projection swapped them for control connectors, so every
compiled AppKit action ran from its target to the control. The action
trace, which follows control -> action, could not find them, and the
selector node was keyed by the control instead of the target class. When
the target was nil, the swapped source was null and the action was
dropped: Chess lost 29 menu actions, KeepingYouAwake 7.
Connectors now keep NSSource -> NSDestination. The NIBArchive test
encoder moves to a fixture module so a bundle test can build compiled
NIBs.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(artifacts): report observed action routes when a compiled route is missing
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(artifacts): report compiled connector records when a storyboard route is missing
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(artifacts): write the storyboard fixture's action in Cocoa syntax
MacFixture.storyboard declared its button action with the iOS attribute,
<action selector="buildTapped:" destination="vc1">. Cocoa documents
name an action's receiver with target=. ibtool compiled the iOS spelling
into an NSNibControlConnector whose NSSource is the view controller
placeholder and whose NSDestination is the button. That is the reverse
of what Xcode-authored AppKit NIBs contain (Music, Chess,
KeepingYouAwake, and Transmission all archive NSSource as the control),
and it is what the old inversion had matched. With target= the compiled
fixture archives the button as NSSource. The temporary connector dump is
removed; the observed routes remain in the assertion message.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* feat(website): add local introduction and DX-Ball showcase
* feat(website): illustrate REA and DX-Ball reconstruction
Add two explanatory figures and an interactive comparison of recorded DX-Ball x86 instructions with maintained C. Preserve the full instruction listing, caller excerpt, constant reads, figure prompts and evidence provenance.
Validation: Chrome preview at local root and /rea/; five comparison steps; 22 clipboard checks; keyboard navigation; responsive widths 1440, 768, 390 and 320. Verify assembly against saved REA Evidence and C against the pinned public source. Existing execution and compiler results are cited, not rerun.
* docs(website): show the REA queries behind source recovery
Present compact function, caller and byte-read request excerpts alongside recorded evidence. Keep the overview and case narrative focused on REA, with provider provenance in contributor notes. Replace raster references with maintained SVG source diagrams while retaining the established layout and image-generation prompts.
Validation: local and /rea/ Chrome previews, five comparison steps, 22 clipboard checks, responsive widths and keyboard navigation passed. SVG XML and all 41 local links/assets passed checks.
Compiled UIKit NIBs and storyboards archive outlets and control actions
as UIRuntimeOutletConnection and UIRuntimeEventConnection with
UISource, UIDestination, and UILabel. The NIBArchive projection
recognized only AppKit *Connector classes with NS-prefixed keys, so an
iOS app produced no outlet or action edges: Stash's 64 decoded documents
yielded none. These connections are now projected with the same
source -> destination roles, an event connection carries its
UIEventMask as ui_event_mask, UIClassSwapper reports its UIClassName,
UIProxyObject is a placeholder, and connection records are no longer
emitted as unknown objects.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Carry the Info.plist that declared the program file on the target as
bundleInfoPlist, so inspect_plist defaults to it even when the program
file is a symlink into another bundle directory.
- Accept a readable Info.plist symlink, as reading the plist directly did.
- Treat only a missing path as an absent layout or wrapper; a permission
denial now reaches the resolver's permission-denied classification.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An ambiguous exact-signature group was described as sharing a
non-name identity key, but that key includes the declared type and name,
so names cannot separate it. Ambiguity limitations now name the key the
group actually shares.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MacFixture.storyboard declared its button action with the iOS attribute,
<action selector="buildTapped:" destination="vc1">. Cocoa documents
name an action's receiver with target=. ibtool compiled the iOS spelling
into an NSNibControlConnector whose NSSource is the view controller
placeholder and whose NSDestination is the button. That is the reverse
of what Xcode-authored AppKit NIBs contain (Music, Chess,
KeepingYouAwake, and Transmission all archive NSSource as the control),
and it is what the old inversion had matched. With target= the compiled
fixture archives the button as NSSource. The temporary connector dump is
removed; the observed routes remain in the assertion message.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every native command rejected an iOS app installed on an Apple silicon
Mac, such as /Applications/Stash.app, with "app has no readable
CFBundleExecutable": the resolver understood only the macOS layout,
Contents/Info.plist with Contents/MacOS/<executable>. iOS-style bundles,
including those extracted from an IPA, keep Info.plist and the program
file at the bundle root, and an iOS-on-Mac wrapper holds that bundle in
Wrapper/<Name>.app.
Bundle resolution moves to AppBundleExecutable and accepts the macOS
layout, then the flat layout, then a wrapper's single real Wrapper/*.app
directory. The WrappedBundle symlink is never followed, and the program
file must stay inside its bundle. inspect_plist defaults to the Info.plist
beside the program file when the bundle has no Contents/Info.plist.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* perf(graph): avoid repeated traversal edge scans and copies
* fix(android)!: preserve JVM settings and reuse metadata sessions
Read class metadata without generating application source, retain immutable serialized APK sessions, and join owned cleanup on cancellation and shutdown.
BREAKING CHANGE: Android analysis now requires a full JDK 17 or newer with its compiler module for the packaged Java source bridge.
An undecoded member in an ambiguous exact-signature group stays unpaired,
like a one-sided member, but the counterpart check considered only
one-sided members. A decoded member with the same declared type and name
on the other side was therefore reported as removed or added. Ambiguous
candidates now count as possible changed counterparts too.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
NSNibControlConnector archives the sending control as NSSource and the
action target as NSDestination; a nil target is the first responder. The
NIBArchive projection swapped them for control connectors, so every
compiled AppKit action ran from its target to the control. The action
trace, which follows control -> action, could not find them, and the
selector node was keyed by the control instead of the target class. When
the target was nil, the swapped source was null and the action was
dropped: Chess lost 29 menu actions, KeepingYouAwake 7.
Connectors now keep NSSource -> NSDestination. The NIBArchive test
encoder moves to a fixture module so a bundle test can build compiled
NIBs.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Reserving the __proto__ placeholder decodes the whole document, so
<![CDATA[�]]> or a comment with an out-of-range reference
threw a RangeError, and every XML plist reader failed on a valid
document. References beyond U+10FFFF now stay as written. The XML
decoder still rejects them outside comments and CDATA.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A receiver spelled indexedDB or caches does not prove the binding, so
indexedDB.open("GET", "/api") keeps its endpoint. Such receivers
still need a standard HTTP method literal: a computed first argument or
an uppercase database name such as "APP" reads as storage, not XHR.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
decode_interface_builder failed on every flat (keyed-archive) NIB that
holds plist data or dates. Archived colors keep their components as
data, so this covers nearly every AppKit NIB: XLD.app decoded 0 of 64.
The decoded Uint8Array and Date values failed JSON validation. They now
use the shared plist projection, which keeps them as explicit
$plist_type values.
Decoding those archives exposed a second failure. The keyed-archive
parser inlined every UID reference up to 16 levels for every object, so
an archive whose views reference their window, superview, and next key
view expanded exponentially. A 9 KB NIB took 3 s, and a 158 KB
MainMenu.nib did not finish. A reference now resolves to its string, or
to a stub naming the referenced object's archive UID, authored ID, and
class. The hierarchy walk visits each object once. The parser also reads
XML CF$UID references and treats UID 0 as nil.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#877 reads a computed-method `.open(method, url)` as XMLHttpRequest when
the second literal could be a URL. IndexedDB uses the same callee name
with a database name and version, so `indexedDB.open(name, "2")` was
published as the network endpoint "2". Recognized storage `open` calls
(IndexedDB and Cache Storage) are no longer read as XHR. Both the bundle
and static analyzers still report them as storage.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#885 decodes XML plists that contain a __proto__ key by omitting those
entries, but signature entitlements and Interface Builder plists dropped
the omission count. inspect_signature returned an entitlement set that
looked complete, and archive_decode stayed complete. Both now report the
omission: a signature limitation, and a partial archive_decode facet with
reason dictionary_entries_omitted and a per-document limitation.
The placeholder that stands in for __proto__ was reserved against the raw
XML text, so an entity-encoded key such as __rea_prototype_key__
decoded to the placeholder and was omitted as if it were __proto__. The
placeholder is now reserved against the decoded text.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When the CLI header parsed but its metadata could not be admitted, the
native-boundary fallback reported hard-coded false flags and zero header
values. A corrupt-metadata ReadyToRun image therefore appeared IL-free
and non-native. The fallback now reports the parsed CLI header and
derives the summary from it as the full inspection does. When the CLI
header itself is unreadable, a limitation says the values are defaults.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A field that changed from a decodable to an undecoded signature was
reported as removed on the decoded side and unknown on the other. The
undecoded member with the same declared type and name may be that field
with a changed signature, so its decoded counterpart is now unknown too,
with a counterpart-signature-not-decoded limitation.
The compare_managed_members description now names the exact declared
type, name, and raw signature tier and the undecoded handling.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`compare_managed_members` gave undecoded (unsupported or malformed)
signatures no match key at all. In complete inventories every such member
was then reported as removed on one side and added on the other, even
for byte-identical assemblies: comparing PSReadLine.dll with itself
reported 457 added and 457 removed members, mostly generic
instantiations the signature decoder does not support.
The raw signature blob is the exact signature, so methods and fields now
pair by exact declared type, name, and raw signature without decoding.
An undecoded member that still has no counterpart is reported as unknown
with a `signature-not-decoded` limitation, never added or removed, because
no shape round could look for a changed counterpart.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`inspect_managed_native_boundaries` wrote the PE classification
(`not-managed` or `malformed`) into `coverage.state`, which accepts only
`complete`, `partial`, or `unavailable`. Its own result validation then
threw, so every native DLL and every PE with unreadable CLI metadata
failed as a generic execution failure advising a retry. The sibling
artifact and member inspectors succeed on the same files.
Report these files with `unavailable` coverage, as the member inspector
does, keeping the metadata status and parse issues.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`xhr.open(method, "api/users")` is a same-origin request, but the
computed-method fallback required an absolute URL or a path prefix.
Keep the literal unless it is provably not a URL: a Node fs open flag,
a reserved browsing-context name, or a call on a receiver spelled as a
browsing context or document.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* feat(browser): trace captured website module imports
Compose verified exported scripts, inert native import syntax and a narrow
Chromium resolution port. Preserve query/fragment identity, import-map context,
all reported capture candidates and explicit unknown execution. Share named
CLI/MCP contracts and retain native reports, diagnostics and cleanup failures.
Add focused boundary regressions and a real module-loading oracle to the
existing conditional Chrome lane. No captured application code is executed
by module tracing, and no selected website asset is refetched.
Refs #851, #774
Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
* fix(browser): preserve module contexts and source bindings
Keep capture completeness inline, validate actual source text against its
digest, and separate unsupported URL contexts from malformed input.
Use the importer origin for native module resolution and the selected map
base independently, including mixed HTTP/HTTPS and escaped HTML attributes.
Refs #851, #774
Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
The `plist` XML decoder throws on the legal dictionary key `__proto__`
(its CVE-2022-22912 guard). An app whose XML Info.plist held such an
entry could not be opened at all ("app has no readable
CFBundleExecutable"), and entitlements, XML keyed archives, and
Interface Builder plists failed the same way. On the plutil JSON route,
validation silently dropped the key from `inspect_plist` results.
Decode XML plists through a shared reader that substitutes such keys
before the decoder runs, then omits and counts those entries.
`inspect_plist` and `inspect_keyed_archive` report the omission as a
limitation instead of failing or dropping it silently.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Merge main (#874) and resolve the endpoint heuristics together. Receiver
spellings do not prove bindings: `parent.open("GET", "/api")` may be a
local XHR, `new Headers()` may be an imported client, and
`api.headers.get("/v1/x")` may be a nested client.
A literal HTTP method is read as XHR on any receiver; the browsing-
context exclusion now applies only to computed methods. A get/delete
literal that is a URL or path stays an endpoint even when the receiver
is spelled as a keyed collection.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
otool and dyld_info print the operand path before a slice's records,
and the Mach-O parsers read that header as output. A file name holding
`Load command` blocks or `(from lib)` lines therefore added a forged
LC_MAIN entrypoint, corrupted the Mach header fields, and injected
imports and exports into `inspect_macho`.
Strip the exact echoed operand header (`<path>:`, `<path> (architecture
<arch>):`, `<path> [<arch>]:`) before parsing. Output without that
header, such as replayed captures, is parsed unchanged.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The collection APIs share only `get` and `delete` with HTTP clients, so
`api.headers.post("/v1/headers")` and `api.searchParams.request("/s")`
keep their endpoints.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`window.open(url, "/preview")` has a computed first argument and a
path-shaped browsing-context name, so the computed-method XHR fallback
reported the target name as an endpoint. Browsing-context and document
`open` calls never take an XHR method and request URL; skip them.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A regular plist that the host refuses to open made both plutil
conversions fail, which was reported as an undecodable property list.
Open the file before running plutil and report EACCES/EPERM as a
target access failure naming the path.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Static endpoint extraction read the first literal argument of any call
named get, post, put, patch, delete, or request as an HTTP request URL.
Reads of a provable keyed collection also became network endpoints in
application and web bundle analysis: `new URLSearchParams(...).get("q")`,
`response.headers.get("content-type")`, `new Map().get("key")`, and
`url.searchParams.get("page")`.
Skip these calls only when the receiver is a constructed Map, WeakMap,
Set, WeakSet, Headers, FormData, or URLSearchParams, or a platform
`headers`/`searchParams` property. Any other receiver may still be an
HTTP client with a base URL, so `api.get("users")` keeps its endpoint.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A computed XHR method, as in `xhr.open(method, "/api")`, no longer
discarded an endpoint that main reports. Keep the URL when it is an
HTTP(S)/WebSocket URL or a path; fs flags and window targets such as
`r` and `_blank` still produce no endpoint.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`inspect_plist` turned a missing selected plist, a directory, or a file
that is not a property list into a generic execution failure that
advised retrying and running `rea doctor`. A bare Mach-O without
Contents/Info.plist failed the same way.
Check the resolved path before running plutil and keep plutil's decode
diagnostic. A caller-selected path now fails as invalid input naming
the path and the reason; a missing default Info.plist is unavailable for
the target. The CLI no longer sends Contents/Info.plist as an explicit
selection, so its default matches the MCP default.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Static endpoint extraction treated any `.open(_, "literal")` call as
`XMLHttpRequest.open(method, url)`. In application and web bundle
analysis, `fs.open("/tmp/data.txt", "r")` became the network endpoint
`r` and `window.open(url, "_blank")` became the endpoint `_blank`.
Read the URL only when the first argument is a literal HTTP method: a
standard method in any case, or an uppercase extension token such as
WebDAV `PROPFIND`.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Static application analysis read call arguments only from quoted string
literals. A template literal without substitutions denotes the same
exact string, yet `fetch(`https://x`)`, `localStorage.setItem(`k`)`,
`new Worker(`./w.js`)`, and `require(`./dep.js`)` produced no endpoint,
an unnamed storage node, or an unresolved reference expression instead
of the facts their quoted spellings produce. Electron IPC and data-effect
readers already accepted these templates.
Read substitution-free templates in the shared static string and
argument readers so both spellings produce the same graph.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Foundation encodes `encode(_:forKey: "UID")` as a `$top` dictionary
whose single key is `UID`. The keyed archive projection treated every
one-key `UID`/`CF$UID` dictionary as a reference marker, so that root
became a malformed reference and the real link to its object was lost.
Treat a one-key dictionary as a UID only when its value is a number,
matching the binary decoder's UID shape and Foundation's XML `CF$UID`
rule; otherwise descend into it as an ordinary dictionary.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`swift-demangle` parsed a symbol beginning with `-` as an option, so
`-help` replaced the results with usage text and the call failed as
unreadable output. A symbol containing a line feed split into extra
output records, and the CRLF-tolerant parser stripped a carriage return
that belonged to the final symbol.
Pass the symbols after `--`, split records on the LF the demangler
emits, and reject multi-line symbols in the shared CLI/MCP input schema.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* feat(application): wire Android and Apple inventory graph tools
Expose project_android_application_graph and project_apple_application_graph
through CLI and MCP so authenticated inventory Evidence can be projected
without a provider launch.
* fix(application): use producer root occurrence IDs in graph examples
Catalog examples constructed root occurrence IDs from artifact_id +
logical_path, but inventory validation authenticates "." with
{ root: root_artifact_id }. Align the examples and regenerate catalogs
after rebasing onto main (application family count 11).
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
* refactor(domain): split Interface Builder keyed-archive parse from graph builder
* fix(domain): drop unused Interface Builder type re-exports
Knip failed Static checks because the split re-exported object and
connection types that no caller imported.
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Extract Mach-O/FAT selection, Objective-C class/method/ivar decode, and
Swift conformance/witness facets so AppleDispatchMetadata stays a thin
orchestrator without changing decode semantics.
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Move AnalysisClient construction into GhidraProviderClient and the DOS
load-image attestation path into GhidraLoadImageAttest so GhidraProvider
stays a thin candidate adapter without behavior changes.
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
codesign echoes the executable path and signing identifier verbatim,
and an ad hoc identifier derives from the file name. A file name with
line breaks added forged Authority lines, a signed file named after
codesign's unsigned message was reported unsigned, and path text could
supply entitlements. Parse display fields after the exact echoed path
and identifier, classify unsigned output by exit status, and read
requirements and entitlements from stdout.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Only a string type is the V1 entry discriminator; a native mcp.servers
table may hold a server object named type.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Zod reports union branch issues relative to the union, so a missing
union-typed argument such as trace_application_feature's seed was
reported at the request root, once per branch.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
plutil's JSON spells an integral <real> such as 9007199254740992 like an
<integer>, so the JSON path labeled it an exact integer. When the JSON
holds an unsafe integral number, read element types from plutil's XML
conversion; numbers whose origin stays ambiguous are reported as decoded
with an explicit limitation.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Keep adapter/OS helper failures in diagnostics instead of replacing them
with a canned remediation sentence. Share browserVersionSchema, Node
support prose, and JADX heap/remediation constants so release pins stay
authoritative.
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Express the empty-seed rule as a JSON-Schema-representable union, so
the advertised trace_application_feature schema rejects what the
server rejects, and match context-bridge seeds on the exact api_key.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
OpenCode V2 reads native server entries from mcp.servers, and a native
entry takes precedence over a V1 mcp.<name> entry. After OpenCode
migrated a configuration, setup wrote an ignored V1 entry, status
reported REA as missing, and uninstall left the native entry in place.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* feat(javascript): recover readable modules with Wakaru
Integrate pinned upstream source behind a typed optional recovery port,
preserve source identity and producer provenance, and publish verified
artifacts for existing JavaScript analysis through CLI and MCP.
Add focused real-tool CI with genuine bundler fixtures and bounded
resource, cancellation, cleanup, schema and packaged-artifact checks.
Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
* fix(javascript): align recovery catalog and browser verification
Share canonical Wakaru provider identity, describe CLI mode options, and
format the new workflow test. Disconnect the real page transport after
its observation readiness progress instead of a fixed delay.
Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
* refactor(javascript): consume the investigation evidence writer
Verify that the SDK recovery handler records complete Evidence through the newly shared investigation owner.
Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
* chore(test): account for isolated recovery fixture compilers
* fix(javascript): validate recovery paths before acquiring the engine
Return field-specific invalid_format diagnostics for relative paths and verify compiled CLI/MCP parity even when the optional engine is unavailable.
Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
The pattern-based reader decoded entities twice, ignored numeric
character references and CDATA, and could match a commented or nested
CFBundleExecutable key, so valid app bundles reported a missing program.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Pair the same empty IPC channel, context-bridge key, or endpoint value
across application versions by its exact value, and accept an exact
empty feature seed while rejecting an empty containment seed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(ghidra): admit the 12.1 line and the install's JDK range
The provider treated the verified Ghidra 12.1.4 build and JDK 21 as the only
legal installation, so a working 12.1.x package or a newer JDK was rejected
before analysis started.
Admission now follows the 12.1 release line and application.java.min/max.
A compatible build other than 12.1.4 keeps its observed version and records
that the bridge was verified against 12.1.4.
Fixes#821
* fix(ghidra): stop pinning the NativeAOT build to one version string
The build script still rejected every Ghidra release except the literal
12.1.4 and every javac except major 21. It now accepts the 12.1 line and
javac 21 or newer, compiles with --release 21, and records the observed
Ghidra version. The JADX engine version uses the audited release constant.
* fix(ghidra): report unverified builds on analysis results
Session open uses health only as a startup gate and discards that
execution, so the unverified-build limitation never reached CLI or MCP
results. Attach it to every Ghidra execution for that install.
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
* fix(firmware): accept the verified Binwalk and Unblob release lines
Exact --version equality rejected every build except Binwalk 3.1.0 and
Unblob 26.6.4, then stored that constant as the observed engine version.
Admit the 3.1 and 26.6 lines, keep the audited build as verified, and
report the banner that actually ran.
* chore(docs): regenerate skill metadata after firmware contract text
docs:check failed because SKILL.md lagged the Binwalk/Unblob release-line
tool descriptions.
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Artifact path failures told callers to "inspect the reported path" but
reported none: `ArtifactReaderFailure` messages such as
`Artifact path collision: ...` were dropped when converted to
`ArtifactOperationError`, leaving only `{ operation, reason: "path" }`.
Carry the failure message into `details.detail` for artifact tools and
JavaScript application analysis. Name both spellings in case-fold
collisions and include the JSON-escaped input in unsafe and
non-normalized path messages.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
The XML fallback inferred an integer from `Number.isInteger`, so an
integral `<real>` beyond 2^53 was misreported as an unknown integer.
Read the `<integer>` and `<real>` literals from plutil's XML text instead:
an unsafe integral number that matches one `<integer>` literal and no
`<real>` gets its exact decimal; a number that could be either stays as
decoded with a limitation.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A synthetic `""` label for an empty application-graph value could still
be matched by a literal `""` feature seed, which also matches the label of
a real two-quote value, so `trace_application_feature` combined
`fetch('')` with `fetch('""')`. Emit no label (`null`) for empty values;
the exact value stays in the identity and properties.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`inspect_plist` parsed plutil JSON with `JSON.parse`, silently rounding
integers outside ±(2^53 - 1): `18446744073709551615` became
`18446744073709552000` with no limitation. Keep the exact decimal text
from the JSON source as `{ "$plist_type": "integer", "decimal": "..." }`
and add a limitation. On the XML fallback path, the decoder has already
rounded such values, so they become `decimal: null` instead of a wrong
number.
Also restore the `` escape in the BOM regex, which an earlier
rewrite had turned into a raw invisible character.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#839 displayed empty artifact-local keys and source-map original names as
`""` inside node identities, so `fetch("")` and `fetch('""')` (or
`sources: ["", "\"\""]`) produced the same node ID and merged two
distinct facts. Function nodes likewise exposed only a display label, so
`['']()` and `['""']()` were indistinguishable.
Admit the exact empty string in `artifact-local-key.key` and
`source-map-original.original_source`, keep the `""` substitution for
labels only, and record each function node's exact `name` in its
properties. Regenerate the catalog digests for the relaxed output schema.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Explain that bare `rea doctor` audits every integration, map common tasks
to `--provider`, `--client`, and `--skill` scopes, and describe how
`scope_checks`, `informational_checks`, `healthy`, and
`environment_healthy` relate. Document the typed ambiguous-provider
error and how to choose an engine once without implying a fallback.
Fixes#726
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`inspect_plist` converted every plist with `plutil -convert json`, which
rejects plists containing `<data>`, `<date>`, or non-finite `<real>`
values. Such valid plists (including Stocks.app's Info.plist) failed with
a cause-free `execution_failure`.
When the JSON conversion exits nonzero, decode `plutil -convert xml1`
instead. Data and dates use the `$plist_type` objects the keyed-archive
reader already emits; non-finite reals become an explicit unknown because
the XML decoder reports NaN and infinity alike. Provenance records both
conversions and limitations explain the representation. Plists that JSON
can express keep the unchanged single-conversion path.
The projection moves to `src/domain/plistValue.ts` and is shared with the
keyed-archive reader, which keeps rejecting non-finite reals.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A source map whose `sources` contains `""` (a legal relative reference,
emitted for virtual or generated modules) made the whole application
analysis fail: the empty name became the `source-map-original` identity's
`original_source`, which must be nonempty. Display it as `""` at the same
accumulator seam; the observation's `properties.source` keeps the exact
empty name.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A single legal empty literal such as `fetch('')`, `require('')`,
`bus.on('', f)`, `localStorage.getItem('')`, or `ipcMain.handle('', f)`
made the whole application analysis fail with `unreadable_output`: the
literal became an application-graph observation label, an artifact-local
identity key, or a semantic node label, all of which must be nonempty.
Normalize display at the two graph construction seams instead of at each
producer: `JavaScriptArtifactGraphAccumulator.addNode` and
`constructSemanticGraphNode` show the empty value as `""` via a shared
`javascriptDisplayText` helper. Observation and node properties keep the
exact empty value. This replaces the per-site `semanticNameLabel` calls.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Document the three disjoint failure taxonomies (filesystem reader
codes, session reference reasons, inventory TypeErrors) with a test
pinning their disjointness. Export ParsedInventorySet and add
tryAssembleInventorySet covering the empty-pages leaf as Result;
the throwing entry contract is unchanged until callers migrate.
Delete the private canonicalJson duplicate in
functionComparisonNormalization in favor of comparisonSemantics
(same canonicalize behavior via the context parameter).
Add comparisonStatus as the single owner of the canonical
unchanged/changed/unknown triple and conclusion vocabulary, with
mappers pinning every pipeline-native status; adopt the shared
triple schema where wire-identical (bundle result, scenario
overall/step). Native detail enums and collation choices stay
untouched.
Migrate the remaining `""`-sentinel consumers from #783 to the nullable
`semanticStaticPropertyKey`: CommonJS module origins
(`require("m")['']`), require destructuring (`const {'': a} =
require("m")`), and request body fields (`{ '': value }`). Dynamic keys
still produce no link or field. API selectors that compare against known
names are unchanged.
Fixes#783
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Record the pinned Node 24.18.0 setup and that Hopper, Ghidra, and IDA stay optional for JavaScript analysis and deterministic tests.
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
`process.env['']` now projects an exact empty environment key with
complete resolution instead of the same null/partial result as a dynamic
`process.env[key]`. `{ ['']() {} }` keeps its exact empty method name in
the IR instead of a generated `[computed@N]` name.
Semantic graph labels stay nonempty: a shared `semanticNameLabel` helper
displays the empty key as `""` for property slots, config sources, and
function nodes, while `properties.key` keeps the exact value.
Refs #783
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Report canonical BrowserExclusionReasons from runtime location
authorization (unsupported_url, not_approved) and collapse them
onto the fixed V8 wire bucket via inspectorExclusionKey, keeping
describeInspectorTargetLimitations text stable. Document the
provider authority split (attach-only CDP/V8 vs owned-runtime
Playwright) so the shared vocabulary is not re-split.
Move hasScheme/stripQueryAndFragment/admitsCanonicalPathSyntax
plus looksExternal into domain/artifactPathSyntax with the
deliberate policy-divergence table (artifact root vs allowedOrigins
vs exact-origin fetch). Adopt in JavaScriptArtifactPathResolution
and the Electron native specifier check with characterization
tests. Policy unification tracked in #829.
Move the indexed sections walk shared by the browser fetcher and
the artifact reader into domain/sourceMapEnvelope with the
fetchers stricter offset validation as an option; both validators
keep their leaf strictness. Rename the browser CDP stringValue to
cdpStringValue across its 18 files, fold the fingerprint duplicate
into the static helper, and rename the version-keys shadow to
nonEmptyString.
Inline the private memberKey/propertyKey wrappers in semantic
MemberMutations/Projection/Values to direct canonical calls.
Migrate the electron Browser/Values member keys off legacy
propertyName (provably identical: explicit computed guard retained).
Delegate bundle calleeName/endpointArgument/stringArgument to the
static helpers, adding loadURL endpoint parity with static analysis.
Bundle regressions pin nested-dynamic-receiver and loadURL parity.
Remaining computed-identifier forks in electron Native/Ipc tracked
in #822.
* feat(web): export captured scripts for JavaScript application analysis
Add capture adapters, conservative source path projection, verified exclusive publication and a shared CLI/MCP workflow. Retain source identities, missing content and competing URL versions in a complete manifest for existing static analysis.
Refs: #774Closes: #799
Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
* test(web): include script export in independent effect audit
Register the new contract family in the independent inventory audit and verify the filesystem, session, network and idempotence metadata of the named export contract.
Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
* fix(web): preserve capture limitation values in export manifests
Align the export boundary with passive capture’s string contract instead of rejecting an admitted empty limitation. Cover the publisher boundary and regenerate canonical schemas and identities.
Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
* feat(browser): capture correlated network content and lifecycle evidence
Keep request identities and redirect relationships across ordered scenario events.
Capture selected browser-exposed bytes and duplicate headers through modular
readers, settle bounded reads before cleanup, and preserve unavailable states.
Keep content-selection mismatches and legacy network coverage unknown during
comparison. Verify real CLI/MCP, installed package, and browser lifecycle paths.
Refs #774
Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
* fix(browser): align capture defaults and redact encoded media metadata
Correct the complete documented request and legacy default expectation caught by CI. Cover and redact encoded declared values in captured body media types.
Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
* test(browser): verify polling capture cutoff completeness
Accept incomplete event coverage only when the continuously polling fixture has explicit unfinished requests; retain failures for other missing or truncated sections. Include actual completeness and unfinished transactions in diagnostics.
Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
Documents NativeAOT as a native-analysis route with format/architecture limits, keeps the skill DOS-guide link inside the installed bundle convention, and regenerates the managed conformance manifest.
SafeOutputTree.create() called fchmod(0o700) on a directory handle and
commit() fsynced a directory handle. Both are POSIX-only: Windows rejects
them with EPERM ("operation not permitted, fchmod"/"fsync"), so every
extract_artifact call failed with a generic io error and produced no output.
Skip the redundant directory chmod and directory fsync on Windows. mkdir
already applies the requested mode, and file contents are synced in write().
Add a Windows regression test and run it, plus the archive-safety test, in
the curated Windows CI lane so the behavior is covered.
* docs(browser): add an interaction example that captures the visible result
Fixes#728
Co-authored-by: Cursor <cursoragent@cursor.com>
* docs(browser): wait for asynchronous search results before capture
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: N0zoM1z0 <1705004398@qq.com>
* fix(browser): classify CSP host sources by their own origin
A Content-Security-Policy host-source without a scheme (for example
`cdn.example.com` or `*.trusted.test`) was resolved with
`new URL(token, baseUrl)`, so it became a page-relative path and was
reported as the observed page's own origin. Third-party script, style, and
connect sources were therefore misreported as approved origins, and a bare
`*` wildcard collapsed to the page origin as well.
Resolve host-sources per CSP3 \u00a72.3.1: a scheme-less source inherits the
protected resource's scheme, wildcard host/port sources stay classified as a
set of origins, and non-host tokens remain `other`. Keyword and scheme
sources are unchanged.
Adds boundary coverage for scheme-less host sources, wildcards, and scheme
inheritance against the approved-origin set.
* fix(browser): validate CSP host source syntax
---------
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
* feat(ghidra): edit function annotations atomically
Return annotation readback and refreshed function analysis through CLI and MCP. Own each database transaction, invalidate caches and immutable snapshots, preserve executable bytes, and retain the Windows mutation boundary.
Assisted-by: Nitori (gensokyo-skills:nitori-reverse-engineering)
* fix(ghidra): preserve qualified function annotation identity
Preserve namespaces during local name writes and match qualified readback to the refreshed dossier. Add a producer-shaped regression and verify a real namespaced C++ function through the CLI.
Assisted-by: Nitori (gensokyo-skills:nitori-reverse-engineering)
* test(ghidra): align verification with annotation authority
Keep strict capability and profile checks while admitting the explicit session metadata operation. Verify packaged transport authority and atomic transaction commitments and preserve a read-only Windows expectation.
Assisted-by: Nitori (gensokyo-skills:nitori-reverse-engineering)
* feat(ghidra): enable Windows x64 read-only analysis
* test(ghidra): exercise native Windows runtime boundaries
* test(ghidra): verify current Windows inventory and isolate ACL observer
* fix(ghidra): align Windows admission and address P0 review
* feat(ghidra): admit explicit DOS COM analysis
Carry caller-selected COM interpretation through CLI, MCP and target
identity, seed real-mode entry/context before Ghidra analysis, and verify
complete loaded bytes, source mappings and measured register context.
Keep original binaries unchanged and PSP/runtime coverage explicit.
Assisted-by: Nitori (gensokyo-skills:nitori-reverse-engineering)
* fix(verification): validate COM package selection before allocating fixtures
* feat(ghidra): verify DOS load images and expose memory evidence
Verify measured source bytes, mapped regions, fixups and entries against
the immutable MZ snapshot, retaining independent checks and raw evidence.
Expose loaded byte reads and authoritative original file offsets through
both CLI and MCP, with focused and actual Ghidra DOS verification.
Assisted-by: Nitori (gensokyo-skills:nitori-reverse-engineering)
* fix(cli): describe memory inspection arguments
* test(ghidra): align bridge fixtures and CLI capability accounting
* chore(deps): finish toolchain upgrades and drop dead weight
pino 9 to 10, @types/node 24 to 26, oxlint 1.73 to 1.87, knip 6.26
to 6.39, turbo 2.10 to 2.11. Narrow engines to supported majors
(22/24/26; vitest 5 refuses Node 25). Scope no-var-requires off for
Electron CJS hooks and fixtures.
Remove TypeDoc: incompatible with TypeScript 7 at install and
runtime, used by nothing in any gate. Drop the dep, docs:api
workflow, typedoc.json, CI artifact step, and related docs.
Replace graphology with a local call-graph adjacency plus BFS: the
only consumer is call-path search, and graphology-types ships no
types entry for TS7 NodeNext resolution. Delete both graphology
dependencies.
Remove dead re-exports newly flagged by knip 6.39.
* chore: drop stale typedoc and replay references
Remove the docs:api release-checklist step, the orphaned docs/api
ignore entry, and the nonexistent replay glob from the adapters
project.
* refactor(domain): split error taxonomy into thematic modules
Move each error family out of domain/errors.ts into its own module
(base, core, provider selection/adapter, browser observation,
artifact, evidence, unknown registry, hopper, configuration) and
relocate AnalysisErrorProjection to analysisErrorProjection.
Migrate all 162 importers to the owning modules and delete
errors.ts. No re-export shims; behavior is unchanged.
* refactor(runtime): name all silent catch causes without changing diagnostics
Bind cause in every bare catch and unhandled rejection across src/.
Real failures preserve the cause for logging; best-effort cleanup
carries an explicit comment. Caller-visible and Evidence strings are
byte-identical to before.
Move each error family out of domain/errors.ts into its own module
(base, core, provider selection/adapter, browser observation,
artifact, evidence, unknown registry, hopper, configuration) and
relocate AnalysisErrorProjection to analysisErrorProjection.
Migrate all 162 importers to the owning modules and delete
errors.ts. No re-export shims; behavior is unchanged.
Move official, enhanced, and session contract arrays with their
builders into officialToolContracts, enhancedToolContracts, and
sessionToolContracts. toolContracts keeps the ordered assembly and
resolver. Migrate all importers including catalog scripts. No
re-export shims; generated catalog output is unchanged.
typescript 5.9.3 to 7.0.2, vitest 4.1.10 to 5.0.3 (plus
@vitest/coverage-v8 and @fast-check/vitest 0.5.0 for peer compat),
@Modelcontextprotocol/client and server 2.0.0 to 2.3.1. Migrate the
removed describe.sequential to concurrent:false and regenerate
package metadata and product catalog.
Also restore byte-faithful reads in parseCliJsonInput: the safeJson
migration dropped the fatal UTF-8 check from #613. Vitest 5 requires
Node 22/24/26+, so verify on Node 24 (repo-pinned toolchain).
* refactor(domain): consolidate canonical ordering and digest helpers (#624)
* refactor(domain): consolidate canonical ordering and digest helpers
Single owner for code-point ordering (domain/canonicalOrdering.ts)
and canonical JSON digests (domain/comparisonSemantics.ts). Delete
all local compareCodePoints/compareText/digestCanonical duplicates
and migrate every importer. No re-export shims.
* fix(ci): allow slower real browser startup
* chore(config): remove dead eslint, dedupe scripts, cacheable turbo tasks
Delete eslint.config.js (oxlint is the linter), drop lint:dead alias,
pin smol-toml, fold jscpd/scan:todos into check:pr, make test:run
cacheable, align oxlint ignores.
* fix(config): hash all test inputs for cached runs
* docs: fix architecture diagram and pretty-print tool catalog
Drop dangling REPLAY edges, add dotnet/reference/error/evaluation
nodes. Emit 2-space JSON from the catalog generator and regenerate.
* test: extract shared fixtures, drop knip carve-outs
Dedupe android/apple session tests, bundler adapter headers, and
reconstruction helpers into tests/support fixtures. Delete unused
type aliases and the knip ignoreIssues block. Lower jscpd threshold
2.7 to 2.5.
* refactor(app): split Setup and ProcessOwnership modules
Extract SetupTypes/SetupHost from Setup.ts and move observation
helpers into ProcessOwnershipObservation/ProcessTree. Migrate all
importers including CLI commands. No re-export shims.
* refactor(runtime): centralize safe JSON parsing and preserve error causes
Add domain/safeJson.safeParseJson and migrate all raw JSON.parse
call sites. Name catch causes and preserve failure reasons instead
of swallowing; annotate genuine best-effort cleanup.
* fix(runtime): retain JSON parse error causes
* refactor(domain): consolidate canonical ordering and digest helpers (#624)
* refactor(domain): consolidate canonical ordering and digest helpers
Single owner for code-point ordering (domain/canonicalOrdering.ts)
and canonical JSON digests (domain/comparisonSemantics.ts). Delete
all local compareCodePoints/compareText/digestCanonical duplicates
and migrate every importer. No re-export shims.
* fix(ci): allow slower real browser startup
* chore(config): remove dead eslint, dedupe scripts, cacheable turbo tasks
Delete eslint.config.js (oxlint is the linter), drop lint:dead alias,
pin smol-toml, fold jscpd/scan:todos into check:pr, make test:run
cacheable, align oxlint ignores.
* fix(config): hash all test inputs for cached runs
* docs: fix architecture diagram and pretty-print tool catalog
Drop dangling REPLAY edges, add dotnet/reference/error/evaluation
nodes. Emit 2-space JSON from the catalog generator and regenerate.
* test: extract shared fixtures, drop knip carve-outs
Dedupe android/apple session tests, bundler adapter headers, and
reconstruction helpers into tests/support fixtures. Delete unused
type aliases and the knip ignoreIssues block. Lower jscpd threshold
2.7 to 2.5.
* refactor(app): split Setup and ProcessOwnership modules
Extract SetupTypes/SetupHost from Setup.ts and move observation
helpers into ProcessOwnershipObservation/ProcessTree. Migrate all
importers including CLI commands. No re-export shims.
* refactor(domain): consolidate canonical ordering and digest helpers (#624)
* refactor(domain): consolidate canonical ordering and digest helpers
Single owner for code-point ordering (domain/canonicalOrdering.ts)
and canonical JSON digests (domain/comparisonSemantics.ts). Delete
all local compareCodePoints/compareText/digestCanonical duplicates
and migrate every importer. No re-export shims.
* fix(ci): allow slower real browser startup
* chore(config): remove dead eslint, dedupe scripts, cacheable turbo tasks
Delete eslint.config.js (oxlint is the linter), drop lint:dead alias,
pin smol-toml, fold jscpd/scan:todos into check:pr, make test:run
cacheable, align oxlint ignores.
* fix(config): hash all test inputs for cached runs
* docs: fix architecture diagram and pretty-print tool catalog
Drop dangling REPLAY edges, add dotnet/reference/error/evaluation
nodes. Emit 2-space JSON from the catalog generator and regenerate.
* test: extract shared fixtures, drop knip carve-outs
Dedupe android/apple session tests, bundler adapter headers, and
reconstruction helpers into tests/support fixtures. Delete unused
type aliases and the knip ignoreIssues block. Lower jscpd threshold
2.7 to 2.5.
* refactor(domain): consolidate canonical ordering and digest helpers (#624)
* refactor(domain): consolidate canonical ordering and digest helpers
Single owner for code-point ordering (domain/canonicalOrdering.ts)
and canonical JSON digests (domain/comparisonSemantics.ts). Delete
all local compareCodePoints/compareText/digestCanonical duplicates
and migrate every importer. No re-export shims.
* fix(ci): allow slower real browser startup
* chore(config): remove dead eslint, dedupe scripts, cacheable turbo tasks
Delete eslint.config.js (oxlint is the linter), drop lint:dead alias,
pin smol-toml, fold jscpd/scan:todos into check:pr, make test:run
cacheable, align oxlint ignores.
* fix(config): hash all test inputs for cached runs
* docs: fix architecture diagram and pretty-print tool catalog
Drop dangling REPLAY edges, add dotnet/reference/error/evaluation
nodes. Emit 2-space JSON from the catalog generator and regenerate.
* refactor(domain): consolidate canonical ordering and digest helpers (#624)
* refactor(domain): consolidate canonical ordering and digest helpers
Single owner for code-point ordering (domain/canonicalOrdering.ts)
and canonical JSON digests (domain/comparisonSemantics.ts). Delete
all local compareCodePoints/compareText/digestCanonical duplicates
and migrate every importer. No re-export shims.
* fix(ci): allow slower real browser startup
* chore(config): remove dead eslint, dedupe scripts, cacheable turbo tasks
Delete eslint.config.js (oxlint is the linter), drop lint:dead alias,
pin smol-toml, fold jscpd/scan:todos into check:pr, make test:run
cacheable, align oxlint ignores.
* fix(config): hash all test inputs for cached runs
* refactor(domain): consolidate canonical ordering and digest helpers
Single owner for code-point ordering (domain/canonicalOrdering.ts)
and canonical JSON digests (domain/comparisonSemantics.ts). Delete
all local compareCodePoints/compareText/digestCanonical duplicates
and migrate every importer. No re-export shims.
* fix(ci): allow slower real browser startup
Replace inline magic comparisons with an exhaustive fatHeaderFormat
switch and add a regression test locking in rejection of 32-bit
slice payloads inside little-endian containers. Behavior-preserving:
the new test passes on the old implementation.
Equivalent hexadecimal addresses no longer collapse a fully observed CFG to unknown, and duplicate numeric block starts are rejected even when spelled differently.
Cancel ZIP extraction promptly when an unread consumer applies backpressure, releasing the producer instead of leaving it parked on a drain that can never arrive.
## Changes
Related to #545 and the permission-system removal in #555.
- Upgrade the shipped skill to v24 and remove obsolete filesystem grants, per-call approval flags, Electron file-root configuration, and DMG approval flags. Calls follow the user-requested investigation directly. Keep setup plan confirmation, actual OS requirements, and process/archive lifecycle boundaries.
- Correct the passive browser guide: endpoint/scope come from requests; ordinary local URL queries are retained, while credentials remain redacted.
- Audit canonical tool effects: declare possible DMG process/temp-directory effects, mark fresh extraction non-idempotent, and mark comparisons of supplied captures/PNGs as closed-world. Align artifact-provider capability effects with temporary mount-directory writes.
- Retain non-read-only hints for calls that add Evidence to the session; document that annotations are hints and that clients control their confirmation UI. Do not mislabel session mutations as read-only to suppress prompts.
- Regenerate package, skill, MCP, and product metadata from source.
## Verification
- `npm run test:focused -- <11 affected test files>`: **40 tests passed**, including skill transaction/backup/idempotence, SDK tools/list annotations, actual local capture/PNG comparisons, artifact extraction/containment/cancellation, DMG launcher/cleanup seam, setup confirmation, browser MCP and scenario MCP, CLI catalog parity.
- `npm run check`: typecheck, lint, format, knip, package metadata.
- `npm run docs:check`: generated catalogs, skill metadata, documentation facts, completion ledger, error schema.
No local real Hopper/Ghidra run: their adapters and analysis operations are unchanged. Native macOS DMG behavior is covered locally through the launcher seam; no local macOS/hdiutil claim is made.
Real browser verification passed using existing Headless Chrome143.0.7499.4: actual CLI/stdio MCP,9,331,407-byte PNG, passive capture/source maps, and owned/external scenario cleanup. An initial full Chrome143 run failed the existing screenshot-height assertion (1397 versus1536); the dedicated headless-shell run passed the complete verifier without code changes. The verifier run-lineage field remained unavailable; no lineage-coverage claim is made. Browser download into `.codex` was blocked by CDN403, so the successful run used an existing browser without changing host configuration.
* fix(browser): derive source-map imports from syntax nodes
Signed-off-by: Rudy Celekli <47457359+rudycelekli@users.noreply.github.com>
* fix(browser): recover source-map dependencies from decorated and aliased sources
Discarding a source's edges whenever it had parse errors cost more than it
protected. parseJavaScriptSource only enabled jsx and typescript, so a
decorated TypeScript source did not parse at all and contributed no edges at
all, even for the imports Babel could otherwise have read. That is the common
shape for the bundles this boundary inspects. "decorators-legacy" is enabled
instead of "decorators" because the standard form still rejects parameter
decorators such as constructor(@Inject() private s: S), which is the Angular
and Nest dependency-injection shape.
import x = require("m") parses cleanly but is a TSImportEqualsDeclaration
rather than a call expression, so it contributed no edge. It is now read as a
require dependency. It is only legal at module top level and always refers to
the host loader, so it needs no unbound-require check; the local-alias form
imports an entity name and still declares nothing.
A source whose syntax could not be recovered now yields status "partial" with
a limitation naming the affected sources, instead of an included item whose
empty edge list was indistinguishable from a source that genuinely imports
nothing. Edges that did parse are retained and the caller is told the list is
a subset, which matches how the static and semantic analysers already report
recovered syntax.
The source-map item status union gains "partial" and the coverage rollup now
counts it as retained, so a collection of only-partial items reports partial
rather than unavailable.
* Merge main into fix(browser): derive source-map imports from syntax nodes
Resolve the generated-file conflicts by taking main's generated output and
regenerating from the merged source contracts, rather than merging generated
text by hand.
---------
Signed-off-by: Rudy Celekli <47457359+rudycelekli@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
* fix(javascript): honor package exports condition order
Signed-off-by: Rudy Celekli <47457359+rudycelekli@users.noreply.github.com>
* fix(javascript): resolve exports against Node's full condition set
The declared-order fix selected targets against {default, import|require},
but Node's active set for the resolver that owns installed packages also
includes "node" and "node-addons". Ordering only means something against the
full active set, so a package declaring {"node", "import"} resolved to the
wrong target, and a package declaring only {"import"} reported no target
where Node resolves ./node.cjs.
Nested condition objects and fallback arrays are also valid Node targets.
They are now flattened in Node's own order: a condition object stops at its
first active key, so a null or unmatched nested target ends the search, while
an array skips the entries it cannot resolve and concatenates the rest. Node
does not fall through a target whose file is absent, so the first flattened
target stands and its absence is reported rather than skipped.
A valid exports map that matches no active condition is reported as external
with the declared condition names, and one that selects an unsupported nested
or array target no longer borrows the "not valid package JSON" reason.
The differential test installs a real package and resolves the same bare
specifier through Node and through REA, mirroring file presence between the
filesystem and the inventory. 18 of the 25 cases fail without this change.
* style: apply Prettier to the conditional exports differential test
---------
Signed-off-by: Rudy Celekli <47457359+rudycelekli@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
* fix(javascript): respect HTML base URL components
Signed-off-by: Rudy Celekli <47457359+rudycelekli@users.noreply.github.com>
* fix(javascript): resolve HTML base href dot segments and gate base syntax
A relative HTML reference resolves against the base URL's directory, and that
directory drops a trailing "." or ".." segment rather than stepping through
it. Only a trailing "/" was treated as a directory, so <base href=".">
resolved against the artifact root instead of the document directory, and
<base href="sub/."> resolved against the parent of "sub".
The base href is also a second untrusted path input, but rejectDeclaration
only applied its admission rules to the declared path, so an encoded-traversal
or backslash base href relied on files-map confinement to stay safe. Both
inputs now share one admitsCanonicalPathSyntax predicate, and a local base
href is rejected with a reason naming the base href rather than a generic
declared-path message. External base hrefs are still reported as external,
so an encoded path on an unreachable origin keeps the more accurate reason.
7 of the new cases fail without this change.
* style: apply Prettier to the HTML base resolution changes
---------
Signed-off-by: Rudy Celekli <47457359+rudycelekli@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
* fix(comparisons)!: preserve unknowns across partial observations
Share absence and digest semantics, keep unobserved managed bodies unknown, and match unique managed type/name/signatures before structural fallback.
BREAKING CHANGE: Managed comparison metadata adds exact-signature matching and its count, and name_matching now reports exact-signature-fallback.
* fix(javascript): preserve projected result binding semantics
Share syntax-aware property reads and assigned-result resolution. Retain destructuring paths and downgrade downstream whole-result relationships instead of resolving nested or wrapped calls as aliases.
* fix(native)!: admit complete parser values and preserve typed failures
Decode Mach headers by named columns, validate complete slice keys and lipo alignment, and preserve codesign runtime flags and tagged parser errors. Rename the Ghidra test dossier fixture and connect fake-backed suites to real verification lanes.
BREAKING CHANGE: Native load-command results no longer contain the unused, always-null file_offset field.
* fix(process): preserve host identity and actionable boundary failures
Thread selected platform and environment through process and Doctor seams, stamp observed producer identity in Evidence, and retain PTY, filesystem, lease and lazy-provider failure causes. Drain cancelled lazy loads and omit exited descendants from verified lineage.
* fix(browser): preserve cleanup and document-transition evidence
Make V8 and Playwright teardown cancellation-aware, expose primary failures alongside incomplete cleanup, share frame-tree and navigation rules, and clear stale WebMCP registrations without pruning unrelated child frames.
* fix(adapters): align managed targets and typed CLI outcomes
Inspect managed PE/CLI targets independently of native provider selection, reuse successful managed selections, and keep evidence bound to the actual inspected target. Classify canonical CLI error envelopes and exhaustive setup/update/uninstall outcomes, audit registered CLI coverage, and assert platform-specific runtime results.
* docs: refresh boundary contracts and shipped roadmap behavior
Return complete canonical Evidence records inline, including normalized_result, and preserve direct comparison and retained bundle identity.
Verified full deterministic gate, real Linux Ghidra CLI/MCP and independently installed artifact, generic package acceptance, private local samples, and targeted updates after syncing main.
Closes#551
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
* feat(setup)!: expand agent integrations and simplify onboarding
Add native configuration formats for OpenCode, Antigravity, GitHub Copilot
CLI, VS Code, and Devin. Preserve JSONC comments and unrelated settings
while making setup and uninstall ownership-aware and idempotent.
Select agent targets before planning, separate discovery from intent, and
keep agent-only setup independent of optional provider prerequisites.
Cover configuration boundaries and interactive behavior in packaged checks.
BREAKING CHANGE: unscoped setup refreshes only existing REA-owned
registrations. Use --all-detected to configure every detected client.
Setup JSON contains a compact doctor summary; use rea doctor for full
diagnostics. Cancellation and successful dry runs now exit successfully.
* feat(cli)!: replace upgrade with verified updates
Resolve an exact release through npm's configured registry, update only the
identified installation, and verify its new executable before reporting success.
Return a read-only maintenance plan for existing enabled REA integrations.
BREAKING CHANGE: replace rea upgrade with rea update; no alias is retained.
Successful update JSON uses status "updated", reports the verified installed
version, and returns an unapplied maintenance plan instead of opening setup.
Correlate typed labels with recovered block entries and one indirect dispatch.
Preserve ambiguous and nonexact integer associations as unknown with raw diagnostics.
Expose defaults separately, collect backing load metadata, and invalidate old profiles.
Add independent compiler-byte CLI/MCP acceptance and actual Ghidra model controls.
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning)
* fix(hopper): report unavailable procedure body coverage
* refactor!: simplify runtime tools and remove replay engines
Keep direct inspection, capture, and comparison tools. Bind handlers to named contracts and let agents compose experiments with commands and local fixture servers.
BREAKING CHANGE: Remove controlled replay, Node characterization, finite replay-machine, managed runtime planning, and redundant string-tracing tools. Retire process replay, shims, reactive scenarios, custom checkpoints, and active browser replay and origin-scope inputs.
Validate DOS MZ load modules and import them with Ghidra's 16-bit
real-mode profile. Preserve complete observed inclusive function body
ranges through inventory, function analysis, Evidence and snapshots.
Add a public source-generated DOS CLI/MCP verification lane and
regressions for malformed headers, body membership and cache profiles.
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning)
* fix(platform): accept absolute paths for any host and stop blaming the ceiling for a missing grant
Addresses #548 and #545.
#548: processScenarioSchema required a leading "/" for executable,
working_directory and filesystem_roots, so no process scenario could be
expressed on Windows at all. The report suggested node:path's isAbsolute, but
that answers for the host running the check: on Linux `C:\tools` is not
absolute, so a scenario captured on Windows would fail validation when it is
replayed, compared, or asserted in a test on another host. A boundary schema
must not vary with its evaluator, so the check accepts the POSIX form, a
Windows drive path and a UNC share everywhere. The rejection message now names
the constraint instead of leaving the caller to infer it from "invalid request".
The HTTP `path` field inside `checkpoints` is an URL path and is deliberately
left alone.
I checked whether this merely moved the failure downstream: containment is
enforced by isPathWithinRoot, which already uses host-aware path.relative, so
validation really was the only blocker.
#545: when a scope is inside the administrator ceiling but no grant was ever
issued, the denial still pointed at widening the ceiling -- advice that cannot
help, since the ceiling already permits the operation. The `missing` payload is
computed against candidate *grants*, so it describes what a grant must cover,
not a ceiling gap. `PermissionRemediation` gains a `grant` variant saying
exactly that, and PermissionAuthority selects it when the denial is not a
ceiling violation. An explicitly requested remediation is still honoured, and a
genuine ceiling violation still says "configure".
* refactor(config): take the environment as an input at every configuration read
Completes B-2. Every `parseConfig(process.env)` site now reads from an
injected environment, so configuration-driven behaviour is a function of an
argument rather than of the machine running it.
The twelve sites were not equivalent, and treating them as one number would
have hidden the difference:
- **src/application/ (3 sites) were genuine defects.** `runSessionStatus`
already injected its `logger` but hardcoded `process.env` for config, so the
MCP path's `dependencies.env` never reached it; `captureProcessScenarioFile`
and `runAnalysis` had the same problem. `runAnalysis` gained `environment` on
the options object it already had, which is where its other injected
dependencies live.
- **The CLI command layer (9 sites) is a documented boundary,** where
`process.env` is legitimate. Rather than 9 independent ambient reads, they
now share one seam: `createCli(environment)` passes it to the seven
registrars that need configuration, and the nested helpers (`electronContext`,
`runtimeContext`, `loadConfiguredAuthority`, `inspectJavaScriptReplay`) take
it explicitly.
Every new parameter defaults to `process.env`, so all existing call sites are
unchanged and production behaviour is identical. The point is that the ambient
read is now a documented default at a boundary rather than a hidden dependency
deep inside behaviour.
`process.env` now survives in `src/` only as those default parameters —
nothing reads it at the point of use.
* style(cli): apply prettier formatting to the runtime observation command
Addresses #548 and #545.
#548: processScenarioSchema required a leading "/" for executable,
working_directory and filesystem_roots, so no process scenario could be
expressed on Windows at all. The report suggested node:path's isAbsolute, but
that answers for the host running the check: on Linux `C:\tools` is not
absolute, so a scenario captured on Windows would fail validation when it is
replayed, compared, or asserted in a test on another host. A boundary schema
must not vary with its evaluator, so the check accepts the POSIX form, a
Windows drive path and a UNC share everywhere. The rejection message now names
the constraint instead of leaving the caller to infer it from "invalid request".
The HTTP `path` field inside `checkpoints` is an URL path and is deliberately
left alone.
I checked whether this merely moved the failure downstream: containment is
enforced by isPathWithinRoot, which already uses host-aware path.relative, so
validation really was the only blocker.
#545: when a scope is inside the administrator ceiling but no grant was ever
issued, the denial still pointed at widening the ceiling -- advice that cannot
help, since the ceiling already permits the operation. The `missing` payload is
computed against candidate *grants*, so it describes what a grant must cover,
not a ceiling gap. `PermissionRemediation` gains a `grant` variant saying
exactly that, and PermissionAuthority selects it when the denial is not a
ceiling violation. An explicitly requested remediation is still honoured, and a
genuine ceiling violation still says "configure".
Keep explicitly selected Node Inspector targets observable when discovery
cannot verify their file location. Resolve literal POSIX discovery paths
without URI decoding, and retain lossy Windows or underscore paths as
unresolved metadata. Validate scriptParsed file URLs independently.
Preserve unknown target identity through runtime reconciliation, regenerate
contracts, and verify real CLI/MCP behavior on Linux and Windows.
Closes#530
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
Replace empty tuples with a shared empty-array schema. Validate all input
and output schemas against Draft 2020-12 during catalog generation and
packaged MCP verification, with runtime and catalog regression coverage.
Closes#528
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
* fix(win32): probe .cmd/.bat runtime shims via cmd.exe to avoid spawn EINVAL
Node >= 18.20 refuses to spawn .cmd/.bat files without a shell
(CVE-2024-27980 mitigation) and throws spawn EINVAL. On Windows, the
npm and npx PATH shims are .CMD files, so doctor's runtime toolchain
probes always failed even on a healthy install.
Route batch-file candidates through cmd.exe /d /s /c with the command
line as a single quoted argument and windowsVerbatimArguments.
* fix(win32): thread platform through version probe and harden batch quoting
- windowsBatchCommand takes platform/systemRoot params instead of reading
process.platform directly, so it is unit-testable off Windows
- double embedded quotes in the cmd.exe /c string to block breakout
- replace spawn-based win32 tests with pure helper units plus a
win32-only temp .bat probe
---------
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
* fix(process): normalize reactive rendered-frame timestamps
A reactive `resize` action stamped `rendered_frames[].at_ms` with the raw
elapsed time while every other rendered frame used
`normalizeProcessElapsedTime`. Under the default 10ms time bucket the next
frame buckets down and appears to move backwards, so `parseProcessCapture`
rejected the entire capture with "rendered_frames: timestamps must be
ordered". No test combined a reactive resize with time bucketing, so the
path was never exercised.
Thread the scenario's bucket into the reactive effect host and normalize the
renderer call, matching what the scheduled-event resize path already did.
`dispatched_at_ms` and `captured_at_ms` stay raw on both paths, so this
changes only the one inconsistent clock.
Also replace the wall-clock-scheduled interactive PTY scenario with
terminal_text triggers. A fixed `at_ms` could fire before the child wrote
its prompt under host contention, dropping the input and the resize echo.
That rewrite is what surfaced this bug, and it now passes deterministically.
Replace the 11 `if (!capability.available) return;` guards across the PTY
suite with a shared it.skipIf gate. The old form reported a green pass with
zero assertions on any host lacking native PTY authority; skips are now
named and reported.
Verified by reverting only the normalization, which reproduces the
validation failure immediately.
* fix(install): add recovery guidance to version-mismatch failure
Every installer failure except one told the user what to do next. The
version-mismatch failure reported only that the installed version did not
match, with no remedy, which contradicts the requirement to keep
diagnostics actionable for mismatch locations.
Add a remedy in the same style as the neighbouring failures and drop the
exemption the test carried for it, so all ten installer failures now assert
they carry a recovery action.
* ci: repair stale curated Windows lane and unblind the duplication gate
The `windows-curated` job listed fifteen test files and nine of them no
longer existed, including six `processOwnership*` files moved to
`src/process/` in 4ecc7a72. Vitest silently drops unmatched paths, so the
job ran six files and reported success. Repoint the paths at their current
locations and add a test that fails when any listed path is renamed or
removed, so the lane cannot silently lose coverage again.
The duplication gate ignored `**/*.test.ts`, so it reported zero clones
across the test tree while running on every PR. Include test files, remove
the two largest duplicated clusters, and ratchet the threshold to the
measured result so the gate can no longer pass by not looking.
Run local tests with two workers instead of one. A single worker made a
full local run cost ~140s of wall time at ~100% CPU on a 10-core host,
which was the largest dev-cycle cost in the repository. Local now matches
the concurrency CI already proves green, and PTY scenarios moved to a
serial project because they contend for host terminal resources. Full local
suite: 140s to ~89s.
Regenerate the managed conformance manifest. Commit 4ecc7a72 edited
SKILL.md without refreshing the digest, so `npm run check:pr` has been
failing on main since that commit.
* test: replace implementation lock-in with behavioural assertions
Audit the suite for tests that cost maintenance without catching defects,
then remove the lock-in rather than the coverage.
Replace assertions that froze incidental detail:
- toolContracts.test.ts pinned group sizes and 50 lines of literal tool
names, so any additive catalog change required a test edit. Replace with
four structural invariants: global name uniqueness, group containment in
the published inventory, group disjointness, and non-empty groups. Both
invariants are mutation-checked by orphaning and duplicating a tool.
- Six tests asserted only that a schema accepts its own canonical fixture.
Replace five with real rejections and two with property tests covering
the invariants those tests were gesturing at: `isDbSaveComplete` is
downward closed in every expected count, and frame retention holds at
any size.
- A concurrency test whose fake returned `? [] : []` could not fail. Give
the fake real shared state so a lost update is observable.
- providerProcess.test.ts asserted listener and timer counts plus exact
cleanup retry counts. Assert detachment behaviour instead, so an
unrelated internal timer no longer breaks the test.
- Scale tests that rebuilt removed caps: 16 MiB and 10,001 files to prove
limits that no longer exist, 100,001 frames compared against their own
length, and a projection asserting a literal 10,201 bridge candidates.
Replace with derived relationships that hold at any size.
- installScript.test.ts merged two tables and now asserts alongside the
exact wording that every failure carries a recovery action.
- cdpBrowserProvider.sensitive_data asserted outcomes produced after the
observation window closes while using a zero-length window; give it a
real window so it measures the malformed-body rejection rather than host
speed.
- runtime.test.ts repeated the catalog assertion from the MCP boundary
suite while spawning a second stdio server. Give the database-kind
scenario its own claim and make stale-build failures legible.
Extract two byte-identical fixture preambles that the max-lines rule had
split across five and three files respectively, removing ~1,000 duplicated
lines.
Profile the heaviest files rather than only running them: the Apple
projection test drops from 6.4s to 0.28s and the reference source import
from 2.3s to 0.2s, with stronger assertions in both cases.
* ci: keep native-authority suites out of the curated Windows lane
CI showed the repointed curated list was red. Three of the restored files
require verified Windows native authority, which windows-latest does not
provide by design:
- src/ghidra/GhidraProvider.test.ts, the replacement for the deleted
tests/boundary/providers/ghidra/ghidraProvider.test.ts
- tests/boundary/providers/ghidra/ghidraClient.test.ts
- tests/boundary/process/providerProcess.test.ts
All three fail with PrivateRuntimeRootUnavailableError, because Job Object
process ownership and private-runtime DACL enforcement are unimplemented.
The previous ghidraClient and providerProcess entries were added in this
branch and never belonged here; the GhidraProvider replacement does not
inherit the deleted file's Windows behaviour.
Those claims belong behind the same approval boundary as the real Ghidra
Windows workflow rather than the default lane. Record the exclusion in the
guard test so the lane cannot regress to red, and in ci.yml so the next
reader knows the omission is deliberate.
The lane now runs 14 files, up from the 6 it silently ran before, all
verified green on windows-latest.
* test: stop max-lines from forcing test files to split
The 500-line cap on test files only ever produced duplication. It chopped one
binary session suite across nine files whose names were truncated
mid-sentence, and it is why the curated Windows lane referenced six
`processOwnership*` paths that had been split apart in the first place.
Turn the cap off for tests and fixtures, keeping the function-length limit,
then merge the nine binary session files back into one suite. That restores
all 22 cases under a single module registry instead of nine and cuts the
composition project from 20 files to 12. The merged cases become nine
top-level describes grouped by concern, because a single wrapping describe
would itself breach the function-length limit.
Drop applicationWorkflowVerifier.test.ts. Its first case asserted
`verified: true`, which the script emits as a literal after its own checks,
so it could not fail, and every remaining assertion was `expect.any`. Its
second case asserted an export-shape comparison that
applicationWorkflowCli.test.ts already asserts through the product CLI,
which is the stronger claim.
Finally, five javascriptSemanticAnalysis files imported `it` from
@fast-check/vitest while containing no properties. Import `it` from vitest
so those files no longer read as property-based coverage.
* test: stop creating temp scaffolding the temp helper immediately deletes
`createTestTempDirectory` called `createTestWorkspace`, which creates `home`
and `xdg/{config,cache}`, then deleted two of those three directories so the
caller would receive an empty root. Every caller paid three `mkdir` calls and
two `rm` calls per temporary directory for scaffolding it never used, across
roughly a hundred test files.
Create the directory directly instead. Callers that genuinely need a home or
XDG tree can call `createTestWorkspace`.
* test: merge the split process reactive runtime suite
Five files shared one describe name in pairs and re-imported the same fixture
helpers. With the shared preamble already extracted into
processReactiveRuntime.fixture.ts, merge them into one suite of five
top-level describes grouped by concern. All 12 cases are preserved and the
domain project drops from 92 files to 88.
* test: drop two identity round-trips from node runtime characterization
One test built a plan with `max_calls: 10_001` and asserted the field came
back as 10_001, which asserts that the plan constructor copies a field the
test just set, and freezes a former ceiling in the process.
The other built a 201-character alias and asserted it parsed back to the
same string, which round-trips a value the test created.
Neither could fail for a reason that matters. The remaining cases still
cover preparation, stale-plan rejection, single dispatch, and artifact write.
* test: hoist duplicated graph fixtures into the shared fixture module
Eleven copies of three helpers were spread across the seven
javascriptApplicationGraph files: `completeCoverage` five times,
`nodeByLabel` four times, and `firstOf` twice, all byte-identical. The
fixture module already carried a private `completeCoverage`.
Export all three from javascriptApplicationGraph.fixture.ts and import them,
removing 95 duplicated lines.
* test: separate the reactive fixture's two PTY writes
The multi-source run resolved target_lost instead of passed intermittently.
The ready transition matches terminal text "Ready" and consumes that
observation, advancing the terminal frontier; the collecting state then
needs "Collecting" in a later observation. The fixture wrote both back to
back, so the PTY sometimes coalesced them into one chunk and the collecting
trigger could never match.
Move the "Collecting" write after the synchronous shim probe. The probe takes
real wall time, so the reader has drained the first chunk before the second
is written, which makes the ordering deterministic rather than timing
dependent.
Measured 33/34 isolated passes, against roughly even odds before. Under four
concurrent copies it still failed 2 of 12, so this narrows the window rather
than closing it: the underlying race is that node-pty delivers buffered
output through a callback the exit path never awaits, so the harness can
declare the target lost before the last chunk is ingested. The test is left
strict because it is correctly detecting that.
* test: replace expect.any placeholders with real results
Four acceptance scenarios and one composition scenario asserted only that a
field was a string, number, object, or array. Those assertions cannot fail
for a reason that matters, and three of them sit behind real CLI process
spawns that cost about 1.5s.
Capture the actual results once and assert them exactly. The CLI parity
scenario now pins the trace summary and coverage, the version comparison
summary and coverage, and the source-to-bundle summary and coverage, so each
spawn earns its cost. The MCP rejection case now asserts `invalid_request`
with category `invalid_input`, which is what makes it a caller-input failure
rather than a provider one.
The artifact comparison case asserted three `expect.any` values immediately
before an assertion that subsumed them. Replace them with the claim that
actually matters above 500 entries: manifest counts must reconcile with the
arrays returned, and every written file must appear as an occurrence, so a
reintroduced truncation would fail.
* test: remove impossible and incidental prompt assertions
Two assertions in toolResult could never fail: each asserted that the
serialized result did not contain a string that appears nowhere in its own
inputs, so only in the assertion itself.
promptContracts asserted that a `Set` built from a locally declared six
element literal had no duplicates, and pinned thirteen incidental fragments
of rendered prompt prose. Drop the tautology and reduce the prose block to
the five properties an analyst actually depends on: caller input framed as
data rather than instruction, tools offered as options rather than a
mandated sequence, the epistemic vocabulary present, tools never framed as
authorization, and deterministic suggestion order.
* test: hoist the remaining duplicated graph fixtures
Eight more byte-identical helper copies across the javascriptApplicationGraph
files: `graphForNode` four times, `unknownEvidence` twice, and `contentNode`
twice. Move them into javascriptApplicationGraph.fixture.ts alongside the
three hoisted earlier, and drop the imports they left behind.
Net -92 lines across the seven files.
* test: drop enhancedTools helpers already in the shared harness
Three of the six enhancedTools files still carried local copies of
PROCEDURES, inventory, and emptyBounded that are byte-identical to the
exports added to enhancedToolsHarness.ts. Import them instead.
Only fixturePort, connect, and jsonResult differ per file, so those stay
local.
* test: replace repeated process-tree event literals with fixture builders
The file spelled out nineteen thirteen-field event literals and thirteen-field
process nodes inline, varying only three or four fields each, so a test read as
a wall of repeated boilerplate rather than the transitions under test.
Add eventProcessTree.fixture.ts with spawn, exit, re-exec and reparent
builders plus a process-node builder, and express each case as the sequence it
describes. The test drops from 422 to 214 lines with all nine cases intact.
* test: share the process-ownership validation fixtures
The two process-ownership validation files each declared byte-identical copies
of an `ownership` constant and a 24-line `host` builder. Move both into
ProcessOwnership.fixture.ts and import them.
* test: make rejection and retention assertions exact
The reactive scenario rejection table asserted only that each of its six
fixtures failed to parse. A typo anywhere in a fixture would satisfy that,
including one that invalidated an unrelated field. Record the field each row
is meant to invalidate and require the reported issue to point at that path
with the expected code. Verified by making one row valid except for an
unknown key: the row now fails instead of passing for the wrong reason.
The large-body replay test asserted that the serialized result exceeded five
million characters as a proxy for the bodies being retained, which escaping
or padding could satisfy even under truncation. Compare each retained body to
the input byte for byte and total the retained length. Verified by shaving one
byte off the expected value, which now fails.
* test: share the elicitation grants fixtures
The three processCaptureElicitationGrants files each declared the same five
helpers inline: an elicitation request, a fixed clock, a ceiling-only
permission authority, a request-context builder, and a verified-state stub.
Move them into elicitationGrantsHarness.ts and import them.
* fix(process): wait for trailing PTY chunks before declaring target loss
The exit path drained the reactive coordinator and then submitted
target_lost, but node-pty delivers buffered output through onData callbacks
that run outside the coordinator's queue. A trailing chunk that had not been
delivered yet produced no journal entry, so the drain had nothing to wait for
and the target was declared lost while a terminal trigger was still
satisfiable. That is what made the multi-source reactive fixture resolve
target_lost instead of passed at roughly even odds.
Yield to the event loop until the capture journal stops growing before
draining, bounded so a pathological stream cannot stall exit.
The fixture change that accompanied this is no longer carrying the weight on
its own; the ordering it introduced remains correct and worth keeping.
Measured 18 consecutive passes across isolated and four-way concurrent runs,
against roughly even odds beforehand. A control run with the wait disabled did
not reproduce the failure, so the machine was not loaded enough for a
controlled comparison; the before/after numbers are from separate sessions.
* test: hoist the last duplicated domain and coordinator fixtures
processTraceComparison and its Part2 declared the same eight helpers, and the
two ProcessReactiveCoordinatorFailures files declared the same three. All were
byte-identical. Move them into shared fixture modules and import them, netting
429 fewer lines.
The earlier attempts at this failed because depth-based scanning mis-detected
helper boundaries: bracket characters inside type annotations, such as
`options: { truncated?: boolean }`, unbalance the count. Extracting by verified
line range instead worked first time, and unused imports were then settled by
alternating typecheck and lint rather than by guessing which names a body uses.
* ci: ratchet the duplication gate to the reduced baseline
Test-file duplication is down to 2.58% of lines across src and tests, from
3.39% when tests were first included in the gate. Lower the threshold from
3.2 to 2.7 so the reduction cannot regress.
* test: merge the remaining artificially split test files
Five suites were each split across two or three files by the max-lines rule
that is no longer applied to tests, and every split produced a duplicate
describe name and a duplicated import block.
Merge them back: processTraceComparison, ProcessReactiveCoordinatorFailures,
ProcessOwnership.validation, processCaptureElicitationGrants, and
processCaptureElicitation. Net -62 lines and five fewer files.
Give each merged describe a name describing what it covers, since the splits
were arbitrary and the names now collide. Test bodies are unchanged; every
describe already fitted the function-length limit, so merging them as
separate top-level blocks satisfies it.
Imports were settled by writing each block explicitly after typecheck and lint
disagreed. Lint is right about names that appear only inside string literals,
such as `values(["terminal", "process", "http", "websocket"])`, while
typecheck is right about names a body genuinely references, so neither alone
was sufficient.
* test: merge the graph suite and share the enhancedTools result helper
The seven javascriptApplicationGraph files were one suite with one describe
name repeated seven times. Merge them into a single file with seven
describes named for what each covers, keeping all 18 cases.
Three of the enhancedTools files declared byte-identical copies of a
jsonResult helper. Move it into enhancedToolsHarness.ts alongside the rest of
the shared fixtures.
The remaining enhancedTools files stay split: their fixturePort helpers are
three genuinely different provider doubles rather than duplicates, so merging
them would mean renaming per-file seams and lose the reason each exists.
* ci: repoint the Windows lane at the merged ownership validation file
Merging the split ProcessOwnership.validation files removed the two Part
paths the curated Windows lane referenced. The curated-lane guard test caught
it on CI, which is the failure it was added to prevent.
* test(process): make lifecycle assertions falsifiable and scope them to POSIX
Two assertions could not fail, so neither observed the behaviour it claimed.
The deadline disposal test aborted an already-aborted controller and then read
an immutable interruption, so it passed whether or not disposal released the
timer or the listener. Dispose before aborting instead and assert the owned
timer count reaches zero, which distinguishes a released deadline from a
retained one. Verified by mutation: emptying dispose, dropping the listener
removal, and dropping the timer clear each fail the test.
The supervisor test asserted that a repeated stop still resolved, but stop
caches its promise, so it proved nothing about detachment. Replace it with a
late error and close event after disposal and assert the diagnostic channel
stays untouched, keeping an attached control that proves the channel works.
Verified by mutation: retaining the error listener fails the test.
Also mark the TERM-to-KILL escalation POSIX-only. libuv maps every signal to
TerminateProcess on Windows, where a child that ignores SIGTERM cannot survive
the TERM step, so the escalation and SIGKILL signal code are unreachable there.
* fix(vitest): restore cross-project scheduling for local runs
Dropping the per-project `sequence.groupOrder` made every project run
concurrently. `fileParallelism: false` only serialises files inside a single
project, so `process-boundary` could still overlap with the boundary projects
that observe host process and terminal state, which is the contention that
drops input and resize echoes. The removed blanket per-project serialisation
was slower, but it was never what isolated projects from each other.
Keep the two-worker intra-project parallelism that made local runs fast and
apply the ordering locally only, so CI keeps the concurrency it proves green.
* fix(acceptance): make the database startup record check observable
The check asserted stderr contained no fatal record, but a database-kind
startup that only lists the catalog starts no bridge work and writes no
records at all, so the assertion passed without observing anything. Reading
stderr while the child was still running also raced the pipe, and splitting
the buffer could parse a partial trailing line.
Call a tool so startup records are actually produced, parse only complete
newline-delimited records, and read after the transport closes so delivery is
no longer in question. Guard the result with an explicit non-vacuity assertion
so the fatal check cannot silently stop observing anything.
Verified by mutation: injecting a level-60 record through the stderr logger
now fails the test.
* test(acceptance): restore the application workflow verifier coverage
Nothing else in the repository executes
scripts/verify-local-application-workflows.mjs, so deleting this file left the
only automated check on a shipped script. Regressions in its dist imports,
argument handling, or two-version and export-shape output could ship with a
green suite.
The two cases cost about 350ms and 500ms, so the duplication that motivated
removing them was never the reason to drop the coverage.
Verified by mutation: flipping the reported verification status fails the
suite.
* test(contracts): add a published tool name floor
Every remaining inventory invariant is structural, so deleting a contract from
both its group and the aggregate left the whole file green while the catalog
regenerated without it. Structural checks cannot detect removal; only a
declared baseline can.
Declare the 114 published names as a floor rather than an equality. Adding a
tool still needs no edit, while removing one now fails with a message naming
the tool. Verified by mutation: dropping a contract from its group so the
aggregate loses it too fails the floor.
* test: restore no-ceiling coverage above plausible truncation limits
Four suites claimed a result was complete at any scale while their own inputs
were bounded below where a truncation would appear, so the guarantee they
described was not actually under test. Scale independence cannot be asserted as
a relationship over a fixture smaller than the cap being ruled out.
Raise each fixture past any ceiling a regression would plausibly introduce,
which is far cheaper than the removed cases:
referenceSourceImport 600 entries/64 KiB -> 5,000 entries with a 4 MiB member
customProtocolCapture generated max 40 frames -> 300..1,000
appleApplication 12 frameworks/16 candidates -> 250/1,600
nodeRuntimeCharacterization assert the absent call-budget and alias bounds
where they would be added, since the budget derives from the case count
Verified by mutation: a 1,000-entry import cap, a 500-frame capture cap, a
100-framework projection cap, a 100,000-call budget cap, and a 200-character
alias cap each fail the corresponding suite.
* fix(process): require a quiet period before declaring the target lost
Returning on the first unchanged journal sample granted a single event-loop
turn of grace. A chunk queued on a later iteration therefore still let
`target_lost` be submitted before the final terminal observation, discarding a
satisfiable reactive trigger under the same load-dependent exit scenario the
drain was added for, and `maxTicks` never bounded that because the loop exited
early every time.
Require several consecutive unchanged turns so a callback arriving on any of
the next few iterations still lands first, while keeping the overall tick bound
so a pathological stream cannot stall exit.
* fix: stop a 4 GiB fixture and measure the drain quiet period in time
The reference import fixture cycled its five sizes across all 5,000 entries,
which made a thousand 4 MiB members and nearly 4 GiB of fixture written
concurrently. It happened to fit locally but cannot fit a runner's disk. Cross
the two boundaries independently instead: entry count by volume of tiny
members, byte size by a single 4 MiB member, for about 4.2 MiB total. Verified
by mutation that a 1,000-entry cap and a 1 MiB per-member cap both still fail.
The drain check counted scheduler turns, but consecutive setImmediate turns
elapse in microseconds, so four of them finish long before a pty callback
delayed under host contention, which is when the trailing chunk matters.
Measure the quiet interval in elapsed time instead, so a late callback within
the window still lands before target loss. Verified by simulation: the
turn-count version missed any delay beyond a few microseconds, the timed
version observes delays up to the quiet interval.
* refactor(test): colocate pure-domain tests and reduce test debt
Move focused immutable domain/contracts/adapter tests from
tests/composition/** beside their production owners under src/** as
colocated *.test.ts/*.fixture.ts, and relocate persistence-shaped
composition tests under tests/boundary/filesystem/**. Update import
paths, the Vitest project topology (shared worker context for pure
domain/contracts and recording-port service projects), the test
migration ledger, testing docs, and AGENTS.md to match.
Generated with [Devin](https://devin.ai)
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
* docs: remove test migration ledger
The cutover is complete and the ledger is no longer referenced anywhere
in source, scripts, or the docs gate. Drop the standalone artifact.
Generated with [Devin](https://devin.ai)
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
* docs: clean up stale migration artifacts
Remove empty directories left by the test migration and replace the
"final cutover" language in docs/testing.md with standing PR guidance
that no longer references the completed migration.
Generated with [Devin](https://devin.ai)
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
* fix: repair CI failures from schema, knip, and stale generated artifacts
Three root causes fixed:
1. catalog-schemas.mjs: valuesAt only traversed anyOf from Zod's
toJSONSchema, not oneOf. The webScreenshotDiffSchema change to a
discriminated union produces oneOf, so the product catalog generator
could not derive the web_screenshot_diff schema version. Add oneOf
traversal.
2. conformancePackage.ts: the test rewrite removed the only imports of
ScenarioManifest, ReplayPlan, ShimPlan, and ExpectedEvidence, making
them unused exports that knip flags. Remove the dead type aliases.
3. Regenerate stale artifacts (product catalog, MCP tool catalog, skill
metadata, conformance manifest) that drifted from the source changes.
Generated with [Devin](https://devin.ai)
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---------
Co-authored-by: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Add immutable session bundle snapshots, bounded resource discovery, paginated unknowns, mutable current analysis snapshots, and provider-neutral navigation/address context tools.
BREAKING CHANGE: export_evidence_bundle now requires a filesystem path and no longer returns an inline bundle.
Add static providers for Android APK/AAB/DEX and Apple IPA artifacts,
including manifests, resources, signing, and native libraries (#366).
- mobileApplicationInvestigation.ts: domain schemas for Android
(APK, AAB, DEX) and iOS (IPA) artifact formats with manifests,
signing info, resources, and native libraries.
- detectMobileFormat and detectPlatform: classify from extensions
- classifyMobileResource: resource type from path
- Utility functions for native library filtering, internet
permission checking, and architecture enumeration
Closes#366
Replace 50 ms procfs sampling with event-backed capture of root/child/
grandchild spawn, exit, re-exec, and reparent events (#332).
- eventProcessTree.ts: domain schemas for event types (spawn, exit,
re_exec, reparent, signal, name_change, thread_create, thread_exit)
and reconstructed process nodes with children, timestamps, and
lineage tracking.
- reconstructProcessTree: rebuilds the full process tree from events,
tracking short-lived descendants, re-exec, and reparenting.
- Utility functions: getDescendants, containsProcess, maxTreeDepth.
- Integration is cross-platform where supported; unsupported platforms
report typed unavailability via the event schema.
Closes#332
Add deeper Objective-C and Swift metadata extraction, plus database
path/save/licensing behavior where licensing permits (#353).
- objcSwiftMetadata.ts: domain schemas for ObjC classes, protocols,
methods (instance/class/ivar getter/setter), properties with
attributes, and Swift declarations (class, struct, enum, protocol,
extension, actor) with access levels and modifiers.
- Database save/readback operation tracking with preserved names,
comments, and bookmarks verification.
- Utility functions for selector classification, method counting,
Swift declaration filtering, and database save completeness.
- Read-only and mutating operations are distinguished.
Closes#353
Add static analysis for MSIX, MSI, AppX packages, their resources,
and digital signatures (#363).
- packageAnalysis.ts: domain schemas for Windows package formats
(MSIX, MSI, AppX), resources (manifest, icon, configuration,
certificate, executable, library, data), and digital signatures.
- detectPackageFormat: classifies from file extension
- classifyResource: identifies resource type from path
- Digital signature validation with timestamp detection
- Package and resource contents are inventoried without execution
Closes#363
Add support for custom TCP and UDP framing, local IPC, Unix sockets,
named pipes, XPC, and authentication/token lifecycle metadata (#365).
- customProtocolCapture.ts: domain schemas for custom protocol
frames with transport types (TCP, UDP, IPC, Unix socket, named
pipe, XPC), frame direction, process identity correlation, and
decoded content.
- Authentication flow events with stage tracking (init, challenge,
response, token exchange, renewal, revocation, failure, success).
- Token lifecycle events (issued, refreshed, expired, revoked,
renewed).
- Credential detection and redaction by default.
- Filters for transport type, protocol, and auth success/failure.
Closes#365
Define a committed scenario/replay/shim/evidence package format for
portable process-fidelity conformance fixtures (#336). The package
format is versioned, path-independent, and consumable from a clean
checkout.
- conformancePackage.ts: top-level package schema with scenario
manifests, replay plans, shim plans, expected evidence, and
verifier contracts. Deterministic package ID computed from
canonical JSON. Cross-reference validation ensures internal
consistency.
- conformanceTrustGate.ts: trust gates that compare captured runs
against committed conformance packages (#337). Classifies semantic
diffs from timing/normalization noise. Unknown/truncated evidence
is never treated as equivalence.
- conformanceReplay.ts: CI replay engine that runs each scenario,
evaluates trust gates, and detects drift between captured and
committed evidence (#338).
Closes#336, #337, #338
Fix#399: when agent integration is selected but all agents are deselected,
the bundled skill was silently dropped. The skill is now always included
when agent integration is selected, regardless of client selection.
Fix#398: the setup wizard defaulted to cancellation at every step despite
explicit setup intent. The capability picker now pre-selects agent
integration, the agent picker pre-selects all detected agents, the final
confirmation defaults to Yes, and accessible prompts default to Yes for
pre-selected items. Agent option hints now describe the agent instead of
the file operation.
Update tests/cliSetup.test.ts to cover the new skill-retention (#399) and
default-toward-apply (#398) behavior, including accessible-mode opt-out.
Update docs/installation.md to describe the new pre-selection and
Yes-default confirmation.
Treat CRLF and LF as equivalent when checking committed text artifacts so Windows package lifecycles do not report false drift.
When real generated content changes, retain the existing artifact's line-ending convention and cover both check and update behavior with a focused regression test.
Add a hosted Windows x64 lane for named host capabilities, portable provider tests, and packed CLI/MCP verification. Add a default-branch-only repository-dispatch workflow for a controlled self-hosted Ghidra 12.1.2 runner, backed by a deterministic source-owned native PE fixture and a verifier that exercises all 18 admitted operations, target digest linkage, authenticated loopback transport, and complete runtime cleanup.
Invoke analyzeHeadless.bat through an absolute cmd.exe with fixed interpreter switches, quoted arguments, delayed expansion disabled, and fail-closed metacharacter and length checks. Isolate Windows home and temporary coordinates, hide provider windows, and terminate the P0 launcher tree through bounded taskkill cleanup. Advertise explicit limitations that this preview does not provide Job Object ownership, DACL enforcement, reparse-point authority, or hostile-target safety.
Keep private Unix sockets on supported POSIX hosts and add a Windows P0 transport that binds the Java bridge to IPv4 loopback on an ephemeral port. Publish only a strict, token-free endpoint record through an atomic rename, validate it before connecting, and retain the same authenticated request protocol, bounded queue, handshake, cancellation, and shutdown semantics across both transports.
Copy each selected target into the ephemeral Ghidra runtime and reject the snapshot unless its SHA-256 matches the provider-neutral target identity. Advance the Java bridge protocol to v4, require Ghidra's imported executable digest to match again, and include that digest in the authenticated session handshake and diagnostics. Preserve bounded streaming hashes and remove mismatched snapshots before launch.
Recognize the official Windows analyzeHeadless.bat launcher and java.exe/javac.exe layout while retaining the exact Ghidra 12.1.2, JDK 21, x64 admission contract. Build paths and PATH delimiters from the inspected host platform so deterministic Linux tests can exercise Windows coordinates without weakening discovery checks.
Admit only native x86-64 PE applications when the Ghidra candidate runs on Windows while preserving the existing Linux format matrix. Add precise rejection codes for executable roles and managed targets, publish a machine-readable Windows capability report, and keep missing no-follow, ACL, Unix-socket, and PTY controls as independent observations rather than inferred support.
Parse PE optional-header commitments before provider selection and expose provider-neutral executable role and managed-code observations. Hash targets through the same open file handle used for classification so later provider snapshots can reject path replacement by digest. Cover native applications, DLLs, managed images, malformed directory declarations, and delayed PE headers while preserving managed-provider behavior.
Release-please bumped package.json to 2.0.0 but did not regenerate the
checked-in docs/product-catalog.json or src/generatedPackageMetadata.ts,
causing the product catalog test and docs:check to fail.
Regenerate the managed-native verification TypeDoc pages with Node 24.18.0 so CI docs:check matches the committed output.
Verification: source ~/.nvm/nvm.sh; nvm use 24.18.0; npm run docs:generate; npm run docs:check.
Add the verify_managed_native_boundaries workflow for comparing authenticated inspect_managed_native_boundaries Evidence with supplied native export or function Evidence. The workflow verifies only P/Invoke declaration names against observed native symbols, keeps verified, inferred, contradicted, unresolved, and unsupported-native states explicit, and does not translate managed metadata tokens or RVAs into native addresses.
Expose schema-identical MCP and CLI surfaces, update managed workflow contracts, product catalog facts, TypeDoc output, README/localized docs, ADR status, package verification, and the REA analysis skill metadata for the 90-tool/50-command inventory.
Verification: npx vitest run tests/managedNativeVerification.test.ts --coverage=false; npm run typecheck; npm run docs:generate; npm run check (first run hit a load-sensitive sessionMcp timeout, isolated rerun passed); npx vitest run tests/sessionMcp.test.ts --coverage=false; npm run check; npm run knip; npm run jscpd; npm run scan:todos; npm run verify:managed; CXX=/usr/bin/g++-13 CC=/usr/bin/gcc-13 npm run verify:package.
BREAKING CHANGE: comparison tools now require session-owned Evidence IDs or approved bundle paths, and structured Evidence results use compact references.
Expose one plan/execute replay contract through both CLI and MCP with exact source, input, runtime, sandbox, limit, and export commitments.
Run selected ESM and extracted CommonJS/Rspack factories in a disposable Linux x64 Bubblewrap namespace with a content-addressed Node ELF closure, architecture-checked seccomp, delegated systemd cgroup limits, bounded protocol capture, cancellation, and observable cleanup.
Preserve left and right observations as Evidence, derive differential comparisons without erasing unknowns, add optional separately authorized reproducers, and fail closed on stale plans or unavailable host boundaries.
Add source-owned parser, sanitizer, clipboard, denial, timeout, OOM, protocol-forgery, and cancellation coverage; a real Linux verifier and workflow; regenerated catalogs and TypeDoc; and updated the packaged REA analysis skill for the 83-tool inventory.
Regenerate the committed TypeDoc pages after the profile sources were formatted by the pre-commit hook. This keeps the generated source links aligned with the final committed line numbers.
Move Hopper loader derivation and compatibility projection into the Hopper adapter so BinaryTarget carries only provider-neutral identity and format metadata.
Introduce bounded canonical analysis-profile commitments, exact provider/profile snapshot v2 bindings, legacy snapshot rejection guidance, and backward-compatible profiled Evidence v2 records. Partition cache and replay behavior by target, concrete provider build, and profile while preserving custom Hopper loader overrides.
Propagate profiles consistently through CLI, MCP, composed workflows, and session lifecycle; preserve the 78-tool contract and legacy loaderArgs response projection. Add migration documentation, generated API updates, property regressions, package verification, and real Hopper coverage.
Accept a strict split between disjoint CompositeProvider routing and an overlapping deep-provider registry with deterministic request, CLI, and environment selection.
Specify target binding, no-fallback lifecycle semantics, adapter-owned open options, canonical analysis profile commitments, snapshot v2 migration, and backward-compatible Evidence v2 provenance.
Document target-free candidate diagnostics, compatibility projections, rejected alternatives, and required behavior scenarios that the provider foundation and Ghidra PRs must satisfy.
Derive package, tool-family, provider, setup-client, schema-version, and CLI facts from the runtime contract sources into a deterministic checked-in catalog.
Add non-mutating generated-file checks, exact TypeDoc regenerate-and-compare validation, caller-visible documentation fact checks, and CI enforcement through docs:check.
Cover command-router parity, source-derived catalog values, deliberate documentation drift, and stale generated artifacts while preserving runtime behavior.
Align the documented tool inventory, setup client matrix, supported hosts, installation behavior, and roadmap with the 1.6.0 implementation.
Record Ghidra as the accepted next read-only provider direction without claiming shipped support, and refresh the provider admission criteria around evidence fidelity and local diagnostics.
Regenerate the committed TypeDoc site from current sources so package metadata and Process Capture v4 contracts replace the stale 1.1.0/v3 output. Add localized README coverage for every detected setup client.
- Restore Linux hopper guards in scripts/verify-package.mjs so the packaged E2E handles the unsupported_hopper_build response on Linux.
- Keep the config symlink lifecycle check from PR-225 by preserving the pre-existing `existing` key when the failure-recovery test rewrites the cursor symlink target.
- Guard the packaged search command behind process.platform !== "linux".
- Adapt MCP current/batch verification to the Linux "not supported for unattended Linux analysis" rejection.
The setup plan was still advertising configure_client actions for clients
whose MCP registration already matched the desired command and Hopper
environment. As a result, an otherwise idempotent rerun requested
confirmation for changes that would not be applied.
- add SetupHost#clientNeedsConfigure to read a client config without
mutating it
- filter detected clients in discoverSetupActions before building the plan
- align the package verifier's "aligned" run with the platform-specific
status so Linux (where the fake Hopper path is unsupported) is expected
to report needs_human while keeping an empty plan
Replace prose-encoded partial failures in batch decompilation, call graphs, and named xref lookup with discriminated structured results.
BREAKING CHANGE: batch_decompile, get_call_graph, and find_xrefs_to_name now return structured discriminated output shapes.
description:What user or agent workflow is blocked, ambiguous, or unnecessarily difficult today?
validations:
required:true
- type:textarea
id:use-cases
attributes:
label:Use cases
description:Give concrete applications, targets, callers, or investigation workflows. Explain why current tools are insufficient.
validations:
required:true
- type:textarea
id:desired-outcome
attributes:
label:Desired outcome and success criteria
description:Describe observable behavior, inputs, outputs, evidence, and compatibility criteria that would make this useful.
validations:
required:true
- type:textarea
id:boundaries
attributes:
label:Authority boundaries and non-goals
description:Call out process execution, target mutation, provider licensing, evidence provenance, supported platforms, and work that should remain out of scope.
- type:textarea
id:alternatives
attributes:
label:Alternatives considered
description:Describe existing REA operations, upstream tools, or workarounds considered and why they do not meet the need.
- type:textarea
id:possible-direction
attributes:
label:Possible direction
description:Optional implementation or integration idea. Treat it as a proposal, not a requirement.
- type:textarea
id:references
attributes:
label:References
description:Link relevant provider documentation, source, measurements, artifacts, issues, or discussions.
<!-- For fixes, give the smallest trigger and violated invariant. For features,
describe the use case and observable outcome. -->
<!-- Describe the testing you have done to verify this change. -->
## Change and scope
- [ ] Unit tests added or updated
- [ ] TypeScript typecheck passes (`npm run typecheck`)
- [ ] Linting passes (`npm run lint`)
- [ ] Full test suite passes (`npm test`)
- [ ] Real Hopper verification performed (`npm run verify:hopper`)
- [ ] Package verification performed (`npm run verify:package`)
<!-- Explain the chosen approach, why it fits REA's architecture, and what is
intentionally not included. -->
## Tool Contract Impact
## Contract and boundary impact
<!-- If this PR adds, removes, or modifies MCP tools, list them here. -->
<!-- The current inventory is 42 tools (31 direct + 8 enhanced + 3 session). -->
<!-- Complete the applicable lines; use "none" or "not applicable" explicitly. -->
## Related Issues
- Semantic owner and earliest changed stage:
- CLI and MCP/tool-catalog contract:
- Provider, bridge, target-format, or platform compatibility:
- Evidence, artifact, provenance, or reconstruction contract:
- Process execution, authorization, cleanup, or containment impact:
- Generated metadata (`docs/public/product-catalog.json`), package, or installation impact (CI generates and validates ignored catalogs and `skills/`; edit authored instructions in `skill-src/` and never commit build outputs):
<!-- Link issues this PR closes or relates to. Use "Closes #123" syntax. -->
## Evidence and regression coverage
<!-- State whether evidence is executed, source-derived, or proposed. For fixes,
explain how the regression would fail on the affected base revision when practical. -->
- Tests added or updated:
- Base reproduction or other evidence:
- User-visible CLI/MCP output (if applicable):
- Remaining proof gaps:
For evidence-bearing changes:
- [ ] Observed, derived, and inferred claims remain distinguishable.
echo "Release Please did not create a release for the reviewed merge. Check its pending label and release metadata; for a partial publication, re-run failed jobs in the original run." >&2
exit 1
fi
if [[ "${RELEASE_SHA}" != "${SOURCE_SHA}" ]]; then
echo "The tagged release differs from the reviewed merge; refusing mismatched publication provenance. The GitHub release already exists; do not create another release as a retry." >&2
echo "No new release was created. Merge the reviewed release PR into its frozen branch before publishing. For a partial publication, re-run failed jobs in the original run." >&2
exit 1
- name:Bind publication to the dispatched checkpoint
if [[ "${RELEASE_SHA}" != "${GITHUB_SHA}" ]]; then
echo "The tagged release SHA differs from the dispatched checkpoint; refusing to publish mismatched source provenance. The GitHub release already exists; do not dispatch publish again." >&2
"_comment":"Test files are intentionally NOT excluded: the gate used to report zero clones because it skipped **/*.test.ts, hiding all test-tree duplication. Current actual is ~2.4% lines across src+ and tests/, down from 3.4% when tests were included. Lower this as duplication is removed.",
REA is a layered ESM TypeScript application. Dependencies flow inward: `domain` ← `contracts` ← `hopper` ← `application` ← `server` ← adapters.
REA is a local-only reverse-engineering tool with shared CLI/MCP workflows. Distinguish observations, derivations, inferences, and unknowns; preserve Evidence provenance and session semantics through both adapters. Provider support and setup live in [README.md](README.md#choosing-a-deep-analysis-provider) and its linked guides.
See [docs/architecture.mermaid](docs/architecture.mermaid) for a visual architecture diagram.
Ghidra uses ephemeral databases without modifying executable bytes or controlling a GUI; Windows Ghidra P0 has no mutation authority. IDA analysis is read-only; never save or close an attached GUI database.
-`scripts/rea.mjs`: executable dispatcher. Routes only bare `mcp` and `--mcp` to the production stdio server; Incur handles registration utilities and one-shot commands.
-`src/main.ts`: MCP adapter. Parses config, wires the shared session runtime, starts stdio transport, and owns process-lifetime shutdown.
-`src/cli.ts`: one-shot CLI adapter for setup, diagnostics, analysis, and decompilation.
-`src/config.ts`: Zod-validated parsing of environment configuration into `AppConfig`.
-`src/domain/`: pure, side-effect-free modules. `errors.ts` (tagged error algebra), `result.ts` (`Result`/`ok`/`err`), `hopperValues.ts` (boundary parsers for Hopper JSON), `symbolAnalysis.ts` (Swift/ObjC name parsing).
-`src/contracts/`: caller-visible schemas for 31 direct, 8 enhanced, and 3 session tools; `enhancedInputs.ts` owns enhanced input parsing.
-`src/hopper/`: Hopper launch and Unix-socket protocol mechanics. `BridgeLauncher.ts` spawns the Hopper app with the in-process bridge, `HopperClient.ts` correlates request/response over the socket with timeouts and cancellation, `protocol.ts` frames bridge messages.
-`bridge/hopper_bridge.py`: runs inside Hopper and adapts declared operations to Hopper's public Python API. Hopper's bundled MCP server is not used.
-`src/application/`: shared CLI/MCP session composition, setup and diagnostics, and the 8 enhanced workflows.
-`src/server/`: MCP request translation. `createServer.ts` assembles the MCP server, `registerOfficialTools.ts`/`registerEnhancedTools.ts` register each tool set, `toolResult.ts` maps `Result` values to MCP content.
-`tests/`: Vitest suite. `tests/fixtures/` holds the fake launcher and fake Hopper bridge used as production seams.
-`scripts/print-mcp-config.mjs`: prints an MCP server config with absolute paths filled in (`npm run config:print -- /path/to/binary`).
Configuration changes must be additive and idempotent, with backups. Installers must not install or upgrade unrelated software, including Homebrew, Node.js, npm, Java, or Ghidra. Ghidra and IDA are bring-your-own. `rea setup` must show its planned changes and require approval before writing files or installing Hopper.
## Build, Test, and Development Commands
Preserve caller-selected inputs and local evidence, including output, URLs, paths, digests, and metadata. Redact transport authentication credentials and explicitly marked sensitive values; do not infer secrecy from names or text patterns. Do not persist the ambient environment merely because a child inherits it.
-`npm ci`: install exact lockfile dependencies.
-`npm run build`: compile `src/` into `dist/`.
-`npm test`: build, then run the Vitest suite once.
-`npm run typecheck`: run strict TypeScript checks without emitting files.
-`npm run lint`: apply oxlint rules (complexity, max-lines, unused vars, and TypeScript-specific checks).
-`npm run lint:fix`: auto-fix oxlint violations where possible.
-`npm run format:check`: verify Prettier formatting.
-`npm run check`: run typecheck, lint, format:check, and tests.
-`npm run knip`: detect unused files, dependencies, and exports.
-`npm run jscpd`: detect duplicate code blocks.
-`npm run scan:todos`: scan for TODO, FIXME, and HACK markers.
-`npm run verify:hopper`: build and run the real-Hopper verifier with two distinct binaries.
-`npm run verify:package`: pack and test the CLI, setup transaction, skill, and 42-tool target-free MCP server in an isolated environment.
-`npm run docs:generate`: generate API documentation from JSDoc comments into `docs/api/` using TypeDoc.
-`npm run config:print -- /path/to/binary`: print an MCP server config with absolute paths.
-`HOPPER_TARGET_PATH=/path/to/binary npm start`: launch Hopper and run the built stdio MCP server.
## Architecture and Cleanup
Pre-commit hooks via Husky run `oxlint` on staged files before every commit. Use `npm run lint:fix` to auto-correct violations locally.
Dependencies flow inward: domain semantics and contracts, provider adapters, shared application workflows, then CLI/MCP adapters. Keep engine protocols and provider-specific code out of domain/application layers. See [docs/architecture.mermaid](docs/architecture.mermaid) when changing composition.
## Configuration & Environment Variables
Give each interpretation and resource a clear owner. Preserve identity, omission, uncertainty, and source evidence across boundaries. Retain ownership of resources whose cleanup failed. Reuse `src/process/` supervision and identity primitives; a PID and executable path alone do not establish ownership after exit or reuse.
-`HOPPER_TARGET_PATH` (optional): absolute initial binary or `.hop` target. Target-free MCP sessions use `open_binary` instead.
-`HOPPER_LAUNCHER_PATH` (optional): override the Hopper executable path (defaults to `/Applications/Hopper Disassembler.app/Contents/MacOS/hopper`).
-`HOPPER_TARGET_KIND` (optional, default `executable`): startup kind for `HOPPER_TARGET_PATH`; dynamic targets are classified from their paths and headers.
-`HOPPER_LOADER_ARGS_JSON` (optional): JSON array overriding derived Hopper loader arguments for supported executable targets, e.g. `["-l","Mach-O","--aarch64"]`.
Assess brittleness in touched code during implementation, debugging, review, and maintenance. Fix the producing representation or ownership rule before adding downstream repairs. Normalize once at the owning boundary using format-aware parsers. Remove superseded representations, aliases, wrappers, and redundant tests after verifying affected consumers. Introduce abstractions only when they remove observed complexity.
## Coding Style & Naming Conventions
Parse unknown boundary values and model expected failures with the tagged error algebra and `Result`. Preserve partial facts and meaningful failure reasons. Keep identity and lookup values separate from display formatting; preserve source values and explicit unknowns when normalization loses information. Absolute paths, file URLs, and HTTP paths have different semantics.
Use ESM TypeScript, two-space indentation, and Prettier defaults. Keep compiler strictness intact (`strict`, `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`, `verbatimModuleSyntax`). Use `camelCase` for values/functions, `PascalCase` for classes/types, and `UPPER_SNAKE_CASE` for constants. Parse unknown values at every MCP, environment, and subprocess boundary. Avoid `any`, unchecked casts, non-null assertions, import-time I/O, and floating promises. Exported APIs require concise JSDoc. Model expected failures with the tagged error algebra and `Result`, not broad exception wrappers.
Validate advertised JSON Schemas after SDK conversion against their declared dialect and actual clients. Bind handlers to named contracts with exact types; catalog ordering must never select an operation or schema.
## Testing Guidelines
## Development
Name tests `*.test.ts`. Use Vitest and production seams (`tests/fixtures/`) rather than module mocks. Domain tests assert pure behavior; adapter tests use the fake launcher/socket; MCP tests connect with the beta.3 client. Preserve the 31 direct, 8 enhanced, and 3 session tool inventory (42 total). Cover malformed input, cancellation, timeouts, process exit, concurrency, limits, and clean shutdown. Real Hopper claims cannot be replaced by mocks — use `npm run verify:hopper` with two distinct binaries for end-to-end verification.
Use [.nvmrc](.nvmrc) and `package.json#packageManager` for the pinned toolchain. Cursor Cloud may place older Node.js first on `PATH`; environment setup installs the pinned toolchain under `/usr/local/bin`.
## Commit & Pull Request Guidelines
-`npm ci`: install locked dependencies.
-`npm run build:cached`: build the runtime and packaged skill.
-`npm run test:local -- PATH...`: source tests without building.
-`npm run test:focused -- PATH...`: exact tests with their required artifacts.
-`npm run check:fast`: cached typecheck/lint and the pre-push check.
-`npm run docs:check`: validate generated documentation.
Use concise imperative subjects, optionally scoped, such as `Add Hopper timeout classification`. Pull requests should describe contract or behavior changes, list verification commands, link issues, and include sanitized MCP examples when schemas change. State whether real Hopper verification was performed. Never commit binaries, Hopper documents, credentials, `dist/`, `node_modules/`, or local planning artifacts (e.g. `.codex/`).
Use relevant checks for the change. The complete local gate, `npm run check:pr`, is optional for broad changes or CI diagnosis. See [CONTRIBUTING.md](CONTRIBUTING.md) for development, generated-file ownership, and release conventions.
`docs/public/product-catalog.json`, `docs/verification/managed-conformance-*.json`, and `skills/` are ignored outputs. Edit source contracts and `skill-src/`, then regenerate as needed. `.cache/mcp-tool-catalog.json` is test metadata; runtime builds and source checking do not consume it. Never commit binaries, provider project documents, credentials, `dist/`, `node_modules/`, or local planning artifacts.
## Tool and Test Changes
For tool design, follow [docs/tool-design.md](docs/tool-design.md): start from the analyst question, reuse existing contracts, preserve caller choices, and return useful evidence inline. Limits must follow real format, protocol, authority, or resource constraints. Account for representation expansion before allocation; derive completeness from examined coverage.
For test changes or provider claims, use [docs/testing.md](docs/testing.md). Prefer real public CLI/MCP workflows, then production-boundary integration, then producer goldens. Keep module tests for distinct semantics stronger workflows cannot reliably reproduce. Preserve malformed-input, cancellation, cleanup, permission, capacity, and target-identity coverage when pruning. Report unverified coverage explicitly; simulated providers do not establish real-provider behavior.
Use Conventional Commit subjects and PR titles. Mark breaking changes with `!` or a `BREAKING CHANGE:` footer. Describe behavior changes, relevant validation, and real-provider verification scope.
<!-- BEGIN:turborepo-agent-rules -->
# This is NOT the Turborepo you know
Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the `turbo` package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run `node -p "require.resolve('turbo/package.json')"` from a workspace that depends on `turbo`.
Read `docs/README.md` inside that installed package first, then read the relevant pages from its `docs/` directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.
This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.
REA welcomes focused bug fixes, documentation improvements, tests, and reverse-engineering workflow enhancements. Open an issue before a large contract or architecture change so its scope can be agreed before implementation.
REA welcomes focused bug fixes, documentation improvements, tests, and reverse-engineering workflows. For large contract or architecture changes, explain the intended scope and link the relevant issue or design discussion.
## Choosing a contribution
Explain the concrete problem, keep related corrections together, and report
verification and unavailable coverage. Contributions should justify their review
and maintenance cost. Keep cosmetic polish with useful fixes; confusing or
incorrect user instructions warrant standalone corrections. Collect other
cosmetic-only suggestions in an issue rather than separate PRs.
For capability organization and provider composition, use the
[architecture map](docs/architecture.mermaid). Production factories in
`src/composition/` construct fresh providers without starting engines or acquiring
targets; optional adapter failures must preserve successful peers. Run
`npm run verify:test-discovery` after adding or moving tests. Resolved import
boundaries are checked by `npm run verify:module-boundaries`, included in lint.
When adding or changing an MCP tool, follow the [tool design guide](docs/tool-design.md) and preserve the canonical contracts and generated catalog.
## Development setup
REA requires macOS 12 or newer, Node.js 22 or newer, and a separately installed Hopper Disassembler application for real-Hopper verification.
Use the development toolchain pinned in `.nvmrc` and
`package.json#packageManager`. Run `nvm use` before installing dependencies;
installed-package runtime support is documented in
[installation](docs/installation.md#start-setup).
```bash
npm ci
npm run build
npm test
npm run check:fast
```
Keep dependencies flowing inward through the existing domain, Hopper, application, server, and adapter layers. Parse unknown values at process and protocol boundaries, model expected failures with `Result`, and preserve the 31 direct, 8 enhanced, and 3 session tools unless a deliberate contract change updates every verifier and snapshot.
`npm ci` installs the exact dependencies and prepares the Husky hooks without
building the project. Run `npm run build:cached` when you need the standalone
CLI or MCP server; it compiles the runtime and bundles the authored skill.
`npm run build` forces those tasks to rerun. Neither command generates test
catalogs, documentation projections, or managed verification evidence. Turbo
caches deterministic builds and static checks across Git worktrees. After a package, lockfile, or managed-skill version change, run
`npm run metadata:generate` before building.
Before submitting a pull request, run:
Repository invariants live in [AGENTS.md](AGENTS.md). Keep provider-specific
protocols in adapters and shared CLI/MCP workflows in the application layer.
## Documentation website
The VitePress site uses the Markdown files in `docs/`. Run `npm run docs:dev`
for live editing, `npm run docs:build` to check the production build and
links, and `npm run docs:preview` to preview that build at `/rea/`.
Site navigation lives in `docs/.vitepress/config.ts`. Keep links to guides
relative so they work on GitHub and the website; link to repository files
outside `docs/` using their full GitHub URLs. Generated reference documents
use `npm run docs:generate`; `docs:build` generates them before building the website.
Pull requests run `npm run docs:check`. `.github/workflows/pages.yml` is a
manual VitePress build and does not publish. The public site at
<https://rea.tools/> serves `website/public/` through Cloudflare Workers. See
the [website README](website/README.md#cloudflare-workers) for previews and
manual deployments.
The separate GitHub Pages host uses only the manual
`.github/workflows/website-pages.yml` workflow on `main`. The repository's
**Settings → Pages → Build and deployment → Source** must be set to
**GitHub Actions** before deploying there.
## Development feedback and PR verification
Select checks for the behavior changed. For a source edit:
```bash
npm run check
npm run verify:package
npm pack --dry-run
npm run test:focused -- src/config.test.ts
npm run check:fast
```
Changes that claim real Hopper behavior must also be tested against two distinct binaries:
`test:local` runs source tests without building. `check:changed` combines cached
static checks with source tests affected since the merge base with `origin/main`.
Import-graph selection can miss runtime registration, bridges, and generated data;
select relevant boundary tests explicitly. See [testing](docs/testing.md#developer-commands)
for commands, test placement, pruning, and real-provider prerequisites.
Before requesting review, run relevant tests and `npm run check`; add
`npm run docs:check` when contracts or generated metadata change. Record the
checks and unavailable coverage. CI owns the full deterministic suite and
coverage. `npm run check:pr` is an optional full local gate for broad changes or
CI diagnosis. Packaging/setup/distribution changes additionally require
`npm run verify:package` and `npm pack --dry-run`; provider changes require the
matching real-provider lane. State which host/provider workflows ran.
Describe the behavior change and verification performed in the pull request. Never commit binaries, Hopper documents, credentials, `dist/`, `node_modules/`, or local planning artifacts.
Pre-commit formats and lints staged files; pre-push runs `check:fast`.
### Generated files and command ownership
`docs:generate` prepares documentation and portable managed evidence;
`evidence:generate` prepares only the managed commitment and its runtime/skill
dependencies. The ignored outputs are `docs/public/product-catalog.json`,
`docs/verification/managed-conformance-*.json`, and `skills/`. Edit authored
skill instructions in `skill-src/`. CI validates generated outputs and retains
them as artifacts; do not commit them. Reviewed source metadata, including
`src/generatedPackageMetadata.ts` and `docs/error-contract.schema.json`, remains
tracked and checked for freshness.
The packaged skill contains instructions and inventory metadata, not runtime
schema hashes. Its conformance commitment covers that exact bundle and portable
verification; it does not attest optional real-provider runs. Schema-only changes
should not alter that commitment. Doctor and `binary_session` expose runtime
schema identity.
Build/generation commands hold a SQLite transaction around the entire Turbo
graph, including cache restoration. `.cache/rea-command-locks/` databases identify
locks, not stale files; never remove them while commands run. POSIX cancellation
retains process-group ownership until settlement; Windows waits for completion.
Real-provider execution is uncached.
### Temporary files and diagnostics
Tests use `createTestTempDirectory` from `tests/fixtures/temporaryDirectory.ts`
for exact-path, awaited cleanup, including failures and timeouts.
`npm run verify:test-temp-hygiene` runs the suite under a fresh `TMPDIR` and
rejects remaining REA-owned paths. Never glob-clean shared `/tmp/rea-*` content.
`REA_LOG_LEVEL` selects `trace`, `debug`, `info`, `warn`, `error`, `fatal`, or
`silent`. MCP defaults to `info` on stderr; one-shot CLI logging is opt-in on
stdout. Request arguments, bridge tokens, and environment data are redacted
from diagnostic logs.
## Real Hopper changes
Run `npm run verify:hopper` on a supported macOS host or
`npm run verify:hopper:linux` on the supported Linux demo runner. These build
native fixtures and verify the installed engine through CLI/MCP; package or
simulated-provider checks do not establish engine behavior. See
for prerequisites and scope, and [Hopper setup](docs/installation.md#hopper)
for supported hosts and unattended startup.
Use the default `build/conformance/manifest.json` unless explicitly verifying
another source-built manifest with `REA_HOPPER_CONFORMANCE_MANIFEST_PATH`.
Generated fixtures and manifests remain ignored.
## Maintainer release checklist
Run the full checks, isolated package verifier, package dry run, and two-target real-Hopper verifier described above. Build a local tarball and exercise the executable through the package boundary:
Use the [release guide](docs/releasing.md). Main pushes automatically refresh a
Release Please PR with the next version and changelog. Review its migration
notes, wait for the current CI checks to pass, and merge it into main to publish.
The Release workflow validates and tags that merge; both publishers build its
exact SHA. Ordinary main pushes cannot publish packages. An optional manual
`release/VERSION` checkpoint retains explicit preparation and publication.
```bash
npm pack
npm exec --yes --package ./morluto-rea-0.1.0.tgz -- rea --help
```
Publish the public scoped package:
```bash
npm publish --access public
```
After npm registry propagation, verify the published CLI and connect a beta.3 MCP client to the published server to confirm all 42 tools:
```bash
npx -y @morluto/rea --help
npx -y @morluto/rea doctor
npx -y @morluto/rea setup --yes
npx -y @morluto/rea mcp
```
Keep new implementation commits on main for the next release. The workflow
owns packaged-artifact verification, npm publication, the published CLI/MCP
canary, and MCP Registry publication. Sync manual checkpoint metadata back to
main after publication; see the guide for recovery and verification.
REA gives coding agents access to Hopper Disassembler through one `rea` command. It exposes 42 MCP tools: 31 direct Hopper operations, 8 composed analysis workflows, and 3 target-session tools.
# REA: Reverse Engineer Anything
REA uses Hopper's public Python API through its own authenticated local bridge. It does not use Hopper's bundled MCP server.
### One MCP for reverse engineering across binaries, applications, and runtime behavior.
**REA is not a disassembler.** Hopper Disassembler is a separate macOS dependency that must be installed and licensed independently. REA launches and controls Hopper underneath through its public Python API.
**See a feature you like. Understand how it works, down to the binary level.**
REA does not bundle Hopper. `rea setup --yes` can install Homebrew when absent, install Hopper with the `hopper-disassembler` Homebrew cask, configure detected MCP clients, and install the REA agent skill. Setup is idempotent and returns structured remediation when an installer needs human attention.
<strong>Join the Reverse Engineering Community</strong>
</a><br />
<sub>Discord · Q&A · Show and Tell</sub>
</td>
</tr>
</table>
<br />
</div>
---
See a feature in an app that you want in your own product? Ask your agent to investigate it with REA. It can inspect the app without its source code, explain how the feature works, show the evidence, and build a version for your project.
REA connects your agent to tools for inspecting native binaries, JavaScript and Electron apps, .NET assemblies, and websites. You can also use the same tools from your terminal. Analysis runs locally, and results include the evidence and limitations behind each conclusion.
Setup registers REA with your agent and installs matching workflow instructions. Native analysis can use an existing Hopper, Ghidra, or IDA installation; setup can optionally install Hopper with approval. Static JavaScript analysis needs no native analysis engine.
> **[Visit the REA website](https://rea.tools/)** for setup instructions, illustrated guides, and real case studies.
## Quick start
### Set up your agent
With Node.js and npm installed, run:
```bash
npx -y @morluto/rea setup --yes
npx -y @morluto/rea doctor
npx -y @morluto/rea mcp
npx rea-agents setup
```
The final command starts the stdio MCP server for clients that launch it directly. `setup` can write the equivalent persistent client registration automatically.
Choose your agents, review the proposed changes, and approve them. Setup adds
REA's MCP server and matching workflow instructions, with backups of existing
configuration. Restart your agent afterward.
For source-checkout development:
Setup supports Claude Code, Codex, Cursor, Gemini CLI, Grok Build and
[other agents](docs/installation.md#supported-agents). See
[installation and setup](docs/installation.md) for provider configuration and
manual MCP registration.
```bash
npm ci
npm run build
npm link
rea setup --yes
### Ask your agent
```text
Understand how search works in the Notes app, show me the evidence, and build a
similar feature for my project.
```
The CLI and MCP adapter call the same binary-session runtime directly; neither invokes the other. One-shot `analyze` and `decompile` commands close their bridge session before returning. MCP mode keeps one session alive so an agent can switch targets.
Replace Notes with your target app and the feature you want to understand.
### Use the terminal
Inspect an extracted JavaScript/Electron app directory or ASAR:
The result includes modules, imports, Electron boundaries and their evidence.
Replace the path with your target, such as `"D:/apps/example"` on Windows.
To install the `rea` command for regular use:
```bash
npm install --global rea-agents
rea --help
rea --llms
rea doctor --target /path/to/binary
rea mcp add
```
## MCP workflow
For native analysis, configure a provider first. See the
[CLI and Evidence guide](docs/cli.md) for native commands, provider selection,
snapshots and scripting.
Start the MCP adapter with `rea mcp` (or `rea --mcp`) with no target. In the connected agent:
### Update REA
1. Call `open_binary` with any readable local binary or `.hop` path.
2. Call `binary_overview`, then use decompilation, strings, symbols, and xrefs tools.
3. Call `open_binary` again to switch targets. If the new target fails, REA attempts to reopen the previous target.
4. Call `close_binary` when finished. `binary_session` reports current state.
REA changes quickly, and new releases include frequent bug fixes. Keep your
installation up to date.
Relative target paths resolve against the MCP server's working directory. Mach-O/FAT, ELF, PE, and Hopper databases are detected automatically. FAT loading selects the host-compatible architecture.
`HOPPER_TARGET_PATH` is optional and opens an initial target at server startup. `HOPPER_LAUNCHER_PATH` overrides the Hopper launcher. `HOPPER_TARGET_KIND` selects `executable` or `database` for an initial target. `HOPPER_LOADER_ARGS_JSON` overrides REA's derived Hopper loader arguments for supported executable formats.
Manual target-free MCP configuration:
```json
{
"mcpServers":{
"rea":{
"command":"npx",
"args":["-y","@morluto/rea","mcp"]
}
}
}
```
The first `open_binary` can take time while Hopper analyzes the file. Analysis calls made without an open target return an actionable `NoBinaryOpenError`.
## Hopper application behavior
REA starts Hopper when needed; Hopper does not have to be running first. Hopper's launcher internally activates the application, so opening a target may bring Hopper to the foreground. REA asks macOS to start Hopper hidden and in the background when possible, but cannot guarantee that Hopper will remain behind the current application.
Explicit format and architecture loader arguments prevent Hopper's common FAT/ARM selection dialogs. Other Hopper or macOS dialogs can still require a person. REA reports timeouts and setup remediation through the CLI or MCP result instead of trying to answer UI prompts.
Closing a REA session shuts down its bridge and removes its private socket directory. It does not quit a Hopper application the user may be using.
## Local security boundary
Each bridge session uses a random capability token and a Unix socket restricted to the current user. This rejects unauthenticated connections and access from other local user accounts, but it does not defend against a malicious process already running as the same user. REA bounds protocol messages and exposes sanitized error messages instead of launcher stderr or internal exception causes.
This boundary prevents unrelated local processes from accidentally using a bridge session; it is not a sandbox. Opening an untrusted binary still delegates parsing and analysis to Hopper under the current macOS user account.
Real-Hopper verification requires Hopper and two distinct binaries. It checks target-free startup, all 42 tools, analysis, bounded decompilation, target switching, bridge cleanup, and server shutdown. The verifier terminates only Hopper bundle processes that appeared during its run; it preserves Hopper processes that were already running.
To refresh your agent registrations and skill, run the setup command printed
by the update.
The npm package is named `@morluto/rea`, while the product and installed executable remain `REA` and `rea`. Setup writes a floating MCP registration using `npx -y @morluto/rea mcp`. See [CONTRIBUTING.md](CONTRIBUTING.md) for the release checklist and local-tarball verification workflow.
If you use `npx`, update your agent setup with:
Security reports should follow [SECURITY.md](SECURITY.md).
```bash
npx rea-agents@latest setup
```
Review the setup changes and restart your agent. For one-off CLI commands,
use `npx rea-agents@latest` followed by the command.
## How REA works
Your agent calls REA through MCP to inspect the target and trace relevant code.
REA returns findings with their evidence. The agent uses them to ask follow-up
questions, explain the behavior, or write and test an implementation.
CLI commands use the same workflows.
[Open the full-size figure](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## What you can analyze
REA requires Node.js 22.x (>=22.19), 24.x (>=24.11), or 26+, plus npm.
Additional tools and host support depend on the target:
| Target | What REA returns | Requirements and guide |
| Native binaries | Pseudocode, assembly, strings, symbols, calls and references | Hopper, Ghidra or IDA; [native analysis](https://rea.tools/guides/native/) |
| Offline ELF layout | Sections, segments, original symbols/relocations and static mitigation candidates | Caller-supplied pwntools on Linux x64; [binary diagnostics](docs/binary-diagnostics.md) |
| EVM bytecode | Dispatch selectors, byte offsets, inferred arguments and mutability | Local raw/hex carrier; [offline EVM guide](docs/evm-bytecode.md) |
| Recorded Linux crashes | Raw notes, every recorded thread's registers/signals and optional mapping candidates | Caller-supplied pwntools; optional GDB/pwndbg; [recorded crashes](docs/recorded-crashes.md) |
| JavaScript / Electron | Modules, imports, source maps, routes, IPC and native add-on relationships | Node.js and npm; [application analysis](https://rea.tools/guides/javascript/) |
| Websites | Page structure, scripts, network observations and requested screenshots | A Chrome-family browser; [browser analysis](https://rea.tools/guides/browser/) |
| Saved network captures | Requests, responses, exposed payloads and source locations | HAR; mitmdump on Linux for native mitmproxy captures; [capture guide](docs/web-network-captures.md) |
| Android APKs | Manifest declarations, classes, decompiled methods and references | Headless JADX and a full JDK on Linux/macOS/Windows x64; [Android guide](docs/android-analysis.md) |
| Firmware | Regions, extraction results and native-analysis handoffs | Binwalk / Unblob on Linux; [firmware guide](docs/firmware-analysis.md) |
| Packages and resources | File inventories, digests, plists, Apple bundle anatomy and extracted resources | [Artifact and JavaScript guide](docs/javascript-artifact-reconstruction.md), [Apple applications](docs/apple-application-analysis.md) |
| Process behavior | Terminal output, interactions, exit and filesystem observations, and run comparisons | Linux/macOS with a native PTY; [process capture](docs/process-capture.md) |
Static JavaScript and .NET inspection read the supplied files without running
the application. Runtime capture runs or interacts with the selected target
using your user permissions; each runtime guide describes its effects.
<a id="choosing-a-deep-analysis-provider"></a>
Native formats and host support vary by provider. See
[Hopper and Ghidra setup](docs/installation.md#hopper), the
[IDA guide](docs/ida-provider.md), and
[experimental Windows Ghidra support](docs/windows-ghidra-p0.md).
Ghidra also supports [16-bit DOS analysis](docs/ghidra-dos.md).
For large binaries, raise its startup deadline with
`REA_GHIDRA_STARTUP_TIMEOUT_MS`.
For provider selection, see the [CLI guide](docs/cli.md#choose-a-provider).
[](https://rea.tools/showcase/)
### DX-Ball: reconstruct a sound-pan calculation
Follow a sound call into its position-to-pan helper, inspect the instructions,
and turn incomplete pseudocode into C. The reconstruction passes 3,205
original-x86 cases and reproduces all 63 compiled function bytes.
[Read the case study](https://rea.tools/showcase/dx-ball/) ·
<img alt="REA GitHub star history" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
</picture>
</a>
## Disclaimer
REA provides tools for lawful reverse-engineering research, analysis, and reconstruction. You are responsible for obtaining any required authorization and complying with applicable laws. The project does not endorse illegal or unauthorized use.
REA is an open-source software project. We have not issued or endorsed any cryptocurrency or token. Tokens using the REA name are not affiliated with the project.
## Contributing
We'd love your help with REA! [Open an issue](https://github.com/morluto/rea/issues) to
report a bug or suggest a feature, or [send a pull request](https://github.com/morluto/rea/pulls)
to improve the code or docs.
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks,
[testing](docs/testing.md) for verification lanes, and the
[architecture map](docs/architecture.mermaid) for the project structure.
هل وجدت في تطبيق ميزة تريد إضافتها إلى منتجك؟ اطلب من وكيلك استقصاءها باستخدام REA. يستطيع فحص التطبيق من دون شيفرته المصدرية، وشرح طريقة عمل الميزة وعرض الأدلة، ثم بناء نسخة تناسب مشروعك.
يربط REA وكيلك بأدوات لفحص الملفات الثنائية للشيفرة الأصلية، وتطبيقات JavaScript وElectron، وتجميعات .NET، والمواقع. يمكنك أيضًا استخدام الأدوات نفسها من الطرفية. يجري التحليل محليًا، وتتضمن النتائج الأدلة والقيود التي تستند إليها كل خلاصة.
يسجّل الإعداد REA لدى وكيلك ويثبّت تعليمات سير العمل المطابقة. يمكن لتحليل الشيفرة الأصلية استخدام تثبيت موجود من Hopper أو Ghidra؛ ويمكن للإعداد أيضًا تثبيت Hopper اختياريًا بعد موافقتك. لا يحتاج التحليل الثابت لـ JavaScript إلى أي من المحركين.
> **[زر موقع REA](https://rea.tools/)** للاطلاع على تعليمات الإعداد والأدلة المصوّرة ودراسات الحالة الفعلية.
## البدء السريع
### إعداد وكيلك
بعد تثبيت Node.js وnpm، نفّذ:
```bash
npx rea-agents setup
```
اختر الوكلاء، وراجع التغييرات المقترحة، ثم وافق عليها. يضيف الإعداد خادم MCP الخاص بـ REA وتعليمات سير العمل المطابقة، مع الاحتفاظ بنسخ احتياطية من الإعدادات الموجودة. أعد تشغيل وكيلك بعد ذلك.
تتضمن النتيجة الوحدات وعمليات الاستيراد وحدود Electron والأدلة المتعلقة بها. استبدل المسار بمسار هدفك، مثل `"D:/apps/example"` على Windows.
لتثبيت أمر `rea` للاستخدام المعتاد:
```bash
npm install --global rea-agents
rea --help
```
لتحليل الشيفرة الأصلية، هيّئ موفّرًا أولًا. راجع [دليل CLI وEvidence](docs/cli.md) لأوامر تحليل الشيفرة الأصلية، واختيار الموفّر، واللقطات، والاستخدام في السكربتات.
### تحديث REA
يتطور REA بسرعة، وتتضمن الإصدارات الجديدة إصلاحات متكررة للأخطاء. حافظ على تحديث نسختك.
لواجهة CLI المثبّتة عبر npm:
```bash
rea update
```
لتحديث تسجيلات الوكلاء والمهارة، نفّذ أمر الإعداد الذي يعرضه التحديث.
إذا كنت تستخدم `npx`، فحدّث إعداد وكيلك بالأمر التالي:
```bash
npx rea-agents@latest setup
```
راجع تغييرات الإعداد وأعد تشغيل وكيلك. لأوامر CLI التي تنفّذها مرة واحدة، استخدم `npx rea-agents@latest` متبوعًا بالأمر المطلوب.
## كيف يعمل REA
يستدعي وكيلك REA عبر MCP لفحص الهدف وتتبع الشيفرة ذات الصلة. يعيد REA النتائج مع أدلتها. يستخدمها الوكيل لطرح أسئلة متابعة، أو شرح السلوك، أو كتابة تنفيذ واختباره. تستخدم أوامر CLI سير العمل نفسه.
[افتح الشكل بحجمه الكامل](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## ما الذي يمكنك تحليله
يتطلب REA إصدار Node.js 22.x (>=22.19) أو 24.x (>=24.11) أو 26+، إضافة إلى npm. تعتمد الأدوات الإضافية والأنظمة المضيفة المدعومة على الهدف:
| الملفات الثنائية للشيفرة الأصلية | شيفرة شبه برمجية، وتعليمات تجميع، وسلاسل نصية، ورموز، واستدعاءات، ومراجع | Hopper أو Ghidra أو IDA؛ [تحليل الشيفرة الأصلية](https://rea.tools/guides/native/) |
| بنية ELF دون تشغيل | الأقسام والمقاطع والرموز ومعلومات إعادة التموضع الأصلية، وآليات الحماية المحتملة المستدلّ عليها بالفحص الثابت | pwntools يوفّره المستدعي على Linux x64؛ [تشخيص الملفات الثنائية](docs/binary-diagnostics.md) |
| شيفرة EVM البايتية | محددات التوجيه، وإزاحات البايتات، والمعاملات المستنتجة، وقابلية تغيير الحالة | مدخل محلي يحمل بايتات خامًا أو تمثيلًا سداسيًا عشريًا؛ [دليل EVM دون تشغيل](docs/evm-bytecode.md) |
| أعطال Linux المسجّلة | سجلات note الخام، ومسجّلات المعالج/الإشارات لكل خيط مسجّل، وترشيحات اختيارية لخرائط الذاكرة | pwntools يوفّره المستدعي؛ GDB/pwndbg اختياريان؛ [الأعطال المسجّلة](docs/recorded-crashes.md) |
| المواقع | بنية الصفحة، والسكربتات، وملاحظات الشبكة، ولقطات الشاشة المطلوبة | متصفح من عائلة Chrome؛ [تحليل المتصفح](https://rea.tools/guides/browser/) |
| تسجيلات الشبكة المحفوظة | الطلبات، والاستجابات، ومحتويات الحمولة المتاحة، ومواضعها في المصدر | HAR؛ وmitmdump على Linux لتسجيلات mitmproxy بصيغتها الأصلية؛ [دليل تسجيلات الشبكة](docs/web-network-captures.md) |
| تجميعات .NET | البيانات الوصفية، وتعليمات CIL، واعتماديات الشيفرة الأصلية المعلنة، ومقارنات البناء | فحص ثابت؛ [دليل الشيفرة المُدارة](docs/managed-code-analysis.md) |
| حزم Android APK | تصريحات ملف manifest، والأصناف، والدوال الناتجة عن فك الترجمة، والمراجع | JADX دون واجهة رسومية وJDK كامل على Linux/macOS؛ [دليل Android](docs/android-analysis.md) |
| البرامج الثابتة | المناطق، ونتائج الاستخراج، وما يُمرّر إلى تحليل الشيفرة الأصلية | Binwalk / Unblob على Linux؛ [دليل البرامج الثابتة](docs/firmware-analysis.md) |
| سلوك العمليات | مخرجات الطرفية، والتفاعلات، وملاحظات الخروج ونظام الملفات، ومقارنات التشغيل | Linux/macOS مع PTY أصلي؛ [تسجيل سلوك العمليات](docs/process-capture.md) |
يقرأ الفحص الثابت لـ JavaScript و.NET الملفات المقدّمة دون تشغيل التطبيق. يشغّل التسجيل أثناء التنفيذ الهدف المحدد أو يتفاعل معه بصلاحيات مستخدمك؛ ويشرح كل دليل للتسجيل أثناء التنفيذ آثاره.
<a id="choosing-a-deep-analysis-provider"></a>
تختلف صيغ ملفات الشيفرة الأصلية والأنظمة المضيفة المدعومة باختلاف الموفّر. راجع [إعداد Hopper وGhidra](docs/installation.md#hopper)، و[دليل IDA](docs/ida-provider.md)، و[دعم Ghidra التجريبي على Windows](docs/windows-ghidra-p0.md). يدعم Ghidra أيضًا [تحليل DOS ذي 16 بت](docs/ghidra-dos.md). لاختيار الموفّر، راجع [دليل CLI](docs/cli.md#choose-a-provider). تحقّق من [توفر الميزات في الإصدارات](docs/installation.md#released-package-and-main) للميزات المضافة بعد أحدث إصدار على npm.
## دراسات الحالة
[](https://rea.tools/showcase/)
### DX-Ball: إعادة بناء حساب توزيع الصوت بين القناتين
تتبّع استدعاء صوت إلى الدالة المساعدة التي تحوّل الموضع إلى توزيع بين القناتين، وافحص التعليمات، وحوّل الشيفرة شبه البرمجية غير المكتملة إلى C. تجتاز إعادة البناء 3,205 حالات اختبار على x86 الأصلي، وتعيد إنتاج جميع بايتات الدالة المترجمة البالغ عددها 63 بايتًا.
[اقرأ دراسة الحالة](https://rea.tools/showcase/dx-ball/) ·
[مستودع إعادة البناء](https://github.com/N0zoM1z0/dx-ball)
### Notion: تتبّع جسر الحافظة في Electron
اعثر على API الحافظة في عملية العرض، وتتبّعه عبر preload وIPC إلى العملية الرئيسية، وافحص صيغة الحافظة ذات التنسيق الغني.
[اقرأ دراسة الحالة](https://rea.tools/showcase/notion/)
### TH04: استعادة حساب حلقة المقذوفات في DOS
افحص تعليمات اللعبة الأصلية على PC-98 ذات 16 بت، واستعد حساب الزوايا الثابتة والموجّهة نحو الهدف، وقارن شيفرة C++ المعاد بناؤها بمخرجات المترجم المستخدم آنذاك.
[اقرأ دراسة الحالة](https://rea.tools/showcase/th04/) ·
[مستودع إعادة البناء](https://github.com/N0zoM1z0/th04)
إذا استخدمت REA لفحص هدف مثير للاهتمام، فنود الاطلاع عليه. شارك حالتك في [issue](https://github.com/morluto/rea/issues) أو [pull request](https://github.com/morluto/rea/pulls)، مع ذكر الهدف، وسؤالك، وكيف ساعدك REA، وما توصلت إليه.
## الأسئلة الشائعة
<details>
<summary><strong>أي وكلاء يمكنهم استخدام REA؟</strong></summary>
أي وكيل يدعم خوادم MCP المحلية. يهيّئ الإعداد [الوكلاء المدعومين](docs/installation.md#supported-agents)؛ ويمكن للعملاء الآخرين استخدام [تسجيل MCP يدويًا](docs/installation.md#mcp-registry).
</details>
<details>
<summary><strong>هل أحتاج إلى Hopper أو Ghidra أو IDA؟</strong></summary>
يستخدم تحليل الشيفرة الأصلية المتعمق أحدها. يعمل الفحص الثابت لـ JavaScript و.NET دون محرك لتحليل الشيفرة الأصلية. يستطيع الإعداد تثبيت Hopper بعد الموافقة؛ أما Ghidra وIDA فيستخدمان تثبيتاتك الموجودة. راجع [إعداد الموفّرين](docs/installation.md#hopper).
</details>
<details>
<summary><strong>هل أحتاج إلى تشغيل Hopper أولًا؟</strong></summary>
يشغّل REA برنامج Hopper عندما تحتاج العملية إليه. على macOS، قد تظهر عند التشغيل الأول نافذة تطلب اختيار وضع العرض التجريبي أو تفعيل الترخيص. راجع [تشغيل Hopper واستكشاف الأخطاء](docs/installation.md#launcher-paths-and-troubleshooting).
</details>
<details>
<summary><strong>ماذا يفعل تثبيت المهارة من skills.sh؟</strong></summary>
توفّر المهارة تعليمات الاستقصاء لوكيلك. استخدم `npx rea-agents setup` لتسجيل خادم MCP الخاص بـ REA وتثبيت التعليمات المطابقة، ثم أعد تشغيل وكيلك. راجع [تثبيت المهارة وحدها](docs/installation.md#skill-only-installation).
</details>
<details>
<summary><strong>ما الشيفرة التي يعيدها REA؟</strong></summary>
يعيد تحليل الشيفرة الأصلية شيفرة شبه برمجية وتعليمات تجميع. يستعيد تحليل JavaScript/Electron الوحدات والعلاقات بينها. يستخدم وكيلك هذه النتائج لكتابة تنفيذ واختباره؛ وتقدّم [دراسات الحالة](#دراسات-الحالة) أمثلة عملية.
</details>
<details>
<summary><strong>هل يرفع REA تطبيقي؟</strong></summary>
يحلّل REA الأهداف محليًا. يتلقى وكيلك نتائج الأدوات، ولموفّر النموذج الذي يستخدمه سياسة بيانات خاصة به.
</details>
<details>
<summary><strong>ماذا أفعل إذا واجهت خطأ؟</strong></summary>
حدّث أولًا؛ فقد يكون إصدار حديث قد أصلح المشكلة بالفعل.
لواجهة CLI المثبّتة عبر npm:
```bash
rea update
```
لإعداد الوكيل عبر `npx`:
```bash
npx rea-agents@latest setup
```
إذا كنت تستخدم وكيلًا، فأكمل [تحديث الإعداد](#تحديث-rea) وأعد تشغيله. أعد محاولة المهمة نفسها. إذا استمرت المشكلة، [افتح issue](https://github.com/morluto/rea/issues) يتضمن إصدار REA، ونوع الهدف، وخطوات إعادة الإنتاج، ومخرجات الخطأ.
</details>
## التوثيق
ابدأ بـ [الأدلة العملية](https://rea.tools/guides/) على الموقع. للخيارات الدقيقة والمتطلبات وعقود النتائج:
- [التثبيت والإعداد](docs/installation.md): تسجيل الوكلاء، وتهيئة الموفّرين، والتحديثات، وإلغاء التثبيت.
- [الجاهزية واستكشاف الأخطاء](docs/installation.md#check-readiness-for-your-task): تشخيص وكيل أو محرك تحليل محدد.
<img alt="سجل نجوم REA على GitHub" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
</picture>
</a>
## إخلاء المسؤولية
يوفّر REA أدوات لأبحاث الهندسة العكسية والتحليل وإعادة البناء المشروعة. أنت مسؤول عن الحصول على أي تفويض مطلوب والالتزام بالقوانين المعمول بها. لا يؤيد المشروع الاستخدام غير القانوني أو غير المصرّح به.
## المساهمة
نرحّب بمساعدتك في تطوير REA! [افتح issue](https://github.com/morluto/rea/issues) للإبلاغ عن خطأ أو اقتراح ميزة، أو [أرسل pull request](https://github.com/morluto/rea/pulls) لتحسين الشيفرة أو التوثيق.
<sub>Discord · Fragen und Antworten · Ergebnisse teilen</sub>
</td>
</tr>
</table>
<br />
</div>
---
Du hast in einer App eine Funktion entdeckt, die du in dein eigenes Produkt übernehmen möchtest? Lass deinen Agenten sie mit REA untersuchen. Er kann die App ohne ihren Quellcode analysieren, die Funktionsweise erklären, Belege zeigen und eine passende Umsetzung für dein Projekt entwickeln.
REA verbindet deinen Agenten mit Werkzeugen zum Untersuchen nativer Binärdateien, von JavaScript- und Electron-Apps, .NET-Assemblies und Websites. Dieselben Werkzeuge kannst du auch im Terminal nutzen. Die Analyse läuft lokal; die Ergebnisse enthalten die Belege und Einschränkungen hinter jeder Schlussfolgerung.
Die Einrichtung registriert REA bei deinem Agenten und installiert passende Workflow-Anweisungen. Für native Analysen kannst du eine vorhandene Hopper- oder Ghidra-Installation verwenden. Mit deiner Zustimmung kann die Einrichtung auch Hopper installieren. Statische JavaScript-Analysen benötigen keines der beiden Programme.
> **[Besuche die REA-Website](https://rea.tools/)** für Einrichtungshinweise, bebilderte Anleitungen und echte Fallstudien.
## Schnellstart
### Deinen Agenten einrichten
Wenn Node.js und npm installiert sind, führe diesen Befehl aus:
```bash
npx rea-agents setup
```
Wähle deine Agenten aus, prüfe die geplanten Änderungen und bestätige sie. Die Einrichtung fügt den MCP-Server von REA und passende Workflow-Anweisungen hinzu und sichert vorhandene Konfigurationen. Starte deinen Agenten anschließend neu.
Die Einrichtung unterstützt Claude Code, Codex, Cursor, Gemini CLI, Grok Build und [weitere Agenten](docs/installation.md#supported-agents). Informationen zur Provider-Konfiguration und manuellen MCP-Registrierung findest du unter [Installation und Einrichtung](docs/installation.md).
### Deinen Agenten fragen
```text
Untersuche, wie die Suche in der Notes-App funktioniert, zeige mir die Belege und entwickle eine ähnliche Funktion für mein Projekt.
```
Ersetze Notes durch deine Ziel-App und benenne die Funktion, die du verstehen möchtest.
### Das Terminal verwenden
Untersuche ein entpacktes JavaScript-/Electron-App-Verzeichnis oder eine ASAR-Datei:
Das Ergebnis enthält Module, Imports, Electron-Grenzen und die zugehörigen Belege. Ersetze den Pfad durch dein Ziel, beispielsweise `"D:/apps/example"` unter Windows.
Für die regelmäßige Nutzung kannst du den Befehl `rea` installieren:
```bash
npm install --global rea-agents
rea --help
```
Konfiguriere für native Analysen zuerst einen Provider. Native Befehle, Provider-Auswahl, Snapshots und Skriptnutzung beschreibt der [CLI- und Evidence-Leitfaden](docs/cli.md).
### REA aktualisieren
REA entwickelt sich schnell weiter; neue Versionen enthalten häufig Fehlerbehebungen. Halte deine Installation aktuell.
Für eine über npm installierte CLI:
```bash
rea update
```
Um die Agentenregistrierungen und den Skill zu aktualisieren, führe den Einrichtungsbefehl aus, den das Update ausgibt.
Wenn du `npx` verwendest, aktualisiere die Agenteneinrichtung mit:
```bash
npx rea-agents@latest setup
```
Prüfe die Änderungen und starte deinen Agenten neu. Für einzelne CLI-Aufrufe verwende `npx rea-agents@latest`, gefolgt vom gewünschten Befehl.
## So funktioniert REA
Dein Agent ruft REA über MCP auf, um das Ziel zu untersuchen und relevanten Code zu verfolgen. REA liefert Ergebnisse mit ihren Belegen zurück. Der Agent nutzt sie für weitere Fragen, Erklärungen oder zum Schreiben und Testen einer Implementierung. CLI-Befehle verwenden dieselben Workflows.
[Abbildung in voller Größe öffnen](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## Was du analysieren kannst
REA benötigt Node.js 22.x (>=22.19), 24.x (>=24.11) oder 26+ sowie npm. Zusätzliche Werkzeuge und unterstützte Hostsysteme hängen vom Ziel ab:
| Ziel | Was REA zurückgibt | Voraussetzungen und Anleitung |
| Native Binärdateien | Pseudocode, Assemblercode, Zeichenketten, Symbole, Aufrufe und Verweise | Hopper, Ghidra oder IDA; [native Analyse](https://rea.tools/guides/native/) |
| Offline-ELF-Struktur | Sektionen, Segmente, ursprüngliche Symbole/Relokationen und mögliche Schutzmaßnahmen aus statischer Analyse | Vom Aufrufer bereitgestelltes pwntools unter Linux x64; [Binärdiagnostik](docs/binary-diagnostics.md) |
| EVM-Bytecode | Dispatch-Selektoren, Byte-Offsets, abgeleitete Argumente und Veränderbarkeit des Zustands | Lokale Eingabe mit Rohbytes oder Hexdarstellung; [Offline-EVM-Leitfaden](docs/evm-bytecode.md) |
| Aufgezeichnete Linux-Abstürze | Unverarbeitete Note-Einträge, Register/Signale aller aufgezeichneten Threads und optionale Zuordnungskandidaten | Vom Aufrufer bereitgestelltes pwntools; optional GDB/pwndbg; [aufgezeichnete Abstürze](docs/recorded-crashes.md) |
| JavaScript / Electron | Module, Imports, Source Maps, Routen, IPC und Beziehungen zu nativen Add-ons | Node.js und npm; [Anwendungsanalyse](https://rea.tools/guides/javascript/) |
| Websites | Seitenstruktur, Skripte, Netzwerkbeobachtungen und angeforderte Screenshots | Ein Browser aus der Chrome-Familie; [Browseranalyse](https://rea.tools/guides/browser/) |
| Gespeicherte Netzwerkaufzeichnungen | Anfragen, Antworten, zugängliche Nutzdaten und Quellpositionen | HAR; mitmdump unter Linux für Aufzeichnungen im nativen mitmproxy-Format; [Leitfaden zu Netzwerkaufzeichnungen](docs/web-network-captures.md) |
| .NET-Assemblies | Metadaten, CIL-Anweisungen, deklarierte native Abhängigkeiten und Build-Vergleiche | Statische Untersuchung; [Leitfaden für verwalteten Code](docs/managed-code-analysis.md) |
| Android-APKs | Manifest-Deklarationen, Klassen, dekompilierte Methoden und Verweise | JADX ohne grafische Oberfläche und ein vollständiges JDK unter Linux/macOS; [Android-Leitfaden](docs/android-analysis.md) |
| Firmware | Bereiche, Extraktionsergebnisse und Übergaben an die native Analyse | Binwalk / Unblob unter Linux; [Firmware-Leitfaden](docs/firmware-analysis.md) |
| Pakete und Ressourcen | Dateiinventare, Hashwerte, plists, Aufbau von Apple-Bundles und extrahierte Ressourcen | [Artefakt- und JavaScript-Leitfaden](docs/javascript-artifact-reconstruction.md), [Apple-Anwendungen](docs/apple-application-analysis.md) |
| Prozessverhalten | Terminalausgabe, Interaktionen, Beobachtungen zu Prozessende und Dateisystem sowie Laufvergleiche | Linux/macOS mit nativer PTY; [Prozessaufzeichnung](docs/process-capture.md) |
Statische JavaScript- und .NET-Untersuchungen lesen die bereitgestellten Dateien, ohne die Anwendung auszuführen. Laufzeitaufzeichnungen führen das gewählte Ziel mit deinen Benutzerrechten aus oder interagieren damit; die jeweiligen Anleitungen beschreiben die Auswirkungen.
<a id="choosing-a-deep-analysis-provider"></a>
Native Formate und unterstützte Hostsysteme unterscheiden sich je nach Provider. Siehe [Hopper- und Ghidra-Einrichtung](docs/installation.md#hopper), den [IDA-Leitfaden](docs/ida-provider.md) und die [experimentelle Ghidra-Unterstützung unter Windows](docs/windows-ghidra-p0.md). Ghidra unterstützt auch [16-Bit-DOS-Analyse](docs/ghidra-dos.md). Die Provider-Auswahl beschreibt der [CLI-Leitfaden](docs/cli.md#choose-a-provider). Prüfe die [Verfügbarkeit in Releases](docs/installation.md#released-package-and-main) für Funktionen, die seit der neuesten npm-Version hinzugekommen sind.
## Fallstudien
[](https://rea.tools/showcase/)
### DX-Ball: Eine Stereo-Panning-Berechnung rekonstruieren
Verfolge einen Sound-Aufruf zur Hilfsfunktion, die Positionen in Panning-Werte umrechnet, untersuche die Anweisungen und überführe unvollständigen Pseudocode in C. Die Rekonstruktion besteht 3.205 Tests mit dem ursprünglichen x86-Code und reproduziert alle 63 Bytes der kompilierten Funktion.
### Notion: Die Electron-Zwischenablagebrücke verfolgen
Finde die Zwischenablage-API des Renderers, verfolge sie über preload und IPC bis zum Hauptprozess und untersuche das Zwischenablageformat samt Formatierungsdaten.
### TH04: Eine DOS-Geschossring-Berechnung wiederherstellen
Untersuche die 16-Bit-Anweisungen des ursprünglichen PC-98-Spiels, rekonstruiere die festen und zielgerichteten Winkelberechnungen und vergleiche das rekonstruierte C++ mit der Ausgabe des damaligen Compilers.
Wenn du mit REA etwas Interessantes untersucht hast, würden wir es gern sehen. Teile deine Fallstudie in einem [Issue](https://github.com/morluto/rea/issues) oder [Pull Request](https://github.com/morluto/rea/pulls) und beschreibe das Ziel, deine Frage, wie REA geholfen hat und was du herausgefunden hast.
## Häufige Fragen
<details>
<summary><strong>Welche Agenten können REA verwenden?</strong></summary>
Jeder Agent, der lokale MCP-Server unterstützt. Die Einrichtung konfiguriert die [unterstützten Agenten](docs/installation.md#supported-agents); andere Clients können die [manuelle MCP-Registrierung](docs/installation.md#mcp-registry) nutzen.
</details>
<details>
<summary><strong>Brauche ich Hopper, Ghidra oder IDA?</strong></summary>
Für tiefgehende native Analysen wird eines dieser Programme verwendet. Statische JavaScript- und .NET-Untersuchungen funktionieren ohne native Analyse-Engine. Die Einrichtung kann Hopper nach Zustimmung installieren; Ghidra und IDA nutzen deine vorhandenen Installationen. Siehe [Provider-Einrichtung](docs/installation.md#hopper).
</details>
<details>
<summary><strong>Muss ich Hopper vorher starten?</strong></summary>
REA startet Hopper, wenn eine Operation es benötigt. Unter macOS kann beim ersten Start ein Dialog erscheinen, in dem du den Demomodus auswählst oder deine Lizenz aktivierst. Siehe [Hopper-Start und Fehlerbehebung](docs/installation.md#launcher-paths-and-troubleshooting).
</details>
<details>
<summary><strong>Was bewirkt die Installation des Skills über skills.sh?</strong></summary>
Der Skill stellt Untersuchungsanweisungen für deinen Agenten bereit. Verwende `npx rea-agents setup`, um den MCP-Server von REA zu registrieren und passende Anweisungen zu installieren. Starte deinen Agenten anschließend neu. Siehe [Installation nur des Skills](docs/installation.md#skill-only-installation).
</details>
<details>
<summary><strong>Welchen Code liefert REA zurück?</strong></summary>
Native Analysen liefern Pseudocode und Assemblercode. JavaScript-/Electron-Analysen rekonstruieren Module und ihre Beziehungen. Dein Agent nutzt diese Ergebnisse zum Schreiben und Testen einer Implementierung; die [Fallstudien](#fallstudien) zeigen konkrete Beispiele.
</details>
<details>
<summary><strong>Lädt REA meine App hoch?</strong></summary>
REA analysiert Ziele lokal. Dein Agent erhält die Werkzeugergebnisse; sein Modellanbieter hat eine eigene Datenrichtlinie.
</details>
<details>
<summary><strong>Was soll ich tun, wenn ich einen Fehler finde?</strong></summary>
Aktualisiere zuerst; eine neuere Version könnte den Fehler bereits behoben haben.
Für eine über npm installierte CLI:
```bash
rea update
```
Für die Agenteneinrichtung über `npx`:
```bash
npx rea-agents@latest setup
```
Wenn du einen Agenten verwendest, schließe die [Aktualisierung der Einrichtung](#rea-aktualisieren) ab und starte ihn neu. Wiederhole dieselbe Aufgabe. Besteht das Problem weiterhin, [öffne ein Issue](https://github.com/morluto/rea/issues) mit deiner REA-Version, dem Zieltyp, den Reproduktionsschritten und der Fehlerausgabe.
</details>
## Dokumentation
Beginne mit den [praxisnahen Anleitungen](https://rea.tools/guides/) auf der Website. Genaue Optionen, Voraussetzungen und Ergebniskontrakte findest du hier:
- [Installation und Einrichtung](docs/installation.md): Agentenregistrierung, Provider-Konfiguration, Updates und Deinstallation.
- [Bereitschaft und Fehlerbehebung](docs/installation.md#check-readiness-for-your-task): Diagnose eines bestimmten Agenten oder einer Analyse-Engine.
- [CLI und Evidence](docs/cli.md): Befehle, Provider-Auswahl, Snapshots, Import/Export und Exit-Status.
- [MCP-Kontrakte](docs/mcp-contracts.md) und [Agenten-Prompts](docs/mcp-prompts.md): Werkzeugergebnisse, Sitzungen und geführte Untersuchungen.
- [Werkzeugkatalog](docs/mcp-contracts.md#generated-catalog): Beim Build erzeugtes Inventar von Werkzeugen, Providern und CLI-Befehlen.
- [Roadmap](docs/roadmap.md): Geplante Arbeiten und Fortschrittsübersichten zu Fähigkeiten.
<img alt="GitHub-Sternverlauf von REA" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
</picture>
</a>
## Haftungsausschluss
REA stellt Werkzeuge für rechtmäßige Reverse-Engineering-Forschung, Analyse und Rekonstruktion bereit. Du bist dafür verantwortlich, erforderliche Genehmigungen einzuholen und geltendes Recht einzuhalten. Das Projekt unterstützt keine rechtswidrige oder unbefugte Nutzung.
## Mitwirken
Wir freuen uns über deine Hilfe bei REA! [Öffne ein Issue](https://github.com/morluto/rea/issues), um einen Fehler zu melden oder eine Funktion vorzuschlagen, oder [sende einen Pull Request](https://github.com/morluto/rea/pulls), um Code oder Dokumentation zu verbessern.
Die Entwicklungsumgebung und Prüfungen beschreibt [CONTRIBUTING.md](CONTRIBUTING.md), die Verifikationspfade der [Testleitfaden](docs/testing.md) und die Projektstruktur die [Architekturübersicht](docs/architecture.mermaid).
<img src="docs/assets/rea-hopper-analysis.png" alt="REA inicia su puente de análisis dentro de Hopper mientras inspecciona un binario nativo" width="1200" />
<strong>Únete a la comunidad de ingeniería inversa</strong>
</a><br />
<sub>Discord · Preguntas y respuestas · Comparte tus resultados</sub>
</td>
</tr>
</table>
<br />
</div>
---
¿Has visto una función en una aplicación que quieres incorporar a tu producto? Pide a tu agente que la investigue con REA. Puede inspeccionar la aplicación sin su código fuente, explicar cómo funciona la función, mostrar las pruebas y crear una versión para tu proyecto.
REA conecta tu agente con herramientas para inspeccionar binarios nativos, aplicaciones JavaScript y Electron, ensamblados .NET y sitios web. También puedes usar las mismas herramientas desde la terminal. El análisis se ejecuta localmente y los resultados incluyen las pruebas y limitaciones que sustentan cada conclusión.
La configuración registra REA en tu agente e instala las instrucciones de trabajo correspondientes. El análisis nativo puede usar una instalación existente de Hopper o Ghidra; la configuración también puede instalar Hopper, si lo autorizas. El análisis estático de JavaScript no necesita ninguno de los dos motores.
> **[Visita el sitio web de REA](https://rea.tools/)** para encontrar instrucciones de configuración, guías ilustradas y casos reales.
## Inicio rápido
### Configura tu agente
Con Node.js y npm instalados, ejecuta:
```bash
npx rea-agents setup
```
Elige tus agentes, revisa los cambios propuestos y apruébalos. La configuración añade el servidor MCP de REA y las instrucciones de trabajo correspondientes, con copias de seguridad de la configuración existente. Reinicia tu agente al terminar.
La configuración admite Claude Code, Codex, Cursor, Gemini CLI, Grok Build y [otros agentes](docs/installation.md#supported-agents). Consulta [instalación y configuración](docs/installation.md) para configurar proveedores y registrar MCP manualmente.
### Pregunta a tu agente
```text
Investiga cómo funciona la búsqueda en la aplicación Notes, muéstrame las pruebas y crea una función similar para mi proyecto.
```
Sustituye Notes por la aplicación objetivo y especifica la función que quieres entender.
### Usa la terminal
Inspecciona un directorio extraído de una aplicación JavaScript/Electron o un archivo ASAR:
El resultado incluye módulos, importaciones, límites de Electron y sus pruebas. Sustituye la ruta por la de tu objetivo, por ejemplo `"D:/apps/example"` en Windows.
Para instalar el comando `rea` y usarlo habitualmente:
```bash
npm install --global rea-agents
rea --help
```
Para el análisis nativo, configura primero un proveedor. Consulta la [guía de CLI y Evidence](docs/cli.md) para los comandos nativos, la selección de proveedores, las instantáneas y el uso en scripts.
### Actualiza REA
REA cambia rápidamente y las nuevas versiones incluyen correcciones frecuentes. Mantén tu instalación actualizada.
Para una CLI instalada mediante npm:
```bash
rea update
```
Para actualizar los registros de tus agentes y la skill, ejecuta el comando de configuración que muestra la actualización.
Si usas `npx`, actualiza la configuración de tu agente con:
```bash
npx rea-agents@latest setup
```
Revisa los cambios de configuración y reinicia tu agente. Para ejecutar comandos de CLI puntuales, usa `npx rea-agents@latest` seguido del comando.
## Cómo funciona REA
Tu agente llama a REA mediante MCP para inspeccionar el objetivo y seguir el código relevante. REA devuelve los hallazgos junto con sus pruebas. El agente los utiliza para hacer preguntas de seguimiento, explicar el comportamiento o escribir y probar una implementación. Los comandos de CLI usan los mismos flujos de trabajo.
[Abre la figura a tamaño completo](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## Qué puedes analizar
REA requiere Node.js 22.x (>=22.19), 24.x (>=24.11) o 26+, además de npm. Las herramientas adicionales y los sistemas anfitriones compatibles dependen del objetivo:
| Objetivo | Qué devuelve REA | Requisitos y guía |
| Binarios nativos | Pseudocódigo, ensamblador, cadenas, símbolos, llamadas y referencias | Hopper, Ghidra o IDA; [análisis nativo](https://rea.tools/guides/native/) |
| Estructura ELF sin ejecutar | Secciones, segmentos, símbolos/reubicaciones originales y posibles medidas de mitigación detectadas mediante análisis estático | pwntools proporcionado por quien llama, en Linux x64; [diagnóstico de binarios](docs/binary-diagnostics.md) |
| Bytecode EVM | Selectores de despacho, desplazamientos en bytes, argumentos inferidos y mutabilidad | Entrada local con bytes sin procesar o representación hexadecimal; [guía de EVM sin ejecutar](docs/evm-bytecode.md) |
| Fallos de Linux registrados | Registros note sin procesar, registros/señales de cada hilo registrado y posibles correspondencias de memoria opcionales | pwntools proporcionado por quien llama; GDB/pwndbg opcionales; [fallos registrados](docs/recorded-crashes.md) |
| JavaScript / Electron | Módulos, importaciones, mapas de código fuente, rutas, IPC y relaciones con complementos nativos | Node.js y npm; [análisis de aplicaciones](https://rea.tools/guides/javascript/) |
| Sitios web | Estructura de la página, scripts, observaciones de red y capturas de pantalla solicitadas | Un navegador de la familia Chrome; [análisis del navegador](https://rea.tools/guides/browser/) |
| Capturas de red guardadas | Solicitudes, respuestas, contenido accesible de las cargas útiles y ubicaciones de origen | HAR; mitmdump en Linux para capturas en formato nativo de mitmproxy; [guía de capturas](docs/web-network-captures.md) |
| Ensamblados .NET | Metadatos, instrucciones CIL, dependencias nativas declaradas y comparaciones de compilaciones | Inspección estática; [guía de código administrado](docs/managed-code-analysis.md) |
| APK de Android | Declaraciones del manifiesto, clases, métodos descompilados y referencias | JADX sin interfaz gráfica y un JDK completo en Linux/macOS; [guía de Android](docs/android-analysis.md) |
| Firmware | Regiones, resultados de extracción y derivaciones al análisis nativo | Binwalk / Unblob en Linux; [guía de firmware](docs/firmware-analysis.md) |
| Paquetes y recursos | Inventarios de archivos, resúmenes criptográficos, plists, estructura de paquetes de Apple y recursos extraídos | [Guía de artefactos y JavaScript](docs/javascript-artifact-reconstruction.md), [aplicaciones de Apple](docs/apple-application-analysis.md) |
| Comportamiento de procesos | Salida de la terminal, interacciones, observaciones de salida y del sistema de archivos, y comparaciones entre ejecuciones | Linux/macOS con una PTY nativa; [captura de procesos](docs/process-capture.md) |
La inspección estática de JavaScript y .NET lee los archivos suministrados sin ejecutar la aplicación. La captura en ejecución inicia el objetivo seleccionado o interactúa con él con los permisos de tu usuario; cada guía describe sus efectos.
<a id="choosing-a-deep-analysis-provider"></a>
Los formatos nativos y los sistemas anfitriones compatibles varían según el proveedor. Consulta [configuración de Hopper y Ghidra](docs/installation.md#hopper), la [guía de IDA](docs/ida-provider.md) y la [compatibilidad experimental de Ghidra en Windows](docs/windows-ghidra-p0.md). Ghidra también admite [análisis de DOS de 16 bits](docs/ghidra-dos.md). Para elegir un proveedor, consulta la [guía de CLI](docs/cli.md#choose-a-provider). Comprueba la [disponibilidad por versión](docs/installation.md#released-package-and-main) de las funciones añadidas después de la última versión publicada en npm.
## Casos prácticos
[](https://rea.tools/showcase/)
### DX-Ball: reconstruir un cálculo de panoramización de sonido
Sigue una llamada de sonido hasta la función auxiliar que convierte la posición en panoramización, inspecciona las instrucciones y transforma el pseudocódigo incompleto en C. La reconstrucción supera 3.205 casos con el x86 original y reproduce los 63 bytes de la función compilada.
[Lee el caso práctico](https://rea.tools/showcase/dx-ball/) · [Repositorio de reconstrucción](https://github.com/N0zoM1z0/dx-ball)
### Notion: seguir el puente del portapapeles de Electron
Encuentra la API del portapapeles del proceso de renderizado, síguela a través de preload e IPC hasta el proceso principal e inspecciona el formato enriquecido del portapapeles.
[Lee el caso práctico](https://rea.tools/showcase/notion/)
### TH04: recuperar el cálculo de un anillo de proyectiles en DOS
Inspecciona las instrucciones de 16 bits del juego original para PC-98, recupera los cálculos de ángulos fijos y dirigidos, y compara el C++ reconstruido con la salida del compilador de la época.
[Lee el caso práctico](https://rea.tools/showcase/th04/) · [Repositorio de reconstrucción](https://github.com/N0zoM1z0/th04)
Si has usado REA para investigar algo interesante, nos gustaría verlo. Comparte tu caso en una [issue](https://github.com/morluto/rea/issues) o una [pull request](https://github.com/morluto/rea/pulls), incluyendo el objetivo, tu pregunta, cómo te ayudó REA y qué encontraste.
## Preguntas frecuentes
<details>
<summary><strong>¿Qué agentes pueden usar REA?</strong></summary>
Cualquier agente que admita servidores MCP locales. La configuración prepara los [agentes compatibles](docs/installation.md#supported-agents); otros clientes pueden usar el [registro manual de MCP](docs/installation.md#mcp-registry).
</details>
<details>
<summary><strong>¿Necesito Hopper, Ghidra o IDA?</strong></summary>
El análisis nativo en profundidad utiliza uno de ellos. La inspección estática de JavaScript y .NET funciona sin un motor de análisis nativo. La configuración puede instalar Hopper después de tu aprobación; Ghidra e IDA usan las instalaciones que ya tienes. Consulta [configuración de proveedores](docs/installation.md#hopper).
</details>
<details>
<summary><strong>¿Tengo que iniciar Hopper primero?</strong></summary>
REA inicia Hopper cuando una operación lo necesita. En macOS, puede aparecer un diálogo al iniciarlo por primera vez para elegir el modo de demostración o activar tu licencia. Consulta [inicio de Hopper y resolución de problemas](docs/installation.md#launcher-paths-and-troubleshooting).
</details>
<details>
<summary><strong>¿Qué hace la instalación de la skill desde skills.sh?</strong></summary>
La skill proporciona instrucciones de investigación a tu agente. Usa `npx rea-agents setup` para registrar el servidor MCP de REA e instalar las instrucciones correspondientes; después reinicia tu agente. Consulta [instalación solo de la skill](docs/installation.md#skill-only-installation).
El análisis nativo devuelve pseudocódigo y ensamblador. El análisis de JavaScript/Electron recupera módulos y sus relaciones. Tu agente utiliza estos hallazgos para escribir y probar una implementación; los [casos prácticos](#casos-prácticos) ofrecen ejemplos completos.
</details>
<details>
<summary><strong>¿REA sube mi aplicación?</strong></summary>
REA analiza los objetivos localmente. Tu agente recibe los resultados de las herramientas, y su proveedor de modelos tiene su propia política de datos.
</details>
<details>
<summary><strong>¿Qué debo hacer si encuentro un error?</strong></summary>
Actualiza primero; una versión reciente puede haber solucionado el problema.
Para una CLI instalada mediante npm:
```bash
rea update
```
Para configurar el agente mediante `npx`:
```bash
npx rea-agents@latest setup
```
Si usas un agente, completa la [actualización de la configuración](#actualiza-rea) y reinícialo. Repite la misma tarea. Si el problema continúa, [abre una issue](https://github.com/morluto/rea/issues) con tu versión de REA, el tipo de objetivo, los pasos para reproducirlo y la salida del error.
</details>
## Documentación
Empieza con las [guías prácticas](https://rea.tools/guides/) del sitio web. Para opciones exactas, requisitos y contratos de resultados:
- [Instalación y configuración](docs/installation.md): registro de agentes, configuración de proveedores, actualizaciones y desinstalación.
- [Preparación y resolución de problemas](docs/installation.md#check-readiness-for-your-task): diagnóstico de un agente o motor de análisis concreto.
- [CLI y Evidence](docs/cli.md): comandos, selección de proveedores, instantáneas, importación/exportación y estados de salida.
- [Contratos de MCP](docs/mcp-contracts.md) y [prompts para agentes](docs/mcp-prompts.md): resultados de herramientas, sesiones e investigaciones guiadas.
- [Catálogo de herramientas](docs/mcp-contracts.md#generated-catalog): inventario de herramientas, proveedores y comandos de CLI generado durante la compilación.
- [Hoja de ruta](docs/roadmap.md): trabajo previsto y seguimiento de capacidades.
Informa de vulnerabilidades siguiendo [SECURITY.md](SECURITY.md).
## Historial de estrellas
🎉 **40.000 estrellas en GitHub: ¡gracias!**
Gracias a quienes usan REA, informan de errores, solicitan funciones, prueban compilaciones y contribuyen con correcciones.
<img alt="Historial de estrellas de REA en GitHub" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
</picture>
</a>
## Aviso legal
REA proporciona herramientas para la investigación, el análisis y la reconstrucción mediante ingeniería inversa conforme a la ley. Eres responsable de obtener las autorizaciones necesarias y cumplir las leyes aplicables. El proyecto no respalda usos ilegales ni no autorizados.
## Contribuir
¡Nos encantaría que ayudaras con REA! [Abre una issue](https://github.com/morluto/rea/issues) para comunicar un error o proponer una función, o [envía una pull request](https://github.com/morluto/rea/pulls) para mejorar el código o la documentación.
Consulta [CONTRIBUTING.md](CONTRIBUTING.md) para preparar el entorno de desarrollo y las comprobaciones, la [guía de pruebas](docs/testing.md) para los procesos de verificación y el [mapa de arquitectura](docs/architecture.mermaid) para la estructura del proyecto.
قابلیتی در یک برنامه دیدهاید که میخواهید در محصول خودتان داشته باشید؟ از ایجنت خود بخواهید با REA آن را بررسی کند. ایجنت میتواند بدون دسترسی به کد منبع برنامه، نحوهٔ کار قابلیت را بررسی و توضیح دهد، شواهد را نشان دهد و نسخهای مشابه برای پروژهٔ شما بسازد.
REA ایجنت شما را به ابزارهایی برای بررسی باینریهای بومی، برنامههای JavaScript و Electron، اسمبلیهای .NET و وبسایتها متصل میکند. همین ابزارها از ترمینال نیز قابل استفادهاند. تحلیل بهصورت محلی انجام میشود و نتایج شامل شواهد و محدودیتهای پشت هر نتیجهگیری هستند.
فرایند راهاندازی، REA را در ایجنت شما ثبت میکند و دستورالعملهای گردشکار متناظر را نصب میکند. تحلیل بومی میتواند از نصب موجود Hopper یا Ghidra استفاده کند؛ همچنین راهاندازی میتواند با تأیید شما Hopper را بهصورت اختیاری نصب کند. تحلیل ایستای JavaScript به هیچیک از این موتورهای تحلیل نیاز ندارد.
> برای دستورالعملهای راهاندازی، راهنماهای تصویری و مطالعات موردی واقعی، **[به وبسایت REA مراجعه کنید](https://rea.tools/)**.
## شروع سریع
### ایجنت خود را راهاندازی کنید
پس از نصب Node.js و npm، دستور زیر را اجرا کنید:
```bash
npx rea-agents setup
```
ایجنتهای موردنظر را انتخاب کنید، تغییرات پیشنهادی را بررسی و تأیید کنید. فرایند راهاندازی، سرور MCP مربوط به REA و دستورالعملهای گردشکار متناظر را اضافه میکند و از پیکربندی موجود نسخهٔ پشتیبان میگیرد. پس از آن ایجنت خود را مجدداً راهاندازی کنید.
راهاندازی از Claude Code، Codex، Cursor، Gemini CLI، Grok Build و [ایجنتهای دیگر](docs/installation.md#supported-agents) پشتیبانی میکند. برای پیکربندی ارائهدهنده و ثبت دستی MCP، [نصب و راهاندازی](docs/installation.md) را ببینید.
### از ایجنت خود بپرسید
```text
بررسی کن جستوجو در برنامهٔ Notes چگونه کار میکند، شواهدش را نشان بده و قابلیتی مشابه برای پروژهٔ من بساز.
```
بهجای Notes، نام برنامهٔ هدف و قابلیتی را قرار دهید که میخواهید درک کنید.
### استفاده از ترمینال
برای بررسی پوشهٔ استخراجشدهٔ یک برنامهٔ JavaScript/Electron یا فایل ASAR:
نتیجه شامل ماژولها، importها، مرزهای Electron و شواهد مربوط به آنهاست. مسیر را با مسیر برنامهٔ هدف جایگزین کنید؛ مثلاً در ویندوز `"D:/apps/example"`.
برای نصب دستور `rea` جهت استفادهٔ مداوم:
```bash
npm install --global rea-agents
rea --help
```
برای تحلیل بومی ابتدا یک ارائهدهنده پیکربندی کنید. برای دستورات بومی، انتخاب ارائهدهنده، snapshotها و اسکریپتنویسی، [راهنمای CLI و شواهد](docs/cli.md) را ببینید.
### بهروزرسانی REA
REA بهسرعت تغییر میکند و نسخههای جدید معمولاً شامل رفع اشکالهای متعددی هستند. نصب خود را بهروز نگه دارید.
برای CLI نصبشده از طریق npm:
```bash
rea update
```
برای بهروزرسانی ثبت ایجنتها و skill، دستور setup نمایشدادهشده توسط بهروزرسانی را اجرا کنید.
اگر از `npx` استفاده میکنید، راهاندازی ایجنت را با دستور زیر بهروز کنید:
```bash
npx rea-agents@latest setup
```
تغییرات راهاندازی را بررسی کنید و ایجنت را دوباره اجرا کنید. برای اجرای یکبارهٔ دستورات CLI، از `npx rea-agents@latest` و سپس دستور موردنظر استفاده کنید.
## REA چگونه کار میکند؟
ایجنت شما از طریق MCP، REA را فراخوانی میکند تا هدف را بررسی و کد مرتبط را ردیابی کند. REA یافتهها را همراه با شواهد برمیگرداند. ایجنت از این نتایج برای طرح پرسشهای تکمیلی، توضیح رفتار یا نوشتن و آزمایش یک پیادهسازی استفاده میکند. دستورات CLI نیز از همین گردشکارها بهره میبرند.
[نمایش تصویر در اندازهٔ کامل](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## چه چیزهایی را میتوان تحلیل کرد؟
REA به Node.js 22.x (>=22.19)، 24.x (>=24.11) یا 26+، بههمراه npm نیاز دارد. ابزارهای اضافی و پشتیبانی سیستم میزبان به نوع هدف بستگی دارند:
| باینریهای بومی | شبهکد، اسمبلی، رشتهها، نمادها، فراخوانیها و ارجاعات | Hopper، Ghidra یا IDA؛ [تحلیل بومی](https://rea.tools/guides/native/) |
| ساختار ELF آفلاین | بخشها، سگمنتها، نمادها و relocationهای اصلی و گزینههای احتمالی کاهش آسیبپذیری ایستا | pwntools تأمینشده توسط فراخواننده روی Linux x64؛ [تشخیص باینری](docs/binary-diagnostics.md) |
| کرشهای ثبتشدهٔ لینوکس | یادداشتهای خام، رجیسترها/سیگنالهای تمام threadهای ثبتشده و گزینههای احتمالی نگاشت | pwntools تأمینشده توسط فراخواننده؛ GDB/pwndbg اختیاری؛ [کرشهای ثبتشده](docs/recorded-crashes.md) |
| JavaScript / Electron | ماژولها، importها، source mapها، مسیرها، IPC و ارتباط افزونههای بومی | Node.js و npm؛ [تحلیل برنامه](https://rea.tools/guides/javascript/) |
| وبسایتها | ساختار صفحه، اسکریپتها، مشاهدات شبکه و اسکرینشاتهای درخواستی | مرورگر مبتنی بر Chrome؛ [تحلیل مرورگر](https://rea.tools/guides/browser/) |
| دادههای ضبطشدهٔ شبکه | درخواستها، پاسخها، payloadهای آشکارشده و مکان آنها در منبع | HAR؛ ابزار mitmdump در لینوکس برای ضبطهای بومی mitmproxy؛ [راهنمای ضبط شبکه](docs/web-network-captures.md) |
| اسمبلیهای .NET | فراداده، دستورالعملهای CIL، وابستگیهای بومی اعلامشده و مقایسهٔ buildها | بررسی ایستا؛ [راهنمای کد مدیریتشده](docs/managed-code-analysis.md) |
| فایلهای APK اندروید | تعاریف Manifest، کلاسها، متدهای دیکامپایلشده و ارجاعات | JADX بدون رابط گرافیکی و JDK کامل در Linux/macOS؛ [راهنمای اندروید](docs/android-analysis.md) |
| Firmware | ناحیهها، نتایج استخراج و تحویل به ابزارهای تحلیل بومی | Binwalk / Unblob در لینوکس؛ [راهنمای Firmware](docs/firmware-analysis.md) |
| بستهها و منابع | فهرست فایلها، digestها، فایلهای plist، ساختار bundle اپل و منابع استخراجشده | [راهنمای آرتیفکت و JavaScript](docs/javascript-artifact-reconstruction.md)، [برنامههای اپل](docs/apple-application-analysis.md) |
| رفتار فرایند | خروجی ترمینال، تعاملات، وضعیت خروج، مشاهدات سیستم فایل و مقایسهٔ اجراها | Linux/macOS با PTY بومی؛ [ضبط فرایند](docs/process-capture.md) |
بررسی ایستای JavaScript و .NET فایلهای ارائهشده را بدون اجرای برنامه میخواند. ضبط زمان اجرا، هدف انتخابشده را با مجوزهای کاربری شما اجرا میکند یا با آن تعامل دارد؛ آثار این عملیات در راهنمای مربوط به هر نوع ضبط توضیح داده شدهاند.
<a id="choosing-a-deep-analysis-provider"></a>
فرمتهای بومی و پشتیبانی سیستم میزبان بر اساس ارائهدهنده متفاوتاند. [راهاندازی Hopper و Ghidra](docs/installation.md#hopper)، [راهنمای IDA](docs/ida-provider.md) و [پشتیبانی آزمایشی Ghidra در ویندوز](docs/windows-ghidra-p0.md) را ببینید. Ghidra همچنین از [تحلیل DOS شانزدهبیتی](docs/ghidra-dos.md) پشتیبانی میکند. برای انتخاب ارائهدهنده، به [راهنمای CLI](docs/cli.md#choose-a-provider) مراجعه کنید. برای قابلیتهایی که پس از آخرین انتشار npm اضافه شدهاند، [وضعیت انتشار](docs/installation.md#released-package-and-main) را بررسی کنید.
## نمونههای عملی
[](https://rea.tools/showcase/)
### DX-Ball: بازسازی محاسبهٔ موقعیت استریوی صدا
یک فراخوانی صوتی را تا تابع کمکی تبدیل موقعیت به pan دنبال کنید، دستورالعملها را بررسی کنید و شبهکد ناقص را به C تبدیل کنید. بازسازی حاصل، هر ۳٬۲۰۵ مورد آزمایش x86 اصلی را با موفقیت پشت سر میگذارد و هر ۶۳ بایت تابع کامپایلشده را دقیقاً بازتولید میکند.
دستورالعملهای ۱۶بیتی بازی اصلی PC-98 را بررسی کنید، محاسبات زاویهٔ ثابت و هدفگیریشده را بازیابی کنید و کد C++ بازسازیشده را با خروجی کامپایلر تاریخی مقایسه کنید.
اگر از REA برای بررسی موضوع جالبی استفاده کردهاید، خوشحال میشویم آن را به اشتراک بگذارید. یک [issue](https://github.com/morluto/rea/issues) یا [pull request](https://github.com/morluto/rea/pulls) ثبت کنید و هدف، پرسش خود، نقش REA و یافتههایتان را توضیح دهید.
## پرسشهای متداول
<details><summary><strong>کدام ایجنتها میتوانند از REA استفاده کنند؟</strong></summary>
هر ایجنتی که از سرورهای MCP محلی پشتیبانی کند. فرایند setup، [ایجنتهای پشتیبانیشده](docs/installation.md#supported-agents) را پیکربندی میکند؛ سایر کلاینتها میتوانند از [ثبت دستی MCP](docs/installation.md#mcp-registry) استفاده کنند.
</details>
<details><summary><strong>آیا به Hopper، Ghidra یا IDA نیاز دارم؟</strong></summary>
تحلیل عمیق بومی به یکی از آنها نیاز دارد. بررسی ایستای JavaScript و .NET بدون موتور تحلیل بومی کار میکند. setup میتواند با تأیید شما Hopper را نصب کند؛ Ghidra و IDA از نصبهای موجود شما استفاده میکنند. [راهاندازی ارائهدهنده](docs/installation.md#hopper) را ببینید.
</details>
<details><summary><strong>آیا باید ابتدا Hopper را اجرا کنم؟</strong></summary>
REA زمانی که عملیاتی به Hopper نیاز داشته باشد آن را اجرا میکند. در macOS، ممکن است هنگام نخستین اجرا پنجرهای برای انتخاب حالت آزمایشی یا فعالسازی مجوز نمایش داده شود. [راهاندازی Hopper و رفع اشکال](docs/installation.md#launcher-paths-and-troubleshooting) را ببینید.
</details>
<details><summary><strong>نصب skill از skills.sh چه کاری انجام میدهد؟</strong></summary>
این skill دستورالعملهای بررسی را برای ایجنت فراهم میکند. برای ثبت سرور MCP مربوط به REA و نصب دستورالعملهای متناظر، `npx rea-agents setup` را اجرا کنید و سپس ایجنت را مجدداً راهاندازی کنید. [نصب مستقل skill](docs/installation.md#skill-only-installation) را ببینید.
</details>
<details><summary><strong>REA چه نوع کدی برمیگرداند؟</strong></summary>
تحلیل بومی، شبهکد و اسمبلی برمیگرداند. تحلیل JavaScript/Electron ماژولها و روابط میان آنها را بازیابی میکند. ایجنت شما از این یافتهها برای نوشتن و آزمایش یک پیادهسازی استفاده میکند؛ [نمونههای عملی](#نمونههای-عملی) مثالهای گامبهگام ارائه میدهند.
</details>
<details><summary><strong>آیا REA برنامهٔ من را آپلود میکند؟</strong></summary>
REA اهداف را بهصورت محلی تحلیل میکند. ایجنت شما نتایج ابزارها را دریافت میکند و ارائهدهندهٔ مدل آن سیاست مستقل خود را دربارهٔ دادهها دارد.
</details>
<details><summary><strong>اگر با خطا مواجه شدم چه کنم؟</strong></summary>
ابتدا بهروزرسانی کنید؛ ممکن است مشکل در نسخهای جدید رفع شده باشد.
برای CLI نصبشده با npm:
```bash
rea update
```
برای راهاندازی ایجنت با `npx`:
```bash
npx rea-agents@latest setup
```
اگر از ایجنت استفاده میکنید، [بهروزرسانی راهاندازی](#بهروزرسانی-rea) را تکمیل و ایجنت را مجدداً اجرا کنید. همان کار را دوباره امتحان کنید. اگر مشکل ادامه داشت، یک [issue ثبت کنید](https://github.com/morluto/rea/issues) و نسخهٔ REA، نوع هدف، مراحل بازتولید و خروجی خطا را ذکر کنید.
</details>
## مستندات
از [راهنماهای عملی وبسایت](https://rea.tools/guides/) شروع کنید. برای گزینههای دقیق، پیشنیازها و قراردادهای خروجی:
- [نصب و راهاندازی](docs/installation.md): ثبت ایجنت، پیکربندی ارائهدهنده، بهروزرسانی و حذف نصب.
- [آمادگی و رفع اشکال](docs/installation.md#check-readiness-for-your-task): عیبیابی یک ایجنت یا موتور تحلیل.
- [CLI و شواهد](docs/cli.md): دستورات، انتخاب ارائهدهنده، snapshotها، ورود/خروج داده و وضعیتهای خروج.
- [قراردادهای MCP](docs/mcp-contracts.md) و [پرامپتهای ایجنت](docs/mcp-prompts.md): نتایج ابزارها، نشستها و بررسیهای هدایتشده.
- [فهرست ابزارها](docs/mcp-contracts.md#generated-catalog): فهرست تولیدشده هنگام build از ابزارها، ارائهدهندگان و دستورات CLI.
- [نقشهٔ راه](docs/roadmap.md): برنامههای آینده و پیگیری قابلیتها.
آسیبپذیریها را از طریق [SECURITY.md](SECURITY.md) گزارش کنید.
## تاریخچهٔ ستارهها
🎉 **۴۰٬۰۰۰ ستارهٔ GitHub — سپاسگزاریم!**
از همهٔ کسانی که از REA استفاده میکنند، خطاها را گزارش میدهند، قابلیتهای جدید پیشنهاد میکنند، buildها را آزمایش میکنند و در بهبود پروژه مشارکت دارند سپاسگزاریم.
REA ابزارهایی برای پژوهش، تحلیل و بازسازی قانونی در حوزهٔ مهندسی معکوس فراهم میکند. مسئولیت دریافت مجوزهای لازم و رعایت قوانین مربوط بر عهدهٔ شماست. این پروژه استفادهٔ غیرقانونی یا بدون مجوز را تأیید نمیکند.
## مشارکت
از کمک شما به REA استقبال میکنیم! برای گزارش خطا یا پیشنهاد قابلیت، یک [issue باز کنید](https://github.com/morluto/rea/issues) یا برای بهبود کد و مستندات [pull request بفرستید](https://github.com/morluto/rea/pulls).
برای راهاندازی محیط توسعه و بررسیها، [CONTRIBUTING.md](CONTRIBUTING.md)، برای مراحل اعتبارسنجی [آزمایشها](docs/testing.md) و برای ساختار پروژه [نقشهٔ معماری](docs/architecture.mermaid) را ببینید.
<strong>Rejoignez la communauté de rétro-ingénierie</strong>
</a><br />
<sub>Discord · Questions et réponses · Partage de projets</sub>
</td>
</tr>
</table>
<br />
</div>
---
Vous avez repéré dans une application une fonctionnalité que vous aimeriez avoir dans votre propre produit ? Demandez à votre agent de l'étudier avec REA. Il peut inspecter l'application sans son code source, expliquer le fonctionnement de la fonctionnalité, présenter les preuves et en construire une version pour votre projet.
REA connecte votre agent à des outils d'inspection de binaires natifs, d'applications JavaScript et Electron, d'assemblys .NET et de sites web. Les mêmes outils sont aussi disponibles depuis votre terminal. L'analyse s'exécute localement, et chaque conclusion s'accompagne des preuves et des limites sur lesquelles elle repose.
Setup enregistre REA auprès de votre agent et installe les instructions de workflow correspondantes. L'analyse native peut utiliser une installation existante de Hopper ou de Ghidra ; Setup peut aussi installer Hopper après votre accord. L'analyse statique JavaScript ne nécessite aucun de ces moteurs.
> **[Visitez le site web de REA](https://rea.tools/)** pour les instructions d'installation, des guides illustrés et des études de cas réelles.
## Démarrage rapide
### Configurer votre agent
Une fois Node.js et npm installés, exécutez :
```bash
npx rea-agents setup
```
Choisissez vos agents, vérifiez les modifications proposées et approuvez-les. Setup ajoute le serveur MCP de REA et les instructions de workflow correspondantes, et sauvegarde la configuration existante. Redémarrez ensuite votre agent.
Setup prend en charge Claude Code, Codex, Cursor, Gemini CLI, Grok Build et [d'autres agents](docs/installation.md#supported-agents). Consultez [Installation et configuration](docs/installation.md) pour la configuration des fournisseurs et l'enregistrement MCP manuel.
### Interroger votre agent
```text
Comprends comment fonctionne la recherche dans l'app Notes, montre-moi les preuves
et construis une fonctionnalité similaire pour mon projet.
```
Remplacez Notes par votre application cible et la fonctionnalité que vous voulez comprendre.
### Utiliser le terminal
Inspectez le répertoire extrait ou l'archive ASAR d'une application JavaScript/Electron :
Le résultat comprend les modules, les imports, les frontières Electron et les preuves associées. Remplacez le chemin par votre cible, par exemple `"D:/apps/example"` sous Windows.
Pour installer la commande `rea` pour un usage régulier :
```bash
npm install --global rea-agents
rea --help
```
Pour l'analyse native, configurez d'abord un fournisseur. Consultez le [guide CLI et Evidence](docs/cli.md) pour les commandes natives, le choix du fournisseur, les snapshots et l'utilisation dans des scripts.
### Mettre à jour REA
REA évolue rapidement, et les nouvelles versions apportent fréquemment des corrections de bugs. Maintenez votre installation à jour.
Pour une CLI installée avec npm :
```bash
rea update
```
Pour actualiser les enregistrements de vos agents et le skill, exécutez la commande setup affichée par la mise à jour.
Si vous utilisez `npx`, mettez à jour la configuration de votre agent avec :
```bash
npx rea-agents@latest setup
```
Vérifiez les modifications proposées par Setup et redémarrez votre agent. Pour des commandes CLI ponctuelles, utilisez `npx rea-agents@latest` suivi de la commande.
## Comment fonctionne REA
Votre agent appelle REA via MCP pour inspecter la cible et suivre le code pertinent. REA renvoie ses constatations avec les preuves correspondantes. L'agent s'en sert pour poser des questions complémentaires, expliquer le comportement, ou écrire et tester une implémentation. Les commandes CLI utilisent les mêmes workflows.
[Ouvrir la figure en taille réelle](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## Ce que vous pouvez analyser
REA nécessite Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, ainsi que npm. Les outils supplémentaires et les hôtes pris en charge dépendent de la cible :
| Cible | Ce que REA renvoie | Prérequis et guide |
| Binaires natifs | Pseudo-code, assembleur, chaînes, symboles, appels et références | Hopper, Ghidra ou IDA ; [analyse native](https://rea.tools/guides/native/) |
| Structure ELF hors ligne | Sections, segments, symboles et relocations d'origine, et protections statiques candidates | pwntools fourni par l'utilisateur sous Linux x64 ; [diagnostics binaires](docs/binary-diagnostics.md) |
| Bytecode EVM | Sélecteurs de dispatch, offsets en octets, arguments inférés et mutabilité | Fichier local brut ou hexadécimal ; [guide EVM hors ligne](docs/evm-bytecode.md) |
| Crashs Linux enregistrés | Notes brutes, registres et signaux de chaque thread enregistré, et correspondances de mappings facultatives | pwntools fourni par l'utilisateur ; GDB/pwndbg en option ; [crashs enregistrés](docs/recorded-crashes.md) |
| JavaScript / Electron | Modules, imports, source maps, routes, IPC et relations avec les modules natifs | Node.js et npm ; [analyse d'applications](https://rea.tools/guides/javascript/) |
| Sites web | Structure des pages, scripts, observations réseau et captures d'écran demandées | Un navigateur de la famille Chrome ; [analyse du navigateur](https://rea.tools/guides/browser/) |
| Captures réseau enregistrées | Requêtes, réponses, payloads exposés et emplacements dans le code source | HAR ; mitmdump sous Linux pour les captures mitmproxy natives ; [guide des captures](docs/web-network-captures.md) |
| Assemblys .NET | Métadonnées, instructions CIL, dépendances natives déclarées et comparaisons de builds | Inspection statique ; [guide du code managé](docs/managed-code-analysis.md) |
| APK Android | Déclarations du manifeste, classes, méthodes décompilées et références | JADX headless et un JDK complet sous Linux/macOS ; [guide Android](docs/android-analysis.md) |
| Firmware | Régions, résultats d'extraction et passage de relais vers l'analyse native | Binwalk / Unblob sous Linux ; [guide firmware](docs/firmware-analysis.md) |
| Paquets et ressources | Inventaires de fichiers, empreintes, plists, anatomie des bundles Apple et ressources extraites | [Guide artefacts et JavaScript](docs/javascript-artifact-reconstruction.md), [applications Apple](docs/apple-application-analysis.md) |
| Comportement des processus | Sortie du terminal, interactions, code de sortie, observations du système de fichiers et comparaisons | Linux/macOS avec un PTY natif ; [capture de processus](docs/process-capture.md) |
L'inspection statique JavaScript et .NET lit les fichiers fournis sans exécuter l'application. La capture à l'exécution lance la cible choisie ou interagit avec elle avec vos permissions utilisateur ; chaque guide d'exécution décrit ses effets.
<a id="choosing-a-deep-analysis-provider"></a>
Les formats natifs et les hôtes pris en charge varient selon le fournisseur. Consultez [la configuration de Hopper et Ghidra](docs/installation.md#hopper), le [guide IDA](docs/ida-provider.md) et [la prise en charge expérimentale de Ghidra sous Windows](docs/windows-ghidra-p0.md). Ghidra prend aussi en charge [l'analyse DOS 16 bits](docs/ghidra-dos.md). Pour les gros binaires, augmentez son délai de démarrage avec `REA_GHIDRA_STARTUP_TIMEOUT_MS`. Pour le choix du fournisseur, consultez le [guide CLI](docs/cli.md#choose-a-provider). Vérifiez la [disponibilité dans les versions publiées](docs/installation.md#released-package-and-main) pour les fonctionnalités ajoutées depuis la dernière version npm.
## Études de cas
[](https://rea.tools/showcase/)
### DX-Ball : reconstruire un calcul de panoramique sonore
Suivez un appel sonore jusqu'à la fonction qui convertit une position en panoramique, inspectez ses instructions et transformez un pseudo-code incomplet en C. La reconstruction réussit 3 205 cas issus du x86 d'origine et reproduit à l'identique les 63 octets de la fonction compilée.
[Lire l'étude de cas](https://rea.tools/showcase/dx-ball/) · [Dépôt de la reconstruction](https://github.com/N0zoM1z0/dx-ball)
### Notion : suivre le pont du presse-papiers d'Electron
Trouvez l'API de presse-papiers du renderer, suivez-la à travers le preload et l'IPC jusqu'au processus principal, puis inspectez le format de presse-papiers enrichi.
[Lire l'étude de cas](https://rea.tools/showcase/notion/)
### TH04 : retrouver un calcul d'anneau de projectiles sous DOS
Inspectez les instructions 16 bits du jeu PC-98 d'origine, retrouvez les calculs d'angles fixes et visés, et comparez le C++ reconstruit avec la sortie du compilateur d'époque.
[Lire l'étude de cas](https://rea.tools/showcase/th04/) · [Dépôt de la reconstruction](https://github.com/N0zoM1z0/th04)
Si vous avez utilisé REA sur un projet intéressant, nous serions ravis de le découvrir. Partagez votre cas dans une [issue](https://github.com/morluto/rea/issues) ou une [pull request](https://github.com/morluto/rea/pulls), en précisant la cible, votre question, la manière dont REA vous a aidé et ce que vous avez découvert.
## Questions fréquentes
<details>
<summary><strong>Quels agents peuvent utiliser REA ?</strong></summary>
Tout agent compatible avec les serveurs MCP locaux. Setup configure les [agents pris en charge](docs/installation.md#supported-agents) ; les autres clients peuvent utiliser [l'enregistrement MCP manuel](docs/installation.md#mcp-registry).
</details>
<details>
<summary><strong>Ai-je besoin de Hopper, Ghidra ou IDA ?</strong></summary>
L'analyse native approfondie utilise l'un d'eux. L'inspection statique JavaScript et .NET fonctionne sans moteur d'analyse native. Setup peut installer Hopper après votre accord ; Ghidra et IDA utilisent vos installations existantes. Consultez [la configuration des fournisseurs](docs/installation.md#hopper).
</details>
<details>
<summary><strong>Dois-je lancer Hopper au préalable ?</strong></summary>
REA lance Hopper lorsqu'une opération en a besoin. Sous macOS, une boîte de dialogue de premier lancement peut vous demander de choisir le mode démo ou d'activer votre licence. Consultez [Démarrage et dépannage de Hopper](docs/installation.md#launcher-paths-and-troubleshooting).
</details>
<details>
<summary><strong>Que fait l'installation du skill depuis skills.sh ?</strong></summary>
Le skill fournit des instructions d'investigation à votre agent. Utilisez `npx rea-agents setup` pour enregistrer le serveur MCP de REA et installer les instructions correspondantes, puis redémarrez votre agent. Consultez [l'installation du skill seul](docs/installation.md#skill-only-installation).
</details>
<details>
<summary><strong>Quel code REA renvoie-t-il ?</strong></summary>
L'analyse native renvoie du pseudo-code et de l'assembleur. L'analyse JavaScript/Electron récupère les modules et leurs relations. Votre agent s'appuie sur ces résultats pour écrire et tester une implémentation ; les [études de cas](#études-de-cas) en donnent des exemples concrets.
</details>
<details>
<summary><strong>REA envoie-t-il mon application en ligne ?</strong></summary>
REA analyse les cibles localement. Votre agent reçoit les résultats des outils, et son fournisseur de modèle applique sa propre politique de données.
</details>
<details>
<summary><strong>Que faire si je rencontre un bug ?</strong></summary>
Commencez par mettre à jour ; une version récente l'a peut-être déjà corrigé.
Pour une CLI installée avec npm :
```bash
rea update
```
Pour une configuration d'agent via `npx` :
```bash
npx rea-agents@latest setup
```
Si vous utilisez un agent, terminez l'[actualisation de la configuration](#mettre-à-jour-rea) et redémarrez-le. Relancez la même tâche. Si le problème persiste, [ouvrez une issue](https://github.com/morluto/rea/issues) en indiquant votre version de REA, le type de cible, les étapes pour reproduire le problème et la sortie d'erreur.
</details>
## Documentation
Commencez par les [guides pas à pas](https://rea.tools/guides/) du site web. Pour les options exactes, les prérequis et les contrats de résultats :
- [Installation et configuration](docs/installation.md) : enregistrement des agents, configuration des fournisseurs, mises à jour et désinstallation.
- [Vérification et dépannage](docs/installation.md#check-readiness-for-your-task) : diagnostiquer un agent ou un moteur d'analyse précis.
- [CLI et Evidence](docs/cli.md) : commandes, choix du fournisseur, snapshots, import/export et codes de sortie.
- [Contrats MCP](docs/mcp-contracts.md) et [prompts pour agents](docs/mcp-prompts.md) : résultats des outils, sessions et investigations guidées.
- [Catalogue des outils](docs/mcp-contracts.md#generated-catalog) : inventaire des outils, fournisseurs et commandes CLI, généré lors du build.
- [Feuille de route](docs/roadmap.md) : travaux prévus et suivi des capacités.
Signalez les vulnérabilités via [SECURITY.md](SECURITY.md).
## Historique des étoiles
🎉 **40 000 étoiles GitHub — merci !**
Merci à toutes les personnes qui utilisent REA, signalent des bugs, proposent des fonctionnalités, testent les builds et contribuent des correctifs.
<img alt="Historique des étoiles GitHub de REA" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
</picture>
</a>
## Avertissement
REA fournit des outils destinés à la recherche, à l'analyse et à la reconstruction légales en rétro-ingénierie. Il vous appartient d'obtenir toute autorisation nécessaire et de respecter les lois applicables. Le projet n'encourage aucune utilisation illégale ou non autorisée.
## Contribuer
Votre aide sur REA est la bienvenue ! [Ouvrez une issue](https://github.com/morluto/rea/issues) pour signaler un bug ou proposer une fonctionnalité, ou [envoyez une pull request](https://github.com/morluto/rea/pulls) pour améliorer le code ou la documentation.
Consultez [CONTRIBUTING.md](CONTRIBUTING.md) pour l'environnement de développement et les vérifications, la page [tests](docs/testing.md) pour les filières de vérification, et la [carte de l'architecture](docs/architecture.mermaid) pour la structure du projet.
REA は、合法的なリバースエンジニアリングの研究、分析、再構築のためのツールを提供します。必要な許可を得て、適用される法律に従う責任は利用者にあります。このプロジェクトは違法または無許可の利用を支持しません。
## 貢献する
REA への貢献を歓迎します！[issue を作成](https://github.com/morluto/rea/issues)してバグや機能の提案を報告したり、[pull request を送信](https://github.com/morluto/rea/pulls)してコードやドキュメントを改善したりできます。
앱에서 내 제품에도 넣고 싶은 기능을 발견했나요? 에이전트에게 REA로 조사해 달라고 요청하세요. 소스 코드가 없어도 앱을 검사하고, 기능의 작동 원리를 설명하고, 근거를 보여 주고, 프로젝트에 맞는 기능을 구현할 수 있습니다.
REA는 에이전트를 분석 도구에 연결해 네이티브 바이너리, JavaScript와 Electron 앱, .NET 어셈블리, 웹사이트를 검사할 수 있게 합니다. 터미널에서도 같은 도구를 사용할 수 있습니다. 분석은 로컬에서 실행되며, 결과에는 각 결론의 근거와 한계가 포함됩니다.
설정 과정은 에이전트에 REA를 등록하고 해당 버전에 맞는 워크플로 지침을 설치합니다. 네이티브 분석에는 기존 Hopper 또는 Ghidra 설치를 사용할 수 있습니다. 승인하면 설정 과정에서 Hopper를 설치할 수도 있습니다. 정적 JavaScript 분석에는 두 엔진 모두 필요하지 않습니다.
> **[REA 웹사이트](https://rea.tools/)**에서 설정 방법, 그림으로 설명한 가이드, 실제 사례를 확인하세요.
## 빠른 시작
### 에이전트 설정
Node.js와 npm이 설치된 환경에서 다음 명령을 실행하세요.
```bash
npx rea-agents setup
```
에이전트를 선택하고, 예정된 변경 사항을 검토한 뒤 승인하세요. 설정 과정은 기존 설정을 백업하고 REA의 MCP 서버와 버전에 맞는 워크플로 지침을 추가합니다. 완료 후 에이전트를 다시 시작하세요.
설정은 Claude Code, Codex, Cursor, Gemini CLI, Grok Build 및 [다른 에이전트](docs/installation.md#supported-agents)를 지원합니다. 제공자 설정과 수동 MCP 등록은 [설치 및 설정](docs/installation.md)을 참고하세요.
### 에이전트에게 요청
```text
Notes 앱의 검색 기능이 어떻게 작동하는지 조사하고, 근거를 보여 준 다음, 내 프로젝트에 비슷한 기능을 구현해 줘.
결과에는 모듈, 임포트, Electron 경계와 관련 근거가 포함됩니다. 경로를 분석할 대상으로 바꾸세요. Windows에서는 `"D:/apps/example"` 같은 경로를 사용할 수 있습니다.
자주 사용할 경우 `rea` 명령을 설치하세요.
```bash
npm install --global rea-agents
rea --help
```
네이티브 분석에는 먼저 제공자를 설정해야 합니다. 네이티브 명령, 제공자 선택, 스냅샷, 스크립트 사용은 [CLI 및 Evidence 가이드](docs/cli.md)를 참고하세요.
### REA 업데이트
REA는 빠르게 바뀌며 새 릴리스에는 버그 수정이 자주 포함됩니다. 설치된 버전을 최신으로 유지하세요.
npm으로 설치한 CLI에서는 다음 명령을 사용합니다.
```bash
rea update
```
에이전트 등록과 스킬을 갱신하려면 업데이트 과정에서 출력된 설정 명령을 실행하세요.
`npx`를 사용한다면 다음 명령으로 에이전트 설정을 갱신하세요.
```bash
npx rea-agents@latest setup
```
설정 변경 사항을 검토하고 에이전트를 다시 시작하세요. 일회성 CLI 작업에는 `npx rea-agents@latest` 뒤에 필요한 명령을 붙여 실행하세요.
## REA의 작동 방식
에이전트는 MCP를 통해 REA를 호출하여 대상을 검사하고 관련 코드를 추적합니다. REA는 조사 결과와 근거를 반환합니다. 에이전트는 이를 바탕으로 추가 질문을 하고, 동작을 설명하거나, 구현을 작성하고 테스트합니다. CLI 명령도 같은 워크플로를 사용합니다.
[원본 크기의 그림 열기](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## 분석할 수 있는 대상
REA에는 Node.js 22.x(>=22.19), 24.x(>=24.11) 또는 26+와 npm이 필요합니다. 추가 도구와 호스트 지원은 대상에 따라 다릅니다.
| 펌웨어 | 영역, 추출 결과, 네이티브 분석으로 전달할 정보 | Linux의 Binwalk / Unblob; [펌웨어 가이드](docs/firmware-analysis.md) |
| 패키지 및 리소스 | 파일 목록, 다이제스트, plist, Apple 번들 구조, 추출한 리소스 | [아티팩트 및 JavaScript 가이드](docs/javascript-artifact-reconstruction.md), [Apple 애플리케이션](docs/apple-application-analysis.md) |
| 프로세스 동작 | 터미널 출력, 상호작용, 종료 및 파일 시스템 관찰 결과, 실행 비교 | 네이티브 PTY를 지원하는 Linux/macOS; [프로세스 캡처](docs/process-capture.md) |
정적 JavaScript 및 .NET 검사는 제공된 파일을 읽으며 애플리케이션을 실행하지 않습니다. 런타임 캡처는 사용자의 권한으로 선택한 대상을 실행하거나 대상과 상호작용합니다. 각 런타임 가이드에서 그 영향을 설명합니다.
<a id="choosing-a-deep-analysis-provider"></a>
지원하는 네이티브 형식과 호스트는 제공자마다 다릅니다. [Hopper 및 Ghidra 설정](docs/installation.md#hopper), [IDA 가이드](docs/ida-provider.md), [실험적 Windows Ghidra 지원](docs/windows-ghidra-p0.md)을 참고하세요. Ghidra는 [16비트 DOS 분석](docs/ghidra-dos.md)도 지원합니다. 제공자 선택은 [CLI 가이드](docs/cli.md#choose-a-provider)를 참고하세요. 최신 npm 릴리스 이후 추가된 기능은 [릴리스에서의 사용 가능 여부](docs/installation.md#released-package-and-main)를 확인하세요.
## 사례
[](https://rea.tools/showcase/)
### DX-Ball: 사운드 패닝 계산 재구현
사운드 호출에서 위치를 패닝 값으로 변환하는 보조 함수까지 추적하고, 명령을 검사하여 불완전한 의사 코드를 C로 옮깁니다. 재구현한 코드는 원본 x86에 대한 3,205개 테스트 케이스를 통과했으며, 컴파일된 함수의 63바이트 전체를 재현합니다.
[사례 읽기](https://rea.tools/showcase/dx-ball/) ·
[재구현 저장소](https://github.com/N0zoM1z0/dx-ball)
### Notion: Electron 클립보드 브리지 추적
렌더러의 클립보드 API를 찾고, preload와 IPC를 거쳐 메인 프로세스까지 추적한 뒤, 서식 있는 클립보드 형식을 검사합니다.
[사례 읽기](https://rea.tools/showcase/notion/)
### TH04: DOS 원형 탄막 계산 복원
원본 PC-98 게임의 16비트 명령을 검사하고 고정 각도와 조준 각도의 계산을 복원합니다. 재구현한 C++를 당시 컴파일러의 출력과 비교합니다.
[사례 읽기](https://rea.tools/showcase/th04/) ·
[재구현 저장소](https://github.com/N0zoM1z0/th04)
REA로 흥미로운 대상을 분석했다면 알려 주세요. [issue](https://github.com/morluto/rea/issues) 또는 [pull request](https://github.com/morluto/rea/pulls)에 대상, 조사하려던 질문, REA가 어떻게 도움이 되었는지, 무엇을 알아냈는지를 담아 공유하세요.
## 자주 묻는 질문
<details>
<summary><strong>어떤 에이전트에서 REA를 사용할 수 있나요?</strong></summary>
로컬 MCP 서버를 지원하는 에이전트라면 사용할 수 있습니다. 설정 과정은 [지원하는 에이전트](docs/installation.md#supported-agents)를 구성합니다. 다른 클라이언트는 [수동 MCP 등록](docs/installation.md#mcp-registry)을 이용할 수 있습니다.
</details>
<details>
<summary><strong>Hopper, Ghidra 또는 IDA가 필요한가요?</strong></summary>
심층 네이티브 분석에는 이 중 하나를 사용합니다. 정적 JavaScript 및 .NET 검사에는 네이티브 분석 엔진이 필요하지 않습니다. 설정 과정에서 승인 후 Hopper를 설치할 수 있으며, Ghidra와 IDA는 기존 설치를 사용합니다. [제공자 설정](docs/installation.md#hopper)을 참고하세요.
</details>
<details>
<summary><strong>Hopper를 먼저 실행해야 하나요?</strong></summary>
REA는 작업에 필요할 때 Hopper를 실행합니다. macOS에서는 처음 실행할 때 데모 모드를 선택하거나 라이선스를 활성화하라는 대화 상자가 나타날 수 있습니다. [Hopper 실행 및 문제 해결](docs/installation.md#launcher-paths-and-troubleshooting)을 참고하세요.
</details>
<details>
<summary><strong>skills.sh에서 설치하는 스킬은 어떤 역할을 하나요?</strong></summary>
스킬은 에이전트에게 조사 지침을 제공합니다. `npx rea-agents setup`으로 REA의 MCP 서버를 등록하고 버전에 맞는 지침을 설치한 뒤 에이전트를 다시 시작하세요. [스킬만 설치하기](docs/installation.md#skill-only-installation)를 참고하세요.
</details>
<details>
<summary><strong>REA는 어떤 코드를 반환하나요?</strong></summary>
네이티브 분석은 의사 코드와 어셈블리를 반환합니다. JavaScript/Electron 분석은 모듈과 그 관계를 복원합니다. 에이전트는 이 결과를 사용해 구현을 작성하고 테스트합니다. [사례](#사례)에서 구체적인 예를 볼 수 있습니다.
</details>
<details>
<summary><strong>REA가 내 앱을 업로드하나요?</strong></summary>
REA는 대상을 로컬에서 분석합니다. 에이전트는 도구 결과를 받으며, 에이전트의 모델 제공자에는 별도의 데이터 정책이 있습니다.
</details>
<details>
<summary><strong>버그가 발생하면 어떻게 해야 하나요?</strong></summary>
먼저 업데이트하세요. 최근 릴리스에서 이미 수정되었을 수 있습니다.
npm으로 설치한 CLI에서는 다음 명령을 사용합니다.
```bash
rea update
```
`npx`로 에이전트를 설정했다면 다음 명령을 사용합니다.
```bash
npx rea-agents@latest setup
```
에이전트를 사용 중이라면 [설정 갱신](#rea-업데이트)을 완료하고 다시 시작하세요. 같은 작업을 다시 시도하세요. 문제가 계속되면 REA 버전, 대상 유형, 재현 단계, 오류 출력을 포함해 [issue를 등록](https://github.com/morluto/rea/issues)하세요.
</details>
## 문서
웹사이트의 [실습 가이드](https://rea.tools/guides/)부터 읽어 보세요. 정확한 옵션, 사전 요구 사항, 결과 계약은 다음 문서를 참고하세요.
- [설치 및 설정](docs/installation.md): 에이전트 등록, 제공자 설정, 업데이트, 제거.
- [준비 상태 확인 및 문제 해결](docs/installation.md#check-readiness-for-your-task): 특정 에이전트 또는 분석 엔진 진단.
- [CLI 및 Evidence](docs/cli.md): 명령, 제공자 선택, 스냅샷, 가져오기/내보내기, 종료 상태.
- [MCP 계약](docs/mcp-contracts.md) 및 [에이전트 프롬프트](docs/mcp-prompts.md): 도구 결과, 세션, 안내에 따른 조사.
- [도구 카탈로그](docs/mcp-contracts.md#generated-catalog): 빌드 시 생성되는 도구, 제공자, CLI 명령 목록.
- [로드맵](docs/roadmap.md): 계획된 작업과 기능 진행 상황.
취약점은 [SECURITY.md](SECURITY.md)에 따라 보고하세요.
## 스타 기록
🎉 **GitHub 스타 40,000개, 감사합니다!**
REA를 사용하고, 버그를 보고하고, 기능을 요청하고, 빌드를 테스트하고, 수정에 기여해 주신 모든 분께 감사드립니다.
<img alt="REA GitHub 스타 기록" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
</picture>
</a>
## 면책 조항
REA는 합법적인 리버스 엔지니어링 연구, 분석, 재구성을 위한 도구를 제공합니다. 필요한 권한을 얻고 관련 법률을 준수할 책임은 사용자에게 있습니다. 이 프로젝트는 불법적이거나 허가받지 않은 사용을 지지하지 않습니다.
## 기여
REA에 도움을 보태 주세요! [issue를 등록](https://github.com/morluto/rea/issues)해 버그나 기능을 제안하거나, [pull request를 보내](https://github.com/morluto/rea/pulls) 코드와 문서를 개선할 수 있습니다.
개발 환경과 검사 항목은 [CONTRIBUTING.md](CONTRIBUTING.md), 검증 절차는 [테스트 가이드](docs/testing.md), 프로젝트 구조는 [아키텍처 지도](docs/architecture.mermaid)를 참고하세요.
<img src="docs/assets/rea-hopper-analysis.png" alt="REA uruchamia most analityczny w Hopperze podczas analizy natywnego pliku binarnego" width="1200" />
<strong>Dołącz do społeczności inżynierii wstecznej</strong>
</a><br />
<sub>Discord · Pytania i odpowiedzi · Pokaż swój projekt</sub>
</td>
</tr>
</table>
<br />
</div>
---
Widzisz w aplikacji funkcję, którą chcesz mieć we własnym produkcie? Poproś swojego agenta, aby zbadał ją za pomocą REA. Może przeanalizować aplikację bez jej kodu źródłowego, wyjaśnić działanie funkcji, pokazać dowody i stworzyć jej wersję dla Twojego projektu.
REA łączy Twojego agenta z narzędziami do analizy natywnych plików binarnych, aplikacji JavaScript i Electron, zestawów .NET oraz stron internetowych. Z tych samych narzędzi możesz korzystać w terminalu. Analiza odbywa się lokalnie, a wyniki zawierają dowody i ograniczenia stojące za każdym wnioskiem.
Konfigurator rejestruje REA w Twoim agencie i instaluje pasujące instrukcje pracy. Analiza kodu natywnego może korzystać z istniejącej instalacji Hoppera lub Ghidry; konfigurator może też zainstalować Hoppera po uzyskaniu zgody. Statyczna analiza JavaScript nie wymaga żadnego z tych silników.
> **[Odwiedź stronę REA](https://rea.tools/)**, aby znaleźć instrukcje konfiguracji, ilustrowane przewodniki i rzeczywiste studia przypadków.
## Szybki start
### Skonfiguruj agenta
Po zainstalowaniu Node.js i npm uruchom:
```bash
npx rea-agents setup
```
Wybierz swoich agentów, sprawdź proponowane zmiany i zatwierdź je. Konfigurator dodaje serwer MCP REA i pasujące instrukcje pracy, tworząc kopie zapasowe istniejącej konfiguracji. Następnie uruchom agenta ponownie.
Konfigurator obsługuje Claude Code, Codex, Cursor, Gemini CLI, Grok Build i [innych agentów](docs/installation.md#supported-agents). Konfigurację dostawców analizy i ręczną rejestrację MCP opisuje przewodnik [instalacji i konfiguracji](docs/installation.md).
### Zapytaj agenta
```text
Sprawdź, jak działa wyszukiwanie w aplikacji Notes, pokaż mi dowody i stwórz podobną funkcję dla mojego projektu.
```
Zastąp Notes wybraną aplikacją i wskaż funkcję, którą chcesz zrozumieć.
### Korzystaj z terminala
Przeanalizuj rozpakowany katalog aplikacji JavaScript/Electron lub archiwum ASAR:
Wynik obejmuje moduły, importy, granice komponentów Electron oraz dowody. Zastąp ścieżkę ścieżką do swojego celu, na przykład `"D:/apps/example"` w systemie Windows.
Aby zainstalować polecenie `rea` do regularnego użytku:
```bash
npm install --global rea-agents
rea --help
```
Przed analizą kodu natywnego skonfiguruj dostawcę analizy. Polecenia analizy natywnej, wybór dostawcy, migawki i użycie w skryptach opisuje [przewodnik CLI i Evidence](docs/cli.md).
### Zaktualizuj REA
REA szybko się rozwija, a nowe wydania często zawierają poprawki błędów. Dbaj o aktualność swojej instalacji.
Dla CLI zainstalowanego przez npm:
```bash
rea update
```
Aby odświeżyć rejestracje agentów i umiejętność, uruchom polecenie konfiguracji wyświetlone po aktualizacji.
Jeśli używasz `npx`, zaktualizuj konfigurację agenta poleceniem:
```bash
npx rea-agents@latest setup
```
Sprawdź zmiany konfiguracji i uruchom agenta ponownie. Do jednorazowych poleceń CLI używaj `npx rea-agents@latest`, a następnie nazwy polecenia.
## Jak działa REA
Twój agent wywołuje REA przez MCP, aby analizować cel i śledzić istotny kod. REA zwraca ustalenia wraz z dowodami. Agent wykorzystuje je do zadawania dalszych pytań, wyjaśniania zachowania lub pisania i testowania implementacji. Polecenia CLI korzystają z tych samych procedur.
[Otwórz ilustrację w pełnym rozmiarze](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## Co możesz analizować
REA wymaga Node.js 22.x (>=22.19), 24.x (>=24.11) lub 26+ oraz npm. Dodatkowe narzędzia i obsługiwane platformy zależą od celu analizy:
| Natywne pliki binarne | Pseudokod, kod asemblera, ciągi znaków, symbole, wywołania i odwołania | Hopper, Ghidra lub IDA; [analiza kodu natywnego](https://rea.tools/guides/native/) |
| Układ pliku ELF w trybie offline | Sekcje, segmenty, oryginalne symbole/relokacje i potencjalne mechanizmy zabezpieczeń wskazane przez analizę statyczną | pwntools dostarczone przez użytkownika w systemie Linux x64; [diagnostyka plików binarnych](docs/binary-diagnostics.md) |
| Kod bajtowy EVM | Selektory wywołań, przesunięcia bajtowe, wywnioskowane argumenty i mutowalność | Lokalny plik z surowymi bajtami lub zapisem szesnastkowym; [przewodnik EVM offline](docs/evm-bytecode.md) |
| Zarejestrowane awarie systemu Linux | Surowe rekordy note, rejestry/sygnały każdego zarejestrowanego wątku i opcjonalni kandydaci na mapowania | pwntools dostarczone przez użytkownika; opcjonalnie GDB/pwndbg; [zarejestrowane awarie](docs/recorded-crashes.md) |
| JavaScript / Electron | Moduły, importy, mapy źródeł, trasy, IPC i powiązania z natywnymi dodatkami | Node.js i npm; [analiza aplikacji](https://rea.tools/guides/javascript/) |
| Strony internetowe | Struktura strony, skrypty, obserwacje sieciowe i zamówione zrzuty ekranu | Przeglądarka z rodziny Chrome; [analiza w przeglądarce](https://rea.tools/guides/browser/) |
| Zapisane przechwycenia ruchu sieciowego | Żądania, odpowiedzi, dostępne dane przesyłane i lokalizacje źródłowe | HAR; mitmdump w systemie Linux dla natywnych przechwyceń mitmproxy; [przewodnik przechwytywania](docs/web-network-captures.md) |
| Zestawy .NET | Metadane, instrukcje CIL, zadeklarowane zależności natywne i porównania kompilacji | Analiza statyczna; [przewodnik kodu zarządzanego](docs/managed-code-analysis.md) |
| Pakiety APK dla Androida | Deklaracje manifestu, klasy, zdekompilowane metody i odwołania | JADX bez interfejsu graficznego i pełny JDK w systemie Linux/macOS; [przewodnik Androida](docs/android-analysis.md) |
| Oprogramowanie układowe | Regiony, wyniki wyodrębniania i przekazanie do analizy kodu natywnego | Binwalk / Unblob w systemie Linux; [przewodnik oprogramowania układowego](docs/firmware-analysis.md) |
| Pakiety i zasoby | Spisy plików, skróty, pliki plist, struktura pakietów Apple i wyodrębnione zasoby | [Przewodnik artefaktów i JavaScript](docs/javascript-artifact-reconstruction.md), [aplikacje Apple](docs/apple-application-analysis.md) |
| Zachowanie procesów | Wyjście terminala, interakcje, obserwacje zakończenia i systemu plików oraz porównania uruchomień | Linux/macOS z natywnym PTY; [przechwytywanie procesów](docs/process-capture.md) |
Statyczna analiza JavaScript i .NET odczytuje dostarczone pliki bez uruchamiania aplikacji. Przechwytywanie w czasie wykonywania uruchamia wybrany cel lub wchodzi z nim w interakcje z uprawnieniami Twojego użytkownika; skutki opisano w odpowiednich przewodnikach.
<a id="choosing-a-deep-analysis-provider"></a>
Obsługiwane formaty natywne i platformy zależą od dostawcy analizy. Zobacz [konfigurację Hoppera i Ghidry](docs/installation.md#hopper), [przewodnik IDA](docs/ida-provider.md) oraz [eksperymentalną obsługę Ghidry w systemie Windows](docs/windows-ghidra-p0.md). Ghidra obsługuje też [analizę 16-bitowego DOS-a](docs/ghidra-dos.md). Wybór dostawcy opisuje [przewodnik CLI](docs/cli.md#choose-a-provider). Sprawdź [dostępność w wydaniach](docs/installation.md#released-package-and-main) dla funkcji dodanych po najnowszym wydaniu npm.
## Przykłady zastosowań
[](https://rea.tools/showcase/)
Prześledź wywołanie dźwięku do funkcji pomocniczej przeliczającej pozycję na panoramę, sprawdź instrukcje i przekształć niepełny pseudokod w C. Odtworzona implementacja przechodzi 3 205 przypadków dla oryginalnego x86 i odtwarza wszystkie 63 bajty skompilowanej funkcji.
[Przeczytaj studium przypadku](https://rea.tools/showcase/dx-ball/) · [Repozytorium odtworzonej implementacji](https://github.com/N0zoM1z0/dx-ball)
### Notion: śledzenie mostu schowka w Electron
Znajdź API schowka w procesie renderującym, prześledź je przez preload i IPC do procesu głównego, a następnie sprawdź format schowka wraz z danymi formatowania.
[Przeczytaj studium przypadku](https://rea.tools/showcase/notion/)
### TH04: odtworzenie obliczania pierścienia pocisków w DOS-ie
Sprawdź 16-bitowe instrukcje oryginalnej gry na PC-98, odtwórz obliczenia kątów stałych i skierowanych na cel oraz porównaj odtworzony C++ z wynikiem historycznego kompilatora.
[Przeczytaj studium przypadku](https://rea.tools/showcase/th04/) · [Repozytorium odtworzonej implementacji](https://github.com/N0zoM1z0/th04)
Jeśli użyłeś REA do czegoś ciekawego, chętnie to zobaczymy. Opisz swój przypadek w [zgłoszeniu](https://github.com/morluto/rea/issues) lub [pull requeście](https://github.com/morluto/rea/pulls), podając cel analizy, pytanie, sposób, w jaki REA pomogło, i swoje ustalenia.
## FAQ
<details>
<summary><strong>Którzy agenci mogą korzystać z REA?</strong></summary>
Każdy agent obsługujący lokalne serwery MCP. Konfigurator konfiguruje [obsługiwanych agentów](docs/installation.md#supported-agents); inne klienty mogą użyć [ręcznej rejestracji MCP](docs/installation.md#mcp-registry).
</details>
<details>
<summary><strong>Czy potrzebuję Hoppera, Ghidry lub IDA?</strong></summary>
Dogłębna analiza kodu natywnego używa jednego z nich. Statyczna analiza JavaScript i .NET działa bez silnika analizy natywnej. Konfigurator może zainstalować Hoppera po uzyskaniu zgody; Ghidra i IDA korzystają z istniejących instalacji. Zobacz [konfigurację dostawców analizy](docs/installation.md#hopper).
</details>
<details>
<summary><strong>Czy muszę najpierw uruchomić Hoppera?</strong></summary>
REA uruchamia Hoppera, gdy wymaga tego operacja. W systemie macOS przy pierwszym uruchomieniu okno dialogowe może poprosić o wybór trybu demonstracyjnego lub aktywację licencji. Zobacz [uruchamianie Hoppera i rozwiązywanie problemów](docs/installation.md#launcher-paths-and-troubleshooting).
</details>
<details>
<summary><strong>Co daje zainstalowanie umiejętności z skills.sh?</strong></summary>
Umiejętność dostarcza agentowi instrukcje prowadzenia analizy. Użyj `npx rea-agents setup`, aby zarejestrować serwer MCP REA i zainstalować pasujące instrukcje, a następnie uruchom agenta ponownie. Zobacz [instalację samej umiejętności](docs/installation.md#skill-only-installation).
</details>
<details>
<summary><strong>Jaki kod zwraca REA?</strong></summary>
Analiza kodu natywnego zwraca pseudokod i kod asemblera. Analiza JavaScript/Electron odzyskuje moduły i ich powiązania. Agent wykorzystuje te ustalenia do napisania i przetestowania implementacji; [przykłady zastosowań](#przykłady-zastosowań) pokazują ten proces w praktyce.
</details>
<details>
<summary><strong>Czy REA przesyła moją aplikację?</strong></summary>
REA analizuje cele lokalnie. Twój agent otrzymuje wyniki narzędzi, a dostawca jego modelu ma własną politykę dotyczącą danych.
</details>
<details>
<summary><strong>Co zrobić, gdy napotkam błąd?</strong></summary>
Najpierw zaktualizuj REA; najnowsze wydanie mogło już naprawić ten problem.
Dla CLI zainstalowanego przez npm:
```bash
rea update
```
Dla konfiguracji agenta przez `npx`:
```bash
npx rea-agents@latest setup
```
Jeśli używasz agenta, wykonaj [odświeżenie konfiguracji](#zaktualizuj-rea) i uruchom go ponownie. Ponów tę samą operację. Jeśli problem pozostaje, [otwórz zgłoszenie](https://github.com/morluto/rea/issues), podając wersję REA, typ celu analizy, kroki odtworzenia problemu i komunikaty błędu.
</details>
## Dokumentacja
Zacznij od [przewodników z przykładami](https://rea.tools/guides/) na stronie internetowej. Dokładne opcje, wymagania wstępne i kontrakty wyników opisano tutaj:
- [Instalacja i konfiguracja](docs/installation.md): rejestracja agentów, konfiguracja dostawców analizy, aktualizacje i odinstalowanie.
- [Gotowość i rozwiązywanie problemów](docs/installation.md#check-readiness-for-your-task): diagnostyka jednego agenta lub silnika analizy.
- [CLI i Evidence](docs/cli.md): polecenia, wybór dostawcy, migawki, import/eksport i kody zakończenia.
- [Kontrakty MCP](docs/mcp-contracts.md) i [prompty dla agentów](docs/mcp-prompts.md): wyniki narzędzi, sesje i prowadzone analizy.
- [Katalog narzędzi](docs/mcp-contracts.md#generated-catalog): generowany podczas kompilacji wykaz narzędzi, dostawców i poleceń CLI.
- [Plan rozwoju](docs/roadmap.md): planowane prace i śledzenie funkcjonalności.
Zgłaszaj podatności zgodnie z [SECURITY.md](SECURITY.md).
## Historia gwiazdek
🎉 **40 000 gwiazdek na GitHubie — dziękujemy!**
Dziękujemy wszystkim, którzy używają REA, zgłaszają błędy, proponują nowe funkcje, testują kompilacje i przesyłają poprawki.
<img alt="Historia gwiazdek REA na GitHubie" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
</picture>
</a>
## Zastrzeżenie
REA dostarcza narzędzia do zgodnych z prawem badań z zakresu inżynierii wstecznej, analizy i odtwarzania. Odpowiadasz za uzyskanie wymaganych zezwoleń i przestrzeganie obowiązującego prawa. Projekt nie popiera działań nielegalnych ani nieautoryzowanych.
## Współtworzenie
Chętnie przyjmiemy Twoją pomoc w rozwoju REA! [Otwórz zgłoszenie](https://github.com/morluto/rea/issues), aby poinformować o błędzie lub zaproponować funkcję, albo [wyślij pull request](https://github.com/morluto/rea/pulls) z ulepszeniami kodu lub dokumentacji.
Zobacz [CONTRIBUTING.md](CONTRIBUTING.md), aby poznać konfigurację środowiska programistycznego i kontrole, [testowanie](docs/testing.md), aby poznać ścieżki weryfikacji, oraz [mapę architektury](docs/architecture.mermaid), aby poznać strukturę projektu.
**[Site](https://rea.tools/) · [Guias](https://rea.tools/guides/) · [Casos de uso](https://rea.tools/showcase/)**
[Início rápido](#início-rápido) · [Como o REA funciona](#como-o-rea-funciona) · [O que você pode analisar](#o-que-você-pode-analisar) · [Casos de uso](#casos-de-uso) · [Perguntas frequentes](#perguntas-frequentes) · [Documentação](#documentação)
<code>npx rea-agents setup</code>
<br />
<img src="docs/assets/rea-hopper-analysis.png" alt="REA inicia sua ponte de análise dentro do Hopper enquanto inspeciona um binário nativo" width="1200" />
<strong>Participe da comunidade de engenharia reversa</strong>
</a><br />
<sub>Discord · Perguntas e respostas · Compartilhe seus resultados</sub>
</td>
</tr>
</table>
<br />
</div>
---
Viu uma funcionalidade em um aplicativo que gostaria de ter no seu próprio produto? Peça ao seu agente para investigá-la com o REA. Ele pode inspecionar o aplicativo sem o código-fonte, explicar como a funcionalidade funciona, apresentar as evidências e criar uma versão para o seu projeto.
O REA conecta seu agente a ferramentas para inspecionar binários nativos, aplicativos JavaScript e Electron, assemblies .NET e sites. Você também pode usar as mesmas ferramentas pelo terminal. A análise acontece localmente, e os resultados incluem as evidências e limitações por trás de cada conclusão.
A configuração registra o REA no seu agente e instala as instruções de fluxo de trabalho correspondentes. A análise nativa pode usar uma instalação existente do Hopper ou do Ghidra; a configuração também pode instalar o Hopper opcionalmente, mediante aprovação. A análise estática de JavaScript não precisa de nenhum dos dois motores.
> **[Visite o site do REA](https://rea.tools/)** para instruções de configuração, guias ilustrados e estudos de caso reais.
## Início rápido
### Configure seu agente
Com Node.js e npm instalados, execute:
```bash
npx rea-agents setup
```
Escolha seus agentes, revise as alterações propostas e aprove-as. A configuração adiciona o servidor MCP do REA e as instruções de fluxo de trabalho correspondentes, com backups das configurações existentes. Reinicie seu agente depois.
A configuração oferece suporte ao Claude Code, Codex, Cursor, Gemini CLI, Grok Build e [outros agentes](docs/installation.md#supported-agents). Consulte [instalação e configuração](docs/installation.md) para configurar provedores e registrar o MCP manualmente.
### Peça ao seu agente
```text
Investigue como a busca funciona no aplicativo Notes, mostre as evidências e crie uma funcionalidade semelhante para o meu projeto.
```
Substitua Notes pelo aplicativo alvo e indique a funcionalidade que deseja entender.
### Use o terminal
Inspecione um diretório extraído de um aplicativo JavaScript/Electron ou um arquivo ASAR:
O resultado inclui módulos, importações, limites do Electron e suas evidências. Substitua o caminho pelo do seu alvo, como `"D:/apps/example"` no Windows.
Para instalar o comando `rea` e usá-lo regularmente:
```bash
npm install --global rea-agents
rea --help
```
Para análise nativa, configure primeiro um provedor. Consulte o [guia de CLI e Evidence](docs/cli.md) para comandos nativos, seleção de provedores, snapshots e uso em scripts.
### Atualize o REA
O REA muda rapidamente, e novas versões incluem correções frequentes de bugs. Mantenha sua instalação atualizada.
Para uma CLI instalada pelo npm:
```bash
rea update
```
Para atualizar os registros dos agentes e a skill, execute o comando de configuração exibido pela atualização.
Se você usa `npx`, atualize a configuração do agente com:
```bash
npx rea-agents@latest setup
```
Revise as alterações de configuração e reinicie seu agente. Para comandos avulsos da CLI, use `npx rea-agents@latest` seguido do comando.
## Como o REA funciona
Seu agente chama o REA por MCP para inspecionar o alvo e rastrear o código relevante. O REA retorna os resultados com suas evidências. O agente usa esses resultados para fazer novas perguntas, explicar o comportamento ou escrever e testar uma implementação. Os comandos da CLI usam os mesmos fluxos de trabalho.
[Abra a figura em tamanho completo](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## O que você pode analisar
O REA requer Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, além do npm. As ferramentas adicionais e os sistemas anfitriões compatíveis dependem do alvo:
| Alvo | O que o REA retorna | Requisitos e guia |
| Binários nativos | Pseudocódigo, assembly, strings, símbolos, chamadas e referências | Hopper, Ghidra ou IDA; [análise nativa](https://rea.tools/guides/native/) |
| Estrutura ELF sem execução | Seções, segmentos, símbolos/relocações originais e possíveis mecanismos de mitigação identificados por análise estática | pwntools fornecido pelo chamador no Linux x64; [diagnóstico de binários](docs/binary-diagnostics.md) |
| Bytecode EVM | Seletores de despacho, offsets de bytes, argumentos inferidos e mutabilidade | Entrada local com bytes brutos ou representação hexadecimal; [guia de EVM sem execução](docs/evm-bytecode.md) |
| Falhas do Linux registradas | Registros note brutos, registradores/sinais de cada thread registrada e candidatos opcionais a mapeamentos | pwntools fornecido pelo chamador; GDB/pwndbg opcionais; [falhas registradas](docs/recorded-crashes.md) |
| JavaScript / Electron | Módulos, importações, source maps, rotas, IPC e relações com complementos nativos | Node.js e npm; [análise de aplicativos](https://rea.tools/guides/javascript/) |
| Sites | Estrutura da página, scripts, observações de rede e capturas de tela solicitadas | Um navegador da família Chrome; [análise do navegador](https://rea.tools/guides/browser/) |
| Capturas de rede salvas | Requisições, respostas, payloads acessíveis e localizações de origem | HAR; mitmdump no Linux para capturas no formato nativo do mitmproxy; [guia de capturas](docs/web-network-captures.md) |
| Assemblies .NET | Metadados, instruções CIL, dependências nativas declaradas e comparações de builds | Inspeção estática; [guia de código gerenciado](docs/managed-code-analysis.md) |
| APKs Android | Declarações do manifesto, classes, métodos descompilados e referências | JADX sem interface gráfica e um JDK completo no Linux/macOS; [guia de Android](docs/android-analysis.md) |
| Firmware | Regiões, resultados de extração e encaminhamentos à análise nativa | Binwalk / Unblob no Linux; [guia de firmware](docs/firmware-analysis.md) |
| Pacotes e recursos | Inventários de arquivos, digests, plists, estrutura de bundles Apple e recursos extraídos | [Guia de artefatos e JavaScript](docs/javascript-artifact-reconstruction.md), [aplicativos Apple](docs/apple-application-analysis.md) |
| Comportamento de processos | Saída do terminal, interações, observações de encerramento e do sistema de arquivos, e comparações entre execuções | Linux/macOS com PTY nativo; [captura de processos](docs/process-capture.md) |
A inspeção estática de JavaScript e .NET lê os arquivos fornecidos sem executar o aplicativo. A captura em execução inicia o alvo selecionado ou interage com ele usando as permissões do seu usuário; cada guia descreve seus efeitos.
<a id="choosing-a-deep-analysis-provider"></a>
Os formatos nativos e os sistemas anfitriões compatíveis variam por provedor. Consulte [configuração do Hopper e Ghidra](docs/installation.md#hopper), o [guia do IDA](docs/ida-provider.md) e o [suporte experimental ao Ghidra no Windows](docs/windows-ghidra-p0.md). O Ghidra também oferece [análise de DOS de 16 bits](docs/ghidra-dos.md). Para selecionar um provedor, consulte o [guia da CLI](docs/cli.md#choose-a-provider). Verifique a [disponibilidade nas versões](docs/installation.md#released-package-and-main) das funcionalidades adicionadas após a versão mais recente no npm.
## Casos de uso
[](https://rea.tools/showcase/)
### DX-Ball: reconstruir um cálculo de panorâmica de áudio
Siga uma chamada de áudio até a função auxiliar que converte posição em panorâmica, inspecione as instruções e transforme pseudocódigo incompleto em C. A reconstrução passa em 3.205 casos com o x86 original e reproduz todos os 63 bytes da função compilada.
[Leia o estudo de caso](https://rea.tools/showcase/dx-ball/) · [Repositório da reconstrução](https://github.com/N0zoM1z0/dx-ball)
### Notion: rastrear a ponte da área de transferência do Electron
Encontre a API da área de transferência do renderizador, siga-a por preload e IPC até o processo principal e inspecione o formato da área de transferência com seus dados de formatação.
[Leia o estudo de caso](https://rea.tools/showcase/notion/)
### TH04: recuperar o cálculo de um anel de projéteis no DOS
Inspecione as instruções de 16 bits do jogo original para PC-98, recupere os cálculos de ângulos fixos e direcionados e compare o C++ reconstruído com a saída do compilador da época.
[Leia o estudo de caso](https://rea.tools/showcase/th04/) · [Repositório da reconstrução](https://github.com/N0zoM1z0/th04)
Se você usou o REA em algo interessante, gostaríamos de conhecer. Compartilhe seu caso em uma [issue](https://github.com/morluto/rea/issues) ou um [pull request](https://github.com/morluto/rea/pulls), incluindo o alvo, sua pergunta, como o REA ajudou e o que descobriu.
## Perguntas frequentes
<details>
<summary><strong>Quais agentes podem usar o REA?</strong></summary>
Qualquer agente que ofereça suporte a servidores MCP locais. A configuração prepara os [agentes compatíveis](docs/installation.md#supported-agents); outros clientes podem usar o [registro manual do MCP](docs/installation.md#mcp-registry).
</details>
<details>
<summary><strong>Preciso do Hopper, Ghidra ou IDA?</strong></summary>
A análise nativa aprofundada usa um desses motores. A inspeção estática de JavaScript e .NET funciona sem um motor de análise nativa. A configuração pode instalar o Hopper após aprovação; Ghidra e IDA usam as instalações existentes. Consulte [configuração dos provedores](docs/installation.md#hopper).
</details>
<details>
<summary><strong>Preciso iniciar o Hopper antes?</strong></summary>
O REA inicia o Hopper quando uma operação precisa dele. No macOS, um diálogo na primeira execução pode pedir que você escolha o modo de demonstração ou ative a licença. Consulte [inicialização do Hopper e solução de problemas](docs/installation.md#launcher-paths-and-troubleshooting).
</details>
<details>
<summary><strong>O que faz a instalação da skill pelo skills.sh?</strong></summary>
A skill fornece instruções de investigação ao seu agente. Use `npx rea-agents setup` para registrar o servidor MCP do REA e instalar as instruções correspondentes, depois reinicie seu agente. Consulte [instalação apenas da skill](docs/installation.md#skill-only-installation).
</details>
<details>
<summary><strong>Que código o REA retorna?</strong></summary>
A análise nativa retorna pseudocódigo e assembly. A análise de JavaScript/Electron recupera módulos e suas relações. Seu agente usa esses resultados para escrever e testar uma implementação; os [casos de uso](#casos-de-uso) apresentam exemplos completos.
</details>
<details>
<summary><strong>O REA envia meu aplicativo para algum servidor?</strong></summary>
O REA analisa os alvos localmente. Seu agente recebe os resultados das ferramentas, e o provedor do modelo tem sua própria política de dados.
</details>
<details>
<summary><strong>O que devo fazer se encontrar um bug?</strong></summary>
Atualize primeiro; uma versão recente pode já ter corrigido o problema.
Para uma CLI instalada pelo npm:
```bash
rea update
```
Para configurar o agente por `npx`:
```bash
npx rea-agents@latest setup
```
Se você usa um agente, conclua a [atualização da configuração](#atualize-o-rea) e reinicie-o. Tente executar a mesma tarefa novamente. Se o problema persistir, [abra uma issue](https://github.com/morluto/rea/issues) com sua versão do REA, o tipo de alvo, os passos para reproduzir e a saída do erro.
</details>
## Documentação
Comece pelos [guias práticos](https://rea.tools/guides/) do site. Para opções exatas, pré-requisitos e contratos dos resultados:
- [Instalação e configuração](docs/installation.md): registro de agentes, configuração de provedores, atualizações e desinstalação.
- [Prontidão e solução de problemas](docs/installation.md#check-readiness-for-your-task): diagnóstico de um agente ou motor de análise específico.
- [CLI e Evidence](docs/cli.md): comandos, seleção de provedores, snapshots, importação/exportação e status de saída.
- [Contratos MCP](docs/mcp-contracts.md) e [prompts para agentes](docs/mcp-prompts.md): resultados das ferramentas, sessões e investigações guiadas.
- [Catálogo de ferramentas](docs/mcp-contracts.md#generated-catalog): inventário de ferramentas, provedores e comandos da CLI gerado durante o build.
- [Roadmap](docs/roadmap.md): trabalho planejado e acompanhamento das capacidades.
<img alt="Histórico de estrelas do REA no GitHub" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
</picture>
</a>
## Aviso legal
O REA fornece ferramentas para pesquisa, análise e reconstrução por engenharia reversa dentro da lei. Você é responsável por obter as autorizações necessárias e cumprir as leis aplicáveis. O projeto não apoia usos ilegais ou não autorizados.
## Contribuir
Sua ajuda com o REA é bem-vinda! [Abra uma issue](https://github.com/morluto/rea/issues) para relatar um bug ou sugerir uma funcionalidade, ou [envie um pull request](https://github.com/morluto/rea/pulls) para melhorar o código ou a documentação.
Consulte [CONTRIBUTING.md](CONTRIBUTING.md) para configurar o ambiente de desenvolvimento e as verificações, o [guia de testes](docs/testing.md) para os fluxos de verificação e o [mapa da arquitetura](docs/architecture.mermaid) para a estrutura do projeto.
[Быстрый старт](#быстрый-старт) · [Как работает REA](#как-работает-rea) · [Что можно анализировать](#что-можно-анализировать) · [Примеры](#примеры) · [Частые вопросы](#частые-вопросы) · [Документация](#документация)
<code>npx rea-agents setup</code>
<br />
<img src="docs/assets/rea-hopper-analysis.png" alt="REA запускает мост анализа внутри Hopper при исследовании нативного бинарного файла" width="1200" />
<strong>Присоединяйтесь к сообществу реверс-инжиниринга</strong>
</a><br />
<sub>Discord · Вопросы и ответы · Обмен результатами</sub>
</td>
</tr>
</table>
<br />
</div>
---
Увидели в приложении функцию, которую хотите добавить в свой продукт? Попросите агента исследовать её с помощью REA. Он может изучить приложение без исходного кода, объяснить работу функции, показать подтверждающие данные и создать подходящую реализацию для вашего проекта.
REA подключает вашего агента к инструментам для исследования нативных бинарных файлов, приложений JavaScript и Electron, сборок .NET и сайтов. Те же инструменты доступны в терминале. Анализ выполняется локально, а результаты содержат данные и ограничения, на которых основан каждый вывод.
Настройка регистрирует REA в вашем агенте и устанавливает соответствующие инструкции по работе. Для нативного анализа можно использовать уже установленный Hopper или Ghidra; настройка также может установить Hopper с вашего согласия. Для статического анализа JavaScript не нужен ни один из этих движков.
> **[Посетите сайт REA](https://rea.tools/)**: там есть инструкции по настройке, иллюстрированные руководства и реальные исследования.
## Быстрый старт
### Настройте агента
Если Node.js и npm установлены, выполните:
```bash
npx rea-agents setup
```
Выберите агентов, проверьте предлагаемые изменения и подтвердите их. Настройка добавляет MCP-сервер REA и соответствующие рабочие инструкции, сохраняя резервные копии существующих настроек. После этого перезапустите агента.
Настройка поддерживает Claude Code, Codex, Cursor, Gemini CLI, Grok Build и [других агентов](docs/installation.md#supported-agents). Настройка провайдеров и ручная регистрация MCP описаны в разделе [установка и настройка](docs/installation.md).
### Задайте вопрос агенту
```text
Исследуй, как работает поиск в приложении Notes, покажи подтверждающие данные и создай похожую функцию для моего проекта.
```
Замените Notes нужным приложением и укажите функцию, которую хотите понять.
### Используйте терминал
Исследуйте распакованный каталог приложения JavaScript/Electron или файл ASAR:
Результат включает модули, импорты, границы Electron и подтверждающие данные. Замените путь своим, например `"D:/apps/example"` в Windows.
Для регулярного использования установите команду `rea`:
```bash
npm install --global rea-agents
rea --help
```
Для нативного анализа сначала настройте провайдер. Нативные команды, выбор провайдера, снимки и работу со скриптами описывает [руководство по CLI и Evidence](docs/cli.md).
### Обновите REA
REA быстро развивается, и новые версии часто содержат исправления ошибок. Регулярно обновляйте установленную версию.
Для CLI, установленного через npm:
```bash
rea update
```
Чтобы обновить регистрации агентов и skill, выполните команду настройки, которую выведет обновление.
Если используете `npx`, обновите настройку агента командой:
```bash
npx rea-agents@latest setup
```
Проверьте изменения настроек и перезапустите агента. Для разовых команд CLI используйте `npx rea-agents@latest`, а затем нужную команду.
## Как работает REA
Агент вызывает REA через MCP, чтобы исследовать цель и проследить связанный код. REA возвращает результаты вместе с подтверждающими данными. Агент использует их для уточняющих вопросов, объяснения поведения или написания и тестирования реализации. Команды CLI используют те же рабочие процессы.
[Открыть рисунок в полном размере](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## Что можно анализировать
REA требует Node.js 22.x (>=22.19), 24.x (>=24.11) или 26+, а также npm. Дополнительные инструменты и поддерживаемые системы зависят от цели:
| Цель | Что возвращает REA | Требования и руководство |
| Нативные бинарные файлы | Псевдокод, ассемблер, строки, символы, вызовы и ссылки | Hopper, Ghidra или IDA; [нативный анализ](https://rea.tools/guides/native/) |
| Структура ELF без запуска | Секции, сегменты, исходные символы/релокации и возможные механизмы защиты по данным статического анализа | pwntools, предоставленный вызывающей стороной, в Linux x64; [диагностика бинарных файлов](docs/binary-diagnostics.md) |
| Байт-код EVM | Селекторы диспетчеризации, смещения байтов, предполагаемые аргументы и изменяемость состояния | Локальные необработанные байты или шестнадцатеричное представление; [руководство по EVM без запуска](docs/evm-bytecode.md) |
| Записанные сбои Linux | Необработанные записи note, регистры/сигналы каждого записанного потока и необязательные кандидаты сопоставления с памятью | pwntools, предоставленный вызывающей стороной; необязательные GDB/pwndbg; [записанные сбои](docs/recorded-crashes.md) |
| JavaScript / Electron | Модули, импорты, карты исходного кода, маршруты, IPC и связи с нативными дополнениями | Node.js и npm; [анализ приложений](https://rea.tools/guides/javascript/) |
| Сайты | Структура страницы, скрипты, наблюдения за сетью и запрошенные снимки экрана | Браузер семейства Chrome; [анализ браузера](https://rea.tools/guides/browser/) |
| Сохранённые сетевые захваты | Запросы, ответы, доступные полезные данные и позиции в источнике | HAR; mitmdump в Linux для захватов в собственном формате mitmproxy; [руководство по сетевым захватам](docs/web-network-captures.md) |
| Сборки .NET | Метаданные, инструкции CIL, объявленные нативные зависимости и сравнения сборок | Статическое исследование; [руководство по управляемому коду](docs/managed-code-analysis.md) |
| Android APK | Объявления манифеста, классы, декомпилированные методы и ссылки | JADX без графического интерфейса и полный JDK в Linux/macOS; [руководство по Android](docs/android-analysis.md) |
| Прошивки | Области, результаты извлечения и передача в нативный анализ | Binwalk / Unblob в Linux; [руководство по прошивкам](docs/firmware-analysis.md) |
| Пакеты и ресурсы | Списки файлов, хеши, plist, структура пакетов Apple и извлечённые ресурсы | [Руководство по артефактам и JavaScript](docs/javascript-artifact-reconstruction.md), [приложения Apple](docs/apple-application-analysis.md) |
| Поведение процессов | Вывод терминала, взаимодействия, наблюдения за завершением и файловой системой, сравнения запусков | Linux/macOS с нативным PTY; [захват процессов](docs/process-capture.md) |
Статическое исследование JavaScript и .NET читает предоставленные файлы, не запуская приложение. Захват во время выполнения запускает выбранную цель или взаимодействует с ней с правами вашего пользователя; соответствующие руководства описывают последствия.
<a id="choosing-a-deep-analysis-provider"></a>
Нативные форматы и поддерживаемые системы различаются у разных провайдеров. См. [настройку Hopper и Ghidra](docs/installation.md#hopper), [руководство по IDA](docs/ida-provider.md) и [экспериментальную поддержку Ghidra в Windows](docs/windows-ghidra-p0.md). Ghidra также поддерживает [анализ 16-битного DOS](docs/ghidra-dos.md). Выбор провайдера описан в [руководстве по CLI](docs/cli.md#choose-a-provider). Для функций, добавленных после последней версии в npm, проверьте [доступность в релизах](docs/installation.md#released-package-and-main).
## Примеры
[](https://rea.tools/showcase/)
### DX-Ball: восстановление расчёта звуковой панорамы
Проследите звуковой вызов до функции, преобразующей координату в значение панорамы, изучите инструкции и превратите неполный псевдокод в C. Восстановленная реализация проходит 3 205 тестов с исходным x86-кодом и воспроизводит все 63 байта скомпилированной функции.
### Notion: исследование моста буфера обмена Electron
Найдите API буфера обмена в процессе рендеринга, проследите его через preload и IPC до основного процесса и изучите формат буфера обмена с форматированием.
### TH04: восстановление расчёта кольца пуль в DOS
Изучите 16-битные инструкции оригинальной игры для PC-98, восстановите расчёты фиксированных и прицельных углов и сравните восстановленный C++ с выводом компилятора того времени.
Если вы исследовали с REA что-то интересное, поделитесь результатом. Создайте [issue](https://github.com/morluto/rea/issues) или [pull request](https://github.com/morluto/rea/pulls) и укажите цель, ваш вопрос, как помог REA и что удалось узнать.
## Частые вопросы
<details>
<summary><strong>Какие агенты могут использовать REA?</strong></summary>
Любой агент с поддержкой локальных MCP-серверов. Настройка конфигурирует [поддерживаемых агентов](docs/installation.md#supported-agents); другие клиенты могут использовать [ручную регистрацию MCP](docs/installation.md#mcp-registry).
</details>
<details>
<summary><strong>Нужны ли мне Hopper, Ghidra или IDA?</strong></summary>
Углублённый нативный анализ использует один из этих инструментов. Статическое исследование JavaScript и .NET работает без движка нативного анализа. Настройка может установить Hopper после подтверждения; Ghidra и IDA используют существующие установки. См. [настройку провайдеров](docs/installation.md#hopper).
</details>
<details>
<summary><strong>Нужно ли сначала запускать Hopper?</strong></summary>
REA запускает Hopper, когда он нужен для операции. В macOS при первом запуске может появиться диалог выбора деморежима или активации лицензии. См. [запуск Hopper и устранение неполадок](docs/installation.md#launcher-paths-and-troubleshooting).
</details>
<details>
<summary><strong>Что даёт установка skill с skills.sh?</strong></summary>
Skill предоставляет агенту инструкции по исследованию. Используйте `npx rea-agents setup`, чтобы зарегистрировать MCP-сервер REA и установить соответствующие инструкции, затем перезапустите агента. См. [установку только skill](docs/installation.md#skill-only-installation).
</details>
<details>
<summary><strong>Какой код возвращает REA?</strong></summary>
Нативный анализ возвращает псевдокод и ассемблер. Анализ JavaScript/Electron восстанавливает модули и их связи. Агент использует эти результаты, чтобы написать и протестировать реализацию; в [примерах](#примеры) показаны практические исследования.
</details>
<details>
<summary><strong>REA загружает моё приложение на сервер?</strong></summary>
REA анализирует цели локально. Ваш агент получает результаты инструментов, а у его поставщика моделей есть собственная политика обработки данных.
</details>
<details>
<summary><strong>Что делать, если я столкнулся с ошибкой?</strong></summary>
Сначала обновитесь: недавний релиз мог уже исправить ошибку.
Для CLI, установленного через npm:
```bash
rea update
```
Для настройки агента через `npx`:
```bash
npx rea-agents@latest setup
```
Если используете агента, завершите [обновление настройки](#обновите-rea) и перезапустите его. Повторите ту же задачу. Если проблема сохраняется, [откройте issue](https://github.com/morluto/rea/issues), указав версию REA, тип цели, шаги воспроизведения и вывод ошибки.
</details>
## Документация
Начните с [практических руководств](https://rea.tools/guides/) на сайте. Точные параметры, требования и контракты результатов описаны здесь:
- [Установка и настройка](docs/installation.md): регистрация агентов, настройка провайдеров, обновление и удаление.
- [Готовность и устранение неполадок](docs/installation.md#check-readiness-for-your-task): диагностика конкретного агента или движка анализа.
- [CLI и Evidence](docs/cli.md): команды, выбор провайдера, снимки, импорт/экспорт и коды завершения.
- [Контракты MCP](docs/mcp-contracts.md) и [промпты агентов](docs/mcp-prompts.md): результаты инструментов, сеансы и исследования с подсказками.
- [Каталог инструментов](docs/mcp-contracts.md#generated-catalog): создаваемый при сборке перечень инструментов, провайдеров и команд CLI.
- [План развития](docs/roadmap.md): запланированные работы и отслеживание возможностей.
Сообщайте об уязвимостях согласно [SECURITY.md](SECURITY.md).
## История звёзд
🎉 **40 000 звёзд на GitHub — спасибо!**
Спасибо всем, кто использует REA, сообщает об ошибках, предлагает новые функции, тестирует сборки и помогает с исправлениями.
<img alt="История звёзд REA на GitHub" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
</picture>
</a>
## Отказ от ответственности
REA предоставляет инструменты для законных исследований, анализа и реконструкции с помощью реверс-инжиниринга. Вы отвечаете за получение необходимых разрешений и соблюдение применимых законов. Проект не поддерживает незаконное или несанкционированное использование.
## Участие в проекте
Будем рады вашей помощи с REA! [Откройте issue](https://github.com/morluto/rea/issues), чтобы сообщить об ошибке или предложить функцию, либо [отправьте pull request](https://github.com/morluto/rea/pulls) с улучшениями кода или документации.
Настройка среды разработки и проверки описаны в [CONTRIBUTING.md](CONTRIBUTING.md), направления проверки — в [руководстве по тестированию](docs/testing.md), а структура проекта — на [схеме архитектуры](docs/architecture.mermaid).
Bir uygulamada kendi ürününüze eklemek istediğiniz bir özellik mi gördünüz? Ajanınızdan REA ile araştırmasını isteyin. Kaynak kodu olmadan uygulamayı inceleyebilir, özelliğin nasıl çalıştığını açıklayabilir, kanıtları gösterebilir ve projenize uygun bir sürümünü geliştirebilir.
REA, ajanınızı yerel makine kodu içeren ikili dosyaları, JavaScript ve Electron uygulamalarını, .NET derlemelerini ve web sitelerini inceleyen araçlara bağlar. Aynı araçları terminalden de kullanabilirsiniz. Analiz yerel olarak çalışır; sonuçlar her çıkarımın dayandığı kanıtları ve sınırlamaları içerir.
Kurulum, REA'yı ajanınıza kaydeder ve uyumlu iş akışı talimatlarını yükler. Yerel makine kodu analizi mevcut bir Hopper veya Ghidra kurulumunu kullanabilir; kurulum işlemi, onayınızla isteğe bağlı olarak Hopper da yükleyebilir. Statik JavaScript analizi bu iki motora da ihtiyaç duymaz.
> Kurulum talimatları, görselli rehberler ve gerçek örnek çalışmalar için **[REA web sitesini ziyaret edin](https://rea.tools/)**.
## Hızlı başlangıç
### Ajanınızı yapılandırın
Node.js ve npm yüklüyken şu komutu çalıştırın:
```bash
npx rea-agents setup
```
Ajanlarınızı seçin, önerilen değişiklikleri inceleyin ve onaylayın. Kurulum, mevcut yapılandırmaları yedekleyerek REA'nın MCP sunucusunu ve uyumlu iş akışı talimatlarını ekler. Ardından ajanınızı yeniden başlatın.
Kurulum Claude Code, Codex, Cursor, Gemini CLI, Grok Build ve [diğer ajanları](docs/installation.md#supported-agents) destekler. Sağlayıcı yapılandırması ve elle MCP kaydı için [yükleme ve kurulum](docs/installation.md) belgesine bakın.
### Ajanınıza sorun
```text
Notes uygulamasında aramanın nasıl çalıştığını araştır, kanıtları göster ve projem için benzer bir özellik geliştir.
```
Notes yerine hedef uygulamanızı ve anlamak istediğiniz özelliği belirtin.
### Terminali kullanın
Çıkarılmış bir JavaScript/Electron uygulama dizinini veya ASAR dosyasını inceleyin:
Sonuç; modülleri, içe aktarmaları, Electron sınırlarını ve bunlara ilişkin kanıtları içerir. Yolu hedefinizle değiştirin; Windows'ta örneğin `"D:/apps/example"` kullanabilirsiniz.
Düzenli kullanım için `rea` komutunu yüklemek üzere:
```bash
npm install --global rea-agents
rea --help
```
Yerel makine kodu analizi için önce bir sağlayıcı yapılandırın. Yerel analiz komutları, sağlayıcı seçimi, anlık görüntüler ve betik kullanımı için [CLI ve Evidence rehberine](docs/cli.md) bakın.
### REA'yı güncelleyin
REA hızla değişir ve yeni sürümler sık sık hata düzeltmeleri içerir. Kurulumunuzu güncel tutun.
npm ile yüklenen CLI için:
```bash
rea update
```
Ajan kayıtlarını ve skill'i güncellemek için güncellemenin çıktısında gösterilen kurulum komutunu çalıştırın.
`npx` kullanıyorsanız ajan kurulumunu şu komutla güncelleyin:
```bash
npx rea-agents@latest setup
```
Kurulum değişikliklerini inceleyin ve ajanınızı yeniden başlatın. Tek seferlik CLI işlemleri için `npx rea-agents@latest` komutunun ardından istediğiniz komutu yazın.
## REA nasıl çalışır
Ajanınız, hedefi incelemek ve ilgili kodu izlemek için MCP üzerinden REA'yı çağırır. REA bulguları kanıtlarıyla birlikte döndürür. Ajan bunları takip soruları sormak, davranışı açıklamak veya bir uygulama yazıp test etmek için kullanır. CLI komutları aynı iş akışlarını kullanır.
[Şekli tam boyutuyla açın](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## Neleri analiz edebilirsiniz
REA; Node.js 22.x (>=22.19), 24.x (>=24.11) veya 26+ ve npm gerektirir. Ek araçlar ve desteklenen ana bilgisayar sistemleri hedefe bağlıdır:
| Hedef | REA'nın döndürdükleri | Gereksinimler ve rehber |
| Yerel makine kodu içeren ikili dosyalar | Sözde kod, assembly kodu, dizeler, semboller, çağrılar ve referanslar | Hopper, Ghidra veya IDA; [yerel kod analizi](https://rea.tools/guides/native/) |
| Çevrimdışı ELF yapısı | Bölümler, segmentler, özgün semboller/yeniden konumlandırmalar ve statik analizden olası güvenlik önlemleri | Linux x64 üzerinde çağıranın sağladığı pwntools; [ikili dosya tanılama](docs/binary-diagnostics.md) |
| EVM bayt kodu | Yönlendirme seçicileri, bayt ofsetleri, çıkarımla belirlenen argümanlar ve durum değiştirilebilirliği | Yerel ham bayt/onaltılık girdi; [çevrimdışı EVM rehberi](docs/evm-bytecode.md) |
| Kaydedilmiş Linux çökmeleri | Ham note kayıtları, kaydedilen her iş parçacığının yazmaçları/sinyalleri ve isteğe bağlı eşleme adayları | Çağıranın sağladığı pwntools; isteğe bağlı GDB/pwndbg; [kaydedilmiş çökmeler](docs/recorded-crashes.md) |
| JavaScript / Electron | Modüller, içe aktarmalar, kaynak haritaları, rotalar, IPC ve yerel eklenti ilişkileri | Node.js ve npm; [uygulama analizi](https://rea.tools/guides/javascript/) |
| Web siteleri | Sayfa yapısı, betikler, ağ gözlemleri ve istenen ekran görüntüleri | Chrome ailesinden bir tarayıcı; [tarayıcı analizi](https://rea.tools/guides/browser/) |
| Kaydedilmiş ağ yakalamaları | İstekler, yanıtlar, erişilebilir yük içerikleri ve kaynak konumları | HAR; mitmproxy'nin kendi biçimindeki yakalamalar için Linux üzerinde mitmdump; [ağ yakalama rehberi](docs/web-network-captures.md) |
| .NET derlemeleri | Meta veriler, CIL talimatları, bildirilmiş yerel bağımlılıklar ve derleme karşılaştırmaları | Statik inceleme; [yönetilen kod rehberi](docs/managed-code-analysis.md) |
| Android APK'leri | Manifest bildirimleri, sınıflar, tersine derlenmiş metotlar ve referanslar | Linux/macOS üzerinde arayüzsüz JADX ve tam bir JDK; [Android rehberi](docs/android-analysis.md) |
| Donanım yazılımı | Bölgeler, çıkarma sonuçları ve yerel kod analizine devirler | Linux üzerinde Binwalk / Unblob; [donanım yazılımı rehberi](docs/firmware-analysis.md) |
| Paketler ve kaynaklar | Dosya envanterleri, özet değerleri, plist'ler, Apple paket yapısı ve çıkarılmış kaynaklar | [Artefakt ve JavaScript rehberi](docs/javascript-artifact-reconstruction.md), [Apple uygulamaları](docs/apple-application-analysis.md) |
| Süreç davranışı | Terminal çıktısı, etkileşimler, sonlanma ve dosya sistemi gözlemleri, çalıştırma karşılaştırmaları | Yerel PTY ile Linux/macOS; [süreç yakalama](docs/process-capture.md) |
Statik JavaScript ve .NET incelemesi, uygulamayı çalıştırmadan sağlanan dosyaları okur. Çalışma zamanı yakalaması, seçilen hedefi kullanıcı izinlerinizle çalıştırır veya onunla etkileşime girer; her çalışma zamanı rehberi etkilerini açıklar.
<a id="choosing-a-deep-analysis-provider"></a>
Yerel makine kodu içeren ikili dosya biçimleri ve ana bilgisayar desteği sağlayıcıya göre değişir. [Hopper ve Ghidra kurulumu](docs/installation.md#hopper), [IDA rehberi](docs/ida-provider.md) ve [Windows için deneysel Ghidra desteği](docs/windows-ghidra-p0.md) belgelerine bakın. Ghidra ayrıca [16 bit DOS analizini](docs/ghidra-dos.md) destekler. Sağlayıcı seçimi için [CLI rehberine](docs/cli.md#choose-a-provider) bakın. En son npm sürümünden sonra eklenen özellikler için [sürümlerde kullanılabilirliği](docs/installation.md#released-package-and-main) kontrol edin.
## Örnek çalışmalar
[](https://rea.tools/showcase/)
### DX-Ball: Sesin stereo konumlandırma hesabını yeniden oluşturma
Bir ses çağrısından konumu stereo konumlandırmaya dönüştüren yardımcı fonksiyona ilerleyin, talimatları inceleyin ve eksik sözde kodu C'ye dönüştürün. Yeniden oluşturulan kod, özgün x86 üzerinde 3.205 test durumunu geçer ve derlenmiş fonksiyonun 63 baytının tamamını yeniden üretir.
Özgün PC-98 oyununun 16 bit talimatlarını inceleyin, sabit ve hedefe yönelik açı hesaplarını geri çıkarın ve yeniden oluşturulan C++ kodunu dönemin derleyici çıktısıyla karşılaştırın.
REA'yı ilginç bir konuda kullandıysanız görmek isteriz. Hedefi, sorunuzu, REA'nın nasıl yardımcı olduğunu ve bulgularınızı bir [issue](https://github.com/morluto/rea/issues) veya [pull request](https://github.com/morluto/rea/pulls) ile paylaşın.
Yerel MCP sunucularını destekleyen her ajan REA'yı kullanabilir. Kurulum, [desteklenen ajanları](docs/installation.md#supported-agents) yapılandırır; diğer istemciler [elle MCP kaydını](docs/installation.md#mcp-registry) kullanabilir.
</details>
<details>
<summary><strong>Hopper, Ghidra veya IDA gerekiyor mu?</strong></summary>
Derin yerel kod analizi bunlardan birini kullanır. Statik JavaScript ve .NET incelemesi yerel analiz motoru olmadan çalışır. Kurulum onaydan sonra Hopper yükleyebilir; Ghidra ve IDA mevcut kurulumlarınızı kullanır. [Sağlayıcı kurulumuna](docs/installation.md#hopper) bakın.
REA, bir işlem gerektirdiğinde Hopper'ı başlatır. macOS'ta ilk çalıştırmada demo modunu seçmenizi veya lisansınızı etkinleştirmenizi isteyen bir iletişim kutusu açılabilir. [Hopper başlatma ve sorun giderme](docs/installation.md#launcher-paths-and-troubleshooting) belgesine bakın.
</details>
<details>
<summary><strong>skills.sh üzerinden skill yüklemek ne yapar?</strong></summary>
Skill, ajanınıza araştırma talimatları sağlar. REA'nın MCP sunucusunu kaydetmek ve uyumlu talimatları yüklemek için `npx rea-agents setup` kullanın, ardından ajanınızı yeniden başlatın. [Yalnızca skill yükleme](docs/installation.md#skill-only-installation) belgesine bakın.
</details>
<details>
<summary><strong>REA hangi kodu döndürür?</strong></summary>
Yerel kod analizi sözde kod ve assembly kodu döndürür. JavaScript/Electron analizi modülleri ve aralarındaki ilişkileri geri çıkarır. Ajanınız bu bulgularla bir uygulama yazar ve test eder; [örnek çalışmalar](#örnek-çalışmalar) uygulamalı örnekler sunar.
REA hedefleri yerel olarak analiz eder. Ajanınız araç sonuçlarını alır ve model sağlayıcısının kendi veri politikası vardır.
</details>
<details>
<summary><strong>Bir hatayla karşılaşırsam ne yapmalıyım?</strong></summary>
Önce güncelleyin; yakın tarihli bir sürüm hatayı düzeltmiş olabilir.
npm ile yüklenen CLI için:
```bash
rea update
```
`npx` üzerinden ajan kurulumu için:
```bash
npx rea-agents@latest setup
```
Ajan kullanıyorsanız [kurulum yenilemesini](#reayı-güncelleyin) tamamlayın ve ajanı yeniden başlatın. Aynı görevi tekrar deneyin. Sorun sürerse REA sürümünüzü, hedef türünü, yeniden üretme adımlarını ve hata çıktısını içeren bir [issue açın](https://github.com/morluto/rea/issues).
</details>
## Belgeler
Web sitesindeki [uygulamalı rehberlerden](https://rea.tools/guides/) başlayın. Kesin seçenekler, ön koşullar ve sonuç sözleşmeleri için:
- [Yükleme ve kurulum](docs/installation.md): ajan kaydı, sağlayıcı yapılandırması, güncellemeler ve kaldırma.
- [Hazırlık ve sorun giderme](docs/installation.md#check-readiness-for-your-task): belirli bir ajanı veya analiz motorunu tanılama.
- [CLI ve Evidence](docs/cli.md): komutlar, sağlayıcı seçimi, anlık görüntüler, içe/dışa aktarma ve çıkış durumları.
- [MCP sözleşmeleri](docs/mcp-contracts.md) ve [ajan istemleri](docs/mcp-prompts.md): araç sonuçları, oturumlar ve yönlendirmeli araştırmalar.
- [Araç kataloğu](docs/mcp-contracts.md#generated-catalog): derleme sırasında oluşturulan araç, sağlayıcı ve CLI komutu envanteri.
- [Yol haritası](docs/roadmap.md): planlanan çalışmalar ve yetenek takibi.
Güvenlik açıklarını [SECURITY.md](SECURITY.md) üzerinden bildirin.
## Yıldız geçmişi
🎉 **GitHub'da 40.000 yıldız — teşekkürler!**
REA'yı kullanan, hata bildiren, özellik talep eden, derlemeleri test eden ve düzeltmelere katkıda bulunan herkese teşekkürler.
<img alt="REA GitHub yıldız geçmişi" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
</picture>
</a>
## Sorumluluk reddi
REA, yasal tersine mühendislik araştırması, analizi ve yeniden oluşturma için araçlar sağlar. Gerekli izinleri almak ve geçerli yasalara uymak sizin sorumluluğunuzdadır. Proje yasa dışı veya yetkisiz kullanımı desteklemez.
## Katkıda bulunma
REA'ya katkınızı bekliyoruz! Hata bildirmek veya özellik önermek için bir [issue açın](https://github.com/morluto/rea/issues); kodu veya belgeleri geliştirmek için bir [pull request gönderin](https://github.com/morluto/rea/pulls).
Geliştirme ortamı ve kontroller için [CONTRIBUTING.md](CONTRIBUTING.md), doğrulama süreçleri için [test rehberi](docs/testing.md) ve proje yapısı için [mimari harita](docs/architecture.mermaid) belgelerine bakın.
[Швидкий старт](#швидкий-старт) · [Як працює REA](#як-працює-rea) · [Що можна аналізувати](#що-можна-аналізувати) · [Приклади](#приклади) · [Поширені запитання](#поширені-запитання) · [Документація](#документація)
<code>npx rea-agents setup</code>
<br />
<img src="docs/assets/rea-hopper-analysis.png" alt="REA запускає міст аналізу всередині Hopper під час дослідження нативного бінарного файла" width="1200" />
<strong>Приєднуйтеся до спільноти реверс-інжинірингу</strong>
</a><br />
<sub>Discord · Запитання й відповіді · Обмін результатами</sub>
</td>
</tr>
</table>
<br />
</div>
---
Побачили в застосунку функцію, яку хочете додати до свого продукту? Попросіть агента дослідити її за допомогою REA. Він може перевірити застосунок без вихідного коду, пояснити роботу функції, показати підтвердження та створити реалізацію для вашого проєкту.
REA підключає вашого агента до інструментів дослідження нативних бінарних файлів, застосунків JavaScript і Electron, збірок .NET та сайтів. Ті самі інструменти можна використовувати з термінала. Аналіз виконується локально, а результати містять підтвердження й обмеження, на яких ґрунтується кожен висновок.
Налаштування реєструє REA у вашому агенті та встановлює відповідні інструкції робочих процесів. Для нативного аналізу можна використати вже встановлений Hopper або Ghidra; налаштування також може встановити Hopper за вашою згодою. Статичному аналізу JavaScript не потрібен жоден із цих рушіїв.
> **[Відвідайте сайт REA](https://rea.tools/)**, щоб знайти інструкції налаштування, ілюстровані посібники та реальні дослідження.
## Швидкий старт
### Налаштуйте агента
Якщо Node.js і npm встановлено, виконайте:
```bash
npx rea-agents setup
```
Виберіть агентів, перевірте запропоновані зміни та схваліть їх. Налаштування додає MCP-сервер REA та відповідні інструкції робочих процесів, створюючи резервні копії наявної конфігурації. Після цього перезапустіть агента.
Налаштування підтримує Claude Code, Codex, Cursor, Gemini CLI, Grok Build та [інших агентів](docs/installation.md#supported-agents). Конфігурацію провайдерів і ручну реєстрацію MCP описано в розділі [встановлення й налаштування](docs/installation.md).
### Запитайте агента
```text
Досліди, як працює пошук у застосунку Notes, покажи підтвердження й створи подібну функцію для мого проєкту.
```
Замініть Notes цільовим застосунком і вкажіть функцію, яку хочете зрозуміти.
### Використовуйте термінал
Перевірте розпакований каталог застосунку JavaScript/Electron або файл ASAR:
Результат містить модулі, імпорти, межі Electron і підтвердження для них. Замініть шлях своїм, наприклад `"D:/apps/example"`у Windows.
Для регулярного використання встановіть команду `rea`:
```bash
npm install --global rea-agents
rea --help
```
Для нативного аналізу спочатку налаштуйте провайдера. Нативні команди, вибір провайдера, знімки та використання у скриптах описує [посібник CLI та Evidence](docs/cli.md).
### Оновіть REA
REA швидко розвивається, а нові випуски часто містять виправлення помилок. Підтримуйте встановлену версію актуальною.
Для CLI, встановленого через npm:
```bash
rea update
```
Щоб оновити реєстрації агентів і skill, виконайте команду налаштування, яку виведе оновлення.
Якщо використовуєте `npx`, оновіть налаштування агента командою:
```bash
npx rea-agents@latest setup
```
Перевірте зміни налаштувань і перезапустіть агента. Для разових команд CLI використовуйте `npx rea-agents@latest`, а потім потрібну команду.
## Як працює REA
Агент викликає REA через MCP, щоб перевірити ціль і простежити пов'язаний код. REA повертає знахідки разом із підтвердженнями. Агент використовує їх для уточнювальних запитань, пояснення поведінки або написання й тестування реалізації. Команди CLI використовують ті самі робочі процеси.
[Відкрити зображення в повному розмірі](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## Що можна аналізувати
REA потребує Node.js 22.x (>=22.19), 24.x (>=24.11) або 26+, а також npm. Додаткові інструменти й підтримувані системи залежать від цілі:
| Структура ELF без запуску | Секції, сегменти, початкові символи/релокації та можливі захисні механізми за даними статичного аналізу | pwntools, наданий стороною, що викликає інструмент, у Linux x64; [діагностика бінарних файлів](docs/binary-diagnostics.md) |
| Байт-код EVM | Селектори диспетчеризації, зміщення байтів, виведені припущення про аргументи та змінюваність стану | Локальні необроблені байти або шістнадцяткове представлення; [посібник EVM без запуску](docs/evm-bytecode.md) |
| Записані аварійні завершення в Linux | Необроблені записи note, регістри/сигнали кожного записаного потоку й необов'язкові кандидати зіставлення пам'яті | pwntools, наданий стороною, що викликає інструмент; необов'язкові GDB/pwndbg; [записані аварійні завершення](docs/recorded-crashes.md) |
| JavaScript / Electron | Модулі, імпорти, карти вихідного коду, маршрути, IPC і зв'язки з нативними доповненнями | Node.js і npm; [аналіз застосунків](https://rea.tools/guides/javascript/) |
| Сайти | Структура сторінки, скрипти, мережеві спостереження й запитані знімки екрана | Браузер сімейства Chrome; [аналіз браузера](https://rea.tools/guides/browser/) |
| Збережені мережеві захоплення | Запити, відповіді, доступні корисні дані та місця в джерелі | HAR; mitmdump у Linux для захоплень у власному форматі mitmproxy; [посібник мережевих захоплень](docs/web-network-captures.md) |
| Збірки .NET | Метадані, інструкції CIL, оголошені нативні залежності й порівняння збірок | Статична перевірка; [посібник керованого коду](docs/managed-code-analysis.md) |
| Android APK | Оголошення маніфесту, класи, декомпільовані методи й посилання | JADX без графічного інтерфейсу й повний JDK у Linux/macOS; [посібник Android](docs/android-analysis.md) |
| Прошивки | Області, результати видобування й передавання до нативного аналізу | Binwalk / Unblob у Linux; [посібник прошивок](docs/firmware-analysis.md) |
| Пакети й ресурси | Переліки файлів, хеші, plist, структура пакетів Apple та видобуті ресурси | [Посібник артефактів і JavaScript](docs/javascript-artifact-reconstruction.md), [застосунки Apple](docs/apple-application-analysis.md) |
| Поведінка процесів | Вивід термінала, взаємодії, спостереження за завершенням і файловою системою та порівняння запусків | Linux/macOS із нативним PTY; [захоплення процесів](docs/process-capture.md) |
Статична перевірка JavaScript і .NET читає надані файли, не запускаючи застосунок. Захоплення під час виконання запускає вибрану ціль або взаємодіє з нею з правами вашого користувача; відповідні посібники описують його вплив.
<a id="choosing-a-deep-analysis-provider"></a>
Нативні формати й підтримка систем відрізняються залежно від провайдера. Дивіться [налаштування Hopper і Ghidra](docs/installation.md#hopper), [посібник IDA](docs/ida-provider.md) та [експериментальну підтримку Ghidra у Windows](docs/windows-ghidra-p0.md). Ghidra також підтримує [аналіз 16-бітного DOS](docs/ghidra-dos.md). Для вибору провайдера дивіться [посібник CLI](docs/cli.md#choose-a-provider). Для функцій, доданих після найновішої версії в npm, перевірте [доступність у випусках](docs/installation.md#released-package-and-main).
## Приклади
[](https://rea.tools/showcase/)
### DX-Ball: відновлення розрахунку звукової панорами
Простежте звуковий виклик до допоміжної функції, що перетворює координату на панорамування, перевірте інструкції та перетворіть неповний псевдокод на C. Відновлена реалізація проходить 3 205 тестів з оригінальним x86-кодом і відтворює всі 63 байти скомпільованої функції.
### Notion: відстеження мосту буфера обміну Electron
Знайдіть API буфера обміну в процесі рендерингу, простежте його через preload та IPC до головного процесу й перевірте формат буфера обміну з даними форматування.
### TH04: відновлення розрахунку кільця куль у DOS
Перевірте 16-бітні інструкції оригінальної гри для PC-98, відновіть розрахунки фіксованих і прицільних кутів та порівняйте відновлений C++ із виводом тогочасного компілятора.
Якщо ви дослідили з REA щось цікаве, поділіться результатом. Створіть [issue](https://github.com/morluto/rea/issues) або [pull request](https://github.com/morluto/rea/pulls) і вкажіть ціль, ваше запитання, як допоміг REA та що ви з'ясували.
## Поширені запитання
<details>
<summary><strong>Які агенти можуть використовувати REA?</strong></summary>
Будь-який агент, що підтримує локальні MCP-сервери. Налаштування конфігурує [підтримуваних агентів](docs/installation.md#supported-agents); інші клієнти можуть використати [ручну реєстрацію MCP](docs/installation.md#mcp-registry).
</details>
<details>
<summary><strong>Чи потрібні мені Hopper, Ghidra або IDA?</strong></summary>
Поглиблений нативний аналіз використовує один із цих інструментів. Статична перевірка JavaScript і .NET працює без рушія нативного аналізу. Налаштування може встановити Hopper після схвалення; Ghidra й IDA використовують наявні встановлення. Дивіться [налаштування провайдерів](docs/installation.md#hopper).
</details>
<details>
<summary><strong>Чи потрібно спочатку запускати Hopper?</strong></summary>
REA запускає Hopper, коли він потрібен для операції. У macOS під час першого запуску може з'явитися діалог вибору деморежиму або активації ліцензії. Дивіться [запуск Hopper та усунення неполадок](docs/installation.md#launcher-paths-and-troubleshooting).
</details>
<details>
<summary><strong>Що дає встановлення skill із skills.sh?</strong></summary>
Skill надає агенту інструкції дослідження. Використовуйте `npx rea-agents setup`, щоб зареєструвати MCP-сервер REA та встановити відповідні інструкції, а потім перезапустіть агента. Дивіться [встановлення лише skill](docs/installation.md#skill-only-installation).
</details>
<details>
<summary><strong>Який код повертає REA?</strong></summary>
Нативний аналіз повертає псевдокод і асемблерний код. Аналіз JavaScript/Electron відновлює модулі та їхні зв'язки. Агент використовує ці результати, щоб написати й протестувати реалізацію; [приклади](#приклади) містять практичні дослідження.
</details>
<details>
<summary><strong>Чи завантажує REA мій застосунок на сервер?</strong></summary>
REA аналізує цілі локально. Ваш агент отримує результати інструментів, а постачальник його моделі має власну політику даних.
</details>
<details>
<summary><strong>Що робити, якщо я зіткнувся з помилкою?</strong></summary>
Спочатку оновіться: нещодавній випуск уже міг виправити помилку.
Для CLI, встановленого через npm:
```bash
rea update
```
Для налаштування агента через `npx`:
```bash
npx rea-agents@latest setup
```
Якщо використовуєте агента, завершіть [оновлення налаштувань](#оновіть-rea) і перезапустіть його. Повторіть те саме завдання. Якщо проблема залишається, [відкрийте issue](https://github.com/morluto/rea/issues) із версією REA, типом цілі, кроками відтворення та виводом помилки.
</details>
## Документація
Почніть із [практичних посібників](https://rea.tools/guides/) на сайті. Точні параметри, передумови й контракти результатів описано тут:
- [Встановлення й налаштування](docs/installation.md): реєстрація агентів, конфігурація провайдерів, оновлення та видалення.
- [Готовність та усунення неполадок](docs/installation.md#check-readiness-for-your-task): діагностика конкретного агента або рушія аналізу.
- [CLI та Evidence](docs/cli.md): команди, вибір провайдера, знімки, імпорт/експорт і статуси завершення.
- [Контракти MCP](docs/mcp-contracts.md) і [промпти агентів](docs/mcp-prompts.md): результати інструментів, сеанси й керовані дослідження.
- [Каталог інструментів](docs/mcp-contracts.md#generated-catalog): створюваний під час збірки перелік інструментів, провайдерів і команд CLI.
- [План розвитку](docs/roadmap.md): заплановані роботи й відстеження можливостей.
Повідомляйте про вразливості згідно з [SECURITY.md](SECURITY.md).
## Історія зірок
🎉 **40 000 зірок на GitHub — дякуємо!**
Дякуємо всім, хто використовує REA, повідомляє про помилки, пропонує нові функції, тестує збірки й допомагає з виправленнями.
<img alt="Історія зірок REA на GitHub" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
</picture>
</a>
## Відмова від відповідальності
REA надає інструменти для законних досліджень, аналізу й реконструкції за допомогою реверс-інжинірингу. Ви відповідаєте за отримання необхідних дозволів і дотримання застосовних законів. Проєкт не підтримує незаконне або несанкціоноване використання.
## Участь у проєкті
Будемо раді вашій допомозі з REA! [Відкрийте issue](https://github.com/morluto/rea/issues), щоб повідомити про помилку чи запропонувати функцію, або [надішліть pull request](https://github.com/morluto/rea/pulls) з поліпшеннями коду чи документації.
Налаштування середовища розробки й перевірки описано в [CONTRIBUTING.md](CONTRIBUTING.md), шляхи верифікації — у [посібнику тестування](docs/testing.md), а структуру проєкту — на [схемі архітектури](docs/architecture.mermaid).
[Bắt đầu nhanh](#bắt-đầu-nhanh) · [Cách REA hoạt động](#cách-rea-hoạt-động) · [Những gì bạn có thể phân tích](#những-gì-bạn-có-thể-phân-tích) · [Các nghiên cứu điển hình](#các-nghiên-cứu-điển-hình) · [Câu hỏi thường gặp](#câu-hỏi-thường-gặp) · [Tài liệu](#tài-liệu)
<code>npx rea-agents setup</code>
<br />
<img src="docs/assets/rea-hopper-analysis.png" alt="REA khởi chạy cầu nối phân tích bên trong Hopper khi kiểm tra tệp nhị phân mã máy" width="1200" />
<strong>Tham gia cộng đồng kỹ thuật dịch ngược</strong>
</a><br />
<sub>Discord · Hỏi đáp · Chia sẻ kết quả</sub>
</td>
</tr>
</table>
<br />
</div>
---
Bạn thấy một tính năng trong ứng dụng và muốn đưa nó vào sản phẩm của mình? Hãy nhờ tác nhân của bạn điều tra bằng REA. Tác nhân có thể kiểm tra ứng dụng mà không cần mã nguồn, giải thích cách tính năng hoạt động, đưa ra bằng chứng và xây dựng một phiên bản cho dự án của bạn.
REA kết nối tác nhân của bạn với các công cụ kiểm tra tệp nhị phân mã máy, ứng dụng JavaScript và Electron, assembly .NET và trang web. Bạn cũng có thể dùng các công cụ đó từ terminal. Việc phân tích chạy cục bộ; kết quả bao gồm bằng chứng và giới hạn làm cơ sở cho từng kết luận.
Quá trình thiết lập đăng ký REA với tác nhân và cài đặt các hướng dẫn quy trình tương ứng. Phân tích mã máy có thể sử dụng Hopper hoặc Ghidra đã cài sẵn; quá trình thiết lập cũng có thể cài Hopper nếu bạn chấp thuận. Phân tích tĩnh JavaScript không cần công cụ nào trong hai công cụ này.
> **[Truy cập trang web REA](https://rea.tools/)** để xem cách thiết lập, hướng dẫn có hình minh họa và các nghiên cứu điển hình thực tế.
## Bắt đầu nhanh
### Thiết lập tác nhân
Sau khi cài Node.js và npm, chạy:
```bash
npx rea-agents setup
```
Chọn các tác nhân, xem lại những thay đổi được đề xuất và chấp thuận. Quá trình thiết lập thêm máy chủ MCP của REA cùng hướng dẫn quy trình tương ứng, đồng thời sao lưu cấu hình hiện có. Sau đó khởi động lại tác nhân.
Quá trình thiết lập hỗ trợ Claude Code, Codex, Cursor, Gemini CLI, Grok Build và [các tác nhân khác](docs/installation.md#supported-agents). Xem [cài đặt và thiết lập](docs/installation.md) để cấu hình trình phân tích và đăng ký MCP thủ công.
### Hỏi tác nhân
```text
Tìm hiểu cách tính năng tìm kiếm trong ứng dụng Notes hoạt động, cho tôi xem bằng chứng và xây dựng tính năng tương tự cho dự án của tôi.
```
Thay Notes bằng ứng dụng mục tiêu và chỉ rõ tính năng bạn muốn hiểu.
### Sử dụng terminal
Kiểm tra thư mục ứng dụng JavaScript/Electron đã giải nén hoặc tệp ASAR:
Kết quả bao gồm mô-đun, các khai báo import, ranh giới Electron và bằng chứng tương ứng. Thay đường dẫn bằng mục tiêu của bạn, chẳng hạn `"D:/apps/example"` trên Windows.
Để cài lệnh `rea` cho việc sử dụng thường xuyên:
```bash
npm install --global rea-agents
rea --help
```
Để phân tích mã máy, trước tiên hãy cấu hình trình phân tích. Xem [hướng dẫn CLI và Evidence](docs/cli.md) về các lệnh phân tích mã máy, lựa chọn trình phân tích, ảnh chụp trạng thái và sử dụng trong script.
### Cập nhật REA
REA thay đổi nhanh và các bản phát hành mới thường xuyên có bản sửa lỗi. Hãy giữ bản cài đặt của bạn được cập nhật.
Với CLI được cài bằng npm:
```bash
rea update
```
Để cập nhật đăng ký tác nhân và skill, chạy lệnh thiết lập được in ra sau khi cập nhật.
Nếu dùng `npx`, cập nhật thiết lập tác nhân bằng:
```bash
npx rea-agents@latest setup
```
Xem lại thay đổi cấu hình và khởi động lại tác nhân. Với lệnh CLI dùng một lần, dùng `npx rea-agents@latest` rồi thêm lệnh cần chạy.
## Cách REA hoạt động
Tác nhân gọi REA qua MCP để kiểm tra mục tiêu và lần theo mã liên quan. REA trả về các phát hiện kèm bằng chứng. Tác nhân dùng chúng để đặt câu hỏi tiếp theo, giải thích hành vi hoặc viết và kiểm thử một cách triển khai. Các lệnh CLI sử dụng cùng quy trình.
[Mở hình ở kích thước đầy đủ](website/public/assets/figures/rea-investigation-flow.svg).
<a id="current-status"></a>
## Những gì bạn có thể phân tích
REA yêu cầu Node.js 22.x (>=22.19), 24.x (>=24.11) hoặc 26+, cùng với npm. Công cụ bổ sung và nền tảng chạy REA được hỗ trợ tùy thuộc vào mục tiêu:
| Mục tiêu | REA trả về gì | Yêu cầu và hướng dẫn |
| Tệp nhị phân mã máy | Mã giả, hợp ngữ, chuỗi, ký hiệu, lời gọi và tham chiếu | Hopper, Ghidra hoặc IDA; [phân tích mã máy](https://rea.tools/guides/native/) |
| Bố cục ELF ngoại tuyến | Các section, segment, ký hiệu/thông tin tái định vị gốc và các biện pháp giảm thiểu có thể có từ phân tích tĩnh | pwntools do bên gọi cung cấp trên Linux x64; [chẩn đoán tệp nhị phân](docs/binary-diagnostics.md) |
| Bytecode EVM | Bộ chọn điều phối, độ lệch byte, tham số suy luận và khả năng thay đổi trạng thái | Đầu vào cục bộ chứa byte thô hoặc dạng thập lục phân; [hướng dẫn EVM ngoại tuyến](docs/evm-bytecode.md) |
| Sự cố Linux đã ghi lại | Bản ghi note thô, thanh ghi/tín hiệu của mọi luồng được ghi lại và các ứng viên ánh xạ tùy chọn | pwntools do bên gọi cung cấp; GDB/pwndbg tùy chọn; [sự cố đã ghi lại](docs/recorded-crashes.md) |
| JavaScript / Electron | Mô-đun, các khai báo import, source map, tuyến, IPC và quan hệ với tiện ích mở rộng mã máy | Node.js và npm; [phân tích ứng dụng](https://rea.tools/guides/javascript/) |
| Trang web | Cấu trúc trang, script, quan sát mạng và ảnh chụp màn hình được yêu cầu | Trình duyệt thuộc họ Chrome; [phân tích trình duyệt](https://rea.tools/guides/browser/) |
| Bản ghi lưu lượng mạng đã lưu | Yêu cầu, phản hồi, payload có thể truy cập và vị trí nguồn | HAR; mitmdump trên Linux cho bản ghi định dạng gốc của mitmproxy; [hướng dẫn bản ghi mạng](docs/web-network-captures.md) |
| Assembly .NET | Siêu dữ liệu, lệnh CIL, các phụ thuộc mã máy được khai báo và so sánh bản dựng | Kiểm tra tĩnh; [hướng dẫn mã được quản lý](docs/managed-code-analysis.md) |
| APK Android | Khai báo manifest, lớp, phương thức được dịch ngược và tham chiếu | JADX không giao diện đồ họa và JDK đầy đủ trên Linux/macOS; [hướng dẫn Android](docs/android-analysis.md) |
| Phần sụn | Các vùng, kết quả trích xuất và dữ liệu chuyển sang phân tích mã máy | Binwalk / Unblob trên Linux; [hướng dẫn phần sụn](docs/firmware-analysis.md) |
| Gói và tài nguyên | Danh sách tệp, giá trị băm, plist, cấu trúc bundle Apple và tài nguyên được trích xuất | [Hướng dẫn hiện vật phần mềm và JavaScript](docs/javascript-artifact-reconstruction.md), [ứng dụng Apple](docs/apple-application-analysis.md) |
| Hành vi tiến trình | Đầu ra terminal, tương tác, quan sát khi thoát và hệ thống tệp, cùng so sánh các lần chạy | Linux/macOS có PTY gốc; [ghi lại tiến trình](docs/process-capture.md) |
Kiểm tra tĩnh JavaScript và .NET đọc các tệp được cung cấp mà không chạy ứng dụng. Ghi lại khi chạy sẽ khởi chạy hoặc tương tác với mục tiêu đã chọn bằng quyền người dùng của bạn; từng hướng dẫn mô tả tác động của nó.
<a id="choosing-a-deep-analysis-provider"></a>
Định dạng mã máy và nền tảng chạy REA được hỗ trợ khác nhau tùy trình phân tích. Xem [thiết lập Hopper và Ghidra](docs/installation.md#hopper), [hướng dẫn IDA](docs/ida-provider.md) và [hỗ trợ Ghidra thử nghiệm trên Windows](docs/windows-ghidra-p0.md). Ghidra cũng hỗ trợ [phân tích DOS 16 bit](docs/ghidra-dos.md). Để chọn trình phân tích, xem [hướng dẫn CLI](docs/cli.md#choose-a-provider). Kiểm tra [khả năng sử dụng theo bản phát hành](docs/installation.md#released-package-and-main) đối với tính năng được bổ sung sau phiên bản npm mới nhất.
## Các nghiên cứu điển hình
[](https://rea.tools/showcase/)
### DX-Ball: tái tạo phép tính phân bố âm thanh trái phải
Lần theo lời gọi âm thanh đến hàm hỗ trợ chuyển vị trí thành giá trị phân bố âm thanh, kiểm tra các lệnh và chuyển mã giả chưa đầy đủ sang C. Bản tái tạo vượt qua 3.205 trường hợp kiểm thử với x86 gốc và tái tạo đủ 63 byte của hàm đã biên dịch.
### Notion: lần theo cầu nối clipboard của Electron
Tìm API clipboard trong tiến trình kết xuất, lần theo qua preload và IPC đến tiến trình chính, rồi kiểm tra định dạng clipboard có dữ liệu định dạng phong phú.
Kiểm tra các lệnh 16 bit của trò chơi PC-98 gốc, khôi phục phép tính góc cố định và góc nhắm mục tiêu, rồi so sánh C++ được tái tạo với đầu ra của trình biên dịch thời đó.
Nếu bạn dùng REA cho một mục tiêu thú vị, chúng tôi muốn biết. Chia sẻ trường hợp của bạn qua [issue](https://github.com/morluto/rea/issues) hoặc [pull request](https://github.com/morluto/rea/pulls), nêu mục tiêu, câu hỏi, cách REA giúp bạn và những gì tìm được.
## Câu hỏi thường gặp
<details>
<summary><strong>Tác nhân nào có thể dùng REA?</strong></summary>
Bất kỳ tác nhân nào hỗ trợ máy chủ MCP cục bộ. Quá trình thiết lập cấu hình các [tác nhân được hỗ trợ](docs/installation.md#supported-agents); ứng dụng khách khác có thể dùng [đăng ký MCP thủ công](docs/installation.md#mcp-registry).
</details>
<details>
<summary><strong>Tôi có cần Hopper, Ghidra hoặc IDA không?</strong></summary>
Phân tích mã máy chuyên sâu sử dụng một trong những công cụ đó. Kiểm tra tĩnh JavaScript và .NET hoạt động mà không cần bộ máy phân tích mã máy. Quá trình thiết lập có thể cài Hopper sau khi được chấp thuận; Ghidra và IDA dùng bản cài đặt sẵn có. Xem [thiết lập trình phân tích](docs/installation.md#hopper).
</details>
<details>
<summary><strong>Tôi có cần khởi chạy Hopper trước không?</strong></summary>
REA khởi chạy Hopper khi một thao tác cần đến nó. Trên macOS, hộp thoại lần chạy đầu có thể yêu cầu chọn chế độ dùng thử hoặc kích hoạt giấy phép. Xem [khởi động Hopper và khắc phục sự cố](docs/installation.md#launcher-paths-and-troubleshooting).
</details>
<details>
<summary><strong>Cài skill từ skills.sh có tác dụng gì?</strong></summary>
Skill cung cấp hướng dẫn điều tra cho tác nhân. Dùng `npx rea-agents setup` để đăng ký máy chủ MCP của REA và cài hướng dẫn tương ứng, sau đó khởi động lại tác nhân. Xem [chỉ cài skill](docs/installation.md#skill-only-installation).
</details>
<details>
<summary><strong>REA trả về mã gì?</strong></summary>
Phân tích mã máy trả về mã giả và hợp ngữ. Phân tích JavaScript/Electron khôi phục mô-đun cùng quan hệ giữa chúng. Tác nhân dùng các phát hiện này để viết và kiểm thử cách triển khai; các [nghiên cứu điển hình](#các-nghiên-cứu-điển-hình) cung cấp ví dụ thực hành.
</details>
<details>
<summary><strong>REA có tải ứng dụng của tôi lên không?</strong></summary>
REA phân tích mục tiêu cục bộ. Tác nhân nhận kết quả công cụ, và nhà cung cấp mô hình của tác nhân có chính sách dữ liệu riêng.
</details>
<details>
<summary><strong>Tôi nên làm gì khi gặp lỗi?</strong></summary>
Hãy cập nhật trước; một bản phát hành gần đây có thể đã sửa lỗi.
Với CLI được cài bằng npm:
```bash
rea update
```
Với thiết lập tác nhân qua `npx`:
```bash
npx rea-agents@latest setup
```
Nếu dùng tác nhân, hãy hoàn tất [làm mới thiết lập](#cập-nhật-rea) và khởi động lại nó. Thử lại cùng tác vụ. Nếu vấn đề vẫn còn, [mở issue](https://github.com/morluto/rea/issues) với phiên bản REA, loại mục tiêu, các bước tái hiện và đầu ra lỗi.
</details>
## Tài liệu
Bắt đầu với [hướng dẫn thực hành](https://rea.tools/guides/) trên trang web. Để biết tùy chọn cụ thể, điều kiện tiên quyết và hợp đồng kết quả:
- [Cài đặt và thiết lập](docs/installation.md): đăng ký tác nhân, cấu hình trình phân tích, cập nhật và gỡ cài đặt.
- [Kiểm tra mức sẵn sàng và khắc phục sự cố](docs/installation.md#check-readiness-for-your-task): chẩn đoán một tác nhân hoặc bộ máy phân tích cụ thể.
- [CLI và Evidence](docs/cli.md): lệnh, lựa chọn trình phân tích, ảnh chụp trạng thái, nhập/xuất và trạng thái thoát.
- [Hợp đồng MCP](docs/mcp-contracts.md) và [prompt cho tác nhân](docs/mcp-prompts.md): kết quả công cụ, phiên làm việc và điều tra có hướng dẫn.
- [Danh mục công cụ](docs/mcp-contracts.md#generated-catalog): danh sách công cụ, trình phân tích và lệnh CLI được tạo khi dựng dự án.
- [Lộ trình](docs/roadmap.md): công việc dự kiến và theo dõi các khả năng.
Báo cáo lỗ hổng theo [SECURITY.md](SECURITY.md).
## Lịch sử sao
🎉 **40.000 sao trên GitHub — xin cảm ơn!**
Cảm ơn mọi người đã sử dụng REA, báo lỗi, đề xuất tính năng, kiểm thử bản dựng và đóng góp bản sửa lỗi.
<img alt="Lịch sử sao GitHub của REA" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
</picture>
</a>
## Miễn trừ trách nhiệm
REA cung cấp công cụ cho nghiên cứu dịch ngược, phân tích và tái tạo hợp pháp. Bạn có trách nhiệm có được các quyền cho phép cần thiết và tuân thủ luật áp dụng. Dự án không ủng hộ việc sử dụng trái pháp luật hoặc không được cho phép.
## Đóng góp
Chúng tôi hoan nghênh bạn giúp phát triển REA! [Mở issue](https://github.com/morluto/rea/issues) để báo lỗi hoặc đề xuất tính năng, hoặc [gửi pull request](https://github.com/morluto/rea/pulls) để cải thiện mã hay tài liệu.
Xem [CONTRIBUTING.md](CONTRIBUTING.md) về thiết lập môi trường phát triển và các bước kiểm tra, [hướng dẫn kiểm thử](docs/testing.md) về các luồng xác minh và [sơ đồ kiến trúc](docs/architecture.mermaid) về cấu trúc dự án.
在應用中看到一個想加入自己產品的功能？讓 AI 代理用 REA 調查它。即使沒有原始碼，AI 代理也可以檢查應用、解釋功能的工作方式、展示證據，並為你的專案實現類似功能。
REA 將 AI 代理連接到分析工具，用於檢查原生二進位檔案、JavaScript 和 Electron 應用、.NET 程式集以及網站。你也可以在終端中使用同樣的工具。分析在本機執行，結果包含支撐各項結論的證據和相關限制。
設定流程會向 AI 代理註冊 REA，並安裝對應的工作流程指引。原生分析可以使用已有的 Hopper 或 Ghidra；設定流程也可以在你核准後安裝 Hopper。靜態 JavaScript 分析不需要這兩個引擎。
> **[訪問 REA 網站](https://rea.tools/)**，查看設定說明、圖解指南和真實案例。
## 快速開始
### 設定 AI 代理
安裝 Node.js 和 npm 後，執行：
```bash
npx rea-agents setup
```
選擇 AI 代理，檢查計劃中的變更並核准。設定流程會添加 REA 的 MCP 服務和對應的工作流程指引，並備份已有組態。完成後重新啟動 AI 代理。
設定流程支援 Claude Code、Codex、Cursor、Gemini CLI、Grok Build 和[其他 AI 代理](docs/installation.md#supported-agents)。提供者組態和手動註冊 MCP 的方法見[安裝與設定](docs/installation.md)。
@@ -6,14 +6,42 @@ Security fixes are provided for the latest published version of REA. Upgrade to
## Reporting a vulnerability
Do not disclose vulnerabilities, proof-of-concept exploits, credentials, private binaries, or Hopper documents in a public issue.
Do not disclose vulnerabilities, proof-of-concept exploits, credentials,
private binaries, Hopper documents, or private Ghidra projects in a public
issue.
Use **Report a vulnerability** in the repository's **Security** tab to submit the report privately. Do not open a public issue to request a private contact channel.
Include the affected REA version, macOS and Hopper versions, impact, reproduction conditions, and any suggested mitigation in the private report. Remove credentials, proprietary binaries, Hopper documents, socket capability tokens, and unrelated local paths from logs or examples.
Include the affected REA version, operating system/distribution, selected
provider and version, impact, reproduction conditions, and any suggested
mitigation in the private report. Remove credentials, proprietary binaries,
Hopper documents, Ghidra project contents, socket capability tokens, and
unrelated local paths from logs or examples.
The maintainer will acknowledge the report, assess its scope, and coordinate remediation and disclosure timing with the reporter. Please allow time for Hopper-dependent behavior to be reproduced safely.
The maintainer will acknowledge the report, assess its scope, and coordinate
remediation and disclosure timing with the reporter. Please allow time for
provider-dependent behavior to be reproduced safely.
## Security boundary
REA authenticates each local bridge session with a random capability token and a current-user Unix socket. This is not a sandbox and does not protect against malicious processes already running as the same macOS user. Opening an untrusted binary delegates parsing and analysis to Hopper with that user's permissions.
REA authenticates each local provider bridge session with a random capability
token and a current-user Unix socket. Tokens are transferred through private
session descriptors rather than process arguments or environment variables.
This is not a sandbox and does not protect against malicious processes already
running as the same operating-system user. Opening an untrusted binary
delegates parsing and analysis to the selected local provider with that user's
permissions.
Ghidra sessions use a packaged Java `HeadlessScript`, an isolated temporary
project, and private home, cache, and runtime directories. REA imports only the
requested target, bounds startup and protocol messages, requests bounded CPU
and heap settings, and deletes the temporary project when the session closes.
These controls limit accidental persistence and resource use; they do not make
Ghidra a sandbox. REA does not open or modify user-owned Ghidra projects.
`GHIDRA_INSTALL_DIR` and optional `JAVA_HOME` identify user-managed
installations. Setup can add those values to detected client configuration only
after showing its plan and receiving approval. REA does not download, install,
upgrade, or modify Ghidra or Java.
On Linux, REA accepts release metadata only from Hopper's HTTPS endpoint, restricts package URLs to Hopper's public download origin, bounds the package size, and compares the downloaded bytes with Hopper's published checksum before requesting installation. The published SHA-1 value is a corruption check, not a modern package signature; HTTPS origin validation remains part of the trust boundary. Dependency installation is delegated without shell evaluation to `apt-get`, `dnf`, or `pacman`, directly as root or through `pkexec`. REA never invokes `sudo`.
log.appendMsg("REA","Preserved pre-recovery calling conventions; new functions use the loaded compiler specification default. Original method signatures remain unknown.");
limitations.add("Recovery covers the reported metadata candidates; it does not reconstruct original C# source, custom field layouts, every runtime object, or execution behavior.");
limitations.add("Method prototypes and parameter names remain Ghidra inferences; verify them against instructions and call sites. Pre-recovery conventions are retained rather than universally forcing __thiscall.");
limitations.add("NativeAOT type identities and relationships are inferred; generated names are not original names. Derived memory has no original file offsets.");
summary.add("limitations",limitations);
returnsummary;
}
/** Read recovered relationships without restoring or mutating database state. */
limitations.add("Type identities and relationships are recovered by upstream heuristics. Original source names and custom field layouts are not recovered.");
limitations.add("Method prototypes are inferred, not original signatures. REA preserves pre-recovery calling conventions and the loaded compiler default for new functions.");
limitations.add("Rehydrated metadata bytes are derived analysis-memory content; their original file offsets and runtime behavior remain unknown.");
limitations.add("Verified workflow: .NET 8.0.22 NativeAOT RTR 9.1, Linux x64 ELF / Windows x64 PE on Linux; other runtime layouts and hosts are unverified.");
raiseCaptureFailure("format","Malformed native record at byte offset "+str(start)+".")fromNone
ifnotisinstance(state,dict):
raiseCaptureFailure("format","Native flow record must be a dictionary at byte offset "+str(start)+".")
records.append({"ordinal":len(records),"location":{"kind":"byte-range","offset":start,"bytes":handle.tell()-start},**project_record(state,request["sensitive_values"]),"limitations":["Fields are original native states without FlowReader migration. Binary fields contain exact producer bytes; reported UTF-8 strings for those fields are derived display views. Unknown flow/version extensions are retained without interpretation."]})
tryfail("screen-recording-denied","Grant Screen Recording to the REA host in System Settings > Privacy & Security, then retry; no broad capture fallback is used")
}
varselected:AXUIElement?
ifrequest.accessibility||request.action!=nil{
guardAXIsProcessTrusted()else{tryfail("accessibility-denied","Grant Accessibility to the REA host in System Settings > Privacy & Security, then retry")}
letitem=(selectedChildas?[AXUIElement])?.firstelse{tryfail("element-missing","Selected accessibility path no longer exists")}
element=item
}
varowner:pid_t=0
guardAXUIElementGetPid(element,&owner)==.success&&owner==request.pidelse{tryfail("element-owner-mismatch","Selected element belongs to another process")}
tryfail("capture-window-missing","Selected window disappeared before capture")
}
guardbounds.width>0&&bounds.height>0&&bounds.width<=100000&&bounds.height<=100000else{tryfail("window-bounds","Selected window has invalid or oversized geometry")}
return["window":["pid":request.pid,"window_id":request.window_id,"executable":request.executable,"launch_time":launch,"title":window[kCGWindowNameasString]as?String??""],"nodes":nodes,"truncated":truncated,"screenshot":screenshot,"gaps":request.accessibility?gaps:["Accessibility capture was disabled"]]
reply={"ok":False,"reason":"resource-limit","message":"pwntools memory allocation failed under the effective resource limits; the exact allocation cause is unknown.","reported_limits":limits}
exceptExceptionaserror:
ifisinstance(error,OSError)anderror.errno==12:
memory_reserve=None
reply={"ok":False,"reason":"resource-limit","message":"pwntools reported OSError(ENOMEM); the exact allocation cause is unknown.","reported_limits":limits}
raiseLayoutFailure("format",f"ELF SHN_XINDEX resolves to ordinary index {section_name_index}; the escape requires an index at least SHN_LORESERVE (0xff00).")
ifsection_name_index!=0:
ifsection_name_index>=section_count:
raiseLayoutFailure("format",f"ELF section-name table index {section_name_index} lies outside the declared section count {section_count}.")
"index":index,"name":name_reference(section.name,shstrings,h.sh_name,content)ifshstringsisnotNoneelse{"display":"","bytes_base64":None,"location":None,"unknown_reason":"ELF declares no section-name table (SHN_UNDEF index 0)."},"name_offset":address(h.sh_name),"type":h.sh_type,
"PT_NULL payload fields are unused and retain their reported numbers without file-byte or permission claims. Zero-file-size segments provide no file bytes.",
"SHN_XINDEX symbol values remain unresolved in this upstream representation; an external index table does not establish a resolved index in this report.",
"Reported values preserve linked addresses, section offsets, TLS offsets, alignment and absolute values separately. Runtime load base and library paths are unknown.",
"Names are display strings plus raw bytes and file ranges where resolvable; section/table/entry indices preserve identity and duplicates. Name ranges include their terminating NUL; raw name bytes exclude it.",
"Ordinary relocation rows cover REL/RELA. RELR tables retain complete encoded bytes and upstream-decoded offsets as derived evidence; per-offset packed-word locations and implicit addends remain unknown. Relocation inventory completeness is unknown, including other encodings and missing section tables.",
"Relocation symbol index zero uses a zero symbol value without a table lookup. Positive indices reference validated original symbol-table entries; raw table and symbol indices remain reported.",
"Relocatable relocation targets with SHN_UNDEF or inactive SHT_NULL headers retain their reported section index/offset as unknown; they do not establish an associated target section.",
"GOT/PLT are derived upstream convenience maps; PLT inference can emulate selected instructions in Unicorn. They do not establish target runtime behavior; aliases may collapse and warnings may indicate incomplete coverage. Their completeness is unknown.",
"Mitigations are upstream static heuristics, not runtime protection. ET_DYN does not prove an executable; absent canary symbols do not prove every function unprotected.",
"This profile inspects ELF EXEC/DYN/REL layout only. It does not analyze recorded cores, resolve loaded libraries, launch the target as a host process or start a debugger.",
"Symbol/relocation inventories reflect original section tables. A sectionless image can still report dynamic dependency names; missing tables do not prove absence of dynamic symbols or relocations.",
*(["Absent section-name table: section-dependent RELRO/canary heuristics may be incomplete; protection coverage is unknown."]ifall_sectionsandsection_name_index==0else[]),
*(["Sectionless images lack the .dynamic section and symbol tables used by upstream heuristics. RELRO/canary indicators may be incomplete; their values remain reported static candidates, with protection coverage unknown."]ifnotall_sectionselse[]),
raiseCoreFailure("format","Selected ELF64 core header is truncated.")
ifcontent[6]!=1:
raiseCoreFailure("format","ELF identification version is not EV_CURRENT.")
ifint.from_bytes(content[20:24],"little")!=1:
raiseCoreFailure("format","ELF header version is not EV_CURRENT.")
# Linux commonly emits ELFOSABI_NONE (0), also accepted as GNU/Linux (3).
# Other declared OSABIs must never select Linux note ctypes.
ifcontent[7]notin(0,3)orcontent[8]!=0:
raiseCoreFailure("unsupported-target","Initial recorded-core profile requires System V or GNU/Linux OSABI with ABI version zero; selected OSABI="+str(content[7])+", ABI version="+str(content[8])+".")
"limitations":["The initial Linux note profile accepts System V/unspecified or GNU/Linux OSABI with ABI version zero; an unspecified OSABI alone does not prove operating-system origin.",
"Historical PID and signal values are recorded metadata, not current process identity or attach authority.",
"Only exact Linux CORE NT_PRSTATUS/NT_SIGINFO owners are interpreted; every descriptor and owner retains original bytes. Other note semantics remain unknown.",
"NT_SIGINFO thread association is unknown. Only SIGSEGV SEGV_MAPERR/SEGV_ACCERR initially establish a fault-address union meaning.",
"PT_LOAD file bytes are recorded bytes. Undumped memory and current executable/library identity remain unknown; no current host file is resolved from a recorded pathname.",
"Missing notes/registers/signals do not establish their absence at the original crash. Full unwinding, executable pairing and live control are not provided."]}
window.translations={"copy":"Copy","copied":"Copied!","normally_hidden":"This member is normally hidden due to your filter settings.","hierarchy_expand":"Expand","hierarchy_collapse":"Collapse","folder":"Folder","search_index_not_available":"The search index is not available","search_no_results_found_for_0":"No results found for {0}","kind_1":"Project","kind_2":"Module","kind_4":"Namespace","kind_8":"Enumeration","kind_16":"Enumeration Member","kind_32":"Variable","kind_64":"Function","kind_128":"Class","kind_256":"Interface","kind_512":"Constructor","kind_1024":"Property","kind_2048":"Method","kind_4096":"Call Signature","kind_8192":"Index Signature","kind_16384":"Constructor Signature","kind_32768":"Parameter","kind_65536":"Type Literal","kind_131072":"Type Parameter","kind_262144":"Accessor","kind_524288":"Get Signature","kind_1048576":"Set Signature","kind_2097152":"Type Alias","kind_4194304":"Reference","kind_8388608":"Document"};
(()=>{varKe=Object.create;varhe=Object.defineProperty;varGe=Object.getOwnPropertyDescriptor;varZe=Object.getOwnPropertyNames;varXe=Object.getPrototypeOf,Ye=Object.prototype.hasOwnProperty;varet=(t,e)=>()=>{try{returne||t((e={exports:{}}).exports,e),e.exports}catch(n){throwe=0,n}};vartt=(t,e,n,r)=>{if(e&&typeofe=="object"||typeofe=="function")for(letiofZe(e))!Ye.call(t,i)&&i!==n&&he(t,i,{get:()=>e[i],enumerable:!(r=Ge(e,i))||r.enumerable});returnt};varnt=(t,e,n)=>(n=t!=null?Ke(Xe(t)):{},tt(e||!t||!t.__esModule?he(n,"default",{value:t,enumerable:!0}):n,t));varye=et((me,ge)=>{(function(){vart=function(e){varn=newt.Builder;returnn.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),n.searchPipeline.add(t.stemmer),e.call(n,n),n.build()};t.version="2.3.9";t.utils={},t.utils.warn=(function(e){returnfunction(n){e.console&&console.warn&&console.warn(n)}})(this),t.utils.asString=function(e){returne==null?"":e.toString()},t.utils.clone=function(e){if(e==null)returne;for(varn=Object.create(null),r=Object.keys(e),i=0;i<r.length;i++){vars=r[i],o=e[s];if(Array.isArray(o)){n[s]=o.slice();continue}if(typeofo=="string"||typeofo=="number"||typeofo=="boolean"){n[s]=o;continue}thrownewTypeError("clone is not deep and does not support nested objects")}returnn},t.FieldRef=function(e,n,r){this.docRef=e,this.fieldName=n,this._stringValue=r},t.FieldRef.joiner="/",t.FieldRef.fromString=function(e){varn=e.indexOf(t.FieldRef.joiner);if(n===-1)throw"malformed field ref string";varr=e.slice(0,n),i=e.slice(n+1);returnnewt.FieldRef(i,r,e)},t.FieldRef.prototype.toString=function(){returnthis._stringValue==null&&(this._stringValue=this.fieldName+t.FieldRef.joiner+this.docRef),this._stringValue};t.Set=function(e){if(this.elements=Object.create(null),e){this.length=e.length;for(varn=0;n<this.length;n++)this.elements[e[n]]=!0}elsethis.length=0},t.Set.complete={intersect:function(e){returne},union:function(){returnthis},contains:function(){return!0}},t.Set.empty={intersect:function(){returnthis},union:function(e){returne},contains:function(){return!1}},t.Set.prototype.contains=function(e){return!!this.elements[e]},t.Set.prototype.intersect=function(e){varn,r,i,s=[];if(e===t.Set.complete)returnthis;if(e===t.Set.empty)returne;this.length<e.length?(n=this,r=e):(n=e,r=this),i=Object.keys(n.elements);for(varo=0;o<i.length;o++){vara=i[o];ainr.elements&&s.push(a)}returnnewt.Set(s)},t.Set.prototype.union=function(e){returne===t.Set.complete?t.Set.complete:e===t.Set.empty?this:newt.Set(Object.keys(this.elements).concat(Object.keys(e.elements)))},t.idf=function(e,n){varr=0;for(variine)i!="_index"&&(r+=Object.keys(e[i]).length);vars=(n-r+.5)/(r+.5);returnMath.log(1+Math.abs(s))},t.Token=function(e,n){this.str=e||"",this.metadata=n||{}},t.Token.prototype.toString=function(){returnthis.str},t.Token.prototype.update=function(e){returnthis.str=e(this.str,this.metadata),this},t.Token.prototype.clone=function(e){returne=e||function(n){returnn},newt.Token(e(this.str,this.metadata),this.metadata)};t.tokenizer=function(e,n){if(e==null||e==null)return[];if(Array.isArray(e))returne.map(function(f){returnnewt.Token(t.utils.asString(f).toLowerCase(),t.utils.clone(n))});for(varr=e.toString().toLowerCase(),i=r.length,s=[],o=0,a=0;o<=i;o++){varc=r.charAt(o),l=o-a;if(c.match(t.tokenizer.separator)||o==i){if(l>0){vard=t.utils.clone(n)||{};d.position=[a,l],d.index=s.length,s.push(newt.Token(r.slice(a,o),d))}a=o+1}}returns},t.tokenizer.separator=/[\s\-]+/;t.Pipeline=function(){this._stack=[]},t.Pipeline.registeredFunctions=Object.create(null),t.Pipeline.registerFunction=function(e,n){ninthis.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[e.label]=e},t.Pipeline.warnIfFunctionNotRegistered=function(e){varn=e.label&&e.labelinthis.registeredFunctions;n||t.utils.warn(`Function is not registered with pipeline. This may cause problems when serialising the index.
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/application/BinarySession.ts#L27">src/application/BinarySession.ts:27</a></li></ul></aside>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/application/BinarySession.ts#L33">src/application/BinarySession.ts:33</a></li></ul></aside></div></li></ul></section></section></details>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/application/BinarySession.ts#L33">src/application/BinarySession.ts:33</a></li></ul></aside></section></section></details>
<p>Implementation of <ahref="../interfaces/application_HopperToolPort.HopperToolPort.html">HopperToolPort</a>.<ahref="../interfaces/application_HopperToolPort.HopperToolPort.html#calltool">callTool</a></p>
<ul>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/application/BinarySession.ts#L108">src/application/BinarySession.ts:108</a></li></ul></aside></div></li></ul></section>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/application/BinarySession.ts#L80">src/application/BinarySession.ts:80</a></li></ul></aside></div></li></ul></section>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/application/BinarySession.ts#L39">src/application/BinarySession.ts:39</a></li></ul></aside></div></li></ul></section>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/application/BinarySession.ts#L91">src/application/BinarySession.ts:91</a></li></ul></aside></div></li></ul></section></section></details></div>
<divclass="tsd-comment tsd-typography"><p>Composes official Hopper operations into bounded reverse-engineering tools.
Inputs are parsed again at this application boundary even though MCP normally
validates them, allowing direct callers to use the same service safely.</p>
</div></section><asideclass="tsd-sources">
<ul>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/application/EnhancedTools.ts#L29">src/application/EnhancedTools.ts:29</a></li></ul></aside>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/application/EnhancedTools.ts#L30">src/application/EnhancedTools.ts:30</a></li></ul></aside></div></li></ul></section></section></details>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/application/EnhancedTools.ts#L33">src/application/EnhancedTools.ts:33</a></li></ul></aside></div></li></ul></section></section></details></div>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/domain/errors.ts#L88">src/domain/errors.ts:88</a></li></ul></aside></div></li></ul></section></section></details>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/domain/errors.ts#L89">src/domain/errors.ts:89</a></li></ul></aside></section></section></details></div>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/domain/errors.ts#L72">src/domain/errors.ts:72</a></li></ul></aside></section></section></details></div>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/domain/errors.ts#L19">src/domain/errors.ts:19</a></li></ul></aside></div></li></ul></section></section></details>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/domain/errors.ts#L17">src/domain/errors.ts:17</a></li></ul></aside></section></section></details></div>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/domain/errors.ts#L3">src/domain/errors.ts:3</a></li></ul></aside></section></section></details></div>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/domain/errors.ts#L45">src/domain/errors.ts:45</a></li></ul></aside></div></li></ul></section></section></details>
<li>Defined in <ahref="https://github.com/morluto/rea/blob/main/src/domain/errors.ts#L45">src/domain/errors.ts:45</a></li></ul></aside></section></section></details></div>
<pclass="tsd-generator">Generated using <ahref="https://typedoc.org/"target="_blank">TypeDoc</a></p></footer>
<divclass="overlay"></div></body></html>
Loaded 100 of 2520 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
morluto
