Operazioni sicure sui file

OpenClaw utilizza @openclaw/fs-safe per le operazioni sensibili alla sicurezza sui file locali: letture/scritture limitate alla directory radice, sostituzione atomica, estrazione di archivi, spazi di lavoro temporanei, stato JSON e gestione dei file contenenti segreti.

È una protezione a livello di libreria per il codice OpenClaw attendibile che riceve nomi di percorsi non attendibili, non una sandbox. Le autorizzazioni del file system dell'host, gli utenti del sistema operativo, i container e i criteri dell'agente e degli strumenti continuano a definire il reale raggio d'impatto.

Impostazione predefinita: nessun helper Python

OpenClaw imposta l'helper Python POSIX di fs-safe come disattivato per impostazione predefinita:

• il Gateway non deve avviare un processo ausiliario Python persistente, a meno che un operatore non lo abiliti esplicitamente;
• la maggior parte delle installazioni non necessita della protezione aggiuntiva contro le modifiche alle directory superiori;
• la disattivazione di Python mantiene prevedibile il comportamento in fase di esecuzione negli ambienti desktop, Docker, CI e delle applicazioni distribuite in bundle.

OpenClaw modifica soltanto l'impostazione predefinita. Un'impostazione esplicita ha sempre la precedenza:

# Comportamento predefinito di OpenClaw: fallback fs-safe basati solo su Node.OPENCLAW_FS_SAFE_PYTHON_MODE=off # Abilita l'helper quando disponibile, ricorrendo al fallback se non è disponibile.OPENCLAW_FS_SAFE_PYTHON_MODE=auto # Interrompe l'esecuzione in modo sicuro se l'helper non può avviarsi.OPENCLAW_FS_SAFE_PYTHON_MODE=require # Percorso esplicito facoltativo dell'interprete.OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

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

Utilizza require (non auto) quando l'helper fa parte della tua strategia di sicurezza; auto ricorre silenziosamente al comportamento basato solo su Node se l'helper non può avviarsi.

Cosa rimane protetto senza Python

Con l'helper disattivato, OpenClaw continua a beneficiare delle protezioni di fs-safe basate solo su Node:

• rifiuta i tentativi di uscire dal percorso relativo (..), i percorsi assoluti e i separatori di percorso nei casi in cui sono consentiti soltanto nomi semplici;
• esegue le operazioni tramite un handle attendibile della directory radice anziché ricorrere a controlli ad hoc come path.resolve(...).startsWith(...);
• rifiuta schemi con collegamenti simbolici e collegamenti fisici nelle API che richiedono tali criteri;
• apre i file verificandone l'identità quando l'API restituisce o utilizza il contenuto dei file;
• scrive i file di stato e configurazione tramite un file temporaneo adiacente e una rinomina atomica;
• applica limiti in byte alle letture e all'estrazione degli archivi;
• applica modalità di accesso private ai segreti e ai file di stato quando richiesto dall'API.

Ciò copre il normale modello di minaccia di OpenClaw: codice Gateway attendibile che gestisce input di percorso non attendibili provenienti da modelli, Plugin o canali all'interno del confine di un singolo operatore attendibile.

Cosa aggiunge Python

Su POSIX, l'helper facoltativo mantiene un processo Python persistente e utilizza operazioni sul file system relative ai descrittori di file per le modifiche alle directory superiori: rinomina, rimozione, creazione di directory, rilevamento dello stato/elenco e alcuni percorsi di scrittura.

Ciò riduce le finestre temporali per condizioni di competizione con lo stesso UID, nelle quali un altro processo sostituisce una directory superiore tra la convalida e la modifica: una difesa in profondità sugli host in cui processi locali non attendibili possono modificare le stesse directory in cui opera OpenClaw.

Se la tua distribuzione presenta questo rischio e la presenza di Python è garantita, imposta:

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Indicazioni per Plugin e core

• L'accesso ai file da parte dei Plugin deve avvenire tramite gli helper openclaw/plugin-sdk/*, non direttamente tramite fs, quando un percorso proviene da un messaggio, dall'output di un modello, dalla configurazione o dall'input di un Plugin.
• Il codice core deve utilizzare i wrapper fs-safe in src/infra/*, affinché i criteri di processo di OpenClaw siano applicati in modo coerente.
• L'estrazione degli archivi deve utilizzare gli helper per archivi di fs-safe con limiti espliciti per dimensioni, numero di elementi, collegamenti e destinazione.
• I segreti devono utilizzare gli helper per i segreti di OpenClaw oppure gli helper di fs-safe per segreti e stato privato; non implementare manualmente controlli delle modalità di accesso attorno a fs.writeFile.
• Per l'isolamento da utenti locali ostili, non affidarti esclusivamente a fs-safe. Esegui Gateway separati con utenti del sistema operativo o host distinti oppure utilizza una sandbox.

Vedi anche: Sicurezza, Uso della sandbox, Approvazioni dell'esecuzione, Segreti.