mtfyun/nodeagent
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
73 Commits 1 Branch 14 Tags
e841fbb187c1be24e46b9bcf5e63d29d4f22bb49
Commit Graph
13 Commits
Author SHA1 Message Date
jkooe e841fbb187 feat(v22): 第二批安全加固 —— 每客户端独立 PSK + 发现广播最小化 
接着 v21 的两件 P0，补齐第二批清单里的两项（对应原建议 ③/④ 的一半）。

## ① 每客户端一把 PSK（`agent.json` 的 `keys{}`）—— 让 ACL 的身份维度真正有效
**问题**：psk 模式下 `client_id` 由客户端自报（server.ts 原注释自认），
一把共享 key 意味着**持有者可冒充任意 client_id**，ACL 的身份维度形同虚设。

**做法**：按 `client_id` 分配独立钥匙；未登记者回落到共享 `key`（旧部署行为不变）。
比 ed25519 更轻量（不用管公钥），同样是「一把一个身份」。

**实测**（五场景全对）：
| 场景 | 结果 |
|---|---|
| alice 用自己的 key | ✅ |
| **alice 的 key 冒用 bob 身份** | ❌ E_AUTH_FAILED ← 核心安全性质 |
| bob 用自己的 key | ✅ |
| 未登记 carol 用共享 key | ✅（向后兼容） |
| 已登记 alice 用共享 key | ❌ 拒绝（专属优先，不被共享 key 绕过） |

配套：`nodeagent keygen --psk --id mac_02` 生成专属 key 并打印可直接粘贴的 agent.json 片段；
鉴权日志带 `key=scoped|shared-fallback|shared`，审计区分「专属钥匙失败」与「回落共享失败」。

## ② 发现广播最小化（`discovery.detail` + `discovery.secret`）—— 收情报泄漏
**问题**：UDP 广播未认证，默认明文告知 IP/端口/认证方式/键鼠开关，等于给攻击者一份目标清单。

**做法**：
- `detail: "minimal"` → 顶层只剩 `service / version / node_id / ts`，
  真实信息收进 `detail{}`（**实测顶层已无 host/port/auth_mode/input_enabled**）
- 配 `secret` → `detail` 带 HMAC 签名（`node_id|ts|JSON(detail)`），
  控制端 `discover --discover-secret <同一密钥>` 验签 → 列表标 **🔒 已认证**；
  未配/验签失败标 **⚠️ 明文**（明示「仅作参考、不可当凭据」）
- 配了 secret 自动启用 minimal；未配置时启动横幅**醒目告警**提示收敛

**实测**三视角：正确密钥 🔒 / 无密钥 ⚠️ / 错密钥 ⚠️（验签失败正确降级）✓

## 验证
- 单测 159 → **162**（新增签名往返一致性：错密钥/篡改详情/改时间戳均须验签失败）
- e2e **29** 全绿；本轮改动为纯加法（新增可选字段），未破坏既有行为
- 文档 `SECURITY.md` 新增 §4.5 / §4.6，并把「发现最小化」从待办划掉

## 剩余待办（SECURITY.md §5）
握手失败封禁 / 审计链签名与外部锚定 / 会话上限与空闲断开 / 安装期密钥改用文件传递 /
ed25519 仍非默认（v22 的 `keys{}` 已是更轻量的等价物）
 2026-10-05 02:42:12 +08:00
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
jkooe 9853ee8cdb docs: 增补「杀软误拦（主流杀软 / 杀软 / 360）」排查章节 
真机实证：远程接管类工具的特征（未知 exe + 建计划任务 + 开防火墙 + 常驻监听 + 注入键鼠）
必然触发杀软拦截。主流杀软会拦 install.ps1 执行 / 计划任务注册，或直接处置 node.exe，
表现为「下载成功但装不上」或「装上后 agent 起不来」。

新增内容：
- 逐项放行清单（安装目录 / node.exe / agent.mjs / nodeagent 计划任务 / 入站 8765 / PowerShell 执行 / 键鼠截屏）
- 自检命令（任务状态 + 进程 + 端口三连查）
- 排查顺序：任务与进程 → 端口 → **确认两台机器在同一网络**
- 特别标注最后一个坑：控制端换 Wi-Fi（酒店/热点）后仍在扫旧网段，会误判为「失联」
 2026-10-03 03:07:23 +08:00
jkooe 3f91e1ddc0 docs: 新增《实战复盘：短板与改进优先级》 
基于真机部署 + v2rayN 故障排查 + 重装前采集的真实使用，梳理短板：

P0（决定能不能用）
1. GUI 语义能力缺失 —— 有截屏有鼠标，但没有「界面元素 -> 坐标」的映射，
   切个节点反复点错三次，最后靠键盘导航才成功。建议引入 UIA。
2. 编码不统一 —— 三个真实事故均源于此：Set-Content 写 BOM 致 agent 起不来、
   PowerShell 管道损坏中文致清单报废、控制台 GBK 误判。
