Veilige bestandsbewerkingen

OpenClaw gebruikt @openclaw/fs-safe voor beveiligingsgevoelige lokale bestandsbewerkingen: tot een hoofdmap begrensd lezen/schrijven, atomair vervangen, archieven uitpakken, tijdelijke werkruimten, JSON-status en verwerking van geheime bestanden.

Het is een beveiligingsmechanisme in de bibliotheek voor vertrouwde OpenClaw-code die niet-vertrouwde padnamen ontvangt, geen sandbox. Bestandssysteemmachtigingen van de host, OS-gebruikers, containers en het agent-/toolbeleid bepalen nog steeds de werkelijke impact.

Standaard: geen Python-helper

OpenClaw schakelt de POSIX Python-helper van fs-safe standaard uit:

• de Gateway mag geen permanente Python-sidecar starten, tenzij een beheerder daar expliciet voor kiest;
• de meeste installaties hebben de extra beveiliging tegen wijzigingen van bovenliggende mappen niet nodig;
• door Python uit te schakelen, blijft het runtimegedrag voorspelbaar in desktop-, Docker-, CI- en gebundelde app-omgevingen.

OpenClaw wijzigt alleen de standaardwaarde. Een expliciete instelling heeft altijd voorrang:

# Standaardgedrag van OpenClaw: uitsluitend op Node gebaseerde fs-safe-fallbacks.OPENCLAW_FS_SAFE_PYTHON_MODE=off # Gebruik de helper indien beschikbaar, met een fallback als deze niet beschikbaar is.OPENCLAW_FS_SAFE_PYTHON_MODE=auto # Stop veilig als de helper niet kan starten.OPENCLAW_FS_SAFE_PYTHON_MODE=require # Optioneel expliciet pad naar de interpreter.OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

De algemene fs-safe-omgevingsvariabelen werken ook: FS_SAFE_PYTHON_MODE en FS_SAFE_PYTHON.

Gebruik require (niet auto) wanneer de helper deel uitmaakt van je beveiligingsmodel; auto valt stilzwijgend terug op uitsluitend Node-gebaseerd gedrag als de helper niet kan starten.

Wat zonder Python beschermd blijft

Als de helper is uitgeschakeld, profiteert OpenClaw nog steeds van de uitsluitend Node-gebaseerde beveiligingsmechanismen van fs-safe:

• weigert ontsnappingen via relatieve paden (..), absolute paden en padscheidingstekens waar alleen losse namen zijn toegestaan;
• voert bewerkingen uit via een vertrouwde hoofdmaphandle in plaats van ad-hoccontroles met path.resolve(...).startsWith(...);
• weigert patronen met symbolische en harde koppelingen voor API's waarvoor dat beleid geldt;
• opent bestanden met identiteitscontroles wanneer de API bestandsinhoud retourneert of verwerkt;
• schrijft status-/configuratiebestanden via een atomair tijdelijk bestand in dezelfde map, gevolgd door hernoemen;
• handhaaft bytelimieten voor leesbewerkingen en het uitpakken van archieven;
• past privébestandsmodi toe op geheime en statusbestanden waar de API die vereist.

Dit dekt het normale dreigingsmodel van OpenClaw: vertrouwde Gateway-code die niet-vertrouwde padinvoer van modellen/plugins/kanalen verwerkt binnen één vertrouwde beheerdersgrens.

Wat Python toevoegt

Op POSIX houdt de optionele helper één permanent Python-proces actief en gebruikt die aan bestandsdescriptoren gerelateerde bestandssysteembewerkingen voor wijzigingen van bovenliggende mappen: hernoemen, verwijderen, mappen aanmaken, status opvragen/mappen weergeven en sommige schrijfpaden.

Dit verkleint racevensters voor dezelfde UID waarin een ander proces een bovenliggende map verwisselt tussen validatie en wijziging — extra gelaagde beveiliging op hosts waar niet-vertrouwde lokale processen dezelfde mappen kunnen wijzigen waarin OpenClaw werkt.

Als je implementatie dit risico loopt en Python gegarandeerd beschikbaar is, stel je het volgende in:

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Richtlijnen voor plugins en kerncode

• Bestandstoegang voor plugins moet via de helpers van openclaw/plugin-sdk/* verlopen, niet rechtstreeks via fs, wanneer een pad afkomstig is uit een bericht, modeluitvoer, configuratie of plugininvoer.
• Kerncode moet de fs-safe-wrappers onder src/infra/* gebruiken, zodat het procesbeleid van OpenClaw consistent wordt toegepast.
• Voor het uitpakken van archieven moeten de fs-safe-archiefhelpers worden gebruikt met expliciete limieten voor grootte, aantal items, koppelingen en bestemming.
• Voor geheimen moeten de geheimhelpers van OpenClaw of de helpers van fs-safe voor geheimen/privéstatus worden gebruikt; implementeer niet zelf moduscontroles rond fs.writeFile.
• Vertrouw voor isolatie tegen vijandige lokale gebruikers niet alleen op fs-safe. Voer afzonderlijke Gateways uit onder afzonderlijke OS-gebruikers/hosts of gebruik sandboxing.

Zie ook: Beveiliging, Sandboxing, Uitvoeringsgoedkeuringen, Geheimen.