Secrets Rotation Planner

Introduction:

Secrets rotation replaces an existing credential with a new trusted value, moves every dependent consumer to the new value, and then proves the old value can no longer authenticate. It matters because API keys, database passwords, OAuth client secrets, webhook signing secrets, TLS keys, and Kubernetes-mounted values often outlive the original deployment that created them. The longer a credential remains unchanged, the harder it becomes to know who can still use it and where stale copies may exist.

A reliable rotation is more than issuing a replacement. The operational risk comes from timing, dependent consumers, audit evidence, and rollback. A dual-secret cutover can keep old and new credentials valid during validation, while a single-value system may need a maintenance window because only one credential can be trusted at a time. Emergency revocation reverses the calm order: containment comes first, and the cleanup record must explain what was checked after access was blocked.

The safest plan keeps the credential value out of ordinary notes and focuses on identifiers, managers, consumers, evidence, and stop conditions. A plan should say who owns the change, how each consumer will receive or reload the new value, what proves the new credential works, what old-value reuse would look like after revocation, and when rollback is allowed. Without those details, rotation can leave a credential technically changed but operationally unclear.

A rotation plan is still a plan. It does not prove that a provider accepted the new key, that every pod or worker refreshed, or that every stale copy was destroyed. Those facts come from the manager's version metadata, runtime health checks, authentication logs, and a recorded revocation proof.

Technical Details:

Secrets rotation is governed by three timing questions: when the replacement is created, when consumers begin using it, and when the old value stops working. The low-risk path is usually a staged dual-secret cutover, because consumers can accept old and new credentials while validation runs. A single-credential rotation compresses that overlap and raises the chance that a missed consumer or cached value will break at promotion.

Dynamic secrets change the meaning of rotation. Instead of holding one long-lived value and periodically replacing it, a manager issues short-lived credentials with a lease or time-to-live (TTL). The useful control becomes lease policy, renewal behavior, and revocation evidence. Static secrets need stronger inventory and old-value cleanup because copies can survive in config, logs, sidecars, workers, and third-party integrations.

Rule Core:

The schedule is built from offsets around the chosen start time. Preparation, propagation lag, validation, revoke delay, and notification lead time change the row timestamps. Emergency mode moves block and revoke actions near the start, while single-credential mode places the maintenance cutover at the prepare-window boundary.

The risk score is a capped sum of pattern, manager, age, consumer, fallback, and timing signals. It is a planning priority, not a live compromise score.

Here, P is pattern risk, M is manager risk, A is overdue age risk, C is consumer-count risk, F is fallback-control risk, V is short-validation risk, T is the TTL credit, and D is the dynamic-secret credit. The score becomes Controlled below 31, Watch from 31 through 55, Elevated risk from 56 through 75, and High risk at 76 or above.

Manager choice changes evidence expectations. AWS Secrets Manager plans reference version labels and CloudTrail events. Vault static and dynamic plans reference audit device entries, version metadata, lease IDs, renewal logs, and revoke events. Kubernetes External Secret plans care about operator sync conditions, pod rollout events, and application authentication logs. Manual or config-managed rotation receives a higher manager risk because version labels and centralized audit evidence may be weaker.

Everyday Use & Decision Guide:

Start with Staged dual-secret cutover when the consuming systems can accept old and new credentials during the same validation window. Enter a path or friendly name in Secret identifier, not the actual credential value. Use Secret class and Secret manager to shape the checklist language, then name the accountable team in Rotation owner.

List every app, worker, scheduled job, integration, or partner in Dependent consumers. The consumer count changes the summary and risk register, but the more useful effect is operational: the schedule asks each consumer owner to report readiness or carry a documented exception. A blank consumer list creates a warning because inventory is incomplete, even if the rest of the timing looks tidy.

• Set Current secret age and Target rotation interval before trusting the due badge. A value beyond the interval appears as overdue and adds age risk.
• Turn off Consumers can accept old and new credentials for single-value systems. The old credential hold becomes 0 hours, and the summary badge switches to single-value cutover.
• Use Prepare window, Propagation lag, and Validation window to reflect real deployment timing, not only the planned meeting length.
• Keep Break-glass path verified on only when emergency access has been tested without relying on the credential being rotated.
• Use New credential TTL for lease-backed or expiring credentials. Dynamic-secret mode warns when TTL is missing.
• Write Validation checks as measurable signals, such as authentication success rate, provider usage logs, queue drain, pod rollout, or partner callback checks.

Read the summary before the tables. It shows stage count, total schedule span, manager, secret class, risk badge, overlap state, and due status. If Plan cautions appears, clear the warning or record why it is acceptable before sending the plan to a change board or incident channel.

The plan should slow down at two points: promotion and revocation. Promote only after the validation checks match the listed threshold. Revoke only after the old credential hold is complete and the risk register has no unresolved missed-consumer or rollback concern.

Step-by-Step Guide:

Build one rotation plan per credential so the schedule, checklist, risk register, chart, and JSON all describe the same change.

