Runbook automatizado: remediación de servidores según propuesta de IA y ejecución semiautomática por SSH

Cuando un servidor de producción se comporta de forma „extraña“, en la práctica a menudo solo queda un estrecho corredor: estabilizar rápidamente, documentar con claridad y no introducir nuevos riesgos. Ahí es donde entra un Runbook automatizado: traduce patrones recurrentes de incidentes en pasos de verificación y acciones trazables. La novedad es que un módulo de IA (LLM, Large Language Model – un modelo de lenguaje que resume textos y genera propuestas) produce una propuesta de IA a partir de logs, métricas y contexto. La ejecución, sin embargo, es semi‑automática: un operador confirma los pasos y solo entonces se aplican controladamente vía SSH (Secure Shell – inicio de sesión remoto cifrado).

Esta entrada presenta una arquitectura aplicable y un modelo operativo que funciona en equipos de administración: con límites de seguridad claros, listas de verificación, trampas habituales, pasos de comprobación, patrones de implementación y una estrategia de reversión sólida. El enfoque no es «la IA lo puede todo», sino: ¿Cómo usamos la IA de forma sensata sin desmantelar la operación?

Runbook automatizado: ¿Por qué semi‑automático y no totalmente automático?

La remediación totalmente automática suena tentadora, pero en la práctica suele fracasar por dos motivos: falta de contexto y efectos secundarios difíciles de prever. Un LLM puede formular pasos plausibles, pero no dispone de una “verdad” objetiva; genera texto a partir de patrones. En la remediación de servidores, sin embargo, los efectos secundarios son concretos: reinicios, cambios de configuración, actualizaciones de paquetes, reconstrucciones de bases de datos o reglas de firewall pueden causar daños colaterales.

Por eso la semi‑automatización es un compromiso estable:

• Ruta de diagnóstico rápida: La IA propone comprobaciones estructuradas (p. ej. „¿Disco lleno?“, „¿OOM‑Killer?“, „¿latencia DNS?“), incluyendo las salidas esperadas.
• Operador como puerta de control: Una persona evalúa el riesgo, el momento y las dependencias, y solo confirma lo que encaja en la ventana de cambios y la criticidad del servicio.
• Ejecución determinista: La Runbook-Engine ejecuta pasos predefinidos y versionados —no „cualquier“ texto de shell generado por la IA.

El objetivo es menos el administrador héroe y más la operación repetible: mismos síntomas, mismas comprobaciones, mismos logs, mismas trazas de auditoría.

Arquitectura de referencia: propuesta de IA, Runbook-Engine y ejecución por SSH

Para la mayoría de entornos, resulta conveniente una arquitectura con una separación clara entre «propuesta» y «ejecución»:

• Fuentes de señal: monitorización (métricas), plataforma de logs, tracing, CMDB/datos de activos, ticket/ITSM. Es importante un identificador inequívoco de host/servicio.
• Recolector de contexto: Un job recopila fragmentos relevantes (p. ej. los últimos 10 minutos de logs, alarmas actuales, últimos despliegues, mantenimientos conocidos). De esto depende si la IA hace propuestas „buenas“.

Es importante la distribución de roles: El LLM recomienda, el Executor actúa. Así se evita que salidas textuales «creativas» se ejecuten directamente como comandos.

Modelo operativo SSH: bastión, claves, permisos

SSH es técnicamente simple, pero operativo lleno de detalles. Un modelo robusto utiliza un servidor bastión (servidor de salto como punto de entrada controlado), credenciales de corta duración (p. ej. claves/certificados con validez temporal) y principio de menor privilegio (solo los permisos que necesita el Runbook). En la práctica eso significa:

• El Executor se conecta únicamente al bastión, y desde allí a los hosts objetivo (segmentación de red, punto central de auditoría).
• En los hosts objetivo existe un usuario dedicado „runbook“ con privilegios sudo restringidos (solo comandos definidos).
• Cada acción está asociada a un ticket/incident (cadena de cambios y auditoría).

¿Qué tipos de incidentes son adecuados para la remediación de servidores mediante Runbook?

No todo es apto para runbooks. Buenos candidatos son problemas recurrentes y observables con puntos de comprobación claros:

