DeepSeek Harness 插件：dsh-ssrf-guard

在 DeepSeek Harness (DSH) 環境中，智能體經常需要向外部發起請求。如果不對這些 URL 進行管控，存在服務器端請求僞造（SSRF）的風險。dsh-ssrf-guard 是一個 DSH 函數插件，它通過在請求打開前檢查出站 URL 的主機和方案白名單，實現“拒絕一切”（fail-closed）的安全策略。

插件定位¶

該插件由 jwilson411 維護，基於 MIT 許可證。它不攔截流量，不進行 DNS 解析，也不作爲反向代理或 Web 應用防火牆（WAF）。它僅通過 URL 解析和字符串匹配來決定是否允許訪問。默認配置允許空，即如果不配置任何允許列表，所有請求都會被拒絕。

安裝與啓用¶

在 DSH 的 web profile 中安裝該插件：

dsh plugin --profile web add github:jwilson411/dsh-ssrf-guard

該包的 manifest 聲明瞭 dsh.bundle.patch，安裝後會被追加到 profile manifest 的 dsh.profile.bundles 列表中，並使其 cordis.patch.yml 成爲一層配置。

核心功能¶

白名單機制：僅允許在 allowHosts 中明確指定的主機（支持精確匹配和前綴匹配）和 allowSchemes 中指定的方案。
前置檢查：在請求打開之前進行檢查，未通過檢查的 URL 不會離開當前進程。
API 暴露：
- 提供 ssrf_check 工具，供模型或代碼調用。
- 導出 assertUrlAllowed 和 SsrfDeniedError 庫 API，供開發者在代碼中主動校驗。
默認攔截：內置了對迴環地址（localhost, 127.0.0.1, ::1）、鏈路本地地址（169.254.x.x, fe80::）、包含憑證的 URL 等情況的攔截。

配置與使用¶

1. 配置白名單¶

在 cordis.patch.yml 中配置允許的主機和方案。注意，id-targeted patch 會替換整行配置，因此需要重新聲明所有保留字段。

- id: ssrf-guard
  config:
    allowHosts:
      - .example.com    # 允許所有 *.example.com 子域
      - api.vendor.test # 精確匹配 api.vendor.test
    allowSchemes: [https]

如果未在配置中指定，環境變量 DSH_SSRF_ALLOW_HOSTS 和 DSH_SSRF_ALLOW_SCHEMES 可作爲後備，且僅當配置行完全省略該鍵時纔會生效。

2. 代碼中校驗 URL¶

使用 assertUrlAllowed 函數進行校驗。如果 URL 不被允許，會拋出 SsrfDeniedError。

import { assertUrlAllowed, SsrfDeniedError } from 'dsh-ssrf-guard'

const config = { allowHosts: ['.example.com'], allowSchemes: ['https'] }

try {
  const { host, scheme } = assertUrlAllowed(candidate, config)
  // 校驗通過後，再執行 fetch 等操作
  await fetch(candidate)
} catch (error) {
  if (error instanceof SsrfDeniedError) {
    // 處理拒絕邏輯
    return
  }
  throw error
}

如果不希望使用異常機制，可以使用非拋出的 checkUrl 函數，返回結果對象。

3. 調用工具¶

在 DSH 的工具調用場景中，可以直接調用 ssrf_check 工具，傳入 url 參數。

使用注意事項¶

DNS 重綁定防護：該插件不進行 DNS 解析，僅匹配 URL 中寫入的主機名。如果 DNS 解析結果指向了內網地址，只要主機名在白名單中，該插件不會阻止。
端口不匹配：端口不包含在匹配邏輯中。例如，配置 example.com 允許 https://example.com:8443/。
大小寫不敏感：主機名匹配不區分大小寫。
版本要求：需要 Node.js 版本 >= 22.14.0。插件基於 @deepseek-ai/dsh-tools@0.1.1-rc.2 編寫和測試，建議顯式指定版本而非依賴 latest。
運行環境：插件以當前 DSH 進程的權限運行，安裝前請檢查源碼與許可證。

總結¶

dsh-ssrf-guard 提供了一種在 DSH 插件層級的、輕量級的 SSRF 防護手段。它不接管網絡流量，而是通過顯式的庫 API 或工具調用，強制開發者在發起請求前進行白名單校驗，適合需要精細控制出站 URL 的場景。

插件目錄：SkillHub
源碼地址：GitHub