0 Fork 0

Files

T

jkooe 0d59d6032b feat(v21): 第一批安全加固 —— 证书指纹钉住 + 来源网段白名单

对应审查建议的 P0 两条：这两项是**真实可利用的攻击路径**，其余（发现最小化/失败封禁等）
留待后续批次。

## ① 证书指纹钉住（TOFU）—— 挡同网段中间人
自签证书没有 CA 链，历史上客户端只能 `insecure` 接受任意证书 → 攻击者可**透明中继**：
拿不到钥匙（挑战-应答挡得住冒名），但能读到截屏/剪贴板/键入/exec 输出。

- 被控端：`install.ps1` 打印证书指纹（sha256 of DER）供**带外核对**；
  `system.info.build.cert_sha256` 与 `auth_ok.build.cert_sha256` 上报
- 控制端：首次连接自动钉进 `nodes.<名>.cert_sha256`；之后**严格比对**，
  不一致即 `E_CERT_MISMATCH`(-32422) 拒连，并提示 `--forget-cert` 重钉
- 额外做**交叉确认**：实际握手证书 vs auth_ok 自报，不一致同样拒绝（防自报被篡改）
- 指纹基于 **DER**（不是 PEM 字节），保证与 Windows .NET `GetRawCertData()` 同值

**踩坑记录（写进代码注释，避免后人重走）**：
1. `ws` 客户端的 `upgrade` 事件**只传 IncomingMessage**，拿不到 socket
2. socket 要在 `open` 之后从 `ws._socket` 取（TLSSocket）
3. Node ≥15 的 `getPeerCertificate()` 返回**对象**，DER 在 `.raw` 上（老版本才是 Buffer）
   —— 现已双兼容

## ② 来源网段白名单 `allow_from` —— 收敛暴露面
被控端默认监听 `0.0.0.0`（远程接入所需），但**换到不可信网络就自动暴露**。

- 支持 CIDR / 单 IP / `*`；**未配置 = 放行全部**（保持向后兼容，不打断现有部署）
- 拒绝发生在**业务握手之前**（不做 TLS/挑战应答，省资源），并记 `net.deny` 审计
- 判定按**前缀比特**而非字符串相等：Node 在 IPv6 监听上把 IPv4 客户端报成
  `::ffff:a.b.c.d`，已归一化（单测覆盖）
- `system.info.network.allow_from` 上报状态；`nodeagent info` 一眼看出是否已收敛

## 验证（本地真跑，非纸面）
- 白名单不含本机 → 连接被拒（agent 侧 WARN + 审计留痕）✓
- 白名单含本机 → 连上，并**自动钉住**指纹 ✓
- **换掉被控端证书后重连 → `E_CERT_MISMATCH` 拒绝**（期望 2ed4957b… / 实际 ca8dc20c…）✓
- 新增 e2e 用例（自起 TLS agent）覆盖上述四种情形 + agent 自报与实际证书一致性 ✓
- 新增单测 9 例（CIDR 前缀匹配 / IPv4-mapped 归一 / IPv6 zone / PEM≡DER / 篡改即变）
- 全量：单测 **159**（150→159）· e2e **29**（28→29）全绿

## 文档
新增 `docs/SECURITY.md`：信任模型（钥匙=root）、认证现状与**已知限制**（ACL 身份维度仅在
ed25519 有效）、本次两项加固的用法、尚未收敛的 6 项、应急处置表。

2026-10-05 02:25:19 +08:00

6.0 KiB

Raw Blame History

版本与兼容性契约

为什么需要这份文档：agent 与 CLI/MCP 是分开更新的（CLI 随控制端装，agent 推/拉到被控端），新旧混用是常态而非例外。没有明文契约，升级顺序、什么算破坏性改动、出问题怎么定位全靠猜。

1. 版本号

单一来源：根 package.json 的 version，构建时经 esbuild --define 注入 agent。
运行时可通过 system.info 的 build 字段读到：version / commit（git sha）/ built_at / hash（运行中脚本的 sha256 前 12 位 —— 部署校验用）。

控制端在握手（auth_ok）即拿到被控端版本，nodeagent info 会显示：

被控端版本 : v1.0.0 @ ef9ad97  构建 740d51953fd0
能力对齐   : 42 项，两端一致 ✓

2. 语义化版本的含义

变更类型	版本位	例子
破坏性：删除能力、给既有能力新增必填参数、改变既有能力的返回结构、修改认证/握手流程	MAJOR	删掉 `screen.find`；把 `fs.read` 的 `path` 改成必填 `remote_path`
新增：新能力、既有能力的可选参数、新增返回字段、新增审计事件类型	MINOR	加 `system.audio.*`、给 `deploy` 加 `--check`
修复/内部：bug 修复、性能、文档、不影响协议的重构	PATCH	修备份编码、拆分文件

