Secret Rotation and Audit

Storing a credential securely is only half the job. The other half is proving it hasn't gone stale and proving who touched it. The Versus Vault does both: it can rotate a secret on a schedule or on demand — pushing the new credential all the way onto the device it belongs to and verifying it before committing — and it records every read, write, checkout, reveal, and rotation in a tamper-evident, hash-chained audit trail.

This page covers how rotation works under the hood, how you operate it, and how the audit chain gives you an evidence trail you can hand to an auditor. For how secrets are stored and encrypted, start with Secret Vault.

---

Rotation at a glance

A secret in the vault can carry a rotation policy. The policy says how often the secret should change and whether it should also change automatically after certain high-trust events:

Policies are defined once and then attached to secrets, so a single policy such as device-creds-90d can govern every device credential in your estate. A default policy is seeded out of the box so the Rotation Dashboard isn't empty:

python manage.py seed_vault_rotation_defaults
# → rotation policy 'device-creds-90d' created
#   (interval_days=90, rotate_on_checkin=true, rotate_on_reveal=true)

---

How rotation works under the hood

Rotation is two-phase and fail-safe: the old credential stays current until the new one is proven to work. For a device credential the engine runs:

1. Generate — a fresh 24-character random password is generated with a cryptographically secure RNG.
2. Push — Versus connects to the device with the current credential and changes the account's password to the new value.
3. Verify — Versus re-authenticates to the device with the new password. If verification fails, it attempts to restore the old password and raises an error — the vault version is never advanced.
4. Commit — only after a successful verify does the engine write a new secret version into the vault and stamp last_rotated_at on the policy.

Because the vault keeps every version, a rotation is additive: the new value becomes the current version and prior versions remain for history and audit. See version history under Secret Vault.

Device credential changers

Pushing a password onto a device is vendor-specific, so the engine dispatches to a per-vendor credential changer. Each changer knows both how to change the account password and how to verify it afterward, using the device's own management API or CLI:

If a secret's device has no changer for its vendor, rotation doesn't fail silently — the engine returns manual_rotation_required so the operator knows that credential must be rotated by hand. Device credentials are identified by their vault path convention (devices/<name>/…); the engine resolves the matching device from that path.

Non-device secrets

A secret that isn't tied to a device — an API token, a service-account password, a shared secret — is rotated in place: the engine generates a new value and writes it as a new version. There's no device to push to, so the change-and-verify device dance is skipped. Application consumers pick up the new value on their next fetch, so rotating a token your automation uses is transparent as long as the consumer reads the secret at use time rather than caching it.

---

Operating rotation

On demand

Rotate a single secret immediately from the Rotation Dashboard, or over the API. Rotation requires the rotate capability on the secret's path (see Secret Vault for the capability model):

POST /api/vault/secrets/{id}/rotate/
Authorization: Bearer <token>

200 OK
{ "status": "rotated", "device_rotated": true, "actor": "svc-netops" }

device_rotated tells you whether the new password actually reached a device (true) or the rotation only advanced the vault value (false). A vendor with no changer returns { "status": "manual_rotation_required", … } instead.

Attaching a policy to a secret

A policy only governs a secret once it's linked. Managing that link is a network-admin action, the same bar as creating the policies themselves:

POST /api/vault/secrets/{id}/rotation-policy/
{ "policy_id": 3 }

# detach:
DELETE /api/vault/secrets/{id}/rotation-policy/

Create and list the policies themselves under /api/vault/rotation-policies/.

On a schedule

Scheduled rotation is a sweep you run from cron (or a platform scheduler such as a Railway cron job). It walks every enabled policy, finds the secrets whose interval has elapsed, and rotates them:

# Nightly at 02:00
0 2 * * * python manage.py vault_rotate_scheduled

Preview what would rotate without changing anything:

python manage.py vault_rotate_scheduled --dry-run
# [DRY RUN] Checking scheduled rotation candidates...
# 2 secret(s) would be rotated:
#   device-creds-90d -> devices/edge-fw-1/credential
#   device-creds-90d -> devices/core-sw-2/credential

