Security¶
This page describes what the operator protects, from whom, and how. It also explains how to verify a release. To report a vulnerability, see SECURITY.md.
The full threat model, with data flows, trust boundaries, STRIDE threats per boundary and the open gaps, is security/threat-model.md. The deployment checklist that follows from it is security/hardening.md.
Threat model¶
Assets¶
| asset | where it lives |
|---|---|
| OpenBao configuration: policies, auth roles, mounts, identities; together they decide who can read which secret | OpenBao, declared by custom resources |
| connection credentials: tokens, AppRole secret IDs, ServiceAccount tokens | Kubernetes Secrets, the TokenRequest API, files in the operator pod |
| secret inputs: passwords, JWTs, client secrets | Kubernetes Secrets referenced by <field>SecretRef |
| one-time outputs: secret IDs, OIDC client secrets, exported private keys | Kubernetes Secrets written through writeSecretRef |
the hash key of status.writeOnlyHash |
the hash-key Secret in the operator namespace |
Actors¶
| actor | can | cannot |
|---|---|---|
| platform admin | create connections of both kinds, install the operator, write OpenBao policies | - |
| tenant (namespace admin or editor) | create and edit resources in its namespace through the <release>-tenant-editor role, aggregated into admin and edit |
create or edit connections, write resource status, act with any OpenBao identity but the one of its namespace's connection |
| compromised tenant | everything the tenant's OpenBao policy allows, inside the tenant's OpenBao namespace | reach the root or a sibling OpenBao namespace, borrow the operator's identity, read Secrets of other Kubernetes namespaces through the operator |
| compromised operator pod | everything its Kubernetes RBAC and every connection's OpenBao policy allow | - |
The OpenBao policy behind each connection identity is the real limit. The operator adds no authority of its own on top of it.
The tenant boundary¶
- A namespaced
OpenBaoConnectionserves only resources in its own namespace. - Its Kubernetes and JWT auth must name a
serviceAccountRefin its own namespace. The CRD rejects a connection without one, and the resolver refuses it again (serviceAccountRef is required for a namespaced connection) if the CRD validation was bypassed. The operator requests a 10-minute token for that ServiceAccount through the TokenRequest API and uses it for one login. A namespaced connection can never log in as the operator. audiencesis required on those connections, so the token sent to OpenBao is never valid against the Kubernetes API server. Connections have no address: only the platform'sOpenBaoServersets where the token goes, and it must be https unlessallowInsecureHTTPis set.- Injected identity and token files exist only on
ClusterOpenBaoConnection, which only platform admins create.spec.allowedNamespaceslimits which namespaces may use it; without it, no namespace can, and{}admits every namespace. - The
<release>-tenant-editorrole grants every namespaced kind exceptOpenBaoConnection, and onlygeton status subresources. Tenants therefore cannot choose an identity, and cannot forgestatus.pathto steer a deletion. - Secret references in a resource resolve in the resource's own namespace. A tenant cannot make the operator read another namespace's Secret.
writeSecretRefnever takes over an existing Secret that the resource does not own: the operator fails with "the Secret exists and is not controlled by this resource".
See ADR 0003 for the decision.
Follow a tenant request¶
For a namespaced connection using Kubernetes authentication, the path is:
flowchart LR
resource["Tenant custom resource"] --> connection["OpenBaoConnection in the same Kubernetes namespace"]
connection --> request["TokenRequest for the tenant ServiceAccount"]
request --> login["OpenBao Kubernetes auth role"]
login --> policy["Scoped OpenBao ACL policy"]
policy --> path["Managed path in the connection's OpenBao namespace"]
The operator orchestrates these requests, but the OpenBao token carries the connection identity's permissions. Kubernetes RBAC decides who can edit the resource; the connection and server admission rules decide which identity and server it can use; OpenBao ACLs decide which operations succeed. A broad OpenBao policy remains broad even when the Kubernetes resource has a narrow name.
The two-tenant tutorial provides a concrete configuration to try. Use tenant-scoped operator policies when granting configuration rights, and follow the hardening checklist before sharing a deployment between teams.
OpenBao namespace escape¶
A resource's spec.namespace is relative to its connection's namespace. Four checks keep it
inside:
- The CRD pattern allows only segments that start with a letter, digit,
_or-, separated by single slashes. A leading slash, an empty segment,.and..are rejected at admission. The connection'snamespaceandauthNamespacehave the same pattern. - The engine rejects a namespace with an empty,
.or..segment, or a first segmentroot, with the reasonInvalidSpec. - The client joins the relative namespace to the base without resolving
.or... A..segment that reached it anyway becomes an invalid segment, which OpenBao refuses, so the request fails instead of climbing out of the base namespace. - On deletion, the namespace recorded in
status.namespacemust lie inside the connection's current namespace. Otherwise the operator refuses to delete and asks fordeletionPolicy: Orphan.
spec.namespace and connectionRef are immutable. If the connection's own namespace changes
after a resource acquired its object, the resource stops with NamespaceChanged instead of
writing a second object elsewhere.
Write-only inputs¶
OpenBao does not return passwords, JWTs and client secrets on read, so the operator cannot compare
them. It records status.writeOnlyHash instead and writes again when the hash changes.
The hash is an HMAC-SHA256 of the canonical JSON of the write-only values, keyed by a random
32-byte key in the hash-key Secret (openbao-config-operator-hash-key by default, set with
--hash-key-secret). Anyone who can read the status therefore cannot test guesses of a
low-entropy password offline. The manager creates the key when the Secret is absent, as an
immutable Secret. Protect it like any other Secret in the operator namespace.
Logs, events and status¶
- Logs never contain tokens, secret values or OpenBao response bodies.
- OpenBao errors keep only OpenBao's error strings, never a raw body. Write-only values that
OpenBao echoes in an error message are replaced with
<redacted>before the error reaches the status or the logs. Updatedevents name the keys that differed, never their values.- Status holds paths, IDs, accessors and the HMAC, never secret values.
- The operator does not copy secret values from OpenBao into Kubernetes. It writes a Secret only for a value OpenBao returns once (ADR 0007).
Environment isolation¶
- Run one operator installation per environment, and give each connection only the OpenBao it belongs to. A development cluster must not hold a connection to production OpenBao.
- Use a separate OpenBao identity, and policy, per connection. Do not share a token between connections or environments.
- Select only platform namespaces in a
ClusterOpenBaoConnection'sallowedNamespaces; never use{}. - Secret values stay in OpenBao. Workloads read them with External Secrets Operator or an OpenBao agent, with their own identity, not through this operator.
Kubernetes RBAC¶
| scope | grants | when |
|---|---|---|
ClusterRole <fullname>-manager |
OpenBaoServer and ClusterOpenBaoConnection with their status and finalizers; get, list, watch on Namespaces; GET /.well-known/openid-configuration |
always |
| same ClusterRole | the namespaced kinds with their status and finalizers; Secrets (get, list, watch, create, update, patch), ConfigMaps (read), serviceaccounts/token (create), Events |
watchNamespaces empty |
Role <fullname>-manager per listed namespace |
the namespaced rules of the previous row | watchNamespaces set |
Role <fullname>-manager in the release namespace |
get on the hash-key Secret, create on Secrets |
watchNamespaces set without the release namespace |
Role <fullname>-leader-election |
Leases and Events in the release namespace | leaderElection.enabled |
ClusterRoles <fullname>-metrics-auth, <fullname>-metrics-reader |
TokenReviews and SubjectAccessReviews for the metrics endpoint; GET /metrics for scrapers |
metrics.enabled |
create on serviceaccounts/token lets the manager mint a token for any ServiceAccount in the
namespaces it covers. Set watchNamespaces to the namespaces that hold connections and their
references, so a compromised manager cannot impersonate ServiceAccounts elsewhere. The default install is
cluster-wide, which the threat model lists as residual risk
RR-01.
The manager pod runs as non-root user 65532 on a distroless image, with a read-only root
filesystem, no capabilities, no privilege escalation and the RuntimeDefault seccomp profile.
The metrics endpoint requires an authenticated and authorised client. HTTP/2 is off by default on
the metrics server (--enable-http2).
Supply chain¶
- Images are built for amd64 and arm64 from base images pinned by digest; the runtime image is
distroless and runs as 65532. Builds are reproducible:
SOURCE_DATE_EPOCHfrom the commit,-trimpath, no VCS stamping, rewritten layer timestamps, OCI labels from the build arguments. - The release workflow runs only on a
v*tag, after the full CI suite, and refuses to overwrite an existing release, image tag or chart version. It pushes the image by digest, gates on high and critical vulnerabilities (hack/release/scan.sh, dated and justified exceptions only), then signs and attests before it tags. - The image index, each platform image and the chart are signed with keyless cosign, using the workflow's GitHub OIDC identity, so no cosign key exists to leak.
- From v0.3.0 the chart also carries a Helm provenance file (
.tgz.prov) signed with a GPG key that is stored as a secret of thereleaseenvironment. Artifact Hub shows the chart as signed because of it. The GPG signature proves who packaged the chart; the cosign signature also proves which workflow run built it. - SPDX and CycloneDX SBOMs and build provenance (its two forms and their SLSA levels are in
verify the release) are attached as signed attestations; the chart carries a
CycloneDX SBOM of itself and the image it pins. Release assets are covered by a signed
sha256sums.txt. - The released chart pins the image index by digest.
- Workflow actions are pinned by commit SHA, workflow and Makefile container images by digest, downloaded tools by version and checksum. Renovate updates all of them after a minimum release age of three days.
make release-dry-run(and a manual run of the release workflow) performs every step locally with a throwaway key and verifies the result, without publishing.
Verifying releases¶
The commands, and a script that runs all of them, are in hardening.md.