3. 自断生路 —— 重启 agent 时分离进程被自身进程树清理一起杀掉，导致失联。
   建议提供受控重启（system.agent.restart）+ 看门狗自愈 + 配置回滚。
4. exec 输出未结构化 —— 尾部附加 [退出码/耗时] 文本，污染 JSON 解析。

P1：长任务异步化、定时采样、剪贴板、窗口管理、CLI 常驻 daemon
P2：事件订阅、文件监控、录屏、拖拽/宏、多设备并行、DPAPI

一句话：能看能算能跑命令已扎实，短板在「语义」（读不懂界面）、
「状态」（只看当下）与「自持」（改不动自己）。
 2026-09-28 22:01:15 +08:00
jkooe eb331502a6 docs: 新增《跨机接管的边界与局限》并记录真实故障诊断案例 
皇上报障「Windows 上 WorkBuddy 反复提示 Response timed out」，要求记录
「受到什么局限导致 Mac 端无法修复 Windows 上的问题」。

新增 docs/REMOTE-LIMITS.md：
- 能力边界总览（读状态/执行命令/改文件可；改网络高风险；GUI 与人工判断不可）
- 五大核心局限：自断生路悖论 / 无 GUI 交互 / 无法替代人的判断 / 观测窗口时点性 / 破坏性操作不可逆
- 协作模式建议（能看能算的远程，断后路与需判断的交人工）
- 真实案例（2026-09-27）：完整诊断链路与判读

本次远程诊断结论（未触碰 Windows 即完成）：
- 链路正常：Ethernet 1Gbps/百度 200/腾讯 IPv4 200
- 矛盾状态：System Proxy ProxyEnable=0 但 ProxyServer 残留 127.0.0.1:10808
- 走 10808 访问外网超时 -> xray 上游节点不通
- resolveProxy RPC 耗时 1737ms（代理解析卡顿）
- MarketplaceInitGate 15s 安全超时后强放行
判定高度可能为「代理配置残留 + 上游节点实际不通」导致部分请求超时；
未直接修复，因所需动作为 v2rayN GUI 换节点（属 GUI + 人工判断）。
 2026-09-27 20:23:21 +08:00
jkooe 3d03945448 feat(v6): Hub 中转 —— 跨网段 / 公网接入 
新增 apps/hub（中转节点）：
- 被控端主动外连注册（/hub/agent），控制端接入配对（/hub/client）
- 配对后双向字节透传 —— Hub 不解析内容、不持有设备密钥
- Hub 令牌鉴权；list 可查在线设备
- 连接语义：控制端断开仅解绑（被控端保持在线）；被控端掉线连带关闭控制端
- 同一被控端同一时刻仅服务一个控制端（占用返回 E_NODE_BUSY）

被控端：
- 新增 hub 配置；启用后不监听本地端口，改为主动外连 Hub（穿 NAT）+ 指数退避重连
- 重构抽出 createAgentCore()，监听模式与 Hub 模式共用同一套鉴权/ACL/能力分发

控制端：
- NodeProfile 新增 hub 字段；toWsUrl 自动附 /hub/client 路径
- client 支持 Hub 配对（控制面消息与 RPC 分离）

修复（Hub 场景暴露）：
- cmdConnect 漏传 hub 字段，导致跳过配对直接发 RPC
- Hub unpair 过激进：控制端断开时把被控端也踢下线
- 安全：被控端 hello 时重置认证态与授权（Hub 下同一连接被多控制端复用）

验证：本地 E2E 21/21；构建 + 类型检查全绿；冒烟确认 info/exec 穿透 Hub 且多次接入保持在线
 2026-09-27 15:04:05 +08:00
jkooe 4ff1b4fd90 feat(v5): 多设备管理 + 文件传输 
方向 1 · 多设备管理：
- 配置模型升级为 nodes{} + current，自动迁移 v1/v2 单设备扁平配置（零破坏）
- 新增 resolveTarget()：按名解析生效设备与控制端身份
- CLI: nodes（列表）/ use（切换）/ remove（移除）/ connect --name（命名）
- 全局 --node <设备名> 单次指定目标，前置（--node=x cmd）与后置（cmd --node x）均可

方向 2 · 文件传输（分块 RPC，协议零改动）：
- fs.list（递归+glob）/ fs.stat / fs.read（offset+max_bytes 分块）/ fs.write（原子写+append）
- 小文件（<=8MB）首次读取附带 sha256；路径白名单 fs_roots，越界 -> E_ACL_DENIED
- CLI: ls / stat / cat / pull / push（自动分块；pull 与 push 均原子落盘）
- MCP: na_fs_list / na_fs_read / na_fs_write

能力总数 15 -> 19；MCP 工具 12 -> 15

验证：本地 E2E 20/20（新增文件传输全链路用例）；构建 + 类型检查全绿；
冒烟确认 3MB 文件 pull 后 sha256 一致、白名单越界被拒
 2026-09-27 13:25:38 +08:00
