Operazioni sicure sui file

OpenClaw usa @openclaw/fs-safe per operazioni sui file locali sensibili alla sicurezza: letture/scritture delimitate alla radice, sostituzione atomica, estrazione di archivi, workspace temporanei, stato JSON e gestione dei file segreti.

L'obiettivo è una barriera di protezione della libreria coerente per codice OpenClaw attendibile che riceve nomi di percorso non attendibili. Non è una sandbox. Le autorizzazioni del filesystem host, gli utenti del sistema operativo, i container e la policy di agenti/strumenti definiscono comunque il reale raggio d'impatto.

# Predefinito: nessun helper Python

OpenClaw imposta per impostazione predefinita l'helper Python POSIX di fs-safe su off.

Perché:

• il gateway non dovrebbe avviare un sidecar Python persistente a meno che un operatore non abbia scelto di abilitarlo;
• molte installazioni non hanno bisogno dell'irrobustimento aggiuntivo contro le mutazioni delle directory padre;
• disabilitare Python mantiene il comportamento di package/runtime più prevedibile tra ambienti desktop, Docker, CI e app in bundle.

OpenClaw modifica solo il valore predefinito. Se imposti esplicitamente una modalità, fs-safe la rispetta:

# Default OpenClaw behavior: Node-only fs-safe fallbacks.
OPENCLAW_FS_SAFE_PYTHON_MODE=off

# Opt into the helper when available, falling back if unavailable.
OPENCLAW_FS_SAFE_PYTHON_MODE=auto

# Fail closed if the helper cannot start.
OPENCLAW_FS_SAFE_PYTHON_MODE=require

# Optional explicit interpreter.
OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

Funzionano anche i nomi generici di fs-safe: FS_SAFE_PYTHON_MODE e FS_SAFE_PYTHON.

# Cosa resta protetto senza Python

Con l'helper disattivato, OpenClaw usa comunque i percorsi Node di fs-safe per:

• rifiutare escape da percorsi relativi come .., percorsi assoluti e separatori di percorso dove sono consentiti solo nomi;
• risolvere le operazioni tramite un handle radice attendibile invece di controlli ad hoc path.resolve(...).startsWith(...);
• rifiutare pattern di symlink e hardlink sulle API che richiedono tale policy;
• aprire file con controlli di identità quando l'API restituisce o consuma contenuti di file;
• scritture atomiche con file temporanei sibling per file di stato/configurazione;
• limiti di byte per letture ed estrazione di archivi;
• modalità private per segreti e file di stato dove l'API le richiede.

Queste protezioni coprono il normale modello di minaccia di OpenClaw: codice gateway attendibile che gestisce input di percorso non attendibili da modello/plugin/canale all'interno del perimetro di un singolo operatore attendibile.

# Cosa aggiunge Python

Su POSIX, l'helper opzionale di fs-safe mantiene un processo Python persistente e usa operazioni filesystem relative a fd per mutazioni delle directory padre come rename, remove, mkdir, stat/list e alcuni percorsi di scrittura.

Questo riduce le finestre di race della stessa UID in cui un altro processo può scambiare una directory padre tra validazione e mutazione. È difesa in profondità per host in cui processi locali non attendibili possono modificare le stesse directory su cui OpenClaw sta operando.

Se il tuo deployment ha questo rischio e Python è garantito, usa:

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Usa require invece di auto quando l'helper fa parte della tua postura di sicurezza; auto ripiega intenzionalmente sul comportamento solo Node se l'helper non è disponibile.

# Indicazioni per Plugin e core

• L'accesso ai file rivolto ai Plugin dovrebbe passare dagli helper openclaw/plugin-sdk/*, non da fs grezzo, quando un percorso proviene da un messaggio, output del modello, configurazione o input del Plugin.
• Il codice core dovrebbe usare i wrapper fs-safe locali in src/infra/* in modo che la policy di processo di OpenClaw sia applicata coerentemente.
• L'estrazione di archivi dovrebbe usare gli helper di archivio fs-safe con limiti espliciti di dimensione, numero di voci, link e destinazione.
• I segreti dovrebbero usare gli helper per segreti di OpenClaw o gli helper fs-safe per segreti/stato privato; non implementare manualmente controlli di modalità attorno a fs.writeFile.
• Se ti serve isolamento da utenti locali ostili, non fare affidamento solo su fs-safe. Esegui gateway separati sotto utenti/host del sistema operativo separati o usa sandboxing.

Correlati: Sicurezza, Sandboxing, Approvazioni exec, Segreti.