Introducing a new way to review your PRs.

Read the announcement

morluto / rea

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

View on GitHub

27 documents · Updated Nov 20, 2026

docs / analysis-environments

Analysis environments

Analysis environments turn captured application behavior into a small surface that an engineer can transfer, serve, replay, and compare with a later application run. The environment keeps the capture as its source of truth while allowing a bounded state view to model confirmed reads and writes.

Environment model

Bounded analysis state

An analysis environment is a bounded view of a completed capture. A manifest names the tools and records that the environment may use. The parent capture supplies the recorded requests and responses, and REA accepts the pair only when both refer to the same Evidence record. (src/…/environmentSource.ts.)

The environment may use a replay-only boundary or a derived state boundary. State is available only when captured reads and writes prove enough identity, shape, timing, and response data to support it. Other calls stay recorded instead of being presented as modeled behavior. (src/…/environmentStateView.ts.)

References: src/…/environmentSource.ts• L294-375 src/…/environmentStateView.ts• L561-588

Captured target boundary

The environment exposes captured target content as data. It does not recreate application rules or content that the capture did not retain. Tool names, descriptions, values, and replay results therefore remain bounded evidence rather than instructions or proof that the target still works. (src/…/environmentTools.ts.)

State-backed serving narrows the boundary further. It serves an initial snapshot and applies only write effects confirmed by the capture. Unsupported changes remain replay-only or unavailable. (src/…/environmentStateView.ts.)

References: src/…/environmentTools.ts• L26-77 src/…/environmentStateView.ts• L567-588

Environment coverage

Environment coverage tells an investigator which reads use derived state, which reads use recorded replay, and which writes are served or withheld. It also gives a reason for each withheld write so the boundary is clear before a client relies on it. (src/…/environmentCoverageView.ts.)

Coverage describes the state prepared at startup. It does not prove that later discovery or data intake will remain within limits.

References: src/…/environmentCoverageView.ts• L55-97 src/…/environmentCoverageView.ts• L108-183

Environment lifecycle

Environment transfer flow

The transfer flow starts with a manifest and its parent capture. REA authenticates the pair, prepares the tool view, and then either writes a portable bundle or starts a local server. Both routes use the same retained records, so transfer and serving preserve one investigation boundary.

If the capture supports state, REA prepares it before serving. The resulting environment can mix state-backed calls with exact recorded replay when the state model does not cover a call.

This diagram shows how captured evidence becomes a reusable environment and how clients reach its bounded boundary.

flowchart LR
    A[Manifest] --> C[Authenticated environment source]
    B[Parent capture] --> C
    C --> D[Tool catalog]
    C --> E[Replay records]
    C --> S[Derived initial state]
    S --> W[Confirmed state writes]
    D --> F[Local environment server]
    E --> F
    S --> F
    W --> F
    C --> G[Portable bundle]
    G --> H[Revisited environment]
    F --> I[Investigation client]
    H --> I

References: src/…/AnalysisViewService.ts• L121-163 src/…/environmentManifestView.ts• L156-195 src/…/environmentStateView.ts• L561-588

Bundle construction

Bundle construction packages a supported HAR or capture Evidence with the manifest and the information needed to rebuild and start the same environment. The build can report the planned result without writing it, and it reports state coverage and capture warnings before sharing.

The export contract keeps the package source, provenance, serving definition, and a smoke task with the captured surface. The destination must be new or empty. The bundle name must work as its folder, environment ID, and service host. Credential-like names and unscannable bodies produce warnings without copying detected values into the report. (src/…/environmentBuild.ts.)

The smoke task checks transfer continuity. It checks tool discovery and one suitable recorded GET when available. It does not show that the original application still works.

See Environment bundle construction for the focused workflow.

References: src/…/environmentBuild.ts• L49-110 src/…/environmentBuild.ts• L250-420 src/…/environmentBuildReport.ts• L227-387 src/…/environmentBundle.ts• L47-77 src/…/environmentBundle.ts• L177-258 src/…/environmentExport.ts• L452-517

Environment serving

Environment serving keeps the authenticated source available through an environment card, an MCP interface, and a JSON-RPC data plane when state serving is available. The card and MCP discovery describe the same bounded tool catalog, so a client can learn the available surface before it makes a call. (src/…/environmentTools.ts.)

A replay-only server answers from retained records and exposes no state data plane. A state-backed server shares one bounded state store across its client interfaces. Confirmed writes change that store, while recorded calls keep replay semantics. The server rejects invalid protocol messages and oversized requests or replies at the boundary.

Serving validates the catalog before it binds. Non-loopback listeners require approved host names. Cancellation or listener failure ends the environment, while failed cleanup remains visible for later cleanup.

See Environment serving for the focused workflow.

References: src/…/environmentTools.ts• L26-77 src/…/environmentTools.ts• L432-612 src/…/serveEnvironment.ts• L65-89 src/…/serveEnvironment.ts• L390-645

Environment replay

Environment replay answers a tool call from the retained exchange that best matches its path and query values. It returns the recorded status and content with provenance and flags that show whether the match or body is exact and complete. A missing match is an input error, and a body that exceeds the response limit is marked as truncated.

Replay preserves captured JSON values and distinguishes empty, text, binary, redacted, and incomplete bodies. A state-backed environment answers supported reads and confirmed writes from state. Calls outside that state model use the same bounded replay selection as a replay-only environment.

See Environment replay for the focused workflow and limits.

