Plantilla de Rotación de Secretos

Usa esta plantilla para documentar quién rota qué secretos, con qué frecuencia y con qué procedimiento — incluido el camino sin downtime para las credenciales sin las que producción no puede vivir. Para almacenar secretos de forma segura desde el principio, consulta Gestión de Secretos en Docker.

Visión General

Una clave API filtrada solo es un desastre si sigue siendo válida. La rotación limita el radio de explosión asegurando que las credenciales caduquen antes de que un atacante pueda usarlas — y además hace de auditoría, porque rotar un secreto te obliga a descubrir quién lo usa realmente. He visto una rotación de contraseña “sencilla” tumbar dashboards durante dos días porque nadie sabía que una herramienta de reporting compartía la misma credencial. El inventario es lo que evita eso.

La rotación sin proceso es caos: los servicios se rompen a mitad del deploy, alguien comparte la nueva contraseña de root por Slack y el siguiente ingeniero adivina el procedimiento. Esta plantilla coordina el ciclo de vida — inventario, cadencia, procedimiento, camino de emergencia, validación — para que la rotación sea rutina y no un simulacro de incendio.

Cuándo Usar

• Estás montando una política de gestión de secretos por primera vez y necesitas un inventario de partida.
• Una auditoría o marco de cumplimiento (SOC 2, PCI DSS, ISO 27001) exige una cadencia de rotación documentada.
• Un secreto se expuso y necesitas rotarlo sin romper producción.
• Estás migrando de secretos gestionados a mano a un vault y necesitas saber qué existe antes de moverlo.

No la uses para un reseteo puntual de credenciales — una sola clave filtrada necesita la fila de rotación de emergencia, no el programa completo.

Solución

# Programa de Rotación de Secretos

## 1. Inventario de Secretos

| Secreto | Tipo | Entorno | Ubicación | Versión Actual | Última Rotación | Próxima Rotación | Responsable |
|---------|------|---------|-----------|----------------|-----------------|------------------|-------------|
| `DB_MASTER_PASSWORD` | Contraseña | Producción | HashiCorp Vault | `v3` | `AAAA-MM-DD` | `AAAA-MM-DD` | @db-owner |
| `AWS_ACCESS_KEY_ID` | Clave API | Producción | AWS Secrets Manager | `v2` | `AAAA-MM-DD` | `AAAA-MM-DD` | @infra-owner |
| `JWT_SIGNING_KEY` | Clave de firma | Todos | Vault / HSM | `v4` | `AAAA-MM-DD` | `AAAA-MM-DD` | @security-owner |
| `TLS_CERT_API` | Certificado | Producción | Cert-manager + Vault | `v2` | `AAAA-MM-DD` | `AAAA-MM-DD` | @infra-owner |
| `GITHUB_DEPLOY_TOKEN` | Token | CI/CD | GitHub Secrets | `v1` | `AAAA-MM-DD` | `AAAA-MM-DD` | @devops-owner |

## 2. Política de Cadencia de Rotación

| Tipo de Secreto | Intervalo | Eventos Detonantes | Periodo de Gracia |
|-----------------|-----------|--------------------|-------------------|
| Contraseñas de base de datos | 90 días | Salida de empleado, sospecha de brecha | 7 días |
| Claves API de nube | 90 días | Clave expuesta en logs, cambio de política IAM | 7 días |
| Certificados TLS | Auto-renovación (30 días antes de caducar) | Alerta de caducidad de certificado | 14 días |
| Claves de firma / cifrado | 180 días | Clave comprometida, algoritmo deprecado | 14 días |
| Tokens de CI/CD | 90 días | Cambio de scope del token, cambio de acceso al repo | 3 días |
| Contraseñas de service accounts | 90 días | Cambio de rol, retirada de servicio | 7 días |
| Break-glass de emergencia | Por uso | Tras cada uso | Inmediato |

Alerta a 30, 14 y 7 días de cada fecha límite — la rotación de último minuto es donde ocurren los errores.

## 3. Procedimiento de Rotación

### Rotación de Claves Sin Downtime (Secretos de Aplicación)

1. **Genera el nuevo secreto** en Vault / secrets manager
2. **Despliega la app con dual-read:** la app acepta el secreto viejo y el nuevo
3. **Valida:** confirma que el nuevo secreto funciona en staging
4. **Actualiza consumidores:** rota los servicios de downstream uno a uno
5. **Elimina el secreto viejo:** tras el periodo de validación (24–48 horas)
6. **Actualiza el inventario:** marca la nueva versión y fecha

### Rotación de Certificados (TLS)

1. **Aprovisiona el nuevo certificado** desde la CA
2. **Despliega en el load balancer / ingress** junto al certificado existente
3. **Valida:** scan de SSL Labs + monitor sintético
4. **Espera la propagación:** asegúrate de que todas las cachés edge se refrescaron
5. **Retira el certificado viejo** de todos los endpoints
6. **Actualiza el inventario:** marca la nueva fecha de caducidad

