Bezpieczne operacje na plikach

OpenClaw używa biblioteki @openclaw/fs-safe do lokalnych operacji na plikach o znaczeniu dla bezpieczeństwa: odczytów i zapisów ograniczonych do katalogu głównego, atomowego zastępowania, wyodrębniania archiwów, tymczasowych przestrzeni roboczych, stanu w formacie JSON oraz obsługi plików z danymi poufnymi.

Jest to mechanizm ochronny biblioteki przeznaczony dla zaufanego kodu OpenClaw, który otrzymuje niezaufane nazwy ścieżek, a nie piaskownica. Uprawnienia systemu plików hosta, użytkownicy systemu operacyjnego, kontenery oraz zasady agenta i narzędzi nadal wyznaczają rzeczywisty zasięg potencjalnych szkód.

Domyślnie: bez pomocniczego procesu Pythona

OpenClaw domyślnie ustawia pomocniczy proces Pythona dla fs-safe w systemach POSIX jako wyłączony:

• Gateway nie powinien uruchamiać trwałego procesu pomocniczego Pythona, chyba że operator jawnie go włączy;
• większość instalacji nie potrzebuje dodatkowego zabezpieczenia przed modyfikacją katalogów nadrzędnych;
• wyłączenie Pythona zapewnia przewidywalne działanie środowiska uruchomieniowego na komputerach stacjonarnych oraz w środowiskach Docker, CI i aplikacji pakietowych.

OpenClaw zmienia jedynie wartość domyślną. Jawne ustawienie ma zawsze pierwszeństwo:

# Domyślne zachowanie OpenClaw: mechanizmy zastępcze fs-safe używające tylko Node.OPENCLAW_FS_SAFE_PYTHON_MODE=off # Używaj procesu pomocniczego, gdy jest dostępny, a w przeciwnym razie zastosuj mechanizm zastępczy.OPENCLAW_FS_SAFE_PYTHON_MODE=auto # Odmów działania, jeśli nie można uruchomić procesu pomocniczego.OPENCLAW_FS_SAFE_PYTHON_MODE=require # Opcjonalna jawna ścieżka do interpretera.OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

Działają również ogólne nazwy zmiennych środowiskowych fs-safe: FS_SAFE_PYTHON_MODE i FS_SAFE_PYTHON.

Użyj require (nie auto), jeśli proces pomocniczy jest elementem przyjętego modelu bezpieczeństwa; w trybie auto, gdy nie można go uruchomić, następuje ciche przejście do działania opartego wyłącznie na Node.

Co pozostaje chronione bez Pythona

Gdy proces pomocniczy jest wyłączony, OpenClaw nadal korzysta z mechanizmów ochronnych fs-safe opartych wyłącznie na Node:

• odrzuca próby wyjścia poza ścieżkę względną (..), ścieżki bezwzględne oraz separatory ścieżek tam, gdzie dozwolone są wyłącznie proste nazwy;
• wykonuje operacje za pośrednictwem zaufanego uchwytu katalogu głównego zamiast doraźnych kontroli path.resolve(...).startsWith(...);
• odrzuca wzorce dowiązań symbolicznych i twardych w interfejsach API, które wymagają takiej zasady;
• otwiera pliki z kontrolą tożsamości, gdy interfejs API zwraca lub pobiera ich zawartość;
• zapisuje pliki stanu i konfiguracji za pomocą tymczasowego pliku równorzędnego oraz atomowej operacji zmiany nazwy;
• wymusza limity bajtów podczas odczytu i wyodrębniania archiwów;
• stosuje prywatne tryby uprawnień do plików z danymi poufnymi i plików stanu, gdy wymaga tego interfejs API.

Obejmuje to standardowy model zagrożeń OpenClaw: zaufany kod Gateway obsługujący niezaufane dane wejściowe ścieżek pochodzące z modelu, Pluginu lub kanału w ramach jednej zaufanej granicy operatora.

Co dodaje Python

W systemach POSIX opcjonalny proces pomocniczy utrzymuje jeden trwały proces Pythona i używa operacji systemu plików względem deskryptora pliku do modyfikowania katalogów nadrzędnych: zmiany nazw, usuwania, tworzenia katalogów, pobierania informacji i wyświetlania zawartości oraz niektórych operacji zapisu.

Ogranicza to okna wyścigu między procesami o tym samym UID, w których inny proces podmienia katalog nadrzędny między walidacją a modyfikacją — jest to dodatkowa warstwa ochrony na hostach, gdzie niezaufane procesy lokalne mogą modyfikować te same katalogi, na których działa OpenClaw.

Jeśli wdrożenie jest narażone na takie ryzyko, a dostępność Pythona jest zagwarantowana, ustaw:

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Wskazówki dotyczące Pluginów i rdzenia

• Dostęp Pluginu do plików powinien odbywać się za pośrednictwem funkcji pomocniczych openclaw/plugin-sdk/*, a nie bezpośrednio przez fs, gdy ścieżka pochodzi z wiadomości, danych wyjściowych modelu, konfiguracji lub danych wejściowych Pluginu.
• Kod rdzenia powinien używać opakowań fs-safe z src/infra/*, aby zasady procesu OpenClaw były stosowane spójnie.
• Do wyodrębniania archiwów należy używać funkcji pomocniczych fs-safe z jawnymi limitami rozmiaru, liczby wpisów, dowiązań i miejsca docelowego.
• Dane poufne powinny być obsługiwane za pomocą funkcji pomocniczych OpenClaw do danych poufnych albo funkcji fs-safe do danych poufnych lub prywatnego stanu; nie należy samodzielnie implementować kontroli trybów uprawnień wokół fs.writeFile.
• Aby zapewnić izolację od wrogich użytkowników lokalnych, nie należy polegać wyłącznie na fs-safe. Uruchamiaj oddzielne instancje Gateway dla różnych użytkowników systemu operacyjnego lub na różnych hostach albo zastosuj piaskownicę.

Powiązane: Bezpieczeństwo, Piaskownica, Zatwierdzanie wykonania, Dane poufne.