前言¶
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 进程内的插件，仅负责拦截模型请求。它不是机器级的网络防火墙，也无法阻止恶意插件通过非正常路径窃取数据。
- 图结构冻结：插件在扫描前会冻结请求图，防止在异步解析期间被直接调用者修改，但运行时全局变量的修改不受影响。
