Skip to Content
WebFrostdocs
Architecture

Threat model

What WebFrost protects, who can attack it through which component, the controls in place and the risks that remain open.

Revised 2026-11-21. Scope: @webfrost/core, @webfrost/cli, @webfrost/server, @webfrost/sdk, @webfrost/ui

This document maps what WebFrost protects, who can attack it and through which component, and which risks remain open. Configuration details for each control are in Security.

System overview

WebFrost is single-tenant and self-hosted. One operator runs the server; one admin account (plus API keys) uses it. Users submit URLs; the server fetches them with an HTTP client and a headless Chromium, and stores the results as files plus a database (SQLite by default).

Data flow across trust zones. Admins and API key holders reach the HTTP server with a session or key, anonymous guests only on the GET allowlist when public read is on, and the fully trusted operator uses the CLI. The server and CLI hand submitted URLs to the pipeline, which writes results to the database and captures to files. Untrusted content reaches the pipeline only through safeFetch, the guarded Chromium and yt-dlp, and archived files go back out as downloads.
Who sends what where, and which guard each untrusted input passes.Open interactive diagram(opens in a new tab)

The CLI drives the same core library directly against the data directory, without the HTTP layer.

Assets

AssetWhy it matters
The archive (files + database)The product. Loss or tampering defeats the purpose.
Admin password hash, session rows, API key hashesGrant full control of the instance.
SESSION_SECRETSigns session cookies.
The server's network positionIt can reach hosts that outside users cannot (intranet, cloud metadata).
Host resources (CPU, memory, disk)Each pipeline launches a browser and writes files.

Trust boundaries

Actor / inputTrust
Operator (shell access, environment, data directory)Fully trusted
Authenticated admin / API key holderTrusted to manage the archive. Not trusted to reach the internal network through it.
Unauthenticated network clientUntrusted. Can reach /health, the static UI, login and (before first run) setup.
Submitted URLs, feeds and import filesUntrusted input
Fetched pages and every resource they loadUntrusted and potentially hostile
DNS answersUntrusted
Reverse proxyTrusted only if WEBFROST_TRUST_PROXY=true

Attack surface and controls

1. Authentication and sessions