## 4. Playbook de Rotación de Emergencia

| Detonante | Acción | Responsable | SLA |
|-----------|--------|-------------|-----|
| Secreto expuesto en repo público | Rotar de inmediato; revocar el viejo | @security-owner | 1 hora |
| Empleado con acceso a secretos desvinculado | Rotar todos los secretos a los que tenía acceso | @security-owner + @owner | 4 horas |
| Sospecha de brecha | Rotar secretos críticos; respuesta a incidentes | @security-owner | 24 horas |
| Certificado caduca en < 7 días | Reemisión de emergencia + deploy | @infra-owner | 24 horas |

## 5. Checklist de Validación

- [ ] El nuevo secreto es legible por todos los servicios esperados
- [ ] El secreto viejo está revocado / eliminado (no solo sin uso)
- [ ] Los logs de aplicación no muestran fallos de autenticación post-rotación
- [ ] Los pipelines de CI/CD pasan con el nuevo secreto
- [ ] Las alertas de monitorización están en verde durante 24 horas
- [ ] Inventario actualizado con versión y fecha de rotación
- [ ] Runbook actualizado si el procedimiento cambió

## 6. Registro de Excepciones

| Secreto | Motivo del Intervalo Extendido | Riesgo Aceptado Por | Nueva Fecha | Revisión |
|---------|-------------------------------|---------------------|-------------|----------|
| | | | | |

## 7. Métricas de Rotación

| Mes | Secretos Programados | Rotados a Tiempo | Retrasados | Tasa de Cumplimiento |
|-----|---------------------:|------------------:|-----------:|---------------------:|
| | | | | |

Explicación

La plantilla trata la rotación como un ciclo de vida, no un evento puntual. El inventario responde “¿qué tenemos?”. La cadencia responde “¿con qué frecuencia?”. El procedimiento responde “¿cómo?”. El playbook de emergencia responde “¿y si pasa?”. Y las métricas responden “¿funciona el programa?”.

La rotación sin downtime es la parte más difícil, y el modo dual-read es lo que la hace posible: la aplicación acepta el secreto viejo y el nuevo durante una ventana de transición, de modo que los consumidores migran uno a uno en lugar de en una interrupción coordinada. La checklist de validación existe porque el fallo de rotación más común no es la rotación en sí — es un cron job o un connection string cacheado que sigue usando el valor viejo tres días después.

El registro de excepciones importa más de lo que parece. Todo programa acaba con secretos que no pueden rotar en fecha (un token de proveedor con contrato de 12 meses, un sistema legacy que no soporta dual-read). Escribirlos con un aceptador de riesgo con nombre es la diferencia entre una excepción documentada y un secreto olvidado.

Dual-Read vs Ventana de Mantenimiento

No todo secreto soporta dual-read. Usa esto para elegir el procedimiento:

Enfoque	Cuándo encaja	Coste
Dual-read	La app puede leer dos secretos, o el sistema admite dos credenciales válidas (nuevo usuario de BD)	Cero downtime, más coordinación
Ventana de mantenimiento	Sistemas legacy, credenciales de un solo slot, secretos incrustados en config	Interrupción corta planificada, procedimiento más simple
Rotación canary	Consumidores desconocidos o de terceros	Radio de explosión bajo, más lenta

Si un consumidor es un tercero que no controlas, el enfoque canary del playbook de emergencia es más seguro: rota para un subconjunto, vigila fallos y completa la rotación en su timeline.

Ejemplo de Automatización de Rotación

#!/bin/bash
# Rota una contraseña de base de datos sin downtime usando el patrón
# dual-read: la credencial vieja y la nueva siguen válidas durante la transición.

set -euo pipefail

DB_HOST="db.internal"
DB_NAME="appdb"
OLD_USER="app_user_old"
NEW_USER="app_user_new"
NEW_PASSWORD=$(openssl rand -base64 32)

# 1. Crea el nuevo usuario con permisos idénticos
psql -h "$DB_HOST" -U admin -d "$DB_NAME" -c "
  CREATE USER $NEW_USER WITH PASSWORD '$NEW_PASSWORD';
  GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO $NEW_USER;
  GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO $NEW_USER;
"

# 2. Sube las nuevas credenciales al secret manager
aws secretsmanager update-secret \
  --secret-id prod/db/app-user \
  --secret-string "{\"username\":\"$NEW_USER\",\"password\":\"$NEW_PASSWORD\"}"

# 3. Rolling restart para que los pods tomen el nuevo secreto
kubectl rollout restart deployment/app -n production
kubectl rollout status deployment/app -n production --timeout=300s

