# Security Policy (中文 (繁體)) 🌐 **Languages:** 🇺🇸 [English](../../../SECURITY.md) · 🇪🇹 [am](../am/SECURITY.md) · 🇸🇦 [ar](../ar/SECURITY.md) · 🇦🇿 [az](../az/SECURITY.md) · 🇧🇬 [bg](../bg/SECURITY.md) · 🇧🇩 [bn](../bn/SECURITY.md) · 🇧🇦 [bs](../bs/SECURITY.md) · 🇨🇿 [cs](../cs/SECURITY.md) · 🇩🇰 [da](../da/SECURITY.md) · 🇩🇪 [de](../de/SECURITY.md) · 🇬🇷 [el](../el/SECURITY.md) · 🇪🇸 [es](../es/SECURITY.md) · 🇪🇪 [et](../et/SECURITY.md) · 🇮🇷 [fa](../fa/SECURITY.md) · 🇫🇮 [fi](../fi/SECURITY.md) · 🇫🇷 [fr](../fr/SECURITY.md) · 🇮🇪 [ga](../ga/SECURITY.md) · 🇮🇳 [gu](../gu/SECURITY.md) · 🇳🇬 [ha](../ha/SECURITY.md) · 🇮🇱 [he](../he/SECURITY.md) · 🇮🇳 [hi](../hi/SECURITY.md) · 🇭🇷 [hr](../hr/SECURITY.md) · 🇭🇺 [hu](../hu/SECURITY.md) · 🇦🇲 [hy](../hy/SECURITY.md) · 🇮🇩 [id](../id/SECURITY.md) · 🇳🇬 [ig](../ig/SECURITY.md) · 🇮🇹 [it](../it/SECURITY.md) · 🇯🇵 [ja](../ja/SECURITY.md) · 🇬🇪 [ka](../ka/SECURITY.md) · 🇰🇭 [km](../km/SECURITY.md) · 🇮🇳 [kn](../kn/SECURITY.md) · 🇰🇷 [ko](../ko/SECURITY.md) · 🇱🇹 [lt](../lt/SECURITY.md) · 🇱🇻 [lv](../lv/SECURITY.md) · 🇮🇳 [ml](../ml/SECURITY.md) · 🇮🇳 [mr](../mr/SECURITY.md) · 🇲🇾 [ms](../ms/SECURITY.md) · 🇲🇹 [mt](../mt/SECURITY.md) · 🇲🇲 [my](../my/SECURITY.md) · 🇳🇵 [ne](../ne/SECURITY.md) · 🇳🇱 [nl](../nl/SECURITY.md) · 🇳🇴 [no](../no/SECURITY.md) · 🇮🇳 [or](../or/SECURITY.md) · 🇮🇳 [pa](../pa/SECURITY.md) · 🇵🇭 [phi](../phi/SECURITY.md) · 🇵🇱 [pl](../pl/SECURITY.md) · 🇵🇹 [pt](../pt/SECURITY.md) · 🇧🇷 [pt-BR](../pt-BR/SECURITY.md) · 🇷🇴 [ro](../ro/SECURITY.md) · 🇷🇺 [ru](../ru/SECURITY.md) · 🇱🇰 [si](../si/SECURITY.md) · 🇸🇰 [sk](../sk/SECURITY.md) · 🇸🇮 [sl](../sl/SECURITY.md) · 🇷🇸 [sr](../sr/SECURITY.md) · 🇸🇪 [sv](../sv/SECURITY.md) · 🇰🇪 [sw](../sw/SECURITY.md) · 🇮🇳 [ta](../ta/SECURITY.md) · 🇮🇳 [te](../te/SECURITY.md) · 🇹🇭 [th](../th/SECURITY.md) · 🇹🇷 [tr](../tr/SECURITY.md) · 🇺🇦 [uk-UA](../uk-UA/SECURITY.md) · 🇵🇰 [ur](../ur/SECURITY.md) · 🇺🇿 [uz](../uz/SECURITY.md) · 🇻🇳 [vi](../vi/SECURITY.md) · 🇳🇬 [yo](../yo/SECURITY.md) · 🇨🇳 [zh-CN](../zh-CN/SECURITY.md) --- ## 回報漏洞 如果您在 OmniRoute 中發現安全漏洞，請以負責任的方式回報： 1. **請勿**建立公開的 GitHub issue 2. 使用 [GitHub Security Advisories](https://github.com/diegosouzapw/OmniRoute/security/advisories/new) 3. 請包含：說明、重現步驟及潛在影響 ## 回應時程 | 階段 | 目標 | | ------------ | ----------------------- | | 確認收到 | 48 小時 | | 分類與評估 | 5 個工作天 | | 修補程式發布 | 14 個工作天（重大漏洞） | ## 支援的版本 | 版本 | 支援狀態 | | ------- | --------------------------------------------- | | 3.9.x | 🗓️ 已規劃 — LTS 分支（`stable/v3`），詳見下文 | | 3.8.x | ✅ 積極支援 | | 3.7.x | ✅ 安全性支援 | | < 3.7.0 | ❌ 不支援 | ## LTS 支援期間（v3.9.x） 3.8.59 之後的下一個版本是 **3.9.0**，此版本將在 `stable/v3` 分支上開啟長期支援線（請參閱 [`ROADMAP.md`](ROADMAP.md) →「Phase 3 — v3.9.0 LTS」）。 - **`stable/v3` 會接收的內容：**錯誤修正、安全性修補程式及提供者更新。新 功能會進入 v4 頻道；LTS 支援線以穩定性為優先。在整個 v4 週期期間，`npm install omniroute` （`latest` dist-tag）會維持在 v3。 - **支援期間長度：**``。v4.0 GA 之後 （即 `latest` 切換至 v4 時）的支援期間長度**尚未決定**；維護者公布後將更新此 區段。在此之前，請勿假設結束日期。 - **回報 LTS 支援線中的漏洞：**使用與其他版本相同的管道 — 私密的 [GitHub Security Advisory](https://github.com/diegosouzapw/OmniRoute/security/advisories/new)， 絕不可建立公開 issue。請註明您測試的版本（例如 `3.9.2`）；修正會套用至 `stable/v3`，並向前移植至 v4。 - **LTS 分支建立時的安全性基準：**經測量的掃描器狀態、路由防護及 公開憑證驗證記錄於 [`docs/security/LTS_SECURITY_BASELINE.md`](docs/security/LTS_SECURITY_BASELINE.md)。 --- ## 安全性架構 OmniRoute 實作了多層式安全模型： ``` 請求 → CORS → 授權管線（分類 → 原則 → 強制執行） → 防護機制（PII 遮罩器、提示詞注入防護、視覺橋接器） → 速率限制器 → 斷路器 → 冷卻 → 模型鎖定 → 提供者 ``` ### 🔐 驗證與授權 | 功能 | 實作方式 | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **儀表板登入** | 使用 JWT 權杖（HttpOnly Cookie）的密碼式驗證 | | **API 金鑰驗證** | 使用 CRC 驗證的 HMAC 簽署金鑰 | | **OAuth 2.0 + PKCE** | 提供者特定的瀏覽器／裝置 OAuth 會在支援時使用 PKCE；僅供匯入的 Devin 憑證則會另行處理。 | | **權杖重新整理** | 在到期前自動重新整理 OAuth 權杖 | | **安全 Cookie** | HTTPS 環境使用 `AUTH_COOKIE_SECURE=true` | | **授權管線** | 路由分類（PUBLIC / CLIENT_API / MANAGEMENT）— 請參閱 `docs/architecture/AUTHZ_GUIDE.md` | | **路由防護層級** | 管理路由的三層模型（LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT）— 請參閱 `docs/security/ROUTE_GUARD_TIERS.md` | | **管理範圍 MCP** | 遠端 `/api/mcp/*` 存取由具有 `manage` 範圍的 API 金鑰控管；`/api/cli-tools/runtime/*` 維持嚴格的迴圈介面限制。請參閱 ROUTE_GUARD_TIERS | | **MCP 範圍** | 32 個細粒度範圍（read:health、write:combos、execute:completions 等）— 請參閱 `docs/frameworks/MCP-SERVER.md` | ### 🛡️ 靜態資料加密 儲存在 SQLite 中的所有敏感資料，皆使用採用 scrypt 金鑰衍生的 **AES-256-GCM** 進行加密： - API 金鑰、存取權杖、重新整理權杖及 ID 權杖 - 版本化格式：`enc:v1:::` - 未設定 `STORAGE_ENCRYPTION_KEY` 時使用直通模式（純文字） ```bash # 產生加密金鑰： STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32) ``` ### 🛡️ 防護機制框架 OmniRoute 內建一個可熱重載的**防護機制登錄檔**（`src/lib/guardrails/`），其中包含 3 個依優先順序排列的內建防護機制： | 防護機制 | 優先順序 | 用途 | | ------------------ | -------- | --------------------------------------------------------------------- | | `vision-bridge` | 5 | 使用具備影像感知能力的描述來橋接非視覺模型；為影像 URL 提供 SSRF 防護 | | `pii-masker` | 10 | 呼叫前後的 PII 遮蔽（電子郵件、電話、CPF、CNPJ、信用卡、SSN） | | `prompt-injection` | 20 | 偵測覆寫、角色劫持、越獄及洩漏模式 | 自訂防護機制可透過 `registerGuardrail(new MyGuardrail())` 註冊。此模型採用失敗時開放策略（例外狀況絕不會封鎖流量）。每個請求可透過 `x-omniroute-disabled-guardrails` 標頭選擇停用。→ 請參閱 [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md)。 ### 🧠 提示詞注入防護 盡力而為的啟發式中介軟體，用於偵測 LLM 請求中的提示詞注入模式。 **並非完整的提示詞注入防火牆** — 可能產生誤判（無害的 角色設定／RPG 提示詞）及漏判（leet 語、插入空格、非英文模式）。 | 模式類型 | 嚴重程度 | 範例 | | ---------- | -------- | ----------------------------------- | | 系統覆寫 | 高 | "忽略先前的所有指示" | | 角色劫持 | 中 | "你現在是 DAN，你可以做任何事" | | 分隔符注入 | 高 | 使用編碼後的分隔符來突破上下文邊界 | | DAN／越獄 | 中 | 已知的越獄提示詞模式 | | 指示洩漏 | 高 | "顯示你的系統提示詞" | | 編碼規避 | 中 | base64/rot13/hex 解碼搭配指示關鍵字 | 在 `block` 模式下，只有嚴重程度為**高**的偵測結果會被封鎖。中等嚴重程度的 模式類別會被記錄，但絕不會遭到 `sanitizeRequest` 封鎖。 透過儀表板（設定 → 安全性）或 `.env` 進行設定： ```env INPUT_SANITIZER_ENABLED=true INPUT_SANITIZER_MODE=block # warn | block（注入政策；舊版的 "redact" 不會移除注入文字） INPUT_SANITIZER_BLOCK_THRESHOLD=high # high（預設）| medium | low — 在 block 模式下，達到或高於此嚴重程度的項目將被封鎖 ``` ### 🔒 PII 遮蔽 自動偵測並選擇性遮蔽個人識別資訊： | PII 類型 | 模式 | 替代內容 | | ------------ | --------------------- | ------------------ | | 電子郵件 | `user@domain.com` | `[EMAIL_REDACTED]` | | CPF（巴西） | `123.456.789-00` | `[CPF_REDACTED]` | | CNPJ（巴西） | `12.345.678/0001-00` | `[CNPJ_REDACTED]` | | 信用卡 | `4111-1111-1111-1111` | `[CC_REDACTED]` | | 電話 | `+55 11 99999-9999` | `[PHONE_REDACTED]` | | SSN（美國） | `123-45-6789` | `[SSN_REDACTED]` | ```env PII_REDACTION_ENABLED=true # 重寫請求中的 PII；不受 INPUT_SANITIZER_MODE 影響 PII_RESPONSE_SANITIZATION=true # 選用：遮蔽回傳給用戶端之提供者回應中的 PII ``` ### 🌐 網路安全性 | 功能 | 說明 | | ---------------- | -------------------------------------------------------------------- | | **CORS** | 明確的跨來源允許清單（`CORS_ALLOWED_ORIGINS`；舊版為 `CORS_ORIGIN`） | | **IP 篩選** | 儀表板中的允許清單／封鎖清單 IP 範圍 | | **速率限制** | 各提供者的速率限制與自動退避 | | **防止驚群效應** | 互斥鎖 + 各連線鎖定可防止連鎖式 502 錯誤 | | **TLS 指紋** | 模擬瀏覽器式 TLS 指紋以減少機器人偵測 | | **CLI 指紋** | 各提供者的標頭／本文順序，以符合原生 CLI 特徵 | ### 🔌 韌性與可用性 | 功能 | 說明 | | ------------------ | ---------------------------------------------------------------- | | **斷路器** | 各提供者使用 3 狀態（關閉 → 開啟 → 半開啟），並持久儲存於 SQLite | | **請求冪等性** | 針對重複請求提供 5 秒去重視窗 | | **指數退避** | 以逐漸增加的延遲自動重試 | | **健康狀態儀表板** | 即時監控提供者健康狀態 | ### 📋 合規性 | 功能 | 說明 | | ---------------- | --------------------------------------------------------- | | **日誌保留** | 在 `CALL_LOG_RETENTION_DAYS` 後自動清理 | | **停用日誌選項** | 各 API 金鑰的 `noLog` 旗標可停用請求記錄 | | **稽核日誌** | 在 `audit_log` 資料表中追蹤管理操作 | | **MCP 稽核** | 針對所有 MCP 工具呼叫，使用以 SQLite 為基礎的稽核記錄 | | **Zod 驗證** | 所有 API 輸入都會在模組載入時使用 Zod v4 結構描述進行驗證 | --- ## 必要的環境變數 所有密鑰都必須在啟動伺服器前設定。若缺少密鑰或密鑰強度不足，伺服器將**立即失敗**。 ```bash # 必要 — 若未設定這些變數，伺服器將無法啟動： JWT_SECRET=$(openssl rand -base64 48) # 至少 32 個字元 API_KEY_SECRET=$(openssl rand -hex 32) # 至少 16 個字元 # 建議 — 啟用靜態資料加密： STORAGE_ENCRYPTION_KEY=$(openssl rand -hex 32) ``` 伺服器會主動拒絕已知的弱值，例如 `changeme`、`secret` 或 `password`。 --- ## Docker 安全性 - 在正式環境中使用非 root 使用者 - 將密鑰掛載為唯讀磁碟區 - 絕不將 `.env` 檔案複製到 Docker 映像檔中 - 使用 `.dockerignore` 排除敏感檔案 - 位於 HTTPS 後方時，請設定 `AUTH_COOKIE_SECURE=true` ```bash docker run -d \ --name omniroute \ --restart unless-stopped \ --read-only \ -p 20128:20128 \ -v omniroute-data:/app/data \ -e JWT_SECRET="$(openssl rand -base64 48)" \ -e API_KEY_SECRET="$(openssl rand -hex 32)" \ -e STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \ diegosouzapw/omniroute:latest ``` --- ## 相依套件 - 定期執行 `npm audit`（`npm run audit:deps` 涵蓋主程式與 electron） - 保持相依套件為最新版本 - 專案使用 `husky` + `lint-staged` 執行提交前檢查（lint-staged + check-docs-sync + check:any-budget:t11） - CI 管線會在每次推送時執行 ESLint 安全性規則（`no-eval`、`no-implied-eval`、`no-new-func` = error） - 提供者常數會在模組載入時透過 Zod 驗證（`src/shared/validation/schemas.ts`） - 使用預設安全的函式庫：`dompurify` / `isomorphic-dompurify`（XSS）、`jose`（JWT）、`better-sqlite3`（透過參數化查詢避免 SQLi 風險）、`bcryptjs`（密碼雜湊） ## 強制安全性規則 以下規則由工具與審查人員強制執行： 1. **絕不提交密鑰** — `.env` 已由 gitignore 忽略；`.env.example` 是範本（不含常值，僅含註解 — 請參閱下方的 PUBLIC_CREDS.md） 2. **絕不使用 `eval()`、`new Function()` 或隱含 eval** — 由 ESLint 強制執行 3. **未經操作人員明確核准，絕不略過 Husky 掛鉤**（`--no-verify`、`--no-gpg-sign`） 4. **絕不在路由中撰寫原始 SQL** — 一律透過 `src/lib/db/`（參數化） 5. **一律使用 Zod 驗證輸入** — `src/shared/validation/schemas.ts` 6. **一律清理上游標頭** — 拒絕清單位於 `src/shared/constants/upstreamHeaders.ts` 7. **加密靜態儲存的憑證** — 透過 `src/lib/db/encryption.ts` 使用 AES-256-GCM 8. **透過 `resolvePublicCred()` 取得公開的上游 OAuth 識別碼** — 絕不在原始碼中嵌入 `AIza…` / `GOCSPX-…` / `…apps.googleusercontent.com` 常值。請參閱 [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md)。 9. **錯誤回應須透過 `buildErrorBody()` / `sanitizeErrorMessage()` 處理** — 絕不將原始 `err.stack` / `err.message` 放入 HTTP / SSE / executor / MCP 回應本文。請參閱 [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md)。 10. **透過 `env` 選項傳遞 `exec()` / `spawn()` 的執行階段值** — 絕不將外部路徑或不受信任的值以字串插值方式加入經由 shell 傳遞的指令碼。參考：`src/mitm/cert/install.ts::updateNssDatabases`。 11. **優先採用預設安全的函式庫** — 請參閱 [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)（Helmet.js、DOMPurify、ssrf-req-filter、safe-regex、Google Tink）。自行實作前，應優先選用這些函式庫。 ## 供應鏈掃描器發現（Socket.dev / Snyk / 類似工具） > **範圍說明：** 儲存庫根目錄中的 `socket.yml` 僅用於設定 `projectIgnorePaths`，供 Socket.dev 對已發布 npm 成品套件進行登錄端的發布後掃描；它並非強制執行的 CI/PR 合併閘門。`.github/workflows` 中沒有任何工作流程、`package.json` 中沒有任何指令碼，且 `Makefile` 中也沒有任何目標會叫用 Socket.dev。 已發布的 `omniroute` npm 成品套件包含 Next.js `output: "standalone"` 建置，這表示每個路由處理常式——包括已有文件說明的特權 功能（MITM、Zed 匯入、Cloud Sync、內嵌服務監督程式）——最終都會 進入 `.next/server/*.js` 的壓縮區塊。啟發式供應鏈掃描器 經常會將這些區塊與惡意軟體特徵碼進行模式比對。 我們使用的掃描器設定位於儲存庫根目錄的 [`socket.yml`](socket.yml) （Socket.dev GitHub App 格式 v2——請參閱 ）。它明確排除 不會隨套件發布的目錄（`tests/`、`_tasks/`、`_references/`、`_ideia/`、 `_mono_repo/`、`docs/` 等），使掃描器只回報實際會觸及已發布版本使用者的 程式碼路徑——掃描本身由 Socket GitHub App 讀取該檔案來驅動， 而不是由此儲存庫中的工作流程驅動。 針對每個發現類別，我們都會維護一份逐項發現的維護者證明： - **[`docs/security/SOCKET_DEV_FINDINGS.md`](docs/security/SOCKET_DEV_FINDINGS.md)** — 逐項發現對照表：原始碼檔案 ↔ 被標記的區塊 ↔ 行為 ↔ v3.8.6 中套用的緩解措施。 - 每個被標記函式中的原始碼內 `SECURITY-AUDITOR-NOTE:` 區塊， 皆會指回同一份文件。 若使用者的管線無法放寬此警示，請使用 `OMNIROUTE_BUILD_PROFILE=minimal npm run build` 進行建置。這會以 在執行階段回傳 HTTP 503 `feature-disabled` 的虛設常式取代四個 敏感模組，因此特權程式碼路徑實際上不會存在於套件中。 發布流程請參閱 [`docs/security/SOCKET_DEV_FINDINGS.md`](docs/security/SOCKET_DEV_FINDINGS.md)。 ## 參考資料 - [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md) — 授權管線 - [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md) — 防護機制框架 - [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md) — 稽核記錄與保留 - [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md) — 公開上游認證資訊的**強制**模式 - [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md) — 錯誤回應的**強制**模式 - [`docs/security/SOCKET_DEV_FINDINGS.md`](docs/security/SOCKET_DEV_FINDINGS.md) — 供應鏈掃描器發現的維護者證明 - [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md) — 斷路器 + 冷卻 + 鎖定 - [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md) — TLS 指紋辨識（法律／倫理聲明） - [`CLAUDE.md`](CLAUDE.md) — AI 代理程式的硬性規則 - [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults) — 精選的預設安全函式庫