docs: rewrite README and AGENTS.md etc..
This commit is contained in:
justme committed
1 parent
cc64df3e70
commit
a9bf849697
22 files changed
+514
-665
No files matched your search
+45
-45
@@ -1,8 +1,8 @@
|
||||
# 访问控制与入网信任链
|
||||
|
||||
这份文档讲**谁能做什么**（账户、能力、API key）和**谁能让节点入网**（passkey 到节点的信任根）。它是 [security.md](security.md) 的展开：security.md 讲缺口和威胁，这里讲现在怎么做。以已实现的为主，没做的在最后一节列出。
|
||||
这份文档讲谁能做什么（账户、能力、API key）和谁能让节点入网（passkey 到节点的信任根）。它是 [security.md](security.md) 的展开：security.md 讲缺口和威胁，这里讲现在怎么做。以已实现的为主，没做的在最后一节列出。
|
||||
|
||||
一句话：登录和授权分开。登录证明「你是谁」，授权只看能力；改变信任（操作员集合）只认 passkey 的签名，并且这个签名由**节点自己验证**，Backend 只搬运，伪造不了。
|
||||
概要：登录和授权分开。登录证明「你是谁」，授权只看能力；改变信任（操作员集合）只认 passkey 的签名，并且这个签名由节点自己验证，Backend 只搬运，伪造不了。
|
||||
|
||||
## 1. 总览
|
||||
|
||||
@@ -30,7 +30,7 @@
|
||||
|
||||
没有采用「成员证明」（每个节点一条 Grant、Ticket、Binding 的入网链）：被攻破的 Backend 往名册里塞节点，拿不到比 Backend 已经有的更多的东西（监测数据本来就是明文给 Backend 的；敏感的 extension 靠节点属主，不靠名册），成本却是每个节点一次触碰和一套证明格式。操作员集合和创世固定已经在，以后要叠加不用重装节点。
|
||||
|
||||
**发布密钥可以换**：见 [deployment.md](../ops/deployment.md) 的「换发布密钥」；回滚由清单的 `seq` 防住（更新器只收比已安装更大的）。面板信任哪些发布密钥（官方的，加上可选的自有公钥）在管理端「系统 → 信任 → 可信资产来源」。
|
||||
发布密钥可以换：见 [deployment.md](../ops/deployment.md) 的「换发布密钥」；回滚由清单的 `seq` 防住（更新器只收比已安装更大的）。面板信任哪些发布密钥（官方的，加上可选的自有公钥）在管理端「系统 → 信任 → 可信资产来源」。
|
||||
|
||||
## 2. 名词
|
||||
|
||||
@@ -61,11 +61,11 @@
|
||||
| 运维 | `events.read` · `audit.read` · `ops.metrics` | 事件；审计日志；`/metrics` | |
|
||||
| 集成（预留） | `data.export` · `webhooks.read` · `webhooks.manage` | 批量拉数据、外部回调订阅，见第 6.4 节 | |
|
||||
|
||||
- **一个能力只在一个地方声明**：`Capability` 常量（`MoShiro.Backend.Application`），端点用 `.Requires(Capability.X)`；`Principal.Has(capability)` 是唯一的判断入口，会话和 API key 都走它。写蕴含读（`fleet.write` 带 `fleet.read`）。
|
||||
- **对账测试**：所有 `/api/admin` 端点必须声明能力，没声明测试就失败；OpenAPI 的每个操作带 `x-moshiro-capability`。
|
||||
- **信任类**是界面上特别标出的（吊销、账户管理），授权和其他能力一样靠 API key 或会话。真正由 passkey 签名保护的是操作员集合，那是节点自己验证的。
|
||||
- **不能越权**：创建 API key 时勾选的能力必须是创建者当前拥有能力的子集。
|
||||
- **Backend 更新确认**：更新清单由 CI 的发布密钥签名（面板登记时验签），`seq` 防重放；确认只是让 Backend 有序退出并备份数据库，拉哪个镜像由 Quadlet 单元里写死的仓库和标签决定，面板决定不了。
|
||||
- 一个能力只在一个地方声明：`Capability` 常量（`MoShiro.Backend.Application`），端点用 `.Requires(Capability.X)`；`Principal.Has(capability)` 是唯一的判断入口，会话和 API key 都走它。写蕴含读（`fleet.write` 带 `fleet.read`）。
|
||||
- 对账测试：所有 `/api/admin` 端点必须声明能力，没声明测试就失败；OpenAPI 的每个操作带 `x-moshiro-capability`。
|
||||
- 信任类是界面上特别标出的（吊销、账户管理），授权和其他能力一样靠 API key 或会话。真正由 passkey 签名保护的是操作员集合，那是节点自己验证的。
|
||||
- 不能越权：创建 API key 时勾选的能力必须是创建者当前拥有能力的子集。
|
||||
- Backend 更新确认：更新清单由 CI 的发布密钥签名（面板登记时验签），`seq` 防重放；确认只是让 Backend 有序退出并备份数据库，拉哪个镜像由 Quadlet 单元里写死的仓库和标签决定，面板决定不了。
|
||||
|
||||
## 4. 登录与会话
|
||||
|
||||
@@ -74,8 +74,8 @@
|
||||
| 密码 | PBKDF2；认领向导创建第一个管理员时设置 |
|
||||
| passkey | WebAuthn，只支持 ES256，attestation 一律当 `none`；可以登录，也能给操作员集合签名（节点验证） |
|
||||
|
||||
- 两种方式的会话拿**同样的能力**。passkey 不是 Backend 用来拦操作的一道门，只用在节点自己会验证的事上，见第 5 节。
|
||||
- **认领向导（没有默认账户）**：面板里还没有任何用户时，打开 `/admin/` 进向导——用后端日志里的认领码（或 `MoShiro__ClaimCode`）创建第一个管理员（用户名和密码自己填），注册第一个 passkey，再用它给操作员集合签名建立信任根。谁先打开页面谁就能当管理员，所以要认领码；创建完码作废、入口关闭（`POST /api/admin/auth/setup` 之后返回 409）。后两步是引导不是门槛，可以稍后补；不注册 passkey、不建立信任根，就添加不了 Agent 和 Probe，只能进面板做基础管理，这是架构如此。之后新增的 passkey 不会自动成为操作员：要由现有操作员在信任页看清「新增了哪些」再签新版本，节点才认。
|
||||
- 两种方式的会话拿同样的能力。passkey 不是 Backend 用来拦操作的一道门，只用在节点自己会验证的事上，见第 5 节。
|
||||
- 认领向导（没有默认账户）：面板里还没有任何用户时，打开 `/admin/` 进向导——用后端日志里的认领码（或 `MoShiro__ClaimCode`）创建第一个管理员（用户名和密码自己填），注册第一个 passkey，再用它给操作员集合签名建立信任根。谁先打开页面谁就能当管理员，所以要认领码；创建完码作废、入口关闭（`POST /api/admin/auth/setup` 之后返回 409）。后两步是引导不是门槛，可以稍后补；不注册 passkey、不建立信任根，就添加不了 Agent 和 Probe，只能进面板做基础管理，这是架构如此。之后新增的 passkey 不会自动成为操作员：要由现有操作员在信任页看清「新增了哪些」再签新版本，节点才认。
|
||||
- 建议每个账户至少注册两个 passkey（手机加硬件密钥）。
|
||||
|
||||
### 4.1 passkey 登录的实现
|
||||
@@ -83,23 +83,23 @@
|
||||
- 流程：登录页「使用 Passkey 登录」→ `POST /api/admin/auth/passkey/options` 取挑战 → 浏览器 `navigator.credentials.get`（可发现凭证，不用输用户名）→ `POST /api/admin/auth/passkey/login` 提交断言 → 建立会话（Cookie，或跨域前端用 `return_session`）。注册：已登录用户在「系统 → 用户 → 我的 Passkey」添加，`POST /api/admin/auth/passkeys/options` 加 `POST /api/admin/auth/passkeys`；每个用户最多 10 个。
|
||||
- 校验：挑战在内存里，一次有效、5 分钟过期，并且区分注册和登录、绑定用户；`rpIdHash`、UP 和 UV 标志、`clientDataJSON` 的 type、challenge、origin、ES256 签名；签名计数器只增不减（两边都是 0 的同步型 passkey 不检查）。登录失败一律 401，不区分原因，和密码登录共用限流。
|
||||
- 验证断言的纯函数是 `Fleet.Identity.WebAuthnAssertion`（只用 BCL，节点验证操作员集合也用它）；注册里的 CBOR 和 attestation 解析在 Backend（`WebAuthnRegistration`），节点不带 CBOR。
|
||||
- 依赖方（RP）：`MoShiro__WebAuthnRpId`（缺省取 `PublicUrl` 的主机，没有就取请求的主机）和 `MoShiro__WebAuthnOrigins`（缺省取 `PublicUrl` 的来源）。**passkey 绑定在这个域名上，改了会让已注册的 passkey 失效。**只有和后端同站的页面能用 passkey 登录，管理端在「添加其他后端」（跨域）时不显示这个入口。
|
||||
- 依赖方（RP）：`MoShiro__WebAuthnRpId`（缺省取 `PublicUrl` 的主机，没有就取请求的主机）和 `MoShiro__WebAuthnOrigins`（缺省取 `PublicUrl` 的来源）。passkey 绑定在这个域名上，改了会让已注册的 passkey 失效。只有和后端同站的页面能用 passkey 登录，管理端在「添加其他后端」（跨域）时不显示这个入口。
|
||||
- 会话记录登录方式（`password` 或 `passkey`），只用于审计和显示；API key 不是用户，不能注册 passkey。
|
||||
- 测试：`SoftwarePasskey` 在测试里模拟认证器走完整的注册和登录，覆盖错误的挑战、来源、RP、签名、缺少 UV、挑战重放、计数器回退、只能管理自己的 passkey。
|
||||
|
||||
## 5. passkey 用在哪里（没有提权窗口）
|
||||
|
||||
原则：**passkey 不是 Backend 用来拦操作的一道门**（Backend 被攻破时，它自己做的拦截也会被一起绕过），而是节点或密钥持有者需要它才能验证、解密的东西。
|
||||
原则：passkey 不是 Backend 用来拦操作的一道门（Backend 被攻破时，它自己做的拦截也会被一起绕过），而是节点或密钥持有者需要它才能验证、解密的东西。
|
||||
|
||||
| 事 | 谁验证 | 要 passkey |
|
||||
| --- | --- | --- |
|
||||
| 建立、更新操作员集合（信任根） | **节点**验链 | 是（现在唯一做了的） |
|
||||
| extension 会话（web ssh 等） | **节点**验 passkey 签名的临时密钥 | 是（还没做） |
|
||||
| 建立、更新操作员集合（信任根） | 节点验链 | 是（现在唯一做了的） |
|
||||
| extension 会话（web ssh 等） | 节点验 passkey 签名的临时密钥 | 是（还没做） |
|
||||
| 读加密存储的数据 | 私钥持有者 | 是（还没做） |
|
||||
| 吊销或删除节点、账号、API key、加入码、设置 | 只有 Backend | 否，只看能力 |
|
||||
|
||||
- 这些「只有 Backend」的事靠能力限权：API key 只带需要的能力。密码泄露的后果是这些能力被滥用，改不了信任根，也用不了以后的 extension。
|
||||
- 唯一的风险是往账号里塞一把 passkey 再等人签名：信任页的提案会列出**新增和移除的凭证**，签名之前要看一眼是不是自己加的；签了才算授权。
|
||||
- 唯一的风险是往账号里塞一把 passkey 再等人签名：信任页的提案会列出新增和移除的凭证，签名之前要看一眼是不是自己加的；签了才算授权。
|
||||
|
||||
## 6. API key
|
||||
|
||||
@@ -117,7 +117,7 @@ CI 把签名清单 POST 给 `POST /api/release/offer`，面板用发布公钥验
|
||||
|
||||
### 6.3 预留：外部 webhook 回调与数据拉取
|
||||
|
||||
后面要让外部系统能订阅事件、触发回调、拉数据。接口和权限先留（`data.export`、`webhooks.*` 标预留），实现放后面；全部发生在 Backend 里，**节点零开销**。订阅只能订阅创建者自己读得到的事件；投递是带 HMAC 签名的 `POST`，至少一次、指数退避；目标 URL 要做 SSRF 限制（只放行公网地址，不跟随重定向到内网，有超时和大小上限）。这些都属于 Backend 的集成配置，不改变节点信任，但每次增删订阅都进审计。
|
||||
后面要让外部系统能订阅事件、触发回调、拉数据。接口和权限先留（`data.export`、`webhooks.*` 标预留），实现放后面；全部发生在 Backend 里，节点零开销。订阅只能订阅创建者自己读得到的事件；投递是带 HMAC 签名的 `POST`，至少一次、指数退避；目标 URL 要做 SSRF 限制（只放行公网地址，不跟随重定向到内网，有超时和大小上限）。这些都属于 Backend 的集成配置，不改变节点信任，但每次增删订阅都进审计。
|
||||
|
||||
## 7. 归属与审计
|
||||
|
||||
@@ -127,40 +127,40 @@ CI 把签名清单 POST 给 `POST /api/release/offer`，面板用发布公钥验
|
||||
## 8. 入网信任链的实现要点
|
||||
|
||||
- 语句是 `key=value` 文本，第一行是带版本的标题，签名覆盖整段文本；WebAuthn 的挑战是语句的 SHA-256。库在 `Fleet.Identity` 的 `OperatorTrust`（操作员集合的编码、解析、链验证）和 `SecureChannel`（服务器证明和链路加密），都是只用 BCL 的纯函数，节点和 Backend 共用。
|
||||
- **创世**：第一次建立信任根时，把账号下所有 passkey 和这个面板的服务器密钥登记成一个操作员集合，passkey 对它签名；创世语句的 SHA-256 就是命令里的 `MOSHIRO_GENESIS`。之后加删 passkey 或换服务器密钥要签新版本（上一版里的凭证签），页面会提示；签名更新不会让节点重装。
|
||||
- **操作员集合版本**随期望状态（`trust_chain`）下发，节点从固定的创世验起，版本比现有的新才采用并保存。
|
||||
- **节点注册**：`fleet-enroll --genesis … --controllers …`：先 `POST /api/agent/v1/enroll/trust` 取链，验过（创世指纹、签名、属主在集合里）才把密钥交出去；之后写 `trust.json`。没有命令里的指纹（`--genesis`）就不固定，节点按旧方式工作。
|
||||
- **服务器身份和安全链路**：`ChallengeParams` 带服务器的临时公钥和签名（`server_eph`、`server_sig`），`AuthParams` 带节点的临时公钥（`node_eph`），节点签名的用途是 `auth2`，覆盖双方的临时公钥；通过后两边用 HKDF 派生每个方向一把 AES-256-GCM 密钥，每帧 `计数器(8) ‖ 密文 ‖ 标签(16)`，计数器严格递增，明文帧、改动、重放、乱序一律断开。集合里没有服务器密钥的节点（旧节点）保持明文，不会被降级成放行。
|
||||
- **服务器密钥**存在 Backend 的设置里（`server.identity_key`）：它防的是面板被冒充，不是面板被攻破；面板被攻破时它也泄露，那时要由 passkey 签一个换掉它的新集合版本。集合里没有这个面板的服务器密钥的版本，Backend 不收（否则固定了它的节点就认不出这个面板了）。
|
||||
- **弱点**：创世指纹放在安装命令里，命令本身要从可信渠道拿到（管理端复制）。缓解见第 10 节（静态签名脚本、按 digest 拉镜像），并在信任页展示指纹供核对。
|
||||
- 创世：第一次建立信任根时，把账号下所有 passkey 和这个面板的服务器密钥登记成一个操作员集合，passkey 对它签名；创世语句的 SHA-256 就是命令里的 `MOSHIRO_GENESIS`。之后加删 passkey 或换服务器密钥要签新版本（上一版里的凭证签），页面会提示；签名更新不会让节点重装。
|
||||
- 操作员集合版本随期望状态（`trust_chain`）下发，节点从固定的创世验起，版本比现有的新才采用并保存。
|
||||
- 节点注册：`fleet-enroll --genesis … --controllers …`：先 `POST /api/agent/v1/enroll/trust` 取链，验过（创世指纹、签名、属主在集合里）才把密钥交出去；之后写 `trust.json`。没有命令里的指纹（`--genesis`）就不固定，节点按旧方式工作。
|
||||
- 服务器身份和安全链路：`ChallengeParams` 带服务器的临时公钥和签名（`server_eph`、`server_sig`），`AuthParams` 带节点的临时公钥（`node_eph`），节点签名的用途是 `auth2`，覆盖双方的临时公钥；通过后两边用 HKDF 派生每个方向一把 AES-256-GCM 密钥，每帧 `计数器(8) ‖ 密文 ‖ 标签(16)`，计数器严格递增，明文帧、改动、重放、乱序一律断开。集合里没有服务器密钥的节点（旧节点）保持明文，不会被降级成放行。
|
||||
- 服务器密钥存在 Backend 的设置里（`server.identity_key`）：它防的是面板被冒充，不是面板被攻破；面板被攻破时它也泄露，那时要由 passkey 签一个换掉它的新集合版本。集合里没有这个面板的服务器密钥的版本，Backend 不收（否则固定了它的节点就认不出这个面板了）。
|
||||
- 弱点：创世指纹放在安装命令里，命令本身要从可信渠道拿到（管理端复制）。缓解见第 10 节（静态签名脚本、按 digest 拉镜像），并在信任页展示指纹供核对。
|
||||
|
||||
## 9. 节点属主与 extension 授权
|
||||
|
||||
extension（web ssh、文件、抓包，见 [security.md](security.md)）**现在都不实现**，Agent 和 Probe 一样。这类能力连管理员都不信任：管理员能删，不能读，也不能用。所以入网时就给每个节点固定「属主」，之后不用重装节点。
|
||||
extension（web ssh、文件、抓包，见 [security.md](security.md)）现在都不实现，Agent 和 Probe 一样。这类能力连管理员都不信任：管理员能删，不能读，也不能用。所以入网时就给每个节点固定「属主」，之后不用重装节点。
|
||||
|
||||
**已经实现的部分**
|
||||
已经实现的部分
|
||||
|
||||
- 属主 `controllers` 是一组 passkey 凭证 id，必须是操作员集合里的凭证。由安装命令带来，节点注册时写进 `trust.json`，Backend 之后改不了。
|
||||
- **每个 Agent 和 Probe 都必须有属主，至少一把——而且这是节点自己的要求，不是 Backend 的要求**：节点启动时检查本地固定的属主，没有（或者属主的 passkey 已经不在操作员集合里）就不运行（共用 `Fleet.Hosting` 里的 `OwnerGuard`；配置 `fleet.require_owner`，`MOSHIRO_ALLOW_NO_OWNER=1` 放行）。面板被攻破也改不了。
|
||||
- **添加节点时选属主**：`POST /api/admin/join-tokens` 的 `controllers: [credential_id…]`，不给就是操作员集合里的全部凭证；给了就必须非空且都在集合里。还没有信任根或一把属主都没有时，面板**提前拒绝**创建加入码（400，字段 `controllers`），这只是尽早失败，真正的强制在节点；`MoShiro__RequireOwner=false` 可以关掉这个提前检查（只给没有信任根的老部署）。界面里是必选的「属主（passkey）」多选列表，只是选，不用触碰。
|
||||
- **安装端也强制**：`install.sh`、`install.ps1`、容器入口缺了 `MOSHIRO_GENESIS` 或 `MOSHIRO_CONTROLLERS` 就不装；`fleet-enroll --genesis` 不带 `--controllers` 也拒绝。
|
||||
- **逆推出绑定关系**：节点握手时把本地固定的属主（passkey 凭证 id）报给面板（hello 的 `owners`），面板顺着凭证 id 反查出它绑定在**哪个账户的哪把 passkey** 上，显示在「系统 → 版本」的「属主」列（对不上任何已注册 passkey 的显示「未知凭证」）。上报只是自述，真正的授权由节点自己校验 passkey 签名。
|
||||
- 每个 Agent 和 Probe 都必须有属主，至少一把——而且这是节点自己的要求，不是 Backend 的要求：节点启动时检查本地固定的属主，没有（或者属主的 passkey 已经不在操作员集合里）就不运行（共用 `Fleet.Hosting` 里的 `OwnerGuard`；配置 `fleet.require_owner`，`MOSHIRO_ALLOW_NO_OWNER=1` 放行）。面板被攻破也改不了。
|
||||
- 添加节点时选属主：`POST /api/admin/join-tokens` 的 `controllers: [credential_id…]`，不给就是操作员集合里的全部凭证；给了就必须非空且都在集合里。还没有信任根或一把属主都没有时，面板提前拒绝创建加入码（400，字段 `controllers`），这只是尽早失败，真正的强制在节点；`MoShiro__RequireOwner=false` 可以关掉这个提前检查（只给没有信任根的老部署）。界面里是必选的「属主（passkey）」多选列表，只是选，不用触碰。
|
||||
- 安装端也强制：`install.sh`、`install.ps1`、容器入口缺了 `MOSHIRO_GENESIS` 或 `MOSHIRO_CONTROLLERS` 就不装；`fleet-enroll --genesis` 不带 `--controllers` 也拒绝。
|
||||
- 逆推出绑定关系：节点握手时把本地固定的属主（passkey 凭证 id）报给面板（hello 的 `owners`），面板顺着凭证 id 反查出它绑定在哪个账户的哪把 passkey 上，显示在「系统 → 版本」的「属主」列（对不上任何已注册 passkey 的显示「未知凭证」）。上报只是自述，真正的授权由节点自己校验 passkey 签名。
|
||||
|
||||
**预留的设计（还没做）**
|
||||
预留的设计（还没做）
|
||||
|
||||
- **谁来强制：节点本地，不是 Backend。** web ssh 这类会话要不要加密、要不要验证，由 Agent 和 Probe 自己要求。让 Backend 决定，被攻破的 Backend 一句「这次不用加密」就绕过去了。节点本地强制：没有操作员的现场证明不启动会话；会话密钥只和证明里的那把密钥协商，不和 Backend 转来的公钥协商；加密字段缺失就拒绝，不降级；能开哪些 extension、哪些 passkey 能授权，只看本节点属主。
|
||||
- **证明的方向是反的**：节点先出题（nonce 加它的临时公钥，用节点身份密钥签名），属主的浏览器把 nonce 和自己的临时公钥放进 passkey 断言的挑战里；节点验断言来自本节点属主、要求用户验证、nonce 是自己刚出的且没用过。Backend 仍然管谁有资格发起请求、审计、限流、转发密文。
|
||||
- **交互式会话**（终端、ssh）用现场签名的临时 ECDH 密钥协商，passkey 只签名授权，不参与解密，所以不支持 PRF 的 passkey 也能用，还有前向保密；之后双向是带序号的 AEAD。**静态数据**（抓包文件、会话录像）需要事后解密，才用属主记录里的接收者公钥加密（来自 WebAuthn PRF 或浏览器里不可导出的密钥）。
|
||||
- **删除和使用分开**：admin 能删节点、卸载 extension，读不到也用不了。改属主要现有属主的 passkey 签名（`ControllerUpdate`），账户被删、角色被改都改不了某个节点的属主。属主是 passkey 凭证，不是账户；一个人丢了全部属主 passkey，这个节点上的 extension 就没人能用了，所以添加时建议绑两把以上。
|
||||
- **数据边界**：监测数据（延迟、丢包、吞吐、事件、主机资源汇总）是明文，Backend 要做分析和展示；extension 会话和原始 payload 端到端加密，Backend 只存转发密文。读取权不是能力，是私钥。
|
||||
- 谁来强制：节点本地，不是 Backend。 web ssh 这类会话要不要加密、要不要验证，由 Agent 和 Probe 自己要求。让 Backend 决定，被攻破的 Backend 一句「这次不用加密」就绕过去了。节点本地强制：没有操作员的现场证明不启动会话；会话密钥只和证明里的那把密钥协商，不和 Backend 转来的公钥协商；加密字段缺失就拒绝，不降级；能开哪些 extension、哪些 passkey 能授权，只看本节点属主。
|
||||
- 证明的方向是反的：节点先出题（nonce 加它的临时公钥，用节点身份密钥签名），属主的浏览器把 nonce 和自己的临时公钥放进 passkey 断言的挑战里；节点验断言来自本节点属主、要求用户验证、nonce 是自己刚出的且没用过。Backend 仍然管谁有资格发起请求、审计、限流、转发密文。
|
||||
- 交互式会话（终端、ssh）用现场签名的临时 ECDH 密钥协商，passkey 只签名授权，不参与解密，所以不支持 PRF 的 passkey 也能用，还有前向保密；之后双向是带序号的 AEAD。静态数据（抓包文件、会话录像）需要事后解密，才用属主记录里的接收者公钥加密（来自 WebAuthn PRF 或浏览器里不可导出的密钥）。
|
||||
- 删除和使用分开：admin 能删节点、卸载 extension，读不到也用不了。改属主要现有属主的 passkey 签名（`ControllerUpdate`），账户被删、角色被改都改不了某个节点的属主。属主是 passkey 凭证，不是账户；一个人丢了全部属主 passkey，这个节点上的 extension 就没人能用了，所以添加时建议绑两把以上。
|
||||
- 数据边界：监测数据（延迟、丢包、吞吐、事件、主机资源汇总）是明文，Backend 要做分析和展示；extension 会话和原始 payload 端到端加密，Backend 只存转发密文。读取权不是能力，是私钥。
|
||||
|
||||
## 10. 安装的供应链
|
||||
|
||||
一行安装要执行 Backend 吐出的脚本、拉仓库里的镜像。Backend 或仓库被攻破，就能在新节点上执行任意命令。收束办法，**优先级最高的是第一跳的哈希核对**：
|
||||
一行安装要执行 Backend 吐出的脚本、拉仓库里的镜像。Backend 或仓库被攻破，就能在新节点上执行任意命令。收束办法，优先级最高的是第一跳的哈希核对：
|
||||
|
||||
**① 脚本是静态产物，哈希固定**
|
||||
① 脚本是静态产物，哈希固定
|
||||
|
||||
- 不在服务端做字符串替换。CI 构建时算出 `install.sh`、`install.ps1` 的 SHA-256，写进发布清单（发布密钥签名），同时公布在 Gitea 发布页——**这条渠道独立于 Backend**，这是哈希核对有意义的前提：哈希若和脚本从同一处来，攻击者两个一起换就行。
|
||||
- 不在服务端做字符串替换。CI 构建时算出 `install.sh`、`install.ps1` 的 SHA-256，写进发布清单（发布密钥签名），同时公布在 Gitea 发布页——这条渠道独立于 Backend，这是哈希核对有意义的前提：哈希若和脚本从同一处来，攻击者两个一起换就行。
|
||||
- 参数（代码、面板地址）通过命令行环境变量传入，代码因此不出现在 URL 和反向代理日志里。
|
||||
- 管理端给的命令把「下载、核对、执行」合成一行，哈希核对不通过就不执行：
|
||||
|
||||
@@ -170,28 +170,28 @@ f=$(mktemp) && curl -fsSL https://panel/install -o "$f" && echo "<sha256> $f" |
|
||||
|
||||
macOS 用 `shasum -a 256 -c`，Windows 用 `Get-FileHash` 比较，不通过就 `throw`。命令里的 `<sha256>` 由 Backend 填入，信任页同时标出它与 CI 签名的发布清单是否一致；严格的人对照 Gitea 发布页一次即可（脚本是静态的，哈希在一个版本内不变）。
|
||||
|
||||
**② 镜像按 digest 拉取**
|
||||
② 镜像按 digest 拉取
|
||||
|
||||
- 脚本向面板取已签名的清单（和更新用的是同一份，发布密钥签名、`seq` 防回滚），用**脚本里内置的发布公钥**验签，再按清单里的 digest 拉镜像（`repo@sha256:…`）。Backend 改不了 digest，最多让节点装到一个旧的合法版本。
|
||||
- 脚本向面板取已签名的清单（和更新用的是同一份，发布密钥签名、`seq` 防回滚），用脚本里内置的发布公钥验签，再按清单里的 digest 拉镜像（`repo@sha256:…`）。Backend 改不了 digest，最多让节点装到一个旧的合法版本。
|
||||
- 下载压缩包安装的人，用 Release 里签名的 `SHA256SUMS` 核对（见 [deployment.md](../ops/deployment.md)）。
|
||||
|
||||
**③ 容器安装：Podman 系用 Quadlet（默认），Docker 用 compose**
|
||||
③ 容器安装：Podman 系用 Quadlet（默认），Docker 用 compose
|
||||
|
||||
- 管理端的容器安装是：建目录，把参数写进本地 `.env`（面板地址、一次性码、创世指纹、属主，都是公开的值），下载面板提供的静态 compose 文件、核对 SHA-256，`compose up -d`。compose 文件是静态的（和安装脚本一样嵌在 Backend 里，也作为 Release 资产发布），镜像是 `:latest` 或 `.env` 里固定的版本，**镜像地址由 CI 渠道决定，不由面板决定**，面板被攻破也改不了；Backend 第一次部署时没有面板，就从 Release 资产下载。
|
||||
- 管理端的容器安装是：建目录，把参数写进本地 `.env`（面板地址、一次性码、创世指纹、属主，都是公开的值），下载面板提供的静态 compose 文件、核对 SHA-256，`compose up -d`。compose 文件是静态的（和安装脚本一样嵌在 Backend 里，也作为 Release 资产发布），镜像是 `:latest` 或 `.env` 里固定的版本，镜像地址由 CI 渠道决定，不由面板决定，面板被攻破也改不了；Backend 第一次部署时没有面板，就从 Release 资产下载。
|
||||
- 代价：客户端不再验发布签名，更新（`compose pull && compose up -d`）靠 TLS 加「注册表可信」这个假设；想要更严，在 `.env` 里把 `MOSHIRO_VERSION` 固定到 digest，或者用宿主机更新器（清单有发布签名，不健康自动回滚）。详见 [deployment.md](../ops/deployment.md)。
|
||||
|
||||
**④ 其余**
|
||||
④ 其余
|
||||
|
||||
- 角色（Agent 还是 Probe）、镜像仓库地址仍由代码决定，但镜像身份由签名清单决定。
|
||||
- macOS 的 Developer ID 签名和公证、Windows 的 Authenticode 需要证书，目前没有做。
|
||||
|
||||
## 11. 运行中的二进制不做校验
|
||||
|
||||
曾经做过「节点二进制绑定」：节点握手时自报正在运行的二进制的 SHA-256，Backend 在第一次握手时绑定，之后对不上就标红或拒绝。**已经移除。**
|
||||
曾经做过「节点二进制绑定」：节点握手时自报正在运行的二进制的 SHA-256，Backend 在第一次握手时绑定，之后对不上就标红或拒绝。已经移除。
|
||||
|
||||
原因：哈希和清单都是节点自己报的。一个被换进来、故意撒谎的二进制可以照抄原来的哈希和清单，Backend 分辨不出——上报者就是被怀疑的对象。这一层只能抓到「文件被换了、但程序本身没撒谎」的情形，却让人误以为有保障，还要求运维宿主机更新器、状态卷和每个节点的清单。得不偿失。
|
||||
|
||||
「这个资产是我们的」靠**安装时的来源证明**，那里的哈希来自另一个信道，伪造不了：
|
||||
「这个资产是我们的」靠安装时的来源证明，那里的哈希来自另一个信道，伪造不了：
|
||||
|
||||
- 安装脚本（SHA-256 记在签名的清单里，并公布在发布页），按清单里的 digest 拉镜像（`repo@sha256:…`）；
|
||||
- 下载压缩包的人用签名的 `SHA256SUMS` 核对（验签用 `packaging/update/release-key.pub.pem`）；
|
||||
@@ -201,7 +201,7 @@ macOS 用 `shasum -a 256 -c`，Windows 用 `Get-FileHash` 比较，不通过就
|
||||
|
||||
## 12. 还没有的与局限
|
||||
|
||||
- **还没有**：吊销表；任务和配置内容的操作员签名；节点向别人证明自己运行的就是官方二进制（见第 11 节）；extension 本身、属主的 `ControllerUpdate`、接收者的实际加密（属主只是被固定在节点本地，没有行为）；API key 的 IP 白名单（本部署经 Cloudflare、frp 和 Caddy，后端看到的来源地址是代理，需要先有「可信代理」配置才做得对）；OIDC 登录。
|
||||
- 还没有：吊销表；任务和配置内容的操作员签名；节点向别人证明自己运行的就是官方二进制（见第 11 节）；extension 本身、属主的 `ControllerUpdate`、接收者的实际加密（属主只是被固定在节点本地，没有行为）；API key 的 IP 白名单（本部署经 Cloudflare、frp 和 Caddy，后端看到的来源地址是代理，需要先有「可信代理」配置才做得对）；OIDC 登录。
|
||||
- WebAuthn 只验 ES256 和 attestation = `none`，不验设备证明。
|
||||
- 某个节点的属主 passkey 全部丢失，这个节点上的 extension 就没人能授权，需要重装节点并换属主。
|
||||
- 删除一把操作员 passkey 只是让它不能再签新版本；服务器密钥换新要靠签一个新集合版本，忘了签会让固定了集合的节点认不出面板（fail closed）。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# MoShiro 的注册与身份
|
||||
|
||||
通用的注册、身份、认证机制由 Fleet 提供，见 [../backend/fleet/README.md](../../backend/fleet/README.md) 的「身份」「注册」两节。本文只描述 **MoShiro 在 Fleet 之上的约定**：Agent 注册后如何自动接入测量、Probe 的身份以及 Agent 列表同步，以及节点本地的硬上限。
|
||||
通用的注册、身份、认证机制由 Fleet 提供，见 [Fleet 文档](../../backend/fleet/README.md) 的「身份」「注册」两节。本文只描述 MoShiro 在 Fleet 之上的约定：Agent 注册后如何自动接入测量、Probe 的身份以及 Agent 列表同步，以及节点本地的硬上限。
|
||||
|
||||
## 1. 身份一览
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
| Probe | Fleet 节点身份（连面板）+ 另一把独立的密钥（连 Agent，放在 `tls.pfx`） | `fleet-enroll`，和 Agent 一样用加入令牌（`role=probe`）；可以有多个 Probe，每个独立吊销 | 两把公钥 |
|
||||
| 面板用户 | 账号 + 密码（PBKDF2-SHA256） | 面板 | 密码哈希 |
|
||||
| API 令牌 | 随机高熵令牌，带一组能力（见 [access.md](access.md)） | 面板 | SHA-256 |
|
||||
| 发布签名 | ECDSA P-256 发布密钥 | CI（Woodpecker 密钥 `release_signing_key`）或离线环境 | 只在宿主机的更新器里配置公钥（Backend 和脚本装的节点用 `moshiro-update`，见 [deployment.md](../ops/deployment.md)；Quadlet 节点不验证清单，只是退出后重新拉镜像；纯二进制节点的更新是待办），**面板不保存私钥**；登记清单时面板用公钥验签，宿主机的更新器之后再验一次 |
|
||||
| 发布签名 | ECDSA P-256 发布密钥 | CI（Woodpecker 密钥 `release_signing_key`）或离线环境 | 只在宿主机的更新器里配置公钥（Backend 和脚本装的节点用 `moshiro-update`，见 [deployment.md](../ops/deployment.md)；Quadlet 节点不验证清单，只是退出后重新拉镜像；纯二进制节点的更新见[路线图](../roadmap.md)），面板不保存私钥；登记清单时面板用公钥验签，宿主机的更新器之后再验一次 |
|
||||
|
||||
## 2. Agent 接入流程
|
||||
|
||||
@@ -59,7 +59,7 @@ Probe 启动
|
||||
```
|
||||
|
||||
- 每个 Agent 通过自己的期望状态（`TaskSet.peers`）获得 Probe 的公钥，用来验证点对点会话的签名。
|
||||
- **哪些 Probe 连哪些 Agent 由面板决定，始终是 Probe 主动拨出**：设置 `fleet.auto_link`（默认开）打开时，所有未吊销的 Probe 和所有 Agent 两两连；关闭时只连手动选中的。每一对还可以在管理端 Probe 页的「线路」矩阵里手动强制开或关（`PUT /api/admin/links/{probe_id}/{agent_id}`），手动设置优先于自动连接。结果同时用在 Probe 的 Agent 列表、Agent 的 `peers` 和线路目录（关掉的线路从总览里消失，历史数据还在）。
|
||||
- 哪些 Probe 连哪些 Agent 由面板决定，始终是 Probe 主动拨出：设置 `fleet.auto_link`（默认开）打开时，所有未吊销的 Probe 和所有 Agent 两两连；关闭时只连手动选中的。每一对还可以在管理端 Probe 页的「线路」矩阵里手动强制开或关（`PUT /api/admin/links/{probe_id}/{agent_id}`），手动设置优先于自动连接。结果同时用在 Probe 的 Agent 列表、Agent 的 `peers` 和线路目录（关掉的线路从总览里消失，历史数据还在）。
|
||||
- 吊销 Probe：`POST /api/admin/probes/{id}/revoke`，旧公钥立即从所有 Agent 的期望状态中移除，旧会话随之断开；要继续用就重新注册。
|
||||
|
||||
## 4. Agent 本地配置（`/etc/moshiro/agent.json`，面板无法修改）
|
||||
@@ -78,7 +78,7 @@ Probe 启动
|
||||
}
|
||||
```
|
||||
|
||||
- `limits` 是**本地硬上限**：期望任务集超出这些范围时，调和器拒绝执行，并在 `rejected[]` 中给出原因。
|
||||
- `limits` 是本地硬上限：期望任务集超出这些范围时，调和器拒绝执行，并在 `rejected[]` 中给出原因。
|
||||
- `allowed_target_cidrs` 默认为空，即不允许执行任何目标任务；需要时由节点所有者在本机显式开启。
|
||||
- `listen` 默认不包含 443。要用 443 测量，需要在本机把它加入 `quic_ports` 或 `tcp_ports`（端口不能被真实服务占用），见 [measurement.md](../design/measurement.md) 第 8 节。
|
||||
- `fleet_policy.allow_methods` 在 Fleet 默认值的基础上进一步收窄。
|
||||
|
||||
+46
-46
@@ -1,20 +1,20 @@
|
||||
# 零信任设计
|
||||
|
||||
> **实现状态**：协议方向声明表和卡口、Probe 自己生成密钥、预握手敲门、操作员集合与创世固定、服务器身份和安全链路、属主固定都已实现；测量数据的产生者签名、入库配额、Probe 拨号地址限制等还没做（第 3 节有逐项状态）。
|
||||
> 实现状态：协议方向声明表和卡口、Probe 自己生成密钥、预握手敲门、操作员集合与创世固定、服务器身份和安全链路、属主固定都已实现；测量数据的产生者签名、入库配额、Probe 拨号地址限制等还没做（第 3 节有逐项状态）。
|
||||
|
||||
Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题：现在谁听谁的、被攻破之后最坏会怎样、怎么用密码学把信任从 Backend 身上拿走。账户、能力、passkey 和入网信任链的具体做法见 [access.md](access.md)；纯采集的边界、本地硬上限和签名更新见 [architecture.md](../design/architecture.md) 第 5 节，这里不重复。
|
||||
|
||||
## 1. 范围
|
||||
|
||||
**要防的**
|
||||
要防的
|
||||
|
||||
- Backend（或 Backend 前面的 Cloudflare Tunnel、frp、Caddy 等中间环节）被攻破或被劫持之后，给节点下发恶意内容。
|
||||
- Agent 或 Probe 自己被入侵之后，去影响 Backend 或对端。
|
||||
|
||||
**有意不做的**
|
||||
有意不做的
|
||||
|
||||
- **进程沙箱**（seccomp、pids 和内存上限、出站白名单）。Agent 和 Probe 的定位是 1 核 1 GB 的小机器，不能吃资源。
|
||||
- **供应链的多签、冷却期和可复现构建**。代码风险靠 PR 评审降一个等级；发布仍然是单把发布密钥签名（见 [deployment.md](../ops/deployment.md)）。
|
||||
- 进程沙箱（seccomp、pids 和内存上限、出站白名单）。Agent 和 Probe 的定位是 1 核 1 GB 的小机器，不能吃资源。
|
||||
- 供应链的多签、冷却期和可复现构建。代码风险靠 PR 评审降一个等级；发布仍然是单把发布密钥签名（见 [deployment.md](../ops/deployment.md)）。
|
||||
- 顺带记一条：Agent 的单元挂了 `/:/host/root:ro`、`/proc`、`/sys`，被攻破的 Agent 能遍历宿主机。它们多半是不必要的（宿主网络模式下容器自己的 `/proc` 就是宿主的，磁盘用量可以对已挂载的 `/etc/os-release` 做 `statvfs`），属于沙箱范畴，先不动。
|
||||
|
||||
## 2. 威胁模型
|
||||
@@ -44,23 +44,23 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
|
||||
|
||||
| # | 缺口 | 状态 |
|
||||
| --- | --- | --- |
|
||||
| G1 | 节点不验证 Backend 的身份，只靠 TLS 加公共 CA | **已解决**：操作员集合里登记服务器密钥，节点要求服务器在认证挑战里签名，链路用应用层加密（[access.md](access.md) 第 8 节）。对 Backend 自己被攻破没有帮助 |
|
||||
| G2 | Probe 的私钥由 Backend 生成 | **已解决**：Probe 自己生成密钥，用加入令牌注册，私钥只在节点上（破坏性：旧 `probe.json` 失效） |
|
||||
| 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 被拒绝） |
|
||||
| G4 | Agent 的 TCP 端口对任何人完成 TLS 握手并出示证书 | 已解决：预握手敲门，见第 8 节（破坏性：旧 Probe 被拒绝） |
|
||||
| G5 | Backend 入库只限制了单块的大小，没有按节点的速率或配额 | 未解决：恶意节点可以灌满磁盘 |
|
||||
| G6 | 对端公钥、Agent 地址全由 Backend 决定 | 未解决：操作员集合不包含成员名册，被攻破的 Backend 能把恶意 Probe 加进 Agent 的白名单，或把 Probe 指向恶意 Agent |
|
||||
| G7 | 方法的方向和角色没有统一声明 | **已解决**：声明表和卡口，见第 6 节 |
|
||||
| G7 | 方法的方向和角色没有统一声明 | 已解决：声明表和卡口，见第 6 节 |
|
||||
| G8 | 测量数据没有产生者签名（块只有 CRC32C） | 未解决：中间环节可以改写测量数据；被攻破的 Agent 可以伪造 Probe 侧的时间戳 |
|
||||
| G9 | 入库只核对了 `agent_id`，不核对块里的 `series`（`line:<probe_id>`） | 未解决：被攻破的 Agent 可以为从没连过它的 Probe 灌入假线路数据 |
|
||||
| G10 | 没有合理性检查（`EchoOps` 不检查回显时间戳的一致性） | 未解决：恶意 Agent 可以谎报 `t2`、`t3` |
|
||||
| G11 | Probe 的一把密钥多处使用 | **已解决**：面向 Backend 和面向对等面的是独立的密钥，用途前缀做域隔离 |
|
||||
| G11 | Probe 的一把密钥多处使用 | 已解决：面向 Backend 和面向对等面的是独立的密钥，用途前缀做域隔离 |
|
||||
|
||||
没有问题的部分：UDP 端口对未认证的包静默丢弃，不回应（`DropInvalid`，有测试）；Probe 本身没有 TCP 监听；任务有本地硬上限；更新清单有签名和 `seq` 防回滚。
|
||||
|
||||
## 4. 核心思路：信任锚点从 Backend 移走
|
||||
|
||||
要防 Backend 被攻破，**改变信任的内容必须由 Backend 之外的密钥授权**。Backend 只搬运、计算和存储，不创造信任：
|
||||
要防 Backend 被攻破，改变信任的内容必须由 Backend 之外的密钥授权。Backend 只搬运、计算和存储，不创造信任：
|
||||
|
||||
```text
|
||||
① 发布密钥（CI） ──▶ 「跑什么代码」 清单签名、seq 防重放
|
||||
@@ -78,7 +78,7 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
|
||||
- 节点安装时固定创世指纹和属主；节点注册时先验操作员集合链（创世指纹、passkey 签名、属主在集合里），验不过就不交出密钥。之后只认从这个创世出发的新版本，节点持久化见过的最大版本，旧版本不可回放。
|
||||
- 操作员集合里还登记了 Backend 的服务器密钥（G1）。
|
||||
- 加节点不需要 passkey：创建加入码是普通操作，命令里只有公开的值；自动化用带 `fleet.enroll` 的 API key。信任来自节点注册时固定的创世指纹和属主。
|
||||
- **没有采用**逐节点的「成员证明」链（Grant、Ticket、Binding）：被攻破的 Backend 往名册里塞节点，拿不到比 Backend 已经有的更多的东西。所以名册（G6）仍然由 Backend 决定。
|
||||
- 没有采用逐节点的「成员证明」链（Grant、Ticket、Binding）：被攻破的 Backend 往名册里塞节点，拿不到比 Backend 已经有的更多的东西。所以名册（G6）仍然由 Backend 决定。
|
||||
|
||||
## 6. 协议的方向与平面
|
||||
|
||||
@@ -91,34 +91,34 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
|
||||
对等面（Probe 拨 Agent） TLS 控制 7443/tcp、数据 7443/udp、7444/tcp（先过敲门）
|
||||
```
|
||||
|
||||
- **每个平面只认自己的凭证**：节点面不接受令牌和 Cookie；外部面不接受节点签名；对等面只认敲门通过的成员。
|
||||
- **连接方向固定**：节点面永远是节点拨入 Backend，Backend 从不主动连节点，所谓「下发」只是在节点拨入的连接上发下行消息；对等面永远是 Probe 拨 Agent，Agent 不拨 Probe。
|
||||
- **外部面不能直通节点面**：管理端的操作（例如发起测试）只会触发 Backend 里一个**强类型**的下行方法，管理端不能指定方法名，也不能把请求体原样转给节点（`IAgentGateway` 里全是强类型方法）。
|
||||
- 每个平面只认自己的凭证：节点面不接受令牌和 Cookie；外部面不接受节点签名；对等面只认敲门通过的成员。
|
||||
- 连接方向固定：节点面永远是节点拨入 Backend，Backend 从不主动连节点，所谓「下发」只是在节点拨入的连接上发下行消息；对等面永远是 Probe 拨 Agent，Agent 不拨 Probe。
|
||||
- 外部面不能直通节点面：管理端的操作（例如发起测试）只会触发 Backend 里一个强类型的下行方法，管理端不能指定方法名，也不能把请求体原样转给节点（`IAgentGateway` 里全是强类型方法）。
|
||||
- 三个平面共用同一个监听端口和同一条 ASP.NET 管线，靠路径和凭证类型区分。把节点面和外部面做成可以分别配置监听地址（默认仍同一个），这样管理面可以只对内网或 VPN 开放，是待定的目标。
|
||||
|
||||
### 6.2 每个方法声明方向、类型和角色
|
||||
|
||||
**同一个方法名只允许一个发起方**，不存在「双向方法」。一个方法声明：发起方（`B→A`、`B→P`、`A→B`、`P→B`、`P→A`、`A→P`）、类型（请求有响应、通知无响应）、角色（`A`、`P`、`A+P`）、授权（无，或为 extension 预留的 `operator`）。方向总表见 [protocol.md](../design/protocol.md)，以代码里的声明为准。
|
||||
同一个方法名只允许一个发起方，不存在「双向方法」。一个方法声明：发起方（`B→A`、`B→P`、`A→B`、`P→B`、`P→A`、`A→P`）、类型（请求有响应、通知无响应）、角色（`A`、`P`、`A+P`）、授权（无，或为 extension 预留的 `operator`）。方向总表见 [protocol.md](../design/protocol.md)，以代码里的声明为准。
|
||||
|
||||
强制方式：
|
||||
|
||||
1. **一份声明表，单一真源**：框架的 `fleet.*` 在 `Fleet.Rpc/MethodTable.cs` 的 `FleetMethodTable`，`moshiro.*` 和两条二进制通道在 `MoShiro.Protocol` 的 `MoShiroMethodTable`；角色是 `NodeRoles`（服务端按节点 ID 前缀判断）。声明表按（平面，名字）查找，同名方法在两个平面里可以有不同的发起方（`fleet.state.sync` 在节点面是 Backend→节点，在对等面是 Agent→Probe）。
|
||||
2. **卡口在 `RpcRouter`**：创建时必须给出本侧（`RpcSide`）和声明表。**注册**处理函数时核对方向、类型、角色，不符就在启动时失败；**分发**时拒绝没有声明、方向不对、请求和通知用反了、角色不允许的消息，回 `fleet_protocol_violation`；**发送**前核对本侧有没有资格发起（违反是程序缺陷，抛异常）。
|
||||
3. **违规处理**：`RpcSession` 和服务端的 `NodeConnection` 对违规计数，超过上限（`MaxViolations`，默认 20）就断开连接；二进制通道也在服务端按声明核对。
|
||||
4. **响应匹配**：只接受对应未决请求 ID 的响应，不接受主动「响应」。
|
||||
5. **对账测试**：`Fleet.Tests/MethodDirectionTests` 覆盖卡口本身；`MoShiro.Backend.Tests/ProtocolDeclarationTests` 核对「每个方法常量都声明了」「文档里写了每个方法」「各角色该处理的方法都注册了处理函数」「每条声明的通道都有收件箱」。
|
||||
6. **下行消息只是建议，不是命令**：节点按本地硬上限执行或拒绝；任何带副作用的敏感能力都不走核心的下行消息，见第 9 节。
|
||||
1. 一份声明表，单一真源：框架的 `fleet.*` 在 `Fleet.Rpc/MethodTable.cs` 的 `FleetMethodTable`，`moshiro.*` 和两条二进制通道在 `MoShiro.Protocol` 的 `MoShiroMethodTable`；角色是 `NodeRoles`（服务端按节点 ID 前缀判断）。声明表按（平面，名字）查找，同名方法在两个平面里可以有不同的发起方（`fleet.state.sync` 在节点面是 Backend→节点，在对等面是 Agent→Probe）。
|
||||
2. 卡口在 `RpcRouter`：创建时必须给出本侧（`RpcSide`）和声明表。注册处理函数时核对方向、类型、角色，不符就在启动时失败；分发时拒绝没有声明、方向不对、请求和通知用反了、角色不允许的消息，回 `fleet_protocol_violation`；发送前核对本侧有没有资格发起（违反是程序缺陷，抛异常）。
|
||||
3. 违规处理：`RpcSession` 和服务端的 `NodeConnection` 对违规计数，超过上限（`MaxViolations`，默认 20）就断开连接；二进制通道也在服务端按声明核对。
|
||||
4. 响应匹配：只接受对应未决请求 ID 的响应，不接受主动「响应」。
|
||||
5. 对账测试：`Fleet.Tests/MethodDirectionTests` 覆盖卡口本身；`MoShiro.Backend.Tests/ProtocolDeclarationTests` 核对「每个方法常量都声明了」「文档里写了每个方法」「各角色该处理的方法都注册了处理函数」「每条声明的通道都有收件箱」。
|
||||
6. 下行消息只是建议，不是命令：节点按本地硬上限执行或拒绝；任何带副作用的敏感能力都不走核心的下行消息，见第 9 节。
|
||||
|
||||
### 6.3 各类下行消息怎么处置
|
||||
|
||||
| 下行内容 | 授权 | 被攻破的 Backend 最多能做什么 |
|
||||
| --- | --- | --- |
|
||||
| 操作员集合新版本 | **操作员 passkey 签名**，节点自己验 | 什么都改不了；能转发旧的合法版本，版本号递增防回放 |
|
||||
| 操作员集合新版本 | 操作员 passkey 签名，节点自己验 | 什么都改不了；能转发旧的合法版本，版本号递增防回放 |
|
||||
| 更新清单 | 发布密钥（CI） | 不能伪造；能转发旧的合法清单，`seq` 防回滚；节点的更新器还会用本机公钥再验 |
|
||||
| 成员名册、对端公钥、Agent 地址 | Backend（G3、G6 未解决） | 能把恶意 Probe 加进 Agent 的白名单，或把 Probe 指向恶意 Agent |
|
||||
| 任务集、测试请求 | Backend 计算；节点本地硬上限兜底 | 只能在本地速率和端口上限内发测量流量 |
|
||||
| 重启计划（`moshiro.schedule`） | Backend；节点本地启动后 10 分钟内不触发 | 最多让节点每 10 分钟重启一次 |
|
||||
| 未来的 `extension`（exec 等） | **属主 passkey 签名的一次性能力令牌**，见第 9 节 | 什么都做不了 |
|
||||
| 未来的 `extension`（exec 等） | 属主 passkey 签名的一次性能力令牌，见第 9 节 | 什么都做不了 |
|
||||
|
||||
## 7. 节点自己被攻破时（设计，未实现）
|
||||
|
||||
@@ -126,30 +126,30 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
|
||||
|
||||
测量数据是这个项目的产出，不能只靠传输层可信：链路有 Cloudflare 这样的中间环节，Agent 又要转发 Probe 的数据。
|
||||
|
||||
- **产生者签名**：每个列块由 Probe 签名，每个原始块由上传它的节点签名；Agent 转发 Probe 的块时原样保留签名。签名覆盖块的摘要（SHA-256），签名串带用途前缀 `chunk` 和节点 ID。Backend 入库时逐个验签，不通过的丢弃并计数。每 10 秒一块，一次 ECDSA 验签的开销可以忽略。
|
||||
- **归属校验**：入库时核对块里的 Probe 是和这个 Agent 有线路的成员，不是就丢弃并计数。
|
||||
- **合理性检查**：`t3−t2` 必须小于 `t4−t1`，各时间戳单调；违反的样本不计入指标，记为异常并产生事件。
|
||||
- 产生者签名：每个列块由 Probe 签名，每个原始块由上传它的节点签名；Agent 转发 Probe 的块时原样保留签名。签名覆盖块的摘要（SHA-256），签名串带用途前缀 `chunk` 和节点 ID。Backend 入库时逐个验签，不通过的丢弃并计数。每 10 秒一块，一次 ECDSA 验签的开销可以忽略。
|
||||
- 归属校验：入库时核对块里的 Probe 是和这个 Agent 有线路的成员，不是就丢弃并计数。
|
||||
- 合理性检查：`t3−t2` 必须小于 `t4−t1`，各时间戳单调；违反的样本不计入指标，记为异常并产生事件。
|
||||
- 边界：这样中间环节改不了数据，被攻破的 Agent 改不了 Probe 一侧的数据；但它仍然可以谎报自己一侧的 `t2`、`t3`，合理性检查只能限制它的幅度，因为这一侧的真值只有它自己知道。
|
||||
|
||||
### 7.2 对 Backend 的资源和输入
|
||||
|
||||
- **按节点的配额**：每个节点的字节、块数和速率上限，只是计数，不占资源；全局再限制同时解码的块数（单块解码上限是 64 MiB）。
|
||||
- **节点上报的字符串**：`hello` 里的 `platform`、事件的 `detail` 等一律当不可信数据，入库前统一校验长度、字符集和换行，不依赖前端转义；管理端不渲染成 HTML。
|
||||
- **匿名公开接口**：登录已经有限流，但热力图、分布这类重查询只有范围和指标数的上限，要加每源限速和结果缓存。
|
||||
- **webhook**：实现之前先定约束：只允许 HTTPS、禁止私网和回环地址、不跟随重定向、限制超时和响应大小、解析之后再检查地址。
|
||||
- 按节点的配额：每个节点的字节、块数和速率上限，只是计数，不占资源；全局再限制同时解码的块数（单块解码上限是 64 MiB）。
|
||||
- 节点上报的字符串：`hello` 里的 `platform`、事件的 `detail` 等一律当不可信数据，入库前统一校验长度、字符集和换行，不依赖前端转义；管理端不渲染成 HTML。
|
||||
- 匿名公开接口：登录已经有限流，但热力图、分布这类重查询只有范围和指标数的上限，要加每源限速和结果缓存。
|
||||
- webhook：实现之前先定约束：只允许 HTTPS、禁止私网和回环地址、不跟随重定向、限制超时和响应大小、解析之后再检查地址。
|
||||
|
||||
### 7.3 对对端和身份
|
||||
|
||||
- 被攻破的 Probe 只能拿到 Backend 授权的会话，Agent 的速率上限由本地兜底；被攻破的 Agent 发来的数据只会影响它自己的线路。
|
||||
- **Probe 只拨公网地址**（G3）：固定 SPKI 只能防止建立会话，防不了探测本身；要在 Probe 本地拒绝私网、回环、链路本地地址。
|
||||
- **名册里的主机名解析之后再检查地址**：签名保护的是字符串，不是解析结果；默认只放行公网地址，内网需要节点本地显式允许。
|
||||
- **QUIC 会话迁移要做路径验证**：协议允许会话在 NAT 映射变化后跟随新的源地址，路径上的攻击者可以借此把会话牵到自己的地址。迁移前先做一次挑战应答，验证前限制发送量（不超过收到字节数的 3 倍），由 QUIC path validation 提供。
|
||||
- **不协商、不降级**：现在固定 ECDSA P-256 和固定的签名串格式，没有算法协商，保持这一点。
|
||||
- Probe 只拨公网地址（G3）：固定 SPKI 只能防止建立会话，防不了探测本身；要在 Probe 本地拒绝私网、回环、链路本地地址。
|
||||
- 名册里的主机名解析之后再检查地址：签名保护的是字符串，不是解析结果；默认只放行公网地址，内网需要节点本地显式允许。
|
||||
- QUIC 会话迁移要做路径验证：协议允许会话在 NAT 映射变化后跟随新的源地址，路径上的攻击者可以借此把会话牵到自己的地址。迁移前先做一次挑战应答，验证前限制发送量（不超过收到字节数的 3 倍），由 QUIC path validation 提供。
|
||||
- 不协商、不降级：现在固定 ECDSA P-256 和固定的签名串格式，没有算法协商，保持这一点。
|
||||
- Agent 的 `max_total_mbps` 默认是 1200，对 1 核 1 GB 的小机器没有意义，却是被攻破的 Backend 能让 Agent 向某个 Probe 打出去的上限。默认值应该保守，需要的人再调高；`allowed_target_cidrs` 默认为空是对的。
|
||||
|
||||
## 8. 监听隐身：预握手敲门
|
||||
|
||||
目标：Agent 的 TCP 端口对没有完成挑战的人**不写出任何字节**，包括 TLS 的 ServerHello，扫描器拿不到证书和 TLS 指纹（G4）。UDP 端口本来就是静默的。
|
||||
目标：Agent 的 TCP 端口对没有完成挑战的人不写出任何字节，包括 TLS 的 ServerHello，扫描器拿不到证书和 TLS 指纹（G4）。UDP 端口本来就是静默的。
|
||||
|
||||
```text
|
||||
Probe Agent TCP 7443 / 7444
|
||||
@@ -161,20 +161,20 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题
|
||||
```
|
||||
|
||||
- `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 里上报）。陌生连接得到的是被关闭的连接，没有任何字节。
|
||||
- 实现：`Fleet.Identity.Knock`（构造与核对）和 `KnockGate`（读 32 字节、名册、nonce 去重、按来源限速）；控制端口（`PeerListener`）和数据端口（`TcpAcceptor`）共用同一个关卡，Probe 一侧 `PeerConnector` 和 `TcpLink` 在 TCP 连接建立后、TLS 之前发敲门包。名册是期望状态里的 `peers`（Probe 的对等面公钥）；`probe_agents` 下发的是 Agent 的 `public_key`（Agent 在 hello 里上报）。陌生连接得到的是被关闭的连接，没有任何字节。
|
||||
|
||||
**局限**：TCP 的 SYN-ACK 由内核发出，用户态进程拦不住，所以端口在扫描器眼里仍是「开着，但不说话」，**不是「没监听」**。真正的没监听有两条路：等级二的 UDP 单包授权（Probe 先发签名的 UDP 敲门包，Agent 才临时开 TCP 监听几秒，只放行敲门者的源地址；代价是多一个往返、UDP 丢包重试、多出口源地址可能对不上），或宿主防火墙规则（需要 root，不适合小机器，不做）。先做等级一，等级二可选。
|
||||
局限：TCP 的 SYN-ACK 由内核发出，用户态进程拦不住，所以端口在扫描器眼里仍是「开着，但不说话」，不是「没监听」。真正的没监听有两条路：等级二的 UDP 单包授权（Probe 先发签名的 UDP 敲门包，Agent 才临时开 TCP 监听几秒，只放行敲门者的源地址；代价是多一个往返、UDP 丢包重试、多出口源地址可能对不上），或宿主防火墙规则（需要 root，不适合小机器，不做）。先做等级一，等级二可选。
|
||||
|
||||
## 9. extension：敏感能力的归宿
|
||||
|
||||
Agent 和 Probe 的核心永远是纯采集器。**所有敏感能力**（exec、web ssh 和终端、文件读写、抓包等）都不进核心，做成 extension，**用户可选安装，默认没有**，现在都没有实现。
|
||||
Agent 和 Probe 的核心永远是纯采集器。所有敏感能力（exec、web ssh 和终端、文件读写、抓包等）都不进核心，做成 extension，用户可选安装，默认没有，现在都没有实现。
|
||||
|
||||
- **独立进程，不是插件**：单独的二进制和镜像，和核心之间没有进程内接口，核心不加载任何外部代码、不用反射和动态加载，核心的 NativeAOT 和「不能 exec」都不受影响。
|
||||
- **授权只认节点的属主**：每次调用的能力令牌必须由这个节点绑定的属主 passkey 签名，账户角色不赋予权力；管理员只能删除节点或卸载 extension。交互式会话端到端加密，Backend 只转发密文。属主和会话密钥的设计见 [access.md](access.md) 第 9 节。
|
||||
- **独立身份和发布**：extension 有自己的密钥、自己向 Backend 注册，在名册里是单独的成员（记录它依附的节点 ID）；独立的镜像和清单（`component` 不同，例如 `ext-ssh`），装不装、升不升级都不影响核心。
|
||||
- **独立命名空间**：extension 的方法只能是 `ext.<名字>.*`，同样进方向声明表；核心的声明表里没有 `ext.*`，核心收到一律拒绝。
|
||||
- **本地显式启用**：extension 的本地配置里有 `enabled`、允许的操作员凭证、允许的命令集或目标范围，默认关闭。
|
||||
- **不做的**：核心里的任何 exec、文件写、加载 extension；用 extension 绕过核心的本地硬上限。
|
||||
- 独立进程，不是插件：单独的二进制和镜像，和核心之间没有进程内接口，核心不加载任何外部代码、不用反射和动态加载，核心的 NativeAOT 和「不能 exec」都不受影响。
|
||||
- 授权只认节点的属主：每次调用的能力令牌必须由这个节点绑定的属主 passkey 签名，账户角色不赋予权力；管理员只能删除节点或卸载 extension。交互式会话端到端加密，Backend 只转发密文。属主和会话密钥的设计见 [access.md](access.md) 第 9 节。
|
||||
- 独立身份和发布：extension 有自己的密钥、自己向 Backend 注册，在名册里是单独的成员（记录它依附的节点 ID）；独立的镜像和清单（`component` 不同，例如 `ext-ssh`），装不装、升不升级都不影响核心。
|
||||
- 独立命名空间：extension 的方法只能是 `ext.<名字>.*`，同样进方向声明表；核心的声明表里没有 `ext.*`，核心收到一律拒绝。
|
||||
- 本地显式启用：extension 的本地配置里有 `enabled`、允许的操作员凭证、允许的命令集或目标范围，默认关闭。
|
||||
- 不做的：核心里的任何 exec、文件写、加载 extension；用 extension 绕过核心的本地硬上限。
|
||||
|
||||
## 10. 密码学原语
|
||||
|
||||
@@ -187,7 +187,7 @@ Agent 和 Probe 的核心永远是纯采集器。**所有敏感能力**（exec
|
||||
| 令牌哈希、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 里没有，Probe 和 Agent 不引用 NuGet 包，只能自己实现几百行的便携版本加官方测试向量，这是要长期维护的密码学代码；托管实现没有 SHA-NI 加速，在 x86 上未必更快。若以后在目标硬件上实测发现逐包 MAC 是瓶颈，再单独评估，届时只替换 `Fleet.Identity` 里 `Mac` 和 `Kdf` 两个静态函数，调用方不动。
|
||||
|
||||
## 11. 还没定的事
|
||||
|
||||
|
||||
Reference in new issue
Block a user