Security model and threat model

This page is the canonical threat model for the Electron Stagewright MCP server. It states what the server can touch, who it trusts, what stops misuse, and what risk remains. If you are deciding whether to point an agent at the server, read this first. The posture summarised here is recorded as a decision in ADR-014; to report a vulnerability see SECURITY.md.

Agent quick reference: safe operation

• Treat the server as a privileged local tool. Only a trusted local MCP host should invoke it.
• Keep the stdio transport local; do not place it behind a network endpoint without a separate security design.
• Leave eval disabled unless necessary. Grant only --allow-eval=renderer or --allow-eval=main for the target that needs it.
• Treat tool input, screenshots, console output, traces, and capture results as potentially sensitive. Configure plugin redaction before capture.
• Set --app-root when an agent can select application paths, and write artifacts to an operator-controlled directory.
• For a target-owned Electron runtime, configure --app-root yourself and use runtime: "project"; never make the project root an agent-supplied value.
• Load only trusted first-party or reviewed plugins. Plugins are in-process code, not sandboxed.

Resource reads expose only bundled public guidance. They never read the operator's filesystem, session data, logs, or plugin configuration.

The one-line model

The server is a privileged local tool, not a sandbox. It runs with your OS privileges, drives a real desktop app, and — when you enable the --allow-eval policy — runs arbitrary JavaScript inside that app. Treat it the way you would treat a shell: only let a trusted agent host invoke it. The default transport is stdio (a local child process), so the trust boundary stays local unless you deliberately put a network in front of it.

Assets

What an attacker would want, in rough order of value:

• The host machine. The server can launch processes and read files within its launch surface, with the operator's privileges.
• The target app's runtime. Under the --allow-eval policy, arbitrary main- and/or renderer-process code; without it, the granular tools still drive the app (click, type, navigate).
• Captured data. Screenshots, visual baselines and artifacts, console logs, and session traces can contain secrets the app displayed; IPC capture can record channel payloads; network capture can record request/response headers (and, when opted in, bodies).
• Code-signing identity. The production_validate tool reads signed .app bundles and their updater feeds, and may return bounded evidence such as a signing authority in its local tool result.

Trust boundaries

1. Agent host → server. The agent supplies every tool input. Inputs are treated as untrusted and possibly hostile (a hallucinating or prompt-injected agent).
2. Server → target app. The server drives the app and, under eval, runs code in it. The app is assumed at least semi-trusted (it is the thing under test).
3. Server → host filesystem. Launch paths, screenshot output, visual baseline/artifact roots, and trace artifacts touch disk.

Threat actors

• A misbehaving agent — hallucinated or prompt-injected tool calls. The primary actor the controls below target.
• A malicious app under test — could try to abuse the driving channel. Out of primary scope (you chose to test it), but the server avoids handing it the protocol channel or unbounded waits.
• A local reader of artifacts — anyone who can read the trace/screenshot output directory.

Controls (threats × mitigations)

The eval checks, precisely

A substring blocklist scans eval source for: process.exit, require(, eval(, Function(, __proto__, child_process. It is intentionally minimal — it catches the obvious foot-guns that should stay blocked even when the eval tools are visible.

Structural inspection. Beyond the substring scan, each payload is parsed and walked as an AST, so the same dangerous constructs are matched in the parse tree even when formatting or computed access hides them from a text scan: process . exit, process['exit'], eval ('…'), the constructor-Function escape ([].constructor.constructor('…')()), and dynamic import(). A hit is EVAL_BLOCKED_CONSTRUCT, carrying the construct and the same code_hash. If the payload does not parse, the AST pass defers to the substring scan and the remote eval — never worse than the blocklist alone.

What the checks do NOT catch. Both passes are static and conservative. A key built at runtime (globalThis['pro'+'cess']), an aliased reference (const f = Function; f('…')), or a payload assembled from strings still gets through. This is deliberate: an honest, narrow check beats a broad one that over-claims and false-positives on legitimate code. The --allow-eval opt-in plus the "privileged local tool" trust boundary stay the real controls — the checks raise the floor, they are not a wall.

The gate is per-target. --allow-eval accepts targets: bare --allow-eval enables both, while --allow-eval=main or --allow-eval=renderer enable only one. Each eval tool registers only when its target is permitted, so a renderer-only automation never exposes the main-process surface (full Node/Electron). A plugin that reaches the main process through the eval seam (IPC capture) is gated on the main target too, so it is unavailable under a renderer-only policy.

Every eval is audited. A stderr breadcrumb records each call — tool, target, session, code length, and a code_hash (an FNV-1a of the payload, never the payload itself). A blocked EVAL_BLOCKED_KEYWORD error carries the same code_hash, so a rejected payload can be correlated with the logs without ever being recorded.

Residual risks and recommendations

• No static check of eval is sound. Per-target authorization, the content-hash audit, and structural (AST) inspection have all shipped, but a payload built from runtime strings or dynamic access still defeats both the blocklist and the AST pass. Treat the eval checks as defence-in-depth, not a guarantee — the --allow-eval opt-in and the trust boundary are the controls that matter.
• Do not expose the server to an untrusted agent host, and do not put a network transport in front of it. The supported model is a local stdio child process driven by a host you trust.
• Configure redact for structured trace arguments and IPC payload fields that can carry credentials, tokens, or PII before capturing. It is not a screenshot, console-output, or arbitrary-result scrubber. See Capture diagnostics.
• Treat visual baselines as reviewed project state. Configure dedicated roots, protect their write access, and inspect actual/diff evidence before visual_update_baseline. Visual masks and temporary CSS can deliberately hide or restyle content for a capture; they are useful for known volatile regions, not a way to make a failing UI look passing.
• Keep network-capture redaction on. network_capture_start is bounded to a URL allowlist and redacts authorization / cookie / set-cookie by default; only turn redactSecureDefaults off when you genuinely need those headers, and add app-specific secret headers via redactHeaders. Bodies are captured only when you set captureBodies; leave it off (or use captureBodies: "size" for length-only, or redactBodies to drop content) unless you genuinely need payload content.
• Keep cookie-value redaction on. storage_cookies / storage_snapshot redact cookie values by default; only set revealValues: true when you genuinely need a value (a cookie value can be a session/auth token). Cookie names, domains, paths, and flags are always shown. Note localStorage snapshot values are not redacted (they are app state) — treat the snapshot output as sensitive if your app stores tokens in localStorage. IndexedDB record values are also returned verbatim by default; set the storage plugin's redactValues: true when you need record presence/shape but not the values.
• Set --app-root when launching untrusted or agent-chosen app paths, to confine the launch surface. When native addons require the app's Electron ABI, use that same operator-configured root with runtime: "project"; do not loosen confinement to follow a hoisted package outside it.

Deploying safely — checklist

• Run the server as a local stdio child of a trusted host. Do not expose it on a network.
• Leave --allow-eval off unless a flow genuinely needs it; prefer the granular tools. When you do need it, grant the narrowest target: --allow-eval=renderer for page-state flows, and --allow-eval=main only when a flow truly needs Node-level access in the app's main process.
• Set --app-root to the project you are testing.
• Configure redact for sensitive channels/traces; write artifacts to a directory you control.
• Treat the agent's tool inputs as untrusted — the server does, but your host should not relay inputs from an untrusted source.

The full per-tool contracts (including which tools require --allow-eval) are in the generated TOOL-REFERENCE.md.