# 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 安全性公告](https://github.com/diegosouzapw/OmniRoute/security/advisories/new) 3. 內容需包含：說明、重現步驟及潛在影響 ## 回應時程 | 階段 | 目標 | | ------------ | ----------------------- | | 確認收件 | 48 小時 | | 分類與評估 | 5 個工作日 | | 修補程式發布 | 14 個工作日（重大漏洞） | ## 支援版本 | 版本 | 支援狀態 | | ------- | ------------- | | 3.8.x | ✅ 積極維護中 | | 3.7.x | ✅ 安全性更新 | | < 3.7.0 | ❌ 不再支援 | --- ## 安全架構 OmniRoute 採用多層式安全模型： ``` 請求 → CORS → 授權管道（分類 → 政策 → 強制執行） → 防護欄（PII 遮罩、提示注入、視覺橋接） → 速率限制器 → 斷路器 → 冷卻 → 模型鎖定 → 提供者 ``` ### 🔐 身分驗證與授權 | 功能 | 實作方式 | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **儀表板登入** | 基於密碼的身分驗證，搭配 JWT Token（HttpOnly Cookie） | | **API 金鑰驗證** | HMAC 簽署金鑰搭配 CRC 驗證 | | **OAuth 2.0 + PKCE** | 提供者專用的瀏覽器/裝置 OAuth 在支援時使用 PKCE；僅匯入的 Devin 憑證會單獨處理。 | | **Token 更新** | 自動在 OAuth Token 到期前進行更新 | | **安全 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 範圍** | 約 13 個細粒度範圍（read:health、write:combos、execute:completions 等）— 請參閱 `docs/frameworks/MCP-SERVER.md` | ### 🛡️ 靜態資料加密 所有儲存於 SQLite 的敏感資料皆使用 **AES-256-GCM** 搭配 scrypt 金鑰推導進行加密： - API 金鑰、存取 Token、更新 Token 及身分 Token - 版本化格式：`enc:v1:::` - 若未設定 `STORAGE_ENCRYPTION_KEY`，則以純文字模式（passthrough）運作 ```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())` 註冊。此模型為故障開放（fail-open）設計（異常不會阻斷流量）。可透過 `x-omniroute-disabled-guardrails` 標頭在單次請求中選擇停用。→ 詳見 [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md)。 ### 🧠 提示注入防護 偵測並阻擋 LLM 請求中的提示注入攻擊的中介軟體： | 模式類型 | 嚴重性 | 範例 | | ------------ | ------ | ---------------------------------- | | 系統指令覆寫 | 高 | 「忽略所有先前的指令」 | | 角色劫持 | 高 | 「你現在是 DAN，你可以做任何事」 | | 分隔符號注入 | 中 | 編碼後的分隔符，用以破壞上下文邊界 | | DAN／越獄 | 高 | 已知的越獄提示模式 | | 指令洩漏 | 中 | 「顯示你的系統提示詞」 | 可透過儀表板（設定 → 安全性）或 `.env` 進行設定： ```env INPUT_SANITIZER_ENABLED=true INPUT_SANITIZER_MODE=block # warn | block | redact ``` ### 🔒 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 ``` ### 🌐 網路安全 | 功能 | 說明 | | -------------- | ---------------------------------------------------------------- | | **CORS** | 明確的跨域白名單（`CORS_ALLOWED_ORIGINS`；舊版為 `CORS_ORIGIN`） | | **IP 過濾** | 在儀表板中設定允許／封鎖的 IP 範圍 | | **速率限制** | 依提供者設定的速率限制，搭配自動退避機制 | | **防驚群效應** | 互斥鎖＋連線層級鎖定，防止連鎖 502 錯誤 | | **TLS 指紋** | 模擬瀏覽器風格的 TLS 指紋，降低機器人偵測率 | | **CLI 指紋** | 依提供者調整標頭／主體順序，以符合原生 CLI 簽章 | ### 🔌 韌性與可用性 | 功能 | 說明 | | ------------------ | ------------------------------------------------------------- | | **斷路器** | 三種狀態（關閉 → 開啟 → 半開），依提供者設定，持久化至 SQLite | | **請求冪等性** | 5 秒內重複請求去重視窗 | | **指數退避** | 自動重試，延遲時間逐步增加 | | **健康狀態儀表板** | 即時提供者健康狀態監控 | ### 📋 法規遵循 | 功能 | 說明 | | ------------------ | ------------------------------------------------- | | **日誌保留** | 依 `CALL_LOG_RETENTION_DAYS` 設定自動清理 | | **不紀錄選擇退出** | 可為每個 API 金鑰設定 `noLog` 標記以停用請求記錄 | | **稽核日誌** | 管理操作記錄在 `audit_log` 資料表中 | | **MCP 稽核** | 以 SQLite 為基礎的稽核記錄，涵蓋所有 MCP 工具呼叫 | | **Zod 驗證** | 所有 API 輸入皆在模組載入時以 Zod v4 綱要進行驗證 | --- ## 必要的環境變數 所有機密資訊必須在啟動伺服器前設定完成。若缺少或強度不足，伺服器將**快速失敗（fail fast）**。 ```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. **`exec()` / `spawn()` 的執行期值應透過 `env` 選項傳遞** — 切勿將外部路徑或不可信賴的值以字串插值方式嵌入 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 Agent 的嚴格規則 - [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults) — 精選預設安全程式庫清單