前言¶
DeepSeek Harness (DSH) 的插件機制允許開發者擴展系統行爲。在實際開發中，下游模型適配器通常運行在信任邊界內，直接處理完整的用戶請求圖。如果請求中包含 API 密鑰、數據庫連接字符串等敏感信息，這些數據會直接暴露給模型進行推理。
dsh-egress-guard 插件位於 llm/stream 邊界，在請求被傳遞給下游適配器之前進行檢查。它通過凍結請求圖、掃描文本內容，在本地阻止包含已知密鑰模式的請求。整個過程不聯網、不重寫請求值、不將內容發送給外部服務。
插件定位¶
該插件由 LKRCharon 維護，是一個基於 MIT 許可證的 DSH 安全插件。它專注於“本地、零網絡、確定性的密鑰預檢”。插件在接收到模型請求時，首先驗證並凍結請求圖，若發現疑似憑證則停止調用下游模型適配器，並返回固定的脫敏錯誤。匹配結果不會出現在錯誤信息、報告或插件日誌中。
核心功能¶
插件的核心能力集中在以下幾個方面：
- 請求掃描範圍：掃描系統提示、工具模式、JSON 參數、消息內容以及工具描述等字段。
- 密鑰檢測：內置規則支持檢測多種憑證格式，包括 PEM 私鑰、GitHub/AWS/Google 等平臺的 API 密鑰、Bearer 認證、數據庫連接 URL 以及常見的
password=、api_key=等賦值語句。 - 默認策略（Fail-Closed）：默認情況下，插件會阻斷包含已知密鑰模式、圖片（不支持 OCR 掃描）以及未知內容的請求。
- 審計模式：支持切換爲審計模式，僅記錄發現的信息（規則 ID、結構位置等）而不阻斷請求。
- 圖結構處理：能夠處理循環、稀疏或無法凍結的請求圖，並會因結構異常而阻斷請求。
安裝與啓用¶
安裝前請確保環境滿足依賴要求：Node.js 版本爲 22.19.x 或 24，DeepSeek Harness 版本爲 0.1.0-rc.6 或兼容版本。
執行以下命令安裝插件：
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add dsh-egress-guard
安裝成功後，dsh 命令的輸出中應包含 egress-guard 配置行。注意 DSH rc.6 的配置文件模式禁用了自動 peer 安裝，因此命令可能會提示缺少 @deepseek-ai/cordis 等依賴，但這不影響運行，因爲宿主環境會提供這些依賴。
配置與使用¶
配置通過修改 cordis.patch.yml 文件實現，後續的補丁層可以覆蓋同名 ID 的配置。
基礎配置¶
在配置文件中添加以下內容：
- id: egress-guard
name: dsh-egress-guard
config:
mode: block
scanToolSchemas: true
blockUnscannable: true
maxScanBytes: 4194304
maxFindings: 64
skipProviders: []
skipPurposes: []
customRules: []
配置項說明¶
mode：設置爲block時阻斷請求；設置爲audit時僅記錄日誌。scanToolSchemas：是否掃描發送給模型工具的描述和 JSON Schema。blockUnscannable：默認爲true，用於阻斷圖片、格式錯誤的字段或無法安全掃描的未知內容類型。maxScanBytes：限制掃描的最大文本字節數（默認 4MB，範圍 1 KiB - 16 MiB），超過則阻斷。maxFindings：最大保留的發現記錄數。skipProviders/skipPurposes：通過配置特定路由或對話用途來繞過檢查。
自定義規則¶
插件支持添加自定義規則以匹配特定的密鑰前綴。自定義規則不使用正則表達式，而是採用確定性的前綴 + 字母表 + 長度匹配。
customRules:
- id: acme-production-key
prefix: 'ACME-PROD-'
alphabet: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
length: 24
規則定義了前綴、限定字符集以及固定長度。插件會查找前綴，隨後從限定字符集中選取指定長度的字符作爲後綴。
注意事項¶
- 日誌殘留：插件阻止了模型請求的外發，但文本可能已經寫入本地 DSH 會話日誌中，不會自動清理。
- 二進制內容：插件不支持對圖片進行 OCR 掃描，默認會直接阻斷二進制內容。
- 邊界限制：它是一個運行在 DSH 進程內的插件，僅負責攔截模型請求。它不是機器級的網絡防火牆，也無法阻止惡意插件通過非正常路徑竊取數據。
- 圖結構凍結：插件在掃描前會凍結請求圖，防止在異步解析期間被直接調用者修改，但運行時全局變量的修改不受影響。
