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