jkooe 3d0eb1c696 feat(v4): 无感体验 —— 局域网自动发现 + 断线自动重连 
自动发现（免手抄 IP）：
- 被控端 UDP 心跳广播（默认 5s 一次，目标 255.255.255.255:8766）
- 控制端 Discovery 监听 + TTL 设备表（默认 30s 过期）
- 报文不含任何凭据；可 discovery.enabled:false 关闭
- 控制端取「报文来源 IP」作为可达地址（比被控端自报地址可靠）
- CLI: nodeagent discover [--wait 5]；MCP: na_discover

断线自动重连：
- client 新增 autoReconnect（指数退避 1s→30s + ±15% 抖动）
- 重连前清空在途请求（统一 E_NODE_OFFLINE），避免悬挂
- onStateChange 回调（connected/reconnecting/closed）
- close() 会停止重连，不会关不掉

修复：UDP socket 需先 bind 再 setBroadcast（未绑定时报 EBADF）

验证：本地 E2E 19/19（新增发现 + 重连两用例）；构建与类型检查全绿
 2026-09-27 13:11:13 +08:00
jkooe edc69b0a34 feat(v3+): 审计日志 + 调用限速 
审计（安全闭环最后一环）：
- 被控端将关键动作以 JSONL 写入 <数据目录>/audit.log：agent 启停 / 认证成败 /
  invoke 结果 / ACL 拒绝 / 限速拦截
- 大小轮转（默认 10MB × 5 份）；参数默认只记 sha256 摘要，log_args 开启后
  自动脱敏（pass/token/secret/key/auth 键 → ***，字符串截断 200 字符）
- 审计写入失败被吞掉，绝不阻断业务主流程
- 新增能力 system.audit.list（支持 limit/since/client_id/type 筛选）
- CLI: nodeagent audit；MCP: na_audit

限速：
- 落地 ACL 中预留的 max_calls_per_min（按调用方滑动窗口计数）
- 超限返回 E_RATE_LIMITED(-32407)

验证：本地 E2E 全绿；零信任用例扩展为 6 项断言（授权/拒绝/审计留痕/脱敏/限速/未注册/错钥）
 2026-09-27 11:56:37 +08:00
jkooe 5b7e967868 feat(v3): 零信任安全 —— Ed25519 身份认证 + 能力级 ACL 
认证（两模式并存，默认 psk 向后兼容）：
- 新增 auth_mode: psk | ed25519
- ed25519：每控制端独立密钥对，挑战-应答签名验证（替代共享密钥）
- 密钥用 Node 内置 crypto 生成（零新依赖），Base64(DER) 单行格式
- 私钥存 <数据目录>/keys/ed25519.json（600 权限，永不外传）

授权（能力级 ACL）：
- acl.clients[] 按调用方登记 pubkey + allow/deny（glob 匹配）
- 判定顺序 deny → allow → default_effect（默认拒绝）
- 未注册身份 / 验签失败 → 握手拒绝；未授权能力 → E_ACL_DENIED
- auth_ok 下发 authorized 子集，CLI 以 授权/未授权 标识展示授权矩阵

接入：
- CLI: keygen（生成密钥 + 打印 ACL 配置片段）、connect --auth-mode ed25519
- MCP: 按 auth_mode 自动选择认证方式
- install.ps1: 显式写 auth_mode + 零信任指引

验证：本地 E2E 17/17（新增零信任四项断言）；手动端到端复验通过
 2026-09-27 11:01:58 +08:00
jkooe 792937c6b0 feat(v2): 图形接管 —— 屏幕感知 + 输入控制 
新增 7 项能力（总计 14）：
- screen.info / screen.capture：显示器信息、截屏（region/scale/format）
- input.mouse.move/click/scroll、input.key.type/press：鼠标键盘控制

安全设计：
- input.* 为高危能力，由被控端 allow_input 开关统一管控，默认禁用
- 未开启时返回 E_CAPABILITY_DISABLED（附开启指引）
- 文本输入经 Base64 传参、PowerShell 侧解码，杜绝内容注入
- 按键名走白名单映射（虚拟键码），非法键名直接拒绝

实现：纯 PowerShell（System.Drawing 截屏 + user32.dll SendInput），
无原生编译、无第三方依赖。

接入：
- CLI: screen / screenshot / mouse / key 命令
- MCP: na_screenshot（直接返回图像）/ na_mouse / na_key
- install.ps1: 新增 -AllowInput 开关
- verify.mjs: 新增 v2.1~v2.3 验收项

验证：本地 E2E 16/16；远程验收 12 通过 / 0 失败
 2026-09-27 03:43:10 +08:00
jkooe 3e129e6411 docs: 新增 nodeagent 开发文档（DEVELOPMENT.md，参考 NodeBuddy 裁剪） 2026-09-27 00:50:35 +08:00