1. Choose Rotation pattern. Use Staged dual-secret cutover for normal overlap, Single credential maintenance window when only one value can be trusted, Dynamic or short-lived secret migration for lease-backed work, and Emergency revoke and reissue only when containment comes first.
2. Enter Secret identifier, Secret class, Secret manager, and Rotation owner. If the identifier, owner, or start time is missing, the alert shows Plan needs input and the summary primary value becomes Check input.
3. Fill Dependent consumers with one consumer per line or comma-separated names. The schedule uses that list in the consumer readiness gate, and the risk register uses the count for blast-radius risk.
4. Set Start time, Current secret age, Target rotation interval, Prepare window, Validation window, and Old credential hold. Check that Rotation Schedule places notification, inventory, pending credential, validation, promotion, revocation, and evidence archive in the expected order.
5. Open Advanced for Propagation lag, New credential TTL, Notify before start, Approval ticket, Evidence store, Break-glass path verified, and Previous credential retained for rollback until revoke. These values change warnings, risk rows, schedule notes, and evidence records.
6. Review Validation Checklist and replace generic checks with signals that an on-call engineer can observe. If a listed threshold is vague, edit Validation checks or Rollback trigger before using the output.
7. Open Risk Register and look for High or Elevated rows. Fix the input that caused the row when possible: add consumers, lengthen validation, verify break-glass access, retain rollback until revoke, or select the manager that matches the real lifecycle.
8. Use Rotation Exposure Timeline to compare old credential exposure against new credential readiness. Old exposure should reach 0% at revoke, while new readiness should reach 100% at promotion.
9. Use JSON only after the plan reads correctly. It contains the normalized inputs, summary, warnings, schedule rows, checklist rows, risk rows, and chart data for the current setup.

Interpreting Results:

The risk badge is the fastest triage cue, but the stop/go decision belongs in the rows. A Controlled score can still be unsafe if the validation checks are weak or the consumer list is incomplete. A High risk score does not prove compromise; it means the plan needs stronger controls, a smaller scope, or a more careful change window before revocation.

The planner does not contact AWS, Vault, Kubernetes, an identity provider, a database, or a webhook sender. Use provider logs, audit events, version labels, lease IDs, failed-authentication checks, and workload health signals to prove the real rotation succeeded.

Worked Examples:

Payments API key with overlap

The default-style setup uses Staged dual-secret cutover, an AWS Secrets Manager API key, 3 consumers, a current age of 82 days, a target interval of 90 days, 4 preparation hours, 24 validation hours, 30 minutes of propagation lag, and an 8 hour old credential hold. The summary reads 8 stages / 2.8 days, shows the secret as due in 8 days, and labels the plan Controlled. The useful reading is that overlap and fallback controls are healthy, but promotion still depends on the listed authentication, error-rate, and audit-log checks.

Database credential with no overlap

A production database password with Single credential maintenance window, Manual or config-managed secret, 8 dependent consumers, a current age of 145 days, and a 90 day target interval reaches High risk under the score rules. The no-overlap setting adds maintenance-window pressure, the manual manager adds weaker version evidence, the consumer count raises blast-radius risk, and the overdue age pushes the score higher. The plan should not be read as impossible; it needs a stricter window, per-consumer readiness, explicit rollback, and stronger evidence before the old value is retired.

Vault dynamic migration missing a TTL

A migration using Dynamic or short-lived secret migration with HashiCorp Vault dynamic secret receives lower risk credit for dynamic issuance, but leaving New credential TTL at 0 triggers the caution Dynamic secret migration should define a lease or TTL. Set the TTL to the intended lease duration and make the validation checks confirm lease issuance, renewal behavior if used, and revoke events.

Plan blocked by missing identity fields

If Secret identifier is empty, the alert reports Enter a secret identifier without pasting the secret value. If Rotation owner or Start time is missing or invalid, the same input review panel stops the plan. Fill those fields first, then return to Rotation Schedule and confirm that the rows are no longer blocked.

Responsible Use Note:

Use identifiers, paths, aliases, tickets, and evidence locations rather than live secret values. Planning, scoring, charting, and exports run in the browser, and there is no provider-side rotation or validation call in this planner. Copied rows, CSV files, chart images, DOCX exports, JSON output, screenshots, and shared notes can still expose sensitive operational context, so handle them as change evidence.

FAQ:

Glossary:

Pending credential

A replacement value created before it becomes the default value for consumers.

Dual-secret cutover

A rotation path where old and new credentials can both be accepted during validation.

Old credential hold

The time the prior value remains usable after promotion so rollback can still work.

Break-glass path

An emergency access method that does not depend on the credential being rotated.

Lease

A time-bound validity record for a dynamic secret, often paired with renewal and revocation behavior.

Revocation proof

Evidence that the old credential no longer authenticates and stale use is being watched.

References:

• Lambda function rotation strategies, AWS Secrets Manager User Guide.
• AWS Secrets Manager best practices, AWS Secrets Manager User Guide.
• Lease, renew, and revoke, HashiCorp Developer.
• Secrets Management Cheat Sheet, OWASP Cheat Sheet Series.