mirror of
https://github.com/morluto/rea.git
synced 2026-11-07 05:56:19 -10:00
test(cli): preserve cancellation oracles across main integration
This commit is contained in:
hhang committed
commit
575a10d194
1405 files changed
+116001
-18303
No files matched your search
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: reverse-engineer-anything
|
||||
description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
|
||||
description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
|
||||
metadata:
|
||||
version: "46"
|
||||
version: "49"
|
||||
---
|
||||
|
||||
# REA
|
||||
@@ -133,6 +133,9 @@ explicit path or endpoint and do not need it.
|
||||
`capture_browser_scenario` with declared actions. See
|
||||
[runtime observation](references/runtime-observation.md) for connect/launch
|
||||
and the focused follow-up browser tools.
|
||||
- Agent environment (AgentEnv bundle) of a web application: read
|
||||
[environments](references/environments.md) before recording; it records with
|
||||
`capture_browser_scenario` and writes the bundle with `export_environment_bundle`.
|
||||
- Fiddler Everywhere traffic or a native `.saz` capture: read the
|
||||
[Fiddler workflow](references/runtime-observation.md#fiddler-everywhere-traffic-debugging).
|
||||
Inspect saved SAZ with `inspect_web_network_capture` and `format: "saz"`;
|
||||
@@ -259,12 +262,38 @@ explicit path or endpoint and do not need it.
|
||||
proof the image never imported APIs through another table. Bound snapshots
|
||||
and loaded IAT contents remain unobserved. See the
|
||||
[PE import guide](https://github.com/morluto/rea/blob/main/docs/pe-imports.md).
|
||||
- PE TLS callbacks and load configuration: `inspect_pe_load_config` with the
|
||||
explicit local PE32/PE32+ file. This built-in target-free inspection requires
|
||||
no Windows SDK. Preserve callback VAs as strings with their RVA, file offset
|
||||
and section, and the size-covered security cookie, SafeSEH, CFG,
|
||||
EH-continuation and XFG fields. Guard-flag mitigation claims are inferred
|
||||
linker declarations, not proof of enforcement. A missing directory is observed
|
||||
absence of that declaration. See the
|
||||
[PE load configuration guide](https://github.com/morluto/rea/blob/main/docs/pe-load-config.md).
|
||||
- ELF note tables: `inspect_elf_notes` with the explicit local ELF32/ELF64
|
||||
file. This built-in target-free inspection requires no disassembler. Preserve
|
||||
PT_NOTE and SHT_NOTE ranges, owners, types, descriptor SHA-256, and GNU
|
||||
build-id or ABI-tag fields. A missing table is observed absence of those
|
||||
declarations, not proof the image never carried notes. See the
|
||||
[ELF notes guide](https://github.com/morluto/rea/blob/main/docs/elf-notes.md).
|
||||
- Apple `.ips` crash reports: `inspect_apple_ips` with the explicit local
|
||||
file. This built-in target-free inspection requires no Xcode, atos, or
|
||||
pwntools. Preserve first-line metadata, `bug_type` as a string, process and
|
||||
exception facts, lossless integer registers, usedImages UUIDs, and
|
||||
documented classification matches. Only `bug_type` `"309"` yields a crash
|
||||
body; other types, including `"288"` stackshots, return no crash result.
|
||||
Opened Mach-O and dSYM UUID joins remain unobserved. See the
|
||||
[Apple IPS guide](https://github.com/morluto/rea/blob/main/docs/apple-ips.md).
|
||||
- Linux kernel module metadata: `inspect_kernel_module` with the explicit local
|
||||
ELF32/ELF64 relocatable file. This built-in target-free inspection requires
|
||||
no Linux host or `modinfo`. Preserve `.modinfo` key order and duplicate keys,
|
||||
`__versions` CRC hex, section file ranges, and the appended signature
|
||||
trailer's PKCS#7 SHA-256. A missing section is observed absence when section
|
||||
names are known, not proof the module never carried that metadata.
|
||||
`struct module` is not decoded. The signature is not validated. gzip, xz, and
|
||||
zstd containers are unsupported; decompress into a separate file with an
|
||||
external codec utility, then inspect the decompressed `ET_REL` image. See the
|
||||
[kernel module guide](https://github.com/morluto/rea/blob/main/docs/kernel-modules.md).
|
||||
- CPython 3.7–3.13 `.pyc` header, nested marshal code objects and bytecode
|
||||
identity: `inspect_python_pyc` with the explicit local file. This built-in
|
||||
target-free inspection requires no Python installation. Preserve magic,
|
||||
@@ -463,6 +492,9 @@ as complete while required questions remain open.
|
||||
[references/runtime-observation.md](references/runtime-observation.md)
|
||||
- Evidence paging, comparisons, residual unknowns, and verification:
|
||||
[references/evidence-workflows.md](references/evidence-workflows.md)
|
||||
- Agent environments (AgentEnv bundles) of a web application, recorded from
|
||||
a live instance or a HAR:
|
||||
[references/environments.md](references/environments.md)
|
||||
|
||||
## Finish the task
|
||||
|
||||
|
||||
@@ -0,0 +1,216 @@
|
||||
# Agent environments from a live application
|
||||
|
||||
Use this when the user asks for an agent environment (an AgentEnv bundle) of a
|
||||
web application: a folder `agent-env` deploys, whose MCP tools answer from what
|
||||
one recording of the application observed and serve the writes that recording
|
||||
confirmed. The workflow records the application once with
|
||||
`capture_browser_scenario`, checks what the environment would serve, records
|
||||
again if a hint names a gap, then writes the bundle with
|
||||
`export_environment_bundle`. For a HAR the user already has, skip to
|
||||
[export](#export-and-hand-off) through `inspect_web_network_capture`, or use
|
||||
`rea environment-build <capture.har> <dir>`.
|
||||
|
||||
## Before recording
|
||||
|
||||
- Record only against an instance the user says is disposable or seeded for
|
||||
this purpose: every write step creates, edits or deletes its data. If the
|
||||
user has not said so, ask before any scenario that writes. REA does not
|
||||
start, seed or reset applications.
|
||||
- Credentials come from environment variables the user names. Declare each as a
|
||||
scenario secret, `{secret_id, environment_variable}`; the variable must be set
|
||||
in the environment REA's MCP server started with. Never ask for a password in
|
||||
chat. Declared secrets are redacted as the capture records.
|
||||
- Map the application first with `inspect_web_page` (and `capture_web_screenshot`
|
||||
when layout matters): the login form's locators, and the API calls behind the
|
||||
pages that list and edit the entities the user asked about.
|
||||
|
||||
## Record a session an environment can learn writes from
|
||||
|
||||
One `capture_browser_scenario` records the whole session. Start from this
|
||||
shape, with the application's own locators, paths and headers:
|
||||
|
||||
```json
|
||||
{
|
||||
"browser": { "mode": "launch", "executable_path": "/usr/bin/chromium" },
|
||||
"start_url": { "url": "http://127.0.0.1:3000/login" },
|
||||
"secrets": [
|
||||
{ "secret_id": "admin_password", "environment_variable": "APP_PASSWORD" }
|
||||
],
|
||||
"capture": {
|
||||
"network": {
|
||||
"request_body": true,
|
||||
"response_body": true,
|
||||
"header_values": true
|
||||
}
|
||||
},
|
||||
"actions": [
|
||||
{
|
||||
"step_id": "user",
|
||||
"action": "fill",
|
||||
"timeout_ms": 15000,
|
||||
"locator": { "kind": "css", "selector": "input[name=username]" },
|
||||
"value": { "source": "literal", "value": "admin" }
|
||||
},
|
||||
{
|
||||
"step_id": "password",
|
||||
"action": "fill",
|
||||
"timeout_ms": 15000,
|
||||
"locator": { "kind": "css", "selector": "input[name=password]" },
|
||||
"value": { "source": "secret", "secret_id": "admin_password" }
|
||||
},
|
||||
{
|
||||
"step_id": "sign-in",
|
||||
"action": "press",
|
||||
"timeout_ms": 15000,
|
||||
"locator": { "kind": "css", "selector": "input[name=password]" },
|
||||
"key": "Enter"
|
||||
},
|
||||
{
|
||||
"step_id": "signed-in",
|
||||
"action": "wait_for",
|
||||
"timeout_ms": 15000,
|
||||
"locator": { "kind": "css", "selector": "nav a[href='/settings']" },
|
||||
"state": "visible"
|
||||
},
|
||||
{
|
||||
"step_id": "folders-1",
|
||||
"action": "request",
|
||||
"timeout_ms": 15000,
|
||||
"method": "GET",
|
||||
"path": "/api/folders",
|
||||
"expected_status": [200]
|
||||
},
|
||||
{
|
||||
"step_id": "create-folder-1",
|
||||
"action": "request",
|
||||
"timeout_ms": 15000,
|
||||
"method": "POST",
|
||||
"path": "/api/folders",
|
||||
"json": { "title": "Scratch folder 1" },
|
||||
"headers": [
|
||||
{
|
||||
"name": "X-CSRFToken",
|
||||
"value": { "source": "cookie", "name": "csrftoken" }
|
||||
}
|
||||
],
|
||||
"expected_status": [200, 201]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Give every step a `timeout_ms`. A step without one waits until the scenario
|
||||
is cancelled, so a locator that never matches hangs the capture, and the
|
||||
client with it. Match `wait_for` locators to exactly one element.
|
||||
|
||||
1. Sign in through the UI: `fill` the user and password fields (the password
|
||||
as a secret reference), submit, then `wait_for` an element only a signed-in
|
||||
user sees.
|
||||
2. Read with `request` steps: each collection the environment needs, twice
|
||||
before any write, so fields that change on their own show up; one item of
|
||||
each.
|
||||
3. Use `request` steps only when the API lets the caller choose each scratch
|
||||
object's ID or a prior read already established it. Request paths are fixed
|
||||
strings; no action substitutes a value from an earlier response. For
|
||||
server-assigned IDs, create through the UI and open the new object's detail
|
||||
view to record its read, edit and delete through UI actions. If that journey
|
||||
cannot be scripted, leave the write unserved and report the limitation;
|
||||
never guess an ID or create objects with no supported cleanup path.
|
||||
Record two numbered scratch objects per write type,
|
||||
with varied free text. After each write, and before the next one, read the
|
||||
object back by id and then its list: create 1, read 1, list, create 2,
|
||||
read 2, list; never several writes before their reads.
|
||||
4. Leave more than a second between a create and its first edit
|
||||
(`wait_for_timeout` with `duration_ms: 1100`).
|
||||
5. Update both objects and read each back; delete both and read each back
|
||||
(expect 404) and the list.
|
||||
|
||||
About `request` steps:
|
||||
|
||||
- `path` is on the start URL's origin; the page must be on that origin.
|
||||
- Header values are literals, declared secrets, a cookie the browser holds
|
||||
(`{source: "cookie", name}`), or a local storage entry
|
||||
(`{source: "local_storage", key, json_pointer}`), with an optional
|
||||
`prefix` such as `"Bearer "`. Copy the headers the application's own
|
||||
requests send (a CSRF header, a bearer token). Values read from the page
|
||||
are redacted from records made after they are read, not from the login
|
||||
response that returned them, and values shorter than 8 characters are not
|
||||
redacted at all.
|
||||
- Reading a page value makes later bodies costlier to keep: after a CSRF
|
||||
token, bodies over about 47 KiB are kept as `unavailable`. When the API
|
||||
returns larger responses, raise `capture.limits`
|
||||
(`max_network_body_allocation_bytes`, `max_total_event_allocation_bytes`).
|
||||
- Request steps follow no redirects: a redirect fails the step, and
|
||||
`expected_status` cannot name a 3xx status. Use the path the redirect names,
|
||||
such as the one with the trailing slash.
|
||||
- Set `expected_status` on every step, so a refused call fails its step and
|
||||
the later steps report not having run, instead of recording read-backs of
|
||||
nothing.
|
||||
|
||||
Keep it to about 60 to 160 requests. A scenario with no `request` step is
|
||||
recorded exactly as before.
|
||||
|
||||
The capture returns its whole Evidence, every recorded body included, which is
|
||||
often more than a client shows inline. Before checking coverage, confirm that
|
||||
every entry of `normalized_result.steps` has `status: "completed"`; if the
|
||||
client saved the result to a file, search it for `"status":"failed"` and read
|
||||
that step's `error`. A failed sign-in or write cancels every step after it.
|
||||
Use the result's `evidence_id` for coverage and export; do not paste the
|
||||
Evidence back into another tool.
|
||||
|
||||
## Check coverage
|
||||
|
||||
`inspect_analysis_view` with `source: {kind: "retained-evidence",
|
||||
evidence_id}` (the capture's id) and `view: {kind: "environment-coverage",
|
||||
template_rules: ["after-uid-literal", "opaque-token", "sibling-variance",
|
||||
"prefix-variance"]}`. It reports read tools
|
||||
answered from the state or replayed (`reads.recorded_reasons`), the served write
|
||||
tools, and each withheld write with its `reason` and `hint`. It does not apply
|
||||
the serve-time catalog and state size checks; the export reports those.
|
||||
|
||||
Re-record a withheld write at most twice, and only for a recording gap. Stop at
|
||||
once when the reason is application behaviour, and report the write as
|
||||
withheld with its hint:
|
||||
|
||||
| Reason | What to do |
|
||||
| --------------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `no-state-target` | Re-record: read the collection or item the write changes. |
|
||||
| `no-observation` | Re-record: read the entity back by id after the write; read it first for an update or delete. |
|
||||
| `unconfirmed` | Re-record: read the entity and its list after the write. |
|
||||
| `incomplete-entities` | Re-record: read the entity through every view that lists it. |
|
||||
| `unexplained-change` | Re-record once with a second, different call of the same write. |
|
||||
| `no-call` | Re-record once with a write that succeeds. |
|
||||
| `side-effect` | Stop: the application changes other entities. |
|
||||
| `contradicted` | Stop: a later read disagrees with the modelled effect. |
|
||||
| `body-unusable` | Stop: the body is not a JSON object. |
|
||||
|
||||
Use new scratch names on each attempt; the first attempt's objects may still
|
||||
exist.
|
||||
New browser scenario captures include request times, so a fully timed capture
|
||||
can learn a write clock and serve updates that stamp modification times. Older
|
||||
captures or ones missing a request start keep record order and learn no clock.
|
||||
When coverage reports that limitation, record again with the current version
|
||||
before concluding that the timestamp change cannot be served.
|
||||
|
||||
## Export and hand off
|
||||
|
||||
`export_environment_bundle` with `source: {kind: "retained-evidence",
|
||||
evidence_id}` (or `{kind: "evidence-file", path}`), an absolute
|
||||
`output_directory` that does not exist yet and whose parent does, and a `name`
|
||||
(required when the application runs on `localhost` or an IP address). It returns
|
||||
the coverage again, `tool_count`, the written files and warnings; `dry_run:
|
||||
true` reports without writing. The bundle installs `rea-agents` of this REA's
|
||||
version from the registry; when the user runs an unreleased REA build, pass the
|
||||
`package_tarball` they give you (a packed `rea-agents` tarball) instead.
|
||||
|
||||
Tell the user how many tools answer from the state, which writes are served and
|
||||
which are withheld and why, and the run command (`agent-env run <folder>`). Say
|
||||
that the bundle ships the recorded responses and the capture's local paths
|
||||
(for a browser scenario, the browser executable's path), and
|
||||
list any `credential-named-members` warning pointers for review. Never publish
|
||||
or share the bundle yourself.
|
||||
|
||||
See
|
||||
[agent environments](https://github.com/morluto/rea/blob/main/docs/agent-environments.md)
|
||||
for what the state, replay and the bundle establish, and
|
||||
[evidence workflows](evidence-workflows.md) for the manifest and state views.
|
||||
@@ -106,6 +106,13 @@ each plan states why in its `reason`. It replays the capture instead with
|
||||
`--replay-only` or when the state is unavailable (not derivable, or a catalog
|
||||
over the discovery budget), and its stopped document's `state` says which
|
||||
applied.
|
||||
Use `view: {kind: "environment-coverage"}` with the same rules to see what an
|
||||
environment built from a capture would serve: read tools answered from the
|
||||
state or replayed with their reason, and each write tool served or withheld
|
||||
with a hint about what to record next; it does not apply the serve-time
|
||||
catalog and state size checks. `rea environment-build <capture.har> <dir>`
|
||||
inspects, projects and exports in one step and prints the same coverage, or
|
||||
`null` when the bundle serves replay.
|
||||
|
||||
For a PE/ELF export question, `inspect_native_exports` accepts `detail: "summary"`
|
||||
and retains the complete table. Query `inspect_analysis_view` with
|
||||
|
||||
@@ -125,6 +125,19 @@ table or overlay. Bound snapshots, loaded IAT contents, and export-forward
|
||||
resolution remain unobserved. See
|
||||
[PE import and delay-load tables](https://github.com/morluto/rea/blob/main/docs/pe-imports.md).
|
||||
|
||||
## PE TLS callbacks and load configuration
|
||||
|
||||
Use `inspect_pe_load_config` for an explicit local PE32/PE32+ image when the
|
||||
question concerns code that runs before the entry point through TLS callbacks,
|
||||
or the security cookie, SafeSEH, CFG, EH-continuation and XFG declarations in
|
||||
the load configuration. No `open_binary`, Windows SDK, or target execution is
|
||||
required. The CLI equivalent is `inspect-pe-load-config PATH`. Preserve artifact
|
||||
SHA-256, directory and callback-array file ranges, and callback VAs as
|
||||
hexadecimal strings. Fields outside the declared `Size` are `null`. Guard-flag
|
||||
mitigations carry `evidence_kind: "inferred"`; enforcement remains unobserved.
|
||||
See
|
||||
[PE TLS callbacks and load configuration](https://github.com/morluto/rea/blob/main/docs/pe-load-config.md).
|
||||
|
||||
## ELF note tables
|
||||
|
||||
Use `inspect_elf_notes` for an explicit local ELF32/ELF64 image when the
|
||||
@@ -136,6 +149,37 @@ absence of those declarations, not proof the image never carried notes in
|
||||
another container. See
|
||||
[ELF note tables](https://github.com/morluto/rea/blob/main/docs/elf-notes.md).
|
||||
|
||||
## Apple IPS crash reports
|
||||
|
||||
Use `inspect_apple_ips` for an explicit local Apple `.ips` file when the
|
||||
question concerns crash metadata, exception and termination facts, threads,
|
||||
usedImages, lossless registers, or documented crash classes. No `open_binary`,
|
||||
Xcode, atos, or target execution is required. The CLI equivalent is
|
||||
`inspect-apple-ips PATH`. Preserve artifact SHA-256, `bug_type` as a string,
|
||||
uppercase image UUIDs, and integer literals that exceed IEEE-754 range. Only
|
||||
`bug_type` `"309"` yields a crash body; other DiagnosticReports types return
|
||||
no crash result. Opened Mach-O and dSYM UUID joins remain unobserved. See
|
||||
[Apple IPS crash reports](https://github.com/morluto/rea/blob/main/docs/apple-ips.md).
|
||||
|
||||
## Linux kernel modules
|
||||
|
||||
Use `inspect_kernel_module` for an explicit local ELF32/ELF64 relocatable
|
||||
object when the question concerns `.modinfo` license, vermagic, alias,
|
||||
depends, or parm strings, the `__versions` symbol CRCs, or an appended module
|
||||
signature trailer. No `open_binary`, Linux host, or `modinfo` program is
|
||||
required. The CLI equivalent is `inspect-kernel-module PATH`. Preserve
|
||||
artifact SHA-256, key order, duplicate keys, CRC hex, and section file ranges.
|
||||
A missing section is observed absence when section names are known, not proof
|
||||
the module never carried that metadata. `.gnu.linkonce.this_module` is reported
|
||||
as present or absent; `struct module` stays unknown because its layout changes
|
||||
with the kernel version. `__ksymtab` records are not decoded. The PKCS#7 range
|
||||
and its SHA-256 are observed; certificate, signer, and digest coverage remain
|
||||
unvalidated. An absent trailer is not proof the module is unsigned in another
|
||||
container. gzip, xz, and zstd whole-file containers are unsupported and name
|
||||
`external_decompression` as the next probe: use an external codec utility to
|
||||
decompress into a separate file, then call `inspect_kernel_module` on that file. See
|
||||
[Linux kernel modules](https://github.com/morluto/rea/blob/main/docs/kernel-modules.md).
|
||||
|
||||
## CPython pyc files
|
||||
|
||||
Use `inspect_python_pyc` for an explicit local CPython 3.7–3.13 `.pyc` when the
|
||||
|
||||
@@ -36,6 +36,9 @@ unchecked. Maintainers can help resolve open questions.
|
||||
Use "none" or "not applicable" only when established. -->
|
||||
|
||||
- Semantic owner and earliest changed stage:
|
||||
<!-- Name the producer of parsed facts or resources and its affected consumers.
|
||||
Summarize superseded paths removed and any distinct policy, lifecycle,
|
||||
lazy-loading, or compatibility responsibility retained. -->
|
||||
- Contribution scope fit and linked maintainer decision:
|
||||
- CLI and MCP/tool-catalog contract:
|
||||
- Provider, bridge, target-format, or platform compatibility:
|
||||
@@ -68,6 +71,10 @@ source, link, or rendered-document checks. -->
|
||||
- User-visible CLI/MCP output (if applicable):
|
||||
- Remaining proof gaps:
|
||||
|
||||
For boundary fixes, identify the applicable [boundary regressions](https://github.com/morluto/rea/blob/main/docs/testing.md#boundary-regressions)
|
||||
and [lifecycle regressions](https://github.com/morluto/rea/blob/main/docs/testing.md#lifecycle-regressions)
|
||||
covered by the evidence above, and explain relevant gaps.
|
||||
|
||||
For evidence-bearing changes:
|
||||
|
||||
- [ ] Observed, derived, and inferred claims remain distinguishable.
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
name: Real Android metadata bridge
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: ["**"]
|
||||
paths:
|
||||
- .github/workflows/real-android-metadata.yml
|
||||
- bridge/android/**
|
||||
- src/android/JadxRelease.ts
|
||||
- scripts/fixtures/android/**
|
||||
- tests/conformance/android/**
|
||||
- tests/fixtures/android/static-initializers/**
|
||||
- tests/fixtures/android/direct-invokes/**
|
||||
- .nvmrc
|
||||
workflow_dispatch:
|
||||
workflow_call:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
concurrency:
|
||||
group: android-metadata-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
android-metadata:
|
||||
runs-on: ubuntu-24.04
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
|
||||
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
|
||||
with:
|
||||
node-version-file: .nvmrc
|
||||
- name: Fetch checksum-pinned engine and public APK fixture
|
||||
run: node scripts/fixtures/android/fetch.mjs "$RUNNER_TEMP/rea-android"
|
||||
- name: Compile and exercise the real metadata bridge
|
||||
shell: bash
|
||||
run: |
|
||||
export JAVA_HOME="$JAVA_HOME_21_X64"
|
||||
android_root="$RUNNER_TEMP/rea-android"
|
||||
classes="$android_root/classes"
|
||||
jar="$android_root/jadx-headless-mcp-0.7.1-all.jar"
|
||||
mkdir -p "$classes"
|
||||
"$JAVA_HOME/bin/javac" -J-Xmx512m -J-XX:ActiveProcessorCount=2 \
|
||||
-classpath "$jar" -d "$classes" \
|
||||
bridge/android/ReaJadxBridge.java \
|
||||
tests/conformance/android/ReaJadxMetadataRegression.java
|
||||
"$JAVA_HOME/bin/java" -Xmx512m -XX:ActiveProcessorCount=2 \
|
||||
-classpath "$classes:$jar" ReaJadxMetadataRegression \
|
||||
"$android_root/ApiDemos-debug.apk" \
|
||||
"$GITHUB_WORKSPACE/tests/fixtures/android/static-initializers" \
|
||||
"$classes" "$GITHUB_WORKSPACE/tests/fixtures/android/direct-invokes" \
|
||||
| tee "$android_root/metadata.log"
|
||||
grep -F 'RAW_CLASS_SELECTOR_REGRESSION_PASS nested=true metadata=true references=true' \
|
||||
"$android_root/metadata.log"
|
||||
@@ -48,7 +48,8 @@ jobs:
|
||||
- uses: ./.github/actions/portable-build-cache
|
||||
with:
|
||||
build_cache_artifact: ${{ inputs.build_cache_artifact }}
|
||||
- run: npm run verify:browser
|
||||
# Own a fresh bus so Chromium never depends on an inherited session address.
|
||||
- run: dbus-run-session -- npm run verify:browser
|
||||
env:
|
||||
REA_BROWSER_EXECUTABLE: /usr/bin/google-chrome
|
||||
REA_BROWSER_NO_SANDBOX: "true"
|
||||
@@ -44,7 +44,8 @@ jobs:
|
||||
- uses: ./.github/actions/portable-build-cache
|
||||
with:
|
||||
build_cache_artifact: ${{ inputs.build_cache_artifact }}
|
||||
- run: env -u DBUS_SESSION_BUS_ADDRESS npm run verify:browser:runtime
|
||||
# Own a fresh bus so Chromium never depends on an inherited session address.
|
||||
- run: dbus-run-session -- npm run verify:browser:runtime
|
||||
env:
|
||||
REA_BROWSER_EXECUTABLE: /usr/bin/google-chrome
|
||||
REA_BROWSER_NO_SANDBOX: "true"
|
||||
@@ -46,7 +46,8 @@ jobs:
|
||||
build_cache_artifact: ${{ inputs.build_cache_artifact }}
|
||||
- name: Install the pinned compiler into an isolated fixture directory
|
||||
run: npm install --prefix "$RUNNER_TEMP/rea-web-source-map-compiler" --no-audit --no-fund --package-lock=false [email protected]
|
||||
- run: npm run verify:browser:source-maps
|
||||
# Own a fresh bus so Chromium never depends on an inherited session address.
|
||||
- run: dbus-run-session -- npm run verify:browser:source-maps
|
||||
env:
|
||||
# Retain browser launch argv/PID/stderr in the verifier's captured
|
||||
# CLI failure diagnostics without changing its deadline or retrying.
|
||||
|
||||
+93
-3
@@ -1,7 +1,12 @@
|
||||
{
|
||||
"$schema": "./node_modules/oxlint/configuration_schema.json",
|
||||
"plugins": ["typescript", "import", "unicorn", "oxc"],
|
||||
"plugins": ["typescript", "import", "unicorn", "oxc", "vitest"],
|
||||
"rules": {
|
||||
"rea/no-buffer-deep-equality": "error",
|
||||
"rea/cancellation-cause": "error",
|
||||
"no-async-promise-executor": "error",
|
||||
"no-unreachable": "error",
|
||||
"no-unsafe-optional-chaining": "error",
|
||||
"complexity": ["warn", 20],
|
||||
"max-depth": ["warn", 4],
|
||||
"max-lines": [
|
||||
@@ -23,7 +28,37 @@
|
||||
"max-params": ["warn", 4],
|
||||
"no-var": "warn",
|
||||
"no-var-requires": "error",
|
||||
"typescript/no-import-type-side-effects": "error"
|
||||
"typescript/no-import-type-side-effects": "error",
|
||||
"vitest/no-standalone-expect": "off",
|
||||
"vitest/no-conditional-expect": "off",
|
||||
"vitest/expect-expect": "off",
|
||||
"vitest/no-disabled-tests": "off",
|
||||
"vitest/require-mock-type-parameters": "off",
|
||||
"vitest/require-to-throw-message": "off",
|
||||
"import/no-duplicates": [
|
||||
"warn",
|
||||
{
|
||||
"preferInline": false
|
||||
}
|
||||
],
|
||||
"vitest/valid-expect": [
|
||||
"warn",
|
||||
{
|
||||
"maxArgs": 2
|
||||
}
|
||||
],
|
||||
"rea/no-evidence-json-preadmission": "error",
|
||||
"rea/no-positional-tool-contract": "error",
|
||||
"rea/no-fixture-root-cleanup": "error",
|
||||
"typescript/no-floating-promises": "error",
|
||||
"typescript/no-misused-promises": "warn",
|
||||
"typescript/return-await": ["error", "error-handling-correctness-only"],
|
||||
"typescript/switch-exhaustiveness-check": [
|
||||
"error",
|
||||
{
|
||||
"considerDefaultExhaustiveForUnions": true
|
||||
}
|
||||
]
|
||||
},
|
||||
"overrides": [
|
||||
{
|
||||
@@ -36,6 +71,12 @@
|
||||
"no-var-requires": "off"
|
||||
}
|
||||
},
|
||||
{
|
||||
"files": ["src/**/*.ts"],
|
||||
"rules": {
|
||||
"typescript/no-misused-promises": "error"
|
||||
}
|
||||
},
|
||||
{
|
||||
"files": ["tests/**/*.ts", "src/**/*.test.ts", "src/**/*.fixture.ts"],
|
||||
"rules": {
|
||||
@@ -47,7 +88,8 @@
|
||||
"skipBlankLines": true,
|
||||
"skipComments": true
|
||||
}
|
||||
]
|
||||
],
|
||||
"typescript/no-misused-promises": "warn"
|
||||
}
|
||||
},
|
||||
{
|
||||
@@ -91,6 +133,45 @@
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"files": ["tests/**/*.test.ts", "src/**/*.test.ts"],
|
||||
"rules": {
|
||||
"vitest/valid-expect": [
|
||||
"warn",
|
||||
{
|
||||
"maxArgs": 2
|
||||
}
|
||||
],
|
||||
"vitest/valid-expect-in-promise": "error",
|
||||
"vitest/no-focused-tests": "error"
|
||||
}
|
||||
},
|
||||
{
|
||||
"files": [
|
||||
"scripts/lib/http3-capture-assertions.test.mjs",
|
||||
"scripts/lib/http3-verifier-lifecycle.test.mjs"
|
||||
],
|
||||
"rules": {
|
||||
"typescript/no-floating-promises": [
|
||||
"error",
|
||||
{
|
||||
"allowForKnownSafeCalls": [
|
||||
{
|
||||
"from": "package",
|
||||
"package": "@types/node",
|
||||
"name": "test"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"files": ["scripts/fixtures/javascript-recovery/code-split/entry.mjs"],
|
||||
"rules": {
|
||||
"typescript/no-floating-promises": "off"
|
||||
}
|
||||
}
|
||||
],
|
||||
"env": {
|
||||
@@ -109,5 +190,14 @@
|
||||
".devin",
|
||||
".factory",
|
||||
"third_party"
|
||||
],
|
||||
"options": {
|
||||
"reportUnusedDisableDirectives": "error"
|
||||
},
|
||||
"jsPlugins": [
|
||||
{
|
||||
"name": "rea",
|
||||
"specifier": "./scripts/lint/index.mjs"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -80,7 +80,7 @@ Coordinate expensive checks across agents. If a test unexpectedly consumes heavy
|
||||
|
||||
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.
|
||||
For test changes or provider claims, use [docs/testing.md](docs/testing.md). Select applicable [boundary regressions](docs/testing.md#boundary-regressions) for parser, inventory, snapshot, and projection fixes. 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.
|
||||
|
||||
@@ -108,10 +108,11 @@ distinguish source-derived conclusions, proposed checks, and unavailable coverag
|
||||
Address actionable automated review findings and explain disagreements.
|
||||
|
||||
Leave the template's **Author readiness** declarations unchecked for the human
|
||||
owner to complete. Never attest to human review on their behalf. Keep the PR in
|
||||
draft until the human declares the PR initially ready. Later pushes do not
|
||||
invalidate that declaration or require another human sign-off. Keep the PR body
|
||||
and affected validation current as work changes. The readiness check validates
|
||||
owner to complete. Never attest to human review on their behalf. Draft status
|
||||
is optional; preserve the PR's current draft status unless the user asks to change
|
||||
it. Later pushes do not invalidate the readiness declaration or require another
|
||||
human sign-off. Keep the PR body and affected validation current as work changes.
|
||||
The readiness check validates
|
||||
the filled declaration; CI and automated review results do not establish that
|
||||
human review occurred, maintainer scope approval, or merge permission.
|
||||
|
||||
|
||||
+27
-3
@@ -25,6 +25,18 @@ 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.
|
||||
|
||||
Before retiring an alias or facade, trace runtime registration, dynamic imports,
|
||||
JavaScript verifiers, subprocess scripts, and packaged entrypoints as well as
|
||||
TypeScript references. Tests may be the last consumers of a superseded internal
|
||||
path; migrate their distinct assertions to the current production path before
|
||||
removing it. Preserve validation, lazy loading, caller policy, and resource
|
||||
acquisition and cleanup supplied by the old boundary. Published APIs, persisted
|
||||
formats, and independently versioned bridges require an explicit compatibility
|
||||
decision; an internal representation alone does not establish that obligation.
|
||||
See [interpreting boundary facts once](docs/tool-design.md#interpret-boundary-facts-once)
|
||||
for admission ownership and the distinction between repeated validation and
|
||||
independent checks.
|
||||
|
||||
For analysis workflows and agent interfaces, follow the
|
||||
[performance priorities](AGENTS.md#performance). Explain the selected output
|
||||
scope, reuse/cache decisions, and relevant before/after measurements when these
|
||||
@@ -89,7 +101,11 @@ Human ownership and review remain required when CI or an automated reviewer
|
||||
reports success. Readiness requests maintainer review; it does not grant scope
|
||||
approval or permission to merge.
|
||||
|
||||
Draft PRs may request early feedback with open questions and incomplete checks.
|
||||
Draft status is optional. Draft PRs may request early feedback with open questions
|
||||
and incomplete checks. Agents preserve the current draft status unless asked to
|
||||
change it; missing readiness declarations or later updates do not require a PR
|
||||
to become a draft.
|
||||
|
||||
Leave the readiness declaration unchecked until the human owner has completed
|
||||
it. The declaration records initial readiness; later pushes do not invalidate
|
||||
it or require another human sign-off. Keep the PR description and affected
|
||||
@@ -368,9 +384,17 @@ 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.
|
||||
for exact-path, awaited cleanup, including failures and timeouts. It registers
|
||||
deletion with Vitest's `onTestFinished`; do not also add its result to a roots
|
||||
array or an `afterEach` removal. `createTestWorkspace` from
|
||||
`tests/support/workspace/workspaceFixture.ts` leaves cleanup with its caller,
|
||||
which must await `removeTestWorkspace`. Keep explicit resource teardown before
|
||||
directory deletion, using the case's `finally` or `afterEach`; Vitest runs
|
||||
`afterEach` before `onTestFinished` and awaits finish hooks in reverse
|
||||
registration order.
|
||||
`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.
|
||||
rejects remaining REA-owned paths. It cannot detect duplicate deletion owners or
|
||||
prove resource-close ordering. Never glob-clean shared `/tmp/rea-*` content.
|
||||
|
||||
`REA_LOG_LEVEL` selects `trace`, `debug`, `info`, `warn`, `error`, `fatal`, or
|
||||
`silent`. Logs go to stderr: MCP defaults to `info`, and one-shot CLI logging
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
**English** · [简体中文](docs/readme/README_zh.md) · [繁體中文](docs/readme/README_zh-TW.md) · [日本語](docs/readme/README_ja.md) · [한국어](docs/readme/README_ko.md) · [Türkçe](docs/readme/README_tr.md) · [Русский](docs/readme/README_ru.md) · [Tiếng Việt](docs/readme/README_vi.md) · [ไทย](docs/readme/README_th.md) · [Deutsch](docs/readme/README_de.md) · [Español](docs/readme/README_es.md) · [Français](docs/readme/README_fr.md) · [Українська](docs/readme/README_uk.md) · [Polski](docs/readme/README_pl.md) · [Português (Brasil)](docs/readme/README_pt-BR.md) · [العربية](docs/readme/README_ar.md) · [فارسی](docs/readme/README_fa.md) · [Bahasa Indonesia](docs/readme/README_id.md) · [Italiano](docs/readme/README_it.md)
|
||||
· [Ελληνικά](docs/readme/README_el.md) · [മലയാളം](docs/readme/README_ml.md) · [Roman Urdu](docs/readme/README_ur-Latn.md)
|
||||
· [Ελληνικά](docs/readme/README_el.md) · [മലയാളം](docs/readme/README_ml.md) · [Roman Urdu](docs/readme/README_ur-Latn.md) · [Română](docs/readme/README_ro.md)
|
||||
|
||||
# REA: Reverse Engineer Anything
|
||||
|
||||
@@ -194,6 +194,8 @@ Additional tools and host support depend on the target:
|
||||
| PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](docs/pe-certificates.md) |
|
||||
| PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](docs/pe-imports.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](docs/elf-notes.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and documented crash classes | Built-in static JSON inspection; [Apple IPS](docs/apple-ips.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](docs/kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, imports, lambdas and the Code header | Built-in static BEAM inspection; [Erlang BEAM](docs/erlang-beam.md) |
|
||||
| WASM artifact | Validation, sections, exact import/export WAT forms and decoded WAT | Caller-supplied WABT 1.0.42; `inspect_wasm_artifact` |
|
||||
| EVM bytecode | Dispatch selectors, byte offsets, inferred arguments and mutability | Local raw/hex carrier on Linux x64; [offline EVM guide](docs/evm-bytecode.md) |
|
||||
|
||||
@@ -3,6 +3,8 @@ import com.google.gson.*;
|
||||
import io.modelcontextprotocol.kotlin.sdk.server.*;
|
||||
import io.modelcontextprotocol.kotlin.sdk.types.*;
|
||||
import jadx.api.*;
|
||||
import jadx.api.plugins.input.data.annotations.EncodedValue;
|
||||
import jadx.api.plugins.input.data.attributes.JadxAttrType;
|
||||
import jadx.api.plugins.input.data.ICodeReader;
|
||||
import jadx.api.plugins.input.data.IMethodRef;
|
||||
import jadx.api.plugins.input.insns.InsnIndexType;
|
||||
@@ -40,7 +42,8 @@ class ReaJadxBridge {
|
||||
|
||||
private record MethodSnapshot(String name, String rawName, String shortId, List<String> bodyAbsenceMarkers,
|
||||
Map<String, Object> summary) {}
|
||||
private record ClassSnapshot(JavaClass node, List<MethodSnapshot> methods, Map<String, Object> summary) {}
|
||||
private record ClassSnapshot(JavaClass node, List<MethodSnapshot> methods, Map<String, Object> summary,
|
||||
Map<String, Object> summaryWithValues) {}
|
||||
private record ManifestSnapshot(String text, Map<String, Object> summary) {}
|
||||
|
||||
private static final class InputFailure extends IllegalArgumentException {
|
||||
@@ -142,6 +145,14 @@ class ReaJadxBridge {
|
||||
return value.getAsString();
|
||||
}
|
||||
|
||||
private static boolean flag(JsonObject args, String name) {
|
||||
JsonElement value = args.get(name);
|
||||
if (value == null) return false;
|
||||
if (!value.isJsonPrimitive() || !value.getAsJsonPrimitive().isBoolean())
|
||||
throw new IllegalArgumentException(name + " must be a boolean");
|
||||
return value.getAsBoolean();
|
||||
}
|
||||
|
||||
private static int integer(JsonObject args, String name, int fallback) {
|
||||
JsonElement value = args.get(name);
|
||||
if (value == null) return fallback;
|
||||
@@ -263,18 +274,43 @@ class ReaJadxBridge {
|
||||
"dex_descriptor", descriptor,
|
||||
"is_constructor", method.isConstructor(), "def_pos", 0));
|
||||
}).toList();
|
||||
List<Map<String, Object>> fields = node.getFields().stream()
|
||||
.sorted(Comparator.comparing(FieldNode::getAlias))
|
||||
.map(field -> Map.<String, Object>of("name", field.getAlias(),
|
||||
"type", field.getType().toString(), "def_pos", 0)).toList();
|
||||
List<FieldNode> orderedFields = new ArrayList<>(node.getFields());
|
||||
orderedFields.sort(Comparator.comparing(FieldNode::getAlias));
|
||||
List<Map<String, Object>> fields = new ArrayList<>();
|
||||
List<Map<String, Object>> valuedFields = new ArrayList<>();
|
||||
boolean anyValue = false;
|
||||
for (FieldNode field : orderedFields) {
|
||||
Map<String, Object> entry = Map.of("name", field.getAlias(),
|
||||
"type", field.getType().toString(), "def_pos", 0);
|
||||
fields.add(entry);
|
||||
Map<String, Object> value = dexStaticValue(field);
|
||||
if (value == null) valuedFields.add(entry);
|
||||
else {
|
||||
anyValue = true;
|
||||
Map<String, Object> valued = new LinkedHashMap<>(entry);
|
||||
valued.put("dex_static_value", value);
|
||||
valuedFields.add(Collections.unmodifiableMap(valued));
|
||||
}
|
||||
}
|
||||
List<String> inner = node.getInnerClasses().stream().map(ClassNode::getFullName).toList();
|
||||
Map<String, Object> summary = Map.of(
|
||||
"full_name", cls.getFullName(), "name", cls.getName(),
|
||||
"full_name", cls.getFullName(), "raw_name", cls.getRawName(), "name", cls.getName(),
|
||||
"method_count", methods.size(), "field_count", fields.size(),
|
||||
"inner_class_count", inner.size(), "inner_classes", inner,
|
||||
"methods", methods.stream().map(MethodSnapshot::summary).toList(), "fields", fields);
|
||||
index.computeIfAbsent(cls.getFullName(), ignored -> new ArrayList<>())
|
||||
.add(new ClassSnapshot(cls, methods, summary));
|
||||
"methods", methods.stream().map(MethodSnapshot::summary).toList(), "fields", List.copyOf(fields));
|
||||
// DEX static values are opt-in, so method and reference lookups keep the member-only reply.
|
||||
Map<String, Object> summaryWithValues = summary;
|
||||
if (anyValue) {
|
||||
Map<String, Object> copy = new LinkedHashMap<>(summary);
|
||||
copy.put("fields", List.copyOf(valuedFields));
|
||||
summaryWithValues = Collections.unmodifiableMap(copy);
|
||||
}
|
||||
ClassSnapshot snapshot = new ClassSnapshot(cls, methods, summary, summaryWithValues);
|
||||
index.computeIfAbsent(cls.getFullName(), ignored -> new ArrayList<>()).add(snapshot);
|
||||
// Keep the binary identity supplied by JADX; '$' can also be a literal
|
||||
// name character, so replacing separators would invent lookup aliases.
|
||||
if (!cls.getRawName().equals(cls.getFullName()))
|
||||
index.computeIfAbsent(cls.getRawName(), ignored -> new ArrayList<>()).add(snapshot);
|
||||
}
|
||||
}
|
||||
classes = Collections.unmodifiableMap(index);
|
||||
@@ -289,6 +325,28 @@ class ReaJadxBridge {
|
||||
return candidates.get(0);
|
||||
}
|
||||
|
||||
/** A static final field's class-definition static value; a static initializer can still assign it. */
|
||||
private static Map<String, Object> dexStaticValue(FieldNode field) {
|
||||
if (!field.getAccessFlags().isStatic() || !field.getAccessFlags().isFinal()) return null;
|
||||
EncodedValue encoded = field.get(JadxAttrType.CONSTANT_VALUE);
|
||||
if (encoded == null) return null;
|
||||
Object value = encoded.getValue();
|
||||
// JADX also attaches the shared null to static finals without a value, so null is never reported.
|
||||
// Wide and floating values keep their Java text instead of a lossy JSON number.
|
||||
return switch (encoded.getType()) {
|
||||
case ENCODED_BOOLEAN -> Map.of("type", "boolean", "value", value);
|
||||
case ENCODED_BYTE -> Map.of("type", "byte", "value", value);
|
||||
case ENCODED_SHORT -> Map.of("type", "short", "value", value);
|
||||
case ENCODED_CHAR -> Map.of("type", "char", "value", (int) (Character) value);
|
||||
case ENCODED_INT -> Map.of("type", "int", "value", value);
|
||||
case ENCODED_LONG -> Map.of("type", "long", "value", value.toString());
|
||||
case ENCODED_FLOAT -> Map.of("type", "float", "value", value.toString());
|
||||
case ENCODED_DOUBLE -> Map.of("type", "double", "value", value.toString());
|
||||
case ENCODED_STRING -> Map.of("type", "string", "value", value);
|
||||
default -> null;
|
||||
};
|
||||
}
|
||||
|
||||
private List<MethodSnapshot> methods(ClassSnapshot cls, JsonObject args) {
|
||||
String name = string(args, "method_name");
|
||||
List<MethodSnapshot> result = cls.methods().stream().filter(method -> method.name().equals(name)).toList();
|
||||
@@ -439,7 +497,8 @@ class ReaJadxBridge {
|
||||
"items", items));
|
||||
}
|
||||
ClassSnapshot cls = selected(args);
|
||||
if (name.equals("get_class_summary")) return json(cls.summary());
|
||||
if (name.equals("get_class_summary"))
|
||||
return json(flag(args, "dex_static_values") ? cls.summaryWithValues() : cls.summary());
|
||||
if (name.equals("get_method_body")) {
|
||||
List<MethodSnapshot> overloads = methods(cls, args);
|
||||
int index = integer(args, "overload_index", 0);
|
||||
@@ -454,7 +513,7 @@ class ReaJadxBridge {
|
||||
"markers", code.getMarkers(), "body", code.getText()));
|
||||
}
|
||||
List<JavaNode> uses;
|
||||
String target = string(args, "class_name");
|
||||
String target = (String) cls.summary().get("full_name");
|
||||
MethodSnapshot selectedMethod = null;
|
||||
int overloadIndex = 0;
|
||||
if (name.equals("get_xrefs_to_class")) uses = cls.node().getUseIn();
|
||||
@@ -522,7 +581,7 @@ class ReaJadxBridge {
|
||||
SessionHolder holder = new SessionHolder(defaults);
|
||||
ServerCapabilities capabilities = new ServerCapabilities(
|
||||
new ServerCapabilities.Tools(null), null, null, null, null, null, null, Map.of());
|
||||
Server server = new Server(new Implementation("rea-jadx-bridge", "5", null, null, null),
|
||||
Server server = new Server(new Implementation("rea-jadx-bridge", "7", null, null, null),
|
||||
new ServerOptions(capabilities), "", ignored -> Unit.INSTANCE);
|
||||
SessionToolsKt.registerSessionTools(server, holder);
|
||||
ClassToolsKt.registerClassTools(server, holder);
|
||||
@@ -564,9 +623,12 @@ class ReaJadxBridge {
|
||||
if (name.equals("list_classes")) properties.put("query",
|
||||
new kotlinx.serialization.json.JsonObject(Map.of(
|
||||
"type", kotlinx.serialization.json.JsonElementKt.JsonPrimitive("string"))));
|
||||
if (name.equals("get_class_summary")) properties.put("dex_static_values",
|
||||
new kotlinx.serialization.json.JsonObject(Map.of(
|
||||
"type", kotlinx.serialization.json.JsonElementKt.JsonPrimitive("boolean"))));
|
||||
String description = switch (name) {
|
||||
case "list_classes" -> "Pages of case-sensitive matching top-level class names; offset and next_offset are inventory positions, limit bounds matching rows. Omitted or empty query inventories all names.";
|
||||
case "get_class_summary" -> "Parsed member metadata for one exact class name; no source generation.";
|
||||
case "get_class_summary" -> "Parsed member metadata for one exact class name; no source generation. Set dex_static_values to include encoded static final field values.";
|
||||
case "get_method_body" -> "Source for an exact class and stable same-name overload index; static initializers use smali to preserve folded field initialization.";
|
||||
default -> "Complete static using-node inventory for an exact class or selected method overload; one node may contain multiple invoke instructions, and source lines are unresolved.";
|
||||
};
|
||||
|
||||
@@ -643,6 +643,9 @@ public final class ReaGhidraBridge extends HeadlessScript {
|
||||
mapping.addProperty("initialized", block.isInitialized());
|
||||
mapping.addProperty("loaded", block.isLoaded());
|
||||
mapping.addProperty("overlay", block.isOverlay());
|
||||
mapping.addProperty("readable", block.isRead());
|
||||
mapping.addProperty("writable", block.isWrite());
|
||||
mapping.addProperty("executable", block.isExecute());
|
||||
mapping.addProperty("length", source.getLength());
|
||||
FileBytes backing = source.getFileBytes().orElse(null);
|
||||
int sourceIndex = backing == null ? -1 : files.indexOf(backing);
|
||||
|
||||
@@ -0,0 +1,193 @@
|
||||
import ghidra.app.script.GhidraScript;
|
||||
import ghidra.program.database.mem.FileBytes;
|
||||
import ghidra.program.model.address.Address;
|
||||
import ghidra.program.model.address.AddressSpace;
|
||||
import ghidra.program.model.listing.Program;
|
||||
import ghidra.program.model.mem.Memory;
|
||||
import ghidra.program.model.mem.MemoryBlock;
|
||||
import ghidra.program.model.mem.MemoryBlockSourceInfo;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.LinkOption;
|
||||
import java.nio.file.Path;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Rebuild a GameCube/Wii DOL memory map from the validated load ranges REA's TypeScript
|
||||
* admission wrote. BinaryLoader maps the whole file once at address 0; this
|
||||
* script replaces that block with text, data, and BSS blocks at their load addresses.
|
||||
*/
|
||||
public final class ReaGhidraPrepareDol extends GhidraScript {
|
||||
// Canonical v2 header, 18 section rows, 12 gap rows and entry, using uint32 hex.
|
||||
private static final int MAX_PLAN_BYTES = 13 + 18 * 49 + 12 * 30 + 17;
|
||||
private static final class Section {
|
||||
final String kind;
|
||||
final int index;
|
||||
final long fileOffset;
|
||||
final long address;
|
||||
final long size;
|
||||
|
||||
Section(String kind, int index, long fileOffset, long address, long size) {
|
||||
this.kind = kind;
|
||||
this.index = index;
|
||||
this.fileOffset = fileOffset;
|
||||
this.address = address;
|
||||
this.size = size;
|
||||
}
|
||||
}
|
||||
|
||||
private record BssGap(long address, long size) {}
|
||||
|
||||
@Override
|
||||
public void run() throws Exception {
|
||||
String[] arguments = getScriptArgs();
|
||||
if (arguments.length != 1) {
|
||||
throw new IllegalArgumentException(
|
||||
"GameCube DOL preparation requires exactly one section table path"
|
||||
);
|
||||
}
|
||||
if (!currentProgram.getExecutableFormat().equals("Raw Binary") ||
|
||||
!currentProgram.getLanguageID().getIdAsString().startsWith("PowerPC:BE:32:")) {
|
||||
throw new IllegalArgumentException(
|
||||
"GameCube DOL preparation requires a BinaryLoader import in big-endian 32-bit PowerPC"
|
||||
);
|
||||
}
|
||||
Path tablePath = Path.of(arguments[0]);
|
||||
if (!Files.isRegularFile(tablePath, LinkOption.NOFOLLOW_LINKS)) {
|
||||
throw new IllegalArgumentException("GameCube DOL section table is not a regular file");
|
||||
}
|
||||
if (Files.size(tablePath) > MAX_PLAN_BYTES) {
|
||||
throw new IllegalArgumentException("GameCube DOL plan exceeds the canonical format's byte bound");
|
||||
}
|
||||
|
||||
List<Section> sections = new ArrayList<>();
|
||||
List<BssGap> bssGaps = new ArrayList<>();
|
||||
int expectedSections = -1;
|
||||
int expectedGaps = -1;
|
||||
long entry = -1;
|
||||
for (String line : Files.readAllLines(tablePath)) {
|
||||
String[] fields = line.trim().split("\\s+");
|
||||
switch (fields[0]) {
|
||||
case "plan" -> {
|
||||
requireFields(fields, 4, line);
|
||||
if (expectedSections >= 0 || !fields[1].equals("2")) {
|
||||
throw new IllegalArgumentException("Duplicate or unsupported GameCube DOL plan header");
|
||||
}
|
||||
expectedSections = Integer.parseInt(fields[2]);
|
||||
expectedGaps = Integer.parseInt(fields[3]);
|
||||
// A DOL has 18 slots, including at most 11 data slots and 12 BSS gaps.
|
||||
if (expectedSections < 1 || expectedSections > 18 || expectedGaps < 0 || expectedGaps > 12) {
|
||||
throw new IllegalArgumentException("GameCube DOL plan counts exceed the format's slot bounds");
|
||||
}
|
||||
}
|
||||
case "section" -> {
|
||||
requireFields(fields, 6, line);
|
||||
if (expectedSections < 0 || sections.size() >= expectedSections) {
|
||||
throw new IllegalArgumentException("GameCube DOL section exceeds its declared count");
|
||||
}
|
||||
sections.add(new Section(
|
||||
fields[1],
|
||||
Integer.parseInt(fields[2]),
|
||||
Long.decode(fields[3]),
|
||||
Long.decode(fields[4]),
|
||||
Long.decode(fields[5])
|
||||
));
|
||||
}
|
||||
case "bss-gap" -> {
|
||||
requireFields(fields, 3, line);
|
||||
if (expectedGaps < 0 || bssGaps.size() >= expectedGaps) {
|
||||
throw new IllegalArgumentException("GameCube DOL BSS gap exceeds its declared count");
|
||||
}
|
||||
long address = Long.decode(fields[1]);
|
||||
long size = Long.decode(fields[2]);
|
||||
if (address < 0 || size <= 0) {
|
||||
throw new IllegalArgumentException("GameCube DOL BSS gap is not a positive range");
|
||||
}
|
||||
bssGaps.add(new BssGap(address, size));
|
||||
}
|
||||
case "entry" -> {
|
||||
requireFields(fields, 2, line);
|
||||
entry = Long.decode(fields[1]);
|
||||
}
|
||||
default -> throw new IllegalArgumentException("Unknown GameCube DOL table line: " + line);
|
||||
}
|
||||
}
|
||||
if (expectedSections != sections.size() || expectedGaps != bssGaps.size() || entry < 0) {
|
||||
throw new IllegalArgumentException("GameCube DOL section table is incomplete");
|
||||
}
|
||||
|
||||
Memory memory = currentProgram.getMemory();
|
||||
List<FileBytes> files = memory.getAllFileBytes();
|
||||
if (files.size() != 1) {
|
||||
throw new IllegalStateException("GameCube DOL preparation requires exactly one imported file image");
|
||||
}
|
||||
FileBytes fileBytes = files.get(0);
|
||||
AddressSpace space = currentProgram.getAddressFactory().getDefaultAddressSpace();
|
||||
|
||||
// Remove the whole-file block before creating section blocks, so no two blocks claim one address.
|
||||
for (MemoryBlock block : memory.getBlocks()) {
|
||||
for (MemoryBlockSourceInfo source : block.getSourceInfos()) {
|
||||
if (source.getFileBytes().isPresent() && source.getFileBytes().get().equals(fileBytes)) {
|
||||
memory.removeBlock(block, monitor);
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for (Section section : sections) {
|
||||
if (section.fileOffset + section.size > fileBytes.getSize()) {
|
||||
throw new IllegalArgumentException(
|
||||
"GameCube DOL " + section.kind + " " + section.index + " exceeds the imported file"
|
||||
);
|
||||
}
|
||||
boolean text = section.kind.equals("text");
|
||||
if (!text && !section.kind.equals("data")) {
|
||||
throw new IllegalArgumentException("Unknown GameCube DOL section kind: " + section.kind);
|
||||
}
|
||||
MemoryBlock block = memory.createInitializedBlock(
|
||||
"." + section.kind + section.index,
|
||||
space.getAddress(section.address),
|
||||
fileBytes,
|
||||
section.fileOffset,
|
||||
section.size,
|
||||
false
|
||||
);
|
||||
block.setRead(true);
|
||||
block.setWrite(!text);
|
||||
block.setExecute(text);
|
||||
}
|
||||
|
||||
// Apply the domain owner's exact uninitialized ranges; do not reinterpret BSS here.
|
||||
int gapIndex = 0;
|
||||
for (BssGap gap : bssGaps) {
|
||||
MemoryBlock block = memory.createUninitializedBlock(
|
||||
".bss" + gapIndex++,
|
||||
space.getAddress(gap.address()),
|
||||
gap.size(),
|
||||
false
|
||||
);
|
||||
block.setRead(true);
|
||||
block.setWrite(true);
|
||||
block.setExecute(false);
|
||||
}
|
||||
|
||||
Address entryAddress = space.getAddress(entry);
|
||||
MemoryBlock entryBlock = memory.getBlock(entryAddress);
|
||||
if (entryBlock == null || !entryBlock.isExecute()) {
|
||||
throw new IllegalArgumentException("GameCube DOL entry must lie in an executable section");
|
||||
}
|
||||
addEntryPoint(entryAddress);
|
||||
if (!disassemble(entryAddress) || createFunction(entryAddress, "__start") == null) {
|
||||
throw new IllegalStateException("GameCube DOL entry cannot be decoded as a function");
|
||||
}
|
||||
currentProgram.getOptions(Program.PROGRAM_INFO).setBoolean("REA raw binary prepared", true);
|
||||
currentProgram.getOptions(Program.PROGRAM_INFO).setBoolean("REA GameCube DOL prepared", true);
|
||||
}
|
||||
|
||||
private static void requireFields(String[] fields, int count, String line) {
|
||||
if (fields.length != count) {
|
||||
throw new IllegalArgumentException("Malformed GameCube DOL table line: " + line);
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
@@ -34,7 +34,10 @@ export default defineConfig({
|
||||
{ text: "Rust dependencies", link: "/rust-binaries" },
|
||||
{ text: "PE certificates", link: "/pe-certificates" },
|
||||
{ text: "PE imports", link: "/pe-imports" },
|
||||
{ text: "PE TLS/load config", link: "/pe-load-config" },
|
||||
{ text: "ELF notes", link: "/elf-notes" },
|
||||
{ text: "Apple IPS crash reports", link: "/apple-ips" },
|
||||
{ text: "Linux kernel modules", link: "/kernel-modules" },
|
||||
{ text: "CPython pyc files", link: "/python-pyc" },
|
||||
{ text: "Erlang BEAM", link: "/erlang-beam" },
|
||||
{
|
||||
@@ -79,6 +82,7 @@ export default defineConfig({
|
||||
{ text: "Ghidra raw binary", link: "/raw-binary" },
|
||||
{ text: "Ghidra NativeAOT", link: "/ghidra-nativeaot" },
|
||||
{ text: "Ghidra PowerPC", link: "/ghidra-ppc" },
|
||||
{ text: "Ghidra GameCube DOL", link: "/ghidra-dol" },
|
||||
{ text: "Ghidra semantics", link: "/ghidra-provider" },
|
||||
],
|
||||
},
|
||||
|
||||
+322
-30
@@ -1,16 +1,20 @@
|
||||
# Agent environments from recorded captures
|
||||
|
||||
Use `rea environment-serve` to serve an environment manifest as an agent
|
||||
environment: an MCP server whose tools answer from what one retained web
|
||||
network capture observed, plus the environment card the agentenv framework
|
||||
reads to discover it. By default the server derives the
|
||||
[state the capture observed](#the-state-a-capture-observed) at startup and
|
||||
answers read tools from it, and the write tools whose effect the capture
|
||||
confirmed by changing it; `--replay-only` replays the capture's records
|
||||
Use `rea environment-build` to turn one recorded capture into an agent
|
||||
environment bundle in one offline step: a folder `agent-env run` builds and
|
||||
runs, whose MCP server answers from what the capture observed. See
|
||||
[Build a bundle in one step](#build-a-bundle-in-one-step).
|
||||
|
||||
The steps it composes are separate commands too. `rea environment-serve` serves
|
||||
an environment manifest as an agent environment: an MCP server whose tools
|
||||
answer from what one retained web network capture observed, plus the
|
||||
environment card the agentenv framework reads to discover it. By default the
|
||||
server derives the [state the capture observed](#the-state-a-capture-observed)
|
||||
at startup and answers read tools from it, and the write tools whose effect the
|
||||
capture confirmed by changing it; `--replay-only` replays the capture's records
|
||||
instead. Nothing is fetched from the recorded application; every answer comes
|
||||
from retained Evidence. `rea environment-export` writes the same pair as a
|
||||
bundle folder `agent-env run` builds and runs; see
|
||||
[Export a bundle](#export-a-bundle).
|
||||
bundle folder; see [Export a bundle](#export-a-bundle).
|
||||
|
||||
```sh
|
||||
rea inspect-web-network-capture /absolute/session.har har --format json > capture.json
|
||||
@@ -36,6 +40,185 @@ The third command serves that manifest from the state it derives from the
|
||||
capture; see [Serve from the state](#serve-from-the-state). Both served files
|
||||
are complete REA Evidence JSON as the commands write it with `--format json`;
|
||||
the `evidence` member of `view.json` is the whole of `capture.json`.
|
||||
A `view.json` can also name the capture file as
|
||||
`{"kind": "evidence-file", "path": "capture.json"}`, which projects it as
|
||||
retained Evidence instead of charging the whole capture as inline input.
|
||||
|
||||
## Build a bundle in one step
|
||||
|
||||
```sh
|
||||
rea environment-build grafana.har ./grafana --json
|
||||
agent-env run ./grafana
|
||||
```
|
||||
|
||||
`rea environment-build <capture> [directory]` takes a `.har` file, or capture
|
||||
Evidence JSON from `inspect-web-network-capture` (HAR) or
|
||||
`capture-browser-scenario`, and writes the bundle
|
||||
[Export a bundle](#export-a-bundle) describes. It inspects a HAR as
|
||||
`inspect-web-network-capture` does (Evidence input skips this), projects the
|
||||
environment manifest from that Evidence as retained Evidence, authenticates
|
||||
the pair, prepares the state the bundle's server derives at startup, and
|
||||
writes the bundle with the export. For the same capture path, every file it
|
||||
writes is byte-identical to what `inspect-web-network-capture`,
|
||||
`inspect-analysis-view` and `environment-export` write, Evidence ids included,
|
||||
when `view.json` lists the same rules in the views' order and the export is
|
||||
given the build's name. It reads one file and writes one folder: it fetches
|
||||
nothing and launches no browser (HAR inspection runs REA's own decoder
|
||||
process), so record a browser scenario with `capture-browser-scenario` first
|
||||
and pass its Evidence. Other capture formats are refused, as the manifest view
|
||||
refuses them, and a HAR document saved as `.json` is refused with a hint to
|
||||
name it `.har`.
|
||||
|
||||
- `--template-rule <rule>`, repeated, replaces the default opt-in rules
|
||||
`after-uid-literal`, `opaque-token`, `sibling-variance` and
|
||||
`prefix-variance`, the rules the published capture-built environments use;
|
||||
`--format-rules-only` applies none, the views' own default. Rules apply in
|
||||
the views' fixed order, the report lists them, and a repeated rule is
|
||||
refused as the views refuse it.
|
||||
- `--name` names the env folder and env id. Without it the name is the
|
||||
manifest's, unless the capture's origin is a loopback name or an IP literal:
|
||||
the capture file then names it (`grafana.har` and `grafana.capture.json`
|
||||
become `grafana`) and a `name-from-file` warning says so. A file name that
|
||||
yields no portable label (kebab-case, at most 64 characters, not a Windows
|
||||
device name) is refused; pass `--name`.
|
||||
- `--package-tarball` works as for the export, and `--capture-timeout-ms`
|
||||
as for `inspect-web-network-capture`.
|
||||
- `--dry-run` runs every stage and prints the report with `status: "planned"`
|
||||
and the files a build would write, but writes nothing and does not check the
|
||||
directory, which may then be omitted. It reads and hashes a
|
||||
`--package-tarball` as a build does before copying it, so it refuses the
|
||||
tarballs a build refuses, including one whose contents cannot be read.
|
||||
|
||||
The directory must be absent or empty, as for the export; the build never
|
||||
replaces a folder. A refusal before the write leaves nothing behind. A capture
|
||||
Evidence file, an inspected HAR's Evidence and the projected manifest must each
|
||||
fit the live heap headroom for parsing and sealing, checked before the file is
|
||||
read or the Evidence serialized; one that does not is refused as
|
||||
`resource_constraint`. Each
|
||||
refusal names its stage: `environment-build` for the build's own checks,
|
||||
`inspect_web_network_capture` and `inspect_analysis_view` for inspection and
|
||||
projection, `environment-export` for the bundle. SIGINT cancels the build
|
||||
(`cancelled`); before the bundle stage nothing is written, and a cancellation
|
||||
during the write names the bundle it wrote. Stage progress is logged to stderr
|
||||
at info level; the report is the only output on stdout:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "built",
|
||||
"directory": "/work/grafana",
|
||||
"name": "grafana",
|
||||
"capture": {
|
||||
"evidence_id": "ev_…",
|
||||
"operation": "inspect_web_network_capture",
|
||||
"records": 105,
|
||||
"input": "har"
|
||||
},
|
||||
"manifest": {
|
||||
"evidence_id": "ev_…",
|
||||
"tools": 48,
|
||||
"excluded_groups": 0,
|
||||
"template_rules": [
|
||||
"after-uid-literal",
|
||||
"opaque-token",
|
||||
"sibling-variance",
|
||||
"prefix-variance"
|
||||
]
|
||||
},
|
||||
"state": { "served": true, "evidence_id": "ev_…" },
|
||||
"coverage": {
|
||||
"reads": {
|
||||
"state": 36,
|
||||
"recorded": 6,
|
||||
"recorded_reasons": { "query-varies": 3, "…": 1 }
|
||||
},
|
||||
"writes": {
|
||||
"served": [{ "tool": "delete_folders_by_uid", "effect": "delete" }],
|
||||
"withheld": [
|
||||
{
|
||||
"tool": "post_folders",
|
||||
"effect": "create",
|
||||
"reason": "unconfirmed",
|
||||
"hint": "No later read showed the effect. Read the entity and its list after the write.",
|
||||
"exemplar_ordinal": 94,
|
||||
"contradicted_by": null
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"tool_count": 37,
|
||||
"package_source": { "kind": "registry", "specifier": "rea-agents@…" },
|
||||
"files": [{ "path": "README.md", "bytes": 4210 }],
|
||||
"warnings": [{ "code": "name-from-file", "message": "…" }],
|
||||
"next": ["agent-env run /work/grafana"]
|
||||
}
|
||||
```
|
||||
|
||||
`coverage` is the state's read views and write plans summarized, and `null`
|
||||
when the state is unavailable and the bundle serves replay. The
|
||||
[environment coverage](web-network-captures.md#environment-coverage) view
|
||||
reports the same summary for any capture without building, so an agent can
|
||||
check it after each recording. The view summarizes the state as derived; it
|
||||
does not apply the serve-time admission checks, so for an environment whose
|
||||
served catalog exceeds the discovery budget, or whose state exceeds what
|
||||
`data/add` loads, it still reports the state while the build reports `coverage:
|
||||
null` and the bundle serves replay. Each withheld write carries a hint about
|
||||
what to record next; hints never change what is served:
|
||||
|
||||
| Reason | Hint |
|
||||
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `no-state-target` | The write's path names no collection or item the capture reads. Read the collection or item it changes. |
|
||||
| `no-call` | No recorded call of this tool was modelled, for example because every call failed. Record a successful call. |
|
||||
| `body-unusable` | The retained request or response cannot be modelled. Record a successful call with a complete supported request and reproducible response. |
|
||||
| `no-observation` | Nothing showed the entity or document this write changed. Read a created entity back by id right after the write; for an update or delete the state must already hold the entity, so read it before the write or record the create that made it. |
|
||||
| `unexplained-change` | The write changed fields it did not send, in a way no rule explains. A second, different call of the same tool can show the pattern. |
|
||||
| `contradicted` | A later read disagreed with the modelled effect. Check the read at contradicted_by. |
|
||||
| `side-effect` | The write changed something besides its own entity, which the environment does not model. |
|
||||
| `unconfirmed` | No later read showed the effect. Read the entity and its list after the write. |
|
||||
| `incomplete-entities` | The write is confirmed, but the views that show its entity cannot render it in full. Read the written entity through every view that lists it. |
|
||||
|
||||
The bundle ships `evidence.json`, the whole capture Evidence, response bodies
|
||||
included. Inspection excludes the values of the standard authentication headers
|
||||
(`Authorization`, `Cookie` and `Set-Cookie` among them) and URL userinfo; a
|
||||
custom key header such as `X-Api-Key`, a token in the query string and tokens
|
||||
an application returns in bodies remain. The environment views refuse captures
|
||||
inspected with `--sensitive-value`, so scrub a capture before building it. The
|
||||
report's `credential-named-members` warning counts recorded header names, query
|
||||
parameter names and JSON or form body members whose names look like
|
||||
credentials (whole name segments such as `token`, `secret`, `password`,
|
||||
`api_key`, `authorization` or `session`) and hold a value, and lists the first
|
||||
20 by record and pointer, never by value. A body is read as a form or as JSON by
|
||||
its recorded media type, or by its shape when it has none or one naming
|
||||
neither. A browser scenario is
|
||||
scanned by event (`event 4 response /token` names
|
||||
`normalized_result.events.items[4]`): every retained request and response
|
||||
content event, including a response whose request began before the browser was
|
||||
attached and a transaction no record represents, and each transaction URL's
|
||||
query once. Bodies larger than 4 MiB of UTF-8 text are not
|
||||
scanned; `credential-scan-incomplete` counts them and lists up to 20 record or
|
||||
event pointers, including base64 bodies whose decoded scan was cut. An empty name
|
||||
warning does not establish that these bodies were checked. Names do not establish sensitivity,
|
||||
so the build never refuses on them. Capture
|
||||
|
||||
Evidence also records the capture file's absolute path (`subject.local_path`,
|
||||
`parameters.capture_path`, `locations`, `artifact.path`), and the bundle
|
||||
carries it: build from a neutral folder when that path should not ship.
|
||||
|
||||
Over MCP, `export_environment_bundle` builds the same bundle and returns the
|
||||
same report. Its `source` is capture Evidence the session retained
|
||||
(`{"kind": "retained-evidence", "evidence_id"}`), such as a
|
||||
`capture_browser_scenario` or `inspect_web_network_capture` result, or a
|
||||
capture Evidence file (`{"kind": "evidence-file", "path"}`); inspect a HAR with
|
||||
`inspect_web_network_capture` first. Retained Evidence is written into the
|
||||
bundle as `--format json` writes it, so the bundle is the one
|
||||
`environment-build` writes from that file. `output_directory` must be an
|
||||
absolute path that does not exist yet, whose parent does; the tool creates it
|
||||
and refuses an existing directory, empty or not. `name`, `template_rules`,
|
||||
`package_tarball` and `dry_run` work as `--name`, `--template-rule`,
|
||||
`--package-tarball` and `--dry-run` do, and retained Evidence has no file to
|
||||
name the environment after, so a loopback or IP origin needs `name`. Unlike
|
||||
`--dry-run`, `dry_run` still checks `output_directory`. Destination refusals
|
||||
name `export_environment_bundle`; the others name their stage as
|
||||
`environment-build`'s do.
|
||||
|
||||
## From a browser scenario
|
||||
|
||||
@@ -125,6 +308,51 @@ the replayed body is the bytes the browser exposes for each response, with any
|
||||
declared secret replaced by its redaction marker (a body that redaction had to
|
||||
empty replays no body).
|
||||
|
||||
To record writes, sign in through the UI and then send the application's API
|
||||
calls with [request steps](browser-scenario-contract.md#request-steps): each
|
||||
sends one request to the start origin through the page's own `fetch`, with the
|
||||
session's cookies, and a header can carry the CSRF cookie or stored token the
|
||||
application's own requests send. A write is served only when the capture shows
|
||||
its effect, so read each collection before writing, read every written entity
|
||||
back by id and in its list right after the write, and leave more than a second
|
||||
between a create and its first edit. A request step's path is fixed when the
|
||||
scenario is written and cannot use a value an earlier response returned, so an
|
||||
id must be known before the run: one the caller chooses, such as a `uid` in the
|
||||
create body, or one an earlier scenario created. When the server assigns ids,
|
||||
read the list after each create (the create's response or the list shows the
|
||||
new entity), and record updates and deletes in a second scenario that reads
|
||||
the first one's objects by id before editing them, or make them through the
|
||||
UI. The environment coverage view names each
|
||||
write it withholds and what to record next. A scenario with write requests
|
||||
changes the application's data: record against an instance whose data may
|
||||
change.
|
||||
|
||||
```json
|
||||
{
|
||||
"step_id": "create-folder-1",
|
||||
"action": "request",
|
||||
"method": "POST",
|
||||
"path": "/api/folders",
|
||||
"headers": [
|
||||
{
|
||||
"name": "X-CSRFToken",
|
||||
"value": { "source": "cookie", "name": "csrftoken" }
|
||||
}
|
||||
],
|
||||
"json": { "title": "Scratch folder 1" },
|
||||
"expected_status": [200, 201]
|
||||
}
|
||||
```
|
||||
|
||||
Each record takes its start and duration from the browser's timing (the time
|
||||
the scenario observed the request where the browser reported no start), so the
|
||||
state orders and overlaps
|
||||
records as it does a HAR's and learns a write clock: an update the application
|
||||
stamps with a modification time can be served. A scenario captured before
|
||||
these times were recorded has none; its records keep request order and the
|
||||
state learns no clock, so such updates stay `unexplained-change` until it is
|
||||
recorded again.
|
||||
|
||||
## What a manifest is
|
||||
|
||||
An environment manifest is a projection of one application's recorded request
|
||||
@@ -431,12 +659,12 @@ member reports which applied:
|
||||
|
||||
Each read tool answers according to its view in the state:
|
||||
|
||||
| View | Answer |
|
||||
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `item` | The entity the path arguments name, rendered into the recorded envelope of `envelope_ordinal`. Arguments match as replay matches them: each collection segment equals the held collection's segment as written or after percent-decoding, and the identity is the last argument percent-decoded, then as written; values are never re-split on `/`. Any entity the state holds answers, including one `data/add` loaded; query arguments only decide `replay.exact_match`. An entity the state does not hold answers the tool's latest recorded 400, 404 or 410 response with `state.view` `missing`, or is a tool error when none was recorded; one lacking a field every recording carried is a tool error, unless a read showed the application leaves that field out; a body is never invented. |
|
||||
| `list` | When the arguments name one of the lines the view checked exactly (its latest recordings before the first related write; every path and query value equal to the recording's, and every recorded query parameter supplied), that recorded envelope with its array rendered from the state: every entity of the collection in state order for `membership: "all"` or a line `all_record_ordinals` names, or the recorded members still held. A call with no query argument answers from such a line of the collection its path arguments name that only pages its list, with `replay.exact_match` false. On a line the view's `query` answers, and for a call whose every query argument has a role there (an argument-less call aside), the answer is the query evaluated over the state: filtered, searched, sorted and paged, with counters at the number listed and `query.totals` at the number matched, and `state.membership: "query"`; such a call answers on a query or whole line of its collection with `replay.exact_match` false. A value an `inert` parameter never recorded, or a parameter without a role, replays its recording. A member lacking a field every recording carried makes the call a tool error rather than a partial list. |
|
||||
| `document` | When the arguments name the document's checked line exactly, the state's value for it; a tool error when the state holds none. |
|
||||
| `recorded` | The recording, as replay answers it. |
|
||||
| View | Answer |
|
||||
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `item` | The entity the path arguments name, rendered into the recorded envelope of `envelope_ordinal`, whose `per_response_members` (such as a request id), like a list's or a document's, keep their recorded values. Arguments match as replay matches them: each collection segment equals the held collection's segment as written or after percent-decoding, and the identity is the last argument percent-decoded, then as written; values are never re-split on `/`. Any entity the state holds answers, including one `data/add` loaded; query arguments only decide `replay.exact_match`, except that a call matching one of the view's `projected_query_keys`, or on a view with `projected_record_ordinals` asking for some fields only with a value other than `*` no checked line gave or one a replayed read gave, replays its recording. An entity the state does not hold answers the tool's latest recorded 400, 404 or 410 response with `state.view` `missing`, or is a tool error when none was recorded; one lacking a field every recording carried is a tool error, unless a read showed the application leaves that field out; a body is never invented. |
|
||||
| `list` | When the arguments name one of the lines the view checked exactly (its latest recordings before the first related write; every path and query value equal to the recording's, and every recorded query parameter supplied), that recorded envelope with its array rendered from the state: every entity of the collection in state order for `membership: "all"` or a line `all_record_ordinals` names, or the recorded members still held. A call with no query argument answers from such a line of the collection its path arguments name that only pages its list, with `replay.exact_match` false. On a line the view's `query` answers, and for a call whose every query argument has a role there (an argument-less call aside), the answer is the query evaluated over the state: filtered, searched, sorted and paged, with counters at the number listed and `query.totals` at the number matched, and `state.membership: "query"`; such a call answers on a query or whole line of its collection with `replay.exact_match` false. A value an `inert` parameter never recorded, a parameter without a role, a call matching one of the view's `projected_query_keys`, or a field selection the checked lines do not show (as for `item`), replays its recording. A member lacking a field every recording carried makes the call a tool error rather than a partial list. |
|
||||
| `document` | When the arguments name the document's checked line exactly, the state's value for it; a tool error when the state holds none. |
|
||||
| `recorded` | The recording, as replay answers it. |
|
||||
|
||||
A read with repeated query values uses replay, because the state query model
|
||||
does not infer repeated-parameter semantics. A repeated-query write is refused
|
||||
@@ -451,18 +679,36 @@ An item or list view that always spells a clock field otherwise than the
|
||||
entity's stored value names that spelling in `clock_formats`, and a value it
|
||||
never recorded, such as a created entity's clock, is rendered in it: a list that
|
||||
writes `+00:00` where item reads write `Z` lists a new entity the same way.
|
||||
A view that names a field in `sorted_arrays` lists that string array sorted, as
|
||||
a read-back showed the application does, while the state keeps it in the order
|
||||
it was written, so a write's own answer echoes it. If a later counted read
|
||||
contradicts that ordering, the view stays recorded and its earlier reads no
|
||||
longer confirm served writes. A view that names a field in `nested_fields`
|
||||
always showed that field's objects with the same keys, in any order, and fewer
|
||||
than an entity stores, such
|
||||
as a list showing a parent without the parent's own nested type; a stored
|
||||
object it never recorded, such as a created entity's parent, is rendered with
|
||||
those keys. Members a view names in
|
||||
`per_response_members`, such as a request id each response mints, keep the
|
||||
value its recording carried. A list's `counters` and `query.totals` are
|
||||
top-level members or members one level down in a paging object
|
||||
(`/pageInfo/totalRows`); either is set to the number listed or matched, and
|
||||
members beside it such as `isLastPage` stay as recorded.
|
||||
|
||||
A list or document call that names no checked line, including a line recorded
|
||||
after a write or with other query values, answers from the recording. Every
|
||||
answer has the replay shape plus `state`: `{"source": "state", "view": …}`
|
||||
naming the entity, collection or document path, or `{"source": "recording",
|
||||
"reason": …}` with the view's reason, `no-view`, `unrecorded-request`, `page-exceeded` (a call naming a page of a whole list that the collection has outgrown) or `projection` (a call to an item tool whose recordings asked for some fields only, naming such a parameter for an entity the state holds; the answer is a recording, so it does not show served writes). A
|
||||
"reason": …}` with the view's reason, `no-view`, `unrecorded-request`, `page-exceeded` (a call naming a page of a whole list that the collection has outgrown), `projection` (a call to an item or list tool with replayed reads asking for a selection of fields the checked lines do not show, or leaving out a projection parameter every checked line names) or `variant` (a call matching another `projected_query_keys` key: a parameter, or a value of one, only lines showing the entities in another representation named, or leaving out a parameter every other line named). A `projection` or `variant` answer is a recording, so it does not show served writes. A
|
||||
state answer carries the base record's status, content type and `replay`
|
||||
provenance with `truncated: false`; one whose JSON would exceed 256 KiB is
|
||||
refused as a `resource_constraint` tool error rather than cut. Extraction does
|
||||
not state-back a document whose rendered JSON exceeds 256 KiB; that read stays
|
||||
recorded (`rendered-oversize`) and replays the captured body. Query `POST`s
|
||||
stay served and answer from their recordings with the reason `query-body`.
|
||||
recorded (`rendered-oversize`) and replays the captured body. Query `POST`s,
|
||||
and `POST` tools the capture shows only reading (a lookup answering as a `GET`
|
||||
did, an RPC tunnel naming read operations, a session renewal), stay served and
|
||||
answer from their recordings with the reason `query-body`; they are not write
|
||||
tools.
|
||||
|
||||
A line establishes whole-collection membership only from the beginning:
|
||||
`offset`, `start`, `_start` and `page` must be zero when present. Positive or
|
||||
@@ -477,20 +723,38 @@ tools are not served, so no call claims a change it does not make; each one's
|
||||
plan states why in its `reason`. A served write changes the live state, which
|
||||
every MCP session and `data/get` then see:
|
||||
|
||||
| Effect | Call |
|
||||
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `create` | Adds an entity to the collection the path names, built from the observed entity with each ruled field taken from the call or generated, at the plan's `insert` position. A plan tied to its exemplar's collection writes only there. |
|
||||
| `update` | Sets the sent members on the entity the path names, constants for members accepted only with their recorded value, and the clock, increment, slug, unique and renewed changes the plan models. |
|
||||
| `delete` | Removes the entity the path names. |
|
||||
| `document` | Merges the body into the plan's document object, or replaces it for `PUT`. |
|
||||
| Effect | Call |
|
||||
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `create` | Adds an entity to the collection the path names, built from the observed entity with each ruled field taken from the call or generated, at the plan's `insert` position. A plan tied to its exemplar's collection writes only there. |
|
||||
| `update` | Sets the sent members on the entity the path names, constants for members accepted only with their recorded value, and the clock, nested clock, increment, slug, stamp, derived, composed, reference, unique and renewed changes the plan models. |
|
||||
| `update` (action) | A `POST`, `PUT` or `PATCH` to an item path plus an action segment (`/{type}/{id}/archive`) sets, on the entity before the segment, each scalar the recorded calls showed the action set (`set`), with any sent members; it is served only when a recorded call found those fields already set, so a toggle never is. |
|
||||
| `delete` | Removes the entity the path names. |
|
||||
| bulk `update` or `delete` | A `DELETE`, `PUT` or `PATCH` at a collection, or a `POST` to it plus `delete`, `remove` or `destroy`, applies its effect to every entity the body names, as recorded: an array of ids or of objects carrying the id field, at the root or as the body's one array member (`{"IDs": […], "Read": true}`). |
|
||||
| `document` | Merges the body into the plan's document object, or replaces it for `PUT`. |
|
||||
|
||||
An update's unsent changes follow the plan's rules. A `held-clock` is a clock
|
||||
the client sends back as it read it and the application stamps anew (Ghost's
|
||||
`updated_at`): the call must send the entity's value and the field takes the
|
||||
write's clock. A `nested-clock` sets the clocks inside an object the entity
|
||||
holds, in that object's recorded format. A `stamp` writes the acting user
|
||||
the entity already names under its `created…by` counterpart into a
|
||||
`modified…by` or `updated…by` field. A `derived` field takes a value showing
|
||||
the one sent member's text that the entity stores nowhere (a field Ghost
|
||||
derives from `html`), only with that member's recorded value. An action's
|
||||
`set` rule sets a scalar to the value the recorded calls left it at.
|
||||
|
||||
Its answer has the status and content type of the plan's recorded response,
|
||||
with the written entity or its identity rendered in, no body, or the recorded
|
||||
body. A call whose body is not an object, sends a member the capture did not
|
||||
show stored, sends a fixed member with another value or a member of another
|
||||
JSON type, or lacks a required member is a tool error naming the accepted
|
||||
members; so is a rendered answer missing a field the recorded response
|
||||
carried, and an update or delete of an entity the state does not hold answers
|
||||
members; so is a call sending query parameters other than the exemplar's (they
|
||||
may change what the body does), a body not wrapped in the exemplar's envelope
|
||||
(Ghost's `{"posts": [{…}]}`), a bulk call naming an id the state does not hold,
|
||||
a `held-clock` member sent with another value than the entity holds, a call
|
||||
sending a `derived` rule's member to an entity that does not hold the value the
|
||||
recorded call found, a nested clock on an entity holding no such object, and a
|
||||
rendered answer missing a field the recorded response carried, and an update or delete of an entity the state does not hold answers
|
||||
the recorded 400, 404 or 410 of the tool or of an item view of the type, if
|
||||
any. A refused call leaves the state unchanged. Values a write generates are
|
||||
deterministic: the clock starts at `write_clock` and advances one second per
|
||||
@@ -499,7 +763,8 @@ largest they generated, and UUIDs and tokens derive from the state Evidence
|
||||
id, tool, field and write count, skipping held values. `data/reset` and
|
||||
`data/add` restart the clock, counter and sequences, so the same calls after a
|
||||
reset give the same state. Answers carry `state: {"source": "state", "view":
|
||||
"create" | "update" | "delete", …}` or `"document-write"`.
|
||||
"create" | "update" | "delete", …}` or `"document-write"`; a bulk answer adds
|
||||
`ids`, every entity it wrote in body order, with `id` naming the first.
|
||||
|
||||
The data plane serves three JSON-RPC methods:
|
||||
|
||||
@@ -654,6 +919,25 @@ after an update and referential rules on delete are not modelled. An exported
|
||||
bundle carries no state file: its server derives the state at startup, as the
|
||||
export does to predict what it serves.
|
||||
|
||||
Known limits of served writes:
|
||||
|
||||
- A recorded view answers from its recordings after a served write: Mailpit's
|
||||
`get_messages`, recorded as `list-differs`, still lists a message a served
|
||||
delete removed.
|
||||
- Served n8n workflow updates accept any `versionId`, while served Ghost post
|
||||
updates require `updated_at` to match the entity (a `held-clock`).
|
||||
- A slug derived from a title can repeat across served creates with the same
|
||||
title, where the application would make it unique.
|
||||
- A `composed` string copies sent text as sent: an application that escapes or
|
||||
renders it (HTML entities, Markdown) differs for text that needs it, as
|
||||
BookStack's `description_html` would for a description holding `&`.
|
||||
- A served create's sequence id is the state's next value, not the gaps an
|
||||
application's own sequence would leave.
|
||||
- Nested clocks are served in the spelling of the write's own response, which
|
||||
can differ from what a later read of the application shows.
|
||||
- A served write to an entity that a replayed (unserved) create made answers
|
||||
as for a missing entity, since the state never held it.
|
||||
|
||||
## Export a bundle
|
||||
|
||||
`rea environment-export` writes the same pair as a bundle folder the agentenv
|
||||
@@ -781,9 +1065,11 @@ Numeric arrays retain that containing field's clock context through nested
|
||||
arrays; an object's own fields establish their own context. Numeric values at
|
||||
the body root, in root arrays, or under measurement fields remain literal.
|
||||
|
||||
Generated strings normalize only where this confirmed, served write's entity
|
||||
response rules identify generation. A `unique` rule or UUID identity rule must
|
||||
still compare two UUIDs; a `renewed` rule applies only at its recorded pointers,
|
||||
Generated values normalize only where this confirmed, served write's entity
|
||||
response rules identify generation. A UUID identity rule must still compare two
|
||||
UUIDs, and a `unique` rule two UUIDs or two generated integers (10 to 20
|
||||
digits) of one JSON kind and length; a `renewed` rule applies only at its
|
||||
recorded pointers,
|
||||
with `*` matching actual array items. Token/sequence strings retain the existing
|
||||
format check: equal length of at least eight, the same character classes, and
|
||||
a digit. Numeric sequences continue to compare literally unless an ID mapping
|
||||
@@ -795,6 +1081,12 @@ Admitted generated values must also preserve aliases and distinct identities
|
||||
within that response. UUID identity uses the generator's case-insensitive
|
||||
matching; token and sequence strings retain their literal identity. This
|
||||
correspondence ends with the answer and is not inferred across calls.
|
||||
A `composed` response field must spell the value its parts build from that
|
||||
response's own fields. Its parts then compare by their rendered text or their
|
||||
source fields' clock and ID rules. A coherent archive URL can therefore differ
|
||||
only in normalized clock digits without reporting a value difference; an
|
||||
incoherent URL still differs even when both sides repeat the same stale text.
|
||||
Normalized compositions count under `generated`; source fields are counted once.
|
||||
The report counts each kind of normalised
|
||||
value; the generation rules remain model-derived facts, rather than new
|
||||
observations of the application.
|
||||
|
||||
@@ -34,6 +34,53 @@ One-shot CLI output remains complete. Older servers require the existing complet
|
||||
request after schema discovery. APK authenticity and runtime behavior remain
|
||||
unverified.
|
||||
|
||||
## Manifest component projection
|
||||
|
||||
`inspect_android_package` also returns a static inventory of declared
|
||||
activities, aliases, services, receivers and providers from the decoded
|
||||
manifest. `declared_name` preserves the source attribute; `name` resolves a
|
||||
relative name only when the manifest package is known and the resolved copy
|
||||
fits the UTF-8 byte budget. An unresolved package or exhausted name budget
|
||||
retains the declared name and marks the inventory partial. Empty component
|
||||
names and names with forbidden DEX characters retain their raw spelling and
|
||||
are not treated as identities. Valid DEX spaces, including boundary spaces,
|
||||
are preserved when resolving component names and matching alias targets.
|
||||
Whitespace in the manifest package is rejected by its separate package grammar.
|
||||
Component permissions inherit the application
|
||||
permission when no component permission is declared, except an activity alias
|
||||
with no permission: Android documents that case as requiring no permission
|
||||
through the alias. `permission_source` distinguishes a local declaration,
|
||||
inherited value, no requirement (including an explicit empty override), and a
|
||||
value omitted because its resource/manifest-placeholder token is unresolved
|
||||
or the total permission-byte budget was reached. Resource and placeholder
|
||||
references are not expanded at this parser boundary. Repeated inherited
|
||||
values share one inventory-wide byte budget.
|
||||
Provider `android:readPermission` and `android:writePermission` overrides are
|
||||
not projected as separate fields; their presence marks the inventory partial
|
||||
and is called out in `limitations`. Relative component names are not resolved
|
||||
against a manifest package with surrounding whitespace.
|
||||
Class-name segments follow DEX `SimpleName` characters, including a leading
|
||||
digit or hyphen, rather than Java source identifier rules. Relative-name
|
||||
expansion does not prove class existence, DEX-version compatibility or runtime
|
||||
loadability. SDK defaults accept JADX's decimal and hexadecimal integer
|
||||
spellings; the original SDK declaration strings remain unchanged.
|
||||
|
||||
`exported` is the declared literal `true` or `false`, otherwise null.
|
||||
`exported_default` is the documented default only where it can be established;
|
||||
it remains null for unknown provider target SDKs, nonliteral declarations, or
|
||||
components with filters targeting API 31 or later that omit the now-required
|
||||
explicit declaration. A limitation records the latter validation error.
|
||||
Provider authorities and all inventory dimensions are bounded. `status:
|
||||
"partial"` and `limitations` identify omitted declarations or values; a
|
||||
capacity limitation appears only when an actual collection limit was reached.
|
||||
The projection does not merge manifests, expand resource references, or
|
||||
observe runtime enabled/export state.
|
||||
|
||||
The service `foreground_service_type` field preserves the declared attribute,
|
||||
including an empty value or surrounding spaces; `null` means the attribute is
|
||||
absent or the component is not a service. This field does not validate service
|
||||
type tokens or establish runtime eligibility.
|
||||
|
||||
## Supply tools
|
||||
|
||||
Use a **full JDK 17 or newer** (including its compiler module) and
|
||||
@@ -147,6 +194,21 @@ queries accept the same `overload_index`; the bridge resolves the selected
|
||||
method node and the result reports its index and displayed signature. These
|
||||
indices are tied to the current artifact and engine, not stable across builds.
|
||||
|
||||
`inspect_android_class` also reports `dex_static_value` for each `static final`
|
||||
field whose class definition encodes a value in its DEX static values, so
|
||||
compile-time constants are readable even when the class has no `<clinit>`.
|
||||
Each value is typed: `boolean`, `byte`, `short`, `char` (UTF-16 code unit) and
|
||||
`int` values are JSON booleans or numbers, while `long`, `float` and `double`
|
||||
values are strings holding Java's text for the value, so 64-bit values stay
|
||||
exact. The field reports `null` when no value is encoded, the encoded value is
|
||||
null or of another kind, or the field is not `static final`. The value is read from parsed
|
||||
metadata without generating source, and a static initializer can still assign
|
||||
the field; use `inspect_android_method` on `<clinit>` for that evidence.
|
||||
Only `inspect_android_class` asks the bridge for these values.
|
||||
`inspect_android_method` and `trace_android_references` read the member-only
|
||||
class summary, so large encoded strings cannot push their member lookup past
|
||||
the 8 MiB protocol frame limit.
|
||||
|
||||
Smali fallbacks select one complete block using the original method name and DEX
|
||||
descriptor, before applying the source byte limit. This preserves the selected
|
||||
overload even when Java code generation renames a method. If the selected Java
|
||||
@@ -193,6 +255,13 @@ the same source byte limit and explicit truncation reporting.
|
||||
full reported display types, fields and inner class names. Synthetic members
|
||||
that code generation hides can appear in the inventory; it stays consistent
|
||||
after method decompilation within the retained session.
|
||||
Class and method inspection and reference tracing accept either the exact
|
||||
reported class name or its original binary name, including `$` in nested and
|
||||
anonymous classes. The bridge keeps both identities from JADX; it does not
|
||||
replace separators or guess suffix matches. Ambiguous selectors are refused.
|
||||
Follow-up calls preserve the selected name, while results report the frozen
|
||||
JADX display name. Quote `$` names in the shell, for example
|
||||
`'com.example.Manager$WorkerThread'`.
|
||||
Exact DEX prototypes are reported from frozen JADX method metadata as
|
||||
`dex_descriptor`, for example `(I)V`. Display names can be JADX aliases;
|
||||
the descriptor alone is not a complete raw DEX method ID. Overload indices
|
||||
|
||||
@@ -239,13 +239,19 @@ serialized size of the report together with its limitations (which repeat
|
||||
archive names) is then checked against an 8 MiB output budget (the exact check
|
||||
is authoritative); an over-budget report is refused, not truncated.
|
||||
|
||||
The whole-file reader retains read chunks and a concatenated buffer; total
|
||||
process memory exceeds the selected file's size. It also computes the complete
|
||||
The whole-file reader allocates the selected snapshot and bounded read scratch;
|
||||
total process memory exceeds the selected file's size. It also computes the complete
|
||||
file SHA-256, so inspection is not header-only. Content digests are recomputed
|
||||
at most once per SHA-256/SHA-512 algorithm during one inspection. Input,
|
||||
inflation, decoded-record and serialized-output bounds keep work finite;
|
||||
resource refusals are distinct from malformed format errors.
|
||||
|
||||
If the stable read completes but closing its descriptor fails or is cancelled,
|
||||
the error retains `details.partial_observation` with the selected path, complete
|
||||
file SHA-256 and byte count. These facts describe the acquired file; they do not
|
||||
establish any decoded signing facts. Failed cleanup remains visible until the
|
||||
provider releases the descriptor on a cleanup retry.
|
||||
|
||||
A file that is not a ZIP is refused as an unsupported target. A damaged ZIP
|
||||
(local headers but no end-of-central-directory), a central directory that
|
||||
cannot be walked or whose declared record count does not account for all of
|
||||
|
||||
@@ -213,6 +213,9 @@ Resolution follows dyld:
|
||||
already loaded image reuses it.
|
||||
- Symlinks such as `Versions/Current` are followed inside the analyzed root.
|
||||
An escape through `..` or an absolute link is `escapes-target`.
|
||||
- Dyld path components are POSIX names. On Windows hosts, link text uses `\`
|
||||
as its separator, and a dyld component that contains `\` or `:` cannot name
|
||||
a file in the analyzed root, so its candidate is `absent`.
|
||||
|
||||
Each edge lists every candidate path tried, with its outcome: `resolved`,
|
||||
`absent`, `not-mach-o`, `malformed`, `unsupported` (recognized Mach-O outside
|
||||
|
||||
@@ -0,0 +1,112 @@
|
||||
# Apple IPS crash reports
|
||||
|
||||
`inspect_apple_ips` / `inspect-apple-ips` answers whether one selected local
|
||||
Apple `.ips` file is a crash report (`bug_type` string `"309"`), which process,
|
||||
exception, and termination facts that report records, which threads and
|
||||
`usedImages` rows it lists, and which documented crash classes its strings
|
||||
match. It reads the file without executing a target and does not require Xcode,
|
||||
atos, a disassembler, or pwntools.
|
||||
|
||||
```bash
|
||||
rea inspect-apple-ips /absolute/path/to/report.ips --json
|
||||
```
|
||||
|
||||
The CLI resolves relative paths against the caller's working directory. MCP
|
||||
requires an absolute filesystem path and preserves that exact selection:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "inspect_apple_ips",
|
||||
"arguments": { "path": "/artifacts/report.ips" }
|
||||
}
|
||||
```
|
||||
|
||||
## Observations
|
||||
|
||||
The inline Evidence result contains the artifact path, SHA-256, and byte length.
|
||||
`metadata` is the first-line JSON object. `bug_type` stays a string. The crash
|
||||
body is parsed only when that string is `"309"`. Other types, including `"288"`
|
||||
stackshots, return no crash result.
|
||||
|
||||
`process`, `exception`, `termination`, `faulting_thread`, `threads`, and
|
||||
`images` reproduce documented body fields when present. Integers keep their
|
||||
decimal literals and a hexadecimal form, including arm64e registers above
|
||||
2^53. Frame roles follow the recorded frame index: row zero of the resolved
|
||||
faulting thread is `faulting_instruction`, row zero of other threads is
|
||||
`current_instruction`, and later rows are `return_address`. Each runtime
|
||||
address uses that row's own image base and offset. The recorded `inline` flag
|
||||
does not supply a missing offset or authorize borrowing another row's address.
|
||||
When `faultingThread` is missing or does not resolve to a recorded thread
|
||||
object, row-zero roles are `unknown`; the recorded lookup remains available.
|
||||
Observed JSON strings retain `""`; `null` means the field was missing or JSON
|
||||
`null`. This includes image paths, frame symbols, process text, and the older
|
||||
string `osVersion` form. Unlisted JSON keys and generic register names also
|
||||
retain empty spellings. An empty image architecture remains recorded as `""`
|
||||
while `uuid_unknown` stays true, since that spelling does not establish an
|
||||
architecture. An empty UUID is malformed, so its exact spelling appears in
|
||||
`coverage.type_mismatches` and its canonical UUID remains unknown.
|
||||
`process.os_version` keeps the producer's dictionary (`train`, `build`,
|
||||
`release_type`, `is_embedded`) or the older string form. Image UUIDs are uppercase 8-4-4-4-12; an all-zero UUID
|
||||
or a missing or empty `arch` is `uuid_unknown`. Image `source` letters keep their
|
||||
documented meaning (`P` process, `S` shared cache, `C` shared cache library,
|
||||
`K` kernel, `U` kernel cache, `T` kernel text exec, `A` absolute). Keys the
|
||||
documentation does not list remain in `unlisted_keys` or `unlisted_body_keys`.
|
||||
|
||||
Each frame's `image_index` refers to its entry in `images`. Image architecture,
|
||||
UUID and `uuid_unknown` are retained once on that image. Resolve the reference
|
||||
when using those facts; an absent or out-of-range index leaves the image
|
||||
unknown. This avoids repeating image text for every stack frame.
|
||||
|
||||
A present value whose JSON type differs from the documented one is never read
|
||||
as absent: it is listed in `coverage.type_mismatches` with its path, the
|
||||
expected type, and the observed type, and `coverage.status` becomes
|
||||
`partial`. A crash body without `threads` or `usedImages` is also `partial`.
|
||||
Malformed image UUID strings likewise make coverage partial; their exact spelling
|
||||
is retained in the mismatch's `recorded_value`, while the canonical image UUID
|
||||
remains unknown. Both 32 hexadecimal digits and canonical hyphenated UUIDs are accepted.
|
||||
Unresolved thread/image references also make coverage partial. A rejected
|
||||
integer lookup keeps its exact decimal literal in `recorded_integer`, including
|
||||
negative values and values above uint32. Valid uint32 lookup values remain in
|
||||
`faulting_thread` or `image_index` even when the referenced row is unavailable.
|
||||
|
||||
`classification` matches only documented SIGKILL codes (compared by their
|
||||
canonical hexadecimal form), `EXC_GUARD` subtypes,
|
||||
pointer-authentication suffixes, and dyld missing-library strings. A report
|
||||
that matches none of those rules is `unclassified`.
|
||||
|
||||
Opened Mach-O and dSYM UUID joins remain unobserved. Symbol names printed
|
||||
inside the report are recorded claims and are not verified. Linux ELF cores
|
||||
use the separate [recorded crash](recorded-crashes.md) workflow.
|
||||
|
||||
## Limits and failures
|
||||
|
||||
The selected file is limited to 1 MiB by default (16 MiB maximum). At most 256
|
||||
threads, 8192 frames, 1024 `usedImages` rows, and 16384 `threadState`
|
||||
register slots are examined by default (4096 / 65536 / 4096 / 262144
|
||||
maximum). Budgets are checked before each row is parsed, and body members the
|
||||
report does not interpret are syntax-checked without being kept. Fixed
|
||||
allowances bound JSON nesting (64 levels), unlisted key names per object
|
||||
(1024), and `termination.reasons` entries (256). Malformed metadata, a
|
||||
truncated crash body, invalid UTF-8, a NUL in the text, and exhausted budgets
|
||||
fail without partial success.
|
||||
|
||||
`max_integer_text_bytes` (`--max-integer-text-bytes` in the CLI) separately
|
||||
bounds retained decimal and hexadecimal integer text, including every derived
|
||||
runtime address and rejected lookup literal. Its default is 8 MiB of UTF-16 text storage and its maximum is
|
||||
64 MiB. Each appearance counts, even when an object could be shared in memory
|
||||
but would be serialized more than once. The parser reserves a conservative
|
||||
upper bound before numeric conversion or address expansion, then releases the
|
||||
unused reservation after each value. It reuses the parsed source integer when
|
||||
the same image base contributes to many frames.
|
||||
|
||||
Raise this per-call allowance on the next call when more room is needed; no
|
||||
restart is required. File-size and row budgets do not raise it. This allowance
|
||||
is separate from JSON wire size, MCP response limits and the client's receive
|
||||
buffer. An exhausted allowance reports a typed resource error without partial
|
||||
success or truncated integer facts.
|
||||
|
||||
```bash
|
||||
rea inspect-apple-ips /absolute/path/to/report.ips --max-integer-text-bytes 16777216 --json
|
||||
```
|
||||
|
||||
This workflow does not execute a target, launch atos, or search for dSYMs.
|
||||
@@ -23,7 +23,7 @@ graph TD
|
||||
SESSION["SessionProviderRouter + BinarySession<br/>one immutable deep binding per target<br/>disjoint auxiliary routing"]
|
||||
REGISTRY["AnalysisProviderRegistry<br/>sorted deep candidates<br/>deterministic selection, no fallback"]
|
||||
RECORDS["src/application/investigation/<br/>composed InvestigationRecords + narrow ports<br/>EvidenceLedger and Unknown ownership"]
|
||||
SNAPSHOT["BinarySessionRecords + AnalysisSnapshotCache<br/>binary target/profile snapshots<br/>compatibility facade and post-commit notifications"]
|
||||
SNAPSHOT["BinarySessionRecords + AnalysisSnapshotCache<br/>binary target/profile snapshots and session file ownership<br/>record coordination and post-commit notifications"]
|
||||
JS_RECON["src/application/javascript/ + src/artifacts/javascript/<br/>JavaScript artifact reconstruction<br/>directory/ASAR reads<br/>AST-only bundle projection"]
|
||||
end
|
||||
|
||||
@@ -75,7 +75,7 @@ graph TD
|
||||
end
|
||||
|
||||
subgraph "Domain Layer"
|
||||
DOMAIN["src/domain/<br/>Pure side-effect-free modules<br/>evidence, comparisons, application graphs"]
|
||||
DOMAIN["src/domain/<br/>Pure side-effect-free modules<br/>format declarations, Evidence, comparisons, application graphs"]
|
||||
end
|
||||
|
||||
subgraph "Configuration"
|
||||
|
||||
@@ -100,6 +100,8 @@ one section or symbol, or a stable page without re-running the decoder. CLI
|
||||
one-shot invocations pass portable inline Evidence JSON; an MCP session uses
|
||||
the retained `evidence_id`. Page `limit` is required and bounded by the
|
||||
measured MCP stdio budget documented on the tool contract.
|
||||
An empty retained section or symbol collection has no valid item index. Its page
|
||||
view can still return an empty page.
|
||||
Malformed authenticated layout input remains rejected with the owning schema's
|
||||
safe field diagnostics under `source.normalized_result`, including the field
|
||||
path and type or value reason. Evidence authentication and decoder validation
|
||||
|
||||
@@ -94,6 +94,14 @@ content. Actual JSON properties with those names remain content. Reference-only
|
||||
objects, unsupported values, and opaque cookie partition identities remain
|
||||
incomplete. Previously exported fingerprints are not recomputed; recapture both
|
||||
sides when comparing captures produced across this decoder change.
|
||||
IndexedDB schema fingerprints with `projection_version: 2` include the observed
|
||||
database version and object-store definitions. A missing, malformed, or imprecise
|
||||
version leaves the schema fingerprint incomplete while retaining observed store
|
||||
facts. Historical fingerprints without this marker covered object stores only:
|
||||
matching historical hashes cannot establish unchanged database versions, and a
|
||||
historical hash is not compared with a version-bearing hash. Recapture both
|
||||
sides for a complete IndexedDB version comparison; other proven storage changes
|
||||
remain reportable.
|
||||
|
||||
Script comparison groups observations by reported URL and compares unordered
|
||||
content samples. Producer inventory keys include optional metadata, so a changed
|
||||
@@ -404,8 +412,12 @@ allowance; exhaustion fails the observation explicitly instead of guessing scope
|
||||
|
||||
## Data minimization
|
||||
|
||||
The Link projection parses repeated CDP header field lines independently and
|
||||
retains their declarations in order. Each link keeps its target in `href` and
|
||||
Response metadata parses repeated CDP header field lines independently. The
|
||||
Link projection retains their declarations in order. `csp.directives` lists the
|
||||
directives of every CSP policy in order, across field lines and comma-separated
|
||||
policies, without recording policy boundaries, so a directive name can repeat.
|
||||
Single-valued policy fields combine their lines as one comma-separated value,
|
||||
as RFC 9110 specifies. Each link keeps its target in `href` and
|
||||
its relationship context in `context_url` with a separate `context_scope`;
|
||||
absent `anchor` uses the response URL, while a relative `anchor` resolves
|
||||
against that URL. Anchored links remain in the projection, but a `link_rel`
|
||||
@@ -586,6 +598,22 @@ Network and console coverage starts only after REA attaches and enables the rele
|
||||
|
||||
Source maps are not fetched by inspection. Bundle analysis fetches them only when `fetch_source_maps` is selected, with exact-origin redirect checks and no credentials, cookies, or referrer. Each fetch operation uses `source_map_fetch_timeout_ms` (default 30000) and a 64 MiB aggregate streamed-response budget across redirects. The byte budget has no runtime override. A fetch overrun is an item limitation, not a thrown analysis timeout. A deadline or byte-limit failure remains explicitly unavailable and makes bundle completeness partial. Source-map decoding also bounds raw resolved identities to 64 MiB and aggregate inline evidence to 32 MiB. Failed maps preserve their failure context when it fits; if another context cannot fit, collection stops with the full requested count, the returned processed count, and an explicit unknown-results limitation. Retained mappings and original sources are returned inline. See [source-location limits](web-source-location.md) for the structural decoder bounds. Original source artifacts with `.ts`, `.tsx`, `.mts`, or `.cts` suffixes carry `text/typescript`; other source names retain `text/javascript`.
|
||||
|
||||
A fully read response that fails UTF-8, JSON, mapping, or structural validation
|
||||
retains `artifact: null`, empty original-source, module-edge, and mapping
|
||||
arrays, and an explicit failure limitation. Invalid content is `invalid`;
|
||||
decoder or structural capacity refusal is `fetch_failed`. Its optional
|
||||
`response_identity` records the complete body's SHA-256 digest, byte count,
|
||||
and `fetch-response-body-bytes` representation without retaining malformed
|
||||
text or charging that text to the 32 MiB output budget. These are bytes
|
||||
delivered by Fetch after HTTP content decoding and before UTF-8 decoding, not
|
||||
HTTP wire bytes. The identity is absent when the body was not fully read, and
|
||||
older observations may omit it. A response whose text cannot fit the existing
|
||||
output budget is likewise `fetch_failed` with text omitted and completed-body
|
||||
identity; JSON parsing and source-map decoding are not attempted. Successful and partial maps keep their
|
||||
full text artifacts. Their original text, including an initial BOM or XSSI
|
||||
line, remains distinct from the parsing view that removes that framing.
|
||||
Collection reads the body once and does not raise its response or output limits.
|
||||
|
||||
When fetching is selected, source-map `excluded` facts preserve the capture
|
||||
ledger's reasons and counts for declarations rejected before download. No
|
||||
disallowed URL details are retained or fetched. `requested` and `processed`
|
||||
@@ -593,6 +621,17 @@ count the admitted fetch requests; exclusions are counted separately. Excluded
|
||||
declarations make the collection unavailable, or partial when maps were retained.
|
||||
An empty collection with no declarations remains `not_requested`.
|
||||
|
||||
If the caller cancels while later source maps are being fetched, the failure's
|
||||
partial Evidence retains the captured page and every completed map item. Its
|
||||
`normalized_result.kind` is `web-bundle-acquisition` and
|
||||
`analysis_status` is `not_performed`: no script-analysis result is claimed.
|
||||
`source_maps.requested` remains the admitted request count,
|
||||
`source_maps.processed` counts completed items, and any unprocessed requests
|
||||
have an explicit unknown-results limitation. Capture exclusions remain in the
|
||||
same collection. The cancellation error keeps the caller's exact reason;
|
||||
an already observed response resource or cleanup failure keeps its own error
|
||||
category and cleanup owner.
|
||||
|
||||
Source-map items retain the script's `declared_url` separately from the observed
|
||||
`effective_url`. Successful maps use the latter as their source-resolution base.
|
||||
Failed fetches retain the last response URL observed within the approved origins;
|
||||
|
||||
@@ -10,8 +10,10 @@ liveness deadlines. `INPUT_JSON` may be inline JSON or a JSON file path.
|
||||
The minimal request contains only browser launch/connect selection, `start_url`,
|
||||
and at least one `actions` entry. Launch `headless` defaults to `true` and can
|
||||
be set to `false` where the host supports a visible browser. Navigations follow
|
||||
the destinations named by the scenario and the page's ordinary browser requests;
|
||||
there is no separate origin allowlist or request-interception layer. Environment
|
||||
the destinations named by the scenario and the page's ordinary browser requests,
|
||||
and [request steps](#request-steps) send only to the start URL's origin;
|
||||
there is no separate origin allowlist. Request steps use a temporary dispatch
|
||||
gate for cancellation; ordinary page requests retain their browser behavior. Environment
|
||||
settings (including service workers blocked by default), empty storage, and a
|
||||
final sanitized URL capture are supplied by default. Set
|
||||
`environment.service_workers` to `allow` when the application requires them.
|
||||
@@ -204,7 +206,8 @@ language environments.
|
||||
HTTP(S) URLs may include ordinary query values and fragments directly. Use
|
||||
ordered structured query entries when a value needs to reference a declared
|
||||
environment-backed secret. Form, storage, and cookie values are either literal
|
||||
strings or declared secret references. Raw URL userinfo credentials are rejected.
|
||||
strings or declared secret references; request step headers can also read a
|
||||
cookie or local storage value from the page. Raw URL userinfo credentials are rejected.
|
||||
Captured credential-header
|
||||
values are not retained, and declared secret values are redacted automatically.
|
||||
A secret may be declared solely to
|
||||
@@ -315,6 +318,113 @@ external browser without closing it. The request itself defines the operation;
|
||||
there is no additional REA grant step. The browser and host still enforce their
|
||||
own access and process rules.
|
||||
|
||||
## Request steps
|
||||
|
||||
A `request` step sends one HTTP request from the page with the page's own
|
||||
`fetch`, so the browser attaches the session's cookies and the request is
|
||||
recorded in the step's network events like any request the application makes.
|
||||
Use it to record an application's API, including writes, when driving the UI
|
||||
for each call would be slower or less exact than calling the endpoint the UI
|
||||
calls. It is the only action that changes application state without a user
|
||||
gesture, so run scenarios with write requests only against an instance whose
|
||||
data you may change. This scenario creates one item:
|
||||
|
||||
```json
|
||||
{
|
||||
"browser": {
|
||||
"mode": "launch",
|
||||
"executable_path": "/absolute/path/to/chromium"
|
||||
},
|
||||
"start_url": { "url": "http://127.0.0.1:3000" },
|
||||
"actions": [
|
||||
{
|
||||
"step_id": "create-item",
|
||||
"action": "request",
|
||||
"method": "POST",
|
||||
"path": "/api/items",
|
||||
"query": [
|
||||
{ "name": "notify", "value": { "source": "literal", "value": "false" } }
|
||||
],
|
||||
"headers": [
|
||||
{
|
||||
"name": "X-CSRFToken",
|
||||
"value": { "source": "cookie", "name": "csrftoken" }
|
||||
},
|
||||
{
|
||||
"name": "Authorization",
|
||||
"value": {
|
||||
"source": "local_storage",
|
||||
"key": "auth",
|
||||
"json_pointer": "/token"
|
||||
},
|
||||
"prefix": "Bearer "
|
||||
}
|
||||
],
|
||||
"json": { "title": "Scratch item 1" },
|
||||
"expected_status": [201],
|
||||
"timeout_ms": 10000
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- `method` is `GET`, `HEAD`, `POST`, `PUT`, `PATCH` or `DELETE`. `json` is the
|
||||
body, sent with `Content-Type: application/json` unless a header sets one; a
|
||||
`GET` or `HEAD` step cannot carry it.
|
||||
- `path` starts with one `/` and must resolve to the start URL's origin, which
|
||||
validation checks before the browser starts. When the step runs, the page must
|
||||
be on that origin, checked again in the page as the request is sent; add a
|
||||
`goto` step first if an earlier action left it. A query in `path` is sent as
|
||||
written (a fragment is not sent), and `query` entries are appended after it
|
||||
in order and may reference declared secrets.
|
||||
- Request steps follow no redirects: a redirect answer fails the step, and
|
||||
nothing is sent to the location it names, though a write the redirect
|
||||
answered may already have been applied. `expected_status` cannot name a 3xx
|
||||
status. Give the path the redirect names; with header values selected, the
|
||||
capture records its `Location`.
|
||||
- Header values are literals, declared secrets, a cookie the browser holds for
|
||||
the request URL (`{"source": "cookie", "name"}`, HttpOnly cookies included,
|
||||
whose value the page's scripts can then see while the request runs), or a
|
||||
local storage entry on the start origin (`{"source": "local_storage",
|
||||
"key"}`, with an optional `json_pointer` to a string or number in a stored
|
||||
JSON value). `prefix` is sent before the value. A value read from the page is
|
||||
redacted like a declared secret, as `[REDACTED:page:<step_id>.<header>]`,
|
||||
from records made after the step reads it; a response recorded earlier, such
|
||||
as the login response that returned a token, keeps the value. A value read
|
||||
again keeps its first marker, and a value shorter than 8 characters is not
|
||||
redacted, since redacting it would rewrite ids, ports and hosts throughout
|
||||
the capture. A value is redacted as stored and as `fetch` sends it, without
|
||||
surrounding spaces and tabs. A missing cookie, key or pointer fails the step.
|
||||
Reading a page value raises the estimated cost of redacting every later
|
||||
body, so the bodies kept within `max_network_body_allocation_bytes` (1 MiB
|
||||
by default) get smaller: after a 32-character `X-CSRFToken` value, a body over
|
||||
about 47 KiB is kept as `unavailable`. Raise `capture.limits` when the
|
||||
application's responses are larger.
|
||||
- Validation refuses a header name given twice in a step, header names a
|
||||
page's `fetch` cannot set, such as `Cookie`, `Origin`, `Host` or `Sec-*`, and
|
||||
`User-Agent`, which Chrome drops; it refuses line breaks and other ASCII
|
||||
control characters in literal values and prefixes, and the step fails before sending
|
||||
when a secret or page value holds them.
|
||||
- The step completes when the whole response has been read. With
|
||||
`expected_status`, any other status fails the step and the later actions are
|
||||
recorded as `cancelled`; without it, any response completes the step. A
|
||||
network error fails the step. `timeout_ms` covers reading the header values
|
||||
and the request: a step whose time runs out, or that is cancelled, before
|
||||
its request is sent sends nothing, but a request already sent can still reach
|
||||
the application after the step fails.
|
||||
An absolute deadline also covers browser evaluation queued behind page work.
|
||||
A temporary route checks cancellation again at network dispatch and is removed
|
||||
when the request evaluation settles. A page controlled by a service worker
|
||||
is refused because its fetch can bypass that dispatch gate; use the default
|
||||
blocked service-worker policy for request steps.
|
||||
|
||||
The request runs in the page's main world, so an application that wraps
|
||||
`fetch` sees it, and it goes through the same network observation as other
|
||||
page requests: select network content (bodies or header values) to record it.
|
||||
Captures with request steps state in `limitations` that the steps sent their
|
||||
declared requests through the page's fetch. A scenario without request steps
|
||||
is unchanged.
|
||||
|
||||
## Network evidence
|
||||
|
||||
`capture.events: ["network"]` retains request, response, completion, failure,
|
||||
@@ -355,6 +465,17 @@ and unfinished-request metadata. Select content independently:
|
||||
All three options default to `false`. Any selected network content also enables
|
||||
network metadata observation; listing `network` in `events` is then optional.
|
||||
Each observed request object receives a capture-scoped `transaction_id`.
|
||||
Each `request` event carries `observed_at`, the wall-clock time REA observed the
|
||||
request start. Playwright reports the browser's own start only once a request
|
||||
ends, so each `request-finished` or `request-failed` event carries `started_at`,
|
||||
the browser's wall-clock start, and `elapsed_ms`, its time from that start to
|
||||
the end of the response, when the browser reports them. The environment views
|
||||
time scenario records from these, as HAR entries are timed: the browser's start
|
||||
where it reported one, else `observed_at`, which trails it by up to tens of
|
||||
milliseconds while REA reads other responses, and a duration of 0 where the
|
||||
browser reported none. Captures made before these fields existed lack them and
|
||||
are read in record order. REA versions before them refuse captures that carry
|
||||
them. Scenario comparisons ignore all three (`ignore_network_request_timing`).
|
||||
Requests sharing a URL remain distinct. Redirects link to the preceding
|
||||
transaction only when it was observed; a null predecessor does not establish
|
||||
that no earlier hop existed. Request events require both transaction fields;
|
||||
@@ -452,8 +573,8 @@ and compared as an unordered collection after caller rules apply, because
|
||||
concurrent responses arrive in any order and can land in a later step; a
|
||||
redirect retains the complete predecessor ancestry, including each hop's own
|
||||
request, response outcome, and selected network content. Each transaction's
|
||||
capture-local IDs, sequence/index fields, and content source-sequence anchor
|
||||
are removed. Caller rules normalize retained strings before hashing. The
|
||||
capture-local IDs, sequence/index fields, content source-sequence anchor and
|
||||
request times (`observed_at`, `started_at`, `elapsed_ms`) are removed. Caller rules normalize retained strings before hashing. The
|
||||
`preserve_redirect_transaction_ancestry` built-in rule fingerprints each hop
|
||||
as canonical SHA-256 of `{ events, redirected_from }`: `events` is the sorted
|
||||
list of its normalized event SHA-256 digests, and `redirected_from` is its
|
||||
@@ -474,7 +595,10 @@ scope/flags, value fingerprints, and duplicate entries even when redaction or
|
||||
literal rules make names collide. Captured storage arrays retain their original
|
||||
order. The `compare_storage_entries_as_unordered_collection` built-in rule
|
||||
participates in the normalization commitment; new storage comparison digests
|
||||
therefore differ from earlier order-sensitive comparisons.
|
||||
therefore differ from earlier order-sensitive comparisons. The
|
||||
`ignore_network_request_timing` built-in rule likewise joins the commitment, so
|
||||
normalization digests differ from comparisons made before it, though captures
|
||||
with and without request times compare alike.
|
||||
|
||||
Each aligned step reports changed, unchanged, or unknown. Changed and unknown
|
||||
action, screenshot, DOM, accessibility, URL, history, storage, and event
|
||||
|
||||
+99
-4
@@ -236,6 +236,16 @@ Formats 2, 3 and 4 retain header, directory and integrity facts. Compact deliver
|
||||
keeps complete Evidence in the requested bundle. See [Godot PCK](godot-pck.md)
|
||||
for embedded packs, batch queries and unknown encrypted coverage.
|
||||
|
||||
Inspect a Node.js SEA carrier without running it:
|
||||
|
||||
```sh
|
||||
rea inspect-artifact ./application --json
|
||||
rea extract-artifact ./application --json
|
||||
```
|
||||
|
||||
See [Node.js SEA](node-sea.md) for supported layouts, script and asset paths,
|
||||
fuse observations, and the real-fixture verification lane.
|
||||
|
||||
Inspect local model declarations without loading weights:
|
||||
|
||||
```bash
|
||||
@@ -259,8 +269,8 @@ The command decodes a version 24, 27, 29, 31 or 39 `global-metadata.dat` and rep
|
||||
images, type, method and member names, string literals, index ranges, header
|
||||
sections and SHA-256. With `--binary PATH` it also reads the matching
|
||||
`GameAssembly.dylib`, `GameAssembly.dll` or `libil2cpp.so` (never runs it) and
|
||||
links each method to its code address; `--ghidra-seeds PATH` then writes Ghidra
|
||||
function seeds. It does not decrypt metadata. MCP defaults to compact counts
|
||||
links each method to its code address; `--generic-instances` adds generic
|
||||
method instances and `--ghidra-seeds PATH` then writes Ghidra function seeds. It does not decrypt metadata. MCP defaults to compact counts
|
||||
with retained Evidence; query indexed rows with filters, batch indices and
|
||||
selected fields. The CLI defaults to complete Evidence;
|
||||
`--detail summary --evidence_output FILE` exports the full result to a new file
|
||||
@@ -311,6 +321,33 @@ The workflow reports note owners, types, descriptor hashes, and GNU build-id
|
||||
or ABI-tag fields when those descriptors match. A missing note table is
|
||||
observed absence of those declarations. See [ELF note tables](elf-notes.md).
|
||||
|
||||
Inspect an Apple `.ips` crash report without executing a target:
|
||||
|
||||
```bash
|
||||
rea inspect-apple-ips /absolute/path/to/report.ips --json
|
||||
```
|
||||
|
||||
The workflow reports first-line metadata, process/exception/termination facts,
|
||||
threads, usedImages, lossless integer registers, and documented crash classes
|
||||
when `bug_type` is `"309"`. Other DiagnosticReports types return no crash
|
||||
result. See [Apple IPS crash reports](apple-ips.md).
|
||||
Inspect Linux kernel module metadata without executing the module or requiring
|
||||
`modinfo`:
|
||||
|
||||
```bash
|
||||
rea inspect-kernel-module /absolute/path/to/module.ko --json
|
||||
```
|
||||
|
||||
The workflow reports ordered `.modinfo` keys (duplicate `alias` and `parm`
|
||||
entries preserved), `__versions` symbol CRCs, presence of
|
||||
`.gnu.linkonce.this_module` and `__ksymtab` sections, observed `.init.text`
|
||||
and `.exit.text` sizes, and an appended signature trailer. `struct module` is
|
||||
not decoded and the signature is not validated. Other ELF types are not
|
||||
applicable. gzip, xz, and zstd containers are unsupported and name
|
||||
`external_decompression` as the next probe: decompress with an external
|
||||
utility, then inspect the decompressed file. See
|
||||
[Linux kernel modules](kernel-modules.md).
|
||||
|
||||
Inspect a CPython 3.7–3.13 `.pyc` header and nested marshal code objects
|
||||
without executing bytecode or installing Python:
|
||||
|
||||
@@ -364,7 +401,7 @@ Run `rea --help` or a command's `--help` for arguments and output options.
|
||||
The [generated catalog](mcp-contracts.md#generated-catalog) lists all CLI commands and MCP
|
||||
tools. Provider-specific target support is described in the
|
||||
[native guide](native-investigation.md), [DOS guide](ghidra-dos.md),
|
||||
[raw binary guide](raw-binary.md), and
|
||||
[raw binary guide](raw-binary.md), [GameCube DOL guide](ghidra-dol.md), and
|
||||
[Windows Ghidra guide](windows-ghidra-p0.md).
|
||||
|
||||
## Choose a provider
|
||||
@@ -428,7 +465,14 @@ an exact result when the target bytes, operation, parameters, provider and
|
||||
settings match. Mutations and cursor-dependent calls are excluded from the
|
||||
cache. Snapshot files are local and use owner-only permissions.
|
||||
|
||||
Importing an Evidence bundle refreshes retained subject display names and paths.
|
||||
One-shot binary CLI Evidence reports the exact path argument in `caller_input_path`,
|
||||
including relative spelling and symlink aliases. Its subject identifies the
|
||||
inspected artifact; `caller_input_path` does not change the Evidence ID or
|
||||
snapshot query. A replay reports the current invocation's path while leaving
|
||||
the saved Evidence unchanged. Provider inspections continue to include the
|
||||
established `parameters.input_path` field.
|
||||
|
||||
Importing an Evidence bundle refreshes retained request and subject display metadata.
|
||||
It preserves cached analysis results, including observations for other targets.
|
||||
Snapshot bindings that use a replaced record retain its updated display path.
|
||||
|
||||
@@ -735,6 +779,31 @@ like a blank `MCP_HOST`. The bound URL is written to stderr as one JSON log line
|
||||
[agent environments](agent-environments.md) for what the state and replay
|
||||
return and do not establish.
|
||||
|
||||
## Build an environment bundle
|
||||
|
||||
`rea environment-build <capture> [dir] [--name <name>] [--template-rule <rule> ...]
|
||||
[--format-rules-only] [--package-tarball <path>] [--capture-timeout-ms <ms>] [--dry-run]` builds the bundle
|
||||
`environment-export` writes from one recorded capture: a `.har` file, which it
|
||||
inspects as `inspect-web-network-capture` does, or capture Evidence JSON from
|
||||
`inspect-web-network-capture` (HAR) or `capture-browser-scenario`. It projects
|
||||
the environment manifest from the in-memory Evidence with the opt-in rules
|
||||
`after-uid-literal`, `opaque-token`, `sibling-variance` and `prefix-variance`
|
||||
unless `--template-rule` or `--format-rules-only` selects others, prepares the
|
||||
state, and writes the bundle; every file is byte-identical to the three-step
|
||||
path's when that path lists the same rules in the views' order and exports
|
||||
under the build's name. A loopback or IP-literal capture is named after its file unless `--name`
|
||||
is given. It prints one JSON report: the capture and manifest identities, the
|
||||
state, a `coverage` summary of which tools answer from the state, which replay
|
||||
and why each write is withheld with a hint, the files, warnings and the next
|
||||
command. `--dry-run` writes nothing and may omit the directory.
|
||||
|
||||
```sh
|
||||
rea environment-build grafana.har ./grafana --json
|
||||
```
|
||||
|
||||
See [agent environments](agent-environments.md#build-a-bundle-in-one-step)
|
||||
for the report, the hints and what the bundle ships.
|
||||
|
||||
## Export an environment bundle
|
||||
|
||||
`rea environment-export <manifest.json> --evidence <capture.json> <dir>
|
||||
@@ -910,6 +979,10 @@ server resources. It preserves a primary listener diagnostic, or a
|
||||
tool count and Evidence identifiers. The successful `stopped` document is
|
||||
returned only after cleanup is confirmed. The same in-process server owner
|
||||
retains failed stages for retry; the CLI exposes no separate retry command.
|
||||
`rea environment-build` is one-shot too: it prints its report and exits `0`,
|
||||
or prints the refusing stage's structured error and exits `1`, writing nothing
|
||||
when the refusal comes before the bundle is written. SIGINT cancels it with a
|
||||
`cancelled` error; a cancellation before the bundle stage writes nothing.
|
||||
`rea environment-export` is one-shot: it prints the written files and exits
|
||||
`0`, or prints a structured `invalid_request` error and exits `1` for the same
|
||||
pair refusals, a non-empty or file-occupied directory, a missing package
|
||||
@@ -986,3 +1059,25 @@ Counting retains the existing bounded formatted-string allocation after capacity
|
||||
admission; omit the flag to stream large JSON documents without materializing
|
||||
the complete formatted text. Exhausted token windows display an empty range at
|
||||
the total token count and have no next offset.
|
||||
|
||||
### `inspect-devicetree`
|
||||
|
||||
Inspect an explicit local FDT v16/v17 blob without execution or an external tool.
|
||||
Returns header, reservations, node/property tree, derived standard values and
|
||||
selected phandle references. See [devicetree inspection](devicetree.md) for
|
||||
limits and retained-view pagination.
|
||||
|
||||
```bash
|
||||
rea inspect-devicetree /artifacts/board.dtb --json
|
||||
rea inspect-devicetree /artifacts/board.dtb --detail summary --evidence_output /artifacts/board-evidence.json --json
|
||||
```
|
||||
|
||||
### PE TLS and load configuration
|
||||
|
||||
```sh
|
||||
rea inspect-pe-load-config /absolute/path/to/application.exe --json
|
||||
```
|
||||
|
||||
Reports TLS callbacks and size-covered load-config fields without execution.
|
||||
Use `--max-callbacks` and `--max-file-bytes` to set read budgets. See
|
||||
[PE TLS and load configuration](pe-load-config.md).
|
||||
@@ -18,8 +18,10 @@ default, any floor, the maximum, the schema, the parser, and the recovery
|
||||
text. Register that schema on `environmentSchema` in
|
||||
[`environment.ts`](https://github.com/morluto/rea/blob/main/src/config/environment.ts).
|
||||
`parseConfig` calls `parseEnvironment`. Doctor uses that same parser through
|
||||
`nativeAnalysisConfigurationError`, so startup and `rea doctor` accept the
|
||||
same values. Add the name to `SELECTED_REGISTRATION_SETTINGS` so `rea setup`
|
||||
`inspectNativeAnalysisConfiguration`, which also preserves a supplied Hopper
|
||||
timeout's parsed diagnostic when another setting is invalid. Startup and
|
||||
`rea doctor` accept the same values. Add the name to
|
||||
`SELECTED_REGISTRATION_SETTINGS` so `rea setup`
|
||||
copies it into the client registration. Unset keeps today's behavior. An
|
||||
invalid value is a `ConfigurationError` and projects as `configuration_invalid`.
|
||||
Do not fall back to the default.
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
# Flattened devicetree inspection
|
||||
|
||||
`inspect_devicetree` / `rea inspect-devicetree` reads a local DTB without an
|
||||
engine, target execution or external tools. It supports FDT versions 16 and 17;
|
||||
other versions return `unsupported_target`. Corrupt recognized blobs return
|
||||
`invalid_request`, and exhausted budgets return `resource_constraint` without
|
||||
partial success.
|
||||
|
||||
```bash
|
||||
rea inspect-devicetree /artifacts/board.dtb --json
|
||||
rea inspect-devicetree /artifacts/board.dtb --detail summary --evidence_output /artifacts/board-evidence.json --json
|
||||
```
|
||||
|
||||
The complete Evidence includes the artifact SHA-256, validated header fields,
|
||||
64-bit memory reservations as exact hexadecimal strings, and a flat node tree
|
||||
with explicit parent paths. Each property retains its file offset, byte length,
|
||||
and up to 256 raw bytes as hex. `truncated` qualifies the preview only; parsing
|
||||
coverage includes the entire declared tree. Version 16 has no declared structure
|
||||
size, so `header.size_dt_struct` is null.
|
||||
|
||||
Derived fields carry `confidence: derived`: standard ASCII string lists, scalar
|
||||
phandles and cell counts, and `reg` tuples using the parent's `#address-cells`
|
||||
and `#size-cells` (defaults 2 and 1). Zero-cell components are null (omitted), distinct from an encoded zero. Cell
|
||||
counts above four, invalid counts and incomplete tuples remain undecoded with a
|
||||
limitation. Addresses are bus-local; no `ranges` translation is attempted.
|
||||
Invalid or ambiguous strings remain raw, rather than being guessed.
|
||||
|
||||
The summary is labeled derived and includes root compatible/model, chosen
|
||||
bootargs/stdout-path and aliases. An undecodable alias retains its name with a
|
||||
null path; it is not silently treated as absent. Single-cell `interrupt-parent`, `remote-endpoint` and `msi-parent`
|
||||
references resolve through phandle declarations. Missing or duplicate targets
|
||||
have null target paths. A node whose `phandle` and `linux,phandle` disagree
|
||||
adds a limitation, and references to either value stay unresolved. A present
|
||||
`phandle` that is not one cell also adds a limitation; `linux,phandle` cannot
|
||||
resolve that node when the canonical declaration is malformed. Binding-specific
|
||||
reference arrays and overlays are not resolved; an empty reference list does not
|
||||
prove absence of hardware links.
|
||||
|
||||
MCP `detail: summary` retains complete Evidence in the session. Follow its
|
||||
`parent_evidence_id` with `inspect_analysis_view`:
|
||||
|
||||
```json
|
||||
{
|
||||
"source": { "kind": "retained-evidence", "evidence_id": "ev:<digest>" },
|
||||
"view": {
|
||||
"kind": "devicetree",
|
||||
"collection": "properties",
|
||||
"path": "/serial@1000",
|
||||
"offset": 0,
|
||||
"limit": 32
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Collections are `nodes` (identity and property counts), `properties` (requires an
|
||||
exact node path), `reservations`, and `references`. Pages use retained parsed
|
||||
facts and do not reopen the file. Each page carries fixed-size context
|
||||
(artifact, header, coverage and counts) rather than the summary strings, so a
|
||||
large `bootargs` value does not repeat on every page. Source indices are scoped to the selected
|
||||
collection and parent Evidence; property indices are scoped to their node.
|
||||
|
||||
| Input budget | Default | Ceiling |
|
||||
| ---------------- | ------: | ------: |
|
||||
| `max_file_bytes` | 4 MiB | 16 MiB |
|
||||
| `max_nodes` | 8,192 | 65,536 |
|
||||
| `max_properties` | 32,768 | 262,144 |
|
||||
| `max_depth` | 64 | 256 |
|
||||
|
||||
Decoded names, paths, values and row overhead share a fixed 32 MiB representation
|
||||
allowance, charged before expansion. It has no runtime override.
|
||||
|
||||
The reservation count also uses `max_properties`. CLI flags use kebab case,
|
||||
for example `--max-nodes 16384`. View pages contain at most 256 rows.
|
||||
|
||||
## Verification
|
||||
|
||||
Synthetic tests cover v16/v17, malformed headers/blocks/names/tokens, resource
|
||||
limits, derived values, and CLI/MCP delivery including retained pages after
|
||||
removing the input. The optional real lane requires **dtc 1.8.1**:
|
||||
|
||||
```bash
|
||||
npm run build:cached
|
||||
node scripts/verify/firmware/devicetree.mjs
|
||||
```
|
||||
|
||||
It compiles a DTS with reserved-memory, chosen, aliases and phandles, compares
|
||||
REA's node paths against `dtc -I dtb -O dts`, and checks the derived report.
|
||||
`REA_DTC_PATH` selects the verification executable; it is not runtime setup.
|
||||
|
||||
The dtc 1.8.1 lane ran on macOS arm64 with Node 26.5.0. Its seven node paths
|
||||
matched the decompiled tree. The report included `model: "REA DTB verification"`,
|
||||
`bootargs: "console=ttyS0"`, alias `serial0 -> /serial@1000`, reservation
|
||||
`0x80000000 + 0x1000`, and a resolved reference from `/consumer` to
|
||||
`/serial@1000`. The deliberately minimal remote-endpoint fixture produces dtc
|
||||
graph-binding warnings; this lane verifies FDT structure and selected property
|
||||
derivations, not hardware-binding validity.
|
||||
|
||||
A repeat run of that complete compile/decompile/CLI verification took 2.13 s
|
||||
elapsed, 1.52 s user CPU and 0.27 s system CPU under `/usr/bin/time -l`. This is a
|
||||
small fixture with warm filesystem caches, not a cold-start or large-board
|
||||
benchmark. Peak process-family memory and whole-workflow token usage were not
|
||||
measured; the sandbox denied the memory-reporting system query. No pre-feature
|
||||
equivalent REA workflow exists for comparison. The pinned Node 24.22.1/npm
|
||||
11.16.0 toolchain was unavailable; dependency installation used the local cache
|
||||
with Node 26.5.0/npm 12.2.0 instead.
|
||||
+9
-2
@@ -24,12 +24,17 @@ requires an absolute filesystem path and preserves that exact selection:
|
||||
|
||||
The inline Evidence result contains the artifact path, SHA-256, and byte length.
|
||||
`tables` lists each declared note program header or section, including the
|
||||
section name when a string table is present. Zlib-compressed section-name
|
||||
tables are decompressed within the selected file-size budget. An unsupported
|
||||
section name when a string table is present. Zlib- and Zstandard-compressed
|
||||
section-name tables are decompressed within the selected file-size budget. An unsupported
|
||||
compression type leaves section names unknown and adds a limitation; note bytes
|
||||
remain independently examined. Each `entries[]` item reports owner, type,
|
||||
descriptor SHA-256, and a hex preview for descriptors of 64 bytes or less.
|
||||
|
||||
A section name also stays null when its offset is outside the declared string
|
||||
table or its bytes lack a NUL terminator. A limitation explains that missing
|
||||
name. Note coverage remains complete when all declared note tables and entries
|
||||
were examined; an unavailable section name does not erase those note facts.
|
||||
|
||||
For GNU notes, `gnu.build_id_hex`, `gnu.abi_tag`, or `gnu.gold_version` are
|
||||
filled when the descriptor matches that type. Other owners keep `gnu` null.
|
||||
|
||||
@@ -58,6 +63,8 @@ numbering (`PN_XNUM`, including a section count stored when `e_shnum` is 0) is
|
||||
unsupported and returns an unsupported-target outcome rather than invalid-input
|
||||
recovery.
|
||||
|
||||
Zstandard section-name tables also use a 128 MiB decoder window limit.
|
||||
|
||||
`SHF_COMPRESSED` note sections return `unsupported_target` before their payload
|
||||
is interpreted or decompressed. Their compression header is storage metadata,
|
||||
not a note header. The current result requires physical file offsets for each
|
||||
|
||||
@@ -91,6 +91,13 @@ nothing, and `fields: []` returns only `source_index`. Offset/limit page matchin
|
||||
rows in original order (defaults 0/64). Unfiltered pages slice the retained
|
||||
collection; queries do not decode the file again.
|
||||
|
||||
For `chunks`, `names` matches the four-character IFF chunk tag (for example
|
||||
`"AtU8"`, `"Code"`, `"ExpT"`); available `fields` are `index`, `name`,
|
||||
`location`, and `payload`. For `lambdas`, `names` matches the resolved function
|
||||
name from the atom table; `null` names (unresolved atom indices) are never
|
||||
selected by a name filter. For `atoms`, `names` matches the decoded atom name
|
||||
string.
|
||||
|
||||
`beam` keeps the module, form/Code bounds, original source coverage, and table
|
||||
counts. A null count means no table was decoded; zero means a decoded empty
|
||||
table. Missing tables and unresolved atom names remain explicit, and an empty
|
||||
|
||||
@@ -285,3 +285,10 @@ REA_FIRMWARE_VERIFY_GHIDRA=1 npm run verify:firmware
|
||||
`scripts/rea.mjs` to verify the packaged CLI/MCP workflow. Real coverage here is
|
||||
generated gzip/USTAR/ext4 with a Linux x64 ELF child; SquashFS, UBIFS, proprietary
|
||||
firmware, other hosts and architectures remain unverified.
|
||||
|
||||
## Inspect extracted devicetrees
|
||||
|
||||
Use [`inspect_devicetree`](devicetree.md) / `rea inspect-devicetree` on an
|
||||
extracted DTB for its node/property tree, reservations, hardware summary and
|
||||
selected phandle relationships. FDT v16/v17 inspection is portable and requires
|
||||
no external tool or disassembler.
|
||||
@@ -0,0 +1,129 @@
|
||||
# GameCube DOL analysis through Ghidra
|
||||
|
||||
This lane imports 32-bit big-endian PowerPC GameCube/Wii DOL images through
|
||||
Ghidra. It does not execute the image. DOL is a headerless format with no magic
|
||||
number, so REA never detects it: the caller must select it explicitly.
|
||||
|
||||
Only the cached MEM1 window `0x80000000..0x81800000` is admitted. Wii MEM2
|
||||
and uncached aliases are outside this lane.
|
||||
|
||||
Not covered: small-data anchors (`r2`/`r13`), REL, RPX, and IDA or Hopper
|
||||
support. See [Not supported yet](#not-supported-yet).
|
||||
|
||||
## Select the format
|
||||
|
||||
CLI:
|
||||
|
||||
```bash
|
||||
rea inspect /absolute/path/to/main.dol --target-format gamecube-dol --provider ghidra --json
|
||||
rea function /absolute/path/to/main.dol 0x80003130 --target-format gamecube-dol --provider ghidra --json
|
||||
```
|
||||
|
||||
MCP, with the existing `open_binary` tool:
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "/absolute/path/to/main.dol",
|
||||
"provider_id": "ghidra",
|
||||
"format": "gamecube-dol"
|
||||
}
|
||||
```
|
||||
|
||||
The architecture comes from the DOL header (`powerpc`). Do not pass
|
||||
`architecture` with `gamecube-dol`; it is rejected. `entry_point` is optional,
|
||||
and if given it must equal the header entry.
|
||||
|
||||
Omitting `format` never imports a file as a DOL. Detection does not run for DOL.
|
||||
|
||||
## What the import does
|
||||
|
||||
REA reads the 256-byte DOL header at admission. It checks every section's file
|
||||
range and load address. It records BSS/data overlaps and computes the exact
|
||||
uninitialized BSS gaps once. Malformed headers are refused before Ghidra starts.
|
||||
|
||||
Ghidra then runs in two steps:
|
||||
|
||||
1. The standard `BinaryLoader` maps the whole file at base `0x0`, with
|
||||
`-processor` and `-cspec` taken from the language selection below.
|
||||
2. The pre-script `bridge/ghidra/ReaGhidraPrepareDol.java` reads a section file
|
||||
that REA wrote from the parsed header, with versioned collection counts. It creates one initialized block per
|
||||
used text and data section at its load address, with file bytes from the
|
||||
section's file offset. The whole-file block is removed before the section
|
||||
blocks are created. Text is read-execute and data is read-write. It sets the
|
||||
entry point and labels the entry
|
||||
`__start`.
|
||||
|
||||
Sections that the header marks unused are not mapped. The 256-byte header and
|
||||
any bytes between sections are not mapped either.
|
||||
|
||||
## BSS
|
||||
|
||||
A DOL has one BSS range, and it is not always disjoint from the data sections.
|
||||
The domain parser computes the parts of BSS that no data section covers. Both
|
||||
the pre-script and load-image attestation consume those parsed ranges. The
|
||||
pre-script creates uninitialized read-write blocks only in those gaps. Where BSS overlaps a data slot, that slot
|
||||
keeps its file bytes. Overlapping slot indexes are reported by the parser.
|
||||
|
||||
## Bound language
|
||||
|
||||
The default language is `PowerPC:BE:32:default` with compiler spec `default`,
|
||||
which ships with Ghidra. The load-image attestation checks the language Ghidra
|
||||
reports, not only the requested one.
|
||||
|
||||
### Optional Gekko/Broadway override
|
||||
|
||||
`REA_GHIDRA_LANGUAGE_ID=PowerPC:BE:32:Gekko_Broadway` selects the Gekko/Broadway
|
||||
variant. The language is not in stock Ghidra. It comes from the GameCubeLoader
|
||||
extension, by Cuyler, licensed under Apache-2.0. The extension ships
|
||||
`ppc_gekko_broadway.ldefs` under its `data/languages` directory and must be
|
||||
installed in the Ghidra installation's `Ghidra/Extensions` directory. The stock
|
||||
lane never requires it.
|
||||
|
||||
Any other language id must start with `PowerPC:BE:32:`. Other languages are
|
||||
refused with a specific constraint.
|
||||
|
||||
## Paired-single limitation
|
||||
|
||||
The stock `PowerPC:BE:32:default` language does not decode the paired-single
|
||||
instructions that Gekko and Broadway add. Those words decode as bad or undefined
|
||||
instructions. Use the Gekko override to decode them.
|
||||
|
||||
## Verification
|
||||
|
||||
The source-owned fixture is built from `tests/conformance/c/ppc.c`,
|
||||
`tests/conformance/c/dol.c`, `tests/conformance/ghidra/ppc-probe.S` and the
|
||||
linker script `tests/conformance/ghidra/dol-fixture.ld`. It is converted to a DOL
|
||||
by `tests/conformance/ghidra/dol-fixture.mjs`. Its text is at `0x80003100`, and
|
||||
its single BSS range overlaps data slot 1 and leaves a gap. The fixture is
|
||||
never executed. The real GameCube or Wii game images are never used.
|
||||
|
||||
```bash
|
||||
GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra npm run verify:ghidra:dol
|
||||
```
|
||||
|
||||
The lane needs the same toolchain as the PowerPC ELF lane: `REA_PPC_CLANG`,
|
||||
`REA_PPC_READELF` and LLD. An independent DOL header reader and GNU readelf
|
||||
(run on the source ELF) check the section table, file bytes, entry and BSS gap
|
||||
before Ghidra starts. The checks never use REA's parser.
|
||||
|
||||
After import, the lane checks the load-image attestation (`verified`), the
|
||||
bound language, the `__start` entry procedure, a direct call to the leaf
|
||||
function, decompilation, and bytes at the data, tail, marker and BSS-gap
|
||||
addresses. It also checks CLI identity.
|
||||
|
||||
The Gekko pass runs only when `PowerPC:BE:32:Gekko_Broadway` is in the Ghidra
|
||||
installation's language catalog, the same catalog REA uses to admit
|
||||
`REA_GHIDRA_LANGUAGE_ID`. A language that exists only in a user extension under
|
||||
`~/Library/ghidra` is not admitted, so the lane prints
|
||||
`skipped: PowerPC:BE:32:Gekko_Broadway (not in the Ghidra installation catalog that REA admits); stock lane still verified`
|
||||
and still succeeds on the stock checks.
|
||||
|
||||
The ELF lane (`npm run verify:ghidra:ppc`) is separate. See
|
||||
[PowerPC ELF analysis through Ghidra](/ghidra-ppc).
|
||||
|
||||
## Not supported yet
|
||||
|
||||
- Small-data anchors: `r2` and `r13` are not seeded from the DOL header.
|
||||
- REL (relocatable modules) and RPX (Wii U) are not admitted.
|
||||
- IDA and Hopper refuse `gamecube-dol`. Ghidra is the only provider.
|
||||
- Disc images (ISO/GCM) are not supported. Pass an extracted DOL file.
|
||||
+12
-7
@@ -29,13 +29,18 @@ point using the available structural bytes and actual file length. It reports
|
||||
those DOS facts separately from Windows-header evidence. A recognized PE
|
||||
signature remains PE; recognized NE, LE, and LX headers are explicitly
|
||||
unsupported. A nonzero Windows-header pointer without a recognized signature
|
||||
remains an unresolved candidate, even when the DOS structure validates:
|
||||
automatic target selection fails closed and reports both observations.
|
||||
REA does not infer DOS intent from padding or infer a damaged Windows header
|
||||
from the pointer alone. Inventory classification is a bounded-prefix format
|
||||
hint; it returns `unknown` for that candidate or when its prefix cannot
|
||||
establish the format. That result is distinct from complete DOS validation and
|
||||
does not decide target admission.
|
||||
usually remains an unresolved candidate, even when the DOS structure validates:
|
||||
automatic target selection fails closed and reports both observations. When a
|
||||
nonempty relocation table ends inside a complete DOS header, the remaining
|
||||
header bytes belong to DOS padding; a nonzero dword there is not a Windows
|
||||
declaration. An unread signature beyond the current probe is requested before
|
||||
that padding rule applies. This avoids manufacturing a Windows header from
|
||||
original DOS padding while preserving rejection of damaged Windows
|
||||
declarations.
|
||||
Inventory classification is a bounded-prefix format hint; it returns `unknown`
|
||||
for an unresolved candidate or when its prefix cannot establish the format.
|
||||
That result is distinct from complete DOS validation and does not decide target
|
||||
admission.
|
||||
|
||||
Ghidra imports a private target snapshot with `MzLoader`, language
|
||||
`x86:LE:16:Real Mode`, and compiler specification `default`. These settings,
|
||||
|
||||
+13
-4
@@ -24,7 +24,8 @@ specific unsupported constraint rather than guessing a compatible profile.
|
||||
|
||||
A second admission covers recordless legacy firmware images
|
||||
([#1620](https://github.com/morluto/rea/issues/1620)): ELF32 `ET_EXEC` headers
|
||||
declaring `EF_MIPS_ARCH_32` or `EF_MIPS_ARCH_32R2` with an unspecified ABI
|
||||
declaring `EF_MIPS_ARCH_1` (MIPS-I, a zero ISA field), `EF_MIPS_ARCH_32` or
|
||||
`EF_MIPS_ARCH_32R2` with an unspecified ABI
|
||||
field, `EF_MIPS_ABI2` clear, and an _inspected_ absence of any ABI flags
|
||||
record (a target whose record was merely not observed stays refused). For
|
||||
these images o32 is an analysis assumption derived from the ELF32/ET_EXEC
|
||||
@@ -40,9 +41,17 @@ refusal. A header that declares an ABI field but carries no record is still
|
||||
refused. Two further boundaries apply: an inspection that could not examine
|
||||
every ABI declaration source (for example a carved ELF whose section table
|
||||
extends past the captured bytes without a program-header record) does not
|
||||
establish the recordless admission, and an `EF_MIPS_ARCH_32` header that
|
||||
_declares_ an ABI is refused rather than relabeled, because the declared-ABI
|
||||
lane is verified for `EF_MIPS_ARCH_32R2` headers only.
|
||||
establish the recordless admission, and an `EF_MIPS_ARCH_1` or
|
||||
`EF_MIPS_ARCH_32` header that _declares_ an ABI is refused rather than
|
||||
relabeled, because the declared-ABI lane is verified for
|
||||
`EF_MIPS_ARCH_32R2` headers only. The recordless MIPS-I lane pins the same
|
||||
generic 32-bit language, which also decodes later MIPS32 instructions; the
|
||||
session states that conformance to the MIPS-I subset is not established from
|
||||
the header alone, and names the committed language when the caller selected a
|
||||
variant instead of the pin. A committed profile is bound to the current
|
||||
target's lane and captured ELF metadata before startup; reusing a profile
|
||||
resolved for the other recordless lane is refused rather than exporting
|
||||
attribution for a target it did not describe.
|
||||
|
||||
Explicit `EF_MIPS_FP64` and `EF_MIPS_NAN2008` declarations are refused. Their
|
||||
absence is insufficient: Clang can emit identical `e_flags` for FP32, FP64 and
|
||||
|
||||
+2
-1
@@ -3,7 +3,8 @@
|
||||
This lane extends native ELF analysis to 32-bit big-endian PowerPC; it does
|
||||
not execute PowerPC code. It is the first milestone of
|
||||
[#1741](https://github.com/morluto/rea/issues/1741). GameCube/Wii DOL
|
||||
executables, PPC64 and other PowerPC variants are separate follow-ups.
|
||||
executables are covered by [GameCube DOL analysis](ghidra-dol.md). PPC64 and other
|
||||
PowerPC variants remain separate follow-ups.
|
||||
|
||||
## Admission boundary
|
||||
|
||||
|
||||
@@ -36,6 +36,18 @@ provider stays bound to the target; runtime failure never selects another
|
||||
provider automatically. The contracts below describe Ghidra observations,
|
||||
not equivalence with another engine's pseudocode or analysis database.
|
||||
|
||||
## Request payload ceiling
|
||||
|
||||
Ghidra requests use `REA_BRIDGE_MAX_REQUEST_BYTES`: default 16 MiB, with a
|
||||
configurable range of 7,464–536,870,887 bytes. REA measures UTF-8 JSON, including
|
||||
escaping, before allocating the serialized request or sending it. The framing
|
||||
newline is excluded. An oversized request returns `resource_constraint` with
|
||||
the effective setting, its source, and the exact payload byte count.
|
||||
|
||||
Set the value in the environment that starts REA, then restart REA to apply it.
|
||||
This setting is enforced by the REA client; the Java bridge has no corresponding
|
||||
request ceiling.
|
||||
|
||||
## Admitted inventory semantics
|
||||
|
||||
| Concern | Ghidra contract |
|
||||
|
||||
@@ -7,6 +7,9 @@ releases have not been verified. Format 1 is unsupported.
|
||||
|
||||
Inspection retains the original header and directory facts, including engine
|
||||
version, flags, declared file count, source paths, offsets and declared MD5.
|
||||
For a member declared as `res://scenes/main.gd`, the occurrence's
|
||||
`source_path` retains that exact declaration while `logical_path` is
|
||||
`scenes/main.gd`, the relative path used for lookup and extraction.
|
||||
Observed plaintext bytes receive content-addressed SHA-256 identities. MD5 is a
|
||||
container integrity claim, separate from the observed SHA-256. A mismatch fails
|
||||
by default; `--integrity-policy record-and-continue` retains the observed bytes
|
||||
|
||||
+156
-31
@@ -58,18 +58,22 @@ the original rows without reopening or decoding the file:
|
||||
|
||||
Collections are `sections`, `images`, `types`, `methods`, `fields`,
|
||||
`properties`, `events`, `parameters`, `string_literals`, `method_addresses`,
|
||||
`return_types`, `field_types`, `parameter_types` and `code_gen_modules`. Every returned row includes
|
||||
`return_types`, `field_types`, `parameter_types`, `code_gen_modules`,
|
||||
`generic_method_instances` and `generic_method_issues`. Every returned row includes
|
||||
its source `index`, scoped by artifact SHA-256 and collection. All collections
|
||||
accept batch `indices` and `fields`. Exact `names` filtering is supported for
|
||||
`sections`, `images`, `types`, `methods`, `fields`, `properties`, `events` and
|
||||
`parameters`; native `return_types`, `field_types` and `parameter_types` rows
|
||||
are selected by source indices (or `method_indices` for `parameter_types`),
|
||||
not rendered names. Types also accept `image_indices`, `namespaces` and
|
||||
`sections`, `images`, `types`, `methods`, `fields`, `properties`, `events`,
|
||||
`parameters`, `return_types`, `field_types`, `parameter_types` and
|
||||
`generic_method_instances`. Native type names match the retained rendered display value exactly; every same-name row
|
||||
keeps its source index, and an unavailable (`null`) name never matches a string.
|
||||
Types also accept `image_indices`, `namespaces` and
|
||||
`declaring_types`; methods, fields, properties and events accept
|
||||
`declaring_types`. Parameters accept exact `method_indices`, so a batch of
|
||||
method indices retrieves their parameters without reading the entire parameter
|
||||
table. `parameter_types` accepts the same `method_indices`, resolved through the
|
||||
retained `parameters` owners; Evidence without `parameters` refuses that filter. Filters intersect, duplicate indices are returned once, and
|
||||
retained `parameters` owners; Evidence without `parameters` refuses that filter. Generic method instances
|
||||
accept `method_indices` (definition indices) and `states`; generic method
|
||||
issues accept `rows` (the instance rows they leave unknown). Filters intersect, duplicate indices are returned once, and
|
||||
rows retain metadata order. An empty filter selects no rows; `fields: []`
|
||||
returns indices only. Omitted fields return the complete selected rows.
|
||||
|
||||
@@ -113,7 +117,9 @@ Historical Evidence that predates these member collections remains queryable.
|
||||
A missing collection has an unknown (`null`) summary count, and requesting it
|
||||
reports that it was not collected; it is never presented as an empty inventory. The same holds for Evidence that predates binary linking: its summary
|
||||
omits `binary`, and `method_addresses`, `method_address_states`,
|
||||
`return_types`, `field_types` and `parameter_types` counts are `null`.
|
||||
`return_types`, `field_types` and `parameter_types` counts are `null`. A link retained before
|
||||
generic instances existed omits `binary.generic_methods`, and the
|
||||
`generic_method_instances` and `generic_method_issues` counts are `null`.
|
||||
Existing empty collections retain a zero count. Full Evidence is preserved.
|
||||
|
||||
`offset` counts matching rows, not source indices. `limit` defaults to 64;
|
||||
@@ -146,8 +152,9 @@ in [CLI and Evidence](cli.md#run-a-command). Compact delivery requires
|
||||
`--evidence_output`; existing files are never overwritten. The full export
|
||||
preserves every decoded row for subsequent queries without the original file.
|
||||
|
||||
`--binary PATH` links method addresses and `--architecture arm64|amd64` selects
|
||||
exactly one slice of a universal Mach-O. The report retains the native reader's
|
||||
`--binary PATH` links method addresses, `--architecture arm64|amd64` selects
|
||||
exactly one slice of a universal Mach-O and `--generic-instances` adds generic
|
||||
method instances. The report retains the native reader's
|
||||
`amd64` spelling for x86-64; loader CPU checks use the corresponding `x86_64`
|
||||
identity. Multiple slices with the same architecture label are refused as
|
||||
`ambiguous-slice-selection`, including
|
||||
@@ -234,7 +241,7 @@ record addresses remain distinct candidates, and conflicting file mappings
|
||||
remain malformed.
|
||||
|
||||
Module records establish names through their declared NUL-terminated string pointers. NUL/0xFF padding, spaces, Unicode and suffix-shared storage are supported. A pointer to a longer string does not match just its suffix; a pointer directly into a shared suffix may name it. Exact reversed UTF-8 matching avoids rescanning the file for every name and retains duplicate-name owners until module records resolve them. A contributor investigated a Linux
|
||||
`GameAssembly.so` from Unity 2023.2.13f1 whose static registration was not located. When no static pair is resolved on x86-64, the reader searches executable ranges for bytes consistent with RIP-relative LEA/MOV references to module-array candidates. Exactly one referenced array candidate must remain. `code_gen_modules_field` is then `null`, and Evidence is **inferred**: instruction boundaries, the absence of a static registration elsewhere, and runtime use were not verified. The module records and slots themselves remain file observations. Static-table associations are **derived**. Otherwise the result is `code-registration-not-found`.
|
||||
`GameAssembly.so` from Unity 2023.2.13f1 whose static registration was not located. When no static pair is resolved on x86-64 or arm64, the reader searches executable ranges for bytes consistent with a reference to a module-array candidate: RIP-relative LEA/MOV on x86-64, an adjacent `adrp`/`add` pair on arm64. Exactly one referenced array candidate must remain. `code_gen_modules_field` is then `null`, and Evidence is **inferred**: instruction boundaries, the absence of a static registration elsewhere, and runtime use were not verified. The module records and slots themselves remain file observations. Static-table associations are **derived**. Otherwise the result is `code-registration-not-found`. Cpp2IL's StrippedCodeRegSupport plugin also recovers the module list of an inlined CodeRegistration from the module names; this fallback additionally requires the exact located module set and a single code reference. A Unity 2022.3.62f3 macOS Master build checked by a contributor keeps neither registration symbol; its type table is then inferred as described below.
|
||||
|
||||
The binary/metadata pair is caller-selected. Name/count/token agreement is structural evidence, not a cryptographic same-build proof. File-offset locations refer to the primary metadata artifact; linked virtual addresses refer to `binary.artifact`. Both SHA-256 identities remain available in compact native pages as `artifact` and `binary_source`.
|
||||
|
||||
@@ -292,6 +299,30 @@ The result adds:
|
||||
`Il2CppMetadataRegistration.typesCount` and its value. That record is found as
|
||||
the single place whose `fieldOffsetsCount` and `typeDefinitionsSizesCount` both
|
||||
equal the metadata type-definition count and whose type table is file mapped.
|
||||
Linking reads only that table. When no record on x86-64 or arm64 has both of
|
||||
those counts, the reader collects maximal runs of pointers to Il2CppType-shaped
|
||||
records (an assigned Il2CppTypeEnum kind from 0x01 to 0x1e; class and
|
||||
value-type data below the type-definition count) that are long enough for every
|
||||
type index the metadata references. Exactly one such run may exist in the
|
||||
image, it must start and end inside its mapping (a run touching either end may
|
||||
continue in a neighbouring mapping), and its start must be loaded by the same
|
||||
instruction forms as the module-array fallback. `types_field` is then `null`,
|
||||
`types_count` is that run's length rather than an observed `typesCount`, and
|
||||
Evidence is **inferred**. The run length is at least every referenced type
|
||||
index but can differ from `typesCount`: a type-shaped pointer after the table
|
||||
would lengthen it, and an unreadable slot (such as an unresolved relocation)
|
||||
would end it early. Only the type indices the metadata references are read. A
|
||||
second long-enough run anywhere, a run that a type-shaped neighbour extends
|
||||
before the loaded address, a run touching a mapping end or a slot the loader
|
||||
binds or leaves unresolved (its stored word is only a placeholder), and a covered
|
||||
128-byte record whose two counts match but whose other fields are unusable all
|
||||
leave `metadata-registration-not-found` rather than a guess; the search stops
|
||||
at the second run. The length requirement only separates the type table from
|
||||
other pointer runs when the metadata references most of it: on the one Master
|
||||
build checked, the highest referenced index is 6,031 of 6,576 entries. A
|
||||
metadata referencing few type indices usually
|
||||
leaves several short runs and fails closed.
|
||||
|
||||
Counts use their declared 32-bit width independently of alignment padding.
|
||||
The complete 128-byte registration must have unambiguous loader coverage. Its
|
||||
used fields through byte 112 must be file-backed; a trailing declared zero-fill
|
||||
@@ -306,6 +337,93 @@ fixtures; they do not add real Unity-build verification to the checks above.
|
||||
Without `binary_path`, `binary` is `null` and the four binary collections are
|
||||
empty in the complete producer report to indicate unrequested observations. Their summary counts, including state counts, are `null`, and native page requests report unavailable observations. This does not establish an empty native inventory. Missing native fields in historical Evidence remain unknown too.
|
||||
|
||||
### Generic method instances
|
||||
|
||||
`generic_instances: true` (CLI `--generic-instances`, needs `binary_path`) also
|
||||
links the instances in `Il2CppMetadataRegistration.genericMethodTable`, as
|
||||
Il2CppDumper does: each row's `genericMethodIndex` selects an `Il2CppMethodSpec`
|
||||
(generic method definition plus class and method `Il2CppGenericInst`), and its
|
||||
`methodIndex` selects a `genericMethodPointers` slot. Without the option both
|
||||
fields below are `null` (not linked, so unknown), as are the summary counts
|
||||
`generic_method_instances` and `generic_method_instance_states` and the seed
|
||||
counts. The result adds:
|
||||
|
||||
- `binary.generic_methods`: `generic_method_pointers_field` (the address of
|
||||
`genericMethodPointersCount`), the pointer, table, method spec and generic
|
||||
instance counts, `generic_method_table_stride` and `issues` (each with the
|
||||
`row` it leaves unknown, the `address` of the contradicting row, method spec
|
||||
or pointer slot record, and a `message`);
|
||||
- `generic_method_instances`: one row per table entry (row position is the
|
||||
table index) with `method_spec`, `method` (the recorded definition index,
|
||||
including invalid values, or `null` when the index cannot be read),
|
||||
`name`, and `state`, `address` and `rva` as in `method_addresses`: `code`,
|
||||
`no-body` for a zero pointer slot, or `unknown` exactly when an issue names
|
||||
the row.
|
||||
|
||||
Names follow Il2CppDumper's `GetMethodSpecName`, for example
|
||||
`System.Collections.Generic.Dictionary<int, string>$$TryGetValue` or
|
||||
`System.HashCode$$Add<int>`: namespaces only on the declaring type, nested types
|
||||
joined with `.`, the backtick arity cut, `IntPtr`/`UIntPtr`/`TypedReference`
|
||||
and no byref mark. These names do not depend on the byref bit, so version 27 is
|
||||
covered.
|
||||
|
||||
Header versions do not separate the CodeRegistration layouts (27.0, 27.1 to
|
||||
29 and 29.1/31 differ in the fields before `codeGenModulesCount`). Every layout for the header version is tried, and
|
||||
exactly one must have a `genericMethodPointers` count and an invoker count that
|
||||
bound every table row; the layout also fixes the row size (12 bytes, or 16 with
|
||||
an adjustor thunk index). No layout agreeing fails as
|
||||
`generic-method-registration-not-found`, more than one as
|
||||
`ambiguous-generic-method-registration`. An empty table selects no layout:
|
||||
the result has no rows, and `generic_method_pointers_field`,
|
||||
`generic_method_pointers_count` and `generic_method_table_stride` are `null`.
|
||||
A table of a few rows can still leave two layouts agreeing, which fails as
|
||||
ambiguous rather than picking one. Metadata versions 24 and 39 and builds
|
||||
without a static CodeRegistration (`code_gen_modules_field` `null`) or
|
||||
MetadataRegistration (`types_field` `null`) fail as
|
||||
`generic-methods-unsupported`: for version 24 the type-definition generic
|
||||
container offset and the generic class layout have not been checked against a
|
||||
real build, so it is refused rather than guessed.
|
||||
|
||||
After the layout is fixed, rows that contradict another table do not fail the
|
||||
whole link: a method spec naming a method or generic instance out of range,
|
||||
class or method arguments whose count differs from the generic container the
|
||||
owner declares (none for a non-generic type or method), an owner whose generic
|
||||
container index is out of range, a name that cannot be rendered, or a pointer slot that is unmapped, has an
|
||||
unresolved relocation or points outside unambiguous executable file data adds
|
||||
an `issues` entry, and that row is `unknown` with no address. A method spec
|
||||
issue also leaves `name` `null`, even when the pointer slot is valid: the slot
|
||||
would otherwise be reported under a definition nothing confirms. Capacity
|
||||
refusals are never turned into issues. Rows that share one method spec
|
||||
(Il2CppDumper refuses such a table) each get an issue at their row address that
|
||||
names one other sharing row, and all of them lose `name` and become `unknown`.
|
||||
A zero pointer slot is a `no-body` row and has no issue. Before any row is
|
||||
resolved, the smallest row for every table entry is checked against the
|
||||
remaining report budget; each row and issue is then admitted as it is retained.
|
||||
Compact summaries omit `binary.generic_methods.issues` and keep its count in
|
||||
`counts.generic_method_issues`; query `collection: "generic_method_issues"`
|
||||
with `rows`, `indices`, `fields` and pagination. Select only the instance and
|
||||
issue facts needed for the question. For a small report where both collections
|
||||
are needed, `detail: "complete"` can cost less than a summary followed by two
|
||||
pages. Paging saves irrelevant row text but adds calls and schema overhead; it
|
||||
does not imply lower total latency or memory. See the
|
||||
[completed-query measurements](verification/il2cpp-generic-instances-2026-10-24.md).
|
||||
Like method addresses, these rows are derived from static tables; layout agreement
|
||||
is structural evidence, not proof of runtime use.
|
||||
|
||||
Contributor-reported verification against Il2CppDumper's `script.json` (same
|
||||
`Address` and `Name`):
|
||||
macOS arm64 and x86_64 slices from Unity 2020.3.49f1, 2021.1.28f1 (version 27),
|
||||
2021.3.45f2, 2022.3.30f1 (29), 2022.3.62f3 and 6000.0.84f1 (31); Android arm64
|
||||
from 2022.3.62f3; and the Windows x64 build from 2023.2.13f1 named above
|
||||
(`GameAssembly.dll` SHA-256
|
||||
`a3ae7f6ecd1f671297b7d98d12713ef024062d93cd7a4205298102656c93b67a`). On every
|
||||
build each linked instance matches an Il2CppDumper entry by address and name,
|
||||
and Il2CppDumper lists no address-name pair that REA leaves out (Windows: 63,750
|
||||
linked rows, 142 without code; Android: 5,152 and 44). This does not establish
|
||||
names for versions 24 or 39, for type arguments that are open generic type
|
||||
definitions, or anything about instances created at runtime. The Linux build
|
||||
from 2023.2.13f1 keeps no static CodeRegistration and is refused.
|
||||
|
||||
For metadata version 27, type names are `null` and only type indices are
|
||||
reported: versions 27.0 to 27.2 share that header number but place the
|
||||
Il2CppType byref flag in different bits, so a rendered name could gain or lose
|
||||
@@ -313,22 +431,25 @@ Il2CppType byref flag in different bits, so a rendered name could gain or lose
|
||||
|
||||
The builds checked are listed after the module search rules above.
|
||||
|
||||
| Reason | Category | Meaning |
|
||||
| --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- |
|
||||
| `unsupported-container` | unsupported | Not a 64-bit little-endian Mach-O, PE or ELF image (ELF: AArch64 or x86-64 with dynamic section). |
|
||||
| `slice-selection-required` | unsupported | A universal Mach-O was given without `binary_architecture`. |
|
||||
| `ambiguous-slice-selection` | unsupported | More than one universal slice matches the selected architecture label; select an exact subtype externally. |
|
||||
| `slice-not-found` | unsupported | The requested slice is absent, or a thin binary was given an architecture. |
|
||||
| `unsupported-pointer-encoding` | unsupported | Mach-O chained fixups or Android packed (APS2) ELF relocations; pointers not decoded. |
|
||||
| `malformed-container` | input error | The container headers are damaged. |
|
||||
| `code-gen-modules-not-found` | input error | An image has no module record; often a binary from a different build. |
|
||||
| `ambiguous-code-gen-module` | input error | More than one module record matches an image. |
|
||||
| `code-registration-not-found` | input error | No unique module table or executable-byte array candidate was resolved. |
|
||||
| `invalid-method-token` | input error | A token is outside its module's method-pointer rows, or a MethodDef row is reused within one image. |
|
||||
| `invalid-method-pointer` | input error | A slot is unavailable or its nonzero address lacks unambiguous executable file coverage. |
|
||||
| `metadata-registration-not-found` | input error | No single MetadataRegistration matches the type-definition count. |
|
||||
| `invalid-type` | input error | A type index or `Il2CppType` record is out of range, unmapped or malformed. |
|
||||
| `unsupported-type-kind` | unsupported | A valid type kind has no implemented rendering. |
|
||||
| Reason | Category | Meaning |
|
||||
| --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
| `unsupported-container` | unsupported | Not a 64-bit little-endian Mach-O, PE or ELF image (ELF: AArch64 or x86-64 with dynamic section). |
|
||||
| `slice-selection-required` | unsupported | A universal Mach-O was given without `binary_architecture`. |
|
||||
| `ambiguous-slice-selection` | unsupported | More than one universal slice matches the selected architecture label; select an exact subtype externally. |
|
||||
| `slice-not-found` | unsupported | The requested slice is absent, or a thin binary was given an architecture. |
|
||||
| `unsupported-pointer-encoding` | unsupported | Mach-O chained fixups or Android packed (APS2) ELF relocations; pointers not decoded. |
|
||||
| `malformed-container` | input error | The container headers are damaged. |
|
||||
| `code-gen-modules-not-found` | input error | An image has no module record; often a binary from a different build. |
|
||||
| `ambiguous-code-gen-module` | input error | More than one module record matches an image. |
|
||||
| `code-registration-not-found` | input error | No unique module table or executable-byte array candidate was resolved. |
|
||||
| `invalid-method-token` | input error | A token is outside its module's method-pointer rows, or a MethodDef row is reused within one image. |
|
||||
| `invalid-method-pointer` | input error | A slot is unavailable or its nonzero address lacks unambiguous executable file coverage. |
|
||||
| `metadata-registration-not-found` | input error | No single MetadataRegistration or code-loaded type-table candidate was resolved. |
|
||||
| `invalid-type` | input error | A type index or `Il2CppType` record is out of range, unmapped or malformed. |
|
||||
| `unsupported-type-kind` | unsupported | A valid type kind has no implemented rendering. |
|
||||
| `generic-methods-unsupported` | unsupported | Generic instances were requested for metadata version 24 or 39, or a build lacks either static registration. |
|
||||
| `generic-method-registration-not-found` | input error | No CodeRegistration layout bounds every genericMethodTable row, or the generic tables are unreadable. |
|
||||
| `ambiguous-generic-method-registration` | input error | More than one CodeRegistration layout bounds every genericMethodTable row. |
|
||||
|
||||
Format and selection failures name `binary_path`; capacity refusals remain typed resource errors. Failed linking preserves the metadata source identity, validated counts, selected binary path/architecture and its SHA-256 when observed, plus prior producer observations. It never publishes an incomplete native table as complete. The binary input is bounded to 1 GiB.
|
||||
|
||||
@@ -338,7 +459,7 @@ ELF RELATIVE writes into zero-fill are kept as a private virtual-pointer overlay
|
||||
|
||||
ELF relocation tables and file-backed destinations may span adjacent load ranges when every range agrees on the file translation. Any overlapping zero-fill declaration makes those bytes ambiguous; REA refuses the table or relocation destination instead of choosing the stored file bytes. Missing file bytes remain distinct from conflicting owners: supported unresolved relocations outside file-backed memory retain their unknown overlay, while ambiguous destinations refuse linking. Registration coverage uses the same file/zero-fill ownership checks as pointer reads.
|
||||
|
||||
Native address queries batch exact 64-bit hexadecimal `addresses` and `states` (`code`, `no-body`, `unknown`), intersecting indices and pagination. Numerically equal address spellings match; original row indices and every shared-body alternative survive:
|
||||
Native address queries batch exact 64-bit hexadecimal `addresses` and `states` (`code`, `no-body`, `unknown`), intersecting indices and pagination; `generic_method_instances` accepts the same filters plus `method_indices` (generic definition indices). Numerically equal address spellings match; original row indices and every shared-body alternative survive:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -377,7 +498,10 @@ loaders place the binary: `0x100000` for an ELF linked at 0, and the link base
|
||||
for Mach-O and PE; `--seed-base 0x...` overrides it for a different import. When
|
||||
identical code folding gives several methods one address, the first method names
|
||||
the function and a `# folded <address> <kept> also <names>` comment line after
|
||||
the seeds lists the others, so the kept name is visibly one of several. Ghidra still names a seeded function that is a thunk after its
|
||||
the seeds lists the others, so the kept name is visibly one of several. With
|
||||
`--generic-instances`, linked generic instances are seeded after the method
|
||||
definitions under their Il2CppDumper-style names; an instance sharing an
|
||||
address with a definition or another instance is folded the same way. Ghidra still names a seeded function that is a thunk after its
|
||||
target. The file is atomically published with exclusive creation; an existing destination is never replaced. Failed staging retains its cleanup owner for retry. Source digest and link/seed-base comments make the mapping inspectable. Unknown slots are skipped separately from observed no-body slots. `--seed-base` requires `--ghidra-seeds`; overflowing rebased addresses and names/outputs beyond the existing Ghidra protocol limits (2,000 name characters, 32 MiB file, 1,000,000 entries) are refused before publication. The CLI and reusable service use one formatter and owned output workflow; ordinary MCP inspection remains read-only.
|
||||
|
||||
## Failures
|
||||
@@ -430,10 +554,11 @@ report limit can still require the summary and paging path.
|
||||
|
||||
- Decrypting or deobfuscating protected metadata.
|
||||
- Linking Mach-O binaries that use chained fixups, ELF images with Android
|
||||
packed (APS2) relocations, and 32-bit images; generic method instances,
|
||||
adjustor thunks and invokers.
|
||||
packed (APS2) relocations, and 32-bit images; adjustor thunks and invokers;
|
||||
generic method instances for metadata versions 24 and 39 or builds without a static
|
||||
CodeRegistration.
|
||||
- Full method signatures beyond the rendered field, parameter and return type
|
||||
names, generic method instances, and type names for metadata version 27.
|
||||
names, and type names for metadata version 27.
|
||||
- Running Ghidra or another disassembler. `--ghidra-seeds` only writes a seed
|
||||
file for [`REA_GHIDRA_SEED_FILE`](installation.md); use the
|
||||
[native workflow](native-investigation.md) for native code.
|
||||
|
||||
+14
-13
@@ -47,19 +47,20 @@ For runtime instrumentation, see the [Frida guide](./frida-instrumentation.md).
|
||||
|
||||
## Choose a guide
|
||||
|
||||
| Task | Guides |
|
||||
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Identify a desktop installation | [Runtime candidates, evidence and follow-up files](desktop-applications.md) |
|
||||
| Inspect native functions, references, or types | [Native binaries](native-investigation.md), [Go metadata](go-binaries.md), [Rust dependencies](rust-binaries.md), [CPython pyc files](python-pyc.md), [PE certificates](pe-certificates.md), [PE imports](pe-imports.md), [ELF notes](elf-notes.md), [Erlang BEAM](erlang-beam.md), [offline ELF layout](binary-diagnostics.md), [recorded crashes](recorded-crashes.md) |
|
||||
| Select a native provider or import format | [Ghidra semantics](ghidra-provider.md), [Windows](windows-ghidra-p0.md), [DOS](ghidra-dos.md), [raw bytes](raw-binary.md), [MIPS](ghidra-mips.md), [PSP](ghidra-psp.md), [NativeAOT](ghidra-nativeaot.md), [IDA](ida-provider.md), [Kuna](kuna-provider.md), [JEB](jeb-analysis.md) |
|
||||
| Analyze JavaScript or Electron artifacts | [Static analysis](javascript-artifact-reconstruction.md), [tracing and comparisons](javascript-application-workflows.md), [application graph](javascript-application-graph.md), [source recovery](javascript-recovery.md) |
|
||||
| Compare static JavaScript with runtime observations | [Runtime attribution](javascript-runtime-observation.md), [reconciliation](javascript-runtime-reconciliation.md), [Electron observation](electron-observation.md), [Electron fuses](electron-fuses.md) |
|
||||
| Inspect assemblies, packages, or firmware | [Godot PCK](godot-pck.md), [.NET](managed-code-analysis.md), [Python packages](python-packaged-applications.md), [Android](android-analysis.md), [APK signatures](apk-signature.md), [Apktool resources](apktool-resource-analysis.md), [ADB acquisition](adb-device-analysis.md), [Apple](apple-application-analysis.md), [Harmony](harmony-analysis.md), [firmware](firmware-analysis.md), [WASM](wasm-artifacts.md), [EVM](evm-bytecode.md) |
|
||||
| Observe or compare a browser scenario | [CDP observation](browser-observation.md), [scenarios](browser-scenario-contract.md), [runtime evidence](web-runtime.md), [historical captures](web-network-captures.md) |
|
||||
| Serve recorded behavior as an agent environment | [Agent environments](agent-environments.md) |
|
||||
| Trace captured website source | [Source locations](web-source-location.md), [module traces](website-module-trace.md), [script export](website-script-export.md) |
|
||||
| Capture and compare a command | [Process capture](process-capture.md) |
|
||||
| Use CLI/MCP and retain evidence | [CLI](cli.md), [MCP contracts](mcp-contracts.md), [agent prompts](mcp-prompts.md), [obligation ledgers](reconstruction-obligation-ledgers.md) |
|
||||
| Task | Guides |
|
||||
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Identify a desktop installation | [Runtime candidates, evidence and follow-up files](desktop-applications.md) |
|
||||
| Inspect native functions, references, or types | [Native binaries](native-investigation.md), [Go metadata](go-binaries.md), [Rust dependencies](rust-binaries.md), [CPython pyc files](python-pyc.md), [PE certificates](pe-certificates.md), [PE imports](pe-imports.md), [PE TLS/load config](pe-load-config.md), [ELF notes](elf-notes.md), [Linux kernel modules](kernel-modules.md), [Apple IPS](apple-ips.md), [Erlang BEAM](erlang-beam.md), [offline ELF layout](binary-diagnostics.md), [recorded crashes](recorded-crashes.md) |
|
||||
| Inspect native functions, references, or types | [Native binaries](native-investigation.md), [Go metadata](go-binaries.md), [Rust dependencies](rust-binaries.md), [CPython pyc files](python-pyc.md), [PE certificates](pe-certificates.md), [PE imports](pe-imports.md), [PE TLS/load config](pe-load-config.md), [ELF notes](elf-notes.md), [Apple IPS](apple-ips.md), [Erlang BEAM](erlang-beam.md), [offline ELF layout](binary-diagnostics.md), [recorded crashes](recorded-crashes.md) |
|
||||
| Select a native provider or import format | [Ghidra semantics](ghidra-provider.md), [Windows](windows-ghidra-p0.md), [DOS](ghidra-dos.md), [raw bytes](raw-binary.md), [GameCube DOL](ghidra-dol.md), [MIPS](ghidra-mips.md), [PSP](ghidra-psp.md), [NativeAOT](ghidra-nativeaot.md), [IDA](ida-provider.md), [Kuna](kuna-provider.md), [JEB](jeb-analysis.md) |
|
||||
| Analyze JavaScript or Electron artifacts | [Static analysis](javascript-artifact-reconstruction.md), [tracing and comparisons](javascript-application-workflows.md), [application graph](javascript-application-graph.md), [source recovery](javascript-recovery.md) |
|
||||
| Compare static JavaScript with runtime observations | [Runtime attribution](javascript-runtime-observation.md), [reconciliation](javascript-runtime-reconciliation.md), [Electron observation](electron-observation.md), [Electron fuses](electron-fuses.md) |
|
||||
| Inspect assemblies, packages, or firmware | [Godot PCK](godot-pck.md), [.NET](managed-code-analysis.md), [Python packages](python-packaged-applications.md), [Android](android-analysis.md), [APK signatures](apk-signature.md), [Apktool resources](apktool-resource-analysis.md), [ADB acquisition](adb-device-analysis.md), [Apple](apple-application-analysis.md), [Harmony](harmony-analysis.md), [firmware](firmware-analysis.md), [WASM](wasm-artifacts.md), [EVM](evm-bytecode.md) |
|
||||
| Observe or compare a browser scenario | [CDP observation](browser-observation.md), [scenarios](browser-scenario-contract.md), [runtime evidence](web-runtime.md), [historical captures](web-network-captures.md) |
|
||||
| Serve recorded behavior as an agent environment | [Agent environments](agent-environments.md) |
|
||||
| Trace captured website source | [Source locations](web-source-location.md), [module traces](website-module-trace.md), [script export](website-script-export.md) |
|
||||
| Capture and compare a command | [Process capture](process-capture.md) |
|
||||
| Use CLI/MCP and retain evidence | [CLI](cli.md), [MCP contracts](mcp-contracts.md), [agent prompts](mcp-prompts.md), [obligation ledgers](reconstruction-obligation-ledgers.md) |
|
||||
|
||||
For development, use [testing](testing.md), [client verification](client-verification.md),
|
||||
[tool design](tool-design.md), [admission limits and recovery](design/limits-and-recovery.md),
|
||||
|
||||
+32
-3
@@ -681,6 +681,12 @@ search permissions (`0700`) on a directory you own before retrying.
|
||||
|
||||
On supported Linux distributions, approved setup verifies Hopper's official
|
||||
`.deb`, `.rpm`, or Arch package before invoking the native package manager.
|
||||
On apt systems, Hopper's runtime dependencies are installed with
|
||||
`--no-upgrade` in their own transaction, so setup no longer names an
|
||||
already-installed dependency as an upgrade target. apt can still upgrade a
|
||||
package that the Hopper package or the Python library repair requires at a
|
||||
newer version. Arch's `pacman -S --needed` still updates an outdated
|
||||
dependency.
|
||||
The official release feed selects the current public demo without a version
|
||||
pin. REA verifies the package's detached PGP signature against Hopper's stable
|
||||
primary fingerprint `7C2D73BAFAF5B9A710A69DA1A26DF815099B1BCD`, then checks
|
||||
@@ -745,6 +751,18 @@ may conflict with Hopper's versioned `zlib` dependency. Resolve the package
|
||||
conflict yourself, install Hopper's official package manually, or use another
|
||||
provider such as Ghidra; rerun `rea setup` after installing Hopper.
|
||||
|
||||
If setup cannot finish releasing its resources, a normally returned structured
|
||||
result reports `needs_human` and includes `cleanup.reason` with the identified
|
||||
paths in `cleanup.resources`. A thrown typed failure reports the same retained
|
||||
paths in `details.resources`, preserving the primary failure separately. Reasons
|
||||
that do not identify a resource remain explicit without guessing paths from text.
|
||||
For in-process callers retaining REA's setup host, a successful retry of its close
|
||||
updates the original failure's cleanup state and removes released resource labels.
|
||||
Custom `SetupHost` implementations must bind returned or thrown cleanup errors
|
||||
to their resource owners to provide the same live recovery. An ownerless error
|
||||
remains an unconfirmed snapshot: `runSetup` does not observe later direct calls
|
||||
to the caller's port or replace that port's methods.
|
||||
|
||||
The supported Linux demo forwards additional launches into its existing
|
||||
application, even across private displays. REA therefore reserves one Linux
|
||||
Hopper application per user across cooperating REA processes. A competing
|
||||
@@ -985,9 +1003,13 @@ Target admission preserves recognized PE/NE/LE/LX signatures separately from
|
||||
reader layout support. A Windows header overlapping the first 64 DOS-header
|
||||
bytes remains an unsupported layout in this release; it is not reported as an
|
||||
invalid offset. Tiny PE files with short optional headers have additional
|
||||
unverified loader requirements. Unconfirmed nonzero DOS padding remains an
|
||||
unresolved Windows-header candidate, with independently validated DOS facts in
|
||||
the target error diagnostics; those facts do not prove a Windows header absent.
|
||||
unverified loader requirements. A nonzero Windows-header pointer without a
|
||||
recognized signature remains an unresolved candidate, with independently
|
||||
validated DOS facts in the target error diagnostics; those facts do not prove a
|
||||
Windows header absent. When a nonempty relocation table ends inside a complete
|
||||
DOS header, the remaining header bytes are DOS padding, so a nonzero dword
|
||||
there is not a Windows declaration. An unread signature beyond the current
|
||||
probe is requested before that padding rule applies.
|
||||
On Linux and macOS, `annotate_native_function` also edits a function name and/or
|
||||
entry comments atomically and returns refreshed analysis, and `set_address_name`
|
||||
and `set_addresses_names` name a function entry or any other mapped address
|
||||
@@ -1446,6 +1468,13 @@ setup runs through `bunx`, and pins it to the exact version that performed
|
||||
setup. Run current setup to refresh an older registration, then restart the
|
||||
client.
|
||||
|
||||
Package runners key their package cache by the requested spec, so the entry
|
||||
installed for the `@latest` invocation that ran setup cannot serve the pinned
|
||||
registration. Setup therefore materializes the pinned entry once, best-effort
|
||||
with a bounded timeout, before finishing. When that step cannot run, for
|
||||
example offline, the first client start performs the one-time install inside
|
||||
the client's MCP startup deadline and may need one more restart.
|
||||
|
||||
## Package runners and global installation
|
||||
|
||||
A package-runner invocation can use a REA version installed in the current project. To
|
||||
|
||||
@@ -448,8 +448,10 @@ uncertainty rather than pretending to execute later writes. References
|
||||
handed back by local functions, methods, constructors, async functions, and
|
||||
generators also retain escape uncertainty, including when the call is read-only;
|
||||
this does not establish that a mutation occurred. Aliases
|
||||
and shared children in spread and rest copies retain that uncertainty; copied
|
||||
primitive slots and unrelated containing properties remain known. Object rest
|
||||
and shared children in spread and rest copies retain that uncertainty. Exposing
|
||||
the copy alone does not invalidate copied primitive slots or unrelated containing
|
||||
properties. Dynamic child writes such as `copy[key].value = 2` remain conservative
|
||||
about which original slot was selected. Object rest
|
||||
excludes consumed keys, array rest excludes the consumed prefix for known
|
||||
arrays, and later explicit data properties and methods replace earlier object
|
||||
spread references. A known array prefix does not expose values from a following
|
||||
@@ -466,6 +468,11 @@ Receiver projections follow known data fields initialized from `this` or earlier
|
||||
self-referencing fields; static fields retain their declaring class identity.
|
||||
An alias cycle that repeatedly selects deeper children retains escape uncertainty
|
||||
at its recovered roots rather than claiming a fixed number of loop iterations.
|
||||
Equivalent member reads in a repeating loop share unknown ordering instead of
|
||||
creating a distinct capture for every branch history. Straight-line captures and
|
||||
once-only loop inputs retain their own selection sites. When unobserved suffixes
|
||||
are widened, their exact observed prefixes stay separate so unrelated siblings
|
||||
remain known.
|
||||
|
||||
Writes through an object getter's returned receiver retain that uncertainty
|
||||
when the object is an array element, nested inside mixed object/array
|
||||
@@ -510,8 +517,13 @@ escape uncertainty. External prototype changes and unsupported runtime protocols
|
||||
remain unknown rather than supplying exact post-invocation values.
|
||||
Identifier references and closure captures share Babel syntax-role facts plus
|
||||
explicit binding/write roles; noncomputed declaration keys and import/meta names
|
||||
are not lexical reads. Provenance-only expression-depth omissions enter the same typed source coverage
|
||||
as value-evaluation bounds and remain visible in retained application Evidence.
|
||||
are not lexical reads. TypeScript type positions, including `typeof` type queries
|
||||
and computed keys in erased signatures, do not evaluate JavaScript bindings or
|
||||
create runtime calls or captures. Decorators on declared class fields can still
|
||||
run when the class is defined, and a decorated declared or abstract field can
|
||||
evaluate its computed key. Provenance-only expression-depth omissions enter
|
||||
the same typed source coverage as value-evaluation bounds and remain visible in
|
||||
retained application Evidence.
|
||||
Immediate synchronous function results also share the loader reference owner.
|
||||
An expression arrow returning the retained CommonJS `require` can preserve that
|
||||
loader identity. Possible loader results with opaque alternatives or block
|
||||
|
||||
@@ -399,13 +399,19 @@ Bundler adapters own callback roles: Webpack supplies module, exports, then
|
||||
loader; esbuild CommonJS supplies exports, then module. Export extraction uses
|
||||
those binding identities for assignments and declarations, so renaming either
|
||||
parameter does not change the recovered names. Global property-definition
|
||||
intrinsics require lexical and visible-write proof. Computed writes through a
|
||||
standalone loader's exposed module/cache table use the shared value owner; an
|
||||
unknown key invalidates the original-slot proof rather than implying a fresh
|
||||
chunk installation. A function stored on a standalone loader member does not
|
||||
write the table merely by being defined: the bootstrap owner excludes its
|
||||
deferred writes only when that member is unread and the loader namespace stays
|
||||
confined. Calls, member aliases, dynamic member reads, namespace escapes, or
|
||||
intrinsics require lexical and visible-write proof. Factory export declarations
|
||||
also require the loader's `d` member to have no prior or unordered visible
|
||||
replacement, including writes through lexical aliases. Unrelated loader members
|
||||
do not invalidate declarations. Ordering describes declarations within one factory
|
||||
activation; helper integrity on entry, effects of earlier invocations, and
|
||||
arbitrary call side effects remain unproven.
|
||||
Computed writes through a standalone loader's exposed module/cache table use
|
||||
the shared value owner; an unknown key invalidates the original-slot proof
|
||||
rather than implying a fresh chunk installation. A function stored on a
|
||||
standalone loader member does not write the table merely by being defined:
|
||||
the bootstrap owner excludes its deferred writes only when that member is
|
||||
unread and the loader namespace stays confined. Calls, member aliases, dynamic
|
||||
member reads, namespace escapes, or
|
||||
receiver-based access retain uncertainty about those writes. Export names
|
||||
describe recognized declarations, not a proof
|
||||
of final runtime property lifetime or arbitrary helper behavior.
|
||||
|
||||
@@ -0,0 +1,174 @@
|
||||
# Linux kernel modules
|
||||
|
||||
`inspect_kernel_module` / `inspect-kernel-module` reads metadata from one
|
||||
selected local ELF32/ELF64 relocatable object (`.ko`) without executing it.
|
||||
That metadata is the `.modinfo` key/value strings, the `__versions` symbol
|
||||
CRCs, the presence of `.gnu.linkonce.this_module` and `__ksymtab*` sections,
|
||||
the observed file sizes of `.init.text` and `.exit.text`, and an optional
|
||||
appended signature trailer. It does not require a Linux host or the `modinfo`
|
||||
program.
|
||||
|
||||
```bash
|
||||
rea inspect-kernel-module /absolute/path/to/module.ko --json
|
||||
```
|
||||
|
||||
The CLI resolves relative paths against the caller's working directory. MCP
|
||||
requires an absolute filesystem path and preserves that exact selection:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "inspect_kernel_module",
|
||||
"arguments": { "path": "/artifacts/demo.ko" }
|
||||
}
|
||||
```
|
||||
|
||||
## Observations
|
||||
|
||||
The inline Evidence result contains the artifact path, SHA-256, and byte
|
||||
length. `applicability` is `applicable` only for `ET_REL`. Other ELF types are
|
||||
`not_applicable`: header facts are filled and `.modinfo`, `__versions`, and
|
||||
the signature trailer are not examined.
|
||||
|
||||
`.modinfo` entries stay in file order. Duplicate keys such as `alias` and
|
||||
`parm` are preserved. Each entry keeps its key, value, file range, and
|
||||
SHA-256. Values are the bytes after the first `=`. NUL padding between
|
||||
strings is skipped. Keys and values use a byte-preserving Latin1 projection:
|
||||
each source byte becomes the same-numbered Unicode code point. They are not
|
||||
decoded as UTF-8. `raw_sha256` hashes the original entry bytes, including its
|
||||
terminating NUL when present; `raw_hex` shows those bytes when they fit the
|
||||
inline limit.
|
||||
|
||||
`__versions` entries are `struct modversion_info`: a 64-byte record whose CRC
|
||||
is an `unsigned long` and whose name occupies the remaining bytes. ELF32
|
||||
stores a 32-bit CRC and a 60-byte name. ELF64 stores a 64-bit unsigned long
|
||||
and a 56-byte name. CRCs are zero-padded lowercase hex, 8 or 16 characters,
|
||||
not a JavaScript number. The layout is reported from the ELF class even when
|
||||
the section is absent. Names use the same byte-preserving Latin1 projection
|
||||
as `.modinfo` keys and values. Only this classic `__versions` layout is
|
||||
decoded. `versions.status: "absent"` means no `__versions` section was found
|
||||
when section names were complete; it does not establish the absence of version
|
||||
metadata in `__version_ext_names` and `__version_ext_crcs`, which Linux uses
|
||||
with `CONFIG_EXTENDED_MODVERSIONS` and this workflow does not decode.
|
||||
|
||||
`.gnu.linkonce.this_module` is reported as present, absent, or unknown.
|
||||
`layout` is always `unknown` because `struct module` changes with the kernel
|
||||
version and is not decoded. File-backed `__ksymtab*` sections are listed in
|
||||
section-header order by name and file range; their records are not decoded.
|
||||
Sections that are `SHT_NOBITS` or leave the file are counted in one limitation
|
||||
without their names. `.init.text` and `.exit.text` report the
|
||||
observed file-backed size. A compressed payload reports the stored size and a
|
||||
limitation that the decoded size is unknown.
|
||||
|
||||
The signature trailer is the 27-byte magic `~Module signature appended~\n`
|
||||
preceded by a 12-byte `module_signature` (`algo`, `hash`, `id_type`,
|
||||
`signer_len`, `key_id_len`, three pad bytes, and big-endian `sig_len`). When
|
||||
those parameter fields are zero and `id_type` is PKCS#7 (`2`), the preceding
|
||||
`sig_len` bytes are the PKCS#7 range and its SHA-256. The range is not parsed
|
||||
and no certificate, signer, or digest-coverage claim is made. An absent
|
||||
trailer is observed absence, not proof the module is unsigned.
|
||||
|
||||
When section names are incomplete, a missing named section is `unknown`
|
||||
rather than `absent`. An empty file-backed section is present and empty.
|
||||
|
||||
## Limits and failures
|
||||
|
||||
The selected file is limited to 64 MiB by default (512 MiB maximum). At most
|
||||
8192 `.modinfo` and `__versions` entries plus listed `__ksymtab*` sections are
|
||||
examined by default (65536 maximum); `coverage.examined_entries` counts all
|
||||
three. Exceeding that budget fails with no partial success. Keys longer
|
||||
than 256 bytes and values longer than 4096 bytes stay malformed per entry;
|
||||
the field that fits is still copied. A `__ksymtab*` section name longer than
|
||||
256 bytes keeps its range with `name: null` and `ksymtab_name_exceeds_limit`. Inline raw hex stops at 4096 bytes and
|
||||
the SHA-256 remains.
|
||||
|
||||
A `.modinfo` span with no trailing NUL is `unterminated_modinfo_entry` and
|
||||
earlier entries are kept. A string with no `=` is `modinfo_missing_separator`.
|
||||
An empty key is `modinfo_empty_key`. A `__versions` name with no NUL is
|
||||
`version_name_unterminated`. A `__versions` section whose size is not a
|
||||
multiple of 64 bytes is closed with `versions_size_not_multiple` and no
|
||||
entries. `SHT_NOBITS` or a declared range that leaves the file is
|
||||
`modinfo_section_not_file_backed` or `versions_section_not_file_backed`.
|
||||
`SHF_COMPRESSED` payloads are not inflated
|
||||
(`modinfo_section_compressed`, `versions_section_compressed`).
|
||||
|
||||
An appended magic with fewer than 12 preceding bytes is
|
||||
`signature_trailer_truncated`. A `sig_len` that does not leave at least one
|
||||
module byte is `signature_length_inconsistent`. Nonzero `algo`, `hash`,
|
||||
signer, key-id, or pad fields for PKCS#7 are `signature_parameters_nonzero`.
|
||||
A parameter block whose `id_type` is not PKCS#7 is
|
||||
`signature_id_type_not_pkcs7` and is unsupported rather than a validated
|
||||
signature.
|
||||
|
||||
gzip (`1f 8b`), xz (`fd 37 7a 58 5a 00`), and zstd (`28 b5 2f fd`) whole-file
|
||||
containers are `unsupported`. The result names `external_decompression` as the
|
||||
next probe and does not claim the payload is a kernel module. This is an external
|
||||
step, not a REA operation: neither this tool nor `extract_artifact` decodes these
|
||||
containers. Use an external gzip, xz, or zstd utility to decompress into a separate
|
||||
file, then call `inspect_kernel_module` on that file to inspect the `ET_REL` image.
|
||||
|
||||
Malformed ELF headers return no partial kernel-module metadata. This workflow
|
||||
does not execute the module or validate an appended signature.
|
||||
|
||||
## Format references
|
||||
|
||||
The record layout follows Linux v6.12's
|
||||
[`modversion_info`](https://github.com/torvalds/linux/blob/v6.12/include/linux/module.h)
|
||||
and [`MAX_PARAM_PREFIX_LEN`](https://github.com/torvalds/linux/blob/v6.12/include/linux/moduleparam.h).
|
||||
The [Linux kbuild module versioning guide](https://docs.kernel.org/kbuild/modules.html#module-versioning)
|
||||
describes the separate extended version sections.
|
||||
Trailer fields and acceptance rules follow
|
||||
[`module_signature`](https://github.com/torvalds/linux/blob/v6.12/include/linux/module_signature.h)
|
||||
and [`mod_check_sig`](https://github.com/torvalds/linux/blob/v6.12/kernel/module_signature.c).
|
||||
These references establish the decoded layout, not runtime verification.
|
||||
|
||||
## Real-module verification lane
|
||||
|
||||
Run from a built checkout with Docker available. This downloads a Debian kernel
|
||||
package into a disposable container, extracts a filesystem module, decompresses
|
||||
it when necessary, and inspects it with REA. It never installs or loads that
|
||||
kernel module. The temporary output is outside the repository; record the
|
||||
printed package version and module digest with results.
|
||||
|
||||
```bash
|
||||
module_lane=$(mktemp -d)
|
||||
docker run --rm -i -v "$module_lane:/out" debian:stable bash -se <<'CONTAINER'
|
||||
apt-get update -qq
|
||||
apt-get install -y --no-install-recommends xz-utils zstd ca-certificates
|
||||
cd /tmp
|
||||
arch=$(dpkg --print-architecture)
|
||||
package=$(apt-cache depends "linux-image-$arch" | awk '/Depends: linux-image-[0-9]/{print $2; exit}')
|
||||
test -n "$package"
|
||||
apt-get download "$package"
|
||||
dpkg-deb -f ./*.deb Package Version > /out/package.txt
|
||||
dpkg-deb -x ./*.deb /tmp/kernel
|
||||
module=$(find /tmp/kernel -type f -path '*/kernel/fs/*' \( -name '*.ko' -o -name '*.ko.xz' -o -name '*.ko.zst' -o -name '*.ko.gz' \) | sort | head -1)
|
||||
test -n "$module"
|
||||
case "$module" in
|
||||
*.xz) xz -dc "$module" > /out/module.ko ;;
|
||||
*.zst) zstd -dc "$module" > /out/module.ko ;;
|
||||
*.gz) gzip -dc "$module" > /out/module.ko ;;
|
||||
*) cp "$module" /out/module.ko ;;
|
||||
esac
|
||||
cat /out/package.txt
|
||||
sha256sum /out/module.ko
|
||||
CONTAINER
|
||||
node scripts/rea.mjs inspect-kernel-module "$module_lane/module.ko" --json > "$module_lane/rea.json"
|
||||
python3 - "$module_lane" <<'PY'
|
||||
import json, pathlib, sys
|
||||
root = pathlib.Path(sys.argv[1])
|
||||
report = json.loads((root / 'rea.json').read_text())['normalized_result']
|
||||
entries = report['modinfo']['entries']
|
||||
assert entries and all(entry['status'] == 'observed' for entry in entries)
|
||||
keys = [entry['key'] for entry in entries]
|
||||
for key in ('license', 'vermagic', 'name'):
|
||||
assert key in keys, key
|
||||
print('Observed .modinfo entries:', len(entries), 'distinct keys:', len(set(keys)))
|
||||
print('Artifact:', report['artifact'])
|
||||
PY
|
||||
```
|
||||
|
||||
`parm` and `parmtype` are retained separately by REA. Synthetic tests cover
|
||||
their generic key/value representation and all four ELF class/byte-order
|
||||
combinations. A successful real lane verifies only the selected module and
|
||||
printed fields; it does not validate certificates. This lane has not run in the
|
||||
sandbox used for implementation because access to the Docker socket was denied.
|
||||
@@ -68,11 +68,14 @@ byte correspondence or decode the map's original source paths.
|
||||
Artifact inventories declare `coverage.scope` (`root` or `container-entries`)
|
||||
and `coverage.status` (`complete` or `unknown`) independently of diagnostic
|
||||
wording. Comparison requires matching scopes, complete graph members and complete
|
||||
traversal coverage before concluding equality. A fully observed root without
|
||||
container children can be `unchanged`; its scope notice stays in `limitations`
|
||||
without creating a gap. Content and executable metadata changes still produce
|
||||
root deltas. Missing graph members yield `truncated`; unknown traversal coverage
|
||||
or unavailable occurrence hashes retain uncertainty. Integrity mismatches remain
|
||||
traversal coverage before concluding equality. Fully observed roots can be
|
||||
`unchanged` within root scope; their scope notice stays in `limitations` without
|
||||
creating a gap. Root-scoped equality establishes equality of the observed root
|
||||
bytes. Child-container presence and unexamined format details remain unresolved,
|
||||
including when the root format is `unknown`. Content and executable metadata
|
||||
changes still produce root deltas. Missing graph members yield `truncated`;
|
||||
unknown traversal coverage or unavailable occurrence hashes retain uncertainty.
|
||||
Integrity mismatches remain
|
||||
contradictions. Static artifact equality does not establish unchanged runtime
|
||||
behavior.
|
||||
Source-map relation deltas include the content identity of the mapped source,
|
||||
|
||||
@@ -511,15 +511,25 @@ to the linked Mach-O. This classification requires both the recognized native
|
||||
refusal and an independently parsed dSYM Mach header; other tool failures keep
|
||||
their failure outcome.
|
||||
|
||||
Observed `dyld_info` diagnostics include `unknown mh.filetype 4` and
|
||||
`unknown filetype 4` for `MH_CORE`, and the corresponding `3` spellings for
|
||||
`MH_FVMLIB`. These refusals report `unsupported_target` when the independently
|
||||
parsed Mach header confirms the reported file type. The error retains the exact
|
||||
native diagnostic and recommends a linked Mach-O executable or relocatable
|
||||
object. This classifies the selected target's refusal; it does not establish
|
||||
support for core-dump analysis, historical FVMLIB layouts, or unobserved native
|
||||
diagnostic spellings. Unknown or contradictory header values and signalled
|
||||
commands remain failures.
|
||||
|
||||
`inspect_macho.selected_architecture` identifies the exact selected lipo slice
|
||||
and its `container_file_offset` in the input file. A thin Mach-O has a known
|
||||
offset of zero; an unknown universal-slice offset stays null. The Evidence
|
||||
subject format describes the input container: `mach-o-universal` for FAT files,
|
||||
including those with one slice. The normalized result describes the selected
|
||||
Mach-O image. Architecture
|
||||
`file_offset` values are container-relative. Entrypoint, segment and section
|
||||
`file_offset` values retain their source meaning and are relative to the
|
||||
selected Mach-O slice. Raw load-command fields retain their original values.
|
||||
including those with one slice. The normalized result also reports the container
|
||||
in `format`; `selected_architecture` identifies the selected Mach-O image.
|
||||
Architecture `file_offset` values are container-relative. Entrypoint, segment
|
||||
and section `file_offset` values retain their source meaning and are relative
|
||||
to the selected Mach-O slice. Raw load-command fields retain their original values.
|
||||
A field otool prints more than once, such as each `LC_BUILD_VERSION` tool, is
|
||||
keyed `name #n` in print order. Each `LC_LINKER_OPTION` string is keyed
|
||||
`string #n` and checked against the declared `count`. Evidence locations map the LC_MAIN entrypoint and nonempty file-backed segment
|
||||
@@ -556,6 +566,10 @@ complete observation.
|
||||
its outcome. Paths outside the analyzed root, including shared-cache system
|
||||
libraries, stay undetermined. See
|
||||
[Apple application analysis](apple-application-analysis.md#dylib-load-resolution).
|
||||
ARM64 slice labels distinguish `arm64v8`, `arm64e`, and `arm64e.x1` while
|
||||
retaining raw CPU subtype and capability bits. The `arm64` and `arm64e`
|
||||
request filters select their respective families; a shared family label
|
||||
does not establish dependency compatibility across different subtypes.
|
||||
Executable-root discovery preserves traversal uncertainty, including
|
||||
undecodable filenames and skipped symlinks, as partial coverage. Known
|
||||
executable roots remain available; unexamined names and symlink targets
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
# Node.js single executable applications
|
||||
|
||||
REA inventories injected Node.js SEA blobs through `inspect-artifact` /
|
||||
`inspect_artifact` and materializes their contents through `extract-artifact` /
|
||||
`extract_artifact`. It never runs the application or deserializes V8 snapshots
|
||||
or code cache.
|
||||
|
||||
```sh
|
||||
rea inspect-artifact ./application --json
|
||||
rea inspect-artifact ./application --detail summary --evidence_output evidence.json --json
|
||||
rea extract-artifact ./application --json
|
||||
```
|
||||
|
||||
For MCP, open the carrier with `open_binary`, then call `inspect_artifact`.
|
||||
Summary delivery retains the complete Evidence: use `parent_evidence_id` with
|
||||
`inspect_analysis_view` to request particular inventory paths and fields.
|
||||
Extraction returns a fresh `output_root`; analyze that extracted directory with
|
||||
`analyze_javascript_application`. Snapshot-only applications have no recovered
|
||||
main script and receive no JavaScript next probe. Neither does a main script
|
||||
whose logical path lacks a JavaScript source suffix, such as `main`, because the
|
||||
analyzer selects extracted files by suffix.
|
||||
|
||||
## Recognition and evidence
|
||||
|
||||
The container format is `node-sea`. REA locates Mach-O sections named
|
||||
`__NODE_SEA_BLOB` in `NODE_SEA` or `__NODE_SEA`, ELF notes owned by
|
||||
`NODE_SEA_BLOB`, and PE RCDATA resources named `NODE_SEA_BLOB`. PE resource
|
||||
locations come from the shared PE resource parser. ELF program-header
|
||||
`PT_NOTE` segments are authoritative, as at runtime; `SHT_NOTE` sections are
|
||||
read only when no program-header table is readable, because injectors can
|
||||
leave stale section entries. A PE without a `NODE_SEA_BLOB` resource name is
|
||||
left to native classification. Universal Mach-O carriers
|
||||
with different slice blobs are rejected as ambiguous; identical blobs are
|
||||
inventoried once. Native carrier bytes keep their content hash and native
|
||||
classification while the root occurrence represents the SEA container.
|
||||
|
||||
Root `format_metadata` preserves raw flags, decoded flags, code path, blob
|
||||
location, exec arguments and fuse observations. Main and asset children retain
|
||||
their role and exact declared name in `source_path`. Safe, noncolliding names
|
||||
become logical paths after the shared NFC path normalization. Names that are
|
||||
unsafe as relative paths, have an exact or file-prefix collision with another
|
||||
entry, or occupy the reserved `__node_sea__`
|
||||
namespace receive deterministic logical paths: `__node_sea__/main.cjs` for the
|
||||
main CommonJS source and `__node_sea__/assets/<ordinal>` for assets, using their
|
||||
zero-based order in the blob. The original declared name remains
|
||||
in `source_path`, including an empty asset key. Snapshots and code caches use
|
||||
`__node_sea__/snapshot` and `__node_sea__/code-cache`. Extraction materializes
|
||||
the logical paths through the shared path-containment and collision rules and
|
||||
never overwrites existing files.
|
||||
|
||||
The fuse scan independently records `set`, `unset`, `absent`, or `conflicting`.
|
||||
An unset fuse with a present blob is reported as a limitation. These are static
|
||||
sentinel observations, not proof of runtime activation: sentinel-like text in
|
||||
script or asset bytes also participates in the scan.
|
||||
|
||||
## Supported layout and limits
|
||||
|
||||
The decoder follows the 64-bit little-endian layout in Node
|
||||
[v24.10.0 node_sea.cc](https://github.com/nodejs/node/blob/v24.10.0/src/node_sea.cc)
|
||||
and [node_sea.h](https://github.com/nodejs/node/blob/v24.10.0/src/node_sea.h),
|
||||
including the exec-argument extension byte. Older layouts without that byte,
|
||||
32-bit length fields, big-endian blobs and future flags are not supported.
|
||||
Carrier byte order is independent of blob byte order.
|
||||
|
||||
Malformed magic, truncation, unknown flags/extensions, invalid UTF-8, duplicate
|
||||
raw asset keys and conflicting blob declarations fail closed with named reasons.
|
||||
Zero padding after a complete blob is allowed. The blob read ceiling is 256 MiB;
|
||||
PE carriers also use the shared 512 MiB input, 65,536 directory-entry and 8 MiB
|
||||
resource-metadata ceilings. The decoder admits at most 100,000 assets whose
|
||||
names total at most 8 MiB, and 4,096 exec arguments totaling at most 1 MiB of
|
||||
text. These are fixed resource bounds, not Node format limits, checked before
|
||||
decoding names or creating records; a hit fails as a limit with no runtime
|
||||
override. Asset and argument decoding, padding scans, and inventory construction
|
||||
yield in bounded batches and honor caller cancellation. Asset count and name
|
||||
budgets bound retained metadata independently of stored member body sizes. The PE
|
||||
name probe reads headers from the first 64 KiB of the carrier; a PE whose
|
||||
headers extend beyond that is left to native classification. Snapshot and
|
||||
code-cache bytes remain opaque.
|
||||
|
||||
## Verification
|
||||
|
||||
Synthetic fixtures cover Mach-O, ELF and PE inventory/extraction, malformed
|
||||
blobs, collisions and fuse contradictions. CLI and MCP tests exercise the same
|
||||
artifact provider and advertised schemas. A CLI regression also generates a blob
|
||||
with the pinned local Node version, an absolute main path and an empty asset
|
||||
key, then inventories it inside a synthetic ELF carrier. This verifies the real
|
||||
blob producer, not a real injected executable.
|
||||
|
||||
The optional real ELF lane uses Docker's official Node v24.10.0 image and pinned
|
||||
postject to build a fixture, then verifies inventory and extracted script/asset
|
||||
bytes without running the injected application:
|
||||
|
||||
```sh
|
||||
npm run verify:node-sea
|
||||
```
|
||||
|
||||
This requires Docker and network access to fetch the producer image and
|
||||
postject. It creates and removes its own temporary fixture directory. A real
|
||||
macOS Mach-O or Windows PE run is separate coverage; synthetic carriers do not
|
||||
establish real-platform verification. No performance improvement is claimed;
|
||||
whole-task tokens, CPU, memory, and cold/warm timings have not been measured.
|
||||
@@ -35,6 +35,13 @@ present with no consumed `locations`, and coverage is partial. Descriptors,
|
||||
thunks and NUL-terminated names stay within PE's 32-bit RVA space, including
|
||||
PE32+ images; earlier valid rows survive an overflowing descriptor walk.
|
||||
|
||||
`machine` retains the original unsigned COFF value. `architecture` decodes
|
||||
known machines, including ReadyToRun OS overrides when a CLI directory is
|
||||
declared; that declaration does not establish valid CLR metadata or runtime
|
||||
compatibility. Unrecognized machines retain `pe-machine-<decimal>` while their
|
||||
import tables remain inspectable. A recognized machine whose width contradicts
|
||||
the optional header is malformed.
|
||||
|
||||
Each `imports[]` item reports the DLL name, descriptor RVAs, and named or
|
||||
ordinal functions with ILT/IAT RVAs. `delay_imports[]` reports RVA-based
|
||||
delay-load descriptors separately. `imphash` is pefile's `get_imphash()` over
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
# PE TLS callbacks and load configuration
|
||||
|
||||
Use `inspect_pe_load_config` to locate declared TLS callbacks and inspect the load
|
||||
configuration of an explicit local PE32 or PE32+ image. No disassembler, Windows
|
||||
host, or target execution is required.
|
||||
|
||||
```sh
|
||||
rea inspect-pe-load-config /absolute/path/to/application.exe --json
|
||||
rea inspect-pe-load-config /absolute/path/to/application.exe --max-callbacks 256 --json
|
||||
```
|
||||
|
||||
MCP accepts `{ "path": "/absolute/path/to/application.exe" }`. CLI paths may be
|
||||
relative to the current directory; MCP paths must be absolute.
|
||||
|
||||
The complete Evidence includes the artifact path, SHA-256, directory file ranges,
|
||||
and callback-array file ranges. `tls` reports the raw data range, index address,
|
||||
zero-fill size, characteristics and null-terminated callback array. Callback VAs
|
||||
are hexadecimal strings to preserve 64-bit precision. RVA, mapped file offset,
|
||||
and section are derived locations; unknown mappings are `null`.
|
||||
|
||||
`load_config` reports fields only when its declared `Size` covers the entire
|
||||
field. MSVC x86 images often declare a 64-byte load-config data directory while
|
||||
the structure's own `Size` is larger; like the Windows loader, REA reads `Size`
|
||||
bytes when they are file-backed in one run, and reports both
|
||||
`directory.size` and `size`. `structure_location` is the file range of the
|
||||
`Size` bytes REA checked; Evidence locations include it beside the declared
|
||||
directory range when the two differ. Unavailable fields are `null`; a covered zero pointer remains `"0x0"`.
|
||||
The report includes the security cookie, PE32 SafeSEH table/count, CFG pointers
|
||||
and table/count, address-taken IAT and long-jump tables/counts, EH continuation
|
||||
table/count, and XFG check pointer. CHPE and dynamic relocation pointers are raw
|
||||
values. The dynamic relocation table offset (DWORD) and section (WORD) are
|
||||
reported separately when `Size` covers them, including zero values; REA does
|
||||
not infer a VA from that pair or decode the target and mitigation-table entries.
|
||||
|
||||
Guard flags retain the raw DWORD, recognized names, unknown bits, and the CFG
|
||||
entry stride. Mitigation claims derived from those flags carry
|
||||
`evidence_kind: "inferred"`; they do not prove runtime enforcement. The image is
|
||||
never executed. Missing directories are observed absence of those declarations,
|
||||
not proof that no callback or mitigation exists by another mechanism.
|
||||
|
||||
The default read budget is 64 MiB (`max_file_bytes`, ceiling 512 MiB). The default
|
||||
callback budget is 64 (`max_callbacks`, ceiling 4096). An exact-budget array is
|
||||
accepted if its next slot is null. Truncated, ambiguous or unmapped directory and
|
||||
callback-array storage fails closed, as does budget exhaustion; no partial
|
||||
success is returned. An unmapped callback **target** retains its VA/RVA with an
|
||||
unknown file offset. Load-config versions beyond the supported fields remain
|
||||
undecoded.
|
||||
|
||||
Layout references: [Microsoft PE format](https://learn.microsoft.com/en-us/windows/win32/debug/pe-format),
|
||||
[IMAGE_LOAD_CONFIG_DIRECTORY32](https://learn.microsoft.com/en-us/windows/win32/api/winnt/ns-winnt-image_load_config_directory32),
|
||||
and [IMAGE_LOAD_CONFIG_DIRECTORY64](https://learn.microsoft.com/en-us/windows/win32/api/winnt/ns-winnt-image_load_config_directory64).
|
||||
|
||||
For a real cross-compiled fixture, run `npm run verify:pe:load-config` with Zig
|
||||
on PATH (or `REA_ZIG` set to its path). The script builds PE32 and PE32+ samples
|
||||
and inspects them through the public CLI without running them.
|
||||
@@ -25,8 +25,12 @@ metadata retains the original name, table index, type, compression flag,
|
||||
relative offset and known directory record extent. Logical paths follow the
|
||||
carrier's path dialect: backslashes separate components for PE carriers, while
|
||||
they remain literal filename characters for POSIX carriers. The source name
|
||||
always retains its stored spelling. If the carrier dialect is unconfirmed, REA
|
||||
preserves backslashes verbatim instead of inferring POSIX semantics.
|
||||
always retains its stored spelling in occurrence `source_path` and
|
||||
`format_metadata.source_name`. For PYZ rows, that source is the exact module or
|
||||
data key in the PYZ table, not a reconstructed filesystem name;
|
||||
`format_metadata.container_name` identifies the containing PYZ image. If the
|
||||
carrier dialect is unconfirmed, REA preserves backslashes verbatim instead of
|
||||
inferring POSIX semantics.
|
||||
`relative_offset` is relative to the CArchive start for CArchive rows, or to
|
||||
the decoded PYZ image for PYZ rows. A CArchive directory record starts at
|
||||
`archive_start + toc_offset + directory_record_offset`; its size is
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
# Headerless raw-binary analysis with Ghidra
|
||||
|
||||
Headerless images are covered here. GameCube/Wii DOL images have a header and
|
||||
use their own format selection; see [GameCube DOL analysis](ghidra-dol.md).
|
||||
|
||||
REA admits a headerless executable when the caller supplies the CPU family and
|
||||
the address where file offset 0 should be mapped. That interpretation is not
|
||||
inferred from a `.bin` suffix or from unrecognized bytes.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · **العربية** · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: هندسة عكسية لأي شيء
|
||||
|
||||
@@ -158,7 +158,9 @@ npx rea-agents@latest setup
|
||||
| شيفرة EVM البايتية | محددات التوجيه، وإزاحات البايتات، والمعاملات المستنتجة، وقابلية تغيير الحالة | مدخل محلي يحمل بايتات خامًا أو تمثيلًا سداسيًا عشريًا على Linux x64؛ [دليل EVM دون تشغيل](../evm-bytecode.md) |
|
||||
| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| أعطال Linux المسجّلة | سجلات note الخام، ومسجّلات المعالج/الإشارات لكل خيط مسجّل، وترشيحات اختيارية لخرائط الذاكرة | pwntools يوفّره المستدعي على Linux x64؛ GDB/pwndbg اختياريان؛ [الأعطال المسجّلة](../recorded-crashes.md) |
|
||||
| تثبيتات سطح المكتب | عائلات وقت التشغيل، والملفات الداعمة، وعلامات المكونات، والخطوات التالية | فحص محدود للملفات والترويسات；[تطبيقات سطح المكتب](../desktop-applications.md) |
|
||||
| JavaScript / Electron | الوحدات، وعمليات الاستيراد، وخرائط المصدر، والمسارات، وIPC، وعلاقات إضافات الشيفرة الأصلية | Node.js وnpm؛ [تحليل التطبيقات](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · **Deutsch** · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: Alles reverse-engineeren
|
||||
|
||||
@@ -158,7 +158,9 @@ REA benötigt Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) oder 26+ (>=26.12.1) so
|
||||
| EVM-Bytecode | Dispatch-Selektoren, Byte-Offsets, abgeleitete Argumente und Veränderbarkeit des Zustands | Lokale Eingabe mit Rohbytes oder Hexdarstellung unter Linux x64; [Offline-EVM-Leitfaden](../evm-bytecode.md) |
|
||||
| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Aufgezeichnete Linux-Abstürze | Unverarbeitete Note-Einträge, Register/Signale aller aufgezeichneten Threads und optionale Zuordnungskandidaten | Vom Aufrufer bereitgestelltes pwntools unter Linux x64; optional GDB/pwndbg; [aufgezeichnete Abstürze](../recorded-crashes.md) |
|
||||
| Desktop-Installationen | Laufzeitkandidaten, Quelldateien, Komponenten und nächste Schritte | Begrenzte Verzeichnis- und Headerprüfung；[Desktop-Anwendungen](../desktop-applications.md) |
|
||||
| JavaScript / Electron | Module, Imports, Source Maps, Routen, IPC und Beziehungen zu nativen Add-ons | Node.js und npm; [Anwendungsanalyse](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md) · **Ελληνικά** · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md) · **Ελληνικά** · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: Reverse Engineer Anything
|
||||
|
||||
@@ -158,6 +158,8 @@ npx rea-agents@latest setup
|
||||
| PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) |
|
||||
| PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Αρχείο WASM | Έλεγχο εγκυρότητας, ενότητες, ακριβείς μορφές εισαγωγών/εξαγωγών σε WAT και αποκωδικοποιημένο WAT | WABT 1.0.42 που παρέχει ο χρήστης· `inspect_wasm_artifact` |
|
||||
| Bytecode EVM | Selectors επιλογής συνάρτησης, μετατοπίσεις σε bytes, εκτιμώμενα ορίσματα και δυνατότητα μεταβολής της κατάστασης | Τοπική είσοδος σε ακατέργαστα bytes ή δεκαεξαδική μορφή σε Linux x64· [οδηγός EVM χωρίς εκτέλεση](../evm-bytecode.md) |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · **Español** · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: Ingeniería inversa de cualquier cosa
|
||||
|
||||
@@ -158,7 +158,9 @@ REA requiere Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) o 26+ (>=26.12.1), adem
|
||||
| Bytecode EVM | Selectores de despacho, desplazamientos en bytes, argumentos inferidos y mutabilidad | Entrada local con bytes sin procesar o representación hexadecimal, en Linux x64; [guía de EVM sin ejecutar](../evm-bytecode.md) |
|
||||
| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.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, en Linux x64; GDB/pwndbg opcionales; [fallos registrados](../recorded-crashes.md) |
|
||||
| Instalaciones de escritorio | Posibles entornos de ejecución, archivos de evidencia, componentes y siguientes pasos | Inspección acotada de directorios y cabeceras；[Aplicaciones de escritorio](../desktop-applications.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](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center" dir="rtl">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · **فارسی** · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: مهندسی معکوس هر چیزی
|
||||
|
||||
@@ -150,6 +150,8 @@ REA به Node.js 22.x (>=22.23.4)، 24.x (>=24.22.1) یا 26+ (>=26.12.1)، به
|
||||
| بایتکد EVM | selectorهای dispatch، offsetهای بایتی، آرگومانهای استنباطشده و قابلیت تغییر وضعیت | دادهٔ خام/hex محلی روی Linux x64؛ [راهنمای EVM آفلاین](../evm-bytecode.md) |
|
||||
| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| کرشهای ثبتشدهٔ لینوکس | یادداشتهای خام، رجیسترها/سیگنالهای تمام threadهای ثبتشده و گزینههای احتمالی نگاشت | pwntools تأمینشده توسط فراخواننده روی Linux x64؛ GDB/pwndbg اختیاری؛ [کرشهای ثبتشده](../recorded-crashes.md) |
|
||||
| نصبهای دسکتاپ | نامزدهای زمان اجرا، فایلهای شاهد، نشانههای مؤلفهها و مراحل بعدی | بررسی محدود پوشهها و سرآیندها；[برنامههای دسکتاپ](../desktop-applications.md) |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · **Français** · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA : rétro-ingénierie de tout
|
||||
|
||||
@@ -158,7 +158,9 @@ REA nécessite Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) ou 26+ (>=26.12.1), ai
|
||||
| Bytecode EVM | Sélecteurs de dispatch, offsets en octets, arguments inférés et mutabilité | Fichier local brut ou hexadécimal sous Linux x64 ; [guide EVM hors ligne](../evm-bytecode.md) |
|
||||
| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Crashs Linux enregistrés | Notes brutes, registres et signaux de chaque thread enregistré, et correspondances de mappings facultatives | pwntools fourni par l'utilisateur sous Linux x64 ; GDB/pwndbg en option ; [crashs enregistrés](../recorded-crashes.md) |
|
||||
| Installations de bureau | Environnements candidats, fichiers justificatifs, composants et étapes suivantes | Inspection bornée des répertoires et en-têtes；[Applications de bureau](../desktop-applications.md) |
|
||||
| JavaScript / Electron | Modules, imports, source maps, routes, IPC et relations avec les modules natifs | Node.js et npm ; [analyse d'applications](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · **Bahasa Indonesia** · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: Rekayasa Balik Apa Pun
|
||||
|
||||
@@ -161,6 +161,8 @@ Alat tambahan dan dukungan sistem host bergantung pada target yang dianalisis:
|
||||
| Bytecode EVM | Selector dispatch, offset byte, argumen yang disimpulkan, dan sifat mutabilitas | Pembawa data raw/hex lokal; [panduan EVM offline](../evm-bytecode.md) |
|
||||
| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Crash Linux yang direkam | Catatan mentah, register/sinyal setiap thread yang direkam, dan kandidat pemetaan opsional | pwntools yang disediakan pemanggil; GDB/pwndbg opsional; [crash yang direkam](../recorded-crashes.md) |
|
||||
| Instalasi desktop | Kandidat runtime, berkas pendukung, penanda komponen, dan langkah berikutnya | Pemeriksaan direktori dan header terbatas；[Aplikasi desktop](../desktop-applications.md) |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · **Italiano**
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: Reverse Engineer Anything
|
||||
|
||||
@@ -158,7 +158,9 @@ REA richiede Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) o 26+ (>=26.12.1), oltre
|
||||
| Bytecode EVM | Selettori di dispatch, offset dei byte, argomenti inferiti e mutabilità | Carrier raw/hex locale; [guida EVM offline](../evm-bytecode.md) |
|
||||
| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Crash Linux registrati | Note grezze, registri/segnai di ogni thread registrato e candidati mapping opzionali | pwntools fornito dal chiamante; GDB/pwndbg opzionale; [crash registrati](../recorded-crashes.md) |
|
||||
| Installazioni desktop | Runtime candidati, file di supporto, componenti e passi successivi | Ispezione limitata di directory e intestazioni；[Applicazioni desktop](../desktop-applications.md) |
|
||||
| JavaScript / Electron | Moduli, import, source map, route, IPC e relazioni con add-on nativi | Node.js e npm; [analisi delle applicazioni](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · **日本語** · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA：あらゆるものをリバースエンジニアリング
|
||||
|
||||
@@ -158,6 +158,8 @@ REA には Node.js 22.x（>=22.23.4）、24.x（>=24.22.1）、または 26+ (>=
|
||||
| EVM バイトコード | ディスパッチセレクター、バイトオフセット、推定された引数と状態変更の可否 | Linux x64 上のローカルの生バイト／16 進数の入力ファイル；[オフライン EVM ガイド](../evm-bytecode.md) |
|
||||
| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| 記録済みの Linux クラッシュ | 生の note レコード、記録された全スレッドのレジスター／シグナル、任意のマッピング候補 | Linux x64 で利用者が用意する pwntools；GDB/pwndbg は任意；[記録済みクラッシュ](../recorded-crashes.md) |
|
||||
| デスクトップのインストール先 | ランタイム候補、根拠ファイル、コンポーネントの目印、次の調査手順 | 上限付きのディレクトリ・ヘッダー検査；[デスクトップアプリ](../desktop-applications.md) |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · **한국어** · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: 무엇이든 리버스 엔지니어링
|
||||
|
||||
@@ -158,6 +158,8 @@ REA에는 Node.js 22.x(>=22.23.4), 24.x(>=24.22.1) 또는 26+ (>=26.12.1)와 npm
|
||||
| PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) |
|
||||
| PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| WASM 아티팩트 | 유효성 검사, 섹션, import/export의 정확한 WAT 형식, 디코딩된 WAT | 호출자 제공 WABT 1.0.42; `inspect_wasm_artifact` |
|
||||
| EVM 바이트코드 | 디스패치 선택자, 바이트 오프셋, 추론한 인자와 상태 변경 가능 여부 | Linux x64의 로컬 원시 바이트/16진수 입력 파일; [오프라인 EVM 가이드](../evm-bytecode.md) |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · **മലയാളം** · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · **മലയാളം** · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: എന്തും Reverse Engineer ചെയ്യുക
|
||||
|
||||
@@ -158,10 +158,12 @@ REA-യ്ക്ക് Node.js 22.x (>=22.23.4), 24.x (>=24.22.1), അല്ല
|
||||
| PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) |
|
||||
| PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| WASM artifact | Validation, sections, കൃത്യമായ import/export WAT രൂപങ്ങൾ, decoded WAT | Caller നൽകുന്ന WABT 1.0.42; `inspect_wasm_artifact` |
|
||||
| EVM bytecode | Dispatch selectors, byte offsets, അനുമാനിച്ച arguments, mutability | Linux x64-ൽ local raw/hex carrier; [offline EVM guide](../evm-bytecode.md) |
|
||||
| SQLite databases | Tables, columns, indexes, views, triggers, തിരഞ്ഞെടുത്ത സാധാരണ table rows | Local database/WAL snapshot; native SQLite പരിമിതികളോടെ Node.js 24.x >=24.15 അല്ലെങ്കിൽ 26+ |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Recorded Linux crashes | Raw notes, രേഖപ്പെടുത്തിയ ഓരോ thread-ന്റെയും registers/signals, ഐച്ഛിക mapping candidates | Linux x64-ൽ caller നൽകുന്ന pwntools; ഐച്ഛിക GDB/pwndbg; [recorded crashes](../recorded-crashes.md) |
|
||||
| ഡെസ്ക്ടോപ്പ് ഇൻസ്റ്റലേഷനുകൾ | റൺടൈം സാധ്യതകൾ, തെളിവ് ഫയലുകൾ, ഘടക സൂചനകൾ, തുടർ നടപടികൾ | പരിധിയുള്ള ഡയറക്ടറി, ഹെഡർ പരിശോധന；[ഡെസ്ക്ടോപ്പ് ആപ്ലിക്കേഷനുകൾ](../desktop-applications.md) |
|
||||
| JavaScript / Electron | Modules, imports, source maps, routes, IPC, native add-on ബന്ധങ്ങൾ | Node.js, npm; Linux: procps-compatible `ps`; [application analysis](../javascript-application-workflows.md) |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · **Polski** · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: Reverse Engineer Anything
|
||||
|
||||
@@ -158,7 +158,9 @@ REA wymaga Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) lub 26+ (>=26.12.1) oraz n
|
||||
| Kod bajtowy EVM | Selektory wywołań, przesunięcia bajtowe, wywnioskowane argumenty i mutowalność | Lokalny plik z surowymi bajtami lub zapisem szesnastkowym w systemie Linux x64; [przewodnik EVM offline](../evm-bytecode.md) |
|
||||
| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.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 w systemie Linux x64; opcjonalnie GDB/pwndbg; [zarejestrowane awarie](../recorded-crashes.md) |
|
||||
| Instalacje desktopowe | Kandydaci środowisk uruchomieniowych, pliki źródłowe dowodów, komponenty i dalsze kroki | Ograniczona inspekcja katalogów i nagłówków；[Aplikacje desktopowe](../desktop-applications.md) |
|
||||
| JavaScript / Electron | Moduły, importy, mapy źródeł, trasy, IPC i powiązania z natywnymi dodatkami | Node.js i npm; [analiza aplikacji](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · **Português (Brasil)** · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: Faça engenharia reversa de qualquer coisa
|
||||
|
||||
@@ -158,7 +158,9 @@ O REA requer Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) ou 26+ (>=26.12.1), alé
|
||||
| Bytecode EVM | Seletores de despacho, offsets de bytes, argumentos inferidos e mutabilidade | Entrada local com bytes brutos ou representação hexadecimal no Linux x64; [guia de EVM sem execução](../evm-bytecode.md) |
|
||||
| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Falhas do Linux registradas | Registros note brutos, registradores/sinais de cada thread registrada e candidatos opcionais a mapeamentos | pwntools fornecido pelo chamador no Linux x64; GDB/pwndbg opcionais; [falhas registradas](../recorded-crashes.md) |
|
||||
| Instalações desktop | Ambientes candidatos, arquivos de evidência, componentes e próximos passos | Inspeção limitada de diretórios e cabeçalhos；[Aplicações desktop](../desktop-applications.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](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -0,0 +1,442 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · **Română**
|
||||
|
||||
# REA: Reverse Engineer Anything
|
||||
|
||||
### Un singur server MCP pentru inginerie inversă: fișiere binare, aplicații și comportament în timpul execuției.
|
||||
|
||||
**Ai găsit o funcționalitate care îți place? Înțelege cum funcționează, până la nivel de cod binar.**
|
||||
|
||||
[](https://www.npmjs.com/package/rea-agents)
|
||||
[](../mcp-contracts.md#generated-catalog)
|
||||
[](#ce-poți-analiza)
|
||||
[](https://skills.sh/morluto/rea/reverse-engineer-anything)
|
||||
[](../../LICENSE)
|
||||
[](https://discord.gg/GkcryMnJDM)
|
||||
|
||||
<a href="https://trendshift.io/repositories/82054?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-82054" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/82054" alt="morluto%2Frea | Trendshift" width="250" height="55"/></a>
|
||||
|
||||
**[Site web](https://rea.tools/) · [Ghiduri](https://rea.tools/guides/) · [Studii de caz](https://rea.tools/showcase/)**
|
||||
|
||||
[Pornire rapidă](#pornire-rapidă) · [Cum funcționează REA](#cum-funcționează-rea) · [Ce poți analiza](#ce-poți-analiza) · [Studii de caz](#studii-de-caz) · [Întrebări frecvente](#întrebări-frecvente) · [Documentație](#documentație)
|
||||
|
||||
<code>npx rea-agents setup</code>
|
||||
|
||||
</div>
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Descarcă REA din [morluto/rea](https://github.com/morluto/rea),
|
||||
> de pe [rea.tools](https://rea.tools/) sau prin [pachetul npm rea-agents](https://www.npmjs.com/package/rea-agents).
|
||||
> Urmează linkurile de instalare și către versiunile publicate oferite de aceste surse oficiale.
|
||||
> Un nume de repository asemănător sau un README copiat nu dovedește că descărcarea provine dintr-o sursă oficială.
|
||||
|
||||
<div align="center">
|
||||
|
||||
<br />
|
||||
|
||||
<img src="../assets/rea-hopper-analysis.png" alt="REA pornește componenta de legătură pentru analiză în Hopper în timp ce inspectează un fișier binar nativ" width="1200" />
|
||||
|
||||
<br /><br />
|
||||
|
||||
<table aria-label="Comunitatea REA">
|
||||
<tr>
|
||||
<td align="center" width="360">
|
||||
<a href="https://discord.gg/GkcryMnJDM">
|
||||
<img src="../assets/discord.svg" height="42" alt="Discord" /><br />
|
||||
<strong>Alătură-te comunității de inginerie inversă</strong>
|
||||
</a><br />
|
||||
<sub>Discord · Întrebări și răspunsuri · Prezentări și demonstrații</sub>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<br />
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
Ai văzut într-o aplicație o funcționalitate pe care ai vrea să o incluzi în propriul produs? Cere-i agentului tău să o investigheze cu REA. Poate inspecta aplicația fără codul ei sursă, poate explica modul în care funcționează acea funcționalitate, poate prezenta dovezile și poate construi o variantă pentru proiectul tău.
|
||||
|
||||
REA conectează agentul tău la unelte pentru inspectarea fișierelor binare native, a aplicațiilor JavaScript și Electron, a ansamblurilor .NET și a site-urilor web. Poți folosi aceleași unelte și din terminal. Analiza rulează local, iar rezultatele includ dovezile și limitările care stau la baza fiecărei concluzii.
|
||||
|
||||
Programul de configurare înregistrează REA în agentul tău și instalează instrucțiunile corespunzătoare pentru fluxul de lucru. Analiza nativă poate folosi o instalare existentă de Hopper, Ghidra sau IDA; programul de configurare poate instala opțional Hopper, cu aprobarea ta. Analiza statică JavaScript nu necesită un motor de analiză nativă.
|
||||
|
||||
> **[Vizitează site-ul REA](https://rea.tools/)** pentru instrucțiuni de configurare, ghiduri ilustrate și studii de caz reale.
|
||||
|
||||
## Pornire rapidă
|
||||
|
||||
Pe Linux, pornirea Ghidra, JADX și a uneltelor pentru firmware, precum și analiza
|
||||
statică JavaScript/Electron necesită un `ps` compatibil cu procps în `PATH`-ul REA,
|
||||
pentru a verifica dacă procesele îi aparțin. Pașii de remediere sunt în
|
||||
`docs/installation.md`, la secțiunea „Linux owned-process prerequisite”.
|
||||
|
||||
### Configurează agentul
|
||||
|
||||
Cu Node.js și npm instalate, rulează:
|
||||
|
||||
```bash
|
||||
npx rea-agents setup
|
||||
```
|
||||
|
||||
Alege agenții, verifică modificările propuse și aprobă-le. Configurarea adaugă
|
||||
serverul MCP REA și instrucțiunile corespunzătoare pentru fluxul de lucru,
|
||||
creând copii de siguranță ale configurației existente. Repornește apoi agentul.
|
||||
|
||||
Programul de configurare acceptă Claude Code, Codex, Cursor, Gemini CLI, Grok Build și
|
||||
[alți agenți](../installation.md#supported-agents). Consultă
|
||||
[instalarea și configurarea](../installation.md) pentru configurarea motoarelor
|
||||
de analiză și înregistrarea manuală a serverului MCP.
|
||||
|
||||
MCP folosește implicit scheme de intrare compacte, pentru a reduce spațiul ocupat
|
||||
în context. Setează `REA_MCP_INPUT_SCHEMA_PROFILE=full` în înregistrarea MCP când
|
||||
ai nevoie de îndrumările complete pentru câmpurile expuse și de detaliile
|
||||
validării structurilor imbricate. Ambele profiluri păstrează toate uneltele și
|
||||
validarea canonică a serverului. Consultă secțiunea „Compact input schema profile”
|
||||
din ghidul contractelor MCP.
|
||||
|
||||
### Cere-i agentului
|
||||
|
||||
```text
|
||||
Înțelege cum funcționează căutarea în aplicația Notes, arată-mi dovezile și
|
||||
construiește o funcționalitate similară pentru proiectul meu.
|
||||
```
|
||||
|
||||
Înlocuiește Notes cu aplicația vizată și precizează funcționalitatea pe care vrei să o înțelegi.
|
||||
|
||||
### Folosește terminalul
|
||||
|
||||
Inspectează directorul extras al unei aplicații JavaScript/Electron sau o arhivă ASAR:
|
||||
|
||||
```bash
|
||||
npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
|
||||
```
|
||||
|
||||
Rezultatul include modulele, importurile, delimitările dintre componentele Electron
|
||||
și dovezile aferente. Înlocuiește calea cu cea a aplicației vizate, de exemplu
|
||||
`"D:/apps/example"` pe Windows.
|
||||
|
||||
Pentru a instala comanda `rea` și a o folosi în mod curent:
|
||||
|
||||
```bash
|
||||
npm install --global rea-agents
|
||||
rea --help
|
||||
```
|
||||
|
||||
Pentru analiza nativă, configurează mai întâi un motor de analiză. Consultă
|
||||
[ghidul CLI și Evidence](../cli.md) pentru comenzile de analiză nativă,
|
||||
selectarea motorului, instantanee și utilizarea în scripturi.
|
||||
|
||||
### Actualizează REA
|
||||
|
||||
REA evoluează rapid, iar versiunile noi includ frecvent corecții de erori.
|
||||
Menține instalarea la zi.
|
||||
|
||||
Pentru o interfață CLI instalată cu `npm install --global` sau `bun add --global`:
|
||||
|
||||
```bash
|
||||
rea update
|
||||
```
|
||||
|
||||
`rea --update` este un alias pentru acest flux de actualizare verificat și acceptă
|
||||
aceleași opțiuni globale de ieșire. Folosește `rea update` când îl combini cu alte
|
||||
opțiuni de control al comenzii.
|
||||
|
||||
Comenzile de actualizare păstrează cel mult 4 MiB în total din stdout și stderr.
|
||||
Răspunsurile cu metadate prea mari sunt respinse după încheierea comenzii;
|
||||
instalările cu ieșire detaliată continuă cu un volum limitat de date de diagnostic.
|
||||
Afișarea progresului în terminal ține cont de ritmul în care acesta poate primi
|
||||
date și așteaptă finalizarea operațiilor de scriere deja trimise.
|
||||
|
||||
Actualizările instalărilor globale cu Bun necesită Bun 1.2.17 sau o versiune mai nouă.
|
||||
Dacă ai o versiune mai veche, actualizează Bun manual înainte de a rula `rea update`.
|
||||
|
||||
Pentru a actualiza înregistrările agenților și skill-ul, rulează comanda de
|
||||
configurare afișată de programul de actualizare.
|
||||
|
||||
Dacă folosești `npx`, actualizează configurarea agentului cu:
|
||||
|
||||
```bash
|
||||
npx rea-agents@latest setup
|
||||
```
|
||||
|
||||
Verifică modificările de configurare și repornește agentul. Pentru comenzi CLI
|
||||
ocazionale, folosește `npx rea-agents@latest` urmat de comandă. Cu Bun, folosește
|
||||
`bunx rea-agents@latest` în loc de `npx rea-agents@latest`.
|
||||
|
||||
## Cum funcționează REA
|
||||
|
||||
Agentul tău apelează REA prin MCP pentru a inspecta ținta și a urmări codul relevant.
|
||||
REA returnează constatările împreună cu dovezile aferente. Agentul le folosește
|
||||
pentru a pune întrebări suplimentare, a explica comportamentul sau a scrie și
|
||||
testa o implementare. Comenzile CLI folosesc aceleași fluxuri de lucru.
|
||||
|
||||
|
||||
|
||||
[Deschide figura la dimensiunea originală](../../website/public/assets/figures/rea-investigation-flow.svg).
|
||||
|
||||
<a id="current-status"></a>
|
||||
|
||||
## Ce poți analiza
|
||||
|
||||
REA necesită Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) sau 26.12.1+, plus npm.
|
||||
Uneltele suplimentare și platformele acceptate depind de ținta analizată:
|
||||
|
||||
| Țintă | Ce returnează REA | Cerințe și ghid |
|
||||
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Aplicații desktop instalate | Componente de execuție candidate, fișiere auxiliare, indicii despre componente și următoarele verificări | Inspectare integrată a directoarelor și antetelor, cu limite de resurse; [aplicații desktop](../desktop-applications.md) |
|
||||
| Fișiere binare native | Pseudocod, cod de asamblare, șiruri de caractere, simboluri, apeluri și referințe | Hopper, Ghidra sau IDA; [analiză nativă](../native-investigation.md) |
|
||||
| Structura ELF, offline | Secțiuni, segmente, simboluri și relocări originale, precum și indicii statice despre mecanismele de protecție | pwntools furnizat de utilizator, pe Linux x64; [diagnosticarea binarelor](../binary-diagnostics.md) |
|
||||
| Fișiere binare Go | Versiunea compilatorului încorporată în fișier, modulele, înlocuirile și setările de compilare | Inspectare statică integrată a fișierelor ELF/PE/Mach-O cu o singură arhitectură; nu necesită instalarea Go |
|
||||
| Obiecte de cod GPU | Ținte CUDA/HIP, parametri și resurse selectate ale kernelurilor GPU, textul PTX păstrat | Inspectare statică integrată a fișierelor ELF/PE/fatbin/CUBIN/PTX; [obiecte de cod GPU](../gpu-code-objects.md) |
|
||||
| Fișiere de model | Metadate GGUF / safetensors, declarații de tensori și totaluri calculate din acestea | Inspectare integrată a antetelor; opțional, hash al întregului fișier; [fișiere de model](../model-artifacts.md) |
|
||||
| Metadate IL2CPP | Imagini de ansambluri din global-metadata.dat al Unity, nume de tipuri și metode și intervale de indici | Decodare statică integrată a versiunilor 24, 27, 29, 31 și 39; nu necesită Unity |
|
||||
| Godot PCK | Inventarul și extragerea arhivei, informații originale din antet și director și identificatori ai conținutului selectat | Suport static integrat pentru formatele 2, 3 și 4; nu necesită Godot |
|
||||
| Fișiere binare Rust | Nume, versiuni, surse și relații de dependență ale pachetelor crate încorporate prin cargo-auditable | Inspectare statică integrată a fișierelor ELF/PE/Mach-O cu o singură arhitectură; [binare Rust](../rust-binaries.md) |
|
||||
| Certificate PE | Intrări Authenticode WIN_CERTIFICATE și câmpuri de identitate ale semnatarilor PKCS#7 și certificatelor X.509 | Inspectare statică integrată a fișierelor PE; [certificate PE](../pe-certificates.md) |
|
||||
| Importuri PE | Numele DLL-urilor importate și încărcate întârziat, ordinale, RVA-uri ale IAT și hash-ul importurilor calculat de pefile | Inspectare statică integrată a fișierelor PE; [importuri PE](../pe-imports.md) |
|
||||
| Note ELF | Proprietari și tipuri PT_NOTE/SHT_NOTE, câmpuri GNU build-id și ABI-tag | Inspectare statică integrată a fișierelor ELF; [note ELF](../elf-notes.md) |
|
||||
| Rapoarte Apple IPS de eroare fatală | Metadate .ips, fire de execuție, imagini binare, registre și clase documentate de erori fatale | Inspectare statică integrată a datelor JSON; [Apple IPS](../apple-ips.md) |
|
||||
| Module de kernel Linux | Chei .modinfo, CRC-uri din __versions, prezența this_module și structura semnăturii de la sfârșitul fișierului | Inspectare statică integrată a fișierelor ELF; [module de kernel](../kernel-modules.md) |
|
||||
| Erlang BEAM | Blocuri IFF, atomi, exporturi, importuri, funcții lambda și antetul Code | Inspectare statică integrată a fișierelor BEAM; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Fișiere WASM | Validare, secțiuni, forme WAT exacte ale importurilor și exporturilor și cod WAT decodat | WABT 1.0.42 furnizat de utilizator; `inspect_wasm_artifact` |
|
||||
| Bytecode EVM | Selectori de apel, poziții în octeți, argumente și mutabilitate deduse | Fișier local în format brut sau hexazecimal, pe Linux x64; [ghid EVM offline](../evm-bytecode.md) |
|
||||
| Baze de date SQLite | Tabele, coloane, indecși, vizualizări, declanșatoare și rânduri selectate din tabele obișnuite | Instantaneu local al bazei de date/WAL; Node.js 24.x >=24.15 sau 26+, cu limite SQLite native |
|
||||
| Erori fatale Linux înregistrate | Note brute, registrele și semnalele fiecărui fir înregistrat și, opțional, corespondențe candidate pentru mapările de memorie | pwntools furnizat de utilizator, pe Linux x64; opțional GDB/pwndbg; [erori fatale înregistrate](../recorded-crashes.md) |
|
||||
| JavaScript / Electron | Module, importuri, hărți de cod sursă, rute, IPC și relații cu extensiile native | Node.js și npm; pe Linux: `ps` compatibil cu procps; [analiza aplicațiilor](../javascript-application-workflows.md) |
|
||||
| Site-uri web | Structura paginilor, scripturi, observații de rețea și capturi de ecran solicitate | Un browser din familia Chrome; [analiză în browser](../browser-observation.md) |
|
||||
| Capturi de rețea salvate | Cereri, răspunsuri, conținuturi expuse ale mesajelor și pozițiile lor în sursă | HAR sau SAZ din Fiddler Everywhere; mitmdump pe Linux pentru formatul nativ mitmproxy; [ghidul capturilor](../web-network-captures.md) |
|
||||
| Ansambluri .NET | Metadate, instrucțiuni CIL, dependențe native declarate și comparații între compilări | Fără cerințe suplimentare (doar analiză statică); [ghidul codului gestionat](../managed-code-analysis.md) |
|
||||
| APK-uri Android | Declarații din manifest, clase, metode decompilate și referințe | JADX fără interfață grafică și un JDK complet, pe Linux/macOS/Windows x64; [ghidul Android](../android-analysis.md) |
|
||||
| Semnături APK | Semnatari v1/v2/v3/v3.1, amprente ale certificatelor, rotația cheilor și consistența internă a hash-urilor | Fără cerințe suplimentare (doar analiză statică); `inspect_apk_signature` |
|
||||
| Dispozitive Android | Dispozitive, pachete, procese, jurnale, dumpuri, capturi de ecran și transferuri de APK-uri și fișiere | adb furnizat de utilizator (emulator sau dispozitiv fizic); [ghidul ADB](../adb-device-analysis.md) |
|
||||
| Proiecte JEB | Unități de proiect analizate prin motor, hash-uri ale artefactelor și pseudocod pentru tipuri și metode | Un client JEB pornit de utilizator, care oferă un server MCP și este selectat prin REA_JEB_MCP_URL; [ghidul JEB](../jeb-analysis.md) |
|
||||
| Resurse Android | Manifest decodat, tabele de șiruri de caractere, localizări și informații despre versiune | Program de lansare Apktool furnizat de utilizator; [ghidul resurselor](../apktool-resource-analysis.md) |
|
||||
| Aplicații Flutter | Hash-ul instantaneului Dart, hash-uri ale bibliotecilor pentru fiecare ABI și proveniența compilării motorului | Fără cerințe suplimentare (parsare statică a APK-ului); [ghidul Flutter](../flutter-analysis.md) |
|
||||
| Firmware | Regiuni, rezultate ale extragerii și transferul către analiza nativă | Binwalk / Unblob pe Linux; [ghidul firmware](../firmware-analysis.md) |
|
||||
| Pachete de rețea înregistrate | Câmpuri selectate, valori repetate, filtre și reguli decode-as | Linux: TShark 4.x + prlimit; [ghidul capturilor](../packet-captures.md) |
|
||||
| Rezumate ale traficului de rețea | Puncte terminale, DNS, TLS SNI, distribuția protocoalelor și cereri HTTP | tshark și capinfos furnizate de utilizator (verificate pe Linux); [ghidul pcap](../pcap-analysis.md) |
|
||||
| Semnale logice înregistrate | Adnotări ale decodorului, intervale de eșantioane și date de diagnostic | Linux: sigrok-cli 0.7.2 + prlimit; [înregistrări de semnale](../signal-recordings.md) |
|
||||
| Pachete și resurse | Inventare de fișiere, hash-uri, fișiere plist, structura pachetelor de aplicație Apple și resurse extrase | [Ghidul artefactelor și JavaScript](../javascript-artifact-reconstruction.md), [aplicații Apple](../apple-application-analysis.md) |
|
||||
| Comportamentul proceselor | Ieșirea în terminal, interacțiuni, observații despre terminarea proceselor și sistemul de fișiere și comparații între rulări | Linux/macOS cu un PTY nativ; [capturarea proceselor](../process-capture.md) |
|
||||
| Executabile PyInstaller | Membri CArchive, versiunea Python, scripturi de intrare și bytecode extras | Fără cerințe suplimentare (doar analiză statică); [aplicații Python împachetate](../python-packaged-applications.md) |
|
||||
|
||||
Inspectarea statică JavaScript și .NET citește fișierele furnizate fără a rula
|
||||
aplicația. Capturarea în timpul execuției rulează ținta selectată sau interacționează
|
||||
cu aceasta folosind permisiunile contului tău; fiecare ghid de capturare descrie
|
||||
efectele acestor operații.
|
||||
|
||||
Pentru inspectarea offline a binarelor native, REA acceptă și GNU objdump și Rizin,
|
||||
furnizate de utilizator. Consultă [ghidul uneltelor de inginerie inversă](../reverse-engineering-tools.md)
|
||||
pentru configurare, comenzi CLI și limitările obiectelor Evidence. REA nu
|
||||
instalează și nu actualizează niciunul dintre aceste două instrumente.
|
||||
|
||||
<a id="choosing-a-deep-analysis-provider"></a>
|
||||
|
||||
Formatele native și platformele acceptate diferă în funcție de motorul de analiză.
|
||||
Consultă [configurarea Hopper și Ghidra](../installation.md#hopper),
|
||||
[ghidul IDA](../ida-provider.md) (inclusiv o componentă opțională de legătură MCP nativă),
|
||||
[ghidul decompilatorului Kuna](../kuna-provider.md) și
|
||||
[suportul experimental Ghidra pe Windows](../windows-ghidra-p0.md).
|
||||
Ghidra acceptă și [analiza DOS pe 16 biți](../ghidra-dos.md).
|
||||
Pentru binare mari, mărește timpul maxim de pornire al motorului cu
|
||||
`REA_GHIDRA_STARTUP_TIMEOUT_MS` sau `REA_HOPPER_STARTUP_TIMEOUT_MS`.
|
||||
Pentru selectarea motorului, consultă [ghidul CLI](../cli.md#choose-a-provider).
|
||||
Verifică [disponibilitatea în versiunile publicate](../installation.md#released-package-and-main)
|
||||
pentru funcționalitățile adăugate după cea mai recentă versiune npm.
|
||||
|
||||
## Studii de caz
|
||||
|
||||
<a href="https://rea.tools/showcase/">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="../assets/rea-showcases-dark.svg" />
|
||||
<img alt="Ilustrații pentru studiile de caz despre panoramarea sunetului în DX-Ball, legătura cu clipboardul în Notion și inelele de proiectile din TH04" src="../assets/rea-showcases.svg" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
### DX-Ball: reconstruiește calculul panoramării sunetului
|
||||
|
||||
Urmărește un apel audio până la funcția auxiliară care transformă poziția în
|
||||
panoramare stereo, inspectează instrucțiunile și transformă pseudocodul incomplet
|
||||
în C. Reconstrucția trece 3.205 cazuri de test comparate cu originalul x86 și
|
||||
reproduce toți cei 63 de octeți ai funcției compilate.
|
||||
|
||||
[Citește studiul de caz](https://rea.tools/showcase/dx-ball/) ·
|
||||
[Repository-ul reconstrucției](https://github.com/N0zoM1z0/dx-ball)
|
||||
|
||||
### Notion: urmărește legătura Electron cu clipboardul
|
||||
|
||||
Găsește API-ul pentru clipboard din procesul de randare, urmărește-l prin preload
|
||||
și IPC până în procesul principal și inspectează formatul datelor cu formatare din clipboard.
|
||||
|
||||
[Citește studiul de caz](https://rea.tools/showcase/notion/)
|
||||
|
||||
### TH04: recuperează calculul unui inel de proiectile DOS
|
||||
|
||||
Inspectează instrucțiunile pe 16 biți ale jocului original pentru PC-98,
|
||||
recuperează calculele unghiurilor fixe și ale celor orientate spre țintă și
|
||||
compară codul C++ reconstruit cu rezultatul compilatorului folosit la acea vreme.
|
||||
|
||||
[Citește studiul de caz](https://rea.tools/showcase/th04/) ·
|
||||
[Repository-ul reconstrucției](https://github.com/N0zoM1z0/th04)
|
||||
|
||||
Dacă ai folosit REA pentru ceva interesant, ne-ar plăcea să vedem rezultatul.
|
||||
Prezintă cazul într-un [issue](https://github.com/morluto/rea/issues) sau într-un
|
||||
[pull request](https://github.com/morluto/rea/pulls), menționând ținta analizată,
|
||||
întrebarea ta, cum te-a ajutat REA și ce ai descoperit.
|
||||
|
||||
## Întrebări frecvente
|
||||
|
||||
<details>
|
||||
<summary><strong>Ce agenți pot folosi REA?</strong></summary>
|
||||
|
||||
Orice agent care acceptă servere MCP locale. Programul de configurare pregătește
|
||||
[agenții acceptați](../installation.md#supported-agents); pentru ceilalți clienți
|
||||
poți folosi [înregistrarea manuală MCP](../installation.md#mcp-registry).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Am nevoie de Hopper, Ghidra sau IDA?</strong></summary>
|
||||
|
||||
Analiza nativă aprofundată folosește unul dintre aceste instrumente. Inspectarea
|
||||
statică JavaScript și .NET funcționează fără un motor de analiză nativă.
|
||||
Programul de configurare poate instala Hopper după aprobare; pentru Ghidra și IDA
|
||||
folosește instalările existente. Consultă [configurarea motoarelor de analiză](../installation.md#hopper).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Trebuie să pornesc mai întâi Hopper?</strong></summary>
|
||||
|
||||
REA pornește Hopper când o operație are nevoie de el. Pe macOS, un dialog afișat
|
||||
la prima pornire îți poate cere să alegi modul demonstrativ sau să activezi licența.
|
||||
Finalizează acel pas în aceeași sesiune de utilizator înainte de prima operație
|
||||
CLI/MCP sau de prima sarcină nesupravegheată. Deschide Hopper manual dacă este nevoie.
|
||||
Consultă [pornirea Hopper și depanarea](../installation.md#launcher-paths-and-troubleshooting).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Ce face instalarea skill-ului de pe skills.sh?</strong></summary>
|
||||
|
||||
Skill-ul oferă agentului instrucțiuni de investigare. Folosește `npx rea-agents setup`
|
||||
pentru a înregistra serverul MCP REA și a instala instrucțiunile corespunzătoare,
|
||||
apoi repornește agentul. Consultă [instalarea doar a skill-ului](../installation.md#skill-only-installation).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Ce cod returnează REA?</strong></summary>
|
||||
|
||||
Analiza nativă returnează pseudocod și cod de asamblare. Analiza JavaScript/Electron
|
||||
recuperează modulele și relațiile dintre ele. Agentul tău folosește aceste
|
||||
constatări pentru a scrie și testa o implementare;
|
||||
[studiile de caz](#studii-de-caz) oferă exemple detaliate.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>REA îmi încarcă aplicația pe un server?</strong></summary>
|
||||
|
||||
REA analizează țintele local. Agentul tău primește rezultatele uneltelor, iar
|
||||
furnizorul modelului său are propria politică privind datele.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Ce fac dacă întâlnesc o eroare?</strong></summary>
|
||||
|
||||
Actualizează mai întâi; o versiune recentă ar putea să o fi remediat deja.
|
||||
|
||||
Pentru o interfață CLI instalată cu `npm install --global` sau `bun add --global`:
|
||||
|
||||
```bash
|
||||
rea update
|
||||
```
|
||||
|
||||
Pentru configurarea agentului prin `npx`:
|
||||
|
||||
```bash
|
||||
npx rea-agents@latest setup
|
||||
```
|
||||
|
||||
Dacă folosești un agent, finalizează [actualizarea configurării](#actualizează-rea)
|
||||
și repornește-l. Reîncearcă aceeași sarcină. Dacă problema persistă,
|
||||
[deschide un issue](https://github.com/morluto/rea/issues) și include versiunea REA,
|
||||
tipul țintei analizate, pașii de reproducere și mesajele de eroare.
|
||||
|
||||
</details>
|
||||
|
||||
## Documentație
|
||||
|
||||
Începe cu [ghidurile practice](https://rea.tools/guides/) de pe site.
|
||||
Pentru opțiunile exacte, cerințele preliminare și contractele rezultatelor:
|
||||
|
||||
- [Instalare și configurare](../installation.md): înregistrarea agenților, configurarea motoarelor de analiză, actualizări și dezinstalare.
|
||||
- [Verificarea pregătirii și depanare](../installation.md#check-readiness-for-your-task): diagnosticarea unui agent sau motor de analiză.
|
||||
- [CLI și Evidence](../cli.md): comenzi, selectarea motorului, instantanee, import/export și coduri de ieșire.
|
||||
- [Contracte MCP](../mcp-contracts.md) și [prompturi pentru agenți](../mcp-prompts.md): rezultatele uneltelor, sesiuni și investigații ghidate.
|
||||
- [Catalogul uneltelor](../mcp-contracts.md#generated-catalog): inventarul generat al uneltelor, motoarelor de analiză și comenzilor CLI.
|
||||
- [Plan de dezvoltare](../roadmap.md): lucrări planificate și urmărirea progresului funcționalităților.
|
||||
|
||||
Raportează vulnerabilitățile conform [SECURITY.md](../../SECURITY.md).
|
||||
|
||||
## Istoricul stelelor
|
||||
|
||||
🎉 **300.000 de stele pe GitHub — vă mulțumim!**
|
||||
|
||||
Mulțumim tuturor celor care folosesc REA, raportează erori, propun funcționalități,
|
||||
testează versiuni și contribuie cu remedieri.
|
||||
|
||||
<a href="https://www.star-history.com/?repos=morluto%2Frea&type=date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=morluto/rea&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
|
||||
<img alt="Istoricul stelelor REA pe GitHub" src="https://api.star-history.com/chart?repos=morluto/rea&type=date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
## Precizări privind utilizarea
|
||||
|
||||
Consultă [DISCLAIMER.md](../../DISCLAIMER.md) pentru îndrumări privind utilizarea responsabilă.
|
||||
|
||||
Poziția proiectului față de utilizarea ilegală sau neautorizată se aplică tuturor
|
||||
versiunilor REA, canalelor de distribuție și platformelor; fiecare copie își
|
||||
păstrează licențele aplicabile.
|
||||
|
||||
REA este destinat cercetării legale, educației, interoperabilității, conservării
|
||||
software-ului și analizei programelor pe care le deții sau pe care ai autorizarea
|
||||
să le examinezi.
|
||||
|
||||
## Contribuții
|
||||
|
||||
Ne-ar bucura să contribui la REA! [Deschide un issue](https://github.com/morluto/rea/issues)
|
||||
pentru a raporta o eroare sau a propune o funcționalitate ori
|
||||
[trimite un pull request](https://github.com/morluto/rea/pulls) pentru a îmbunătăți
|
||||
codul sau documentația.
|
||||
|
||||
Consultă [CONTRIBUTING.md](../../CONTRIBUTING.md) pentru pregătirea mediului de dezvoltare
|
||||
și verificări, [ghidul de testare](../testing.md) pentru categoriile de verificări
|
||||
și [diagrama arhitecturii](../architecture.mermaid) pentru anumite straturi și
|
||||
relații de dependență.
|
||||
|
||||
## Licență
|
||||
|
||||
[MIT](../../LICENSE)
|
||||
|
||||
Codul scris în cadrul REA este licențiat sub MIT. Materialele terților își păstrează
|
||||
propriile licențe și mențiuni privind drepturile de autor; consultă
|
||||
[mențiunile privind terții](../../THIRD_PARTY_NOTICES.md) pentru inventarul
|
||||
dependențelor, textele licențelor păstrate și condițiile aplicabile uneltelor externe.
|
||||
|
||||
**Trebuie să obții legal uneltele comerciale și să ai dreptul să le folosești**,
|
||||
inclusiv decompilatoarele IDA Pro / Hex-Rays, Hopper și JEB, în condițiile
|
||||
licențelor aplicabile. REA nu îți acordă nicio licență, cheie sau drept de activare
|
||||
pentru aceste unelte. Versiunile de evaluare și demonstrative rămân supuse
|
||||
condițiilor furnizorilor, inclusiv restricțiilor privind utilizatorii,
|
||||
funcționalitățile, automatizarea și partajarea rezultatelor. Nu sunt autorizate
|
||||
copiile piratate, cheile furate, partajarea neautorizată a cheilor sau ocolirea
|
||||
restricțiilor de licențiere. Aceste îndrumări nu modifică licența MIT sau licențele terților.
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · **Русский** · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: Реверс-инжиниринг чего угодно
|
||||
|
||||
@@ -158,7 +158,9 @@ REA требует Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) или 26+ (>=26.1
|
||||
| PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) |
|
||||
| PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Записанные сбои Linux | Необработанные записи note, регистры/сигналы каждого записанного потока и необязательные кандидаты сопоставления с памятью | pwntools, предоставленный вызывающей стороной, в Linux x64; необязательные GDB/pwndbg; [записанные сбои](../recorded-crashes.md) |
|
||||
| Установленные настольные приложения | Возможные среды выполнения, файлы с доказательствами, компоненты и дальнейшие шаги | Ограниченная проверка каталогов и заголовков；[Настольные приложения](../desktop-applications.md) |
|
||||
| JavaScript / Electron | Модули, импорты, карты исходного кода, маршруты, IPC и связи с нативными дополнениями | Node.js и npm; [анализ приложений](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · **ไทย** · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: Reverse Engineer Anything
|
||||
|
||||
@@ -158,7 +158,9 @@ REA ต้องใช้ Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) หรื
|
||||
| ไบต์โค้ด EVM | ตัวเลือกฟังก์ชันสำหรับการเรียก ออฟเซ็ตไบต์ อาร์กิวเมนต์และความสามารถในการเปลี่ยนสถานะที่อนุมานได้ | ไฟล์บนเครื่องที่มีไบต์ดิบหรือข้อมูลเลขฐานสิบหกบน Linux x64; [คู่มือ EVM แบบออฟไลน์](../evm-bytecode.md) |
|
||||
| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| ข้อมูลการแครชของ Linux ที่บันทึกไว้ | ระเบียน note ดิบ รีจิสเตอร์/สัญญาณของทุกเธรดที่บันทึกไว้ และตัวเลือกการแมปเพิ่มเติม | pwntools ที่ผู้ใช้จัดเตรียมบน Linux x64; เลือกใช้ GDB/pwndbg เพิ่มเติมได้; [การแครชที่บันทึกไว้](../recorded-crashes.md) |
|
||||
| ไดเรกทอรีติดตั้งแอปเดสก์ท็อป | รันไทม์ที่เป็นไปได้ ไฟล์หลักฐาน ตัวบ่งชี้ส่วนประกอบ และขั้นตอนถัดไป | ตรวจสอบไดเรกทอรีและส่วนหัวโดยจำกัดขอบเขต；[แอปเดสก์ท็อป](../desktop-applications.md) |
|
||||
| JavaScript / Electron | โมดูล การนำเข้า ซอร์สแมป เส้นทาง IPC และความสัมพันธ์กับส่วนเสริมเนทีฟ | Node.js และ npm; [การวิเคราะห์แอปพลิเคชัน](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · **Türkçe** · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: Her şeyi tersine mühendislikle inceleyin
|
||||
|
||||
@@ -156,6 +156,8 @@ REA; Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) veya 26+ (>=26.12.1) ve npm gere
|
||||
| PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) |
|
||||
| PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| WASM artefaktı | Doğrulama, bölümler, tam import/export WAT biçimleri ve decode edilmiş WAT | Çağıranın sağladığı WABT 1.0.42; `inspect_wasm_artifact` |
|
||||
| EVM bayt kodu | Yönlendirme seçicileri, bayt ofsetleri, çıkarımla belirlenen argümanlar ve durum değiştirilebilirliği | Linux x64 üzerinde yerel ham bayt/onaltılık girdi; [çevrimdışı EVM rehberi](../evm-bytecode.md) |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · **Українська** · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: Реверс-інжиніринг будь-чого
|
||||
|
||||
@@ -158,7 +158,9 @@ REA потребує Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) або 26+ (>=26
|
||||
| Байт-код EVM | Селектори диспетчеризації, зміщення байтів, виведені припущення про аргументи та змінюваність стану | Локальні необроблені байти або шістнадцяткове представлення у Linux x64; [посібник EVM без запуску](../evm-bytecode.md) |
|
||||
| Rust binaries | Embedded cargo-auditable dependency list | [Rust binaries](../rust-binaries.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Записані аварійні завершення в Linux | Необроблені записи note, регістри/сигнали кожного записаного потоку й необов'язкові кандидати зіставлення пам'яті | pwntools, наданий стороною, що викликає інструмент, у Linux x64; необов'язкові GDB/pwndbg; [записані аварійні завершення](../recorded-crashes.md) |
|
||||
| Встановлені настільні програми | Можливі середовища виконання, файли доказів, компоненти та наступні кроки | Обмежена перевірка каталогів і заголовків；[Настільні програми](../desktop-applications.md) |
|
||||
| JavaScript / Electron | Модулі, імпорти, карти вихідного коду, маршрути, IPC і зв'язки з нативними доповненнями | Node.js і npm; [аналіз застосунків](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · **Roman Urdu**
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · **Roman Urdu** · [Română](README_ro.md)
|
||||
|
||||
# REA: Reverse Engineer Anything
|
||||
|
||||
@@ -198,10 +198,12 @@ Mazeed tools aur host support target par depend karte hain:
|
||||
| PE certificates | Authenticode WIN_CERTIFICATE entries aur PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) |
|
||||
| PE imports | Import aur delay-load DLL names, ordinals, IAT RVAs aur pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id aur ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, imports, lambdas aur Code header | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| WASM artifact | Validation, sections, exact import/export WAT forms aur decoded WAT | Aapka diya hua WABT 1.0.42; `inspect_wasm_artifact` |
|
||||
| EVM bytecode | Dispatch selectors, byte offsets, inferred arguments aur mutability | Linux x64 par local raw/hex carrier; [offline EVM guide](../evm-bytecode.md) |
|
||||
| SQLite databases | Tables, columns, indexes, views, triggers aur selected ordinary-table rows | Local database/WAL snapshot; native SQLite limits ke saath Node.js 24.x >=24.15 ya 26+ |
|
||||
| Apple IPS crash reports | Apple .ips metadata, threads, images aur crash classification | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Recorded Linux crashes | Raw notes, har recorded thread ke registers/signals aur optional mapping candidates | Linux x64 par aapka diya hua pwntools; optional GDB/pwndbg; [recorded crashes](../recorded-crashes.md) |
|
||||
| JavaScript / Electron | Modules, imports, source maps, routes, IPC aur native add-on relationships | Node.js aur npm; Linux: procps-compatible `ps`; [application analysis](../javascript-application-workflows.md) |
|
||||
| Websites | Page structure, scripts, network observations aur requested screenshots | Chrome-family browser; [browser analysis](../browser-observation.md) |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · **Tiếng Việt** · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA: Kỹ thuật dịch ngược cho mọi thứ
|
||||
|
||||
@@ -158,7 +158,9 @@ REA yêu cầu Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) hoặc 26+ (>=26.12.1)
|
||||
| PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) |
|
||||
| PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| Erlang BEAM | IFF chunks, atoms, exports, and tables | Built-in static BEAM inspection; [Erlang BEAM](../erlang-beam.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.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 trên Linux x64; GDB/pwndbg tùy chọn; [sự cố đã ghi lại](../recorded-crashes.md) |
|
||||
| Thư mục cài đặt ứng dụng máy tính | Các runtime có khả năng được dùng, tệp bằng chứng, dấu hiệu thành phần và bước tiếp theo | Kiểm tra thư mục và phần đầu tệp có giới hạn；[Ứng dụng máy tính](../desktop-applications.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](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · [简体中文](README_zh.md) · **繁體中文** · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA：逆向一切
|
||||
|
||||
@@ -159,6 +159,8 @@ REA 需要 Node.js 22.x（>=22.23.4）、24.x（>=24.22.1）或 26+ (>=26.12.1)
|
||||
| PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) |
|
||||
| PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| 已記錄的 Linux 崩潰 | 原始 note 記錄、每個已記錄執行緒的暫存器/訊號及可選的對映候選項 | Linux x64 上由呼叫方提供的 pwntools；可選的 GDB/pwndbg；[已記錄崩潰](../recorded-crashes.md) |
|
||||
| 桌面安裝目錄 | 執行階段候選、支持檔案、元件標記與後續操作 | 有界的目錄與檔頭檢查；[桌面應用](../desktop-applications.md) |
|
||||
| JavaScript / Electron | 模組、匯入、source map、路由、IPC 和原生附加元件關係 | Node.js 和 npm；[應用分析](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
<div align="center">
|
||||
|
||||
[English](../../README.md) · **简体中文** · [繁體中文](README_zh-TW.md) · [日本語](README_ja.md) · [한국어](README_ko.md) · [Türkçe](README_tr.md) · [Русский](README_ru.md) · [Tiếng Việt](README_vi.md) · [ไทย](README_th.md) · [Deutsch](README_de.md) · [Español](README_es.md) · [Français](README_fr.md) · [Українська](README_uk.md) · [Polski](README_pl.md) · [Português (Brasil)](README_pt-BR.md) · [العربية](README_ar.md) · [فارسی](README_fa.md) · [Bahasa Indonesia](README_id.md) · [Italiano](README_it.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md)
|
||||
· [Ελληνικά](README_el.md) · [മലയാളം](README_ml.md) · [Roman Urdu](README_ur-Latn.md) · [Română](README_ro.md)
|
||||
|
||||
# REA：逆向一切
|
||||
|
||||
@@ -159,6 +159,8 @@ REA 需要 Node.js 22.x（>=22.23.4）、24.x（>=24.22.1）或 26+ (>=26.12.1)
|
||||
| PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) |
|
||||
| PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) |
|
||||
| ELF notes | PT_NOTE/SHT_NOTE owners, types, GNU build-id and ABI-tag fields | Built-in static ELF inspection; [ELF notes](../elf-notes.md) |
|
||||
| Apple IPS crashes | .ips metadata, threads, images, registers and crash classes | Built-in static JSON inspection; [Apple IPS](../apple-ips.md) |
|
||||
| Linux kernel modules | .modinfo keys, __versions CRCs, this_module presence, and signature trailer | Built-in static ELF inspection; [kernel modules](../kernel-modules.md) |
|
||||
| 已记录的 Linux 崩溃 | 原始 note 记录、每个已记录线程的寄存器/信号及可选的映射候选项 | Linux x64 上由调用方提供的 pwntools；可选的 GDB/pwndbg；[已记录崩溃](../recorded-crashes.md) |
|
||||
| 桌面安装目录 | 运行时候选、支持文件、组件标记和后续操作 | 有界的目录与文件头检查；[桌面应用](../desktop-applications.md) |
|
||||
| JavaScript / Electron | 模块、导入、source map、路由、IPC 和原生扩展关系 | Node.js 和 npm；[应用分析](../javascript-application-workflows.md); Linux: procps `ps` |
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
# Recorded crash evidence
|
||||
|
||||
`inspect_recorded_crash` / `rea inspect-recorded-crash` inspect a caller-selected
|
||||
Linux ELF64 little-endian core independently of an active binary target. Two
|
||||
Linux ELF64 little-endian core independently of an active binary target. Apple
|
||||
`.ips` crash reports use the separate [Apple IPS](apple-ips.md) workflow. Two
|
||||
architecture profiles are interpreted, x86-64 and AArch64; each binds registers
|
||||
to its own `NT_PRSTATUS` layout, and any other `e_machine` is refused as
|
||||
`unsupported_target` before note interpretation.
|
||||
|
||||
+17
-7
@@ -94,13 +94,23 @@ Automatic main proposals and manual checkpoint preparation use
|
||||
`scripts/release-proposal.mjs` with the pinned release-please dependency.
|
||||
The controller applies `patches/release-please+17.3.0.patch` only when invoked;
|
||||
normal dependency installation and published-package installation do not apply it.
|
||||
The patch avoids commit-file backfills and path splitting for a single root Node
|
||||
package with the default changelog, default or always-bump-minor versioning,
|
||||
no path exclusions and no explicit plugins. Other configurations retain the
|
||||
upstream file attribution workflow. Associated PR metadata and commit overrides
|
||||
still come from GitHub. The controller sizes commit search from the complete
|
||||
selected Git history, and a missing known release boundary fails before proposal
|
||||
creation. Publication continues through the pinned release-please action.
|
||||
The patch avoids commit-file backfills, associated PR file lists and path splitting
|
||||
for a single root Node package with the default changelog, default or
|
||||
always-bump-minor versioning, no path exclusions and no explicit plugins. Other
|
||||
configurations retain the upstream file attribution workflow. Commit history and
|
||||
associated PR metadata still come from GitHub: release notes need the commits,
|
||||
and `BEGIN_COMMIT_OVERRIDE` needs the merged PR body. Skipped file lists remain
|
||||
unknown rather than being reported as empty. The controller sizes commit search
|
||||
from the complete selected Git history, and a missing known release boundary
|
||||
fails before proposal creation.
|
||||
|
||||
History-page reads retry GitHub's canonical internal GraphQL response error within
|
||||
the existing five-retry budget and exponential backoff. Each retry uses the same
|
||||
cursor; permission, validation and mixed errors fail immediately. Exhaustion
|
||||
stops preparation before proposal writes. The controller does not restart proposal
|
||||
creation or retry mutations. An internal GraphQL error does not establish API
|
||||
quota exhaustion or prove that query size caused the failure. Publication
|
||||
continues through the pinned release-please action.
|
||||
|
||||
When upgrading release-please, review the upstream manifest implementation,
|
||||
refresh the versioned patch and run the release proposal and workflow boundary
|
||||
|
||||
@@ -42,6 +42,12 @@ Captured stdout and stderr are retained up to a 16 MiB combined limit; `output_t
|
||||
|
||||
Persistent GDB sessions, including the MCP workflow and one-shot `rea debug-with-gdb` CLI, are available only on Linux. REA verifies a live inferior's output descriptors through `/proc` before detaching it; it does not claim equivalent descriptor verification on macOS. Windows is also unsupported because owned Job Object cleanup can terminate debugger inferiors. On supported Linux hosts, `start_gdb_session`, `gdb_console`, `gdb_session_status`, and `close_gdb_session` manage a persistent GDB/MI session in MCP. The one-shot CLI requires a caller-selected durable TTY: `rea debug-with-gdb --inferior-tty /dev/pts/7 'file ./program'`. The TTY must remain available after GDB exits so a detached inferior can continue writing. MCP starts GDB with `--nx --quiet --interpreter=mi3`, retries initialization with MI2 if MI3 initialization returns an error and cleanup succeeds, waits for its prompt, and disables auto-loading. Pass optional `inferior_tty` to select the terminal that future inferior runs use; REA configures it before the session becomes ready and checks the exact value with GDB/MI. `gdb_session_status` reports the selected path, whether REA still considers the configuration verified, and whether invalid UTF-8 has been observed in MI bytes (`mi_invalid_utf8`) or stderr (`stderr_invalid_utf8`). Commands that can change the inferior TTY or redirect a run revoke that verification permanently for the session, so close retains GDB ownership if a live inferior remains. The complete built-in inspections `show inferior-tty` and `help inferior-tty` preserve verification; compound commands still use the conservative mutation checks. Closing a session with one live inferior and a verified TTY automatically detaches the target, which can resume execution; MCP clients receive destructive-operation annotations for this behavior. The console remains unrestricted and can run shell commands, change target state, access files, and use network in the REA process user's security context. Raw MI records and console/target/log streams are returned with Evidence; command output is retained up to 16 MiB and explicitly marked when truncated. GDB startup waits 10000 ms and each MI command waits 120000 ms. This release has no runtime override for those deadlines, the 16 MiB command output budget, session capacity, or the pending-command queue. `command_timeout_ms` does not change them.
|
||||
|
||||
With multiple live inferiors, or a live inferior without a verified TTY, manual
|
||||
close requests an explicit disposition and keeps the session ready. Use
|
||||
`gdb_console` to select and explicitly detach or terminate each remaining
|
||||
inferior, then retry `close_gdb_session`. After owned cleanup has started,
|
||||
console commands remain unavailable while that cleanup can be retried.
|
||||
|
||||
`completion_status` describes completion of the selected console command, not
|
||||
termination of its inferior. After a `^running` result, REA queues a read-only
|
||||
`-gdb-show mi-async` query and waits for its tokenized reply before releasing the
|
||||
@@ -88,6 +94,14 @@ Captured stdout and stderr are retained up to a 16 MiB combined limit; `output_t
|
||||
## Cutter bridge
|
||||
|
||||
Cutter commands use the local REA Python bridge and authenticated loopback messages.
|
||||
Discovery reads the session descriptors that the plugin publishes in the bridge
|
||||
directory. Set `REA_CUTTER_BRIDGE_DIR` in both REA's environment and the environment
|
||||
that starts Cutter to select a custom directory. Both expand `~` and `~/` paths
|
||||
against the current user's home, including `~\` paths on Windows. By default,
|
||||
they use `%LOCALAPPDATA%\REA\CutterBridge` on Windows when `LOCALAPPDATA` is set,
|
||||
and `~/.cache/rea/cutter-bridge` otherwise. The two processes must resolve the
|
||||
same directory for discovery to find the published sessions.
|
||||
|
||||
The client and plugin must support the current v2 handshake; older peers are
|
||||
rejected before dispatch because they cannot preserve cross-caller recovery proof.
|
||||
The client checks the final encoded request against
|
||||
|
||||
@@ -83,7 +83,8 @@ empty dependency set. Retained views describe the captured artifact digest;
|
||||
they do not assert that the current file or running application is unchanged.
|
||||
|
||||
ELF section names are resolved through the section-header string table.
|
||||
Zlib-compressed name tables are decoded within the native structural budget.
|
||||
Zlib- and Zstandard-compressed name tables are decoded within the native structural
|
||||
budget. Zstandard decoding also uses a 128 MiB window limit.
|
||||
If a name table uses unsupported compression, the result reports that
|
||||
limitation and leaves `.dep-v0` presence unknown rather than reporting the
|
||||
section absent.
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
# Plan
|
||||
|
||||
1. Add `environmentCoverageView.ts`: the request schema, the result fields, the
|
||||
hint per write reason (`satisfies Record<WriteReason, string>`), a
|
||||
summarizer over state views and write plans, and the projector, which
|
||||
projects the environment-state view and summarizes it. Register the kind in
|
||||
the view unions, the grouping dispatch and the view service (state
|
||||
accumulator, inferred confidence).
|
||||
2. Split the export's input read into `readEnvironmentExportFile` and
|
||||
`environmentExportFile` (parse and seal bytes), both naming the calling
|
||||
operation, and let the export take an already prepared state.
|
||||
3. Add `environmentBuild.ts`: classify the capture, project the manifest from
|
||||
the in-memory Evidence, serialize it as `--format json` writes it to a file,
|
||||
authenticate the pair from those bytes, name the environment, prepare the
|
||||
state as the export does, summarize coverage, scan credential names, then
|
||||
plan (dry run) or export. `environmentBuildReport.ts` holds the scan and the
|
||||
naming helpers.
|
||||
4. Register `environment-build` in the CLI: inspect a HAR through the capture
|
||||
service as `inspect-web-network-capture` does, or read Evidence once as the
|
||||
export does, and log stages at info.
|
||||
5. Switch `scripts/verify-agentenv-environment.mjs` to the build command.
|
||||
6. Document the command, the report, the hints, what ships, and the view.
|
||||
7. Tests: coverage summary and hint completeness, the view against the state
|
||||
view, build equivalence with the three-step path in process and through the
|
||||
CLI, dry run, naming, refusals, the credential scan, and the view over MCP.
|
||||
@@ -0,0 +1,96 @@
|
||||
# Build an environment in one step
|
||||
|
||||
Issue: https://github.com/morluto/rea/issues/4933
|
||||
|
||||
## Outcome
|
||||
|
||||
Building an agent environment bundle takes three commands and a hand-written
|
||||
view request that embeds the whole capture inline, so large captures hit inline
|
||||
input accounting. The views apply no opt-in template rules by default, while the
|
||||
published capture-built environments all use the same four, and a local capture
|
||||
is named after its origin host (`127-0-0-1-3105`). Nothing reports which tools
|
||||
an environment serves from its state, or why a write tool is withheld.
|
||||
|
||||
`rea environment-build <capture> [directory]` builds the bundle in one offline
|
||||
step and reports what it serves. A new `environment-coverage` analysis view
|
||||
reports the same summary for any capture, so an agent can check a recording
|
||||
before building.
|
||||
|
||||
## Requirements
|
||||
|
||||
- The capture is a `.har` file, inspected as `inspect-web-network-capture`
|
||||
inspects it, or capture Evidence JSON from `inspect_web_network_capture` or
|
||||
`capture_browser_scenario`; any other extension is refused before it is
|
||||
read, and a HAR document saved as `.json` is refused with a hint.
|
||||
- The manifest is projected from the in-memory capture as retained Evidence,
|
||||
with the default rules `after-uid-literal`, `opaque-token`,
|
||||
`sibling-variance` and `prefix-variance` unless `--template-rule` or
|
||||
`--format-rules-only` selects others; rules apply in the views' order and a
|
||||
repeated rule is refused, as the views refuse it.
|
||||
- For the same capture path, every bundle file is byte-identical to what
|
||||
`inspect-web-network-capture --format json`, `inspect-analysis-view --format
|
||||
json` (the same rules in the views' order) and `environment-export` (the
|
||||
build's name) write, Evidence ids included. The Evidence is serialized once
|
||||
into one exactly sized buffer, whose bytes are both authenticated and shipped.
|
||||
- The name is `--name`, else the manifest's, unless the origin is a loopback
|
||||
name or IP literal: then the capture file's name, with a warning; a file name
|
||||
that yields no portable bundle name is refused, asking for `--name`.
|
||||
- The report carries the export's tool count, state, package source and files,
|
||||
plus the capture and manifest identities, `coverage`, warnings and the next
|
||||
command, shell-quoted. `coverage`
|
||||
counts read tools answered from the state and replayed (per view reason), and
|
||||
lists write tools as served or withheld with their reason, plan record, the
|
||||
contradicting read and a hint; it is null when the state is unavailable.
|
||||
- Every write reason has a hint; a reason without one fails to compile.
|
||||
- Credential-named header names, query parameter names and JSON or form body
|
||||
members that hold a value are reported as a count and the first 20 record or
|
||||
event pointers, never values, and never refuse a build; the scan cannot
|
||||
overflow the stack on deeply nested bodies. A body is read as a form
|
||||
(`application/x-www-form-urlencoded`, by `URLSearchParams`) or as JSON (the
|
||||
media types replay parses as JSON) by its recorded media type; a body with
|
||||
none, or one naming neither, is JSON when it starts with `{` or `[` and a form
|
||||
when it contains `=` and no whitespace, so plain text and empty bodies yield
|
||||
no pointers. A browser scenario is scanned by event rather than by record:
|
||||
every retained request and response network-content event's header values and
|
||||
body, including a response whose request began before the browser was attached
|
||||
and a transaction that cannot be attributed to one request and response, and
|
||||
each transaction URL's query parameters once; its pointers name the event's
|
||||
index in `events.items` (`event 4 response /token`). Each occurrence of a
|
||||
repeated form field counts, as each repeated header or query parameter does. A
|
||||
HAR request recorded with structured form parameters and no text, or the null
|
||||
text mitmproxy's SaveHar records, is scanned by those parameters. Text bodies
|
||||
over the 4 MiB scan limit, measured in UTF-8 bytes, including a response body
|
||||
decoded only as a prefix, are not scanned; they are reported as a
|
||||
`credential-scan-incomplete` warning with a count and the first 20 record or
|
||||
event and side pointers (`record 3 response`, `event 4 response`), never
|
||||
contents, and never refuse a build. Binary bodies hold no JSON or form text
|
||||
and are neither scanned nor reported.
|
||||
- The inspected HAR's Evidence and the projected manifest are admitted against
|
||||
the live heap headroom for parsing and sealing before either is serialized, as
|
||||
a capture Evidence file is before it is read; one that does not fit is refused
|
||||
as `resource_constraint` before anything is written.
|
||||
- An empty or NUL-containing capture, directory or package tarball argument is
|
||||
refused as invalid input; it is never resolved to the working directory.
|
||||
- Nothing is written before the bundle stage; `--dry-run` writes nothing,
|
||||
reports the files a build would write and refuses the package tarballs a build
|
||||
refuses, admitting, reading and hashing, and releasing the tarball as a build
|
||||
does before copying it, so a tarball whose contents cannot be read is refused:
|
||||
a close it cannot confirm is reported as incomplete cleanup that keeps its
|
||||
owner. The directory must be absent or empty.
|
||||
- SIGINT is checked between stages and after a dry run's last step: a build
|
||||
cancelled before the bundle stage writes nothing, and one cancelled during the
|
||||
write names the written bundle.
|
||||
- The `environment-coverage` view summarizes the environment-state view with
|
||||
the same rules, refuses what it refuses and is inferred. It does not apply the
|
||||
serve-time catalog and state admission checks, and says so in a limitation.
|
||||
- The `real-agentenv` lane builds its bundle with `environment-build`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- No change to the three existing commands' contracts, or to what any view
|
||||
derives or any environment serves.
|
||||
- No browser launch or network access: scenarios are recorded with
|
||||
`capture-browser-scenario` first.
|
||||
- No `--replace`, no refusal on credential names, and no rewriting of the
|
||||
capture's absolute path, which Evidence identity includes.
|
||||
- No MCP export tool; that is a separate change.
|
||||
@@ -0,0 +1,13 @@
|
||||
# Tasks
|
||||
|
||||
- [x] Record the outcome, requirements and non-goals.
|
||||
- [x] Add the environment-coverage view and register it.
|
||||
- [x] Split the export's input read and accept a prepared state.
|
||||
- [x] Add the build module, its report helpers and the CLI command.
|
||||
- [x] Switch the real-agentenv lane to the build command.
|
||||
- [x] Document the command, the report, the hints and the view.
|
||||
- [x] Add domain, service, CLI and MCP tests.
|
||||
- [x] Run static, formatting, duplication, documentation and test gates.
|
||||
- [x] Build the 50 published captures and compare them with the three-step path.
|
||||
- [x] Build environments end to end on Linux VMs and run them with agents.
|
||||
- [x] Address the independent review.
|
||||
@@ -0,0 +1,113 @@
|
||||
# Verification
|
||||
|
||||
Executed on macOS with Node v24.22.1 (the checkout's `.nvmrc`) on main `3d4f5565`, and on Ubuntu 24.04 VMs for the
|
||||
end-to-end runs.
|
||||
|
||||
## Gates
|
||||
|
||||
- `npm run -s check:fast`, `npm run -s format:check`, `npx knip`, `npm run -s scan:todos`, `npm run -s docs:check`,
|
||||
`npm run -s verify:test-discovery` and `npm run -s mcp-catalog:check`: passed.
|
||||
- `npm run jscpd`: 3.52% duplicated lines over 4348 files, as on main (3.52% over 4341).
|
||||
- `npx vitest run --project domain --project services`: 9537 passed, 6 skipped and 151 failed. The same 151 fail on main
|
||||
`3d4f5565` in this environment (9513 passed there); none is new.
|
||||
- `npm run -s test:prepare`, then `npm run -s test:focused --` the environment build, export, export-inputs and serve CLI
|
||||
boundaries, the analysis-view CLI and MCP boundaries and the environment serve MCP boundary: 7 files, 67 passed and 1
|
||||
failed, "projects portable artifact inventory after the original ZIP is removed", which fails the same way on main.
|
||||
- `npm run verify:agentenv:environment` (the `real-agentenv` lane) passed on Ubuntu 24.04 with `agent-env 0.9.1334`.
|
||||
|
||||
## Equivalence and coverage over the published captures
|
||||
|
||||
Each of the 50 published capture-built environments' captures (capture Evidence JSON) and four scoped HAR recordings
|
||||
(EspoCRM, Ghost, NocoDB, Sonarr) was built twice: once with `rea environment-build <capture> <dir> --json`, and once
|
||||
with the three CLI steps, `inspect-web-network-capture --format json` (HAR only), `inspect-analysis-view` with an
|
||||
`evidence-file` source and the four default rules, and `environment-export --name <the build's name>`. Every file of
|
||||
every bundle was compared by SHA-256.
|
||||
|
||||
| Inputs | Bundles identical | State served | Read tools from state / replayed | Write tools served / withheld | Build / three steps |
|
||||
| ------------------------- | ----------------- | ------------ | -------------------------------- | ----------------------------- | ------------------- |
|
||||
| 50 capture Evidence files | 50 of 50 | 50 | 1,100 / 290 | 50 / 143 | 32.9 s / 59.2 s |
|
||||
| 4 scoped HARs | 4 of 4 | 4 | 166 / 21 | 5 / 12 | 8.3 s / 12.4 s |
|
||||
|
||||
- The coverage of every capture equals an independent census of the environment-state view with the same rules (read
|
||||
views by shape, write plans by verdict and reason).
|
||||
- 43 of the 50 captures have a loopback origin and are named after their file (`grafana.capture.json` becomes `grafana`)
|
||||
with a `name-from-file` warning. 20 carry a `credential-named-members` warning; the published captures were scrubbed by
|
||||
their pipeline, whose placeholder strings still count.
|
||||
- The withheld writes' reasons: no-state-target 86, contradicted 16, unconfirmed 14, no-observation 13,
|
||||
unexplained-change 8, side-effect 4, body-unusable 1, incomplete-entities 1.
|
||||
|
||||
## End to end
|
||||
|
||||
Five environments last rebuilt on 10-23 were built again with this branch's packed CLI on disposable Ubuntu VMs, four
|
||||
from their scoped HAR recordings and Metabase from its capture Evidence, with `rea environment-build <capture> <dir>
|
||||
--name <app> --package-tarball <tarball>`. Each bundle then ran its smoke task, a retrieval eval generated from the
|
||||
bundle's own manifest and capture, and the write eval from its recorded write spec, with two models through a LiteLLM
|
||||
proxy (`fireworks_ai/gpt-oss-120b`, `fireworks_ai/glm-5p3-flash`), one run per task.
|
||||
|
||||
| App | Input | Served tools of manifest | Served writes (build report) | Smoke | Retrieval gpt-oss / GLM | Writes gpt-oss / GLM |
|
||||
| -------- | -------- | ------------------------ | -------------------------------------------------- | ------ | ----------------------- | -------------------- |
|
||||
| Ghost | HAR | 35 of 38 | 0 (3 no-state-target) | passed | 12/12 / 8/12 | 0/2 / 0/2 |
|
||||
| Metabase | Evidence | 40 of 42 | 1 (create contradicted, update unexplained-change) | passed | 12/12 / 12/12 | 1/2 / 1/2 |
|
||||
| EspoCRM | HAR | 85 of 88 | 0 (2 contradicted, 1 unexplained-change) | passed | 12/12 / 10/12 | 0/2 / 0/2 |
|
||||
| NocoDB | HAR | 23 of 28 | 0 (4 no-state-target, 1 unconfirmed) | passed | 6/6 / 5/6 | 0/3 / 0/3 |
|
||||
| Sonarr | HAR | 49 of 50 | 5 (1 side-effect) | passed | 12/12 / 12/12 | 3/3 / 3/3 |
|
||||
|
||||
- Every write task passed with both models when the build report listed its tool as served (Metabase's card delete and
|
||||
Sonarr's release-profile create, update and delete), and failed when it listed it as withheld: 8 of 24 write episodes
|
||||
passed, exactly the served ones. On main these apps' other writes are withheld; the published v0.2.0 versions were
|
||||
built with the state-target and write-rule changes, which serve more of them.
|
||||
- The retrieval misses are GLM answers on bundles byte-identical to the three-step path's; gpt-oss passed all 54.
|
||||
- The `real-agentenv` lane, switched to `environment-build`, passed from a fresh checkout on Ubuntu with
|
||||
`agent-env 0.9.1334` and the host's Docker: five public cases, the smoke task passed in 26.6 s, no new containers.
|
||||
|
||||
## Review
|
||||
|
||||
An independent review rebuilt the branch and tried to refute it. It confirmed byte-equality for pretty-printed,
|
||||
CRLF and newline-free Evidence, Unicode HARs across output part boundaries, inline and file view sources, browser
|
||||
scenario Evidence and relative or symlinked paths, and that the refactored export answers 16 success and refusal cases
|
||||
exactly as main does. Its findings, all addressed:
|
||||
|
||||
- The credential scan recursed and a 4 KB body nested 5,000 deep crashed the build; it now walks with its own stack, and
|
||||
also scans header names, query names and form bodies.
|
||||
- SIGINT after the capture was read was ignored; the build now checks the signal between stages and writes nothing when
|
||||
cancelled before the bundle stage.
|
||||
- The coverage view does not apply the serve-time catalog and state admission checks; a limitation and the docs now say
|
||||
so.
|
||||
- A dry run accepted a tarball the build refuses; it now opens it for reading.
|
||||
- Repeated `--template-rule` values were deduplicated; they are refused as the views refuse them. A HAR saved as `.json`
|
||||
gets a hint, file-derived names follow the bundle name rules, `localhost.` is anonymous, and the next command is
|
||||
shell-quoted.
|
||||
- The `no-observation` hint now covers updates and deletes of entities the state never held; the docs no longer claim
|
||||
the build launches no process, state the conditions of byte-equality, and name the headers inspection excludes; the
|
||||
MCP tool description names the view.
|
||||
|
||||
## Review round on main `584120e8`
|
||||
|
||||
The branch merged main `584120e8`: the export's file read now returns permission refusals through `Result`, as main
|
||||
does, under the build's operation name, and the `environment-coverage` sentence sits in main's `inspect_analysis_view`
|
||||
description. Four automated review findings were fixed, each with a test that fails on the merge:
|
||||
|
||||
- A browser scenario's retained header values and the query parameters of its recorded URLs are scanned for credential
|
||||
names as a HAR's are; the manifest and replay record projections are unchanged.
|
||||
- `--dry-run --package-tarball` admits and releases the tarball through the export's own regular-file scope, so a close
|
||||
it cannot confirm is retried and then reported as incomplete cleanup that keeps its owner.
|
||||
- A dry run checks for cancellation after reading the tarball, before it reports a plan.
|
||||
- Evidence is serialized into one exactly sized buffer instead of chunks joined by a copy. Those bytes are still parsed
|
||||
and sealed before authentication, so authentication reads exactly what ships.
|
||||
|
||||
On macOS with Node v22.23.1: the static gates passed (`npm run jscpd`: 3.53%), `npx vitest run --project domain
|
||||
--project services` passed (9753, 6 skipped), the environment boundary projects passed (102), and the focused build,
|
||||
export, export-inputs, serve and analysis-view boundaries with tool schema validity passed (9 files, 96). Rebuilt over
|
||||
the same 50 captures and four HARs, all 54 bundles are byte-identical to the three-step path's, with the same coverage,
|
||||
served writes and warnings as before the round.
|
||||
|
||||
## Review round on main `3d84215b`
|
||||
|
||||
The branch merged main through `3d84215b`: #6946, which carries this builder, in `27a4e3986`, then #7008. Integrating
|
||||
#6946 took main's event-based credential scan, which also answers the review finding that a scenario transaction with
|
||||
duplicate responses or content events hid their credential names; a test that both content events of a transaction
|
||||
recorded twice are scanned fails on `0895c89bc`. The integration had dropped `0895c89bc`'s tests for form text recorded
|
||||
without a media type and its `body-unusable` hint; both are restored, and main's scan passes the tests.
|
||||
|
||||
Rebuilt at `05566419e` over the same 50 captures and four HARs, all 54 bundles are byte-identical to the three-step
|
||||
path's, and their warnings and credential counts equal the previous round's.
|
||||
@@ -0,0 +1,21 @@
|
||||
# Plan
|
||||
|
||||
1. Add the `request` action to the scenario schema: methods, path, query,
|
||||
headers with page value sources, JSON body and expected statuses; validate
|
||||
the origin and the body against the start URL; include query and header
|
||||
secrets in the declared-secret check.
|
||||
2. Add `PlaywrightScenarioRequest.ts`: check the page's origin, build the URL,
|
||||
resolve header values (admitting values read from the page to the scenario's
|
||||
redaction), fetch in the page with a timeout and read the whole response,
|
||||
then check the status. Dispatch it from the action runner with the start
|
||||
origin, and add the limitation when a scenario has a request step.
|
||||
3. Add a real-browser lane, `verify:browser:request`: a fixture item API that
|
||||
requires a CSRF cookie header and a stored bearer token for writes, a write
|
||||
session recorded through the CLI, the build's served writes, and a failing
|
||||
expected status.
|
||||
4. Add the `export_environment_bundle` contract, effects, CLI alias, catalog
|
||||
family and handler: check the destination as other MCP output tools do,
|
||||
resolve the capture bytes, and call the build with an exclusive destination.
|
||||
5. Write the skill reference, route it from SKILL.md and install it with setup.
|
||||
6. Document the request step, the MCP tool and recording writes.
|
||||
7. Tests: request step unit tests, the MCP tool boundary, setup's skill files.
|
||||
@@ -0,0 +1,83 @@
|
||||
# Build an environment from a prompt
|
||||
|
||||
## Outcome
|
||||
|
||||
`rea environment-build` builds a bundle from one capture, but an agent asked to
|
||||
"make an environment of this app" still cannot finish the job through REA's MCP
|
||||
server. A browser scenario can only reach an application's API through the UI or
|
||||
a `goto` GET, so recording the writes an environment serves means scripting every
|
||||
form, and there is no MCP tool that writes a bundle. Nothing tells the agent how
|
||||
to record a session the state can learn writes from, or when to stop recording.
|
||||
|
||||
A `request` scenario action sends one same-origin request through the page's own
|
||||
`fetch`, so a scenario can sign in through the UI and then call the application's
|
||||
API, writes included, with the session's cookies and the CSRF or bearer values
|
||||
the application's own requests send. An `export_environment_bundle` MCP tool
|
||||
builds the bundle from capture Evidence, as `environment-build` does. A skill
|
||||
reference walks an agent from the prompt to a bundle: map, record, check
|
||||
coverage, re-record by reason, export and hand off.
|
||||
|
||||
## Requirements
|
||||
|
||||
- A `request` step names a method (`GET`, `HEAD`, `POST`, `PUT`, `PATCH`,
|
||||
`DELETE`), a path on the start URL's origin, ordered query entries, headers,
|
||||
an optional JSON body and optional expected statuses. Validation refuses a
|
||||
path that resolves to another origin, a body on `GET` or `HEAD`, a 3xx
|
||||
expected status, header names a page's `fetch` cannot set or Chrome drops
|
||||
(`User-Agent`), a header name given twice, line breaks or control characters
|
||||
in literal values and prefixes, and a path the URL parser rejects, as a field
|
||||
issue at the step's path.
|
||||
- Header values are literals, declared secrets, a cookie the browser holds for
|
||||
the request URL, or a local storage value on the start origin, optionally read
|
||||
at a JSON pointer, with an optional prefix; local storage values are read only
|
||||
while the page is on the start origin. Values read from the page are redacted
|
||||
like declared secrets from records made after they are read, as stored and as
|
||||
sent; a value read again keeps its first marker, a colliding label never
|
||||
unredacts an earlier value, and values shorter than 8 characters are not
|
||||
redacted.
|
||||
- The request runs through the page's `fetch` with same-origin credentials, from
|
||||
a page on the start origin (checked again in the page as it is sent), follows
|
||||
no redirects, and completes when the response has been read to its end,
|
||||
without keeping its body. A redirect, a status outside `expected_status`, a
|
||||
network error or the step timeout fails the step; later steps are cancelled as
|
||||
for other actions. The page sends only before the step's deadline, which it
|
||||
receives as an absolute time, and within one second of being handed the
|
||||
request; a busy page that starts later sends nothing, and the step hands the
|
||||
request over again while it is neither cancelled nor out of time. A step
|
||||
cancelled or out of time before the page starts its request sends nothing,
|
||||
except a request the page starts within that second of being handed it. A
|
||||
browser whose clock runs ahead of the host's fails the step. Its network
|
||||
events are attributed to the step.
|
||||
- Captures with request steps say so in a limitation. A scenario without one
|
||||
validates, runs and records exactly as before.
|
||||
- `export_environment_bundle` takes retained capture Evidence or a capture
|
||||
Evidence file, an absolute output directory that does not exist and whose
|
||||
parent does, and the build's name, template rules, package tarball and dry
|
||||
run. It writes the bundle `environment-build` writes from the same Evidence
|
||||
bytes (retained Evidence serialized as `--format json` writes it) and returns
|
||||
the same report, validated by its output schema. It refuses an existing
|
||||
directory, empty or not, a parentless or relative one, unknown Evidence, an
|
||||
unnamed loopback capture and repeated rules, and writes nothing when it
|
||||
refuses. Retained Evidence is refused for heap headroom before it is
|
||||
serialized, as an Evidence file is before it is read. `environment-build` is
|
||||
its CLI command.
|
||||
- The skill reference `references/environments.md` is installed with the skill
|
||||
and routed from SKILL.md. It covers disposable instances only, credentials
|
||||
from environment variables, the recording rules the state needs, coverage, the
|
||||
stop rule, the hand-off, and how to reach objects by id when the server
|
||||
assigns ids: ids the caller chooses, a second scenario, or the UI.
|
||||
- Coverage of a capture whose records are not all timed, which includes every
|
||||
browser scenario capture, says the state learns no write clock.
|
||||
- Stop rule: re-record a withheld write at most twice for a recording gap
|
||||
(`no-state-target`, `no-observation`, `unconfirmed`, `incomplete-entities`),
|
||||
once for `unexplained-change` and `no-call`, and stop at once for application
|
||||
behaviour (`side-effect`, `contradicted`, `body-unusable`).
|
||||
|
||||
## Non-goals
|
||||
|
||||
- No cross-origin requests, form or multipart bodies, or arbitrary script
|
||||
actions.
|
||||
- No retroactive redaction of values a request step reads: a login response
|
||||
recorded before the step keeps the token it returned, as captures do today.
|
||||
- No application start, seed or reset, and no publishing of bundles.
|
||||
- No change to what any view derives or any environment serves.
|
||||
@@ -0,0 +1,11 @@
|
||||
# Tasks
|
||||
|
||||
- [x] Record the outcome, requirements and non-goals.
|
||||
- [x] Add the request action, its validation and its Playwright runner.
|
||||
- [x] Add the real-browser request lane.
|
||||
- [x] Add the export_environment_bundle tool.
|
||||
- [x] Write and install the skill reference.
|
||||
- [x] Document the request step, the tool and recording writes.
|
||||
- [x] Run static, formatting, documentation and test gates, and the existing browser lanes.
|
||||
- [x] Build environments from prompts with an agent against live applications on Linux VMs.
|
||||
- [x] Address the two independent reviews.
|
||||
@@ -0,0 +1,82 @@
|
||||
# Verification
|
||||
|
||||
Executed on macOS with Node v24.22.1 at `feat/environment-prompt` 8dfd5a4d (stacked on the environment-build branch at
|
||||
eeab0bda), and on Ubuntu 24.04 VMs for the end-to-end runs.
|
||||
|
||||
## Gates
|
||||
|
||||
- `npm run -s typecheck`, `lint`, `format:check`, `docs:check`, `mcp-catalog:check`, `verify:test-discovery` and
|
||||
`npx knip`: passed.
|
||||
- `npx vitest run --project domain --project services --project adapters`: 16,347 passed and 1 failed,
|
||||
"stops Inspector target authorization after the current stat settles", which fails the same way on the base fce1aba8
|
||||
in this environment (16,326 passed, 2 failed there); none is new.
|
||||
- Boundaries: the bundle tool, analysis view, tool schema validity, environment-build CLI, setup skill and client
|
||||
lifecycle suites (123 passed), and every browser and scenario MCP and CLI boundary suite (68 passed).
|
||||
- Real Chrome: `verify:browser:request` (new: 22 request steps, the CSRF cookie and stored token authenticate seven
|
||||
writes and never reach the Evidence, two queued writes are refused, the build serves the three write tools, an unexpected status fails the step and
|
||||
cancels the rest, and a redirect to another origin is not followed, the other origin receiving nothing) and
|
||||
`verify:browser:network` passed. `verify:browser` stops at "Real Chrome stable capture identities did not
|
||||
reconcile", an `inspect_web_page` comparison this change does not touch, and fails the same way on the base.
|
||||
- `verify:browser:request` runs each CLI call under the shared package verifier command owner, which stops the CLI and
|
||||
the browser it launched on timeout, output overflow or failure before the lane's private root is removed, and reports
|
||||
a failed stop with the root retained; `browserRequestVerifierOwnership.test.ts` proves a still-running CLI's
|
||||
separately grouped browser is stopped before the root goes.
|
||||
|
||||
Scenarios without request steps are unchanged: the action union gains a member, the secrets refactor compiles the same
|
||||
patterns, the request-step limitation appears only with request steps, and the browser suites and the network lane pass.
|
||||
|
||||
## End to end: environments from a prompt
|
||||
|
||||
Five self-hosted applications were brought up fresh and seeded on four disposable VMs, loopback only. Claude Code 2.1.310
|
||||
(`claude-sonnet-5-5` through a LiteLLM proxy) got this branch's packed CLI, registered with `rea setup --client
|
||||
claude_code` (the MCP server and the skill), and one prompt per application: build an agent environment of the app at
|
||||
this URL, cover these entities, the instance is disposable but leave the seeded data as found, sign in as this user, the
|
||||
password is in `APP_PASSWORD`, Chromium is here, write the bundle there. The prompt did not mention the skill. The agent
|
||||
could use the REA tools, the skill and file tools; Bash and web tools were disabled.
|
||||
|
||||
Each bundle was then rebuilt with `environment-build` from its own `evidence.json` and this branch's tarball (the
|
||||
registry's `[email protected]` has no `environment-serve`); `manifest.json` and `evidence.json` were byte-identical to
|
||||
the agent's in all five. It ran its smoke task, a retrieval eval generated from its manifest and capture, and the
|
||||
application's recorded write eval with `fireworks_ai/gpt-oss-120b` and `fireworks_ai/glm-5p3-flash`, one run per task.
|
||||
|
||||
| App | Agent run | Recordings | Records | Tools (state / replayed reads) | Served writes | Smoke | Retrieval gpt-oss / GLM | Writes gpt-oss / GLM |
|
||||
| -------- | --------- | ---------- | ------- | ------------------------------ | ------------- | ------ | ----------------------- | -------------------- |
|
||||
| Linkding | 182 s | 9 | 66 | 8 (7 / 1) | 0 | passed | 9/9 / 8/9 | 0/3 / 0/3 |
|
||||
| Grocy | 253 s | 7 | 154 | 22 (16 / 0) | 6 | passed | 10/11 / 10/11 | 3/3 / 3/3 |
|
||||
| Homebox | 391 s | 9 | 268 | 13 (11 / 2) | 0 | passed | 9/9 / 9/9 | 0/2 / 0/2 |
|
||||
| Directus | 202 s | 7 | 100 | 25 (16 / 4) | 5 | passed | 12/12 / 11/12 | 2/2 / 2/2 \* |
|
||||
| Grafana | 143 s | 4 | 100 | 15 (12 / 2) | 1 | passed | 5/5 / 5/5 | 2/2 / 2/2 |
|
||||
|
||||
\* The Directus write eval checks that the state holds exactly the provisions the scripted recording read (2); the
|
||||
agent's recording read all 5, so its count checks fail although every field check passes (0/2 with both models). With
|
||||
the counts relative to the state's own provisions it passes 2/2 with both.
|
||||
|
||||
- Write tasks passed exactly when the build served their tool, with both models.
|
||||
- The skill loaded unprompted in every run. All five agents signed in through the form with the declared secret,
|
||||
recorded the API with request steps, checked coverage, stopped by the withheld reasons and exported with
|
||||
`export_environment_bundle`; each reported the credential-named warning pointers, and none published anything.
|
||||
- The scripted recordings the published environments were built from, built with this branch, read more (11, 39, 21,
|
||||
31 and 35 state-backed reads) and serve 7, 3, 2, 2 and 0 writes; the prompted recordings serve 0, 6, 0, 5 and 1.
|
||||
- Linkding's and Homebox's updates are withheld because a browser scenario carries no request times: the state learns
|
||||
no clock, so an update the application stamps with a modification time is `unexplained-change`. Linkding's scripted
|
||||
HAR serves the same PATCH with a clock rule. The coverage view now says so; recording request times on scenario
|
||||
network events would lift it. Linkding derives each bookmark's archive URL from its creation time, so its create is
|
||||
`contradicted` in both recordings.
|
||||
|
||||
Earlier rounds: in the first, two agents hung on steps without `timeout_ms` and most guessed the scenario schema, so the
|
||||
reference now starts from a whole scenario with a timeout on every step; the second (same five apps, before the review
|
||||
fixes) served 1, 6, 0, 5 and 0 writes with the same eval pattern.
|
||||
|
||||
## Review
|
||||
|
||||
Two independent reviews tried to refute the change.
|
||||
|
||||
- The first found a 302 that took a request step to another origin, page values left unredacted under a repeated or
|
||||
colliding header label, short page values that rewrote ids and hosts across the capture, `User-Agent` accepted but
|
||||
dropped by Chrome, a request that could still be sent after its step timed out, an origin check separated from the
|
||||
send, a literal query re-encoded, line breaks accepted in header values, and CLI wording in MCP refusals. All are
|
||||
fixed and tested; redirects are now checked in real Chrome.
|
||||
- The second confirmed those fixes and found query entries mishandled after a path ending in `?` or `#`, 3xx expected
|
||||
statuses that can never match, and padded stored values escaping redaction (fixed), plus the body cost of reading a
|
||||
page value, short values kept in plain text and the MCP dry run checking its directory (documented). In the
|
||||
prompted captures, only static assets lost bodies to the size limits.
|
||||
@@ -24,7 +24,7 @@ the line recorded, from the collection's initial entities, explains it:
|
||||
nothing else matched); an empty term matches everything, and a term that matched no field leaves the parameter inert
|
||||
until another line's term does;
|
||||
- `sort` by the field the value names, with `-` or an `asc`/`desc` suffix, and `direction` for a separate `asc`/`desc`
|
||||
parameter: numbers by value, text ignoring case, null last ascending, ties (case-only differences included) in state
|
||||
(or `ascending`/`descending`) parameter: numbers by value, text ignoring case, null last ascending, ties (case-only differences included) in state
|
||||
order; an empty selection needs no sort;
|
||||
- `limit`, `offset` and `page` (counted from 1 or 0 only when the line distinguishes them) for paging; zero or a negative limit
|
||||
lists every match;
|
||||
@@ -39,15 +39,21 @@ Query totals retain their numeric or canonical decimal-string type. Unknown or d
|
||||
`state.source` distinguishes a computed response from recording replay; `replay.exact_match` describes only the
|
||||
retained source envelope and can be false for a correctly computed new query.
|
||||
|
||||
Parameter names decide which roles are tried (`sort` for `orderBy`, `search` for `q`), and any parameter may be a
|
||||
filter or inert. No two parameters of one call take the same `sort`, `direction` or paging role: the answer would
|
||||
Parameter names decide which roles are tried (`sort` for `orderBy`, `search` for `q`), and any other parameter may be a
|
||||
filter or inert. A name asking for an order in any common spelling (`_sort`, `sort[]`, `sort[0][field]`, `sorters[...]`,
|
||||
`sort-column`, `sortKey`, `orderBy`) is only a `sort`; a direction name (`_order`, `sortDirection`, `dir`) given a direction
|
||||
is only a `direction`, and given anything else is an ordinary parameter; `reverse` is never inert unless false. The same
|
||||
vocabulary decides which lines set a collection's initial order (see the state view). No two parameters of one call take the same `sort`, `direction` or paging role: the answer would
|
||||
depend on which applied last, and serving supplies a call's values in name order rather than as recorded, so such a
|
||||
combination explains no line and such a call replays its recording. A line with more than 12 query parameters is left
|
||||
unexplained, which bounds the search; names such as `__proto__` are kept as the query's own members. The lines' roles
|
||||
merge: lines that disagree drop the parameter, inert values gather, search fields unite. The merged query keeps the
|
||||
merge: lines that disagree drop the parameter, inert values gather, search fields unite. A filter on a field not
|
||||
named like its parameter (`shelf`, or `shelf_id`, for `shelf`) can match by coincidence, so it stands only when lines
|
||||
giving the parameter two different values agree on it; otherwise the parameter takes no role. The merged query keeps the
|
||||
lines it reproduces, envelope and fields included; any other line keeps its recorded members. The view's `query` names
|
||||
the roles, those lines, and the envelope members that count every match before paging (`totals`); a `number`-of-items
|
||||
member such as `numberOfElements` counts the page.
|
||||
the roles, those lines, and the envelope members that count every match before paging (`totals`), top-level or one
|
||||
level down in a paging object (`/pageInfo/totalRows`); a `number`-of-items member such as `numberOfElements` counts the
|
||||
page.
|
||||
|
||||
## Serving and the write gate
|
||||
|
||||
|
||||
@@ -61,7 +61,8 @@ change.
|
||||
|
||||
- No new browser action: scenarios still cover what the UI requests plus GET
|
||||
reads through `goto`. A fetch or script action would be a new effect and
|
||||
needs its own scope decision.
|
||||
needs its own scope decision. (The `request` action was later scoped and
|
||||
added by [environment-prompt](../environment-prompt/spec.md).)
|
||||
- No change to what the scenario redacts. Values the application returns in
|
||||
response bodies are retained, as they are in HAR captures.
|
||||
- The api-surface view keeps HAR parents only.
|
||||
@@ -0,0 +1,22 @@
|
||||
# Plan
|
||||
|
||||
1. Schema: optional `observed_at` (ISO date-time) on `request` events, and
|
||||
`started_at` (ISO date-time) and `elapsed_ms` (non-negative number) on
|
||||
`request-finished` and `request-failed` events.
|
||||
2. Collector: stamp `observed_at` when a request is observed and copy the
|
||||
browser's `timing().startTime` and `responseEnd` into `started_at` and
|
||||
`elapsed_ms` when it reports them, admitting the strings with the other
|
||||
metadata.
|
||||
3. Records: index each transaction's single finished or failed start and
|
||||
duration and give each attributable record `startedDateTime` and `time`;
|
||||
add a limitation when any record is timed.
|
||||
4. Comparison: drop both fields from network evidence before fingerprinting and
|
||||
commit the rule in the built-in list and the comparison limitation.
|
||||
5. Docs: the scenario contract's network evidence and the environment docs'
|
||||
browser scenario section.
|
||||
6. Tests: the collector stamps both fields, records take them, the state learns
|
||||
the HAR's clock and verdicts from a timed scenario and none from an untimed
|
||||
or partly untimed one, a request that never ended or ended twice falls back
|
||||
to its observation, comparisons ignore the times (also against an untimed
|
||||
capture), and the real-Chrome network lane checks every request is observed
|
||||
and every finished request carries the browser's start and duration.
|
||||
@@ -0,0 +1,44 @@
|
||||
# Time browser scenario records
|
||||
|
||||
## Outcome
|
||||
|
||||
Browser scenario network events record no times, so every record a scenario
|
||||
projects is untimed. The environment-state view then orders records by
|
||||
position, detects no overlapping requests and learns no write clock: an update
|
||||
whose response carries a modification time the application sets is withheld as
|
||||
`unexplained-change` however it is recorded, while a HAR of the same session
|
||||
serves it with a clock rule.
|
||||
|
||||
Scenario network events now record when each request was observed and how long
|
||||
the browser took, and scenario records carry them as HAR entries do, so a
|
||||
scenario capture learns the clock a HAR does.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Each `request` event carries `observed_at`, the ISO wall-clock time the
|
||||
provider observed the request start; Playwright reports the browser's start
|
||||
only once a request ends.
|
||||
- Each `request-finished` and `request-failed` event carries `started_at`, the
|
||||
browser's wall-clock start (`timing().startTime > 0`), and `elapsed_ms`, its
|
||||
time from that start to the end of the response (`timing().responseEnd >= 0`),
|
||||
when the browser reports them.
|
||||
- The fields are optional in the schema, so Evidence captured before them still
|
||||
parses and is read exactly as before. REA versions before them refuse
|
||||
Evidence that carries them.
|
||||
- Scenario records take `startedDateTime` from the transaction's single
|
||||
finished or failed event's `started_at`, else from `observed_at`, and `time`
|
||||
from its `elapsed_ms` (0 without one), and say so in a limitation; a capture
|
||||
whose requests are all timed gets the recorded-start-time timeline and a
|
||||
write clock.
|
||||
- Scenario comparisons ignore both fields, as a committed built-in rule
|
||||
(`ignore_network_request_timing`).
|
||||
- The added metadata is charged to the event budgets as other metadata is.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- No change to HAR captures, to how the state uses times, or to what a
|
||||
record's timing means for overlap or clock rules.
|
||||
- No retroactive timing of captures made before this change.
|
||||
- No browser start for a request that never ended: its record starts at
|
||||
`observed_at`, which can trail the browser's start by tens of milliseconds
|
||||
while the provider reads other responses, with no duration.
|
||||
@@ -0,0 +1,13 @@
|
||||
# Tasks
|
||||
|
||||
- [x] Record the outcome, requirements and non-goals.
|
||||
- [x] Add the optional timing fields to scenario network events.
|
||||
- [x] Stamp them in the Playwright network collector.
|
||||
- [x] Time scenario records from them.
|
||||
- [x] Leave them out of scenario comparisons.
|
||||
- [x] Document the fields and the timed records.
|
||||
- [x] Add unit, view and real-browser checks.
|
||||
- [x] Run the gates.
|
||||
- [x] Re-record stale scenario environments and compare them with their published versions.
|
||||
- [x] Build prompt-recorded environments with and without request times.
|
||||
- [x] Address the independent review.
|
||||
@@ -0,0 +1,73 @@
|
||||
# Verification
|
||||
|
||||
Executed on macOS with Node v24.22.1 at `feat/scenario-request-timing` b92a11b6 (on main d87e73f2), and on Ubuntu 24.04
|
||||
VMs with snap Chromium 155 for the recordings.
|
||||
|
||||
## Gates
|
||||
|
||||
- `npm run -s typecheck`, `lint`, `format:check`, `docs:check`, `mcp-catalog:check`, `verify:test-discovery`,
|
||||
`scan:todos` and `npx knip`: passed.
|
||||
- `npx vitest run --project domain --project services --project adapters`: 16,380 passed and 1 failed, "stops Inspector
|
||||
target authorization after the current stat settles", which fails the same way on main in this environment.
|
||||
- Browser and scenario MCP and CLI boundaries, tool schema validity and the analysis-view MCP boundary: passed.
|
||||
- `npm run -s verify:browser:network` in real Chrome: every one of the 10 requests carries `observed_at`, and every
|
||||
finished request carries the browser's `started_at` and `elapsed_ms` (9 of 10; the tenth is the fixture's deliberately
|
||||
unfinished stream).
|
||||
- Captures made before this change parse and project exactly as before: the published Pinry (568 requests), PhotoPrism
|
||||
(277) and Lychee (134) captures give byte-identical manifest and state views, Evidence ids and digests included, on
|
||||
main and on this branch.
|
||||
|
||||
## The same capture with and without request times
|
||||
|
||||
Each capture below was recorded with this branch, then built twice: as recorded, and with its request times removed and
|
||||
the Evidence sealed again as the provider seals it. The difference is this change alone.
|
||||
|
||||
| Capture | Records | Timeline without / with times | Writes served without / with times |
|
||||
| ---------------------------------------------- | ------- | ----------------------------- | ---------------------------------- |
|
||||
| Linkding, agent-recorded from a prompt | 60 | record order / start time | 1 / 4 |
|
||||
| Linkding, agent-recorded from a prompt (again) | 65 | record order / start time | 3 / 3 |
|
||||
| Homebox, agent-recorded from a prompt | 263 | record order / start time | 2 / 3 |
|
||||
| Homebox, agent-recorded from a prompt (again) | 275 | record order / start time | 2 / 2 |
|
||||
| Pinry, its published scenario re-recorded | 568 | record order / start time | 0 / 0 (1 clock rule learned) |
|
||||
| PhotoPrism, its published scenario re-recorded | 273 | record order / start time | 2 / 2 (2 clock rules learned) |
|
||||
|
||||
- With times, Linkding's bookmark and bundle edits and Homebox's tag edit are served: their responses carry a
|
||||
modification time the application sets, which only a clock explains. PhotoPrism's served album create now stamps
|
||||
`CreatedAt` and `UpdatedAt` from the clock instead of replaying the recorded values. No capture served fewer writes.
|
||||
- The second Linkding and Homebox recordings gain nothing because their gaps are elsewhere (`unconfirmed` and `contradicted`
|
||||
writes): an agent's recording choices move coverage more than timing does.
|
||||
- The prompt-built recordings used a local, unpushed build of this branch merged with the prompt PR (#6946), which adds
|
||||
the `request` scenario action they need. Claude Code (`claude-sonnet-5-5`) recorded each app from a one-paragraph
|
||||
prompt, as in that PR's end-to-end check.
|
||||
- The Linkding bundle with four served writes passes all three of the application's write tasks with
|
||||
`fireworks_ai/gpt-oss-120b` and `fireworks_ai/glm-5p3-flash` (with the tasks' entity counts taken relative to the
|
||||
bundle's own state, which holds active and archived bookmarks as two types); the earlier prompt-built Linkding bundles,
|
||||
recorded without times, passed none. The Homebox bundle passes both of its write tasks with gpt-oss and one with GLM
|
||||
(GLM deleted the wrong item). The final build's prompt-recorded bundles start and answer retrieval: Linkding
|
||||
passed its smoke task and 8/8 and 7/8 retrieval tasks, Homebox its smoke task and 3/3 and 3/3.
|
||||
|
||||
## Stale published environments
|
||||
|
||||
Pinry and PhotoPrism are the oldest published environments recorded as browser scenarios (version 0.1.0, replay only).
|
||||
Both were re-recorded with this branch from their published scenarios on fresh seeded instances and rebuilt with the
|
||||
publishing pipeline:
|
||||
|
||||
| App | Published 0.1.0 | Rebuilt with this branch |
|
||||
| ---------- | ------------------------------------------- | ---------------------------------------------------------------------------------- |
|
||||
| Pinry | 12 tools, replay, retrieval 6/6 and 6/6 | 12 tools, state and clock, no writes served; retrieval 6/6 and 4/6 |
|
||||
| PhotoPrism | 13 tools, replay, retrieval 10/10 and 10/10 | 14 tools, state and clock, album create and rename served; retrieval 8/10 and 5/10 |
|
||||
|
||||
Neither improves, so neither was republished. The retrieval drops do not come from timing: the timed and untimed states
|
||||
are identical in every view these tasks read. PhotoPrism's album list is answered from the state in name order while
|
||||
the recorded response that generated the task listed another album first; Pinry's two GLM misses are tool calls
|
||||
rejected for passing `limit` and `offset` as numbers, under the same tool schemas the published version had.
|
||||
|
||||
## Review
|
||||
|
||||
An independent review rebuilt the branch and tried to refute it. It confirmed byte-identical views for earlier captures,
|
||||
that comparisons with and without times compare alike, that each record's duration comes only from its own
|
||||
transaction, and that both fields are charged to the event budgets. Its findings are addressed: records now start at the
|
||||
browser's own start time rather than the provider's observation, which trailed it by up to 36 ms while other responses
|
||||
were read; the docs give the fallback's lag, that earlier REA versions refuse captures carrying the fields, and that the
|
||||
comparison's normalization digest changes; and tests cover the fallbacks, partly untimed captures and comparisons with
|
||||
untimed captures.
|
||||
@@ -45,8 +45,10 @@ tool, view kind, provider, network activity or write effect.
|
||||
value. Objects at the root or in one member keep precedence. `at` and
|
||||
`replaceAt` read and replace exactly these forms besides the root and one
|
||||
member, so the gate and renderers run unchanged.
|
||||
- An entity's state order is its earliest sighting on the timeline and it cites
|
||||
its records in timeline order, whichever plan observed it first.
|
||||
- An entity's state order is its place on the first whole line its collection's
|
||||
application order lists, else its earliest sighting on the timeline (see
|
||||
the state view); it cites its records in timeline order, whichever plan
|
||||
observed it first.
|
||||
- Each tool description reads `METHOD template; <returns>; recorded statuses
|
||||
…; replays retained records […]; evidence ev_…` after the untrusted-catalog
|
||||
warning. `<returns>` describes one level deep the first cited `2xx` record
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
# Implementation plan
|
||||
|
||||
1. **Read-only POSTs.** A module decides once per extraction which POST tools only read, used by the write filter,
|
||||
init cutoffs and the write simulation.
|
||||
2. **Adoption.** The write simulation tracks held entities and writes no built plan models, and takes an unseen
|
||||
entity at its first successful item read.
|
||||
3. **Linked creates.** A module links a POST's returned id to the state type it is first read under; the extraction
|
||||
cuts that type's initial window at the POST, and the create plan records the read's collection.
|
||||
4. **Rewrite cuts.** The merge reports the spans behind a type's rewrite; the extraction cuts the type's initial window
|
||||
at the earliest write within them and plans once more.
|
||||
5. **Variant lines.** A module classifies request lines by the members their objects show; plans drop variants, views
|
||||
name them with their query keys, and serving and the write gate replay calls that match.
|
||||
6. **Tests and docs.** Each step's tests fail on the step before; the state-view, state-writes, list-queries and
|
||||
write-coverage specs and the environment docs describe the new behaviour.
|
||||
@@ -0,0 +1,66 @@
|
||||
# Give more write tools a state target
|
||||
|
||||
Issue: https://github.com/morluto/rea/issues/4933
|
||||
|
||||
## Outcome
|
||||
|
||||
Across the 50 published capture-built environments, 91 of 195 write tools got no state target: the gate refused them
|
||||
before looking at their evidence, because their path named no state type, item or document. A diagnosis traced each to
|
||||
its cause in the recordings and the code. The five largest shared causes:
|
||||
|
||||
- **Read-only POSTs counted as writes.** A lookup, an RPC tunnel naming read operations, or a session refresh was
|
||||
planned as an unserved write and cut initial windows.
|
||||
- **Entities a write the gate does not model made.** A later read of such an entity failed its check instead of
|
||||
holding it, so writes to it stayed unobserved.
|
||||
- **Creates read under another path.** A create whose path is no state type (`POST /Playlists` read as `/Items/{Id}`)
|
||||
had no target, and its entity leaked into the initial state of the type it is read under.
|
||||
- **Types whose reads disagree across an unrelated write.** Every view of the type stayed replayed.
|
||||
- **Request lines that show entities in another form.** An extra query parameter that adds or drops members
|
||||
(`?counts=true`, `?expand=`, `?fields=`) failed the whole view.
|
||||
|
||||
## Behaviour
|
||||
|
||||
- **Read-only calls.** A POST is not a state write when its response repeats the read of its path that finished last
|
||||
before it began, with no write between, it tunnels only read operations, its last literal segment names a lookup and
|
||||
no write, or it renews a session; it is replayed. It stays a write when one of its calls was redirected or unanswered,
|
||||
or when a related read line changes across one of its calls, or finds its entity there on one side only, with no write
|
||||
but other read-only calls between; a read overlapping the call counts on neither side. Each response body compared is
|
||||
parsed once and kept only as its canonical digest, charged to the view's budget until the decision ends.
|
||||
- **Adopted entities.** A successful item read of an entity the gate's copy never held, after a write no built plan
|
||||
models or one redirected or unanswered, puts the entity into the copy within the view's budget; an entity a modelled
|
||||
write touched is never taken back.
|
||||
- **Linked creates.** A POST whose path names no state type becomes a create into the type whose item read first names
|
||||
an id its response returned, before any other tool's write, when the id is new: no read finished before it began
|
||||
showed it, whether an item read of the id under that type or collection whose body shows the item, a list of the type
|
||||
or a read of that collection. Its observation is a read of an id its response returned, in an envelope too. Serving
|
||||
creates in that read's collection, for the exemplar's path arguments only (segment by segment, in either spelling),
|
||||
and fills path fields with its exemplar's path values decoded once. A successful POST that returned an id a type's
|
||||
reads only show once it began ends that type's initial window: a read still running then may show it, and a list read
|
||||
shows its listed entities' own ids (identity-named, or a suffix-named field such as `projectId` distinct across two or
|
||||
more when no id-named field identifies them), not those they nest. A read at or after the write that ends the initial
|
||||
reads is not parsed for that cut, since it cannot show a new id.
|
||||
- **Rewrite cuts.** When a type's reads disagree across a write under another root, the type's initial window ends at
|
||||
the earliest write within the change and the state is extracted again. The earlier of this and the creation cut wins.
|
||||
- **Variant lines.** A read line that shows the same entities in another form is a variant: it leaves the view's checks,
|
||||
the entity observations (an entity's first sighting comes from the lines left) and the membership changes that cut a
|
||||
type's initial window, and the view names it with the query keys that pick it out (`projected_query_keys`, on item and
|
||||
list views). Beside a line showing whole entities, a list line asking for some fields only (a projection value other
|
||||
than `*`) is set aside before the identity proof the same way. A call matching those keys replays its recording, so it
|
||||
does not show served writes; a 400, 404 or 410 on such a line is still evidence. A call asking for some fields only
|
||||
replays unless every value it gives is `*` or one a checked line gave, and no replayed read gave it. The write gate
|
||||
skips exactly the successful reads serving replays, by the same decision. A filter role whose name matches no field
|
||||
needs two agreeing values. A tool whose lines would take more than 2^24 line pairs and entity lookups to compare
|
||||
pairwise keeps every line checked; otherwise lines are compared only with those showing one of the same entities,
|
||||
through an index charged to the budget while it is held. The base lines' queries are parsed once for every variant
|
||||
they key. An item line first recorded after the initial window is a variant too, judged against the lines left once
|
||||
variants are dropped: when it names a new shaping parameter and its object carries or lacks members theirs do not, or
|
||||
selects some fields and leaves out members they always show, and an item only a replayed line showed, which the state
|
||||
never started with and in whose type no served create has added an entity since, answers with its own recording.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Over the 50 published captures, write tools with no state target fall from 91 to 61 and served write tools rise from
|
||||
46 to 61, with none lost; every served write tool applies.
|
||||
- Read calls recorded before the first write that state serving answers keep matching their recordings; each newly
|
||||
state-backed view answers them as recorded, except where replay itself does not.
|
||||
- The Grafana and Mailpit environments no longer hold, in their initial state, entities their captures created.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Tasks
|
||||
|
||||
- [x] Keep read-only POSTs out of the write list.
|
||||
- [x] Take an entity a write no plan models made when a read first shows it.
|
||||
- [x] Plan a create into the type its returned id is read under, and cut that type's initial window.
|
||||
- [x] End a type's initial reads at the write its reads disagree across.
|
||||
- [x] Replay request lines that show entities in another form.
|
||||
- [x] Add tests that fail on the step before each change.
|
||||
- [x] Measure the 50 published captures, the served smoke and the serving of recorded reads after each step.
|
||||
- [x] Run static, formatting, duplication, documentation and test gates.
|
||||
@@ -0,0 +1,98 @@
|
||||
# Verification
|
||||
|
||||
Executed on macOS with Node v22.23.1, one change at a time on main, over the 50 published capture-built environments
|
||||
(each app's latest capture). The served smoke rebuilds each manifest with the tree under test and applies every served
|
||||
write tool; the serving check answers every recorded read made before the capture's first write through state serving
|
||||
and compares it with the recording. The serving check reads no records from the five browser-scenario captures (Art
|
||||
Institute collection, LoC photos, Lychee, PhotoPrism, Pinry), so its read counts cover 45 apps; their 41 views count
|
||||
among the state-backed views.
|
||||
|
||||
## Gates
|
||||
|
||||
- `npm run build:cached`, `npm run check:fast` (typecheck and lint, no new warnings in the changed files),
|
||||
`npm run format:check`, `npx knip`, `npm run scan:todos`, `npm run docs:check`, `npm run verify:test-discovery` and
|
||||
`npm run mcp-catalog:check`: passed.
|
||||
- `npm run jscpd`: 3.49% duplicated lines over 4074 files.
|
||||
- `npx vitest run --project domain --project services`: 8992 passed, 6 pre-existing skips, on main `ed069bb9`.
|
||||
- `npm run test:prepare`, then `npm run test:focused --` the environment serve and export CLI boundaries, the serve
|
||||
and served-writes MCP boundaries, the analysis-view CLI and MCP boundaries, the compact input schema boundary and
|
||||
tool schema validity: 8 files, 88 passed.
|
||||
|
||||
## Measurements
|
||||
|
||||
| Step | Write tools | Served | No state target | State-backed read views | Recorded reads matching |
|
||||
| --------------- | ----------- | ------ | --------------- | ----------------------- | ----------------------- |
|
||||
| main | 195 | 46 | 91 | 1,098 | 1,833 of 1,886 |
|
||||
| read-only POSTs | 189 | 46 | 84 | 1,104 | 1,911 of 1,964 |
|
||||
| adoption | 189 | 47 | 84 | 1,104 | 1,911 of 1,964 |
|
||||
| linked creates | 189 | 48 | 80 | 1,105 | 1,911 of 1,964 |
|
||||
| rewrite cuts | 189 | 51 | 77 | 1,110 | 1,922 of 1,975 |
|
||||
| variant lines | 189 | 61 | 61 | 1,150 | 2,068 of 2,126 |
|
||||
| review fixes | 189 | 61 | 61 | 1,151 | 2,075 of 2,133 |
|
||||
| third round | 189 | 61 | 62 | 1,151 | 2,075 of 2,133 |
|
||||
|
||||
The served smoke applies every served write tool at each step. No read view loses its state backing, and no served
|
||||
write tool is lost.
|
||||
|
||||
- **Read-only POSTs:** six tools leave the write list (Mattermost `members/ids`, Miniflux `discover`, NocoDB's two
|
||||
internal tunnels, Paperless `selection_data`, PocketBase `auth-refresh`); Paperless's notes create gains a target.
|
||||
Grafana's `query-history` stays a write. Nomad `jobs/statuses` repeats its GET, but its integers exceed JSON's
|
||||
exact range, so it stays a write.
|
||||
- **Adoption:** Grocy's product delete is served; Mealie's recipe delete moves from no observation to unconfirmed.
|
||||
- **Linked creates:** Jellyfin's item delete is served; its playlist create and item update, and Mailpit's send, gain
|
||||
targets. Grafana's `/api/search` and Mailpit's messages no longer hold the dashboard and message their captures
|
||||
created.
|
||||
- **Rewrite cuts:** Tandoor's recipe create, update and delete are served.
|
||||
- **Variant lines:** Baserow's row create, update and delete, Keycloak's user delete, Miniflux's category create and
|
||||
update, PocketBase's create, update and delete, and Vikunja's task delete are served. Ghost's post create and update,
|
||||
Keycloak's user update, Miniflux's category delete, n8n's tag create and Vikunja's task update gain targets.
|
||||
- **Review fixes:** no write verdict changes. A NocoDB records list whose `fields` line had rejected it becomes
|
||||
state-backed, and all 7 of its recorded reads match. Without its guard, a short id would cut 23 Tandoor views'
|
||||
initial windows at a `POST /api/view-log/` returning `{"id":1}`.
|
||||
The second round (the gate skipping exactly the reads serving replays, earlier reads vetoing a linked create, whole
|
||||
RPC batches, and releasing a discarded planning pass) changes no measurement.
|
||||
- **Third round:** Mailpit's send, a linked create that was never observed, loses its target: other writes (marking
|
||||
messages read, tagging) ran between it and the item read naming its id. No served write, read view or matching read
|
||||
changes.
|
||||
- **Fourth round:** no verdict, read view or recorded read changes. A purge of temporary files removed 32 of the local
|
||||
captures, so this round was measured on captures restored from the published datasets, byte-identical where a local
|
||||
copy survived; Baserow's, Grocy's and Keycloak's published captures predate the ones measured above. On that set the
|
||||
previous head and this one both give 187 write tools, 62 served (smoke 62 of 62), 1,151 views and 2,085 of 2,155
|
||||
recorded reads matching.
|
||||
- **Fifth round** (on main `6a34be41`): no verdict, read view or recorded read changes on the same restored captures,
|
||||
once the serving check passes a repeated query value as an array, as main now expects.
|
||||
- **Sixth round:** no verdict, read view or recorded read changes on the restored captures.
|
||||
- **Seventh round** (on main `96ea32b7`): WordPress's post create moves from side-effect to unconfirmed, still unserved:
|
||||
its only later read, `/wp-json/wp/v2/posts/22?context=edit`, shows the edit representation (`generated_slug`), so it
|
||||
is now replayed rather than checked. No served write, read view or recorded read changes.
|
||||
- **Eighth round** (on main `3e7e102a`): no verdict, read view or recorded read changes on the restored captures.
|
||||
- **Ninth round** (on main `b7ebccf8`): no verdict, read view, recorded read or session replay changes on the restored
|
||||
captures (187 write tools, 62 served, 1,151 views, 2,085 of 2,155 initial reads and 2,764 of 3,022 session reads
|
||||
matching).
|
||||
- **Tenth round** (on main `a2235b09`): no verdict, read view, recorded read or session replay changes on the restored
|
||||
captures.
|
||||
- **Eleventh round** (on main `2968d1e9`, performance review): variant lines compare only lines that share an entity,
|
||||
read-only decisions parse each body once and keep its digest, and the creation cut skips reads that cannot count.
|
||||
Every census, serving-check and session-replay row equals the previous head's. On a synthetic capture of a list and
|
||||
1,000 items read plainly and with `?expand=`, the variant pass falls from 401 ms to 2 ms and the state build from 659
|
||||
ms to 216 ms (Node v22.23.1).
|
||||
- **Twelfth round** (on main `d87e73f2`, second performance review): the write gate lists a type's collections only when
|
||||
the path's own collection holds no id, and the variant pass parses base lines once. Every census, serving-check and
|
||||
session-replay row equals the previous head's. The synthetic 1,000-item capture takes 259–264 ms against main's
|
||||
244–247 ms (378–397 ms before this round; Node v22.23.1, medians of seven warm runs). Over the 50 captures, the
|
||||
environment-state and environment-manifest views together take 2.96 s wall and 3.82 s CPU with a 540 MiB peak RSS,
|
||||
against main's 2.61 s, 3.41 s and 516 MiB (one Node v24.22.1 process per sweep, warm medians of three runs; the cold
|
||||
first run is within 2% of them); the environment-state view alone takes 2,093 ms against 1,791 ms, and its results
|
||||
grow from 3.69 MB to 3.84 MB. Agent tokens were not measured.
|
||||
|
||||
Of the 40 views variant lines make state-backed, 146 of 151 recorded reads before the first write match; the other five
|
||||
(Sentry projects) are replayed, and replay returns the first of several differing recordings, as before. A paged
|
||||
Paperless document list answers all five documents, a PocketBase item without `expand` answers without it, and a
|
||||
NetBox `site_id` filter learned from one line is not adopted.
|
||||
|
||||
## Not included
|
||||
|
||||
- Making a value that differs between two request lines volatile: it contradicts the spec's distinct query strings and
|
||||
made 11 recorded reads answer otherwise than replay.
|
||||
- Item actions (`/{type}/{id}/archive`), bulk writes at a collection path, templating literal ids by value, and
|
||||
envelope masking: each needs further recording evidence or a separate change.
|
||||
@@ -25,28 +25,78 @@ later increments.
|
||||
any start time is missing, and say which. Bound each type's state by the first
|
||||
write under its root (API base, version segments, one segment); a query
|
||||
`POST` is not a write, a read overlapping the write is left out, and a write
|
||||
whose URL was redacted bounds every type, with a limitation counting it.
|
||||
whose URL was redacted bounds every type, with a limitation counting it. A
|
||||
successful `POST` elsewhere bounds a type's state too when its response named
|
||||
an id (an identity member, or a bare or sole scalar of four characters or
|
||||
more) that the type's reads show only once it began: the `POST` made that
|
||||
entity, so it is not in the initial state. A read finished before the `POST`
|
||||
began shows what was there, and one still running may show its effect. A list
|
||||
read shows the ids its listed entities carry as their own identity members, an
|
||||
item read its path's id only when its body shows the item (a JSON `null` shows
|
||||
none), and
|
||||
across two or more of them, when no id-named field (`id`, `uuid`, …; not `key`,
|
||||
`slug` or `name`) identifies them, the first suffix-named field (`projectId`)
|
||||
distinct on each, so a foreign key beside an `id` is none of theirs, nor are the
|
||||
ids of entities they nest. An id shorter than four characters counts only
|
||||
when the type was read before the `POST` and an item read names it after.
|
||||
- Prove an item type's identity field from the requested path value its
|
||||
responses repeat; otherwise infer it from a fixed list of identity names that
|
||||
every listed item carries distinctly, which needs at least one listed item.
|
||||
An item read that asked for some fields only (`fields`, `fields[...]`,
|
||||
`select`, `$select`) and does not return the item is left out of the proof
|
||||
and of the view's checks; the view lists it in `projected_record_ordinals`,
|
||||
and serving replays any call to that tool that names a projection parameter
|
||||
for an entity the state holds. The write gate also leaves out any read that
|
||||
names one and leaves out a field its view requires.
|
||||
and of the view's checks; the view lists it in `projected_record_ordinals`.
|
||||
Beside a line showing whole entities, a list line asking for some fields only
|
||||
(a projection value other than `*`, which asks for all) is listed there too,
|
||||
and proves no identity or membership. So is an item line first recorded after
|
||||
the type's initial reads, judged against the lines left once variants are
|
||||
dropped: one that names a shaping parameter none of them named while its
|
||||
object carries or lacks members theirs do not, such as a later
|
||||
`?expand=shelf` read, or one that selects some fields and leaves out members
|
||||
they always show, such as a later `?fields=id,name` read. On a view with
|
||||
such replayed reads, serving replays a call naming a projection parameter for
|
||||
an entity the state holds unless every value it gives is `*` or one a checked
|
||||
line gave, and no replayed read gave it. The write gate leaves out exactly
|
||||
the successful reads serving replays, and any read that names one and leaves
|
||||
out a field its view requires, which serving would answer whole.
|
||||
- A request line of an item or list view is a representation variant when it
|
||||
shows an entity another line shows with other members, or names a parameter
|
||||
the base lines do not (paging aside) while its objects carry a member no base
|
||||
object carries or lack one every base object carries. Base lines are taken
|
||||
first: lines naming no such parameter, then lines asking for every field,
|
||||
then the line most others agree with. A variant leaves the view's checks, the
|
||||
entity observations and the membership changes that would end the type's
|
||||
initial reads when a query key tells it apart: a parameter only
|
||||
variants name, a value no base line gives a parameter, or a parameter every
|
||||
base line names that a variant leaves out. The view lists its latest
|
||||
recordings in `projected_record_ordinals` and the keys in
|
||||
`projected_query_keys`; serving replays a call matching a key with the reason
|
||||
`variant` (`projection` when it leaves out a projection parameter every base
|
||||
line names; a projection value is tested as above), so the
|
||||
answer is a recording and shows no served write. The write gate neither
|
||||
checks nor learns from a successful read serving replays; a 400, 404 or 410
|
||||
such a read answers is still the absence it checks.
|
||||
- A field every recording of a view carried is required: serving refuses an
|
||||
entity lacking it. Once a successful read the write gate checks, naming no
|
||||
projection parameter, shows the application leaves the field out of an entity
|
||||
the state holds (APIs that omit empty or false members), no view of the type
|
||||
requires it.
|
||||
Never treat an envelope that is itself an entity as a list.
|
||||
- A top-level UUID or clock member that differs on every repeat of a path's
|
||||
successful GET lines with no write between, and across the capture differed
|
||||
on at least two repeats and never stayed the same, is minted per response
|
||||
there (a request id). A view names it in `per_response_members` only when
|
||||
every concrete path the view answers independently proves it minted. A
|
||||
collection's proof does not establish that its item paths mint the same
|
||||
member. The shared envelope compares without these common members, and
|
||||
serving keeps their recorded values; an unproved envelope difference stays
|
||||
recorded rather than borrowing another path's value.
|
||||
- Merge observations into one entity per collection and identity: item views'
|
||||
latest values win over list views', differing views keep their own values,
|
||||
and a value that changed between repeats of one request line with no recorded
|
||||
write is volatile and keeps the latest; a change across a write under another
|
||||
root, including between two tools of the type, leaves every tool of the type
|
||||
recorded. Compare list membership, including empty lists, and field presence before selecting each request line's latest recording; a change across a write also leaves the type recorded. Different query strings remain distinct; omitted fields do not erase their earlier observations on other request lines.
|
||||
root, including between two tools of the type, ends the type's initial reads
|
||||
at the earliest write within the change, and the state is extracted again
|
||||
once; a type whose reads still disagree keeps every tool recorded. Compare list membership, including empty lists, and field presence before selecting each request line's latest recording; a change across a write ends the type's initial reads the same way. Different query strings remain distinct; omitted fields do not erase their earlier observations on other request lines.
|
||||
- An item or list view whose recordings always spell a clock field's instant
|
||||
otherwise than the entity's stored value (`Z` against `+00:00`, another
|
||||
separator or fraction width) names that spelling in `clock_formats`; a field
|
||||
@@ -56,9 +106,30 @@ later increments.
|
||||
under the view's separator, with its own fraction digits padded with zeros to
|
||||
the view's width and none dropped; an epoch spelling is computed from the
|
||||
instant.
|
||||
- An item or list view names in `sorted_arrays` the fields it lists as string
|
||||
arrays in code-point order whatever order they were written in (tags kept as
|
||||
a set). Only the write gate learns it. A field is a candidate when every
|
||||
initial entity shows it as a sorted string array or null, one with two
|
||||
distinct strings, and no read the gate counts has listed it unsorted with two
|
||||
distinct strings. It is learned from a counted read that fails with the
|
||||
stored order and passes with the field sorted, and only when that read lists
|
||||
a written array in an order that is neither the written one nor values the
|
||||
initial state held first, then the new ones as written (an application
|
||||
ordering by tag id or creation shows that order too). The stored value keeps
|
||||
the written order, so a write's own answer echoes it; every view of the type
|
||||
for which the field is still a candidate sorts it as well.
|
||||
- A collection's initial order is the order of the first line that lists every
|
||||
entity any initial read shows in it and names no sort, direction (`sort[]`,
|
||||
`_sort`, `sort-column`, `sortKey`, `orderBy` and like spellings) or random
|
||||
parameter (`random`, `rand`, `shuffle`, `seed`); a collection without such a
|
||||
line keeps its entities' earliest sightings.
|
||||
- A list has `all` membership only when no item-total envelope member (`total`,
|
||||
`count` and their compounds, not page counts) differs from the number of
|
||||
entities it lists and no `has_more`, `next` or next-page token is set.
|
||||
`count` and their compounds, not page counts), at the top level or in a
|
||||
top-level object beside the list such as `pageInfo.totalRows`, differs from
|
||||
the number of entities it lists and no `has_more`, `next` or next-page token
|
||||
is set. Such a member that equals the number listed is a counter; a nested
|
||||
one is named by its pointer (`/pageInfo/totalRows`), and members beside it
|
||||
such as `isLastPage` stay as recorded.
|
||||
- Keep an item or list plan only when it reproduces each request line's latest
|
||||
initial recording from the state, comparing JSON values without regard to
|
||||
member order; otherwise record the tool with a reason. Parse bodies only when
|
||||
@@ -68,7 +139,8 @@ later increments.
|
||||
semantics and write effects.
|
||||
- Charge the manifest's admission and grouping, every record line, every body
|
||||
as temporary bytes before decoding and parsing, and every kept value, within
|
||||
the existing 96 MiB budget.
|
||||
the existing 96 MiB budget. A planning pass that a rewrite cut discards
|
||||
releases its charges before the state is extracted again.
|
||||
- Read response bodies through one domain owner shared with replay, and parse
|
||||
exact JSON through the owner of the exact-number policy.
|
||||
|
||||
|
||||
@@ -31,9 +31,49 @@ a reset give the same state.
|
||||
The view adds two members to its result:
|
||||
|
||||
- `writes`: one plan per manifest tool whose method may change state
|
||||
(`changesState`);
|
||||
(`changesState`), less the `POST` tools the capture shows only reading (below);
|
||||
- `write_clock`: the instant the served clock starts from.
|
||||
|
||||
**Calls that only read.** A `POST` tool whose calls read state is no write: it
|
||||
gets no plan, stays a recorded view with the reason `query-body`, is served by
|
||||
replay, and its calls bound no initial-recording window and end no observation
|
||||
search. The capture shows it by the first of these that applies:
|
||||
|
||||
1. every successful call answers as the successful `GET` of its path that
|
||||
finished last before the call began, of those with no write between, did (a
|
||||
status lookup posting the jobs it names);
|
||||
2. every call names read operations only, in its body's `operation` or
|
||||
`operations[].operation`, else its query's `operation`, `op` or `action`
|
||||
(`batch` and similar only wrap them, in either place, so a call needs at
|
||||
least one other, and every `operations` entry must name one of its own, so
|
||||
an entry with no string operation or another container keeps the call a
|
||||
write); an operation reads when its words name one of `list`,
|
||||
`get`, `count`, `aggregate`, `info`, `search`, `find`, `read`, `query`,
|
||||
`schema`, `describe`, `fetch` or `lookup`, and none of `create`, `insert`,
|
||||
`update`, `modify`, `replace`, `delete`, `remove`, `upsert`, `add`, `set`,
|
||||
`save` and similar, so `findAndModify` and `findOneAndReplace` stay writes;
|
||||
3. the path's last literal segment has a query word as its last meaningful
|
||||
word, split on `_`, `-`, `.` and case and skipping trailing `data`, `info`
|
||||
and `results` (`search`, `query`, `list`, `find`, `lookup`, `count`,
|
||||
`aggregate`, `stats`, `ids`, `selection`, `discover`, …), and no write word:
|
||||
`selection_data` names a lookup, while `query-history` names a history,
|
||||
`create_lookup` a create and `selection_data/import` an import, and each
|
||||
stays a write;
|
||||
4. the path's last literal segment renews or opens a session: `auth-refresh`,
|
||||
`auth-with-password`, `login`, `logout`, `refresh` or `token`.
|
||||
|
||||
A tool stays a write when one of its calls was redirected or went unanswered,
|
||||
since nothing shows what it did. It also stays a write when a `GET` line whose
|
||||
path its call's path relates to (segment by segment, a parameter matching any
|
||||
value) reads differently just before and just after one of its calls, or finds
|
||||
its entity on one side only (a 400, 404 or 410 on the other), with no other
|
||||
write between; the other read-only tools' calls are no writes there, so the
|
||||
tools are dropped until none is vetoed. Those reads are the one that finished
|
||||
last before the call began, of those no other write follows, and the first that
|
||||
began after it ended, since one overlapping the call may show either state. Reads of unrelated paths do not
|
||||
count, so a session renewal stays read-only although an endpoint under the
|
||||
same root regenerates values on every read.
|
||||
|
||||
**Effects.** Each plan classifies its tool:
|
||||
|
||||
| Effect | Tool | Target |
|
||||
@@ -44,13 +84,85 @@ The view adds two members to its result:
|
||||
| `document` | `PUT`, `PATCH` or `POST` to a document view's path | that document |
|
||||
| `none` | anything else | reason `no-state-target` |
|
||||
|
||||
**Item actions.** A `POST`, `PUT` or `PATCH` to an item path plus one literal
|
||||
segment (`/{type}/{id}/archive`) is an `update` of the entity the item path
|
||||
names, recorded as `address: {by: "action", segment}`, when the segment names
|
||||
no collection (no state type ends in it, and it is not `delete`, `remove` or
|
||||
`destroy`) and every successful call answered nothing or that entity: never a
|
||||
201, and an object holding the id at the type's id field where an item read of
|
||||
the type shows its entity, with every field that read always shows. A call
|
||||
answering anything else made a sub-resource, as a comment `POST` does, and
|
||||
stays `none`. An action's unsent change of a scalar that no other rule
|
||||
explains takes the value its observation showed, a `set` rule applied on every
|
||||
call (`archived: true`); a changed object, list or instant has no rule, so the
|
||||
plan is `unexplained-change`. An action is served only when it sets something
|
||||
and a recorded call found every field it sets already at that value, since one
|
||||
change cannot tell a set from a toggle; otherwise it stays `unconfirmed`. Its
|
||||
call may send no body. An action is observed in its own response, or in a
|
||||
later item read only while no other tool's modelled write to the entity awaits
|
||||
a check: that read then checks the other write, and the action's call is one
|
||||
the gate does not model.
|
||||
|
||||
**Bulk writes.** A `DELETE`, `PUT` or `PATCH` at a type's
|
||||
`collection_template`, or a `POST` to it plus `delete`, `remove` or `destroy`,
|
||||
names its entities in its body: an array of ids of one JSON kind, or of
|
||||
objects carrying the type's `id_field`, at the root or as the body's one array
|
||||
member (`{"IDs": […], "Read": true}`, `[{"Id": 9}]`). Every successful call
|
||||
must name them the same way, recorded as `address: {by: "ids", member, kind}`
|
||||
or `{by: "elements", member}`. A path whose last segment is the type's
|
||||
singular or plural (`/messages` for `/message`) writes that type. An `ids`
|
||||
member applies the body's other members to every id, an element its own
|
||||
members; a root id array updates nothing. Each named entity gets the effect as
|
||||
an item call would, checked by the same reads; one the state does not hold
|
||||
leaves the call unmodelled there. A bulk update's observation must show the
|
||||
members the call sent. Serving answers any ids only when the exemplar's
|
||||
response fits: no body, a body naming none of the recorded ids and holding no
|
||||
number equal to how many it named (a count), or an array with one element per
|
||||
id, each showing it as the first does; otherwise the reason is
|
||||
`body-unusable`.
|
||||
|
||||
A `POST` whose path gives it no target is a `create` into the type its returned
|
||||
id is read under: its exemplar's response names an id (an identity member of the
|
||||
body or of an object member, or a scalar body or sole member of four characters
|
||||
or more), and the first later successful item read naming that id, whose body
|
||||
shows the item (a JSON `null` read is passed over), belongs to a state type. That read must come before any other tool's write, which may have
|
||||
made what it shows, as a publish call makes a note from a draft. The entity must
|
||||
be new: neither the initial state nor any read finished before the call began
|
||||
holds that id (one still running may show what the call made): an item read of
|
||||
it under the item read's type or collection whose body shows the item (a JSON
|
||||
`null` is an absence), a list read of its type, or any read of that collection, whether an
|
||||
item read of it, a list read of its type, or any read of the item read's
|
||||
collection, with or without a query, that lists it under an identity member of
|
||||
its own (a body with no list counts an identity member at any depth). An id shorter than four characters may be any type's,
|
||||
so it links only to a type a successful read showed before the call. The plan
|
||||
records that read's collection, and serving creates there, since the call's own
|
||||
path names no collection of the type. That collection holds only for the
|
||||
exemplar's path arguments, compared segment by segment, each as recorded or in
|
||||
the other spelling once percent-decoded: serving refuses a call with others, and the gate counts such a
|
||||
recorded call as a write no built plan models. Its path fields take the
|
||||
exemplar's path values decoded once, the source it accepts, whichever spelling
|
||||
the call sends. A linked create's call is
|
||||
observed only in a read of an id its response returned, at the top or in an
|
||||
envelope member, so another unseen item's read is never taken for it.
|
||||
|
||||
**Exemplar.** A plan is built from its first successful (2xx) recorded call,
|
||||
the exemplar.
|
||||
|
||||
- **Request body.** The exemplar's request body must be a JSON object that
|
||||
could enter the state: a JSON-like media type, complete UTF-8 text within
|
||||
256 KiB, exact numbers, no `__proto__` member. Otherwise the reason is
|
||||
`body-unusable`. A `DELETE` takes no body.
|
||||
`body-unusable`. A `DELETE` takes no body. A create's or update's body
|
||||
whose only member wraps one object in a one-element array (Ghost's
|
||||
`{"posts":[{...}]}`) is that object, and the plan records the member as
|
||||
`body.envelope`: serving takes only a body wrapped that way.
|
||||
- **Query.** Serving takes only the query parameters the exemplar sent, with
|
||||
its values, since they may change what the body does (Ghost reads `html`
|
||||
only with `?source=html`): a parameter a call leaves out takes the recorded
|
||||
value, as the recording sent it, and a call with another value or parameter
|
||||
is refused, a bulk call included. The gate treats a later recorded call sent
|
||||
with another query, or wrapped otherwise, as a write its plan does not
|
||||
explain: it brings the entity to what the call recorded, without
|
||||
attribution, and a bulk call leaves the entities it names unmodelled.
|
||||
- **The written entity.** The entity is observed in the exemplar's response,
|
||||
located by its identity value at the root, in one member, or in a
|
||||
one-element array, as item views locate it. When the response does not carry
|
||||
@@ -79,33 +191,64 @@ identity the client sends is an echo:
|
||||
classes.
|
||||
6. **Clock.** A timestamp within 10 minutes of the exemplar's start time. The
|
||||
format is kept: ISO-8601 with its separator, fraction digits and zone, or
|
||||
epoch seconds or milliseconds.
|
||||
epoch seconds or milliseconds. An object whose every clock lies between 1
|
||||
second before the start time (a whole second's truncation) and 2 seconds
|
||||
after it, in one format, is a nested clock when the type's other entities
|
||||
hold that field as objects agreeing with it in every other member and
|
||||
holding other clocks: served, those members take the write's clock and the
|
||||
others are kept. A reference to another entity, which differs by entity or
|
||||
was made before the request, is not one.
|
||||
7. **Sequence.** An integer one greater than the largest value of the field in
|
||||
the collection, else in the type. The integer may be written as `-`-separated
|
||||
digit groups of one width of at least two digits (an asset number `000-005`;
|
||||
not a date, version or address); a served value keeps the recorded value's
|
||||
groups and zero padding, and digits that outgrow them lead. A later call must
|
||||
record the value spelled that way.
|
||||
8. **Unique.** A UUID-shaped string that no other entity of the type shares.
|
||||
8. **Unique.** A UUID-shaped string that no other entity of the type shares,
|
||||
or an opaque token (16 to 64 letters, digits, `_` or `-`, with letters and
|
||||
digits both) that no other field of the entity repeats, where every other
|
||||
entity of the type holds a token of the same length and none this one.
|
||||
Serving generates a token of the same length, character classes and
|
||||
separator positions.
|
||||
9. **Template.** A string containing a generated value, or else a copied
|
||||
value, as a delimited token (for example a URL that ends in the new id or in
|
||||
a slug the call sent under another name). It is rebuilt around the new
|
||||
value. An echoed value is not a token, nor is a copy of one: it may recur in
|
||||
unrelated text. A copied member whose value also sits in text no template
|
||||
rebuilds around it (beside another source in one template, or in a constant)
|
||||
is accepted only with its recorded value.
|
||||
unrelated text. A copied or echoed member whose value also sits in text no
|
||||
template rebuilds around it (beside another source in one template, or in a
|
||||
constant) is accepted only with its recorded value.
|
||||
10. **Constant.** Otherwise the exemplar's value.
|
||||
|
||||
When a constant, or the text a template keeps, contains a path value of the
|
||||
exemplar's call as a delimited token, the create is served only for calls
|
||||
naming the exemplar's collection.
|
||||
|
||||
A constant may also derive from a member without holding its text, when the
|
||||
constant is named after the member: with a reference's `Id` or `_id` left off,
|
||||
one name's letters and digits begin the other's (`parentId` and `parentName`,
|
||||
`dateEndDate` and `dateEnd`), three or more of them. Such a member is accepted
|
||||
only with its recorded value when it names another entity the copy holds (by
|
||||
its id, among the types whose paths hold the member's name when any does; a
|
||||
value shorter than 8 characters only under a member named as a reference, such
|
||||
as `parentId` or `parent_id`) whose own string of 8 or more characters the
|
||||
constant repeats under another name, neither name reading as a reference; or
|
||||
when it sends a date or time that the constant's instant lies within two days
|
||||
of (an end date stored as a time in another zone).
|
||||
|
||||
**Body members of a create.** A member is either accepted or not:
|
||||
|
||||
- **Accepted.** An echoed member, a member copied whole into a field of another
|
||||
name and stored under none of its own, or the identity field's value. A
|
||||
member copied whole must have the JSON type of the field it is copied into.
|
||||
Every member the exemplar sent is required.
|
||||
- **Accepted only as recorded.** An echoed member naming the object the entity
|
||||
nests under the field it refers to (`collection_id` and a `collection`
|
||||
object), whose other members serving would keep as recorded; and a state
|
||||
word other fields go with: a lowercase word several entities share, where
|
||||
every entity in another state holds a field the new one leaves null, or the
|
||||
reverse (Ghost's `status: "draft"` beside `published_at: null`), unless the
|
||||
tool's recorded calls sent other values of it. Updates take a member naming
|
||||
a nested object only as recorded too.
|
||||
- **Not accepted.** A member the application stored with a different value
|
||||
(transformed), or one it did not show. A call that sends such a member is a
|
||||
tool error naming the accepted members.
|
||||
@@ -127,15 +270,46 @@ as sent in another letter case is the sent value, not a fresh one. A member a la
|
||||
which the plan's observation does not show, keeps the JSON type that call stored
|
||||
it as (the body's `kinds`), as an exemplar's member keeps the observation's.
|
||||
`PUT` requires every member the exemplar sent; `PATCH` and `POST` require at
|
||||
least one. A field the exemplar's update changed without sending it is
|
||||
explained as one of:
|
||||
least one. A sent clock the call left as it was, stored in whole seconds and
|
||||
naming the second the call ran in, is a `held-clock` the application stamps
|
||||
anew (Ghost's `updated_at`, which a client sends back as it read it), when it is
|
||||
the only such member the call sent: a call must send it as the entity holds it,
|
||||
or it is refused, and it is served as the write's clock. An unsent clock the
|
||||
call left as it was, stored in whole seconds and naming the second the call ran
|
||||
in, cannot show whether the update stamps it, unless it names when the entity
|
||||
was made (`createdAt`, `row_created_timestamp`): the plan stays `unconfirmed`
|
||||
until another call shows it stamped, and that call's clock rule then holds
|
||||
without the first call contradicting it. A field the exemplar's update changed
|
||||
without sending it is explained as one of:
|
||||
|
||||
- clock;
|
||||
- a nested clock: an object the entity held whose only changes are clocks
|
||||
within 10 minutes of the start time, in one format, where the type's other
|
||||
entities hold that field as objects agreeing in every other member. The gate
|
||||
stores the object the first later read of the entity shows when it differs
|
||||
from the write's only in those members, each within 2 seconds, as Metabase
|
||||
answers an update with one instant and stores another. Serving refuses it on
|
||||
an entity holding no such object;
|
||||
- an increment by one;
|
||||
- a slug of an echoed member;
|
||||
- `unique`: a UUID in place of another UUID, that no other entity of the type
|
||||
holds and the call sent nowhere in its body (a version the application assigns
|
||||
on every update);
|
||||
- a slug of an echoed member, judged before a token, since a renamed slug is
|
||||
spelled like one;
|
||||
- `unique`: a UUID in place of another UUID, or an opaque token in place of
|
||||
another of the same length, that no other entity of the type holds and the
|
||||
call sent nowhere in its body (a version the application assigns on every
|
||||
update);
|
||||
- `stamp`: the acting user on a field named `modified…by`, `updated…by`,
|
||||
`edited…by` or `changed…by` (or `last…`), stored on every call, when the
|
||||
entity already held the value under its `created…by` counterpart
|
||||
(`modifiedByName` and `createdByName`), and the call sent no member naming
|
||||
the same thing (`modifiedById`). The other `…by` field naming the same user
|
||||
(`modifiedById` beside `modifiedByName`) is stamped with it when the call
|
||||
showed it at its own `created…by` counterpart's value, even where the entity
|
||||
lacked it before;
|
||||
- `derived`: when the call sent exactly one member the entity stores nowhere,
|
||||
a value showing that member's text, markup aside (at least 8 characters): a
|
||||
field Ghost derives from the `html` it was sent. The member is accepted only
|
||||
with its recorded value, and a call sending it is served only on an entity
|
||||
holding the value the recorded call found (`from`), else refused;
|
||||
- `renewed`: an array or object whose only changes are UUIDs replaced by ones
|
||||
that neither it nor another entity of the type held, as child rows an update
|
||||
rewrites are. The rule names the pointers it renewed at (`*` for any array
|
||||
@@ -146,7 +320,7 @@ explained as one of:
|
||||
|
||||
A field the entity lacked before is a change too when the view that observed
|
||||
the update had shown the entity, so a field the application fills in on update
|
||||
follows its rule. Any other change is `unexplained-change`. An increment or a slug applies to
|
||||
follows its rule. Any other change is `unexplained-change`. An increment, a slug, a stamp or a derived value applies to
|
||||
every call that could take it, and `unique` and `renewed` to every call, so the
|
||||
plan is also `unexplained-change` when such a rule would give a call of the
|
||||
tool another value than the one it recorded, a recorded call kept a `unique` or
|
||||
@@ -183,7 +357,13 @@ and the state is left unchanged.
|
||||
collection's order: sorted by the identity field or a clock field (ascending
|
||||
or descending), `first` or `last`. The rule is the first candidate consistent
|
||||
with both the initial `all`-membership recordings and the position a later
|
||||
recorded list shows. With no evidence, the rule is `last`.
|
||||
recorded list shows. With no evidence, the rule is `last`. A sort by a
|
||||
random identity (version 4 UUIDs, or generated ids every creation clock lists
|
||||
in another order) is a candidate only after `last`: the recorded order by it is
|
||||
a coincidence until a list shows a create placed by it; time-ordered ids
|
||||
(ObjectId, ULID, TSID, version 7 UUIDs) keep it. When the sorts the recorded
|
||||
order admits would place the created entity differently, none is claimed
|
||||
before `last` until a later list settles it.
|
||||
|
||||
## The gate
|
||||
|
||||
@@ -228,8 +408,24 @@ unknown. Writes that changed it since its last check are checked only on the
|
||||
members they sent, less those the view treats as volatile, which show nothing
|
||||
of a write.
|
||||
|
||||
A write no built plan models can also make an entity the copy never held, such
|
||||
as a row an import or a nested create added: a write of a tool with no create,
|
||||
update, delete or document plan, a call of a tool whose plan was never built, a
|
||||
linked create's call that serving would refuse, or any write redirected or left
|
||||
unanswered.
|
||||
A successful item read of an entity the copy has never held (no initial entity,
|
||||
and none a modelled write created, changed or removed) that names it by the
|
||||
type's identity, when such a write ran since that entity or its collection was
|
||||
last checked, shows that entity: the copy takes its recorded values instead of
|
||||
failing the read, and later writes to it are modelled and checked as usual. The
|
||||
taken entity counts against the view's budget as a created one does. An
|
||||
entity a modelled write touched is never taken back this way, and a built plan's
|
||||
call that serving would not apply, such as a create outside its tied
|
||||
collection, keeps its evidence.
|
||||
|
||||
**Reads.** A read is checked when the served environment would answer it
|
||||
from the state:
|
||||
from the state (an item, list or document read compares without the view's
|
||||
`per_response_members`):
|
||||
|
||||
- an item read of a state-backed item view, of the entity serving would name:
|
||||
in a held collection the read's path matches, each segment verbatim or either
|
||||
@@ -293,12 +489,40 @@ refuses to answer with.
|
||||
does not excuse a newer write the list shows undone. An item read checks the writes an unmodelled
|
||||
write did follow only on the members they sent, and a list with such a write
|
||||
is not checked again: the unmodelled write may explain the rest.
|
||||
- A failed item read with no such unmodelled write contradicts the writes that
|
||||
changed the whole entity (its create or delete). When one of them is
|
||||
exercised, each exercised update is checked instead on the fields its effect
|
||||
holds, and confirmed when those show as the copy holds them and its latest
|
||||
call's response shows every other field it and the read both show (but
|
||||
volatile ones and those other updates wrote) as the read does: serving
|
||||
answers an update from the copy, so a response that shows the entity
|
||||
otherwise would be answered wrongly. A field the copy lacks that the read and
|
||||
an exercised update's response both show, with the same value other than
|
||||
null, is that update's change: an update whose effect does not hold it is
|
||||
neither confirmed nor contradicted by the read, and when such changes are
|
||||
the read's whole difference the entity's own writer is not contradicted.
|
||||
When the read differs on a field the copy holds that no exercised update
|
||||
wrote, any of the writes may have caused it, and each is contradicted.
|
||||
- A failed item read whose field newly embeds an entity a create made (an
|
||||
object in the field, or within it, naming it by its id and by another of its
|
||||
strings of 3 or more characters, 8 or more when the id is shorter than 8),
|
||||
which the copy's value lacks, contradicts that create: serving would not show
|
||||
the change it made there.
|
||||
- A mismatch on an entity or collection that no write changed contradicts,
|
||||
as `side-effect`, the modelled writes since that previous check whose paths
|
||||
are segment-prefix related to the read's path.
|
||||
are segment-prefix related to the read's path. When a refused write's
|
||||
recorded outcome since then left the entity lacking a field every recording
|
||||
of its view carried, the create that made it is contradicted too: an outcome
|
||||
merges only what its answer showed.
|
||||
- After a failed item check, the copy takes the read's recorded values (or
|
||||
drops the entity on a recorded absence). A list whose check failed is not
|
||||
checked again.
|
||||
- A failed item or list read the gate counts passes when the view lists some
|
||||
string-array fields sorted and its order rules out the written one and the
|
||||
order the values were first held in (see `sorted_arrays` in the state view);
|
||||
the type's views keep the fewest such fields the read needs, and the read
|
||||
checks the writes it exercises. A counted read listing such a field unsorted
|
||||
rules it out for its view.
|
||||
- A list that fails only for where one create placed its entity passes when
|
||||
another of that create's insert candidates reproduces it, which then
|
||||
becomes the plan's rule, unless an earlier list check relied on the rule
|
||||
@@ -331,7 +555,20 @@ served. Their descriptions say the tool:
|
||||
- applies its effect to the served state;
|
||||
- names its target type;
|
||||
- lists its required and accepted body members, quoted and sampled within the
|
||||
description budget as response fields are.
|
||||
description budget as response fields are, the members it accepts only with
|
||||
their recorded value, with that value when its JSON text is 120 characters
|
||||
or less, and the envelope a body wraps its object in;
|
||||
- names the query its recording sent.
|
||||
|
||||
The input schema says the same: each query parameter the recording sent is
|
||||
optional, defaulting at execution to its recorded value, with a nonempty value
|
||||
as the only `enum` member; an empty value is described and enforced at execution
|
||||
because some clients reject empty literals. A body that wraps its
|
||||
object requires that member, an array of one object; and a member accepted
|
||||
only with its recorded value carries that value as `const` when it is short
|
||||
and neither a boolean nor an empty string (some clients reject these literals), else a description
|
||||
saying it must equal the recorded value. A refused member's message names the
|
||||
recorded value the same way.
|
||||
|
||||
The discovery budget charges them. `--replay-only` and the replay fallback are
|
||||
unchanged.
|
||||
@@ -414,7 +651,18 @@ covers its arguments; otherwise it keeps the recorded page members.
|
||||
|
||||
**Provenance.** Write answers carry `state: {source: "state", view: "create" |
|
||||
"update" | "delete", type, collection, id}`, or `{source: "state", view:
|
||||
"document-write", path}`.
|
||||
"document-write", path}`. A bulk answer adds `ids`, every entity it wrote in
|
||||
body order, `id` naming the first.
|
||||
|
||||
**Bulk and action calls.** A served bulk tool takes its body as recorded (an
|
||||
array of objects or of ids of the recorded kind, or an object), a `DELETE`
|
||||
included, and `environment-compare` sends a probe's body to it; every id must
|
||||
name an entity the state holds, else the call is refused and the state is
|
||||
unchanged. A bulk
|
||||
update with a `unique` or `renewed` rule writes one entity per call, since one
|
||||
call draws those values once. A bulk write changes or removes its entities in
|
||||
one step, so a call the state cannot hold changes none of them. A served item action's path names its entity
|
||||
before the action segment.
|
||||
|
||||
**Data plane and export.**
|
||||
|
||||
|
||||
@@ -31,11 +31,16 @@ what the writes did:
|
||||
is left out of the identity proof and the view's checks. The view lists it in `projected_record_ordinals`, and serving
|
||||
replays a call to that tool naming such a parameter, for an entity the state holds, with the reason `projection`;
|
||||
the replay shows the recording, not served writes. The write gate neither checks nor learns a write's effect from a
|
||||
successful read that names such a parameter and leaves out a field its view requires; a 400, 404 or 410 such a read
|
||||
answers is still the absence it checks.
|
||||
successful read serving replays, nor from one that names such a parameter and leaves out a field its view requires; a
|
||||
400, 404 or 410 such a read answers is still the absence it checks.
|
||||
Identity-free projection evidence after the initial-state cutoff is retained too, without seeding later values
|
||||
into initial entities. Failed responses are classified before the projection-replay shortcut, so a projected
|
||||
absence can confirm a delete or contradict an unexplained disappearance.
|
||||
A list line asking for some fields only beside one showing whole entities is replayed the same way and proves no
|
||||
identity or membership; an item or list line showing its entities in another representation (an expanding or
|
||||
reducing query) is replayed when a query key tells it from the view's other lines (`projected_query_keys`, reason
|
||||
`variant`). A call asking for some fields only replays unless every value it gives is `*` or one a checked line
|
||||
gave, and no replayed read gave it; such calls replay recordings and do not show served writes.
|
||||
- **Sequences.** A sequence value may be `-`-separated digit groups of one width of at least two digits, not a date,
|
||||
version or address. The next value keeps the exemplar's groups and zero padding; digits that outgrow them lead. A
|
||||
later create must record its value spelled that way. A held value whose digits outgrew the mask (`100-00` after
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
# Implementation plan
|
||||
|
||||
1. **Defaults.** `WriteBody.defaults` and its schema; a create's echo of a member a call leaves out takes its default.
|
||||
2. **Merging.** Explain a later create on its own and merge it: agreeing rules, references one call shows alone, joined
|
||||
bodies and defaults, the plan's rule order.
|
||||
3. **Sorted echoes.** Learn `sorted` for creates and updates, store sorted strings when serving, and agree plain and
|
||||
sorted echoes in update and create plans.
|
||||
4. **References.** A references module that learns and resolves them; created and updated fields resolve them against
|
||||
the replayed or live state; the members they read are accepted.
|
||||
5. **Nested view keys.** The gate's view spelling learner, moved to its own module, notes object keys; rendering
|
||||
applies them.
|
||||
6. **Schema, tests and docs.**
|
||||
Loaded 100 of 1405 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user