Runbook di esposizione del Gateway

Questo runbook trasforma la guida più ampia sulla Sicurezza in una checklist operativa per l'accesso remoto e l'esposizione della messaggistica.

Scegli il modello di esposizione

Preferisci il modello più ristretto che soddisfa il flusso di lavoro.

Evita il port-forwarding pubblico diretto verso il Gateway. Se ti serve accesso pubblico, metti davanti un proxy identity-aware e rendi il proxy l'unico percorso di rete verso il Gateway.

Inventario preliminare

Registra questi elementi prima di modificare bind, proxy, Tailscale o policy dei canali:

• Host del Gateway, utente del sistema operativo e directory di stato.
• URL del Gateway e modalità di bind.
• Modalità di autenticazione, origine del token/password o origine dell'identità del proxy attendibile.
• Tutti i canali abilitati e se accettano DM, gruppi o webhook.
• Agenti raggiungibili da mittenti non locali.
• Profilo degli strumenti, modalità sandbox e policy degli strumenti elevati per ogni agente raggiungibile.
• Credenziali esterne disponibili per quegli agenti.
• Posizione del backup per ~/.openclaw/openclaw.json e le credenziali.

Se più di una persona può inviare messaggi al bot, trattalo come autorità condivisa delegata sugli strumenti, non come isolamento host per utente.

Controlli di base

Esegui questi comandi prima di aprire l'accesso:

openclaw doctoropenclaw security auditopenclaw security audit --deepopenclaw health

Risolvi prima i risultati critici. Gli avvisi possono essere accettabili solo quando sono intenzionali e documentati per la distribuzione.

Per la convalida CLI remota, passa le credenziali esplicitamente:

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

Non presumere che le credenziali della configurazione locale si applichino a un URL remoto esplicito.

Baseline minima sicura

Usa questa forma come punto di partenza per le distribuzioni esposte:

{  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 },  },}

Poi amplia un controllo alla volta. Ad esempio, aggiungi una allowlist specifica del canale prima di abilitare strumenti capaci di scrivere, oppure abilita un reverse proxy prima di accettare traffico remoto della Control UI.

La baseline rigorosa exec.security: "deny" blocca tutte le chiamate exec, incluse diagnostiche innocue. Se sono necessarie diagnostiche o comandi a basso rischio, rilassala solo dopo aver scelto i mittenti, gli agenti, i comandi e la modalità di approvazione specifici che corrispondono al tuo modello di minaccia.

Esposizione di DM e gruppi

I canali di messaggistica sono superfici di input non attendibili. Prima di consentire DM o gruppi:

• Preferisci dmPolicy: "pairing" o liste allowFrom rigorose.
• Evita dmPolicy: "open" a meno che ogni mittente sia attendibile.
• Non combinare allowlist "*" con accesso ampio agli strumenti.
• Richiedi menzioni nei gruppi a meno che la stanza sia strettamente controllata.
• Usa session.dmScope: "per-channel-peer" quando più persone possono inviare DM al bot.
• Instrada i canali condivisi verso agenti con strumenti minimi e senza credenziali personali.

Il pairing autorizza il mittente ad attivare il bot. Non rende quel mittente un confine di sicurezza host separato.

Controlli del reverse proxy

Per i proxy identity-aware:

• Il proxy deve autenticare gli utenti prima di inoltrare al Gateway.
• L'accesso diretto alla porta del Gateway deve essere bloccato da firewall o policy di rete.
• gateway.trustedProxies deve contenere solo gli IP sorgente del proxy.
• Il proxy deve rimuovere o sovrascrivere gli header di identità e inoltro forniti dal client.
• gateway.auth.trustedProxy.allowUsers dovrebbe elencare gli utenti previsti quando il proxy serve più di un pubblico.
• La modalità proxy loopback sullo stesso host dovrebbe usare allowLoopback solo quando i processi locali sono attendibili e il proxy possiede gli header di identità.

Esegui openclaw security audit --deep dopo le modifiche al proxy. I risultati sul trusted-proxy sono intenzionalmente ad alto segnale perché il proxy diventa il confine di autenticazione.

Revisione di strumenti e sandbox

Prima di esporre un agente a mittenti remoti:

• Conferma quali sessioni vengono eseguite sull'host rispetto alla sandbox.
• Nega o richiedi approvazione per l'exec sull'host.
• Mantieni disabilitati gli strumenti elevati a meno che un mittente specifico e attendibile ne abbia bisogno.
• Evita strumenti browser, canvas, node, cron, gateway e session-spawn per superfici di messaggistica aperte o semiaperte.
• Mantieni i bind mount ristretti ed evita credenziali, home, socket Docker e percorsi di sistema.
• Usa gateway, utenti del sistema operativo o host separati per confini di fiducia materialmente diversi.

Se gli utenti remoti non sono completamente attendibili, l'isolamento deve provenire da distribuzioni separate, non solo da prompt o etichette di sessione.

Convalida post-modifica

Dopo ogni modifica di esposizione:

1. Riesegui openclaw security audit --deep.
2. Testa una connessione autorizzata riuscita.
3. Testa che un mittente o una sessione browser non autorizzati vengano negati.
4. Conferma che i log redigano i segreti.
5. Conferma che l'instradamento DM/gruppo raggiunga solo l'agente previsto.
6. Conferma che gli strumenti ad alto impatto chiedano approvazione o vengano negati.
7. Documenta gli avvisi residui accettati.

Non procedere alla modifica di esposizione successiva finché quella corrente non è compresa.

Piano di rollback

Se il Gateway potrebbe essere sovraesposto:

{  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 },  },}

Poi:

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

Checklist di revisione

• Il Gateway resta solo loopback a meno che ci sia un motivo documentato.
• L'accesso non-loopback ha autenticazione, firewall e nessuna route diretta pubblica.
• Le distribuzioni con trusted-proxy hanno IP del proxy e controlli degli header rigorosi.
• I DM usano pairing o allowlist, non accesso aperto per impostazione predefinita.
• I gruppi richiedono menzioni o allowlist esplicite.
• I canali condivisi non raggiungono credenziali personali.
• Le sessioni non-main vengono eseguite in modalità sandbox.
• L'exec sull'host e gli strumenti elevati sono negati o protetti da approvazione.
• I log redigono i segreti.
• I risultati critici dell'audit sono risolti.
• I passaggi di rollback sono testati e documentati.