Socket.dev / supply-chain finding attestation (中文 (繁體))

§1 — MITM 根 CA 安裝（77484.js）

原始碼檔案：

• src/mitm/cert/install.ts — 公開的 installCert() / uninstallCert()， 以及各平台的 installCertWindows/Mac/Linux。
• src/mitm/systemCommands.ts — 安裝路徑所使用的共用 execFile / spawn / PowerShell 輔助函式。

觸發方式：使用者在本機儀表板的 /dashboard/cli-tools/mitm 中點擊「啟用 MITM Proxy」。該路由僅限回環介面存取——請參閱 CLAUDE.md 中的強制規則 #17，以及 src/server/authz/routeGuard.ts::isLocalOnlyPath()。透過通道洩漏的 JWT 無法觸發此程式碼路徑。

執行的高權限操作（依平台）：

作業系統	命令
Windows	透過 UAC 執行 certutil -addstore Root <cert>
macOS	sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain <cert>
Linux	sudo cp <cert> <distro-trust-dir> + sudo update-ca-certificates（Debian）/ sudo update-ca-trust（RHEL/SUSE）
Linux+Firefox/Chromium	透過 certutil -d sql:<profile> 更新各設定檔的 NSS DB

這些命令與 mitmproxy、Charles Proxy、Fiddler 及 Caddy 所使用的命令相同。OmniRoute 中存在這些命令的原因，已記載於 docs/security/STEALTH_GUIDE.md。

v3.8.6 緩解措施：

• runElevatedPowerShell() 不再使用 -EncodedCommand <base64utf16le>。 提權後執行的承載內容會寫入每次呼叫專用的暫存 .ps1 檔案（模式為 0o600， 位於私有的 mkdtempSync 目錄中），並透過 -File 加以參照。 該檔案會在 finally 中解除連結。此作法移除了 Socket.dev 的 AI 分類器所標記之典型「透過 PowerShell 使用 base64 提權」特徵。
• installCertWindows 包含一段行內 SECURITY-AUDITOR-NOTE: 區塊，指向本文件。

保留原因：MITM Proxy 是一項已記載於 docs/security/STEALTH_GUIDE.md 與 docs/frameworks/MITM-PROXY.md 的功能。移除它 會破壞 agent-bridge 功能集。

---

§2 — Zed 憑證匯入（app/api/providers/zed/import/route.js）

原始檔案：

• src/app/api/providers/zed/discover/route.ts （v3.8.6 新增）
• src/app/api/providers/zed/import/route.ts
• src/lib/zed-oauth/keychain-reader.ts
• src/lib/zed-oauth/credentialFingerprint.ts （v3.8.6 新增）

觸發方式：使用者在本機儀表板的提供者頁面中點擊「從 Zed 匯入」。 此端點受 requireManagementAuth 保護。Zed 編輯器本身會依照文件所載的服務名稱， 將其提供者 API 金鑰寫入作業系統鑰匙圈中——請參閱 https://zed.dev/docs/ai/llm-providers。

v3.8.5 的行為（Socket.dev 所標記的版本）：

POST /import 會探索憑證，並在單次往返中自動將其儲存至本機 SQLite 儲存區。沒有逐帳戶確認、沒有指紋，只有「找到 N 個權杖，已全部匯入。」

v3.8.6 緩解措施——兩步驟確認：

1. POST /api/providers/zed/discover 會傳回 { candidates: [{ provider, service, account, fingerprint }] }。原始 權杖永遠不會被傳輸。指紋為 sha256(service|account|token).slice(0,16)。
2. 儀表板會呈現候選項目清單，操作人員選取要匯入的項目，並將 { confirmedAccounts: [{ service, account, fingerprint }] } 傳送至 POST /api/providers/zed/import。
3. 匯入端點會在伺服器上重新讀取鑰匙圈，並依 (service, account, fingerprint) 進行篩選。遭竄改或重播的探索 回應無法誘使匯入端點儲存不相關的權杖—— 如果即時權杖自探索後已變更，指紋便不再相符，而該憑證會被略過。

OMNIROUTE_ZED_IMPORT_LEGACY_ONE_STEP=true 環境變數旗標會為尚未更新其自動化流程的 操作人員保留 v3.8.5 的行為。此旗標將於 v3.9 移除。

保留原因：對於已使用 Zed，並希望將提供者金鑰鏡像至 OmniRoute、 而不必重新貼上的使用者而言，Zed 匯入是最便利的入門途徑。

---

§3 — execFile / spawn / 提升權限的 PowerShell（21843.js）

原始檔案：src/mitm/systemCommands.ts。

被標記的原因：此區塊會重新匯出 execFileWithPassword、 runElevatedPowerShell 與共用的 quotePowerShell 輔助函式。Socket.dev 的 AI 分類器將它們視為通用的「主機執行 + 權限提升工具組」。在 OmniRoute 中， 它們僅由 MITM 憑證安裝路徑（§1）使用，以及由 execFileWithPassword 用於執行 sudo 命令。

v3.8.6 緩解措施：

• 重構 runElevatedPowerShell（請參閱 §1）。
• 在 runElevatedPowerShell 與 execFileWithPassword 兩處加入行內 SECURITY-AUDITOR-NOTE: 區塊，記錄允許清單中的呼叫端與固定的 可執行檔清單。
• execFileWithPassword 的 spawn() 呼叫帶有 nosemgrep 標記， 其中列出允許傳入此輔助函式的可執行檔清單—— 使用者輸入沒有任何路徑可到達 finalCommand/finalArgs。

