Security

Security in knext is not a milestone to defer — these controls run through every phase. The non-negotiable rule: no unauthenticated mutating endpoints, ever. Several controls are enforced automatically; the rest are documented guarantees knext holds to.

No unauthenticated mutating endpoints

Any route that changes state requires auth. Two app routes mutate cache state, and both require a Bearer token:

The token check is:

• Fail-closed — if CACHE_INVALIDATE_TOKEN is unset or empty, nothing is authorized. An unconfigured deployment rejects all invalidations rather than leaving the endpoint open.
• Constant-time — comparison uses timingSafeEqual so the token cannot be recovered via response timing (length is checked first, which does not leak the secret).

The token is provisioned from a Kubernetes Secret into the CACHE_INVALIDATE_TOKEN env var — never hardcoded.

The browser RUM beacon POST /api/rum is a deliberate, justified exception — a bounded metrics aggregator, not a write primitive. See Observability → RUM for the full rationale.

Network isolation

Auth is one factor; network isolation is the second. knext reconciles a default-on Kubernetes NetworkPolicy for your app automatically.

• Object: a NetworkPolicy named <app>-allow-ingress, tied to your app's lifecycle (garbage-collected on delete).

• Targets: the app's serving pods (selected by serving.knative.dev/service: <app>).

• Allows ingress from: the knative-serving and kourier-system namespaces (so scale-from-zero traffic keeps flowing) on the serving and metrics ports, plus same-namespace pods on the metrics ports only. Everything else — arbitrary cross-namespace and external pod-direct traffic — is denied.

• Ports are restricted, and your app's own port is not among them. The policy admits the Knative queue-proxy ports (8012/8013, plus 8112 for internal TLS), the queue-proxy metrics port (9090) and knext's app-metrics port (9464). Your app's container port is deliberately excluded: the queue-proxy reaches it over pod-local loopback, which no NetworkPolicy governs. The effect is that a pod sharing your namespace can no longer dial your app container directly and bypass the queue-proxy — and with it your concurrency limit.

• Scraping from another namespace requires a label on that namespace. If your Prometheus runs outside your app's namespace, label its namespace and it may scrape the app metrics port (9464) — and only that:

  kubectl label namespace monitoring knext.dev/metrics-scrape=true

  Without the label, cross-namespace scraping is denied — including for knext's own shipped PodMonitor. A labelled namespace never gains your app's serving ports.

• Toggle: spec.security.networkPolicy (*bool). nil (unset) or true reconciles the policy (default-on); false skips it and deletes any existing one on the next reconcile.

knext tells you which case you are in instead of leaving it silent. The operator reports a NetworkPolicyEnforced condition on every NextApp: True when a NetworkPolicy-enforcing agent (Calico, Cilium, kube-router, Weave Net, Antrea, Canal) is detected on the cluster, False when flannel is the CNI — there the policy is declarative only: it is written but enforces nothing — and Unknown when the CNI cannot be identified. Treat Unknown as unenforced until you verify it; a detector that guessed "enforced" would be worse than none. knext doctor runs the same read-only detection as a preflight check. Note that flannel is what OrbStack and stock OKE clusters run — on those, treat network isolation as absent unless you install a policy-capable CNI.

Read-only root filesystem

Defense in depth against in-container tampering: knext renders your app's container with a read-only root filesystem by default.

• Toggle: spec.security.readOnlyRootFilesystem (*bool). nil (unset) or true renders readOnlyRootFilesystem: true on the container (default-on); false keeps a writable root, the pre-existing behavior.
• No extra volume is mounted by default. Writable scratch volumes cost pod-startup time on every scale-from-zero wake, so knext only provisions one when your app's image actually needs it. When knext deploy builds the image itself and knows it writes nothing to local disk, it sets spec.security.writeFree: true on your NextApp, and the operator then mounts no writable volume at all. That covers:
  • vinext apps built as a disk-mode binary (the default): image optimization loads its native library from the image's read-only native/ directory.
  • Standalone (Node/Bun) apps with object storage (spec.storage) that use the knext cache handler (every knext create app does): the knext adapter turns on Next's images.customCacheHandler option, so optimized images are stored through the cache handler instead of .next/cache/images on disk. On the Bun runtime with Redis configured they are shared by every pod and kept across scale-to-zero. On the Node runtime, and without Redis, they are kept in each pod's memory, capped at 32 MiB by default (set KNEXT_IMAGE_CACHE_MEMORY_BYTES to change it). To keep Next's disk cache instead, build with KNEXT_IMAGE_CACHE_HANDLER=0 and set writableCache: true.
  • Self-contained standalone executables (selfContained: true on the Bun runtime), which carry no native libraries.
• Shapes that still get a volume. knext keeps a writable volume when it cannot vouch for the image:
  • A self-contained vinext binary (selfContained: true with the vinext target) gets a writable, executable /tmp, because it unpacks a native library there on the first image-optimization request.
  • A standalone app with object storage whose build still writes images to disk (a custom cacheHandler, or a Next.js version without images.customCacheHandler) gets Next's cache directory, so the image optimizer can write the variant before knext syncs it to your bucket.
  • A deploy with --image or --skip-build never sets writeFree, so these shapes keep the volumes they had before.
