Skip to content

Security: jntegz/ambersight

SECURITY.md

Security

Ambersight is built so that a stolen Cloudflare token can never change or delete anything. It can still read everything its permissions allow, which is much more than the metadata and metrics Ambersight itself stores. With the pre-filled token, across all the accounts and zones it is given, that means: Worker scripts and their settings (script code and plain-text variables, not secret values), the data in KV and R2 and as much of D1 as Cloudflare's D1 Read allows, Pages projects, zones, routes, DNS records and certificates, account members and the audit log, billing details, and API token details. Treat it as a sensitive credential, and narrow it to the accounts and zones you watch.

  • The API token must be read-only. Ambersight only sends GET requests and GraphQL queries to api.cloudflare.com. The setup wizard refuses a token with a write permission when it can read the token's permissions; when it cannot, you confirm the token by hand, and that confirmation is what the install relies on.
  • Every inventory refresh (daily by default) reads the token's permissions again and compares them with a fixed list of the read permissions Ambersight has a use for. Anything else raises the critical finding health:token-scope. If the permissions cannot be read, the finding health:token-scope-unverified says so, and a grant already found stays reported.
  • The token and the dashboard passphrase are Worker secrets. They are never sent to the browser or logged.
  • D1 never holds a passphrase in the clear. It does hold values derived from one, which someone with a copy of the database could test guesses against, slowly and offline, so use a long random passphrase: a passphrase set in Settings as a salted PBKDF2 hash (50,000 iterations), and the ADMIN_PASSPHRASE secret as a salted PBKDF2 value (25,000 iterations). That value is the binding stored with a Settings passphrase and, while the secret is the credential, the credential mark on sessions, known-device markers and API tokens.
  • The dashboard requires a session. Sessions are random 256-bit ids; D1 stores only their SHA-256 digest, so a copy of the database contains no working cookies. The cookie is __Host- prefixed, HttpOnly; Secure; SameSite=Strict.
  • A passphrase set in Settings counts only while the ADMIN_PASSPHRASE secret stays the one it was saved under. Replacing the secret with a new value makes the secret the credential again, and the first sign-in with it deletes the Settings passphrase. A Settings passphrase saved before this check existed gets its binding at its next sign-in; until then, and on an install with no secret, replacing the secret does not affect it, so delete the stored hash instead (see the README).
  • Sessions, known-device markers and API tokens are tied to the credential that issued them: changing the passphrase, replacing the ADMIN_PASSPHRASE secret while it is in force or bound, or deleting the stored hash ends all of them. Upgrading to this scheme signs everyone out once. An API token from before the upgrade is tied to the credential at the first sign-in, use of such a token or scheduled run (every 15 minutes) after it. Nothing records the earlier credential, so if the secret is replaced or the stored hash deleted between the upgrade and that moment, such a token is tied to the new credential and keeps working. If you did that, revoke those tokens.
  • API tokens are read-only, stored only as SHA-256 digests, and expire after 30, 90 or 365 days (90 by default; tokens from before expiry existed got 90 days from the upgrade). Creating one requires entering the passphrase again.
  • An API token reads only the accounts chosen when it was created, or every watched account if that was chosen on purpose: the request must say which. For a token limited to some accounts, the others do not exist: naming one gets the same 404 as an unknown account, finding history by id returns the same as for an unknown finding, and the account list and overview do not reveal them. Without the person-linked grant, which is off by default, answers leave out deploy authors and messages, audit actors and descriptions, member ids, Cloudflare notification text, and repository and branch names, and an account name that identifies someone is replaced. Names people chose for Workers, resources and tags stay, because Ambersight cannot tell whether one is personal. Tokens from before scopes keep every watched account and lose person-linked data. A scope cannot be changed afterwards: create a new token.
  • Dashboard sessions are not limited this way. Every session sees, and can act on, every watched account, because one shared passphrase cannot identify separate people. If accounts belong to different clients, do not share the passphrase with them: give them a limited API token, a client digest or a report.
  • Every API request that changes something must show it comes from the dashboard's own page: Sec-Fetch-Site: same-origin (or, where a browser does not send that header, an Origin equal to the dashboard's) and a JSON content type. A request with neither signal is refused, so other Workers on the same workers.dev subdomain cannot send changes with your cookie. Hono's CSRF check stays as a second layer.
  • The dashboard cannot be framed: the static files carry Content-Security-Policy: frame-ancestors 'none' and X-Frame-Options: DENY from web/public/_headers, and API responses set the same.
  • Five wrong passphrases from one client lock it out for 15 minutes. A client is an IPv4 address or an IPv6 /64. Past 50 attempts from any mix of clients in a 15-minute window, sign-in is paused until the window ends, except for a browser that has signed in before (a random __Host- cookie, stored only as a digest, at most 10 per install, 90 days at most, ended by a credential change) or a request that passed Turnstile. Turnstile counts only up to 200 attempts in the window, which keeps the attempt table small; past that, only a browser that has signed in before gets through. The per-client limit still applies to those. A browser that has never signed in can be kept out during an attack, and with Turnstile on it can still be once the window passes 200; Cloudflare Access in front prevents it. Open sessions keep working, and a session can still change the passphrase, under the per-client limit. Attempts are counted atomically, refused attempts write nothing, and the scheduled run deletes expired attempt rows, so client addresses are kept for well under an hour after the last attempt.
  • The ADMIN_PASSPHRASE secret must be at least 12 characters, or sign-in stays off. The setup wizard and Settings › Security refuse passphrases that are common, repetitive or simple sequences.
  • Manual scans run at most once a minute per account and test messages at most once a minute per channel.
  • No third-party scripts, fonts or analytics are loaded; the page sets a Content-Security-Policy. There is no second factor in Ambersight itself: on a public address put Cloudflare Access in front (see the README), and if you use a custom domain set "workers_dev": false in wrangler.jsonc.
  • Names that other people in your account choose (Workers, KV namespaces, routes) are escaped in the dashboard, e-mail and chat alerts. The dashboard shows them, deploy messages and audit-log text in quotes, so that they read as data and not as Ambersight's advice. A Worker card's link shows the host it opens, and links built from stored data are only ever http or https. CSV exports put an apostrophe before a text cell a spreadsheet would run as a formula.
  • The installed app keeps copies in the browser so that it opens offline: the page itself, and the overview, accounts, findings, analytics, resources, packages and self-cost views. The Timeline and Worker pages are never kept, and the people named in a finding's evidence are removed from the copy. A copy is not served after 7 days and is deleted then. All copies are deleted as soon as the browser sees the session has ended (a 401 from the API, or /api/session saying so) and on sign-out, which also removes the selected account, the last-visit times and the chosen group from localStorage. Theme and display preferences stay. These copies still hold Worker and resource names and metrics until then, and nothing runs while the browser is closed: someone with access to that browser profile can read what has not been deleted yet. Do not install the app on a computer you share. Apart from these copies, API answers to the signed-in dashboard are sent with Cache-Control: no-store, so the browser's HTTP cache does not keep them. Answers stored there by an earlier version stay until they are replaced or evicted.
  • The session cookie is HttpOnly, so only the server can end a session. If it does not confirm a sign-out, the browser's copies are still removed, the sign-in page says the session may still be active, and the sign-out is tried again when you ask, when the connection returns and at the next page load.
  • E-mail recipients come only from configuration; no endpoint accepts an address.
  • Ambersight sends no telemetry to its maintainers.
  • Settings › Security shows an admin log of sign-ins and of changes to settings, watched accounts, API tokens and the passphrase, and of acknowledged or snoozed findings. It records the action, what it applied to, the time and a short handle derived from the session cookie, which is neither the session id nor its stored digest. There is one shared passphrase, so the handle tells sessions apart and does not identify a person. Entries are kept 90 days, at most 1,000. Refused sign-ins write nothing to it.
  • Changes that reduce detection (alert routes, muted checks, scope exclusions, raised thresholds and the like), acknowledging or snoozing 10 or more findings at once, unwatching an account, creating an API token and changing the passphrase also send a notice to the operators and the webhook. It does not follow the alert routes or quiet hours, which the same session could change. At most one goes out every 30 minutes; later changes are grouped into the next one.
  • The Packages check compares a dependency with the public npm registry only if its lockfile entry shows it came from there, so names of private packages are not sent to npm and get no update advice. GITHUB_REPO_ALLOWLIST limits which repositories it can read.
  • Retention differs per kind of data; see what is kept and for how long. Data of an account you stop watching ages out too, without a scan.
  • All-account mail (alerts, the main digest, test messages) goes only to operators. An address named as a client or group digest recipient gets only its own digest, in a message of its own, unless DIGEST_OPERATORS lists it.
  • Finding messages, e-mail, webhooks and the AI summary do not name people. The actor of an audit-log change stays in the dashboard, for troubleshooting, and reaches only API tokens explicitly given person-linked data. Client digests and reports leave out deploy authors. The AI summary gets check names, severities, counts and Worker names only.
  • Settings › General › Record who made changes can be turned off for the whole install. Scans then store no deploy authors or audit-log actors, and the names already stored are erased from the database and its cached views. Erasing cannot be undone, and it does not reach free text that names someone other than by the reported address or token name, or by an e-mail address. What it covers.
  • Settings › Security › Remove one person from stored data finds an exact e-mail address or name and replaces it with [removed], keeping the rows. It needs a dashboard session, the same origin, a finished preview of that identifier and the passphrase under the per-client attempt limit; API tokens cannot use it. The identifier is not stored or logged. The admin log records that it ran and how many records changed, and the operators get a notice. It cannot reach messages already sent, what recipients kept, copies in other browsers, backups or D1 Time Travel, or what Cloudflare still holds and a later scan can fetch again. Settings that hold the identifier are listed for you to change. What it covers.
  • D1 query text is stored and shown as its shape, with literal values replaced by ?. Error messages lose URLs, query strings and credential-shaped values before they are stored, sent or returned, and API tokens get only a general status.

Deploying safely

Whoever can get code onto the branch your Worker deploys from can run code inside it. A compromised deploy can reach every binding: CF_API_TOKEN (and all it can read), ADMIN_PASSPHRASE, GITHUB_TOKEN, WEBHOOK_URL, TURNSTILE_SECRET, the D1 database with its history, session digests and passphrase hash, and the e-mail binding, and it can send them anywhere: the outbound allowlist only binds Ambersight's own code. So:

  • Deploy a release you have looked at, not a branch that moves on its own.
  • Protect the branch that deploys: require a review, and allow no force pushes.
  • Install with npm ci, so the versions in package-lock.json are the ones you get.

Reporting a vulnerability

Please do not open a public issue. Use GitHub's Report a vulnerability (private advisory) on this repository. We aim to reply within 7 days.

There aren't any published security advisories