Skip to content

Security Model

Every trust boundary Sparrow crosses – inbound API, outbound delivery, and data at rest – and what protects it. For envelope encryption at rest and outbound delivery signing, see Architecture: Encryption at Rest and Verifying Webhook Signatures. For TLS, SSO, and per-user login in front of Sparrow, see Securing Sparrow.

The master key (SPARROW_API_KEY) or a per-person access token gates every inbound /v1 request. Credentials travel in X-API-Key or Authorization: Bearer, never a query parameter – URLs get logged by proxies, kept in browser history, and leaked via Referer. Key and token comparison is constant-time, so a wrong guess takes the same time regardless of how many characters match, defeating timing side-channel attacks.

Empty SPARROW_API_KEY disables auth entirely – intentional for local dev. With SPARROW_ENVIRONMENT=production, the server refuses to boot without a key, so this can’t ship silently misconfigured.

Named, stored credentials that can be created, listed, and individually revoked. See Access: Tokens and Invites for the operational guide; this section covers the implementation.

  • Hashing. Secrets carry 256 random bits; only a SHA-256 hash is stored. The plaintext is returned once, in the creation response.
  • Prefixes. Sparrow tokens start with sparrow_tk_; invite secrets with sparrow_inv_. The prefixes make leaked secrets easy to spot in log scans and secret-scanning tools.
  • Scopes. A token is either tenant-wide (nil scope – same power as the master key) or pinned to one consumer (non-nil scope – portal API only, same allow-list as portal tokens). Consumer-scoped tokens get 403 on /v1; full-access tokens get 403 on /portal/api.
  • Cache. Successful lookups are cached for 30 seconds to avoid hitting the database on every request. Revocation clears the cache synchronously on the revoking instance; other instances honour it when their cache entry expires (within 30 seconds).
  • last_used_at. Updated at most once per minute per token to reduce write load.
  • 401 reasons. On failure, the JSON body includes a reason field: missing (no credential), invalid (unknown key or token), expired, or revoked.
  • 503 on DB outage. If the token store is unreachable, the server returns 503 Service Unavailable with Retry-After: 5, not 401. Browsers keep their credential and retry. The master key (a root key checked in memory) still works without the database.
  • Invites. A single-use, expiring secret redeemed at POST /invite/redeem (no auth required – the invite is the credential). Redeeming creates a token; unknown, expired, cancelled, and used invites all return 400 invalid_invite.

A portal token is a consumer-scoped access token (see above), minted with POST /v1/tokens and a consumer by the master key or a tenant-wide token, and returned with a ready-made portal_path for the embeddable consumer portal. Minting, external_id reuse and lifetimes are covered in Access: Portal links. Two storage details differ from other tokens: a token minted with an external_id also keeps its secret, envelope-encrypted with the keyring and deleted on revocation, so the same link can be returned again; and the portal can carry the token in the /portal#token=... URL fragment, which browsers never send to the server, so it stays out of access logs.

A portal token authorizes exactly: everything under its own consumer’s routes except pushing or re-pushing events (events:rePush, repush-jobs, prepare_repush) and minting further tokens, plus the read-only helpers the portal UI needs (event-type catalog, template functions, server capabilities, template dry-run). The portal calls these through the single /portal/api/ gateway prefix — the consumer is carried by the token, not the URL, so cross-consumer access is structurally impossible and event injection, token minting, other consumers, global routes, and admin operations all return 401/403. Retrying the consumer’s own deliveries is allowed unless the server runs with SPARROW_PORTAL_RETRY=false, which refuses the retry calls and prepare_retry with 403.

Behind the gateway, every /v1/consumers/{consumer}/... route also checks that the resource it names belongs to that consumer: a webhook, subscription, delivery, delivery’s attempts, alert config or batch job of another consumer answers 404, so a leaked id from another consumer reveals nothing. Batch jobs snapshotted from an all-consumers list (the operator’s “all consumers” view) are reachable only with tenant-wide credentials, never with a portal token.

Sparrow makes outbound HTTP requests to user-supplied URLs – the classic server-side request forgery surface. Every URL is checked at three points:

  • Registration – only http/https schemes; well-known internal hostnames (localhost, *.internal, *.local, cloud metadata hosts) are rejected outright; everything else is resolved and every returned IP is checked against the blocklist, not just the literal host string.
  • Every redirect – each redirect target is re-validated before it is followed, so a webhook can’t register a public URL that 302s to an internal one. Redirect chains are capped at 10 hops.
  • Connection time – the resolved IP is checked again immediately before the TCP connection is opened, on every delivery. A DNS record that changes after registration (DNS rebinding) still can’t steer a delivery to a blocked address.