• Standalone apps without object storage never got a volume. The image optimizer re-computes each variant per request unless the app uses the knext cache handler, and an app with no cacheHandler configured sees its default ISR/fetch-cache writes rejected (see the callout below).
• Opt in to the old, always-mounted behavior with spec.security.writableCache: true — this mounts both the /tmp scratch volume and (standalone target only) Next's cache directory unconditionally, regardless of your build shape, storage configuration or writeFree. Use this if you want the image-optimizer's local cache to persist across requests on the standalone target with no object storage configured, or if your app has no cacheHandler and you want its default on-disk ISR fallback to actually persist rather than fail silently.
• What this does not affect: the baked, build-time code cache your runtime warms into the image stays fully readable; a read-only root only removes the (already rare) ability to add a new entry to it at request time, never the ability to read what shipped.

Digest pinning

knext rejects mutable image tags everywhere.

• :latest is rejected. An app whose image is :latest, tag-only, or untagged is marked Degraded (reason InvalidImage) and never deployed — a ref is accepted only if it is digest-pinned (@sha256:).
• knext's own images are digest-pinned too. A build-time check fails if any internal deployment manifest references a non-pinned tag, so knext never ships a mutable image reference.

See Operator → Security defaults.

Supply chain

Both the app image and the operator image go through the same supply-chain pipeline, with a strict ordering: build → SBOM → scan gate → push → sign. Nothing reaches the registry before it passes the scan, and signing happens on the digest that was actually pushed.

• SBOM per image — generated with syft (SPDX-JSON), published as an artifact and attested.
• Vulnerability scan as a push gate — Trivy scans the exact image (as a local OCI layout) for HIGH,CRITICAL findings before it is pushed. A failing scan means the image is never published — not "published but flagged."
• Signing + attestation on the pushed digest — cosign keyless signing (OIDC / Sigstore) of the digest that was pushed, plus an SBOM attestation (cosign attest --type spdxjson) bound to that digest.
• SLSA provenance — the build carries a BuildKit SLSA provenance attestation, and the pipeline asserts it survived the push before anything is signed.
• Digest-pinned release bundle — the operator's install.yaml release asset is regenerated with the real pushed digest of the operator image, so what you kubectl apply is exactly what was scanned and signed. See Installing knext.

Runtime hardening

• Distroless, non-root. The operator image is gcr.io/distroless/static:nonroot running as UID 65532; the app image runs as non-root UID 65532.
• No token automount. knext sets AutomountServiceAccountToken: false on the app's ServiceAccount.
• Graceful shutdown. On SIGTERM the server drains in-flight requests and runs after() callbacks before exit, then closes the metrics server — no dropped requests on scale-down. On the standalone targets the supervisor forwards the signal to Next.js; on the vinext targets (the Bun executable and the Node server) the app's server entry does the drain itself. It waits for every after() callback, including work that an after() callback schedules while the drain is already running. The drain has a hard cap (SHUTDOWN_GRACE_MS) kept below the pod's terminationGracePeriodSeconds; on the vinext targets, work still running at the cap is cut off and the process exits with code 1. On the standalone targets the process still exits with code 0 at the cap, but first logs a warning whose message starts with [knext] shutdown (where the server writes JSON logs, that text is the log line's msg field) and says what it cut off: the number of in-flight requests it dropped where the process can count them, or that the number is unknown where it cannot. If that warning shows up in your pod logs, raise SHUTDOWN_GRACE_MS or find the request or after() callback that never finishes. Apps created before this behaviour shipped carry an older knext-bun-entry.mjs that exits without waiting for after() work. Copy knext-bun-entry.mjs and runtime-contract.mjs from a freshly created app into yours to pick it up.

Secrets

Secrets live in Kubernetes Secrets / env only — never in config files, source, container images, or URLs. knext provisions them (via spec.secrets — envFrom / envMap) and the app reads them from the environment.

Operator permissions

The operator runs with a least-privilege ClusterRole (config/rbac/role.yaml in the install bundle) and, in particular, no permission on core Secrets — no get, list, watch, or any write verb, cluster-wide or in any namespace. Your spec.secrets entries are passed to the kubelet as references (envFrom.secretRef, valueFrom.secretKeyRef), and the kubelet reads the Secret when your pod starts. You can verify what an installed operator may do:

kubectl auth can-i list secrets --all-namespaces \
  --as=system:serviceaccount:kn-next-operator-system:kn-next-operator-controller-manager
# no

What the operator does still hold, so you can size the risk accurately: create/update/delete on the Knative Services, ServiceAccounts, NetworkPolicies, image-prewarm DaemonSets, and Kafka sources it manages, and read-only access to PersistentVolumeClaims and Knative Revisions. Anyone allowed to create a NextApp can reference a Secret in their own namespace by name, so restrict who may create NextApp resources with ordinary namespace RBAC.

This removes the operator's direct access to Secrets, not every path to them: because it can create workloads cluster-wide, a compromised operator could still reach a Secret through a pod it creates. Install the operator per namespace, or add an admission policy, to close that path.

See also: Operator & the NextApp CRD · Observability · Scale-to-zero.