ThreatControlStatus
Unauthenticated API accessAll /api/v1/* routes require a session or API keyMitigated
Anonymous visitor changing the archive when public read is onWEBFROST_PUBLIC_READ admits only GETs on an explicit allowlist of read routes; storage paths and raw extractor errors (which can name internal hosts and paths) are withheld from anonymous responses; list pages capped at 200Mitigated
Operator enables public read on an archive holding private capturesNone — the whole archive becomes readableOperator responsibility
Password brute force10 attempts/min per client; bcrypt; uniform timing for unknown usersMitigated
Rate-limit evasion with a forged X-Forwarded-ForHeader ignored unless WEBFROST_TRUST_PROXY=true; behind a proxy the right-most entry (minus WEBFROST_TRUSTED_PROXY_HOPS) is used, never the client-chosen left-most; IPv6 bucketed per /64Mitigated
Stolen session cookieHttpOnly/SameSite=Strict/Secure; server-side sessions revoked on logout, on re-login over the same cookie and on password changeMitigated
Oversized bodies (huge passwords for bcrypt, giant imports)Length limits on every string field; imports capped by size and URL count (413); request body capMitigated
Forged cookieHMAC-SHA256 with SESSION_SECRET, constant-time compare, must match a session rowMitigated
Leaked API keyStored hashed; revocable; optional expiryMitigated
First-run takeover: whoever reaches a fresh instance first creates the adminSetup only works while no admin exists; WEBFROST_SETUP_TOKEN makes it require a secret; a warning is logged at startup while setup is open and unprotectedMitigated with WEBFROST_SETUP_TOKEN; otherwise finish setup before exposing the port
CSRF, including from a sibling subdomain (same site)Cookie-authenticated writes need Sec-Fetch-Site: same-origin/none, or a matching Origin; JSON-only bodies (415 otherwise); SameSite=Strict; form-action 'self'Mitigated
Everything above bypassed by AUTH_DISABLED=trueWarning logged at startup; binds to 127.0.0.1 unless HOST is setOperator responsibility

2. URL submission — snapshots, imports, schedules

ThreatControlStatus
SSRF to loopback / private / link-local / metadata addressessafeFetch resolves and rejects on every hop; IPv4-mapped and NAT64 forms coveredMitigated
SSRF through redirectsRedirects followed manually and re-validated (max 5)Mitigated
Non-HTTP schemes (file:, ftp:)Rejected at the route, the CLI and in safeFetchMitigated
DNS rebinding between check and connectNone at application levelOpen — use network egress controls
Memory exhaustion via huge responses50 MB cap, streamedMitigated
Slow-loris upstream holding a worker30 s fetch timeoutMitigated
Flooding the pipeline60 creations/min per client; WEBFROST_CONCURRENCY bounds running pipelinesMitigated
Unbounded queue from one very large importNone — queued jobs are rows plus a small in-memory entry eachAccepted
Hammering a third-party sitePer-host gap between archives (WEBFROST_DOMAIN_DELAY_MS)Mitigated

3. Headless Chromium

The page being archived controls what the browser requests.

ThreatControlStatus
Page embeds an internal URL (iframe, image, fetch, WebSocket) and it is captured in the screenshot/PDF/DOMEvery browser request is checked; blocked hosts are abortedMitigated
Subresource or navigation redirects to an internal hostDetected; browser extractors are skipped for the snapshot so nothing is capturedMitigated for disclosure; the request itself is still sent (blind SSRF, open)
Script waits until after load, then loads an internal URLAll requests are checked, and once the network settles (WEBFROST_SETTLE_MS) all further requests are refused, before captureMitigated
Service worker making unchecked requestsService workers blockedMitigated
Page stalls or loops forever30 s navigation timeout; 60 s per extractor; browser closed afterwardsMitigated
Renderer exploitChromium runs without its own sandbox inside the container; the container is the boundaryOpen — keep the image updated, do not add capabilities

4. Media extraction (yt-dlp)

ThreatControlStatus
Argument injection through the URLURL passed as a single argv element, no shellMitigated
Runaway download500 MB size cap; process killed after 10 minMitigated
Pipeline waiting forever on a finished subprocess (lost exit notification, pipe held open)Output collection gives up 3 s after the process exits or its pipes closeMitigated
yt-dlp following redirects to internal hostsOnly the initial URL is validatedOpen

5. Serving archived content

ThreatControlStatus
Stored XSS from archived HTMLDownloads are Content-Disposition: attachment (with S3, signed into the presigned URL together with the content type, so HTML never renders on the bucket's origin); the in-app preview is served with CSP: sandbox (opaque origin, no scripts, no network) inside <iframe sandbox="">; strict CSP on the app itselfMitigated
Archived page phoning home when previewedPreview policy allows only inline styles and data: URIsMitigated
HTML injection through search snippetsServer escapes archived text; UI renders snippets as text nodesMitigated
Path traversal via a stored file referenceReference normalised and checked against the storage root / S3 prefixMitigated
Unknown extractor nameAllowlistMitigated
Clickjackingframe-ancestors 'none', X-Frame-Options: DENYMitigated

6. Data at rest

ThreatControlStatus
SQL injectionBound parameters everywhereMitigated
Concurrent writers corrupting or losing writesWAL mode, busy_timeout, one connection per jobMitigated
Snapshots lost in limbo after a crashJobs are leased by heartbeat; a pending job whose lease expired is re-queued (checked at startup and every minute), up to 3 timesMitigated
Two processes on one archive (server + CLI worker) stealing each other's jobsOnly jobs with an expired lease are adopted, inside an immediate transactionMitigated
First-run setup raced by two requestsAdmin row inserted only if none exists, atomicallyMitigated
Local user reading the archiveNone — plain filesOperator responsibility (file permissions, disk encryption)
S3 credentials in the environmentNoneOperator responsibility

7. CLI

The CLI runs with the operator's own privileges against a local directory, so it is trusted input by definition. It still refuses non-HTTP(S) URLs and applies the same SSRF guard as the server.

Open risks, ranked

#RiskSeverityWhat to do today
1DNS rebinding past the SSRF guardMediumBlock egress to internal ranges at the network layer
2Blind SSRF through browser redirect hops and yt-dlpMediumSame as above
3Chromium without its own sandboxMediumKeep the image current; treat the container as the sandbox
4First-run setup raceLowSet WEBFROST_SETUP_TOKEN, or complete setup before exposing the port
5Rate-limit state is per process and in memoryLowSingle-instance deployments only; limits reset on restart

Items 1–2 would be closed by routing all outbound traffic through a filtering egress proxy that pins the validated IP; that is tracked in the roadmap.

Out of scope

  • Multi-tenant isolation. There is one admin; every credential sees the whole archive.
  • TLS. Terminate it at a reverse proxy.
  • Authenticity of archived content. WebFrost records what the server returned at capture time; it does not sign or notarise it.

On this page