Security

etcd typically holds secrets — Kubernetes API objects include passwords, tokens, certificate material — so threat-model rigor is non-negotiable. This page summarizes the trust boundaries and where to find each control in the code.

Reporting vulnerabilities

security/README.md and security/security-release-process.md define the embargoed-disclosure flow. PGP keys for the security team are tracked in security/. Do not file vulnerabilities as public GitHub issues.

Trust boundaries

graph LR
    subgraph internet[Public network]
        client[Untrusted client]
    end
    subgraph cluster[etcd cluster]
        m1[Member 1]
        m2[Member 2]
        m3[Member 3]
    end
    operator[Operator / etcdctl]

    client -->|TLS + RBAC| m1
    operator -->|TLS + RBAC + maintenance| m1
    m1 -.peer TLS.- m2
    m2 -.peer TLS.- m3

Boundary	Control	Source
Public client → member	TLS, optional client-cert auth, RBAC	server/embed/config.go::ClientTLSInfo, server/auth/, server/etcdserver/api/v3rpc/interceptor.go
Operator	Same as client + Maintenance permissions	server/etcdserver/api/v3rpc/maintenance.go
Member ↔ Member	Peer TLS, optional peer client-cert auth	server/embed/config.go::PeerTLSInfo, server/etcdserver/api/rafthttp/transport.go
Disk	OS file permissions; bcrypt-hashed passwords; no encryption at rest in tree	server/auth/store.go (bcrypt), operators handle disk encryption out-of-band

TLS

• Auto-TLS (--auto-tls, --peer-auto-tls) generates self-signed certs on first start — appropriate only for testing.
• For production, certs are loaded from --cert-file, --key-file, --trusted-ca-file (and the peer equivalents).
• TLS minimum version defaults to TLS 1.2 (DefaultTLSMinVersion = string(tlsutil.TLSVersion12)). Cipher allowlist is configurable via --cipher-suites.
• Certificates are validated against allowed CN / hostname (--allowed-cn, --allowed-hostname) for inter-peer authentication.

Authentication

Two token formats:

• simple — opaque, server-side stored, default 5-minute TTL. Easy and stateless on the client; tokens can be invalidated centrally.
• jwt — RS256 / PS256 / ES256 / ES384 / ES512 / EdDSA signed JWTs verified by server/auth/jwt.go. Stateless, federation-friendly, but compromised keys are forever.

Configuration is done via --auth-token=<provider>,<options>.

Authorization (RBAC)

Per-key range permissions (READ, WRITE, READWRITE) attached to roles, granted to users. The full model is documented under systems/auth. Highlights:

• Permissions are checked on every gRPC call by the auth interceptor (server/etcdserver/api/v3rpc/interceptor.go).
• A per-user interval tree (server/auth/range_perm_cache.go) accelerates checks.
• The root role is special — required before auth can be enabled.

Recent CVE/RBAC fixes

The latest commits at wiki time (70a2b4871, 4bc674b79, d97dfbc3b, c5893b5e6) closed three RBAC-bypass corner cases:

1. Put with prev_kv=true nested in a transaction read the previous value without checking read permission on the key.
2. Put with lease=N nested in a transaction attached the put to a lease the user might not own.
3. Range reading via prev_kv likewise bypassed read perms.

The fix consolidated the put-side permission logic into a single checkPutAuth helper (commit 778237265). The changelog entries are in CHANGELOG/CHANGELOG-3.6.md and CHANGELOG-3.7.md.

Audit logging

etcd does not write a structured audit log, but every write entry is in WAL with the originating user (when auth is on). Operators wanting full audit logs typically run a sidecar or use the gRPC interceptor hooks.

Fuzzing

• make fuzz runs the registered Go fuzz targets, including server/etcdserver/api/v3rpc/validationfuzz_test.go.
• The 2022 third-party fuzzing audit (security/FUZZING_AUDIT_2022.PDF) drove additional hardening of the gRPC validation paths.

Static analysis and supply chain

• .github/workflows/codeql-analysis.yml runs CodeQL on every push.
• .github/workflows/scorecards.yml publishes OpenSSF Scorecard data.
• bill-of-materials.json and bill-of-materials.override.json document every dependency's license.
• make verify-mod-tidy and make verify-gomodguard keep the dependency graph honest.

Hardening checklist for operators

The shortened version (full list is at https://etcd.io/docs/latest/op-guide/security/):

• Enable peer TLS and client TLS with mutual authentication.
• Use auth enable and create per-application users, never share root.
• Set --quota-backend-bytes, --max-request-bytes, and the gRPC keepalive flags consistent with the workload.
• Run on encrypted-at-rest volumes; etcd does not encrypt the bbolt file itself.
• Monitor etcd_server_has_leader and etcd_disk_* series; both are early-warning signals.