References: src/…/environmentReplay.ts• L49-60 src/…/environmentReplay.ts• L172-410 src/…/environmentSource.ts• L53-109

Environment comparison

Environment comparison checks whether one or more later application probes agree with the transferred environment. Each probe starts from a fresh environment state. Its requests are ordered by recorded time when every record has a usable time; otherwise REA keeps capture order. Requests at other origins or without usable request lines are reported as unobserved, while a request with no response is still made because it may change later state. (src/…/environmentCompareProbe.ts.)

For each comparable request, REA matches the application path, query, and body to a served tool. It translates learned identifiers into the environment's identifiers, including collection-specific identifiers and bulk-write bodies. This prevents a re-seeded application from producing false differences when its entities use different IDs. (src/…/environmentCompare.ts, src/…/environmentCompareIds.ts.)

REA compares status and retained response content. It reports missing or extra fields, changed values, length, order, refusal, missing tools, and unmapped IDs. It can normalize only differences supported by the capture, such as learned IDs, confirmed clock formats, and confirmed generated values. Large or unobserved live bodies compare by status only and are counted in the report. (src/…/environmentCompareDiff.ts.)

The report gives agreement with and without order differences, per-tool results, per-step differences, omitted difference counts, identifier mappings, conflicts, and unobserved records. A capped difference list does not hide the total count or its categories.

References: src/…/environmentCompare.ts• L65-125 src/…/environmentCompare.ts• L320-412 src/…/environmentCompare.ts• L488-584 src/…/environmentCompareProbe.ts• L33-167 src/…/environmentCompareIds.ts• L19-143 src/…/environmentCompareDiff.ts• L29-64 src/…/environmentCompareDiff.ts• L573-645

Investigation continuity

Provenance and revisiting

An environment remains revisitable only when its manifest, parent capture, Evidence IDs, and serving package source stay together. The bundle records these links so another engineer can rebuild the same bounded view and distinguish it from a new capture.

Comparison reports retain the environment identity and each probe's Evidence identity. They also show which differences were normalized and which records could not be compared. This keeps transfer checks separate from claims that the target application remains available or unchanged.

References: src/…/environmentState.ts• L134-210 src/…/environmentBundle.ts• L186-364 src/…/environmentCompare.ts• L104-125

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep manifest tool names, route templates, query roles, record ordinals, and replay matching aligned. A comparison can otherwise call the wrong captured exchange.
  • Keep state identity, collection scope, list ownership, bulk-body translation, and write response rules aligned. Reused IDs must not cross collection boundaries.
  • Keep probe origin selection, time ordering, request-body admission, missing-response handling, and unobserved-record reasons aligned. A probe must not change state through a request that the report treats as another-origin data.
  • Keep comparison normalization tied to confirmed capture facts. Generated-looking values, clock-shaped numbers, and reordered identifiers must not become equal without proof.
  • Keep comparison limits aligned with replay limits. A truncated or unobserved live body must remain status-only and must be counted as such.
  • Keep environment identity, parent Evidence linkage, manifest rules, and bundle provenance aligned when exporting or rebuilding an environment.

Important failure modes

TriggerConsequenceGuard
A probe omits response bodies or request bodies needed for a writeREA refuses the comparison or compares the live body by status onlyCapture the response body and request body needed by the probe's methods
A probe calls another origin or has no usable request lineThe record is not sent to the environment and appears as unobservedReview probe origins and retain usable request URLs
A probe has no response for a requestThe request is made but not compared, although its later state effect may remainKeep the request in chronological replay and inspect the unobserved reason
Application and environment identifiers conflict or are reused across collectionsID translation is withheld or differences appear as unmapped or changed valuesLearn IDs from the same matched call and preserve collection scope
A body is too large, missing, redacted, or truncatedContent agreement is not proved; only supported status checks remainTreat body coverage and truncation flags as part of the result
A generated value or clock format is not confirmed by the environmentThe value is reported as a real differenceNormalize only values supported by captured write or clock rules
A list has duplicate or ambiguous identifier matchesREA avoids claiming an order match that the evidence cannot provePreserve typed literal matches and report only forced order changes
The environment manifest and capture use different Evidence identitiesREA refuses to serve, compare, or export the environmentKeep the authenticated manifest and parent capture pair together

Key files

FileWhy to read it
src/…/environmentBuild.tsConnects capture input to state preparation, coverage, warnings, and bundle planning.
src/…/environmentBundle.tsDefines the purpose, provenance, name contract, and continuity check for a portable bundle.
src/…/environmentSource.tsDefines the trusted relationship between the manifest and its parent capture.
src/…/environmentTools.tsDefines the bounded catalog and the interfaces that expose it to clients.
src/…/environmentState.tsConnects state Evidence to the tools that can use it.
src/…/environmentReplay.tsDefines recorded call selection and replay result limits.
src/…/environmentCompare.tsCoordinates probe execution and produces the environment agreement report.
src/…/environmentCompareProbe.tsDefines probe ordering, origin filtering, and unobserved records.
src/…/environmentCompareIds.tsDefines identifier learning and translation across application and environment runs.
src/…/environmentCompareDiff.tsDefines response comparison, normalization, and difference categories.
src/…/environmentStateView.tsExplains when captured reads and writes can form a bounded state view.
src/…/serveEnvironment.tsShows how the bounded source becomes a local HTTP, MCP, and optional state service.
docs/environment-bundle-and-replay.mdProvides the focused workflows for bundle construction, replay, and serving.