Skip to main content

Runbook: secret rotation overdue

Alert source: packages/testkit/alerts/security.rules.yaml

Canonical markdown: docs/runbooks/secret-rotation-overdue.md

Severity: warning.

Symptom​

Secret at ref {{ ref }} on provider {{ provider }} has not rotated in over 180 days. The rotation monitor warns before it hits the configured errorAfterDays threshold.

Likely cause​

  1. The secret was deployed before the rotation policy took effect.
  2. Rotation automation is broken on the provider side.
  3. The secret owner forgot — it's a human-managed credential.

Immediate mitigation​

Rotate the secret:

declaragent secrets rotate <ref>

This resets the provider's lastRotatedAt and silences the alert.

Root-cause investigation​

# Full secret metadata:
declaragent secrets describe <ref>

If the ref belongs to a rotation-automation pipeline that's stuck, open a ticket with the platform team. If it's human-managed, reassign ownership so rotation lands on a schedule.

Post-incident​

  • Capture: ref, provider, last rotation timestamp, new rotation date.
  • Close when: the ref's lastRotatedAt (via declaragent secrets describe <ref>) is < 90d old. (The secret_rotation_age_seconds gauge this alert is contracted on is not emitted yet — backlog #65.)