• Espacio en disco lleno: rotación de logs/journal, directorios temporales, volcados de memoria (crashdumps), artefactos antiguos.
• Servicio colgado: fallo de chequeo de salud, proceso vivo pero sin respuesta (p. ej. deadlocks, agotamiento de hilos).
• OOM/presión de memoria: Out-of-Memory-Killer, swap-thrashing, indicadores de fugas.
• Errores de DNS/red: problemas del resolvedor, rutas defectuosas, MTU/fragmentación.
• Certificados caducados: problemas con la cadena, truststore incorrecto, certificados de cliente próximos a expirar.

Malos candidatos son casos „únicos“, cambios con un radio de impacto elevado (p. ej. actualización del kernel durante un incidente) o síntomas poco claros sin telemetría fiable.

Requisitos: telemetría, identidades, diseño de Runbooks

Para que la propuesta de la IA no sea conjetura, se requieren bases sólidas:

1) Telemetría con correlación

Logs, métricas y alertas deben conciliarse. „Correlación“ en operaciones significa: hostname, instance-id, nombre del servicio, versión del despliegue y ventana temporal son consistentes. Sin eso, la IA sugerirá por defecto „reinicio“, porque no reconoce la causa de forma diferenciada.

2) Acciones de Runbook deterministas

Un Runbook es más que un texto de wiki. Para ejecución semiautomática necesita pasos idempotentes (ejecutables varias veces sin causar daño) y preconditions (precondiciones) que eviten que un paso se ejecute en el contexto equivocado. Ejemplo: „solo iniciar si el espacio libre < 5% y /var es la causa“.

3) Reglas de cambio y aprobación

También en un incidente aplica: los cambios deben ser rastreables. Estándar mínimo: Change-ID, aprobación (al menos 1 operador) y un log que contenga input, output, exit-code y la hora por cada paso.

Integrar correctamente la propuesta de la IA: salida como plan, no como shell

Si un LLM genera comandos de shell libres, se enfrentan a dos riesgos: sintaxis no verificada e intención no verificada. Mejor: el LLM entrega un plan que su Runbook-Engine valida frente a un catálogo de acciones permitidas.

Un formato práctico es JSON, que la Engine valida de forma estricta (validación de esquema):

{
  "incident_id": "INC-2026-071",
  "target": {
    "hostname": "app-17",
    "environment": "prod"
  },
  "hypotheses": [
    {
      "name": "disk_pressure_var",
      "evidence": ["/var usage high", "journald size increased"],
      "confidence": 0.72
    }
  ],
  "proposed_runbook": {
    "id": "Linux-disk-remediation",
    "steps": [
      {"action": "collect_disk_state", "params": {"paths": ["/", "/var"]}},
      {"action": "journald_vacuum", "params": {"retain": "1G"}},
      {"action": "logrotate_force", "params": {"dry_run": true}}
    ]
  },
  "risk_notes": [
    "Vacuum kann Debug-Logs entfernen; vorher Incident-Logs sichern.",
    "logrotate nur nach Review ohne dry_run ausführen."
  ]
}

Importante: la Engine acepta solo Runbook-IDs y acciones que existan en el catálogo. Todo lo demás se descarta. Así la IA permanece como un sistema de asistencia, no como un acceso root remoto.

Implementación: Runbook-Executor a través de SSH con revisión, registro y reglas de parada

Un Executor no tiene que ser complejo, pero sí riguroso. En la operación, tres características son decisivas:

• Trazabilidad: Cada paso escribe logs estandarizados (inicio/fin, destino, comando, hash de salida, código de salida).
• Límites de seguridad: timeouts, comandos permitidos, targets bloqueados (p. ej. Domain Controller, Storage-Controller), límites de tasa.
• Reglas de parada: Ante desviaciones no se continúa probando, sino que se detiene y se escala.

Ejemplo: ejecución SSH a través de bastión con permisos sudo restringidos

En el ejemplo siguiente, el Executor usa un usuario dedicado y fuerza la ejecución no interactiva. Esto no es un producto completo, sino un patrón tangible para sus propios runbooks.

#!/usr/bin/env bash
set -euo pipefail

BASTION="bastion01"
TARGET="$1"               # z.B. app-17
RUNBOOK_ID="$2"           # z.B. Linux-disk-remediation
INCIDENT_ID="$3"          # z.B. INC-2026-071

SSH_OPTS=(
  -o BatchMode=yes
  -o StrictHostKeyChecking=yes
  -o ConnectTimeout=8
  -o ServerAliveInterval=10
  -o ServerAliveCountMax=3
  -J "runbook@${BASTION}"
)

