111 lines
5.0 KiB
Markdown
111 lines
5.0 KiB
Markdown
# Passive Node and Electron runtime observation
|
|
|
|
REA can attach to an already-running Node.js or Electron V8 Inspector target
|
|
and retain script-load and execution-context metadata. The
|
|
`list_javascript_runtime_targets` and `observe_javascript_runtime` MCP tools
|
|
have equivalent `rea list-javascript-runtime-targets` and
|
|
`rea observe-javascript-runtime` commands. Successful calls return
|
|
deterministic Evidence.
|
|
|
|
This authority is disabled by default and is separate from browser CDP,
|
|
Electron file-page inspection, Process Capture, and controlled JavaScript
|
|
replay:
|
|
|
|
```bash
|
|
export REA_V8_INSPECTOR_OBSERVE_ENABLED=true
|
|
export REA_V8_INSPECTOR_ENDPOINTS_JSON='["http://127.0.0.1:9229"]'
|
|
export REA_V8_INSPECTOR_FILE_ROOTS_JSON='["/absolute/path/to/app"]'
|
|
export REA_V8_INSPECTOR_ALLOWED_ORIGINS_JSON='[]'
|
|
|
|
rea list-javascript-runtime-targets http://127.0.0.1:9229 \
|
|
--json
|
|
rea observe-javascript-runtime http://127.0.0.1:9229 TARGET_ID \
|
|
--runtime-kind node --json
|
|
```
|
|
|
|
At least one canonical file root or exact HTTP(S) origin is required.
|
|
Discovery is restricted to a literal-loopback HTTP endpoint. A target must
|
|
match the exact requested target ID, expose a same-port WebSocket reported by
|
|
the approved discovery endpoint, and remain inside the requested file or
|
|
origin scope. Targets already marked attached are rejected rather than
|
|
displacing another debugger. Canonical file paths are checked after symlink resolution.
|
|
Excluded locations are counted but never retained.
|
|
|
|
`list_javascript_runtime_targets` returns every approved target in one inline
|
|
array. The Inspector discovery response-size ceiling remains internal; an
|
|
oversized response fails explicitly.
|
|
|
|
For the MCP follow-up call, pass the discovery Evidence ID and selected target
|
|
ID to `observe_javascript_runtime`. REA reuses the endpoint and file/origin
|
|
scope from that retained discovery Evidence, checks the selected ID against its
|
|
target list, and reapplies permission policy. The agent does not repeat roots or
|
|
origins. The CLI continues to accept its endpoint and scope arguments directly.
|
|
|
|
## Passive protocol boundary
|
|
|
|
The provider sends exactly two protocol commands:
|
|
|
|
- `Runtime.enable`
|
|
- `Debugger.enable`
|
|
|
|
It never sends `Runtime.evaluate`, reads script source, installs breakpoints,
|
|
pauses or resumes execution, calls `Runtime.runIfWaitingForDebugger`, launches
|
|
the target, instruments JavaScript, or invokes Electron APIs. Closing a call
|
|
closes only REA's WebSocket.
|
|
|
|
The direct observations are:
|
|
|
|
- `Debugger.scriptParsed`, establishing that a bounded script location was
|
|
parsed in the observed execution context;
|
|
- `Debugger.scriptFailedToParse`, retained only as a bounded invalid-script
|
|
count;
|
|
- `Runtime.executionContextCreated`,
|
|
`Runtime.executionContextDestroyed`, and
|
|
`Runtime.executionContextsCleared`, establishing context lifecycle within
|
|
the capture window.
|
|
|
|
The Inspector protocol does not directly expose require/import caller edges,
|
|
EventEmitter emissions or listener invocation, Electron IPC messages or
|
|
handlers, or script-unload events. Those facts remain explicit unknowns.
|
|
`scriptParsed` proves script presence, not the importing module, feature
|
|
execution, initialization order, or causality.
|
|
|
|
## Node and Electron roles
|
|
|
|
The caller declares one role: `node`, `electron-main`, `electron-preload`, or
|
|
`electron-renderer`. Node and Electron-main declarations require a protocol
|
|
target of type `node`; preload and renderer declarations require `page`.
|
|
Inspector does not authenticate the operating-system PID or distinguish an
|
|
Electron role, so Evidence records the role authority as
|
|
`caller-declared-unverified`.
|
|
|
|
Electron main, preload, and renderer behavior can therefore be observed only
|
|
as separate approved Inspector targets. The provider does not infer that two
|
|
targets belong to the same Electron application.
|
|
|
|
## Capture and determinism
|
|
|
|
Every observation records its time window and returns all valid script and
|
|
execution-context events received during it. Per-location protocol validation
|
|
remains in force. Scripts are authorized after capture, deduplicated by stable
|
|
metadata, and canonically sorted. Wall-clock timestamps and protocol script IDs
|
|
are excluded from the durable result, so identical inputs and captured metadata
|
|
produce the same Evidence ID.
|
|
|
|
Inspector attach is inherently incomplete. Enabling `Debugger` reports known
|
|
and uncollected scripts, but scripts collected before attachment may be
|
|
missing. Absence from the observation window never proves that a script or
|
|
behavior does not occur.
|
|
|
|
## Static correlation
|
|
|
|
Pass the resulting observation Evidence and an
|
|
`analyze_javascript_application` Evidence record to
|
|
`reconcile_javascript_runtime`. The reconciliation accepts this provider
|
|
alongside passive web and Electron page captures. Exact approved file or URL
|
|
mappings can correlate script presence with JavaScript Application Graph
|
|
assets. Because this provider never reads source bytes, matches normally use a
|
|
unique authorized location and remain weaker than captured-byte identity.
|
|
Builtin `node:` scripts remain runtime-only nodes unless a future explicit
|
|
static authority models them.
|