Blocked ranges: loopback (127.0.0.0/8, ::1), private (10/8, 172.16/12, 192.168/16), link-local (169.254.0.0/16 – covers the 169.254.169.254 cloud metadata endpoint), CGNAT (100.64.0.0/10, RFC 6598), and IETF special-use/multicast/reserved ranges (RFC 6890).

Deliveries verify the receiver’s TLS certificate. A webhook can opt out with http_config.verify_ssl: false, for trusted internal endpoints with self-signed certificates; it defaults to true, and the SSRF checks above still apply to opted-out webhooks.

Go’s certificate verification checks no revocation: no CRLs, no OCSP, no browser blocklists. Sparrow adds two checks after it, on every outbound client that verifies TLS (pkg/safetransport, a stdlib-only module other Go programs can import).

Each intermediate in a receiver’s chain is checked against the CRL its issuer publishes (SPARROW_TLS_REVOCATION, default soft). Leaf certificates are not checked: their CRLs are large and change often, and the compromise this guards against is a CA key, which is what intermediates carry.

  • When CRLs are downloaded. The first delivery whose chain needs a CRL downloads it and waits for it: at most 5s in total per connection, however many intermediates the chain has. A download still running after that finishes in the background, and that connection treats the CRL as unavailable (allowed in soft). Each instance keeps its CRLs in memory. Once a CRL is older than SPARROW_CRL_MAX_AGE (default 6h), the next delivery that uses it refreshes it in the background and still uses the cached copy. A CRL past its own nextUpdate is downloaded again before use. Nothing runs on a schedule, and an idle instance downloads nothing.
  • Refreshing now. When a CA revokes an intermediate and you don’t want to wait for the max age, POST /v1/tls/crls:refresh asks every instance to download its CRLs, through a Postgres NOTIFY. One request a minute per server. GET /v1/tls/crls shows what the answering instance has cached and any download errors.
  • When a CRL can’t be used (unreachable, bad signature, expired), soft allows the connection and records the error, and hard refuses it. A certificate listed on an expired CRL is still refused: revocation is permanent. Intermediates without an http(s) CRL address, typical of private CAs, are not checked in either mode.
  • SSRF. CRL addresses come from certificates a remote server sends, so downloads go through the same network policy as deliveries. The chain is checked from the root down and stops at the first revoked intermediate, so a CRL address written by a revoked CA, such as one an attacker put in a certificate signed with a stolen key, is never fetched.

A revoked chain fails the delivery with tls_error, which is not retried.

A separate check refuses chains containing an EC key whose private key is below 256, or its negation: the eMudhra intermediates of October 2026 (Mozilla bug 2083449). It needs no network access, so it also protects with SPARROW_TLS_REVOCATION=off and covers the AI provider and documentation fetches, which skip the CRL check. It targets that incident, not weak keys in general.

Defense-in-depth headers on every API and UI response:

Header Value Stops
X-Content-Type-Options nosniff Browser MIME-sniffing a JSON response as HTML – reflected XSS
X-Frame-Options DENY (omitted on /portal paths, which allow framing) Clickjacking – the admin UI is never legitimately framed; the portal is designed for iframe embedding
Referrer-Policy strict-origin-when-cross-origin Leaking consumer/webhook IDs in URLs to an external Referer
Permissions-Policy interest-cohort=() FLoC / Topics API tracking
Content-Security-Policy default-src 'self'; script-src 'self' 'sha256-...' ...; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data:; connect-src 'self' Loading any script, style, or image from a non-Sparrow origin other than the UI’s Google Fonts. When the embedded UI is built, script-src uses SHA-256 hashes of the SPA’s inline scripts instead of 'unsafe-inline'; the fallback to 'unsafe-inline' applies only when the UI is not embedded (API-only deploys). Portal paths add frame-ancestors *; non-portal paths add frame-ancestors 'none'. Applies only when Sparrow serves the UI; a separately hosted UI gets whatever headers its static host sets

Two more request-level controls:

  • Body size cap: every request body is capped at SPARROW_MAX_BODY_BYTES (default 5 MiB) – bounds memory use against oversized payloads before they’re read. Values below 1 MiB are rejected at startup. API requests are also limited to 1 MiB each (event-type import: 5 MiB).
  • Per-webhook rate limiting: optional leaky-bucket http_config.rate_limit_rps per webhook throttles outbound delivery – protects the receiver from being hammered. (It does not protect Sparrow’s own inbound API; see the note under API Authentication.)