3. 兼容性契约（硬规则）

只增不改：既有能力的参数名与语义不得变更；要改就新增能力（如 screen.find 与未来的 screen.find2 并存一代），旧能力至少在下一个 MAJOR 才移除。
不新增必填参数：既有能力只能加可选参数 —— 否则旧控制端一调就 E_PARAM_INVALID。
返回结构只加不减：新增字段必须可选，旧控制端忽略即可。
auth_ok 的字段只增不减：v20 新增的 agent_version/build/protocol 均为可选，旧控制端不认也不报错。
协议主版本（PROTOCOL_VERSION 的主号）不一致时被控端直接拒绝连接并返回 E_PROTOCOL_MISMATCH —— 这是唯一的硬闸门，用于承载无法兼容的协议变更。
能力清单是唯一事实源：控制端不比版本号，而是比能力集合 （capabilityDiff）—— 版本号可能相同而内容不同（本地 dev 构建），能力集合不会骗人。

3.1 v21 新增字段（均为可选，向后兼容）

位置	字段	含义
被控端 `agent.json`	`allow_from: string[]`	来源网段白名单；未配置 = 放行全部（与旧行为一致）
被控端 `system.info`	`build.cert_sha256` / `network.allow_from`	证书指纹与白名单状态（供控制端展示与巡检）
被控端 `auth_ok`	`build.cert_sha256`	同上（握手期即可得）
控制端 `nodes.<名>`	`cert_sha256: string`	钉住的被控端证书指纹；不一致即 `E_CERT_MISMATCH` 拒连
发现报文	`cert_sha256`	未认证广播，仅作参考，不可当身份凭据

新增错误码：E_CERT_MISMATCH (-32422)、E_NET_DENY 类事件走审计 net.deny。

4. 升级顺序建议

先升级被控端，再升级控制端：

组合	结果
新被控端 + 旧控制端	✅ 安全。被控端只做加法，旧控制端不认识的新能力会被忽略
旧被控端 + 新控制端	⚠️ 可用，但新功能不可用。`nodeagent info` 会列出远端缺少的能力并提示升级

若顺序反了也不会坏：控制端调用缺失能力时返回 E_CAPABILITY_NOT_FOUND，而 nodeagent info / connect 会提前把它变成一句人话提示。

5. 更新方式（两条路，按可达性选）

方式	命令	前提
推送式	`pnpm update:win <设备名>`	控制端↔被控端可达；自动打包含校验与指纹复核
拉取式	`nodeagent update --url <地址> --sha256 <哈希>`	只要被控端能上网（含 GitHub Release）

先预检再更新（不动任何文件）：

nodeagent --node win update --url <地址> --sha256 <哈希> --dry-run

--sha256 是安全底线：不校验哈希等于开放远程代码执行。

6. 发版流程

pnpm release patch|minor|major|<x.y.z>   # 改版本 → 构建 → 打包 → 校验和/清单 → 提交打标签 → GitHub Release
pnpm release 1.0.0 --dry-run             # 演练（无任何副作用）

产物（GitHub Release 资产）：

资产	用途
`agent.mjs`	自更新载荷 —— 被控端 `system.agent.update` 直接用它（配 `--sha256`）
`nodeagent-win-x64.zip`	人工安装包（自包含 `node.exe`，免装 Node.js）
`latest.json`	版本清单：version/commit/built_at/capabilities + 两个资产的 url 与 sha256
`SHA256SUMS`	校验和

⚠️ 首次仍需一次性安装：自更新能力本身得先在机器上（鸡生蛋无解）。 ⚠️ node.exe（Node 运行时）不在自更新范围：只换 agent.mjs；需升级 Node 时重跑 install.ps1。 ⚠️ 本仓库的 .github/ 改动需要 workflow 权限才能推送（gh auth refresh -h github.com -s workflow），发版脚本刻意跳过 .github/，避免发版流程被它卡住。

7. 出问题怎么排查

nodeagent --node win info                       # 版本 + 能力对齐情况（先看这个）
nodeagent --node win invoke system.info --args '{"fields":["build"]}'   # 构建指纹
nodeagent --node win deploy <包> --check        # 本地包 vs 远端是否一致（不改动）

远端过旧：info 会列出缺失能力 → nodeagent update ...
本控制端过旧：info 会列出"不认识的新能力" → 更新控制端（git pull → pack:mac → install-macos.sh）
同版本但指纹不同：属正常（内容相同才叫同版本）；用 --check 对比实际内容
部署后没生效：先查杀软是否处置了被替换的 agent.mjs（见 REMOTE-LIMITS.md 的「杀软误拦」）

6.0 KiB Raw Blame History Unescape Escape