# 4. Verifica que las conexiones ya usan el nuevo usuario
psql -h "$DB_HOST" -U admin -d "$DB_NAME" -c "
  SELECT usename, count(*) FROM pg_stat_activity
  WHERE datname='appdb' GROUP BY usename;
"

# 5. Tras la ventana de validación, elimina el usuario viejo
psql -h "$DB_HOST" -U admin -d "$DB_NAME" -c "DROP USER $OLD_USER;"

echo "Rotación completa. Usuario viejo eliminado."

Ejemplo: Una Entrada de Rotación Rellenada

| Secreto | Tipo | Entorno | Ubicación | Versión Actual | Última Rotación | Próxima Rotación | Responsable |
|---------|------|---------|-----------|----------------|-----------------|------------------|-------------|
| `DB_MASTER_PASSWORD` | Contraseña | Producción | Vault | `v4` | `2026-10-15` | `2027-01-13` | @db-owner |

Registro de rotación — 2026-10-15 02:00 UTC (ventana de bajo tráfico):
- Nuevo usuario `app_user_2026q4` creado con grants idénticos; staging a las 01:30.
- Secreto actualizado en Vault; rolling restart terminado a las 02:12.
- pg_stat_activity: 0 conexiones en `app_user_2026q3` a las 02:20.
- Dashboard de reporting confirmado leyendo por la réplica de analytics
  (credencial separada — no afectada).
- Usuario viejo eliminado el 2026-10-17 tras 48h limpias. Sin fallos de auth en logs.

Esa entrada responde las preguntas que hará la próxima auditoría: qué cambió, cuándo, quién lo verificó y qué pasó con la credencial vieja. Fíjate en lo que registra que una fila de tabla vacía no puede: el dashboard de reporting se verificó porque comparte la base de datos, y el ETL batch se confirmó con credencial separada. Las rotaciones fallan en los consumidores que nadie anotó; el registro es donde pruebas que lo comprobaste.

Los secretos de emergencia merecen su propia fila

Las credenciales break-glass — la contraseña de admin que esperas no usar nunca — siguen reglas distintas. Rotan por uso, no por calendario, y el procedimiento debería ser un reseteo de un comando, no una coreografía dual-read. Mantenlas fuera de la tabla de cadencias normal y dentro del playbook de emergencia, donde el SLA se mide en minutos.

Variantes

Contexto	Diferencia clave	Herramienta
Kubernetes	cert-manager para TLS, External Secrets Operator para secretos de app	Vault, AWS SM, Azure Key Vault
Cloud-native (AWS)	Rotación de roles IAM vía STS, auto-rotación de Secrets Manager	AWS Secrets Manager, funciones Lambda de rotación
Enterprise on-prem	HSM para almacenar claves, control de cambios manual	Thales Luna, SafeNet
Startup / equipo pequeño	1Password / Bitwarden compartido, rotación manual trimestral	1Password, Bitwarden
Microservicios de alta frecuencia	Certificados mTLS de corta duración (SPIFFE/SPIRE)	SPIRE, Istio

Lo Que Funciona

• Automatiza primero certificados y claves de nube — los humanos olvidan calendarios; cert-manager y Secrets Manager no.
• Usa dual-read durante la transición — la rotación de un solo secreto causa interrupciones; viejo+nuevo en la ventana, ninguna.
• Rota tras incidentes, no solo en calendario — una brecha no espera a tu cadencia de 90 días.
• Alerta 30/14/7 días antes de cada fecha límite — las rotaciones de último minuto son las que rompen cosas.
• Rota en ventanas de bajo tráfico — incluso los procedimientos sin downtime fallan a veces; falla cuando cuesta menos.
• Audita cada evento de rotación — las rotaciones fallidas son indicadores tempranos de drift de configuración.
• Nunca hardcodees secretos — la rotación solo ayuda si el secreto no está también en un repo de 2024.

Errores Comunes

• Rotar sin identificar consumidores primero — la rotación más rápida es inútil si deja un servicio roto. Consulta los access logs del secret manager antes de tocar nada.
• Olvidar secretos de downstream — actualizar la contraseña de la base de datos pero no la herramienta de reporting rompe dashboards.
• No revocar el secreto viejo — los secretos “sin uso” siguen siendo vectores de ataque válidos.
• Rotar todo a la vez — una rotación masiva fallida es una caída total; agrupa por servicio.
• Tratar las excepciones como permanentes — el registro de excepciones necesita fecha de revisión, o “temporal” se convierte en “para siempre”.

Cómo Adoptar Esta Plantilla

Empieza por el inventario — la mayoría de equipos descubre que tiene más secretos de los que creía, y la mitad sin responsable. Luego elige un secreto de bajo riesgo (un token de staging, una credencial de CI) y ejecútalo por el procedimiento completo una vez. El piloto te dice dónde se rompe el procedimiento antes de que lo haga una contraseña de producción.

La cadencia que funciona en la práctica:

