Web 安全守卫 exp9187/dsh-guard

dsh-guard 🔒

DeepSeek Harness（dsh）Web 面安全守卫插件：为无 GUI 的公网 Linux 部署加"安全锁"。
密码登录、API Token、IP 白名单、防爆破锁定、暴露绑定 fail-loud 保护，一行命令挂载。

为什么需要它

dsh web 的 Web 界面（默认 http://127.0.0.1:3080）本质上是一个远程代码执行面：
agent 的 bash/pwsh 工具可以直接执行服务器命令，还能读写全部会话数据、模型凭证和插件配置。
官方 web profile 只做了 DNS-rebinding 防线（Host 头校验），没有任何身份认证。

两种典型的裸奔路径：

1. 有人把 webserver 行改成绑定 0.0.0.0（CLI 的 --host 0.0.0.0 被官方禁了，但 patch 层可以改）；
2. 更常见的是公网 Caddy/Nginx 反代 → 127.0.0.1:3080，等于把 RCE 面直接暴露到互联网。

dsh-guard 在所有路由逻辑之前强制认证，覆盖：

- 全部 HTTP 路由（/api/ 网关、/plugins/、HMR）
- WebSocket 升级握手（/api/events.mux、/api/events.host）
- SPA 静态资源兜底

预览

工业级访问控制台风格的登录页：3D 透视面板 + 指针视差、透视线框网格、雷达扫描、扫描线/噪点、实时 UTC 时钟与安全读条、手绘 SVG 图标、密码明文切换：

dsh-guard login page

能力总览

| 功能 | 说明 |
| 🔑 密码登录 | 登录页 + HMAC 签名会话 Cookie（scrypt 哈希，Node 内置 crypto，零第三方依赖） |
| 🪙 API Token | Authorization: Bearer 或 ?token=，支持 sha256: 哈希形式存储 |
| 🌐 IP 白名单 | IPv4/IPv6 CIDR 列表；本机回环默认免认证（适合 SSH 端口转发场景） |
| 🔒 安全锁 | 绑定非回环地址且没有任何认证配置 → 拒绝启动（exit 1），杜绝裸奔 |
| 🛡️ 防爆破 | 登录失败按 IP 计数，达到阈值锁定（默认 10 次锁 15 分钟）；常量时间比较 |
| 🧾 审计 | 登录成败、认证失败（按 IP 限频）打日志；guard/login、guard/auth-failure Cordis 事件 |
| 🏗️ 加固 | X-Frame-Options/nosniff/Referrer-Policy 等安全头；反代 X-Forwarded-For 支持；SameSite=HttpOnly Cookie |

安装

方式 A：npm bundle（推荐，多机部署）

dsh plugin --profile web add dsh-guard
包自带 dsh.bundle 声明，自动挂载为 profile 的最后一个补丁层
dsh web # 直接启动即可

内网/离线服务器（无法访问 npm registry 时）：

在联网机器上打包，再把 tarball scp 到服务器
npm pack dsh-guard # 得到 dsh-guard-1.0.0.tgz
scp dsh-guard-1.0.0.tgz server:/tmp/
服务器上（tarball 会作为真实目录安装，依赖经 profile 平铺 node_modules 解析）
dsh plugin --profile web add /tmp/dsh-guard-1.0.0.tgz

注意：dsh plugin add 走 link: 软链安装，Node 会从源码真实路径解析依赖（与官方插件的约定一致）——从本地源码 checkout 安装时需先在该目录 pnpm install；生产部署请用 registry 或 tarball 方式。

方式 B：免 npm 单文件（单机快速上锁）

1. 拷贝守卫实现到 profile 目录
cp standalone/guard.js ~/.dsh/profiles/web/guard.js

2. 把 standalone/install.patch.yml 的内容合并进 ~/.dsh/profiles/web/cordis.patch.yml （即：禁用 webserver 行 + 插入 guard-webserver 行）

3. 用环境变量配置凭据（见下），然后正常启动
dsh web

配置

凭据首选进程环境变量（注意：harness 明确禁止 .env 文件设置 DSH_* 前缀变量，必须从 systemd Environment= / shell export 传入）：