log(){
  printf '%s %s %sn' "$(date -Is)" "${INCIDENT_ID}" "$*"
}

run(){
  local cmd="$1"
  log "STEP cmd=${cmd}"
  ssh "${SSH_OPTS[@]}" "runbook@${TARGET}" -- "${cmd}"
  log "STEP exit=$?"
}

log "START runbook=${RUNBOOK_ID} target=${TARGET}"

# Beispiel-Schritte (in der Praxis aus einem signierten Katalog geladen)
run "sudo -n /usr/local/sbin/collect_disk_state"
run "sudo -n /usr/local/sbin/journald_vacuum --retain=1G"

log "DONE runbook=${RUNBOOK_ID} target=${TARGET}"

Por qué estos detalles son importantes: BatchMode evita los prompts de contraseña, StrictHostKeyChecking reduce los riesgos de MitM (Man-in-the-Middle), y -J (Jump) fuerza a la bastión como punto de entrada. Las reglas de parada se generan aquí mediante set -e: en cuanto un paso falla, el script termina de forma controlada.

Runbook-Design in der Praxis: Preconditions, Dry-Run, Idempotenz

Para los equipos de administración, tres principios marcan la diferencia entre «la automatización ayuda» y «la automatización causa problemas»:

Preconditions (Vorbedingungen) erzwingen Kontext

Antes de borrar, detener o reiniciar, compruebe el estado. Ejemplo: Disk-Remediation solo si realmente un filesystem está lleno y no, por ejemplo, un NFS-Mount está colgado (si no, empeorará la situación por timeouts).

#!/usr/bin/env bash
set -euo pipefail

THRESHOLD_PERCENT=95

# Prüfen: Welche Mounts sind kritisch?
df -P | awk 'NR>1 {print $5 " " $6}' | while read -r use mount; do
  pct=${use%%%}
  if [ "${pct}" -ge "${THRESHOLD_PERCENT}" ]; then
    echo "CRITICAL ${mount} ${pct}%"
  fi
done

# Prüfen: journald-Größe (kann /var füllen)
if command -v journalctl >/dev/null 2>&1; then
  journalctl --disk-usage || true
fi

El objetivo no es una «salida bonita», sino una señal objetiva: el runbook solo debe continuar cuando se cumplen las Preconditions.

Dry-Run als Standard

En pasos potencialmente destructivos, la primera ejecución debería ser «dry» (solo mostrar lo que ocurriría). Esto encaja perfectamente con la ejecución semiautomática: el operador ve el efecto y luego confirma el paso real.

#!/usr/bin/env bash
set -euo pipefail

# Beispiel: logrotate zuerst testen, dann ausführen
logrotate -d /etc/logrotate.conf
# Erst nach Freigabe:
# logrotate -f /etc/logrotate.conf

Idempotenz: gleiche Aktion, gleicher Effekt

Idempotente significa: si un paso se ejecuta dos veces, no causa daño adicional. Ejemplo: «iniciar servicio» es idempotente, «parchar configuración varias veces» a menudo no lo es. Por eso prefiera patrones de «replace/ensure» en lugar de «append».

Risiken und typische Stolperfallen (aus Betriebssicht)

Los runbooks asistidos por IA rara vez fallan por SSH: fallan por condiciones límite. Las trampas más frecuentes:

1) Falscher Host oder falsche Umgebung

Un clásico: la alarma proviene de «prod», pero el recolector de contexto accede a los logs de «stage» (igualdad de nombres, etiquetas erróneas). Contramedida: comprobaciones estrictas sobre Environment y Asset-ID, más «deny lists» para sistemas especialmente críticos.

2) Unvollständige Datenlage

Si faltan logs (rotación, Forwarding-Backpressure) o las métricas no están actualizadas, la sugerencia de IA será insegura. Trate la «ausencia de datos» como una señal propia. En el runbook: primero reparar la telemetría (p. ej. comprobar la Logforwarder-Queue), luego remediar.

3) Nebenwirkungen durch „hilfreiche“ Standardmaßnahmen

Reiniciar como opción predeterminada es arriesgado cuando el sistema está atrapado en un bucle de recuperación, una replicación de base de datos está rezagada o un almacenamiento está degradado. Por eso los Runbooks necesitan reglas de parada y listas „Do-not-do“, p. ej. no aplicar actualizaciones de paquetes durante un incidente sin un Change-Gate separado.