1. Semana 1: rellena el inventario desde los access logs del secret manager y la lista del proveedor cloud — no confíes en la memoria.
2. Semana 2: asigna cadencias y responsables; activa las alertas de 30/14/7 días.
3. Semana 3: rotación piloto de un secreto de bajo riesgo con dual-read; mide cuánto tarda.
4. Continuo: revisa la tabla de métricas cada mes — las rotaciones tardías y el crecimiento del registro de excepciones son las dos señales de que el programa se resiente.

Troubleshooting

• Un servicio que no conocías se rompe tras la rotación: estaba consumiendo el secreto por un camino desconocido. Consulta los access logs del secret manager buscando cada identidad que leyó el secreto en los últimos 90 días — la lista suele ser más larga de lo que sugiere el inventario. Añade el consumidor y decide si haces rollback o arreglas hacia adelante.
• El secreto viejo sigue válido semanas después: alguien se saltó el paso de revocación, o un periodo de gracia “temporal” nunca se cerró. Programa la revocación como una tarea con fecha límite al planificar la rotación — los periodos de gracia abiertos son el hallazgo de auditoría más común.
• Un cron job o worker batch falla días después: cachea la conexión o lee el secreto solo al arrancar. Tras rotar, busca fallos de autenticación en los logs durante todo el intervalo entre ejecuciones — no solo la primera hora.
• cert-manager renueva el certificado pero los clientes siguen viendo el viejo: el nuevo certificado no se propagó a todos los endpoints de ingress o cachés edge. Revisa cada LB, ingress y CDN que termina TLS — la espera de propagación del procedimiento existe por esto.
• La rotación de emergencia se atasca durante un incidente: nadie sabe quién puede aprobar la excepción. La columna de responsable del playbook es la solución — una rotación que necesita tres aprobaciones a las 3 a.m. se diseñó en una reunión, no se probó.
• El script de rotación funciona en staging pero el secreto nunca llega a los pods de producción: el intervalo de sync del External Secrets Operator o la estrategia de refresh del deployment son la causa habitual — un kubectl rollout restart tras el sync lo resuelve, pero la solución va en el runbook, no en la memoria de alguien.
• Dos servicios rotan el mismo secreto en calendarios distintos: las credenciales compartidas son un problema de acoplamiento, no de planificación. Divídelas en credenciales por servicio; si el sistema no lo permite, regístralo en el log de excepciones con fecha de corrección.

Notas de Producción

• Mantén el secreto viejo legible durante el periodo de gracia — la revocación inmediata elimina tu camino de rollback si un consumidor aparece tarde.
• Vigila las métricas de fallos de auth durante 48h post-rotación — los fallos que importan llegan cuando corre el batch job, no cuando recarga la app.
• Prueba el playbook de emergencia trimestralmente — un tabletop es barato; descubrir que el on-call no puede revocar un token de Vault durante una brecha, no.
• Registra las rotaciones en el SIEM — los eventos de rotación son evidencia de auditoría y señal de anomalía a la vez.

Puntos Clave

• La rotación es un ciclo de vida: inventario → cadencia → procedimiento → validación → métricas. Saltarte el inventario convierte todo lo demás en adivinación.
• El dual-read es la diferencia entre rutina y caída — diseña para viejo+nuevo válidos durante la transición.
• El playbook de emergencia no es opcional — los secretos se filtran en su propio calendario, no en el tuyo.
• Mide el programa: la tasa de rotación a tiempo y la longitud del registro de excepciones te dicen si la rotación es un hábito o una esperanza.
• Empieza por los secretos sin dueño — los secretos sin responsable son los que se filtran en silencio; asignar un owner es la mitad de la rotación.

Lectura Adicional

• NIST SP 800-57 — Gestión de Claves — la guía de cryptoperiod y ciclo de vida de claves detrás de la tabla de cadencias
• HashiCorp Vault — Secretos Dinámicos — credenciales de base de datos que se rotan solas
• Documentación de cert-manager — renovación automática de certificados TLS en Kubernetes
• Recursos complementarios — programa descargable, runbook de rotación y checklist de validación

Errores Comunes en Producción

• Mantener el secreto viejo activo “temporalmente” durante meses — fija la fecha de revocación al programar la rotación.
• Tratar el inventario como un censo de una vez — cada servicio nuevo añade secretos; los inventarios viejos se degradan rápido.
• Rotar la contraseña pero no los tokens derivados de ella (credenciales de réplica, usuarios de solo lectura).
• Asumir que la auto-rotación del secret manager lo cubre todo — rota el valor, no los consumidores.
• Saltarse la revisión del registro de excepciones — las excepciones sin fecha se convierten en exposiciones permanentes.
• Documentar el procedimiento solo en el registro de rotación — el siguiente ingeniero busca en la wiki, no en tu hoja de cálculo.