Runbook automatizzato: remediation dei server mediante suggerimento IA ed esecuzione semi-automatica via SSH

Quando un server di produzione si comporta in modo „strano“, nella pratica resta spesso un corridoio ristretto: stabilizzare rapidamente, documentare in modo pulito e non introdurre nuovi rischi. Proprio qui interviene un Runbook Automatizzato: traduce schemi di guasto ricorrenti in passi di verifica e azioni comprensibili. Novità è che un modulo IA (LLM, Large Language Model – un modello linguistico che riassume testi e genera suggerimenti) genera, a partire da log, metriche e contesto, un proposta IA. L’esecuzione avviene però in modalità semiautomatica: un operatore conferma i passi e solo allora vengono applicati in modo controllato via SSH (Secure Shell – accesso remoto cifrato).

Questo articolo mostra un’architettura pragmatica e un modello operativo che funziona nei team di amministrazione: con chiare regole di sicurezza, checklist, insidie tipiche, passi di verifica, pattern di implementazione e una strategia di rollback affidabile. L’enfasi non è „l’IA può fare tutto“, ma: Come utilizziamo l’IA in modo sensato, senza indebolire l’operatività?

Runbook Automatizzato: Perché semiautomatico — e non completamente automatico?

Una remediation completamente automatica suona allettante, ma nella pratica spesso fallisce su due punti: mancanza di contesto e effetti collaterali difficili da prevedere. Un LLM può formulare passaggi plausibili, ma non possiede una vera „verità“, genera testo basato su pattern. Nella remediation dei server gli effetti collaterali sono invece concreti: riavvii, modifiche di configurazione, aggiornamenti di pacchetti, rebuild di database o regole firewall possono causare danni secondari.

La semiautomazione è quindi un compromesso solido:

• Percorso diagnostico rapido: l’IA propone controlli strutturati (es. „Disco pieno?“, „OOM-Killer?“, „latenza DNS?“), includendo le uscite previste.
• Operatore come filtro: Una persona valuta rischio, tempistica, dipendenze e conferma solo ciò che è compatibile con la finestra di cambiamento e la criticità del servizio.
• Esecuzione deterministica: Il motore Runbook esegue passi predefiniti e versionati – non un qualsiasi testo shell generato dall’IA.

L’obiettivo è meno l’amministratore eroico, più un operare ripetibile: stessi sintomi, stessi controlli, stessi log, stesse tracce di audit.

Architettura di riferimento: proposta IA, motore Runbook ed esecuzione SSH

Per la maggior parte degli ambienti è consolidata un’architettura con chiara separazione tra „proposta“ e „esecuzione“:

• Sorgenti di segnale: monitoring (metriche), piattaforma di log, tracing, CMDB/dati asset, ticket/ITSM. Importante è un identificatore univoco host/service.
• Raccoglitore di contesto: un job raccoglie estratti rilevanti (p. es. gli ultimi 10 minuti di log, gli allarmi correnti, gli ultimi deploy, le manutenzioni note). Qui si decide se l’IA produce suggerimenti „buoni”.
• Assistente IA (modulo di proposta): Genera un piano di diagnosi e intervento, inclusa una valutazione del rischio. L’output idealmente come JSON strutturato (non solo testo libero).
• Runbook-Katalog: Runbook versionati (Git), con azioni approvate, parametri, precondizioni e definizione di rollback.
• Runbook-Executor: Esegue azioni via SSH, scrive i log, impone timeout, raccoglie gli output, imposta i codici di uscita e si interrompe in caso di deviazioni.
• Gate & Audit: Principio dei quattro occhi, Change-ID, approval, registrazione (chi ha confermato cosa e quando?).

Importante è la distribuzione dei ruoli: LLM propone, l’Executor agisce. Così si evita che output testuali „creativi“ vengano eseguiti direttamente come comandi.

SSH-Betriebsmodell: Bastion, Schlüssel, Rechte

SSH è tecnicamente semplice, ma operativo pieno di dettagli. Un modello robusto utilizza un Bastion Host (server di salto come punto d’ingresso controllato), credenziali a breve durata (es. chiavi/certificati a validità temporanea) e Least Privilege (solo i permessi necessari al runbook). Praticamente ciò significa:

• L’Executor si connette solo al Bastion Host, da lì agli host di destinazione (segmentazione della rete, punto centrale di audit).
• Sugli host di destinazione esiste un utente dedicato ‚runbook‘ con permessi sudo limitati (solo comandi definiti).
• Ogni azione è associata a un ticket/incident (catena di change e audit).