| 环境变量 | 说明 |
| DSH_GUARD_MODE | auto（默认，启用保护+安全锁）/ off（完全关闭，明确接受风险） |
| DSH_GUARD_HOST / DSH_GUARD_PORT | 覆盖绑定地址/端口（无 GUI 部署直接改环境即可） |
| DSH_GUARD_PASSWORD | 明文密码，启动时用 scrypt 现算哈希（图省事用这个） |
| DSH_GUARD_PASSWORD_HASH | 预计算哈希（推荐，避免明文留在环境里） |
| DSH_GUARD_TOKENS | 逗号分隔 API Token（可混用 sha256: 哈希形式） |
| DSH_GUARD_ALLOWLIST | 逗号分隔 CIDR，如 10.0.0.0/8,192.168.1.0/24 |
| DSH_GUARD_SESSION_SECRET | 会话 HMAC 密钥（默认每次启动随机 → 重启后需重新登录） |

生成密码哈希：

npm 安装后
npx dsh-guard-hash '你的密码'
或免 npm
node standalone/hash-password.js '你的密码'
输出形如: scrypt$16384$8$1$$，填入 DSH_GUARD_PASSWORD_HASH

Token 哈希（可选加固，配置里存哈希而非明文）：

printf 'my-secret-token' | sha256sum # 填 DSH_GUARD_TOKENS='sha256:'

也可在 cordis.patch.yml 的 guard: 对象里写行级配置（环境变量优先级更高），完整字段见 standalone/guard.js 顶部的 GuardConfigSchema：

- id: guard-webserver
config:
guard:
mode: auto
behindProxy: true # 反代后面部署时打开 allowLoopback: true maxFailedAttempts: 10 lockoutSeconds: 900 sessionTtlSeconds: 604800
publicPaths: ['/robots.txt']

使用

浏览器

访问时未登录 → 自动跳转 /auth/login，输入密码后获得 7 天会话 Cookie。
登出：/auth/logout。健康检查：/auth/status（返回 {"authenticated":bool}）。

脚本 / curl

curl -H "Authorization: Bearer my-token" http://server:3080/api/...
curl "http://server:3080/api/...?token=my-token"

公网部署套路（无 GUI Linux）

三种姿势，安全度递增：

1. SSH 隧道（零暴露，最省心） ssh -N -L 3080:127.0.0.1:3080 user@server 浏览器访问 http://127.0.0.1:3080（回环免认证，或仍可加密码）

2. 直连公网：DSH_GUARD_HOST=0.0.0.0 + 凭据环境变量。没有凭据时会直接拒绝启动（安全锁）。
3. 反代 + TLS（推荐）：dsh 绑定回环，Caddy/Nginx 终止 TLS 并转发。见 docs/。
⚠️ 注意：安全锁只看绑定地址，反代场景必须配置凭据（behindProxy: true + 信任代理 IP）。

systemd 服务样例见 docs/dsh-guard.service.example。

安全设计说明

- 零竞态：守卫在 WebServer 服务构造时同步包裹 register/registerUpgrade/registerFallback，之后任何插件（包括未来新增的）注册的路由都在认证之后。不依赖激活顺序，不 patch 其他行。
- 会话无状态：HMAC-SHA256 签名 Cookie（过期时间.随机ID.签名），不依赖存储；默认密钥每次启动随机 → 重启强制重新登录，DSH_GUARD_SESSION_SECRET 可持久化。
- 密码比较：scrypt + timingSafeEqual，哈希自描述（scrypt$N$r$p$salt$hash）。
- 锁定按来源 IP，配合 behindProxy 时取可信代理写入的最右 X-Forwarded-For 值。
- 审计事件：其他插件可监听 guard/login、guard/auth-failure 做告警/联动封禁。
- 逃逸开关：DSH_GUARD_MODE=off 完全关闭保护（含安全锁）——仅在明确知情时使用。

版本兼容性

- 依赖：@deepseek-ai/dsh-host-webserver / @deepseek-ai/cordis / @deepseek-ai/schemastery （harness 内置包，profile 平铺 node_modules 兜底可解析，无需额外安装）
- 目标版本：@deepseek-ai/dsh 0.1.0-rc.6；升级后若官方 bundle 行结构变化，重跑一次
dsh plugin --profile web update dsh-guard 或重新合并 install.patch.yml 即可。

开发

端到端测试（隔离 DSH_HOME，不碰真实配置） powershell -File test/run-tests.ps1

测试覆盖：登录页/密码流程、会话 Cookie、Token（HTTP+WS 升级）、CIDR 白名单、 X-Forwarded-For、防爆破锁定、登出、安全锁 fail-loud、--dump-config 组合检查。

License

MIT