Skip to content

Security: CMLPlatform/r9lab

.github/SECURITY.md

Security Policy

Reporting a Vulnerability

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.

What to Expect

  • 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.

Supported Versions

Only the latest release and main get security fixes.

Security Baseline

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 under DATA_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-pkce cookie 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.
  • 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 /v1 route carries a rate limit; the exemptions (admin routes, device-signed camera routes, routes on the guess budget) are listed and justified in backend/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 a 400 instead 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 answers 413 past 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.json is built from UserRead, 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 a 400 past 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.py requires the read limit on every public route that lists components or returns a tree.
  • 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}/revisions and GET /components/{id}/revisions are as public as the product, but return the snapshot only to the owner and to admins (has_admin_access); everyone else gets null, 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 --sql refuses too.
  • cookie-authenticated writes: an unsafe /v1 request carrying the session cookies, and every session login, is refused with 403 when Sec-Fetch-Site is cross-site or the Origin is 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-For only when the request comes from Docker's private range (172.16.0.0/12, FORWARDED_ALLOW_IPS and TRUSTED_PROXY_CIDRS in compose.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-Key header 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 /uploads mount serves stored bytes with a content-hashed, immutable cache policy and Cross-Origin-Resource-Policy: same-site. In the dev and testing environments, where the API and the frontends sit on different ports of 127.0.0.1 and Chromium blocks the loads, the policy is cross-origin for /uploads alone. The relaxation is derived from the environment, not configured, so staging and production cannot opt into it.
  • admin APIs
    • Every /v1/admin route 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 of GET /v1/admin/users (account_guards.py).
    • No admin route sets is_verified or is_superuser: verification proves control of the mailbox, and OAuth sign-in links by email only to verified accounts.
  • 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_authenticate in device_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.
  • 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 (anonymize or delete) 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 restore replays the union of the live ledger and the newest snapshot's copy through erase_user before 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.
  • 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-verify before 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.

Automated Checks

Supply-chain and code-security checks:

  • Dependencies: GitHub Dependency Review / Dependency Graph and Renovate. Renovate runs from .github/workflows/renovate.yml as 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 to main go through a pull request with one approving review, and must pass the required CI Result check. The app bypasses the review (the protect_main ruleset) and merges what .github/renovate.json marks automerge itself. It cannot skip the check, which protect_main_checks requires with no app bypass, so a leaked key cannot reach main without a pull request that passes CI. Release tags are held by the release tags ruleset (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 the staging and prod Environments 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.yml grants contents: write to the release SBOM job, which uploads assets to the release. The workflow default is permissions: {}.
    • container-images.yml has no top-level permissions: 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.

Maintainer Review

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.

There aren't any published security advisories