Quali tipi di guasto sono adatti per la remediation dei server tramite runbook?

Non tutto è adatto ai runbook. Buoni candidati sono problemi ricorrenti e osservabili con checkpoint di controllo chiari:

• Spazio disco esaurito: rotazione dei log/journal, directory temporanee, crashdump, artefatti obsoleti.
• Servizio bloccato: health-check fallito, processo vivo ma non reagisce (es. deadlock, esaurimento dei thread).
• OOM/Memory Pressure: Out-of-Memory-Killer, swap-thrashing, indicatori di leak.
• Errore DNS/rete: problemi del resolver, route errata, MTU/frammentazione.
• Certificati scaduti: problemi di catena, truststore errato, certificati client in scadenza.

Cattivi candidati sono casi speciali „una tantum“, modifiche con alto Blast-Radius (es. upgrade del kernel durante un incident) o sintomi non chiari senza telemetria affidabile.

Prerequisiti: telemetria, identità, design del runbook

Perché la proposta IA sia più di un’ipotesi, servono basi solide:

1) Telemetria con correlazione

Log, metriche e alert devono convergere. „Correlazione“ in esercizio significa: hostname, instance-ID, nome del servizio, versione di deployment e finestra temporale siano coerenti. Senza questo l’IA per difetto proporrà un „riavvio“, perché non riconosce una causa differenziata.

2) Azioni di runbook deterministiche

Un runbook è più di un testo wiki. Per esecuzione semiautomatica servono passaggi idempotenti (eseguibili più volte senza danni) e precondizioni che impediscano che un passo venga eseguito nel contesto sbagliato. Esempio: „avviare solo se spazio libero < 5% e /var è la causa“.

3) Regole di change e approvazione

Anche durante un incident vale: le modifiche devono essere tracciabili. Standard minimo: Change-ID, approval (almeno 1 operatore) e un log che contenga input, output, exit code e timestamp per ogni passo.

Incorporare correttamente la proposta IA: output come piano, non come shell

Se un LLM genera comandi shell liberi, si affrontano due rischi: sintassi non verificata e intenzione non verificata. Meglio: l’LLM fornisce un piano che la vostra Runbook-Engine convalida rispetto a un catalogo di azioni ammesse.

Un formato praticabile è JSON, che l’engine verifica rigorosamente (validazione dello schema):

{
  "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: l’engine accetta solo Runbook-IDs e azioni che esistono nel catalogo. Tutto il resto viene scartato. Così l’IA rimane un sistema di supporto, non un accesso root remoto.

Implementazione: esecutore di runbook via SSH con revisione, logging e regole di stop

Un esecutore non deve essere complesso, ma deve essere coerente. Tre caratteristiche sono decisive in esercizio:

• Tracciabilità: ogni passo scrive log standardizzati (inizio/fine, target, comando, hash dell’output, codice di uscita).
• Limiti di sicurezza: timeout, comandi consentiti, target bloccati (es. domain controller, storage controller), rate-limits.
• Regole di stop: in caso di deviazioni non si continua a tentare, ma si arresta e si procede all’escalation.

Esempio: esecuzione SSH tramite Bastion con privilegi sudo limitati

Nell’esempio seguente l’esecutore usa un utente dedicato e impone esecuzione non interattiva. Non è un prodotto completo, ma un modello concreto per i vostri runbook.

#!/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}"

Perché questi dettagli sono importanti: BatchMode impedisce i prompt per la password, StrictHostKeyChecking riduce i rischi di MitM (Man-in-the-Middle), e -J (Jump) impone la bastion come punto di ingresso. Le regole di stop nascono qui da set -e: non appena un passaggio fallisce, lo script termina in modo controllato.

Progettazione dei runbook nella pratica: Precondizioni, Dry-Run, Idempotenza

Per i team di amministrazione tre principi fanno la differenza tra “l’automazione aiuta” e “l’automazione causa problemi”:

Precondizioni (condizioni preliminari) impongono il contesto

Prima di cancellare, fermare o riavviare, verificate lo stato. Esempio: la remediation del disco solo se un filesystem è realmente vicino al limite e non, per esempio, un mount NFS bloccato (altrimenti peggiorate la situazione con timeout).

#!/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

L’obiettivo non è una “bella uscita”, ma un segnale oggettivo: il runbook può proseguire solo quando le precondizioni sono soddisfatte.

Dry-Run come impostazione predefinita

Per passaggi potenzialmente distruttivi il primo passaggio dovrebbe essere “dry” (mostrare solo cosa accadrebbe). Questo si integra perfettamente con l’esecuzione semi-automatica: l’operatore vede l’effetto e poi conferma l’esecuzione reale.

#!/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

Idempotenza: stessa azione, stesso effetto

Idempotente significa: se un passaggio viene eseguito due volte non provoca danni aggiuntivi. Esempio: “avviare il servizio” è idempotente, “patchare la configurazione più volte” spesso non lo è. Usate quindi pattern “replace/ensure” piuttosto che “append”.

Rischi e insidie tipiche (dal punto di vista operativo)

I runbook supportati da IA raramente falliscono per SSH – falliscono per condizioni marginali. Le trappole più frequenti:

1) Host errato o ambiente sbagliato

