08 · MCP、許可權與 Sandbox 怎麼管
Antigravity 安全治理實踐：MCP 最小開放、Allow/Deny/Ask、terminal sandbox、workspace file access、browser allowlist 和任務級放權。
Antigravity 的安全問題不是“能不能信任模型”，而是“你給了 agent 哪些工具、哪些路徑、哪些 URL、哪些自動執行許可權”。只要它能呼叫 terminal、browser、MCP 和檔案系統，就必須把許可權當成工程設計。
官方安全相關文件把控制點拆得很細：MCP 有 resources（上下文資源）和 tools（工具）；Browser 有 allowlist / denylist（允許 / 拒絕名單）；Strict Mode（嚴格模式）會強制多類動作 Request Review（請求人工審閱）；Sandboxing（沙箱）會限制 terminal 命令的檔案系統和網路訪問。真實專案要組合這些設定，而不是隻開一個"安全開關"。
預設策略：先 Ask，再 Allow。先 workspace-only，再最小路徑。先本地域名，再外部 URL。先只讀 MCP，再寫操作。
閱讀目標：讀完本章，你應該能為一個有 secrets 的真實專案配置 browser、terminal、file、MCP 四類邊界。
1. 四個風險面
flowchart TD
Agent["Antigravity Agent"] --> Terminal["Terminal commands"]
Agent --> File["File access"]
Agent --> Browser["Browser URLs / JavaScript"]
Agent --> MCP["MCP tools"]
Terminal --> Risk1["刪除 / 上傳 / 部署 / SSH"]
File --> Risk2["金鑰 / 私人檔案 / 非專案目錄"]
Browser --> Risk3["prompt injection / 賬號後臺"]
MCP --> Risk4["外部副作用 / 資料讀取"]任何一個風險面過寬，都會讓 agent 變成不可控執行器。
2. Allow / Deny / Ask 的組合
| 模式 | 適合 | 風險 |
|---|---|---|
| Ask by default | 真實專案、初期使用、團隊環境 | 速度慢，但邊界清楚 |
| Allow low-risk | 重複低風險命令 | 需要定期清理 |
| Deny dangerous | Always Proceed 的兜底 | 容易漏列危險動作 |
推薦組合：
默认 Ask
Allow: ls、git status、读取官方文档域名、读取本地 workspace
Deny: rm、ssh、git push、上传命令、凭据目录這裡的關鍵不是列出所有危險命令，而是先把預設狀態設成 Ask。真實專案裡，Allow 只適合低副作用、可重複、可解釋的動作，例如 rg、git status、測試命令；部署、推送、刪除、遠端連線、資料庫遷移都不應該自動執行。
2.5 Allow / Deny / Ask 的具體寫法
上面的"自然語言"例子只是原則說明。在真實 Antigravity 設定裡，每條規則必須寫成官方的資源字串格式：
action(target)官方 Agent Permissions 文件列出 5 種 action：
| Action | Target 格式 | 匹配方式 |
|---|---|---|
command | command(prefix) 或 command(*) | 按命令字首匹配。command(git) 同時匹配 git add / git commit 等 |
read_file | read_file(/abs/path) | 匹配檔案或目錄下所有內容；必須絕對路徑，不支援 *.go glob、不支援正則、不支援 ~ |
write_file | write_file(/abs/path) | 與 read_file 同；寫許可權隱式包含同路徑的讀許可權 |
read_url | read_url(domain) 或 read_url(*) | 匹配域名 + 所有子域，不匹配 URL 路徑 |
mcp | mcp(server/tool) / mcp(server/*) / mcp(*) | 按 server 名精確匹配；server/* 放通該 server 全部工具 |
把上面的"自然語言"清單翻譯成可寫入的真實規則：
# Allow（自动放行）
command(git status)
command(git diff)
command(ls)
read_file(/Users/me/projects/myapp)
read_url(antigravity.google)
# Deny（永远拦截）
command(rm)
command(sudo)
command(ssh)
write_file(/Users/me/.ssh)
write_file(/Users/me/.aws)
# Ask（每次问）
command(*)
mcp(*)三個高頻踩坑：① read_file / write_file 不能寫 ~/projects 或 *.env 這類 shell 風格——必須絕對路徑；② command(git) 會匹配所有 git 子命令（包括 git push），如果要細，寫 command(git status)、command(git diff)；③ write_file(/some/path) 會隱式給同路徑開 read_file，不要為了"只讀"反而把目錄寫成 write_file。
3. Strict Mode 的作用
官方 Strict Mode 文件說明，開啟後會強制收緊這些行為：
| 領域 | Strict Mode 行為 |
|---|---|
| Browser URL | 外部 markdown 圖片和 Read URL tool 受 allowlist / denylist 控制 |
| Terminal Auto Execution | 強制 Request Review，忽略 terminal allowlist |
| Browser JavaScript Execution | 強制 Request Review |
| Artifact Review | 強制 Request Review |
| File System Access | respect .gitignore，停用 workspace 外檔案訪問 |
這對真實專案很有價值，因為它會覆蓋之前過寬的自動執行設定。尤其是 terminal allowlist 被忽略這一點，可以防止你以為進入安全模式，實際上舊 allowlist 還在放行命令。
建議起點：
Strict Mode: on
Artifact Review: Request Review
Terminal Auto Execution: Request Review
Browser JavaScript Execution: Request Review
Non-Workspace File Access: off4. Terminal sandbox
Sandbox 是執行限制，不是授權策略。即使啟用 sandbox，也不能隨便允許：
- 刪除命令
- 部署命令
- 上傳命令
- 連線遠端
- 修改系統配置
- 寫 workspace 外目錄
Permission 解決“能不能做”，sandbox 解決“做的時候被限制在哪”。兩者都要有。
官方 Sandboxing 文件說明，terminal sandbox 為 Agent 執行的命令提供 kernel-level isolation。macOS 使用 Seatbelt，也就是 sandbox-exec；Linux 使用 nsjail。啟用後可以限制命令寫 workspace 外檔案，也可以單獨控制網路訪問。
Sandbox 當前預設關閉（官方原話："Sandboxing is currently disabled by default, but this may change in future releases."）。也就是說，如果你只是開了 Antigravity 沒動設定，agent 跑命令是沒有 kernel 層隔離的。商業專案第一件事就是去 Antigravity User Settings 開啟 "Enable Terminal Sandboxing"，並按需開/關 "Sandbox Allow Network"。
反過來，開啟 Strict Mode 時官方會自動啟用 sandbox 並預設停用網路——這是 Strict Mode 的副作用之一，不需要單獨再開。
如果命令被 sandbox 攔住，不要第一反應永久關閉 sandbox。先判斷它是否真的需要：
| 情況 | 推薦處理 |
|---|---|
| 測試指令碼寫 workspace 外快取 | 優先改測試或臨時目錄 |
| 構建需要聯網下載 | 單次允許網路，檢查 lockfile |
| 部署命令被攔 | 不自動部署，改成人工執行 |
| 讀取 home 目錄配置 | 改成複製必要檔案到 workspace |
| 確認只是一次性例外 | Request Review 下單命令 bypass |
5. File access
預設 workspace-only 是正確的。非 workspace 檔案訪問只適合非常明確的臨時任務，例如讀取一個指定日誌檔案。不要授權：
| 路徑 | 原因 |
|---|---|
| 使用者家目錄 | 範圍過大 |
| 憑據目錄 | token 和金鑰風險 |
| 雲同步根目錄 | 私人資料和歷史檔案 |
| 系統配置目錄 | 破壞環境 |
| 其他專案根目錄 | 任務邊界混亂 |
Strict Mode 會 respect .gitignore，這點很重要。.gitignore 經常包含 .env、構建產物、快取、憑據、私有輸出目錄。不要為了“讓 agent 看更多上下文”就讓它讀這些檔案。
6. Browser allowlist
瀏覽器能力必須按域名限制。常用策略：
- 本地驗證只 allow
localhost。 - 查官方資料只 allow 官方域名。
- 社群網頁臨時 allow。
- 登入後臺不預設 allow 自動點選。
- 任務完成後清理臨時域名。
官方 Allowlist / Denylist 文件說明，Browser 有兩層 URL 控制：server-side denylist（雲端拒絕名單，由 Google Superroots BadUrlsChecker 服務維護）和本地 allowlist（一份你可以手動編輯的本地文本檔案）。denylist 優先，denylist 服務不可用時預設拒絕訪問；allowlist 初始只有 localhost。
實際觸發時有三種處理路徑：
| 觸發場景 | 你能做什麼 |
|---|---|
| agent 想訪問非 allowlist URL | 彈出視窗給 Always allow 按鈕——點了就把這條 URL 加進 allowlist |
| 想批次預先放行 | 直接編輯 allowlist 本地文本檔案（新增 / 刪除 URL） |
| URL 在 denylist 裡 | 即使 allowlist 添了也無效——denylist 永遠優先 |
實操 prompt 可以寫：
Browser 只允许访问：
1. http://localhost:3000
2. https://antigravity.google/docs
如果遇到登录、支付、广告后台、云控制台或外部跳转，立刻停止并报告。
不要点击 always allow，除非我明确批准。7. MCP 最小開放
MCP 的風險在於 tool 的外部副作用。一個 MCP server 可能看起來只是“查資料”，實際也可能寫檔案、發請求、建立資源。
治理清單：
- 先列出 server 和 tool。
- 寫操作預設 Ask。
- 只讀工具也要限制域名或資源範圍。
- 不把大型 MCP 全域性常駐。
- 每個 workspace 單獨決定 MCP。
- 團隊專案把 MCP 配置納入審查。
官方 MCP 文件把能力分成兩類：
| MCP 能力 | 價值 | 風險 |
|---|---|---|
| Context Resources | 讀取資料庫 schema、日誌、文件、上下文 | 洩露業務資料、客戶資料、內部日誌 |
| Custom Tools | 建立 Linear issue、搜尋 GitHub/Notion、呼叫外部服務 | 觸發寫操作、建立資源、改遠端狀態 |
Antigravity 安裝 MCP server 有兩種方式：① 透過內建 MCP Store（編輯器 agent panel 的 ... 下拉 → MCP Store → Browse & Install），覆蓋 GitHub / Linear / Notion / Stripe / Supabase / Figma 等 30+ 官方接入；② 自己寫自定義 server 配置。兩者最終都落到同一份配置檔案：
~/.gemini/antigravity/mcp_config.json每個 server 條目支援的關鍵欄位：
| 欄位 | 作用 |
|---|---|
command 或 serverUrl | stdio 二選一傳輸；前者本地執行檔，後者遠端 HTTP server |
args / env / cwd | 啟動命令引數、環境變數、工作目錄（僅 stdio） |
headers | 遠端 server 的自定義 HTTP 頭（如 Authorization: Bearer ...） |
authProviderType | 認證提供方，"google_credentials" 走 Google ADC（gcloud auth application-default login） |
oauth.clientId / clientSecret | 不支援 OAuth 動態註冊的 server 用這個手動配 |
disabled | 臨時停用整個 server，但保留配置 |
disabledTools | 陣列，指名停用 server 上的某些 tools，其餘可用 |
商業專案裡，不要因為需要某個只讀 resource 就放開整個 server 的所有 tools。能寫 GitHub、Stripe、PayPal、資料庫、雲服務、CMS 的 tool 預設在 disabledTools 裡列上，再用 Allow/Deny/Ask 配 mcp(server/tool) 資源字串做第二層閘門。
8. 按任務放權
最穩的方式不是一次性設定完，而是按任務放權：
| 階段 | 許可權 |
|---|---|
| 只讀分析 | read workspace |
| 單檔案小改 | write 指定目錄或檔案 |
| 本地驗證 | command(dev server) + read localhost |
| UI 錄屏 | browser allowlist |
| 釋出前 | 只生成 checklist，不自動部署 |
一個安全 prompt 可以這樣寫：
先只读分析，不要修改文件。
只允许读取当前 workspace，不允许读取 workspace 外文件。
如果需要 terminal、browser 或 MCP，请先说明目的、命令/URL/tool 名称和风险。
本轮禁止 git push、部署、删除文件、写外部系统。9. 商業專案預設配置
| 控制項 | 預設建議 |
|---|---|
| Strict Mode | 開啟 |
| Terminal Sandboxing | 開啟 |
| Sandbox Network | 預設關閉，需要時單次批准 |
| Terminal Auto Execution | Request Review |
| Artifact Review | Request Review |
| Browser JavaScript | Request Review |
| Browser Allowlist | localhost + 必要官方域名 |
| Non-Workspace File Access | 關閉 |
| MCP | workspace 級配置，寫操作預設停用 |
| Secrets | 不讀、不貼、不寫入儲存庫 |
這套設定會慢一點，但可解釋、可審計、可回退。商業級上線前，速度不是第一優先順序，邊界清楚才是。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
- Strict Mode 會強制收緊哪些設定？
- Sandbox 和 Request Review 分別解決什麼問題？
disabledTools為什麼比“裝不裝某個 MCP server”更細？
透過標準：你能為一個真實專案寫出 browser allowlist、terminal sandbox、MCP disabledTools 和 workspace-only 檔案訪問策略。
官方來源
- Google Antigravity MCP Integration - 官方說明 MCP Store、自定義 server、resources、tools、OAuth、headers、
disabled和disabledTools。 - Google Antigravity Strict Mode - 官方說明 strict mode 對 terminal、browser、artifact review 和 file access 的強制收緊。
- Google Antigravity Allowlist / Denylist - 官方說明 browser URL denylist、allowlist、localhost 初始狀態和 denylist 優先順序。
- Google Antigravity Sandboxing Terminal Commands - 官方說明 terminal sandbox、檔案系統限制、網路限制、單命令 bypass 和 strict mode 關係。