运行时出站安全网关 tancheng33/dsh-egress-guard

dsh-egress-guard

npm
license

给 DeepSeek Harness 工具调用加的运行时安全网关。

生态里已有的安全插件都是在 agent 跑起来之前静态扫描配置文件。这个插件挂在工具执行管线上，作用于调用本身：

| 规则 | 扩展点 | 作用 |
| 出站白名单 | tools/pre-execute | 调用里出现白名单之外的网络目的地时拒绝（或转审批）——curl 到某个 paste 站、git push 到陌生远端、fetch 到外传端点。 |
| 密钥脱敏 | tools/post-execute | 在模型、持久化会话日志、Code Mode 程序读到之前，把工具结果里的凭据改写掉。 |
| 审计日志 | 两条瀑布 | 每个决策都追加成一行 JSONL，包括 monitor 模式下"本来会拦"的那些。 |

不 fork、不改 loop：三个监听器挂在文档化的扩展点上，卸载时干净释放。

安装

dsh plugin --profile add dsh-egress-guard

bundle 默认是 mode: monitor，所以装上它不会弄坏你现有的配置：所有规则照常评估、照常写审计日志，但不拦截、不改写。先看一天日志，再去 profile 的 cordis.patch.yml 里打开强制：

- id: egress-guard
config:
mode: enforce
egress:
enabled: true
allowHosts: ['.github.com', '.npmjs.org', 'api.deepseek.com']
denyHosts: []
allowLoopback: true
onViolation: deny
redact:
enabled: true
builtins: true
extraPatterns: []
placeholder: '[redacted:{name}]'
audit:
enabled: true
path: ''
logAllowed: false

注意 patch 替换的是整个 config，不是深合并——你想保留的键都要重写一遍。

配置项

| 键 | 默认值 | 含义 |
| mode | monitor | off 什么都不注册；monitor 只评估只记录；enforce 真拦真改。 |
| egress.allowHosts | schema 里为 []，bundle 里给了一份起步清单 | 放行的主机。.example.com 同时覆盖主域名和所有子域名。留空表示只用黑名单。 |
| egress.denyHosts | [] | 始终拒绝，优先级高于 allowHosts 和 allowLoopback。 |
| egress.allowLoopback | true | 放行 localhost、127.0.0.0/8、::1、.localhost。 |
| egress.onViolation | deny | 设成 ask 则交给 ctx.approval 审批——没挂审批服务时会降级为拒绝。 |
| redact.builtins | true | 内置：私钥、各家 API key、JWT、bearer 头、KEY=value 赋值。 |
| redact.extraPatterns | [] | 额外的正则（按 global 标志编译）。 |
| redact.placeholder | [redacted:{name}] | {name} 会替换成命中的规则名。 |
| audit.path | $DSH_HOME/egress-guard.jsonl | JSONL，一行一个决策。 |
| audit.logAllowed | false | 连"命中了主机但放行"的调用也记——这是用真实流量反推白名单的办法。 |

用真实流量反推白名单

1. 先用 monitor 模式装上，把 logAllowed 开成 true，正常干活一段时间
2. 看你的 agent 到底访问了哪些主机： jq -r '.hosts[]?' ~/.dsh/egress-guard.jsonl | sort | uniq -c | sort -rn
3. 把合理的填进 allowHosts，再把 mode 切成 enforce

设计取舍

脱敏改的是 canonical value，不是渲染出来的 content。 注册表的契约里写得很明确：content 替换不是保密边界——Code Mode 的程序直接拿到的是 value。所以成功结果走 value 替换，content 由脱敏后的 value 重新渲染；失败结果没有 value（注册表禁止对失败结果替换 value），只能按 content 脱敏。

这个插件在 post-execute 瀑布里最后动手。 它先 next() 把下游跑完，再对最终决策实际携带的那份投影做脱敏，这样瀑布更深处的监听器没法把原文再塞回来。如果别的插件替换了 content 而底层 value 里还有密钥，本插件会替换 value——代价是丢掉那个插件的展示效果，但不会泄漏给程序化消费者。这个优先级是有意为之的。

拒绝时会明确告诉模型别绕路。 只回一句"denied"会诱导模型换个工具重试；这里的 reason 会点名主机，并要求它去问用户。

局限 —— 信任它之前请先读这段

这是护栏，不是隔离边界。它提高的是"手滑"和"轻度 prompt 注入"的成本，挡不住一个已经能在你机器上执行代码的对手。

- 检测是文本层面的：从参数字符串里扫 URL 和 user@host 远端。运行期才拼出目的地的命令（curl "$ENDPOINT"、base64、字符串拼接、十进制形式的 IP）对这个网关完全隐形。真正的隔离是沙箱接缝该干的事（dsh-bash-sandbox、网络命名空间、代理），不是字符串匹配。
- 工具自己开 socket 就完全绕过，除非目的地出现在它的参数里。
- 脱敏基于模式匹配：不认识的凭据形状会漏，看起来像密钥的正常文本会被误改。自己的格式请加 extraPatterns；开强制之前先看审计日志里的误报。
- 不扫二进制内容：图片等非文本块原样透传。
- 审计日志在本地且未签名：任何能写你文件系统的东西都能改它。

兼容性

针对 @deepseek-ai/dsh-tools 0.1.5 / 0.1.6 的管线契约开发；逐版本声明写在 package.json 的 dsh.compatibility.dshReleases 里。

2026-09-22 验证，每条发布线都把整个 @deepseek-ai/dsh- 家族钉到同一版本：

| DSH 版本 | 类型检查 | 构建 | 测试 |
| 0.1.5-rc.2（npm latest） | 通过 | 通过 | 61/61 |
| 0.1.6-alpha.1 | 通过 | 通过 | 61/61 |
| 0.1.6-alpha.2（npm alpha） | 通过 | 通过 | 61/61 |

在 0.1.5-rc.2 上还用打包 tarball 做了一次性 Profile 验证（DSH_HOME 指向临时目录，--from-default-profile headless）：bundle 作为 egress-guard 行合入 profile 树，profile 带着它启动、只停在供应商凭据门槛上，dsh plugin remove 把依赖和这一行都干净移除。

0.2.0 不再支持 0.1.0-rc 线：上游把 CallId 改名为 ToolCallId，并把 JsonValue 从 dsh-session 挪走，对 0.1.0-rc.6 构建会直接失败。还留在那条线上的话请继续用本插件的 0.1.0。

另外提醒：npm 上 @deepseek-ai/ 的 latest 标签现在指向 0.1.5-rc.2，0.1.6 预发布在 alpha 标签上。手动安装 harness 相关包时请显式指定版本。

Harness 处于开发者预览期，官方明确说会有破坏性变更。契约一旦变动，本插件的测试会直接炸——因为它们是通过真实注册表执行真实调用，而不是 mock 瀑布。

开发

npm install
npm test # 61 个测试：纯单元测试 + 通过真实 ToolRuntime 的端到端测试
npm run typecheck
npm run build

dsh.compatibility.dshReleases 里的每个版本 CI 都会跑。本地复现某一个版本时，把整个 harness 家族钉到该版本再跑套件（package.json 和 lockfile 跑完会还原）：

node scripts/pin-dsh.mjs 0.1.6-alpha.2
npm run typecheck && npm test && npm run build

不发包也能在真实 harness 上试：

dsh plugin --profile add /path/to/dsh-egress-guard
dsh --profile --dump-config # 能看到 "# == dsh-egress-guard" 这一层

许可证

MIT