範例

總覽

我們準備了幾個範例，說明如何在不同情境中使用 Sandbox2，以及如何編寫政策。

您可以在 //sandboxed_api/sandbox2/examples 中找到這些範例，詳情請參閱下文。

CRC4

CRC4 範例是刻意設計的 CRC4 總和檢查碼計算錯誤，用來示範如何將其他程式放入沙箱，以及如何與該程式通訊。

  • crc4bin.cc：我們要採用沙箱機制的程式 (即 Sandboxee)
  • crc4sandbox.cc：將執行該程式的沙箱程式 (即執行器)。

運作方式：

  1. 執行器會使用 ::sandbox2::GetDataDependencyFilePath()，從檔案路徑啟動 Sandboxee。
  2. 執行器會使用 SendBytes()，透過通訊管道 Comms 將輸入內容傳送至 Sandboxee。
  3. Sandboxee 會計算 CRC4，並透過通訊管道 Comms 將回覆傳送回執行者，執行者會使用 RecvUint32() 接收回覆。

如果程式進行通訊 (read() 和 write()) 以外的任何系統呼叫，就會因違反政策而遭到終止。

靜態

靜態範例會示範如何將靜態連結的二進位檔 (例如您沒有來源的第三方二進位檔) 沙箱化，也就是說，該二進位檔並不知道自己會沙箱化。

  • static_bin.cc：Sandboxee 是靜態 C 二進位檔，可將標準輸入的 ASCII 文字轉換為大寫。
  • static_sandbox.cc：執行器及其政策、限制，以及用於 Sandboxee 輸入內容的檔案描述元。

運作方式：

  1. 執行器會使用 GetDataDependencyFilepath 從檔案路徑啟動 Sandboxee，就像 CRC4 一樣。
  2. 這會設定限制、在 /proc/version 上開啟檔案描述元，並標記要在 Sandboxee 中使用 MapFd 對應的檔案。
  3. 這項政策允許部分系統呼叫 (open) 傳回錯誤 (ENOENT)，而不是因違反政策而遭到終止。當您對第三方程式進行沙箱測試時，這項功能會很有用，因為我們無法修改所做的系統呼叫，因此可以改為讓這些呼叫正常失敗。

工具

這個工具範例既是開發自家政策和實驗 Sandbox2 API 的工具，也是功能展示。

  • sandbox2tool.cc：示範執行器的範例：
    • 如何執行其他沙箱化二進位檔，
    • 如何設定檔案系統檢查，以及
    • 執行器如何非同步執行 Sandboxee，以逐步讀取其輸出內容。

親自試試看：

Bazel

bazel run //sandboxed_api/sandbox2/examples/tool:sandbox2tool -- \
--sandbox2tool_resolve_and_add_libraries \
--sandbox2tool_additional_bind_mounts /etc \
/bin/cat /etc/hostname

CMake + Ninja

cd build-dir
ninja sandbox2_sandbox2tool && \
./sandbox2_sandbox2tool \
--sandbox2tool_resolve_and_add_libraries \
--sandbox2tool_additional_bind_mounts /etc \
/bin/cat /etc/hostname

Google3 (Blaze)

blaze run //third_party/sandboxed_api/sandbox2/examples/tool:sandbox2tool -- \
 --sandbox2tool_resolve_and_add_libraries \
 --sandbox2tool_additional_bind_mounts /etc \
 /bin/cat /etc/hostname

旗標：

  • --sandbox2tool_resolve_and_add_libraries，為 Sandboxee 解決並掛接必要的程式庫
  • --sandbox2tool_additional_bind_mounts <PATHS>，讓 Sandboxee 可使用其他目錄
  • --sandbox2tool_keep_env，保留目前的環境變數
  • --sandbox2tool_redirect_fd1，接收 Sandboxee STDOUT_FILENO (1) 並在本機輸出
  • --sandbox2tool_cpu_timeout，以秒為單位設定 CPU 逾時時間
  • --sandbox2tool_walltime_timeout：以秒為單位設定實際時間逾時
  • --sandbox2tool_file_size_creation_limit，設定建立的檔案大小上限
  • --sandbox2tool_cwd 設定沙箱的目前工作目錄

custom_fork

custom_fork 範例示範如何建立沙箱，初始化二進位檔，然後等待來自父項執行器的 fork() 要求。

相較於其他類型的沙箱，這個模式可能可提升效能，因為建立 Sandboxee 的新執行個體時，不需要執行新的二進位檔，只要分叉現有執行個體即可

  • custom_fork_bin.cc：自訂 fork 伺服器，接收 fork() 的要求 (透過 Client::WaitAndFork)，以便產生新的 Sandboxee。
  • custom_fork_sandbox.cc：執行器，可啟動自訂 Fork 伺服器。然後，它會透過新的執行器向該服務傳送要求，以產生新的 Sandboxee (透過 fork())。

網路

網路命名空間預設為啟用，可防止沙箱處理程序連線至外部世界。這個範例說明如何處理這項問題。

連線會在執行器內初始化，產生的通訊端會透過 ::sandbox2::Comms::SendFD() 傳遞。Sandboxee 會使用 ::sandbox2::Comms::RecvFD() 接收通訊端，然後就能照常使用這個通訊端交換資料。

network_proxy

這個範例示範處理網路命名空間的替代方式。在內部，這個函式的運作方式與上述範例完全相同，但會以更方便的 API 形式公開。

Sandboxee 可以透過 2 種不同方式建立網路連線：

  • 自動：安裝自動處理常式，然後發出一般連線呼叫。
  • 手動：取得 NetworkProxyClient 並直接使用 NetworkProxyClient::Connect。

這個範例會說明這兩種方法。如果設定 connect_with_handler 旗標，系統會使用自動模式，否則會使用手動模式。