electron-release-inspector

Defensive release-diff prototype for Electron applications. Point it at two versions of an app (extracted directories or app.asar files, plus optionally the packaged executables) and it produces a single self-contained HTML report of what changed between them — with emphasis on changes that enlarge the privileged attack surface.

Use it only on software you own or are authorized to analyze. The tool prints this notice on every run.

Install / run

Not yet published to npm. Once published:

npx -y [email protected] \
  --left <old app.asar|dir> --right <new app.asar|dir> \
  --out eri-report/report.html

For now, clone this repo, npm install, and invoke node bin/eri.mjs.

What it does

1. Runs rea-agents (pinned [email protected], invoked via npx -y, never installed globally) twice — analyze-javascript-application on each version in parallel — then feeds both complete Evidence records into compare-application-versions. All raw REA JSON is preserved under <report>-evidence/.
2. Applies severity rules over REA's parsed graph facts only (it does not re-parse JavaScript):
   • high — webPreferences regressed to nodeIntegration: true, contextIsolation: false, sandbox: false, or webSecurity: false; new contextBridge API keys or new exposed members; new IPC channels/handlers (REA sender-validation candidates are listed when observed).
   • medium — new native add-on bindings, new network endpoints/domains, new storage use, changed preload wiring; Electron fuse changes and insecure fuse states.
   • info — added/removed/changed modules and files.
3. Diffs the file inventory byte-for-byte (sha256 per file; files over 64 MB are compared by size only). Files under node_modules/ are summarized per package root rather than listed individually.
4. Diffs shipped packages — every node_modules/**/package.json that is a package root, keyed by install path — plus declared package.json dependencies/devDependencies and package-lock.json resolved entries.
5. Scans text files for exposed secrets (AWS access key IDs, GitHub tokens, Slack tokens, Stripe live keys, Google API keys, private-key blocks). Findings report type, file, line, and a masked fingerprint only (first4… (len=N, sha256:xxxxxxxx)) — raw values are never printed, saved, or written to the report. Findings seen in the left version are marked as pre-existing.
6. Optionally reads Electron fuse wires from the packaged executables (--left-exe / --right-exe). Note: [email protected] does not ship inspect-electron-fuses, so src/fuses.mjs parses the documented fuse wire format directly from the binary; the report labels this as local, not REA-produced, evidence.
7. Writes one self-contained HTML report (inline CSS, no JavaScript, no external resources; all dynamic text is HTML-escaped), a machine-readable report.json twin (same basename, same masking guarantees), and a <basename>-evidence/ directory containing the raw inputs it consumed.

Usage

node bin/eri.mjs \
  --left <dir|asar> --right <dir|asar> \
  [--left-exe <path-to-exe>] [--right-exe <path-to-exe>] \
  [--no-rea] \
  --out <report.html>

--no-rea skips the REA pipeline entirely: file diff, shipped packages, declared dependencies, secrets, and fuses still run, but Electron configuration / IPC / contextBridge analysis is not performed and the report says so. This is the mode to use for large apps whose REA evidence would be hundreds of MB until focused scope lands.

Example:

node bin/eri.mjs --left v1/resources/app.asar --right v2/resources/app.asar \
  --left-exe v1/app.exe --right-exe v2/app.exe --out report.html

Requires Node ^22.19.0 || ^24.11.0 || >=26.0.0 and network access on first run (npx downloads the pinned rea-agents package into the npm cache).

Output

Every run writes three artifacts next to --out:

• report.html — self-contained human report (inline CSS, no JS, no external resources). Sections, in order: Summary → Release changes → Dependency changes → Possible exposed secrets (masked) → Current posture → File/module inventory → Not determined → Coverage & limitations → Run metadata.
• report.json — machine-readable twin with the same masking guarantees: mode, findings[], deps, files, secrets, undetermined, coverage, metadata. Intended for CI gating and agent consumption.
• report-evidence/ — the raw JSON the tool consumed/produced.

Every finding carries a category:

• change — introduced or altered by this release (the review core).
• posture — state of the shipped build regardless of the diff (fuse posture); the rationale says when it is unchanged from the previous version, i.e. pre-existing, not a regression.
• inventory — added/removed/changed files and modules; context only.

An agent skill for driving the tool lives in skill/ (see skill/electron-release-inspector/SKILL.md).

What it does NOT do

• No execution: the target is never launched, no processes are attached, no debuggers. Everything below is static analysis of files you supply.
• Not a full security audit — it diffs two releases and flags changes that deserve review; pre-existing issues that did not change may not appear.
• No credential recovery or exfiltration. Secret scanning is a defensive leak check that emits masked fingerprints only.
• Results inherit REA's coverage: if a graph is partial or a comparison item is unknown, the report says "not determined" — it never reports "no issue" for unanalyzed surface.
• Very large apps: REA Evidence can be hundreds of MB or more. If JSON parsing fails, retry with NODE_OPTIONS=--max-old-space-size=8192, or run with --no-rea (file/dependency/secret/fuse diff only).

Roadmap

• Focused scope (--scope focused, analyzing only files outside node_modules) is planned via REA's --source-path option. The pinned [email protected] does not implement it; it first shipped in 6.5.0 (2026-10-14) and the pin will be revisited once that release is at least seven days old (2026-10-21).

Development

npm install     # only runtime dep: @electron/asar (pinned)
npm test        # node:test unit tests + one end-to-end fixture run

test/fixtures/v1 and v2 are a synthetic Electron-like app pair covering every seeded change the rules look for.