Secrets Management Guide

Storage Backends

Backend	Crate	Use case
Kubernetes secrets	`k8s-openapi`	K8s-deployed control plane
External Secrets Operator	operator	Sync from AWS/GCP/Azure secret stores
HSM (PKCS#11)	`pkcs11`	Air-gapped appliance

Rotation

Each secret has:

rotation_period_days (default: 90).
last_rotated_unix_nano.
next_rotation_due_unix_nano.
grace_period_days (default: 7; old keys still decrypt during grace).

agents/denpex-control-plane/src/secrets/rotation.rs enforces rotation. A secret whose next_rotation_due is past emits a Prediction::SecretStale event.

Reference Resolution

Secrets in environment files use the syntax ${vault://path/to/secret#field}. The control plane resolves each reference at startup, caches it in a memory-only secrets_cache, and never writes the resolved value to disk.

Access Pattern

Every secret access emits an audit record:

{
  "timestamp_unix_nano": 1700000000000000000,
  "actor": "denpex-control-plane@tenant=acme",
  "action": "secret.read",
  "policy": "RBAC+ABAC",
  "evidence": {"secret_path": "vault://prod/otlp/token", "tenant": "acme"},
  "affected_resources": ["vault://prod/otlp/token"],
  "outcome": "ok",
  "previous_hash": "...",
  "current_hash": "..."
}

Per-Tenant Isolation

Vault policies (one per tenant) restrict secret paths to a tenant prefix. A compromised tenant cannot read another tenant's secrets.

HSM-Backed Root

The air-gapped appliance stores the master wrapping key in a PKCS#11 HSM (Thales, AWS CloudHSM, YubiHSM2). The K8s secrets backend is unavailable — only the HSM is consulted for secrets that wrap the local S3 root keys.