Do not open a public GitHub issue for security vulnerabilities.
Report it privately through GitHub's private vulnerability reporting, or email info@r9lab.io, with:
- a clear description of the issue and its potential impact
- steps to reproduce it, or a proof of concept
- any mitigations or patches you have already identified
Both reach only the maintainers.
- We aim to acknowledge reports within 5 business days.
- For confirmed vulnerabilities, we coordinate a fix and a disclosure timeline with the reporter where practical.
- The fix ships in a release. We then publish a GitHub security advisory, with a CVE where one applies, and name it under "Security" in the changelog.
- We credit the reporter in the advisory unless they ask not to be named.
Only the latest release and main get security fixes.
R9lab uses OWASP ASVS as the application-security baseline and the OWASP Secure Product Design lens for product decisions. Keep controls simple, reviewable, and documented near the behavior they protect.
Security and hardening is the reference for the deployed security posture: assets and data classes, account privileges, the edge and application rate limits, the trust boundaries, the egress policy, the browser runtime policy, and the supply chain. This page holds what a reviewer of a change needs on top of it.
Review security-sensitive changes against this baseline:
- Context: self-hosted research and data-collection platform.
- Components: backend, app, web, docs, PostgreSQL, Redis, storage, backups, OAuth, email, YouTube, and RPi camera integrations.
- Connections: clients and devices enter through the API; PostgreSQL and Redis stay on the internal data network; external providers are explicit trust boundaries.
- Code: authorization, validation, upload checks, browser security headers, and tests live close to the behavior they protect.
- Configuration: secrets, Compose policy, HTTPS, least-privilege database roles, and secure runtime defaults are source-controlled where practical. Each Compose service mounts only the secret files its process reads.
Security-sensitive areas:
- authentication and OAuth
- Stored OAuth access and refresh tokens use
EncryptedString(AES-256-GCM underDATA_ENCRYPTION_KEY), like the TOTP secret and the camera broadcast key; the column refuses a value without the encrypted-value prefix. - Unlinking Google or erasing the account revokes the Google grant (YouTube scope included) once the link's deletion is committed. Revocation is best effort: a failure is logged without the token and never blocks the unlink or the erasure. GitHub grants are not revoked by the backend; the user removes them in their GitHub settings.
- Login and account-link flows use PKCE (S256) on top of the CSRF cookie and signed state. The
code verifier is random, lives only in the
__Host-r9lab-oauth-pkcecookie and is never derived from the state, which anyone who sees the authorization URL can read. The callback takes no verifier from the query string.
- Stored OAuth access and refresh tokens use
- rate limits (the buckets and numbers are in the security reference)
- Password login is limited per IP and by failed attempts per account, so a shared account is not locked by use while guessing stays capped per account.
- Per-account buckets for login and forgot-password are keyed on the canonical email address
(
account_rate_limit_identity): the comparison key the account lookup uses, so letter case, Unicode normalization and Unicode or ASCII domain spellings share one budget. - The MFA login challenge and every signed-in re-authentication (account deletion, email and
password changes, social login link and unlink, MFA setup, disable and recovery-code
rotation) share one per-account budget of password, TOTP and recovery-code checks
(
account_guess_budget): a few a minute, and at most 100 a day, so slow guessing paced under the minute limit runs out too. Every check is charged before it runs, right or wrong, so parallel guesses cannot race past the cap. Rotating IPs, routes or fresh login challenges buys no extra guesses, so the MFA routes themselves sit on the looser login IP budget. - Every mutating
/v1route carries a rate limit; the exemptions (admin routes, device-signed camera routes, routes on the guess budget) are listed and justified inbackend/tests/unit/api/test_dos_rate_limit_routes.py.
- step-up re-authentication: changing the email or password through
PATCH /users/me, linking or unlinking a social login, and deleting the account all re-authenticate with the current password (an account without one shows a recent sign-in instead, except for an email or password change), plus a current TOTP or recovery code when the account has MFA (require_account_update_step_up,require_step_up). A request missing a credential the account needs is refused before the guess budget is charged. - public read APIs
- Product export (
/products/export,/products/{id}/export) assembles whole product trees, so it has its own, stricter rate limit. Signed-in exports also share a looser per-IP ceiling, so throwaway accounts on one IP cannot multiply the per-user budget. One request is bounded by three limits, and past any of them it fails with a400instead of a partial file: at most 100 base products, at most 10 component levels below a base product, and at most 5,000 components in total. The tree walk checks the depth and component limits as it loads each level. Creating a component deeper than 10 levels is refused as well. Owner attribution follows the same profile-visibility redaction as the product page. CSV cells that a spreadsheet would read as a formula are prefixed with'. - The account archive (
GET /users/me/export) streams every product, photo and file the signed-in user owns. It holds at most 50,000 products and components together, ten times the export component cap, and answers413past that; the upload quota bounds the files. It needs a session, reads only rows owned by that user or edits they made, and carries its own budget of 5 an hour per user (API_ACCOUNT_EXPORT_RATE_LIMIT) under a per-IP ceiling of 15 an hour for signed-in requests (API_ACCOUNT_EXPORT_RATE_LIMIT_SIGNED_IN_PER_IP).account.jsonis built fromUserRead, so no password hash, MFA material or OAuth token reaches it; camera entries carry no keys. - Component reads carry the per-IP read limit, as do the product search and facet routes. The
direct list (
/products/{id}/components) is paged; the tree (/products/{id}/components/tree) returns at most 1,000 components across all levels and fails with a400past that, checked as each level loads. The category tree routes (/categories/tree,/categories/{id}/subcategories/tree,/taxonomies/{id}/categories/tree) page their top-level categories and carry the same limit.test_dos_rate_limit_routes.pyrequires the read limit on every public route that lists components or returns a tree.
- Product export (
- product edit history (
product_revision): every changing update of a product's own fields stores a snapshot of those fields, the editor and the resulting version, written in the update's transaction under the owner and product row locks. It can hold text the owner later removed, so it is not kept for ever:- Revisions older than two years (
REVISION_RETENTION) are pruned hourly by each API worker. - Erasing an account in anonymize mode deletes the history of that account's products before they move to the system account; in delete mode the history goes with the products. Edits the account made to other people's products stay, with the editor cleared.
GET /products/{id}/revisionsandGET /components/{id}/revisionsare as public as the product, but return thesnapshotonly to the owner and to admins (has_admin_access); everyone else getsnull, with the time, the editor and the changed field names. An owner's edits follow the product's owner redaction; a moderator's edits are marked as such and name the moderator to admins only.- The migration's downgrade refuses while the table holds rows, in SQL, so a script rendered
with
--sqlrefuses too.
- Revisions older than two years (
- cookie-authenticated writes: an unsafe
/v1request carrying the session cookies, and every session login, is refused with 403 whenSec-Fetch-Siteiscross-siteor theOriginis not in the CORS allow-list (app/core/middleware/cross_site.py). Requests without either header (native app, scripts) and bearer-token requests pass. A new browser origin that signs in must be added to the CORS allow-list. - client IP: the API takes the client address from
X-Forwarded-Foronly when the request comes from Docker's private range (172.16.0.0/12,FORWARDED_ALLOW_IPSandTRUSTED_PROXY_CIDRSincompose.deploy.yaml). The API publishes no port, so only containers on its own networks can reach it, and all of them belong to the stack. - authenticated mutation APIs: create endpoints accept an
Idempotency-Keyheader and cache the response in Redis for one hour.- The cache entry is scoped by authenticated user id, endpoint (parent id included), and key, so a cached response is never replayed across accounts or targets.
- The entry stores a hash of the request body: reusing a key with a different payload is rejected
with
422. - If Redis is unreachable the request fails closed with
503.
- uploads and media: the
/uploadsmount serves stored bytes with a content-hashed, immutable cache policy andCross-Origin-Resource-Policy: same-site. In thedevandtestingenvironments, where the API and the frontends sit on different ports of127.0.0.1and Chromium blocks the loads, the policy iscross-originfor/uploadsalone. The relaxation is derived from the environment, not configured, so staging and production cannot opt into it. - admin APIs
- Every
/v1/adminroute needs an active superuser with TOTP enrolled (current_active_superuser), and every write is audited with the acting admin's id. The app's admin section is hidden from other accounts, but that is presentation only. - Suspending an account (
PUT /v1/admin/users/{user_id}/active) revokes its refresh sessions before the write, and refuses the acting admin's own account and the last active superuser. The last-superuser guard locks every active superuser in id order, so two admins acting on each other queue instead of deadlocking. - The anonymous system account, which owns anonymized content, refuses every admin write
(
409) and is left out ofGET /v1/admin/users(account_guards.py). - No admin route sets
is_verifiedoris_superuser: verification proves control of the mailbox, and OAuth sign-in links by email only to verified accounts.
- Every
- RPi camera device APIs and WebSocket relay
- A camera acts for its owner. Device-signed HTTP routes and the relay accept a camera only when
its credential is active and its owner account is active and verified
(
camera_may_authenticateindevice_assertion.py), the same bar a person must clear to upload directly. Triggering a capture also needs a verified account. - The relay re-checks the camera on every heartbeat (30 s) and closes the socket with 1008 when the camera is gone, its credential is no longer active or differs from the key the socket authenticated with, or its owner fails the bar above. A re-check that errors or takes over 5 s keeps the socket once; two in a row close it with 1011, and the device authenticates again.
- A camera acts for its owner. Device-signed HTTP routes and the relay accept a camera only when
its credential is active and its owner account is active and verified
(
- backups, secrets, logs, and telemetry
- Every account erasure is appended to a ledger file on the backup disk, outside Postgres
(
erasure_ledger_path). A line holds the account's UUID, the content policy (anonymizeordelete) and the UTC time: no email address, name or other account field. The entry is fsynced before the erasure commits, and a failed write fails the erasure, so no committed erasure is missing from it. Each database snapshot archives the ledger with the dump, so the offsite copy carries it.just restorereplays the union of the live ledger and the newest snapshot's copy througherase_userbefore the API starts, so a restored dump does not bring an erased account back. The limit: if the backup disk is lost with the live ledger on it, erasures made since the last offsite copy (up to a day) are in no copy, and a restore from offsite brings those accounts back. The file is mode 0600 and owned by the app uid; only the API appends to it, and the migrator and the backup job mount it read-only. Entries are kept indefinitely.
- Every account erasure is appended to a ledger file on the backup disk, outside Postgres
(
- release and security artifacts: the GHCR images the hosts pull, and the landing page and docs
deploy, whose Cloudflare API token is a GitHub Environment secret holding only Workers
Scripts: Edit. A token granted on all Workers is not scoped to one environment, so every
Environment that holds one requires a reviewer; in prod that reviewer is also the release
gate. Hosts check image provenance with
just images-verifybefore pulling a tag.
The product/component catalog and its research content are world-readable; the platform exists to
publish that data. profile_visibility hides owner identity attribution only. It is not a control
over the research content and must never be treated as one.
is_verified, is_superuser, and role are three independent account privileges; the security
reference defines each. Conflating any two of them is a privilege escalation. Keep role off
UserUpdate: fastapi-users' safe update path strips a fixed set of privileged fields, so any new
field on that schema flows through self-service PATCH /users/me.
Supply-chain and code-security checks:
- Dependencies: GitHub Dependency Review / Dependency Graph and Renovate. Renovate runs from
.github/workflows/renovate.ymlas a GitHub App installed on this repository only. The workflow scopes each run's token to the permissions it lists, and the app's private key is an Actions secret: rotate it whenever the key, or a workflow that can read it, may have leaked. Changes tomaingo through a pull request with one approving review, and must pass the requiredCI Resultcheck. The app bypasses the review (theprotect_mainruleset) and merges what.github/renovate.jsonmarks automerge itself. It cannot skip the check, whichprotect_main_checksrequires with no app bypass, so a leaked key cannot reachmainwithout a pull request that passes CI. Release tags are held by therelease tagsruleset (infra/cloudflare/github.tf), which only repository admins and maintainers bypass, so the key cannot mint or move the tag hosts deploy from, and every job in thestagingandprodEnvironments waits for a required reviewer. - Runtime images: Trivy scans and SPDX JSON SBOM artifacts.
- Infrastructure as code: Trivy misconfiguration scans for supported repo config files, OpenTofu validates Cloudflare edge config, plus R9lab Compose render and deploy secret path checks.
- Source code: CodeQL.
- Secrets: Gitleaks.
- GitHub Actions workflows: actionlint and Zizmor.
- Repository hygiene: OpenSSF Scorecard. It is advisory; accepted Token-Permissions findings:
release.ymlgrantscontents: writeto the release SBOM job, which uploads assets to the release. The workflow default ispermissions: {}.container-images.ymlhas no top-levelpermissions: it is a reusable workflow and runs with the job-level permissions each caller grants, which differ between scan and release mode. A fixed block in the called workflow would fail the caller that grants less.
Use just security for local maintainer diagnosis: it runs the dependency audits and the Gitleaks
secret scan. Trivy, CodeQL, actionlint, Zizmor, and Scorecard run in CI.
Release SBOM assets are attested as files and uploaded with GitHub releases.
Automated checks do not replace reviewer judgment. For changes that touch authentication, authorization, uploads/media, RPi camera or device flows, admin APIs, deployment, secrets, dependencies, or personal data, confirm:
- authorization is enforced server-side; hiding an upload affordance from a client that lacks the role is a UX choice, never the control
- input is validated at API, upload, form, and device boundaries
- browser-rendered values stay on framework escaping paths; raw HTML sinks and dynamic URLs are isolated, validated, and tested
- logs do not include tokens, passwords, private URLs, OAuth material, or other sensitive values
- secure defaults fail closed in production and staging
- auth, permission, upload, and device-flow behavior has focused test coverage
Filtering a route out of a public OpenAPI schema hides it from the docs, not from attackers. Authorization must be enforced in backend dependencies and services regardless of which schemas list the route.