BakeLens/crust

🌟 Open Source AI Agent Security Infrastructure — intercepts and blocks dangerous agent behaviors before they happen. Just one command! Join us to build safer Human-AI Symbiosis!

Crust – AI代理的本地安全閘道

是什麼 – Crust 是一個開源、本地執行的代理，位於 AI 驅動的程式碼助手（或任何 LLM 支援的工具）與 LLM 提供者之間。它監控代理執行的每一次工具呼叫（檔案讀取、shell 命令、網路請求等），並阻止可能洩漏機密或損害主機的動作。

為何重要 – 現代 AI 代理與開發者的程式碼和憑證運行在同一台機器上。如果模型被誘騙（提示注入、惡意輸出等），它可能會嘗試讀取 .env 檔案、SSH 金鑰、瀏覽器 Cookie，甚至執行危險的 shell 命令。Crust 在這些呼叫抵達作業系統之前進行攔截，確保使用者資料留在裝置內，且無需修改代理程式碼。

工作原理

入口點	命令	保護內容
HTTP 代理	`crust start`	作為任何 OpenAI 相容 API 的正向代理。掃描請求負載（對話歷史）與回應（工具呼叫）中的機密、危險命令、路徑遍歷等。
MCP stdio 網關	`crust wrap -- <cmd>`	包裝 Model Context Protocol (MCP) 伺服器，攔截 `tools/call` 與 `resources/read` 訊息。
MCP HTTP 網關	`crust wrap -- <cmd>`	流式 HTTP MCP 伺服器的反向代理。
ACP stdio 代理	`crust wrap -- <cmd>`	包裝 Agent Client Protocol (ACP) 代理（如 JetBrains AI、VS Code 擴充），並阻止檔案系統或終端操作。
自動偵測	`crust wrap -- <cmd>`	偵測子流程是否使用 MCP 或 ACP，並套用相應過濾器。

所有入口點共享一個 17 步評估流程，在微秒內完成：

自我保護（防止代理停用 Crust）
輸入淨化
Unicode 正規化
混淆偵測
DLP 機密掃描
路徑正規化
符號連結解析
规則匹配（42 個內建規則，51 個 DLP 模式） 9–17. 其他檢查（大小限制、TLS 強制、日誌記錄等）

每個決策都會記錄到加密的本地儲存，日誌本身也由 OS 密鑰環保護。

快速開始（桌面）

# macOS / Linux / BSD
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/BakeLens/crust/main/install.sh)"
# Windows (PowerShell)
irm https://raw.githubusercontent.com/BakeLens/crust/main/install.ps1 | iex
# Docker（可選）
 docker compose up -d   # 或手動建構/執行

然後啟動代理：

crust start          # 預設監聽 0.0.0.0:9090
crust status         # 確認是否正在執行

閘道會根據模型名稱自動偵測 LLM 提供者，因此您可以保留現有的 API 金鑰不變。

連接代理（範例）

將代理的基底 URL 設定為 http://localhost:9090/v1（某些客戶端可直接使用 http://localhost:9090）。README 列出了數十種支援的工具——Claude Code、OpenAI Codex CLI、Cursor、JetBrains AI、Continue、Aider 等。對於任何 OpenAI 相容客戶端，相同的環境變數皆適用：

export OPENAI_BASE_URL=http://localhost:9090/v1   # 或 ANTHROPIC_BASE_URL 等

Crust 將轉發請求，應用其規則引擎，並僅允許安全的工具呼叫抵達提供者。

移動端 / iOS 集成

Crust 提供 Swift 套件 CrustKit，可嵌入 iOS 15+ 應用。提供三種整合方式：

本地反向代理 – 在裝置上執行小型 HTTP 代理，並將 AI SDK 指向它。
URLProtocol – 註冊 CrustURLProtocol，使任何 URLSession 自動透過引擎（零設定）。
直接評估 – 呼叫 engine.evaluateAsync(...) 進行手動檢查。相同的規則集（包含 7 個行動端專用鎖定規則）保護聯絡人、照片、鑰匙圈、剪貼簿讀取、危險 URL 方案、藍牙/NFC、生物辨識 API 與應用內購買。

內建保護規則

42 個安全規則（39 個鎖定，3 個使用者可停用）：涵蓋憑證、系統認證檔案、shell 歷史、瀏覽器資料、套件註冊表金鑰、Git 憑證、持久化機制、行動端 PII、鑰匙圈、剪貼簿、URL 方案、硬體存取、加密錢包等。
51 個 DLP 模式：可識別真實 API 金鑰、金鑰、PEM 私鑰、BIP-39 詞彙等。
規則以純 YAML（security.yaml）與 Go 程式碼定義，便於審計或擴充。
項目聲稱已通過 84 個真實世界 CVE 的驗證，影響流行的 AI 助手（Cursor、GitHub Copilot、Claude Code、OpenAI Codex 等）。

自訂規則與外掛

自訂規則 – 新增 YAML 檔案：crust add-rule my-rules.yaml。支援熱重載，變更立即生效。
外掛 – 可選的後段過濾器，在隔離程序中執行。透過換行分隔的 JSON 通訊，可用任意語言撰寫，且具備電路斷路器機制，三次失敗後自動停用異常外掛。
Python 範例外掛示範如何在允許檔案存取前強制執行專案目錄沙箱。

Crust 自身的安全姿態

僅監聽本機；無外部網路暴露。
代理無法停用或重新設定閘道（硬編碼預過濾）。
機密與日誌儲存在 OS 密鑰環與加密 SQLite 資料庫中。
所有與 LLM 提供者的通訊皆使用 TLS 1.2+。
CI 每次提交均執行 gosec、semgrep、模糊測試（46 個目標）、govulncheck 與 gitleaks。

參與方式

使用 Go 1.26+ 從原始碼建置（go build .）。
透過拉取請求貢獻新安全規則或外掛。
透過 GitHub 問題追蹤器或 SECURITY.md 中描述的私密揭露流程報告漏洞或安全問題。

授權

Crust 以 Elastic License 2.0 發布，允許使用、修改與分發，但禁止作為競爭服務提供。

結論 – Crust 為開發者提供一個即插即用、本地執行的防護盾，可阻止 AI 代理意外（或惡意）洩漏機密、執行破壞性命令或存取特權資源，且無需修改代理程式碼。