Skip to content

Security ​

Threat model and the write-path review for Portolan v0.1. This is a working document: the findings list is the source of truth for what is fixed and what is still open.

Assets ​

AssetWhere it livesWhy it matters
Site credentialsOS keychain or PORTOLAN_<SITE>_<KEY>Account takeover
Session cookiesChromium profileAccount takeover
Write operationsrunWrite, op executorMoney, inventory, irreversible state
Idempotency ledgerMemoryWriteLedgerDouble-spend on retry
Audit logSQLite audit_logWho did what; contains params
Traces and HARTraceStore, exported filesRequest bodies, PII
Mapsmaps/<site>/v<n>.jsonExecution plan and egress intent
Skillsskills/portolan-<site>Agent instructions
BrowserChromium behind the substrateSandbox boundary

Trust boundaries ​

model / MCP client        semi-trusted: can call any tool, can be prompt-injected
        │  MCP (stdio or HTTP)
        ▼
Portolan server           trusted code
        │
        ├── maps, policies, config, SQLite     operator-controlled
        │
        ▼
browser substrate         executes page JS
        │
        ▼
web page                  UNTRUSTED: text, element names, redirects, downloads

The page is never trusted. The model is trusted to follow the protocol, not to resist an injection. The operator's maps and policies are trusted artifacts; a malicious map is equivalent to a malicious operator.

Threats and mitigations ​

ThreatMitigationWhere
Credential appears in a map, trace, log, or skillSite-scoped credential store; audit/trace redaction by key and value shape; skill secret scancredentials.ts, redact.ts, skills/export.ts
Off-allowlist request leaves the pageDefault-deny egress guard on fetch and goto; the final URL after a redirect and the resolved address are checked too; every block recordedsubstrate/policy.ts, substrate/substrate.ts
Page text becomes a tool callEvery page-derived MCP result is labeled untrusted with a notice; injection fixture asserts the scripted runner never calls a toolserver/mcp.ts, bench/security
Irreversible write without consentconfirm: true required before dispatchruntime/write.ts
Retry double-writesIdempotency key replays a completed result; a pending key is reconciled with outcome_check; a failed-after-dispatch write returns unknown_outcome and is never retried blindlyruntime/write.ts
Idempotency key reused for another op/site returns the wrong resultFixed: collision returns invalid_params with idempotency_key_reusedruntime/write.ts
A restart loses the write ledger, so a retry can double-writeFixed: the ledger is a SQLite table; a pending record from a dead process is settled to unknown at startupserver/write-ledger.ts, server/store.ts
serve and mcp had no substrate factory, so the fallback verbs and egress policies were unavailable outside testsFixed: createServer takes a substrateFactory; serve and mcp share one that launches Chrome, registers the engine, and loads policies/<site>.jsonserver/server.ts, cli/browser.ts
serve had no authentication and could bind a public interfaceFixed: authToken adds a constant-time bearer check to every route except /v1/health; a non-loopback bind is refused without a token or PORTOLAN_ALLOW_REMOTE=1server/server.ts, server/host.ts
A redirect could land outside the allowlistFixed: fetch reports the final URL and the guard checks it, recording reason: "redirect"substrate/substrate.ts
A credential in a free-text field survived key-based redactionFixed: values are also matched by shape — provider keys, GitHub/AWS/Google/Stripe tokens, JWTs, SSNs, and Luhn-valid card numbersruntime/redact.ts, server/log.ts
The Docker image ran Chromium with --no-sandbox unconditionallyDocumented and configurable: the wrapper defaults to --no-sandbox and the image is trusted-sites only; PORTOLAN_CHROME_SANDBOX=1 drops it for a host with a seccomp profiledocker/chromium.sh, Dockerfile
A hostname could resolve to a private address (DNS rebinding)Fixed with a caveat: the guard resolves an allowlisted name before the request and refuses a private, loopback, link-local, CGNAT, or reserved addresssubstrate/policy.ts
Site name escapes the maps directoryFixed: MapStore accepts only [A-Za-z0-9][A-Za-z0-9._-]* and rejects ..server/maps.ts
Orphan browsers after a crashSession TTL/cap/recovery; reapOrphans kills tagged Chromiumserver, substrate/reaper.ts
Session leak from a previous processStartup recovery closes every open sessionserver/server.ts
Unbounded sessions or browsersmaxOpenSessions returns 429 session_limit; idle sweepserver/server.ts
Audit log records a secretParams redacted by key and value shape before the insertruntime/redact.ts
Arbitrary file read via file uploadact rejects files until upload is implementedserver/mcp.ts
Malicious map exfiltrates dataEgress policy is the control; a map cannot widen itsubstrate/policy.ts

