Security model
#Threat model
The full model, every threat with its mitigation and the test that proves it, is in THREAT_MODEL.md. CI also fuzzes the request parsers and runs an OWASP ZAP scan on every push. In short:
PyWeb defends against (on by default, no code needed):
- other sites making a visitor's browser call your server functions (CSRF: JSON-only RPCs,
OriginandSec-Fetch-Sitechecks,SameSitecookies); - injecting HTML or script through data you display (escaping, URL filtering, a strict Content-Security-Policy with Trusted Types);
- forged or tampered sessions, live-update feeds and live queries (HMAC-signed with separate keys);
- server-only code, imports and secrets leaking into browser code (compile errors);
- malformed or hostile requests: wrong argument types, oversized or deeply nested bodies, huge headers, slow clients, connection floods, too many live connections from one address;
- tampered npm package files (
pyweb.lockhashes); - path traversal in static files and unsafe redirects after login;
- with
tenant=TrueModels, one organization reading or changing another's rows (scoped queries, and row-level security on Postgres); - forged or replayed webhooks (signatures, timestamps, event ids);
- your server being tricked into calling internal addresses, when you fetch URLs with
pyweb.http.fetch; - API keys committed with the app (
pyweb checkfails on them).
Your app is responsible for:
- authorization: checking who may do what in
@serverfunctions and page bodies (session.require(...)), never in browser code; - keeping
PYWEB_AUTH_SECRETsecret and serving over HTTPS (PYWEB_COOKIE_SECURE=1); - validating business rules beyond types (amounts, ownership, limits);
- what you do with uploads, raw SQL you build yourself, and third-party services you call.
Run pyweb check --production app.pyweb before deploying: it lists settings that would leave a gap (see Deployment).
#What reaches the browser
Only three things are sent to a browser:
- HTML rendered from your markup.
- The page module: JavaScript compiled from event handlers, markup expressions, computed values, browser-callable helpers and the literal module constants they reference.
- The page state: JSON containing the values of page variables that browser code reads.
Everything else stays on the server: imports, database handles, classes, @server function bodies, module objects, and page variables that browser code doesn't read. Referencing a server-only name from browser code is a compile error. pyweb inspect lists, per name, whether it runs in the browser or on the server and why.
Treat everything in (1)–(3) as public. Authorization belongs in @server functions and page bodies (session.require(...)), never in browser code.
#Secrets
The compiler rejects, with file and line, a page variable whose name looks like a credential (secret, password, token, api_key, private_key, credential) if browser code or markup reads it and its value is not an empty literal. Empty form fields (password = "" bound to an input) are allowed because the value comes from the user.
pyweb check also scans the app and the source files next to it for credentials written into them. Keys in a known format (AWS, GitHub, Stripe, OpenAI, Anthropic, Slack, Google, private keys) fail the check: move the value to an environment variable and revoke the key, because it is already in your git history. A long random-looking string assigned to a name like api_key or password is a warning (--strict fails on it). Found values are never printed in full. Add # pyweb: allow-secret to a line that holds a deliberate fake (a test fixture).
#Cross-site scripting
- Text and attribute values are escaped on the server and set as text (never as HTML) in the browser.
- URLs in
href,src,actionandformactionthat start withjavascript:,vbscript:ordata:text/htmlare replaced by#. - The default Content-Security-Policy only allows scripts from your origin: No inline script runs, ever. A page's own inline
<style>blocks are allowed by their hashes, which are added per response, so markup injected into a page can't add a stylesheet (CSS selectors can leak values such as CSRF tokens).style="..."attributes stay allowed, becausestyle={...}in markup uses them.form-action 'self'stops an injected form from posting to another site. If your app posts a form to a payment provider, add its address withPYWEB_CSP.worker-src ... blob:lets npm packages that start Web Workers from generated code (canvas-confetti, PDF and map libraries) do so; only scripts already allowed byscript-srccan create one. When a page uses npm packages, the hash of its import map is added toscript-src. Override the policy withPYWEB_CSPif you load scripts from a CDN.Outputdefault-src 'self'; script-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'self'; form-action 'self'; img-src 'self' data: https:; style-src 'self' https:; style-src-attr 'unsafe-inline'; font-src 'self' data: https:; connect-src 'self'; worker-src 'self' blob:; require-trusted-types-for 'script'; trusted-types pyweb-md pyweb-nav pyweb-sw; report-uri /__pyweb/csp-report - Trusted Types. The browser refuses plain strings in places that turn text into HTML or script (
innerHTML,insertAdjacentHTML, parsing HTML, a<script>'s text, an iframe'ssrcdoc, a service worker's URL). PyWeb's runtime uses three private policies for the places it needs this: rendering Markdown (whose output escapes everything it doesn't build itself), parsing pages during client navigation, and registering the service worker of an installable app (which accepts/sw.jsand nothing else). So even a bug that handed visitor text to one of those places couldn't run script. Pages that use npm packages don't get this rule, because many libraries writeinnerHTMLthemselves; the rest of the policy still applies to them. - Violation reports. Browsers send what the policy blocked to
/__pyweb/csp-report. Each report is apyweb.cspwarning in the logs (query strings removed, at most 120 lines a minute) and a count in thepyweb_csp_violations_totalmetric, by directive. A steady trickle is usually browser extensions; a page you need to fix shows up as many reports from one page; a jump inscript-srcortrusted-typesreports can mean someone is trying to inject script.
#Cross-site request forgery
RPC endpoints only accept POST with a JSON content type (cross-site form posts are rejected with 415) and reject requests whose Origin header names another site, or that the browser marks Sec-Fetch-Site: cross-site (403 csrf_failed). Session cookies are SameSite=Lax and HttpOnly. Setting PYWEB_CSRF_SECRET adds a token check for RPCs marked @pyweb.decorators.auth_required.
#Signing keys and rotation
PYWEB_AUTH_SECRET is a root secret. Sessions, live-update feeds and live query specs are each signed with their own key derived from it, so a token made for one purpose can't be used as another.
To change the secret without signing everyone out, set the new value as PYWEB_AUTH_SECRET and move the old one to PYWEB_AUTH_SECRET_PREVIOUS (comma-separate several). Tokens signed with an old secret keep working until they expire; remove it from the list after a month (the longest a session lasts). Every token is signed with a key derived for its purpose (sessions, feeds, forms, ...), never with the secret itself, so a token made for one purpose can't be used for another.
#Server function arguments
Arguments are checked against the function's type hints before it runs: str, int, float, bool, list[...], dict[str, ...], Optional[...], Literal[...], dataclasses, Model subclasses and Email. A name: str never receives an object, a dataclass or Model gets only its own fields, and unknown argument names are refused, all with 422 validation_error naming the field. Parameters without a type hint receive the JSON value as it is.
#Data at rest
Field(encrypted=True) encrypts a column with AES-256-GCM under its own key derived from PYWEB_DATA_KEY (see Data). A database dump, backup or read-only SQL injection shows only ciphertext, and a ciphertext copied into another column fails to decrypt instead of showing up there.
#Requests your server makes
When your app fetches a URL that someone else chose (a webhook endpoint, a link preview, an avatar, an import), use pyweb.http.fetch instead of urllib:
from pyweb.http import FetchError, fetch
try:
page = fetch(url, timeout=5, max_bytes=1_000_000)
except FetchError as exc:
raise RPCError("bad_url", str(exc))
title = page.text[:200]A plain urlopen(url) would let anyone make your server request http://169.254.169.254/ (cloud credentials) or http://localhost:6379/ (your Redis): server-side request forgery. fetch only allows http and https, refuses every address that isn't public (loopback, private, link-local, carrier-grade NAT, multicast and reserved ranges, IPv4 hidden in IPv6), connects to the exact address it checked so DNS can't change under it, checks each redirect the same way, drops Authorization and cookies when a redirect leaves the site, and limits time and size.
To call an internal service on purpose, allow it with PYWEB_FETCH_ALLOW=hooks.internal,10.2.0.0/16 or fetch(url, allow=["10.2.0.0/16"]).
#SQL injection
pyweb.db only executes parameterised statements; Query validates table and column identifiers.
#Other protections
- Request bodies are capped (1 MiB by default,
413beyond), and RPC bodies nested more than 32 levels deep or holding more than 10,000 values are refused (422). pyweb servedrops clients that stall for 30 seconds (PYWEB_SOCKET_TIMEOUT) or take more than 10 seconds to send a request head, answers503beyond 10,000 simultaneous connections per process (PYWEB_MAX_CONNECTIONS) and431to headers over 16 KB. It refuses requests whose length is ambiguous (bothContent-LengthandTransfer-Encoding, repeated lengths, folded headers), which is how request smuggling past a proxy works. A client address may hold 20 live connections (PYWEB_MAX_STREAMS_PER_CLIENT;429beyond).- The pages' WebSocket only accepts connections whose
Originis the site itself (or one inPYWEB_ALLOWED_ORIGINS), so another site can't open it with a visitor's cookies. A socket closes when its session is revoked, and sending too many or too large messages closes it too. - Pages that take longer than 30 seconds (
PYWEB_RENDER_TIMEOUT) get a504instead of holding the server. - RPC calls are rate-limited (120/minute per client address by default). Behind a reverse proxy, set
PYWEB_TRUST_PROXY=1so the visitor's address is used;X-Forwarded-Foris ignored otherwise, because anyone can send it. - Static file serving is confined to the static directory (path traversal returns
403). pyweb.security.safe_next/is_safe_redirectvalidate redirect targets;pyweb.uploads.validate_uploadchecks size, declared type and magic bytes, and generates safe storage names.- The auth kit hashes passwords with scrypt (or argon2id with
pyweb-stack[auth]);pyweb.auth.hash_passwordfor apps without the kit uses PBKDF2-HMAC-SHA256. All use per-user salts. Session cookies are HMAC-SHA256 signed and compared in constant time. Each login starts a new session, sessions end 30 days after sign-in, andauth.revoke_user(user_id)signs a user out everywhere (see Auth). - Every response carries
X-Content-Type-Options,Referrer-Policy,X-Frame-Options,Permissions-Policy(camera, microphone, location and payments off),Cross-Origin-Opener-PolicyandCross-Origin-Resource-Policy; withPYWEB_COOKIE_SECURE=1, alsoStrict-Transport-Security. A page that needs the camera can send its ownPermissions-Policy. RedisCachestores JSON. Reading pickled data can run code, so it's only allowed withRedisCache(..., allow_pickle=True).pyweb.lockrecords a SHA-256 for every npm file;pyweb buildrefuses files that changed sincepyweb add.- Releases carry signed build provenance: check a downloaded file with
gh attestation verify FILE --repo MaanavKrishna/PyWeb. PyPI shows the same for each file (PEP 740 attestations), and each GitHub release has a CycloneDX bill of materials (pyweb-stack-<version>.cdx.json). Every GitHub Action PyWeb's own CI uses is pinned to a commit. pyweb buildwritessbom.json(CycloneDX) next to the built app: PyWeb and each npm package it vendors, with the registry's integrity hash, for scanners such as Grype, Trivy or Dependency-Track.- Live-update channels can only be read with a feed from
channel(): an HMAC-signed token that expires after 24 hours. A page that shows private data should only create a feed after checking the visitor (for example withsession.require()), exactly as it would before rendering the data itself.
#AI assistants and the dev server
pyweb mcp runs on your machine with your permissions, like pyweb dev. Over stdio only the assistant that started it can talk to it. With --http it listens on 127.0.0.1 and refuses requests from web pages (by their Origin) and other host names (DNS rebinding); listening on any other address needs a token. pyweb_db_query runs one read-only statement in a transaction that is always rolled back, with secrets redacted. The dev server's state reaches the assistant only with the token in .pyweb/dev.json, a file only you can read; the dev server answers those requests only on loopback.
#Reporting a vulnerability
See SECURITY.md.