Runbook per l'esposizione del Gateway

​

Scegliere il modello di esposizione

​

Inventario preliminare

• Host del Gateway, utente del sistema operativo e directory di stato (predefinita: ~/.openclaw).
• URL del Gateway e modalità di binding (gateway.bind; porta predefinita 18789).
• Modalità di autenticazione, origine del token/della password oppure origine dell’identità del proxy attendibile.
• Ogni canale abilitato e se accetta messaggi diretti, gruppi o webhook.
• Agenti raggiungibili da mittenti non locali.
• Profilo degli strumenti, modalità sandbox e criteri per gli strumenti con privilegi elevati per ciascun agente raggiungibile.
• Credenziali esterne disponibili per tali agenti.
• Posizione del backup di ~/.openclaw/openclaw.json e delle credenziali.

​

Controlli di base

openclaw doctor
openclaw security audit
openclaw security audit --deep
openclaw health

openclaw gateway probe --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

​

Configurazione minima sicura

{
  gateway: {
    bind: "loopback",
    auth: {
      mode: "token",
      token: "replace-with-a-long-random-token",
    },
  },
  session: {
    dmScope: "per-channel-peer",
  },
  agents: {
    defaults: {
      sandbox: { mode: "non-main" },
    },
  },
  tools: {
    profile: "messaging",
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false },
  },
}

​

Esposizione di messaggi diretti e gruppi

• Preferisci dmPolicy: "pairing" o un elenco allowFrom restrittivo rispetto a dmPolicy: "open".
• Non combinare elenchi consentiti "*" con un accesso esteso agli strumenti.
• Richiedi menzioni nei gruppi, a meno che la stanza non sia sottoposta a uno stretto controllo.
• Imposta session.dmScope: "per-channel-peer" (oppure "per-account-channel-peer" per i canali con più account) quando più persone possono inviare messaggi diretti al bot, in modo che le sessioni di messaggistica diretta non condividano il contesto.
• Instrada i canali condivisi verso agenti con strumenti minimi e senza credenziali personali.

​

Controlli del proxy inverso

• Il proxy deve autenticare gli utenti prima di inoltrare le richieste al Gateway.
• Il firewall o i criteri di rete devono bloccare l’accesso diretto alla porta del Gateway.
• gateway.trustedProxies deve elencare esclusivamente gli indirizzi IP di origine del proxy.
• Il proxy deve rimuovere o sovrascrivere gli header di identità e inoltro forniti dal client.
• Imposta gateway.auth.trustedProxy.allowUsers quando il proxy serve più di un gruppo di destinatari.
• Usa gateway.auth.trustedProxy.allowLoopback solo per un proxy sullo stesso host, quando i processi locali sono attendibili e il proxy controlla gli header di identità.

​

Verifica degli strumenti e della sandbox

• Verifica quali sessioni vengono eseguite sull’host e quali nella sandbox.
• Nega o richiedi l’approvazione per l’esecuzione sull’host.
• Mantieni disabilitati gli strumenti con privilegi elevati, a meno che non siano necessari a un mittente specifico e attendibile.
• Evita gli strumenti per browser, canvas, Node, Cron, Gateway e creazione di sessioni sulle superfici di messaggistica aperte o semiaperte.
• Mantieni limitati i mount bind; evita percorsi relativi a credenziali, home, socket Docker e sistema.
• Usa Gateway, utenti del sistema operativo o host separati per confini di attendibilità sostanzialmente diversi.

​

Convalida successiva alle modifiche

1. Esegui nuovamente openclaw security audit --deep.
2. Verifica che una connessione autorizzata riesca.
3. Verifica che un mittente o una sessione del browser non autorizzati vengano rifiutati.
4. Verifica che i log oscurino i segreti.
5. Verifica che l’instradamento dei messaggi diretti/dei gruppi raggiunga soltanto l’agente previsto.
6. Verifica che gli strumenti ad alto impatto richiedano l’approvazione o vengano negati.
7. Documenta gli avvisi residui accettati.

​

Piano di ripristino

{
  gateway: {
    bind: "loopback",
  },
  channels: {
    whatsapp: { dmPolicy: "disabled" },
    telegram: { dmPolicy: "disabled" },
    discord: { dmPolicy: "disabled" },
    slack: { dmPolicy: "disabled" },
  },
  tools: {
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false },
  },
}

1. Interrompi l’inoltro pubblico, Tailscale Funnel o le route del proxy inverso.
2. Ruota i token/le password del Gateway e le credenziali delle integrazioni interessate.
3. Rimuovi "*" e i mittenti imprevisti dagli elenchi consentiti.
4. Esamina i log di audit recenti, la cronologia delle esecuzioni, le chiamate agli strumenti e le modifiche alla configurazione.
5. Esegui nuovamente openclaw security audit --deep.
6. Riabilita l’accesso con il modello più restrittivo che soddisfa il flusso di lavoro.

​

Lista di controllo per la revisione

• Il Gateway rimane accessibile solo tramite loopback, salvo un motivo documentato.
• L’accesso non tramite loopback dispone di autenticazione e firewall e non ha alcun percorso pubblico diretto.
• Le distribuzioni con proxy attendibile hanno indirizzi IP del proxy e controlli degli header restrittivi.
• I messaggi diretti usano l’associazione o elenchi consentiti, non l’accesso aperto per impostazione predefinita.
• I gruppi richiedono menzioni o elenchi consentiti espliciti.
• I canali condivisi non possono accedere alle credenziali personali.
• Le sessioni non principali vengono eseguite in modalità sandbox.
• L’esecuzione sull’host e gli strumenti con privilegi elevati sono negati o subordinati all’approvazione.
• I log oscurano i segreti.
• I problemi critici rilevati dall’audit sono risolti.
• I passaggi di ripristino sono verificati e documentati.