The write path ​

runWrite is the only place a write is allowed to reach the page. Its order:

  1. Confirmation. An irreversible op without confirm: true returns needs_confirmation and never calls the executor.
  2. Key collision. A key already used for a different site or op returns invalid_params (fixed in this review).
  3. Replay. A done key returns the stored result with replayed: true. The record is in SQLite, so a replay survives a restart.
  4. Unknown. An unknown key returns unknown_outcome; the caller must not retry.
  5. Pending. With an outcome_check, the check decides done (replay) or unknown (refuse). Without one, the call is refused.
  6. Dispatch. The executor runs once. A thrown error is treated as after-dispatch, not as a clean failure.
  7. Reconcile. A failure that may have reached the server runs the outcome_check; done records the result, not_done may be retried, unknown is recorded and refused.
  8. Audit. The outcome and redacted params are written to SQLite.

What is proven by tests: confirmation, replay, pending reconciliation, the three failure classes, thrown errors, and the key-collision fix (packages/runtime/src/write.test.ts).

Findings ​

Fixed in this review ​

FindingFix
A reused idempotency key returned another op's resultCollision check on site and op, invalid_params; two tests
MapStore joined an unvalidated site name, so ../ escaped the maps directorySite-name allowlist and .. rejection; test

Ticketed ​

IssueFindingWhy it is not fixed here

Residual risks ​

  • Prompt injection is not solved by the label. The untrusted flag tells a well-behaved client what the data is. A model can ignore it; the server enforces writes, not the label.
  • The model chooses the op and params. A prompt-injected model can call a real checkout with attacker-chosen values if it has confirm: true. The confirmation is a protocol requirement, not a human approval.
  • Maps are trusted code-like artifacts. An op can name any URL or selector. Egress policy limits where it can go; it does not judge intent.
  • A page can navigate itself. location changes and form posts are not intercepted by Substrate.fetch/goto; only those verbs are guarded.
  • A redirect is checked after it is followed. The guard refuses to return the response and records the block, but the request already reached the redirect target. Blocking before the hop needs a browser request route.
  • The rebinding check is a pre-flight lookup, not address pinning. The browser resolves the name again when it connects, so a name that changes between the two lookups can still reach a private address. Pinning needs a proxy or a request route that sees the resolved address.
  • Local files are readable by the process. A malicious map or a future upload feature is a file-read risk; act currently rejects uploads.
  • The audit log is only as complete as the executor. A write that never reaches runWrite is not audited.
  • Redaction covers known credential shapes, not every secret. A novel format, or a secret that looks like ordinary prose, can survive. The field name and the value shape are two filters, not a guarantee.
  • No multi-tenant isolation. One server, one database, one browser pool; sessions are not authenticated principals.
  • The benchmark evidence is scripted. Security claims here are code properties and unit tests, not a red-team exercise.

Reporting ​

Open a private security advisory on the repository, or email the maintainer listed in package.json. Do not file a public issue for a vulnerability that lets a page or a client perform a write it was not granted.

Review scope ​

Reviewed: runtime/write.ts, server/mcp.ts, server/maps.ts, server/server.ts, server/store.ts, substrate/policy.ts, substrate/substrate.ts, substrate/reaper.ts, runtime/redact.ts, skills/export.ts, the Docker image, and the MCP install snippets.

Not reviewed: Chromium itself, Playwright, better-sqlite3, the model providers, and the operating system keychain. Dependency review is separate.

Released under Apache-2.0 · MIT · CC-BY-4.0