POST .../webhooks/{id}:rotateSecret replaces the HMAC signing secret at once. There is no overlap window: every attempt made after the rotation, retries of older deliveries included, is signed with the new secret only, and a receiver still verifying with the old one rejects them. Update the receiver promptly, or pause the webhook, rotate, update the receiver, and resume (held deliveries are retried by hand). Rotation does not change an Ed25519 signing key.

GET /metrics serves Prometheus metrics with no authentication, like /health. Its labels include the host names and ports of webhook receivers (from the outbound HTTP client metrics), webhook counts by health and status, queue depths, and database pool statistics. If that is sensitive, set SPARROW_METRICS_ENABLED=false or block /metrics at the reverse proxy and scrape it from inside the network.

The operator UI keeps the credential it signs in with (an access token from an invite or from exchanging the master key, or a pasted credential) in localStorage (sparrow_api_key), and the portal keeps its consumer token there too, so a session survives restarts. Any script running on the UI’s origin could read it; the strict Content-Security-Policy above, which allows only Sparrow’s own scripts, is what stands between the two. Signing out removes it and revokes tokens the browser created. Use a separate origin for the UI if other content is served next to it.

The portal (/portal paths) is sent with frame-ancestors * so it can be embedded in an iframe on any site; the operator UI is sent with frame-ancestors 'none' and X-Frame-Options: DENY. To restrict who can frame the portal, have the reverse proxy replace frame-ancestors * in that header with your own list, keeping the rest of the policy as Sparrow sent it.

The plaintext webhook secret (whsec_...) is returned exactly once, in the webhook-creation response – copy it down then. Every later read (list, get, update) returns only its shape: the whsec_ prefix plus one • per secret character. The stored secret is decrypted server-side solely to compute that mask; the plaintext never appears in any response again. If a stored secret can’t be decrypted, the response degrades to a fixed •••••• instead of erroring or revealing which webhooks are affected.

Secret headers are stricter: their values never round-trip at all, masked or otherwise. Every configured header comes back as a flat •••••• regardless of the original value’s length – only the header name is real, so a reader can’t even infer secret length from the mask.

A webhook with no secret or secret headers simply returns empty fields – distinguishable from the fixed mask a decryption failure produces.

Webhook URLs often carry credentials outside the user:pass@ part: in the path (Slack’s /services/T…/B…/<secret>, Discord’s /api/webhooks/<id>/<token>) or the query string (?token=). Sparrow’s logs and trace spans therefore record only the scheme and host (https://hooks.slack.com/…); this includes the url.full attribute of each delivery’s HTTP span, so secrets never reach your OTLP backend. Delivery error messages (e.g. connection refused) have the URL reduced the same way. Use the webhook ID to find the endpoint; the full URL is still available through the API to callers with access.

Resources are namespaced by consumer – one integration’s webhooks, events, and deliveries are invisible to another’s in every list and lookup. The global list routes (GET /v1/webhooks, /v1/deliveries, etc.) can span consumers, but never cross the instance’s data boundary.

What Sparrow enforces before the server will boot, and what you should set:

Variable Requirement
SPARROW_ENCRYPTION_KEYS Always required. Comma-separated <key-id>=<64-char-hex-key> entries.
SPARROW_ENCRYPTION_PRIMARY_KEY_ID Always required. Selects the primary key for new encryption.
SPARROW_ENVIRONMENT Set to production (any case). Any other value runs as development, without the checks in this table.
SPARROW_API_KEY Required, at least 32 characters, when SPARROW_ENVIRONMENT=production. Empty is fine for local dev only.
DATABASE_URL Always required.
SPARROW_MAX_BODY_BYTES Optional, default 5 MiB. Values below 1 MiB are rejected at startup.
SPARROW_ALLOW_PRIVATE_NETWORKS Leave unset (false) unless your webhook targets live on your own private network – true disables most SSRF network checks (cloud metadata stays blocked; only SPARROW_ALLOWED_NETWORKS can reach it).
SPARROW_METRICS_ENABLED Optional, default true. Serves Prometheus metrics at /metrics, unauthenticated; labels include receiver host names. Firewall it or set to false if the data is sensitive. See Metrics Endpoint.
SPARROW_EVENT_RETENTION_DAYS Optional, default 0 (keep forever). Purges events and their deliveries older than N days – event payloads are stored in plaintext, so pair a retention window with storage-layer encryption when payloads are sensitive. See Securing Sparrow.