Secrets Rotation Planner

What this skill does

Reads an inventory of secrets and produces a per-secret rotation plan with zero-downtime cutover. Each plan names the rotation API, the systems consuming the secret, and the verification step before disabling the old credential.

Inputs

• secrets_inventory: YAML with rows {name, kind, age_days, consumers: [{service, deploy_target}]}. Kinds include aws-iam-key, github-pat, db-password, oauth-client-secret, slack-webhook.
• Optional priority_threshold: rotate now if age_days > this (default 90).
• Optional parallel_validity_minutes: how long both old and new credentials should coexist (default 60).

Steps

1. Validate the inventory: every row must have at least one consumer; abort if not.
2. Sort secrets by age_days descending, then by kind risk (aws-iam-key first).
3. For each secret, generate a 5-step plan:
   • Step 1: Issue a new credential alongside the old (e.g., AWS access keys allow two simultaneous keys per user; PostgreSQL allows ALTER USER + dual SCRAM creds via passwordcheck-aware schemes).
   • Step 2: Update the secret store (AWS Secrets Manager / Vault / Kubernetes Secret) with the new value.
   • Step 3: Roll consumers: trigger redeploys / sidecar reloads on each deploy_target. For services that read at startup, kubectl rollout restart deployment/<name>.
   • Step 4: Verify: each consumer's health-check or equivalent confirms successful auth with the new value.
   • Step 5: Revoke the old credential after parallel_validity_minutes.
4. For credentials that don't allow two simultaneous values (e.g., Slack webhooks), schedule a brief maintenance window and document explicitly.
5. Generate per-kind commands:
   • AWS: aws iam create-access-key, aws iam delete-access-key.
   • GitHub PAT: open the user's PAT page; programmatic rotation is limited.
   • DB password: psql -c "ALTER USER ... PASSWORD ...".
6. Per consumer service, list the env var or secret ref name being rotated.
7. Emit a markdown plan plus a CSV rotation-schedule.csv for tracking.

Output

rotation-plan.md with a per-secret 5-step plan and a calendar (which secret is rotating which day) plus rotation-schedule.csv for tracking. Stdout summarizes total secrets to rotate and time estimate.

Verification

For each plan, dry-run step 4 against a synthetic environment: with the new credential issued and the old still active, confirm both authenticate (proves dual-validity is real). After the actual rotation, confirm the old credential is denied (e.g., aws sts get-caller-identity with old key returns InvalidClientTokenId). Track audit logs for any 401/403 spikes during the rollout window — those mean a consumer was missed.

Edge cases

• Secrets used by long-lived connections (database connections held for hours): use connection draining or schedule rotation during a low-traffic window.
• Secrets baked into client-side artifacts (e.g., a publishable Stripe key in a JS bundle): cannot be rotated without a redeploy and CDN purge; document the requirement.
• Secrets shared across teams: notify all owners before step 5.
• Secrets that leaked publicly: bypass the 5-step plan, rotate immediately, and treat as an incident.