nodeagent

100 Commits 1 Branch 14 Tags

2 Commits

Include renames

Author	SHA1	Message	Date
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
jkooe	cedc46d090	feat(v20): 版本纪律 + 发版自动化（对齐「做好版本功能 + GitHub 同步资产」） ## 一、版本功能（防新旧混用） 1. 单一版本源 + 构建注入：根 package.json 的 version、git sha、构建时间经 esbuild `--define` 注入 agent；`system.info.build` 新增 `version/commit/built_at`（原有 `hash` 指纹不变）。开发态用 typeof 探测（未注入也不崩）。 2. 握手携带版本：`auth_ok` 新增可选字段 `agent_version` / `build` / `protocol`（只增不减 → 旧控制端忽略即可）。 3. 能力级兼容比对：新增纯函数 `capabilityDiff(local, remote)` —— - `missingOnRemote`：本地有远端没有 → 远端较旧，提示更新被控端 - `unknownLocally`：远端有本地没有 → 本控制端较旧（不影响既有功能）控制端不比版本号而比能力集合：版本号可能相同而内容不同，能力集合不会骗人。 4. CLI 体检：`nodeagent info` / `connect` 直接显示被控端版本与能力对齐情况，把"调用时才炸"变成一句人话提示。 ## 二、发版自动化（GitHub 资产同步） `pnpm release <x.y.z\|patch\|minor\|major>`：前置检查（干净/在 main/与远端同步）→ 改 7 个 package.json → 构建+打包 → 生成资产 → 提交打标签推送 → `gh release create` 上传。 - 资产：`agent.mjs`（自更新载荷）、`nodeagent-win-x64.zip`（人工安装包）、 `latest.json`（version/commit/能力数 + 两个资产的 url 与 sha256）、`SHA256SUMS` - `--dry-run` 无副作用演练；`--no-publish` 只到本地标签 - 能力数从 dist 动态取（避免写死漂移）；刻意排除 `.github/`（缺 workflow 权限推不了） ## 三、兼容性契约文档新增 `docs/VERSIONING.md`：semver 各位的含义、只增不改六条硬规则、升级顺序建议（先被控端：新被控端向后兼容旧 CLI）、两条更新路径、发版流程、排查手册。 ## 验证 - 单测 147 → 149（新增 capabilityDiff 用例：远端过旧 / 本机过旧 / 完全一致 / 真实清单自比无差异） - e2e 28 全绿；`node scripts/release.mjs 1.0.0 --dry-run` 演练通过且工作区无副作用	2026-10-04 23:54:51 +08:00

Author

SHA1

Message

Date

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

jkooe

cedc46d090

feat(v20): 版本纪律 + 发版自动化（对齐「做好版本功能 + GitHub 同步资产」）

## 一、版本功能（防新旧混用）
1. **单一版本源 + 构建注入**：根 package.json 的 version、git sha、构建时间经 esbuild
   `--define` 注入 agent；`system.info.build` 新增 `version/commit/built_at`（原有 `hash` 指纹不变）。
   开发态用 typeof 探测（未注入也不崩）。
2. **握手携带版本**：`auth_ok` 新增可选字段 `agent_version` / `build` / `protocol`（只增不减 → 旧控制端忽略即可）。
3. **能力级兼容比对**：新增纯函数 `capabilityDiff(local, remote)` ——
   - `missingOnRemote`：本地有远端没有 → **远端较旧**，提示更新被控端
   - `unknownLocally`：远端有本地没有 → **本控制端较旧**（不影响既有功能）
   控制端不比版本号而比**能力集合**：版本号可能相同而内容不同，能力集合不会骗人。
4. **CLI 体检**：`nodeagent info` / `connect` 直接显示被控端版本与能力对齐情况，
   把"调用时才炸"变成一句人话提示。

## 二、发版自动化（GitHub 资产同步）
`pnpm release <x.y.z|patch|minor|major>`：前置检查（干净/在 main/与远端同步）→ 改 7 个 package.json
→ 构建+打包 → 生成资产 → 提交打标签推送 → `gh release create` 上传。
- 资产：`agent.mjs`（**自更新载荷**）、`nodeagent-win-x64.zip`（人工安装包）、
  `latest.json`（version/commit/能力数 + 两个资产的 url 与 sha256）、`SHA256SUMS`
- `--dry-run` 无副作用演练；`--no-publish` 只到本地标签
- 能力数从 dist 动态取（避免写死漂移）；刻意排除 `.github/`（缺 workflow 权限推不了）

## 三、兼容性契约文档
新增 `docs/VERSIONING.md`：semver 各位的含义、**只增不改**六条硬规则、
升级顺序建议（**先被控端**：新被控端向后兼容旧 CLI）、两条更新路径、发版流程、排查手册。

## 验证
- 单测 147 → **149**（新增 capabilityDiff 用例：远端过旧 / 本机过旧 / 完全一致 / 真实清单自比无差异）
- e2e 28 全绿；`node scripts/release.mjs 1.0.0 --dry-run` 演练通过且工作区无副作用

2026-10-04 23:54:51 +08:00