The sweep is careful about secrets that are in use. If a secret is actively checked out, the sweep defers it rather than yanking a credential out from under a running session — it retries on the next sweep. Each secret comes back with a status of rotated, manual_rotation_required, deferred, or error, and the command summarizes them and exits non-zero if any rotation failed, so a CI or cron wrapper can alert on it.

Event-driven rotation

Beyond the calendar, rotation can fire on the two moments a credential is most exposed:

• rotate_on_checkin — when a privileged secret is checked out for a task and then checked back in, the credential is rotated before the checkout is released. If that rotation fails, the check-in is refused and the credential is left unchanged, so you never quietly release a credential that couldn't be rolled. An admin force-release of a stuck checkout triggers the same mandatory rotation.
• rotate_on_reveal — after a break-glass reveal is consumed, the credential is rotated automatically, on the assumption that a human eyeball has now seen it. Reveals are dual-control (a second approver, no self-approval) and yield a single-use token that expires in five minutes.

Both behaviors are covered in more depth in Secret Vault; here the point is that rotation is the enforcement mechanism that makes "temporary access" actually temporary.

---

The audit trail

Every vault operation is written to two places, by design.

1. The operations audit log

A flat, queryable record lands in the platform's central audit log — the same log that captures workflow runs, logins, and config changes — with the actor, the action, and the fully-qualified secret reference (<mount>/<path>). This is what you filter and export for day-to-day review and reporting.

2. The tamper-evident vault chain

In addition to the flat log, each vault event is appended to a hash-chained ledger. Every entry carries a monotonic sequence number, the hash of the previous entry, and its own hash computed over its full payload:

hash(n) = SHA-256( seq · prev_hash · actor · action · mount · path · details · timestamp )

Because each entry commits to the one before it, the chain is append-only in effect: you cannot alter or delete a past entry without changing its hash, which breaks every link that follows. An integrity check walks the chain from the beginning and reports whether it's intact and, if not, the exact sequence number where it was broken:

{ "events": 4213, "intact": true, "broken_at": null }

A broken_at sequence number is a red flag that a row was edited or removed out from under the ledger — exactly the kind of evidence a compliance review wants to see checked. This is the same tamper-evidence pattern the platform uses for privileged-session and service-desk audit chains.

What gets recorded

The chain captures the full lifecycle of a secret, not just reads and writes:

Each entry names the actor — a human's username, an app principal (app-principal:<name>), or a system identity such as system:scheduled for the nightly sweep or system:post-reveal for a rotation that fired after a reveal — so scheduled and automated rotations are as attributable as human ones.

---

How it fits the platform

Rotation and audit close the loop that starts with device enrollment and secure storage:

• Enrollment moves a device's credential into the vault and takes it out of scattered config.
• Rotation keeps that credential fresh and revokes exposure after every privileged touch — automatically, and all the way onto the device.
• Audit proves the whole sequence happened, to whom, and in what order, in a form that resists after-the-fact editing.

Machine consumers never see this churn: automation fetches a secret by reference at the moment it's needed (see the app-principal fetch flow in Secret Vault and Collector Security), so a rotated credential is simply the value returned on the next fetch. Workflows that operate on devices likewise read credentials at run time, so a rotation that lands between two runs is invisible to the automation and fully recorded in the chain.

Together these make "the passwords rotate every 90 days and we can prove who saw what" a property of the platform rather than a manual process — which is what a security and compliance review is really asking for.

---

Related

• Secret Vault — storage, envelope encryption, capabilities, checkout, and break-glass reveal.
• Collector Security — resolving secrets locally at the edge so they never leave your network.
• F5 BIG-IP Integration — device enrollment and credential lifecycle for managed devices.
• Security & Compliance — how audit and rotation support the platform's compliance posture.
• Platform Architecture — where the vault sits in the overall stack.