Policy Schema Reference¶

完整的沙箱策略 YAML 欄位參考。每個欄位都記錄了其類型、是否必要以及是靜態（在沙箱建立時鎖定）還是動態（在運行中的沙箱上可熱重載）。

Top-Level Structure¶

策略 YAML 檔案包含以下頂層欄位：

version: 1
filesystem_policy: { ... }
landlock: { ... }
process: { ... }
network_policies: { ... }

靜態字段在沙箱建立時設定。更改這些欄位需要銷毀並重新建立沙箱。動態欄位可以在已執行且設定了 openshell 策略的沙箱上更新(openshell policy set)，並且無需重新啟動即可生效。

Version¶

版本(version)欄位用於標識策略使用的 scheam：

Filesystem Policy¶

Category: Static

控製沙箱內的檔案系統存取。未列入唯讀 read_only 或讀寫 read_write 清單的路徑將無法存取。

Validation constraints:

• 所有路徑必須是絕對路徑（以 / 開頭）。
• 路徑中不得包含 .. 遍歷組件。伺服器會在儲存路徑前進行標準化，但會拒絕遍歷範圍超出預期的策略。
• 讀寫路徑(Read-write paths)不能過寬（例如，僅包含 / 的路徑會被拒絕）。
• 每個路徑的長度不得超過 4096 個字元。
• read_only 和 read_write 路徑的總長度不得超過 256 個字元。

違反這些約束的策略在建立或更新時會被拒絕，並傳回 INVALID_ARGUMENT 錯誤。磁碟載入的 YAML 策略如果驗證失敗，則會回退到限制性更強的預設值。

範例:

filesystem_policy:
  include_workdir: true
  read_only:
    - /usr
    - /lib
    - /proc
    - /dev/urandom
    - /etc
  read_write:
    - /sandbox
    - /tmp
    - /dev/null

Landlock¶

Category: Static

在核心層級配置 Landlock LSM 強制執行。 Landlock 提供低於 UNIX 權限允許的強制性檔案系統存取控制。

Compatibility modes:

best_effort（預設值）適用於大多數部署。它能優雅地處理缺失路徑——例如，/app 路徑可能並非存在於每個容器鏡像中，但對於存在該路徑的容器，它會被包含在基線路徑集中。對於個別缺少的路徑，系統會跳過處理，同時仍強制執行其餘檔案系統規則。

hard_requirement 適用於檔案系統隔離中任何漏洞都無法接受的環境。如果列出的路徑因任何原因（缺失、權限被拒絕、符號連結循環）無法打開，沙箱啟動將立即失敗，而不是以降低的保護等級運作。

當在 best_effort 模式下跳過某個路徑時，沙箱會記錄一條警告，其中包含該路徑、具體錯誤以及人類可讀的原因（例如，“path does not exist” 或 “permission denied”）。

範例:

landlock:
  compatibility: best_effort

Process¶

Category: Static

設定沙箱內 agent 程式的作業系統級身分。

Validation constraint：run_as_user 和 run_as_group 都不能設定為 root 或 0。請求 root 進程身分的策略在建立或更新時將被拒絕。

範例:

process:
  run_as_user: sandbox
  run_as_group: sandbox

Network Policies¶

Category: Dynamic

一個包含命名網路策略條目的映射表。每個條目聲明一組端點和一組二進位檔案。只有列出的二進位檔案才能連接到列出的端點。映射表的鍵是一個邏輯標識符。條目中的 name 欄位是日誌中使用的顯示名稱。

Network Policy Entry¶

network_policies 映射中的每個條目都包含以下欄位：