justme/MoShiro
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

docs: describe the unified Agent topology and link controls

Browse Source 
Align architecture, protocol, API, storage, security and deployment documentation with default mutual measurements and the Agent link board.
This commit is contained in:
justme committed 2026-10-21 11:55:55 +08:00
1 parent 15f0023614
commit c9beeee8e3
16 files changed
+363 -383
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/security/security.md
+34 -34
View File
@@ -1,19 +1,19 @@
# 零信任设计
> 实现状态：协议方向声明表和卡口、Probe 自己生成密钥、预握手敲门、操作员集合与创世固定、服务器身份和安全链路、属主固定都已实现；测量数据的产生者签名、入库配额、Probe 拨号地址限制等还没做（第 3 节有逐项状态）。
> 实现状态：协议方向声明表和卡口、拨号方 自己生成密钥、预握手敲门、操作员集合与创世固定、服务器身份和安全链路、属主固定都已实现；测量数据的产生者签名、入库配额、拨号方 拨号地址限制等还没做（第 3 节有逐项状态）。
Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题：现在谁听谁的、被攻破之后最坏会怎样、怎么用密码学把信任从 Backend 身上拿走。账户、能力、passkey 和入网信任链的具体做法见 [access.md](access.md)；节点能力边界、本地硬上限和签名更新见 [architecture.md](../design/architecture.md) 第 5 节，这里不重复。
Agent、Backend、拨号方 之间互相不信任。这份文档回答三个问题：现在谁听谁的、被攻破之后最坏会怎样、怎么用密码学把信任从 Backend 身上拿走。账户、能力、passkey 和入网信任链的具体做法见 [access.md](access.md)；节点能力边界、本地硬上限和签名更新见 [architecture.md](../design/architecture.md) 第 5 节，这里不重复。
## 1. 范围
要防的
- Backend（或 Backend 前面的 Cloudflare Tunnel、frp、Caddy 等中间环节）被攻破或被劫持之后，给节点下发恶意内容。
- Agent 或 Probe 自己被入侵之后，去影响 Backend 或对端。
- Agent 或 拨号方 自己被入侵之后，去影响 Backend 或对端。
有意不做的
- 进程沙箱（seccomp、pids 和内存上限、出站白名单）。Agent 和 Probe 的定位是 1 核 1 GB 的小机器，不能吃资源。
- 进程沙箱（seccomp、pids 和内存上限、出站白名单）。Agent 的定位是 1 核 1 GB 的小机器，不能吃资源。
- 供应链的多签、冷却期和可复现构建。代码风险靠 PR 评审降一个等级；发布仍然是单把发布密钥签名（见 [deployment.md](../ops/deployment.md)）。
- 顺带记一条：Agent 的单元挂了 `/:/host/root:ro`、`/proc`、`/sys`，被攻破的 Agent 能遍历宿主机。它们多半是不必要的（宿主网络模式下容器自己的 `/proc` 就是宿主的，磁盘用量可以对已挂载的 `/etc/os-release` 做 `statvfs`），属于沙箱范畴，先不动。
@@ -23,7 +23,7 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
| --- | --- | --- |
| T1 | Backend，或它前面的中间环节 | 链路经过 Cloudflare Tunnel、frp、Caddy，它们都能看到 wss 的明文 |
| T2 | 某个 Agent（在 VPS 上，旁边还有别的服务） | VPS 被入侵 |
| T3 | 某个 Probe（在客户内网里） | 客户机器被入侵 |
| T3 | 某个 拨号方（在客户内网里） | 客户机器被入侵 |
| T4 | 管理员的会话或令牌 | 令牌泄露 |
| T5 | 管理员的浏览器 | XSS，或者节点上报的字符串被渲染 |
@@ -35,28 +35,28 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
管理员 ──令牌/会话──▶ ┌──────────┐ ◀── 原始块、事件、主机数字
│ Backend │
└──┬───┬───┘
任务集、对端公钥、 │ │ Agent 名单（host:port，Probe 全部照拨）
任务集、对端公钥、 │ │ Agent 名单（host:port，拨号方 全部照拨）
重启计划、更新清单 ▼ ▼
┌──────┐ ┌──────┐
│Agent │◀─▶│Probe │ Probe 私钥由节点自己生成
│Agent │◀─▶│拨号方 │ 拨号方 私钥由节点自己生成
└──────┘ └──────┘
```
| # | 缺口 | 状态 |
| --- | --- | --- |
| G1 | 节点不验证 Backend 的身份，只靠 TLS 加公共 CA | 已解决：操作员集合里登记服务器密钥，节点要求服务器在认证挑战里签名，链路用应用层加密（[access.md](access.md) 第 8 节）。对 Backend 自己被攻破没有帮助 |
| G2 | Probe 的私钥由 Backend 生成 | 已解决：Probe 自己生成密钥，用加入令牌注册，私钥只在节点上（破坏性：旧 `probe.json` 失效） |
| G3 | Probe 会拨 Backend 给的任意 `host:port` | 未解决：被攻破的 Backend 能让客户内网里的 Probe 去探测内网；本地 `limits` 只有速率、pps 和 `allowed_target_cidrs` |
| G4 | Agent 的 TCP 端口对任何人完成 TLS 握手并出示证书 | 已解决：预握手敲门，见第 8 节（破坏性：旧 Probe 被拒绝） |
| G2 | 拨号方 的私钥由 Backend 生成 | 已解决：拨号方 自己生成密钥，用加入令牌注册，私钥只在节点上（破坏性：旧 `agent.json` 失效） |
| G3 | 拨号方 会拨 Backend 给的任意 `host:port` | 未解决：被攻破的 Backend 能让客户内网里的 拨号方 去探测内网；本地 `limits` 只有速率、pps 和 `allowed_target_cidrs` |
| G4 | Agent 的 TCP 端口对任何人完成 TLS 握手并出示证书 | 已解决：预握手敲门，见第 8 节（破坏性：旧 拨号方 被拒绝） |
| G5 | Backend 入库只限制了单块的大小，没有按节点的速率或配额 | 未解决：恶意节点可以灌满磁盘 |
| G6 | 对端公钥、Agent 地址全由 Backend 决定 | 未解决：操作员集合不包含成员名册，被攻破的 Backend 能把恶意 Probe 加进 Agent 的白名单，或把 Probe 指向恶意 Agent |
| G6 | 对端公钥、Agent 地址全由 Backend 决定 | 未解决：操作员集合不包含成员名册，被攻破的 Backend 能把恶意 拨号方 加进 Agent 的白名单，或把 拨号方 指向恶意 Agent |
| G7 | 方法的方向和角色没有统一声明 | 已解决：声明表和卡口，见第 6 节 |
| G8 | 测量数据没有产生者签名（块只有 CRC32C） | 未解决：中间环节可以改写测量数据；被攻破的 Agent 可以伪造 Probe 侧的时间戳 |
| G9 | 入库只核对了 `agent_id`，不核对块里的 `series`（`line:<probe_id>`） | 未解决：被攻破的 Agent 可以为从没连过它的 Probe 灌入假线路数据 |
| G8 | 测量数据没有产生者签名（块只有 CRC32C） | 未解决：中间环节可以改写测量数据；被攻破的 Agent 可以伪造 拨号方 侧的时间戳 |
| G9 | 入库只核对了 `agent_id`，不核对块里的 `series`（`line:<dialer_id>`） | 未解决：被攻破的 Agent 可以为从没连过它的 拨号方 灌入假线路数据 |
| G10 | 没有合理性检查（`EchoOps` 不检查回显时间戳的一致性） | 未解决：恶意 Agent 可以谎报 `t2`、`t3` |
| G11 | Probe 的一把密钥多处使用 | 已解决：面向 Backend 和面向对等面的是独立的密钥，用途前缀做域隔离 |
| G11 | 拨号方 的一把密钥多处使用 | 已解决：面向 Backend 和面向对等面的是独立的密钥，用途前缀做域隔离 |
没有问题的部分：UDP 端口对未认证的包静默丢弃，不回应（`DropInvalid`，有测试）；Probe 本身没有 TCP 监听；任务有本地硬上限；更新清单有签名和 `seq` 防回滚。
没有问题的部分：UDP 端口对未认证的包静默丢弃，不回应（`DropInvalid`，有测试）；拨号方 本身没有 TCP 监听；任务有本地硬上限；更新清单有签名和 `seq` 防回滚。
## 4. 信任锚点
@@ -65,7 +65,7 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
```text
① 发布密钥（CI） ──▶ 「跑什么代码」 清单签名、seq 防重放
② 操作员密钥（管理员 passkey）──▶ 「谁是操作员、哪个是合法的 Backend」 操作员集合，Backend 持有不了
③ 节点自己的密钥 ──▶ 「我是我」 Agent 和 Probe 都自己生成
③ 节点自己的密钥 ──▶ 「我是我」 Agent 都自己生成
被攻破的 Backend 能做的：拒绝服务、看数据、改成员名册和任务（G3、G6）。
不能做的：改操作员集合、冒充节点、塞恶意更新（发布清单要 CI 签名，节点的更新器还会再验）。
@@ -88,11 +88,11 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
外部面（人、浏览器、脚本） /api/public（匿名只读，SSE） /api/admin（Cookie + CSRF，或 API 令牌）
/install /openapi /healthz /metrics
节点面（节点主动拨入） /api/agent/v1/enroll（加入令牌，一次性） /api/agent/v1/rpc（wss，节点签名认证）
对等面（Probe 拨 Agent） TLS 控制 7443/tcp、数据 7443/udp、7444/tcp（先过敲门）
对等面（拨号方 拨 Agent） TLS 控制 7443/tcp、数据 7443/udp、7444/tcp（先过敲门）
```
- 每个平面只认自己的凭证：节点面不接受令牌和 Cookie；外部面不接受节点签名；对等面只认敲门通过的成员。
- 连接方向固定：节点面永远是节点拨入 Backend，Backend 从不主动连节点，所谓「下发」只是在节点拨入的连接上发下行消息；对等面永远是 Probe 拨 Agent，Agent 不拨 Probe。
- 连接方向固定：节点面永远是节点拨入 Backend，Backend 从不主动连节点，所谓「下发」只是在节点拨入的连接上发下行消息；对等面永远是 拨号方 拨 Agent，Agent 不拨 拨号方。
- 外部面不能直通节点面：管理端的操作（例如发起测试）只会触发 Backend 里一个强类型的下行方法，管理端不能指定方法名，也不能把请求体原样转给节点（`IAgentGateway` 里全是强类型方法）。
- 三个平面共用同一个监听端口和同一条 ASP.NET 管线，靠路径和凭证类型区分。把节点面和外部面做成可以分别配置监听地址（默认仍同一个），这样管理面可以只对内网或 VPN 开放，是待定的目标。
@@ -102,7 +102,7 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
强制方式：
1. 一份声明表，单一真源：框架的 `fleet.*` 在 `Fleet.Rpc/MethodTable.cs` 的 `FleetMethodTable`，`moshiro.*` 和两条二进制通道在 `MoShiro.Protocol` 的 `MoShiroMethodTable`；角色是 `NodeRoles`（服务端按节点 ID 前缀判断）。声明表按（平面，名字）查找，同名方法在两个平面里可以有不同的发起方（`fleet.state.sync` 在节点面是 Backend→节点，在对等面是 Agent→Probe）。
1. 一份声明表，单一真源：框架的 `fleet.*` 在 `Fleet.Rpc/MethodTable.cs` 的 `FleetMethodTable`，`moshiro.*` 和两条二进制通道在 `MoShiro.Protocol` 的 `MoShiroMethodTable`；角色是 `NodeRoles`（服务端按节点 ID 前缀判断）。声明表按（平面，名字）查找，同名方法在两个平面里可以有不同的发起方（`fleet.state.sync` 在节点面是 Backend→节点，在对等面是 Agent→拨号方）。
2. 卡口在 `RpcRouter`：创建时必须给出本侧（`RpcSide`）和声明表。注册处理函数时核对方向、类型、角色，不符就在启动时失败；分发时拒绝没有声明、方向不对、请求和通知用反了、角色不允许的消息，回 `fleet_protocol_violation`；发送前核对本侧有没有资格发起（违反是程序缺陷，抛异常）。
3. 违规处理：`RpcSession` 和服务端的 `NodeConnection` 对违规计数，超过上限（`MaxViolations`，默认 20）就断开连接；二进制通道也在服务端按声明核对。
4. 响应匹配：只接受对应未决请求 ID 的响应，不接受主动「响应」。
@@ -115,7 +115,7 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
| --- | --- | --- |
| 操作员集合新版本 | 操作员 passkey 签名，节点自己验 | 什么都改不了；能转发旧的合法版本，版本号递增防回放 |
| 更新清单 | 发布密钥（CI） | 不能伪造；能转发旧的合法清单，`seq` 防回滚；节点的更新器还会用本机公钥再验 |
| 成员名册、对端公钥、Agent 地址 | Backend（G3、G6 未解决） | 能把恶意 Probe 加进 Agent 的白名单，或把 Probe 指向恶意 Agent |
| 成员名册、对端公钥、Agent 地址 | Backend（G3、G6 未解决） | 能把恶意 拨号方 加进 Agent 的白名单，或把 拨号方 指向恶意 Agent |
| 任务集、测试请求 | Backend 计算；节点本地硬上限兜底 | 只能在本地速率和端口上限内发测量流量 |
| 重启计划（`moshiro.schedule`） | Backend；节点本地启动后 10 分钟内不触发 | 最多让节点每 10 分钟重启一次 |
| 未来的 `extension`（exec 等，尚未实现） | 属主 passkey 签名的一次性能力令牌，见第 9 节 | 设计目标是没有属主签名就无法调用 |
@@ -124,12 +124,12 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
### 7.1 测量数据的可信（G8、G9、G10）
测量数据是这个项目的产出，不能只靠传输层可信：链路有 Cloudflare 这样的中间环节，Agent 又要转发 Probe 的数据。
测量数据是这个项目的产出，不能只靠传输层可信：链路有 Cloudflare 这样的中间环节，Agent 又要转发 拨号方 的数据。
- 产生者签名：每个列块由 Probe 签名，每个原始块由上传它的节点签名；Agent 转发 Probe 的块时原样保留签名。签名覆盖块的摘要（SHA-256），签名串带用途前缀 `chunk` 和节点 ID。Backend 入库时逐个验签，不通过的丢弃并计数。每 10 秒一块，一次 ECDSA 验签的开销可以忽略。
- 归属校验：入库时核对块里的 Probe 是和这个 Agent 有线路的成员，不是就丢弃并计数。
- 产生者签名：每个列块由 拨号方 签名，每个原始块由上传它的节点签名；Agent 转发 拨号方 的块时原样保留签名。签名覆盖块的摘要（SHA-256），签名串带用途前缀 `chunk` 和节点 ID。Backend 入库时逐个验签，不通过的丢弃并计数。每 10 秒一块，一次 ECDSA 验签的开销可以忽略。
- 归属校验：入库时核对块里的 拨号方 是和这个 Agent 有线路的成员，不是就丢弃并计数。
- 合理性检查：`t3−t2` 必须小于 `t4−t1`，各时间戳单调；违反的样本不计入指标，记为异常并产生事件。
- 边界：这样中间环节改不了数据，被攻破的 Agent 改不了 Probe 一侧的数据；但它仍然可以谎报自己一侧的 `t2`、`t3`，合理性检查只能限制它的幅度，因为这一侧的真值只有它自己知道。
- 边界：这样中间环节改不了数据，被攻破的 Agent 改不了 拨号方 一侧的数据；但它仍然可以谎报自己一侧的 `t2`、`t3`，合理性检查只能限制它的幅度，因为这一侧的真值只有它自己知道。
### 7.2 对 Backend 的资源和输入
@@ -140,34 +140,34 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
### 7.3 对对端和身份
- 被攻破的 Probe 只能拿到 Backend 授权的会话，Agent 的速率上限由本地兜底；被攻破的 Agent 发来的数据只会影响它自己的线路。
- Probe 只拨公网地址（G3）：固定 SPKI 只能防止建立会话，防不了探测本身；要在 Probe 本地拒绝私网、回环、链路本地地址。
- 被攻破的 拨号方 只能拿到 Backend 授权的会话，Agent 的速率上限由本地兜底；被攻破的 Agent 发来的数据只会影响它自己的线路。
- 拨号方 只拨公网地址（G3）：固定 SPKI 只能防止建立会话，防不了探测本身；要在 拨号方 本地拒绝私网、回环、链路本地地址。
- 名册里的主机名解析之后再检查地址：签名保护的是字符串，不是解析结果；默认只放行公网地址，内网需要节点本地显式允许。
- QUIC 会话迁移要做路径验证：协议允许会话在 NAT 映射变化后跟随新的源地址，路径上的攻击者可以借此把会话牵到自己的地址。迁移前先做一次挑战应答，验证前限制发送量（不超过收到字节数的 3 倍），由 QUIC path validation 提供。
- 不协商、不降级：现在固定 ECDSA P-256 和固定的签名串格式，没有算法协商，保持这一点。
- Agent 的 `max_total_mbps` 默认是 1200，对 1 核 1 GB 的小机器没有意义，却是被攻破的 Backend 能让 Agent 向某个 Probe 打出去的上限。默认值应该保守，需要的人再调高；`allowed_target_cidrs` 默认为空是对的。
- Agent 的 `max_total_mbps` 默认是 1200，对 1 核 1 GB 的小机器没有意义，却是被攻破的 Backend 能让 Agent 向某个 拨号方 打出去的上限。默认值应该保守，需要的人再调高；`allowed_target_cidrs` 默认为空是对的。
## 8. 监听隐身：预握手敲门
目标：Agent 的 TCP 端口对没有完成挑战的人不写出任何字节，包括 TLS 的 ServerHello，扫描器拿不到证书和 TLS 指纹（G4）。UDP 端口本来就是静默的。
```text
Probe Agent TCP 7443 / 7444
拨号方 Agent TCP 7443 / 7444
│── TCP 连接 ───────────────────────────────────▶ accept（内核已完成三次握手）
│── 敲门包 32 字节：nonce(16) │ tag(16) ─────────▶ 读 32 字节（限时 3 秒）
│ tag = HMAC(K_pair, 时间窗 ‖ nonce) 用名册里每个 Probe 的 K_pair 逐个核对
│ tag = HMAC(K_pair, 时间窗 ‖ nonce) 用名册里每个 拨号方 的 K_pair 逐个核对
│ ├ 合法：继续 TLS 握手 → 现有的签名认证
│◀──────────── TLS ServerHello ─────────────────── └ 不合法或超时：什么都不发，直接断开
```
- `K_pair = HKDF(ECDH(Probe 身份私钥, Agent 身份公钥), "moshiro-knock-v1")`：只有名册里的成员算得出；时间窗 30 秒，接受前后各一个窗；`nonce` 在窗内去重，防重放；每个来源地址限速（默认每来源每 10 秒 300 次）。
- 实现：`Fleet.Identity.Knock`（构造与核对）和 `KnockGate`（读 32 字节、名册、nonce 去重、按来源限速）；控制端口（`PeerListener`）和数据端口（`TcpAcceptor`）共用同一个关卡，Probe 一侧 `PeerConnector` 和 `TcpLink` 在 TCP 连接建立后、TLS 之前发敲门包。名册是期望状态里的 `peers`（Probe 的对等面公钥）；`probe_agents` 下发的是 Agent 的 `public_key`（Agent 在 hello 里上报）。陌生连接得到的是被关闭的连接，没有任何字节。
- `K_pair = HKDF(ECDH(拨号方 身份私钥, Agent 身份公钥), "moshiro-knock-v1")`：只有名册里的成员算得出；时间窗 30 秒，接受前后各一个窗；`nonce` 在窗内去重，防重放；每个来源地址限速（默认每来源每 10 秒 300 次）。
- 实现：`Fleet.Identity.Knock`（构造与核对）和 `KnockGate`（读 32 字节、名册、nonce 去重、按来源限速）；控制端口（`PeerListener`）和数据端口（`TcpAcceptor`）共用同一个关卡，拨号方 一侧 `PeerConnector` 和 `TcpLink` 在 TCP 连接建立后、TLS 之前发敲门包。名册是期望状态里的 `peers`（拨号方 的对等面公钥）；`dial_targets` 下发的是 Agent 的 `public_key`（Agent 在 hello 里上报）。陌生连接得到的是被关闭的连接，没有任何字节。
局限：TCP 的 SYN-ACK 由内核发出，用户态进程拦不住，所以端口在扫描器眼里仍是「开着，但不说话」，不是「没监听」。真正的没监听有两条路：等级二的 UDP 单包授权（Probe 先发签名的 UDP 敲门包，Agent 才临时开 TCP 监听几秒，只放行敲门者的源地址；代价是多一个往返、UDP 丢包重试、多出口源地址可能对不上），或宿主防火墙规则（需要 root，不适合小机器，不做）。先做等级一，等级二可选。
局限：TCP 的 SYN-ACK 由内核发出，用户态进程拦不住，所以端口在扫描器眼里仍是「开着，但不说话」，不是「没监听」。真正的没监听有两条路：等级二的 UDP 单包授权（拨号方 先发签名的 UDP 敲门包，Agent 才临时开 TCP 监听几秒，只放行敲门者的源地址；代价是多一个往返、UDP 丢包重试、多出口源地址可能对不上），或宿主防火墙规则（需要 root，不适合小机器，不做）。先做等级一，等级二可选。
## 9. extension：敏感能力的归宿
当前 Agent 和 Probe 的核心只包含测量与上报。敏感能力（exec、web ssh 和终端、文件读写、抓包等）计划做成 extension，由用户选择安装，默认不启用，目前都没有实现。
当前 Agent 的核心只包含测量与上报。敏感能力（exec、web ssh 和终端、文件读写、抓包等）计划做成 extension，由用户选择安装，默认不启用，目前都没有实现。
- 独立进程：单独的二进制和镜像，和核心之间没有进程内接口，核心不加载外部代码、不用反射和动态加载，核心的 NativeAOT 和构建期限制不受影响。
- 授权只认节点的属主：每次调用的能力令牌必须由这个节点绑定的属主 passkey 签名，账户角色不赋予权力；管理员只能删除节点或卸载 extension。交互式会话端到端加密，Backend 只转发密文。属主和会话密钥的设计见 [access.md](access.md) 第 9 节。
@@ -187,7 +187,7 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
| 令牌哈希、SPKI 指纹 | SHA-256 |
| 原始块完整性 | CRC32C，不是密码学校验 |
BLAKE3 的评估（已定：不采用）：ECDSA P-256 本身用 SHA-256，令牌哈希和 SPKI 指纹也继续用 SHA-256，所以 BLAKE3 是多一个哈希族，不是换掉一个；BCL 里没有，Probe 和 Agent 不引用 NuGet 包，只能自己实现几百行的便携版本加官方测试向量，这是要长期维护的密码学代码；托管实现没有 SHA-NI 加速，在 x86 上未必更快。若以后在目标硬件上实测发现逐包 MAC 是瓶颈，再单独评估，届时只替换 `Fleet.Identity` 里 `Mac` 和 `Kdf` 两个静态函数，调用方不动。
BLAKE3 的评估（已定：不采用）：ECDSA P-256 本身用 SHA-256，令牌哈希和 SPKI 指纹也继续用 SHA-256，所以 BLAKE3 是多一个哈希族，不是换掉一个；BCL 里没有，Agent 不引用 NuGet 包，只能自己实现几百行的便携版本加官方测试向量，这是要长期维护的密码学代码；托管实现没有 SHA-NI 加速，在 x86 上未必更快。若以后在目标硬件上实测发现逐包 MAC 是瓶颈，再单独评估，届时只替换 `Fleet.Identity` 里 `Mac` 和 `Kdf` 两个静态函数，调用方不动。
## 11. 还没定的事