Un classico: l’allarme proviene da “prod”, ma il raccoglitore di contesto accede ai log di “stage” (omonomia dei nomi, label errate). Contromisura: controlli stringenti su environment e Asset-ID, più deny lists per sistemi particolarmente critici.

2) Situazione dati incompleta

Se mancano i log (rotazione, backpressure del forwarding) o le metriche non sono aggiornate, la proposta dell’IA diventa incerta. Trattate la “mancanza di dati” come un segnale a sé. Nel runbook: prima riparate la telemetria (es. controllare la coda del logforwarder), poi effettuate la remediation.

3) Effetti collaterali dovuti a misure standard „utili“

Un riavvio come comportamento predefinito è rischioso se il sistema è bloccato in un ciclo di recovery, una replica del database è in ritardo o uno storage è attualmente degradato. I runbook necessitano quindi di regole di stop e liste “do-not-do”, p.es. nessun aggiornamento di pacchetti durante un incidente senza un change-gate separato.

4) Permessi troppo estesi o troppo RESTrittivi

Troppo estesi: l’utente del Runbook ha sudo globale e ogni errore può scatenare un incidente. Troppo RESTrittivi: il Runbook si interrompe e gli amministratori aggirano il processo. Ha dato buoni risultati una whitelist sudoers con percorsi di comando chiaramente definiti.

Esempio: whitelist sudoers per azioni 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 percorsi assoluti, niente wildcard di shell, e dopo le modifiche validare sempre con visudo (controllo sintassi) prima di distribuire.

Controlli prima dell’esecuzione: checklist per l’operatore

Prima di autorizzare l’esecuzione semi-automatica via SSH, aiuta una checklist breve e rigorosa. È formulata intenzionalmente in modo operativo:

• Scope: Host/servizi interessati identificati in modo univoco? Ambiente corretto (prod/test)?
• Impact: Qual è il rischio worst-case delle azioni proposte (riavvio, perdita dati, perdita log)?
• Dependencies: Altri servizi dipendono dall’host (p.es. DB condiviso, proxy, queue)?
• Timebox: Quanto può durare il ripristino? Esiste una finestra di manutenzione o limiti SLA?
• Observability: Quale metrica/check indica il successo? (p.es. tasso di errori in calo, disco < 90%, healthcheck verde)
• Rollback: Esiste una strategia di ritorno definita per ogni passo?
• Approval/Audit: ID ticket/incident presente, approvazione documentata.

Se una di queste domande rimane “poco chiara”, è un segnale: prima raccogliere dati, poi agire.

Strategia di rollback e ritorno: cosa fare se la remediation fallisce?

Una strategia di ritorno non è opzionale. Fa parte del Runbook. Sul piano pratico si dimostrano efficaci tre livelli:

1) Rollback passo-passo (quando possibile)

Le modifiche di configurazione dovrebbero essere eseguite come “backup & replace”: salvare la versione precedente, attivare la nuova versione, validare e, in caso di errore, tornare indietro.

#!/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: l’automazione si ferma, interviene l’operatore

Se le precondizioni vengono violate, i codici di uscita sono inattesi o la validazione fallisce, il sistema deve fermarsi. Importante: non continuare ad automatizzare, ma congelare lo stato (salvare i log, registrare gli output correnti) ed effettuare l’escalation al 2nd/3rd-level.

3) Percorso „Known Good“

Per i servizi critici conviene predisporre una via di ritorno: ultimo stato noto funzionante (p.es. pacchetto precedente, configurazione precedente, immagine container precedente). Anche senza CI/CD questo può essere gestito tramite un repository di artefatti e versioni definite. Cruciale è che il percorso sia stato prima testato.

Sicurezza e conformità: audit, dati dei prompt, segreti

Nelle proposte generate dall’IA la questione dei dati è centrale: quali log vanno dove? Chi può visualizzarli? E cosa succede ai segreti? Alcune linee guida consolidate:

• Igiene del prompt: I segreti (token, chiavi private, password) vengono mascherati prima della chiamata al LLM. Mascherare significa: rimuovere o sostituire pattern noti (ad esempio „Authorization: Bearer …“).
• Minimizzazione dei dati: Inviare solo le righe di log e gli intervalli temporali rilevanti, non „tutto“.
• On-Prem/LLM privato, quando necessario: Se la conformità lo richiede, il LLM rimane nel vostro ambiente controllato.
• Audit logging: Ogni decisione (proposta dell’IA, approvazione dell’operatore, passaggi eseguiti) viene registrata in modo immutabile per revisione.

Importante anche: il motore del runbook è un accesso amministrativo. Va inserito nel vostro threat modeling: segmentazione di rete, hardening, gestione delle patch, MFA/SSO al punto di approvazione e processi di emergenza chiaramente definiti.

Blueprint pratico: un flusso di runbook che funziona nella pratica

Un flusso pratico è abbastanza breve per l’incidente, ma sufficientemente rigoroso per la sicurezza. Un modello collaudato:

1. Trigger: Un alert o un ticket genera l’ID dell’incidente e il/i target.
2. Raccolta del contesto: Query definite (log/metriche/eventi) vengono raccolte e archiviate.
3. Proposta dell’IA: Il LLM fornisce ipotesi + runbook proposto + rischi in formato JSON.
4. Mapping: Il motore verifica: esiste un runbook approvato e pertinente? Le azioni sono consentite?
5. Revisione dell’operatore: Checklist + approvazione dei singoli passaggi (p.es. prima diagnosi, poi remediation).
6. Esecuzione via SSH: Esecuzione passo-passo con timeout, regole di stop, output.
7. Validazione: Il successo viene verificato rispetto a segnali SLO/di integrità definiti.
8. Chiusura & Apprendimento: Migliorare il runbook: precondizioni mancanti, nuovi punti critici, raccolta dati migliore.

Se usate già Ansible o una piattaforma di runbook, molti di questi elementi possono essere integrati. Il nucleo resta: l’IA genera proposte, l’esecuzione rimane controllata, versionata e auditabile.

Troubleshooting: quando la remediation via SSH crea problemi

Anche il sistema di runbook può diventare fonte di problemi. Cause tipiche e controlli rapidi:

SSH non si connette

• Percorso di rete: La bastion è raggiungibile? L’host di destinazione è raggiungibile? Routing/ACL corretti?
• Host key: StrictHostKeyChecking blocca dopo un rebuild (comportamento previsto). Procedura: definire la rotazione delle host key invece di „disattivare semplicemente“.
• Autenticazione: Credenziali a breve durata scadute? Deriva temporale (NTP) su bastion/target?

Un controllo di connessione minimalista che può essere eseguito come fase preliminare nel 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"

I comandi falliscono con errori sudo

Spesso la whitelist sudoers è errata (percorso sbagliato, requiretty attivo, o il comando invoca internamente una shell). Verificate che il runbook usi davvero solo percorsi assoluti autorizzati e che sia impostato „sudo -n“ (non-interactive).

Il runbook non fa „nulla“, ma segnala successo

Si tratta di un problema di progettazione: mancanza di validazione. Ogni passo di remediation richiede una metrica o uno stato che cambi. Esempio: dopo il log-vacuum il comando „df“ deve tornare sotto la soglia, altrimenti il passo è considerato non riuscito.

Conclusione: l’IA è l’acceleratore, il Runbook resta il freno

La remediation dei server basata su suggerimenti dell’IA e su esecuzione semi-automatica via SSH funziona in modo affidabile solo se si separano chiaramente i ruoli: l’IA fornisce ipotesi e piani strutturati, la vostra Runbook-Engine esegue esclusivamente azioni autorizzate e un operatore mantiene il controllo sul gate. Con precondizioni, dry-run, idempotenza, log di audit e una strategia di fallback testata, eviterete i rischi più comuni: target errati, dati incompleti e modifiche «creative» durante l’incidente.

Se desiderate approfondire l’argomento, il passo successivo consigliato è standardizzare in modo coerente la vostra architettura di accesso remoto (bastion, logging, permessi) e la vostra Runbook-Governance (versionamento, revisioni, integrazione delle modifiche). Così l’intervento rapido diventa un processo operativo affidabile.

Anche l’automazione dei runbook è importante per questo tema. L’articolo inquadra questi aspetti in modo comprensibile e mostra cosa conta nella pratica quotidiana.