runbook-secret-rotation

name	runbook-secret-rotation
enabled	true
description	Use when performing runbook secret rotation — secret and credential rotation procedure covering discovery, rotation execution, deployment, and validation. Use for scheduled credential rotation, responding to leaked secrets, or compliance-driven key rotation.
required_connections	[]
config_fields	[{"key":"secret_type","label":"Secret Type","required":true,"placeholder":"e.g., database password, API key, TLS certificate"},{"key":"secret_name","label":"Secret Name / Identifier","required":true,"placeholder":"e.g., prod/db/primary-password, stripe-api-key"},{"key":"rotation_reason","label":"Rotation Reason","required":true,"placeholder":"e.g., scheduled rotation, suspected compromise, employee offboarding"},{"key":"affected_services","label":"Services Using This Secret","required":false,"placeholder":"e.g., api-service, payment-worker, auth-service"}]
features	["RUNBOOK","SECURITY"]

Secret Rotation Runbook Skill

Rotate {{ secret_type }}: {{ secret_name }} Reason: {{ rotation_reason }} | Services: {{ affected_services }}

Workflow

Phase 1 — Secret Discovery and Audit

SECRET DISCOVERY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SECRET DETAILS
  Type: {{ secret_type }}
  Name/ID: {{ secret_name }}
  Storage: [Secrets Manager / Vault / env vars / config files]
  Last rotated: ___
  Rotation policy: every ___ days
  Current version: ___

CONSUMERS
[ ] Identify all services using this secret:
    Service: ___ | How consumed: [env var / mounted secret / API call]
    Service: ___ | How consumed: [env var / mounted secret / API call]
    Service: ___ | How consumed: [env var / mounted secret / API call]
[ ] Identify CI/CD pipelines referencing this secret
[ ] Identify third-party integrations using this credential
[ ] Check for hardcoded references in code repositories
[ ] Check for references in configuration management

URGENCY ASSESSMENT
[ ] Is this a suspected compromise? YES / NO
  If YES: treat as emergency, skip to Phase 3 immediately
[ ] Is there a compliance deadline? ___
[ ] Can we do a rolling rotation (dual-credential period)? YES / NO

Phase 2 — Pre-Rotation Preparation

PRE-ROTATION PREPARATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] Verify secret management system is healthy
[ ] Confirm rollback procedure (can old secret be restored?)
[ ] Notify service owners of upcoming rotation
[ ] Schedule rotation window (if non-emergency)
[ ] Verify all consumer services support graceful secret reload
[ ] Test rotation procedure in staging environment
[ ] Prepare new credential value:
    - Generate with appropriate strength/length
    - Meets complexity requirements: YES / NO
    - Does NOT resemble previous value: YES / NO

Phase 3 — Rotation Execution

ROTATION EXECUTION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STEP 1: CREATE NEW SECRET
[ ] Generate new credential value
[ ] Store as new version in secret manager
    New version ID: ___
[ ] Verify new secret is retrievable

STEP 2: DUAL-CREDENTIAL PERIOD (if supported)
[ ] Configure target system to accept BOTH old and new credentials
    - Database: CREATE new user or ALTER password while keeping old session
    - API key: Add new key to allowlist before revoking old
    - TLS cert: Deploy new cert alongside old one
[ ] Verify old credential still works
[ ] Verify new credential works
[ ] Record dual-credential start time: ___

STEP 3: DEPLOY NEW SECRET TO CONSUMERS
  For each service in {{ affected_services }}:
  [ ] Service: ___ — updated to new secret version
      Method: [restart / rolling deploy / hot reload / env refresh]
  [ ] Service: ___ — updated to new secret version
  [ ] Service: ___ — updated to new secret version
  [ ] CI/CD pipelines updated
  [ ] Third-party integrations updated

STEP 4: REVOKE OLD SECRET
[ ] Confirm all consumers using new secret (no auth with old)
[ ] Revoke / disable old credential
[ ] Record revocation timestamp: ___

Phase 4 — Post-Rotation Validation

POST-ROTATION VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AUTHENTICATION HEALTH
[ ] All services authenticating successfully with new secret
[ ] No authentication failures in logs (401s, connection refused)
[ ] No services still using old credential
[ ] API response times unaffected

SERVICE HEALTH (check each consumer)
[ ] Service: ___ — healthy, using new secret
[ ] Service: ___ — healthy, using new secret
[ ] Service: ___ — healthy, using new secret
[ ] CI/CD pipeline test run successful with new secret
[ ] Scheduled jobs executing with new secret

SECURITY VERIFICATION
[ ] Old credential confirmed revoked (test fails as expected)
[ ] Audit log shows rotation event
[ ] No copies of old secret in temporary files or logs
[ ] Secret not exposed in environment dumps or error messages

Phase 5 — Rollback Procedure

ROLLBACK (if new secret causes issues)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. [ ] Re-enable old credential on target system
2. [ ] Revert consumer services to previous secret version
3. [ ] Verify services authenticating with old credential
4. [ ] Investigate why new credential failed
5. [ ] Re-attempt rotation after fixing root cause

NOTE: If rotation was due to compromise, DO NOT rollback.
      Instead, generate a different new credential.

Phase 6 — Documentation and Automation

DOCUMENTATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] Update secret rotation log:
    Secret: {{ secret_name }}
    Rotated: [timestamp]
    Reason: {{ rotation_reason }}
    Old version: ___ (revoked)
    New version: ___
    Next rotation due: ___
[ ] Update rotation schedule / calendar
[ ] If manual: create automation ticket to auto-rotate this secret
[ ] Review and update consumer service documentation
[ ] Close change management ticket

Counter-Rationalizations

Shortcut	Counter	Why
"We can skip some steps for this case"	Adapt the workflow steps, don't skip them	Skipped steps are where incidents and oversights originate
"The user seems to already know what to do"	Complete all workflow phases with the user	The workflow catches blind spots that experience alone misses
"This is a minor case, full process is overkill"	Scale the process down, don't turn it off	Minor cases become major when unstructured; the process scales, not disappears
"I'll fill in the details later"	Complete each section before moving on	Deferred details are forgotten; real-time capture is more accurate
"The template output isn't necessary"	Always produce the structured output format	Structured output enables comparison, audit trails, and handoff to other teams

Output Format

Produce a secret rotation report with:

1. Rotation summary (secret type, name, reason, timestamps)
2. Consumer inventory of all services updated
3. Execution log with dual-credential period and revocation
4. Validation results (authentication health per service)
5. Security confirmation (old credential revoked, no leakage)
6. Next rotation scheduled date