4) Permisos demasiado amplios o demasiado RESTringidos

Demasiado amplios: el Runbook-User tiene sudo global, y así cualquier error puede desencadenar un incidente. Demasiado RESTringidos: el runbook se interrumpe y los administradores eluden el proceso. Ha demostrado ser eficaz una lista blanca de sudoers con rutas de comando claras.

Ejemplo: lista blanca de sudoers para acciones del runbook

# /etc/sudoers.d/runbook
Defaults:runbook !requiretty
runbook ALL=(root) NOPASSWD: 
  /usr/local/sbin/collect_disk_state, 
  /usr/local/sbin/journald_vacuum, 
  /usr/local/sbin/service_healthcheck, 
  /bin/systemctl RESTart myservice

Importante: solo rutas absolutas, sin comodines de shell, y tras los cambios siempre validar con visudo (comprobación de sintaxis) antes de desplegar.

Pasos de verificación antes de la ejecución: lista de comprobación para el operador

Antes de autorizar la ejecución semiautomática por SSH, ayuda una lista de comprobación breve y concisa. Está formulada deliberadamente „operativa“:

• Alcance: ¿Hosts/servicios afectados identificados de forma inequívoca? ¿Entorno correcto (prod/test)?
• Impacto: ¿Cuál es el riesgo worst-case de los pasos propuestos (reinicio, pérdida de datos, pérdida de logs)?
• Dependencias: ¿Dependen otros servicios del host (p. ej., BD compartida, proxy, cola)?
• Límite de tiempo: ¿Cuánto tiempo puede durar la remediación? ¿Hay ventana de mantenimiento o límites SLA?
• Observabilidad: ¿Qué métricas/comprobaciones indican éxito? (p. ej., la tasa de errores disminuye, disco < 90 %, healthcheck en verde)
• Rollback: ¿Existe una estrategia de reversión definida por paso?
• Aprobación/Auditoría: ID de ticket/incidente disponible, aprobación documentada.

Si alguna de estas preguntas permanece „incierta“, es una señal: primero recopilar datos, luego actuar.

Estrategia de reversión y retorno: ¿Qué hacer si la remediación falla?

Una estrategia de retorno no es opcional. Forma parte del Runbooks. En la práctica funcionan tres niveles:

1) Reversión gradual (cuando sea posible)

Los cambios de configuración deberían realizarse como „backup & replace“: guardar la versión anterior, activar la versión nueva, validar y, en caso de error, revertir.

#!/usr/bin/env bash
set -euo pipefail

CFG="/etc/myservice/myservice.conf"
BK="${CFG}.$(date +%Y%m%d%H%M%S).bak"

cp -a "${CFG}" "${BK}"

# Beispiel: neue Konfiguration aus gerendertem Artefakt einspielen
cp -a /var/lib/runbook/rendered/myservice.conf "${CFG}"

systemctl reload myservice

# Validierung: Service muss aktiv sein
systemctl is-active --quiet myservice

echo "OK: config applied; backup at ${BK}"

2) Safe Stop: la automatización se detiene, interviene una persona

Si se rompen las precondiciones, los códigos de salida son inesperados o la validación falla, el sistema debe detenerse. Importante: no automatizar „más“ sino congelar el estado (asegurar los logs, guardar las salidas actuales) y escalar al 2nd/3rd-Level.

3) Ruta „Known Good“

Para servicios críticos conviene disponer de un camino de retorno preparado: el último estado conocido (p. ej., paquete anterior, configuración anterior, imagen de contenedor anterior). Incluso sin CI/CD, esto puede gestionarse mediante un repositorio de artefactos y versiones definidas. Es crucial que la ruta se haya probado antes.

Seguridad y cumplimiento: auditoría, datos de prompt, secretos

En las propuestas de IA la cuestión de los datos es central: ¿qué logs van a dónde? ¿Quién puede verlos? ¿Y qué pasa con los secretos? Algunas pautas probadas:

• Higiene de prompts: Los secretos (tokens, claves privadas, contraseñas) se enmascaran antes de la llamada al LLM. Enmascarar significa: eliminar o reemplazar patrones conocidos (p. ej. „Authorization: Bearer …“).
• Minimización de datos: Enviar solo las líneas de log y ventanas temporales relevantes, no „todo“.
• On-Prem/LLM privado, cuando sea necesario: Si la compliance lo exige, el LLM permanece en su entorno controlado.
• Audit Logging: Cada decisión (propuesta de IA, aprobación del operador, pasos ejecutados) se registra con integridad para auditoría.