---

§4 / §6 — 9router 服務監督器（api/services/9router/{start,restart}/route.js）

原始檔案：

• src/app/api/services/9router/_lib.ts — 監督器工廠。
• src/app/api/services/9router/{start,stop,restart,status,install,update,auto-start}/route.ts。
• src/lib/services/ServiceSupervisor.ts — 通用的程序產生／健康狀態輪詢／日誌緩衝。

觸發方式：使用者在本機儀表板的嵌入式服務頁面中點擊「安裝」／「啟動」。

既有的保護措施：

• 根據 src/server/authz/routeGuard.ts（硬性規則 #17），所有 /api/services/* 路由均為 LOCAL_ONLY。迴路位址限制會在任何驗證檢查前執行—— 即使 JWT 外洩，也無法存取這些路由。
• 9router 的資料庫資料列會以 status='not_installed', auto_start=0 作為種子資料 （請參閱 src/lib/db/migrations/071_services.sql:19）。服務不會 在首次啟動時開始執行。
• spawn() 使用由 src/lib/services/installers/ninerouter.ts 中的 resolveSpawnArgs(apiKey, PORT) 傳回的二進位檔路徑呼叫； 該函式使用固定的受支援二進位檔允許清單。
• Stdout/stderr 會緩衝於記憶體中（上限為 5 MB，請參閱 _lib.ts）—— 除非使用者從儀表板啟用記錄，否則不會寫入磁碟。

v3.8.6 緩解措施：無功能變更。最小化建置設定檔 （OMNIROUTE_BUILD_PROFILE=minimal）會將 src/lib/services/installers/ninerouter.ts 替換為 stub， 供希望從套件組合中實際移除權限路徑的使用者使用。

保留原因：9router 是可選擇在本機安裝的配套服務 （可將其視為 WordPress 風格的外掛程式）——必須嚴格明確選擇啟用。

---

§5 — OmniRoute Cloud Sync 憑證回寫（api/keys/[id]/route.js）

原始檔案：

• src/lib/cloudSync.ts — syncToCloud() / updateLocalTokens()。
• src/app/api/keys/[id]/route.ts — 呼叫 syncKeysToCloudIfEnabled()。

觸發條件：isCloudEnabled() 傳回 true（從儀表板設定），且 已設定 CLOUD_URL。若兩者皆停用，則不會對 Cloud 端點發出任何對外網路呼叫。

v3.8.5 的行為（Socket.dev 正確發現的錯誤）：

當 cloudUpdatedAt > localUpdatedAt 時，updateLocalTokens() 會使用 Cloud 回應中的資料覆寫 accessToken、refreshToken 和 providerSpecificData。沒有 HMAC、沒有簽章，也沒有總和檢查碼。 設定錯誤或具惡意的 CLOUD_URL（或通道上的中間人攻擊者）可能會在不被察覺的情況下置換提供者的 OAuth 權杖。

v3.8.6 的緩解措施：

1. HMAC 驗證：verifyCloudSignature(rawBody, sigHeader) 會在剖析 JSON 前檢查 X-Cloud-Sig 標頭（HMAC-SHA256(OMNIROUTE_CLOUD_SYNC_SECRET, rawBody)）。若已設定密鑰，則必須提供簽章。若未設定（舊版相容模式），系統會記錄警告並接受回應——自 v3.9 起將強制要求設定密鑰。
2. 敏感欄位明確選擇加入：僅當 OMNIROUTE_CLOUD_SYNC_SECRETS=true 時，才會覆寫 accessToken / refreshToken / providerSpecificData。預設模式僅同步非憑證中繼資料（expiresAt、status、lastError*、 rateLimitedUntil、updatedAt）。對於依賴遠端權杖同步的使用者而言，這是一項破壞性變更——他們必須明確選擇加入。

保留此功能的原因：Cloud Sync 是 OmniRoute Cloud 租戶集中管理團隊憑證的唯一方式。此修正使威脅模型清楚反映實際情況： 「伺服器簽署、用戶端驗證、操作人員選擇加入。」

---

建置設定檔：minimal

需要 Socket 相容成品的使用者，請使用以下方式建置：

OMNIROUTE_BUILD_PROFILE=minimal npm run build

webpack NormalModuleReplacementPlugin 會將四個模組別名指向虛設實作：

模組	虛設實作
src/mitm/cert/install.ts	src/mitm/cert/install.stub.ts
src/lib/zed-oauth/keychain-reader.ts	src/lib/zed-oauth/keychain-reader.stub.ts
src/lib/cloudSync.ts	src/lib/cloudSync.stub.ts
src/lib/services/installers/ninerouter.ts	src/lib/services/installers/ninerouter.stub.ts

每個虛設實作都會匯出相同的介面，但所有函式都會在執行階段擲回 featureDisabledError(name)。依賴已停用模組的路由會傳回 HTTP 503，並附上清楚的訊息，而不會啟用敏感程式碼路徑。

產生的套件組合預定以 omniroute-secure 發布。發布流程請參閱 docs/ops/PUBLISHING_SECURE.md。

---

外掛程式拆分（v4 追蹤項目）

長期而言，我們打算將 npm 套件拆分為可分別稽核的模組。請參閱 GitHub 議題追蹤器中的 v4 里程碑，以查看相關追蹤議題。

---

OmniRoute 原始碼 (a58000c7685f)