También importante: la Runbook-Engine es un punto de acceso administrativo. Debe integrarse en su modelado de amenazas: segmentación de red, endurecimiento, gestión de parches, MFA/SSO en el Approval-Gate y procesos claros de emergencia.

Blueprint práctico: un flujo de Runbook que funciona en la práctica

Un flujo práctico es lo suficientemente corto para el incidente, pero lo bastante estricto para la seguridad. Un patrón probado:

1. Trigger: Alerta o ticket genera Incident-ID y Target(s).
2. Context Collect: Consultas definidas (Logs/Métricas/Events) se recopilan y almacenan.
3. Propuesta de IA: El LLM entrega hipótesis + Runbook propuesto + riesgos en JSON.
4. Mapping: La engine comprueba: ¿Existe un Runbook aprobado y adecuado? ¿Están permitidas las acciones?
5. Revisión del operador: Checklist + aprobación de pasos individuales (p. ej., primero diagnóstico, luego remediación).
6. Ejecutar vía SSH: Ejecución paso a paso con timeouts, reglas de parada y salidas.
7. Validar: El éxito se verifica frente a señales definidas de SLO / de estado de salud.
8. Cerrar & Aprender: Mejorar el Runbook: precondiciones faltantes, nuevas fuentes de error, mejor recolección de datos.

Si ya usa Ansible o una plataforma de Runbook, muchos de estos elementos pueden integrarse. El núcleo sigue siendo: la IA genera propuestas, la ejecución permanece controlada, versionada y auditable.

Resolución de problemas: cuando la remediación por SSH provoca problemas

El propio sistema de Runbook también puede convertirse en una fuente de fallos. Causas típicas y comprobaciones rápidas:

SSH no se conecta

• Ruta de red: ¿Bastion accesible? ¿Host objetivo accesible? ¿Routing/ACLs correctos?
• Host Keys: StrictHostKeyChecking bloquea tras un rebuild (esperado). Proceso: definir Host-Key-Rotation en lugar de „desactivarlo simplemente“.
• Auth: ¿Credenciales de corta duración caducadas? ¿Deriva temporal (NTP) en Bastion/Target?

Una comprobación de conexión minimalista que puede ejecutarse como etapa previa en el Runbook:

#!/usr/bin/env bash
set -euo pipefail

BASTION="bastion01"
TARGET="$1"

ssh -o BatchMode=yes -o ConnectTimeout=5 "runbook@${BASTION}" -- "echo BASTION_OK"
ssh -o BatchMode=yes -o ConnectTimeout=5 -J "runbook@${BASTION}" "runbook@${TARGET}" -- "echo TARGET_OK"

Los comandos fallan con errores de sudo

Normalmente es que la whitelist de sudoers está mal (ruta incorrecta, requiretty activo, o el comando invoca internamente una shell). Verifique que el Runbook realmente utiliza solo rutas absolutas permitidas y que se usa „sudo -n“ (no interactivo).

El Runbook no hace „nada“, pero reporta éxito

Esto es un problema de diseño: falta de validación. Cada paso de remediación necesita una métrica o un estado que cambie. Ejemplo: después de Log-Vacuum, ‚df‘ debe volver a estar por debajo del umbral; de lo contrario el paso se considera no exitoso.

Conclusión: la IA es el acelerador, el Runbook sigue siendo el freno

La remediación de servidores mediante propuestas de IA y ejecución semiautomática por SSH funciona de forma fiable cuando se separan claramente los roles: la IA aporta hipótesis y planes estructurados, su Runbook-Engine ejecuta exclusivamente acciones autorizadas, y un operador mantiene la intervención manual en el punto de control. Con precondiciones, Dry-Run, idempotencia, registros de auditoría y una estrategia de recuperación probada evita los riesgos más comunes: objetivos incorrectos, situación de datos poco clara y cambios „creativos“ durante el incidente.

Si desea profundizar en el tema, como siguiente paso conviene estandarizar de forma consecuente su arquitectura de acceso remoto (Bastion, logging, permisos) y su Runbook-Governance (versionado, revisiones, integración de cambios). Así, de una ayuda rápida se transforma en un proceso operativo robusto.

Para este tema también son importantes las Runbook Automation. El artículo sitúa estos aspectos de forma clara y muestra qué es importante en la práctica.