# LinkRSP 威胁模型范围 v1.0

**版本**：v1.0（文稿）  
**交叉引用**：[工程架构 v0.1](../engineering/architecture-v0.1.md) · [技术栈策略 v1.0 — §6 刻意不选](../engineering/technology-strategy-v1.0.md) · [可行性评估 §8](../reports/feasibility-assessment-v1.0-alpha.md)

---

## 1. 是否需要「全域」威胁模型

**建议：需要，但分阶段，不必首周即达到 HDGP 主仓体量。**

HDGP 主线的威胁建模与审计门禁，适合作为**成熟度参照**；LinkRSP 在架构阶段应至少具备：

| 阶段 | 威胁建模产出 | 目的 |
|------|----------------|------|
| **当前（架构）** | 本文档 + 可行性 §8 风险表 + 工程「刻意不选」清单 | 对齐攻击面边界，避免首版代码结构性返工 |
| **首版可运行前** | **STRIDE** 或等价的轻量表（按组件：API、账本、存证、HDGP 适配器、LLM 队列、移动端） | 为 Harness 阈值、日志字段、密钥管理提供依据 |
| **对外连接前** | 与部署形态匹配的 **数据流图 + 信任边界**；按需渗透测试范围书 | 满足合作方最低安全问卷 |

**结论**：不做任何威胁梳理会在 **Harness、积分账本、BLE** 三处积累不可逆技术债；**不要求**与 HDGP 同一份 TM 文档，但要求 **同类的显式边界与可追溯更新**。

---

## 2. LinkRSP 优先威胁面（摘要）

1. **账本与事件**：伪造分录、重放、幂等失败、管理员越权改账。  
2. **物理存证**：GPS 欺骗、BLE 中继、弱 V=0 占比导致系统性降质。  
3. **规则与 LLM**：提示注入、灰区队列投毒、规则包版本回滚攻击。  
4. **身份与治理**：女巫注册、Judge 操纵（与 §6 R/S 对齐）。  
5. **供应链**：依赖与 CI 密钥、第三方 Engine 可用性伪造。

详细条目随 `spec` 与实现收敛后，应迁入独立 `THREAT_MODEL.md` 或安全仓库小节。

---

## 3. 与 HDGP 的关系

HDGP 侧威胁模型覆盖 **Engine / 策略包** 等；LinkRSP 须额外覆盖 **LRS 特有业务面**（上表）。集成时避免重复描述 HDGP 已覆盖的引擎内部细节，以 **接口信任边界** 为界。

---

## 4. 当前仓库已具备的安全落地点（2026-04）

以下条目不是完整威胁模型，但已经是对威胁面的**工程承接**：

- **只追加账本 / 审计事件**：当前数据库与应用实现均按 append-only 方向约束，避免原地改账成为默认路径。
- **幂等键**：审计事件已使用 `(rule_id, subject_type, subject_id, trigger, timestamp_minute)` 语义生成幂等键，用于降低重放与重复写入风险。
- **结算事务化**：结算提交已将 `ledger_entries` 与 `audit_events` 放入同一事务，降低“账本已写但审计缺失”的不一致窗口。
- **内部回放查询**：`lrs-ledger-query` 已返回窗口内投影余额与逐笔回放结果，便于后续对账、复核与统计规则复用。
- **共享密钥保护的内部接口**：内部查询与写路径当前通过共享密钥做最小访问控制，适合作为 Phase C 的过渡保护。

这些实现说明仓库里已经存在**威胁模型相关的设计落地**，尤其集中在“伪造分录、重放、幂等失败、审计缺失”这一组风险上。

---

## 5. 最小 STRIDE 轻量表（草案）

> 说明：本表用于首版可运行前的轻量威胁梳理，目标是把“组件 / 威胁 / 当前控制 / 后续动作”先钉住，不替代后续更完整的数据流图与渗透测试范围书。

| 组件 | STRIDE 关注点 | 当前控制 | 仍需补齐 |
|------|---------------|----------|----------|
| **API / Shared Secret** | S / T / I：伪造内部调用、参数篡改、密钥泄露后横向读取内部查询 | 共享密钥保护写路径与内部查询；RFC3339 / limit 参数校验；结构化错误返回 | 补请求级审计、密钥轮换策略、不同角色的接口边界 |
| **Ledger / Settlement** | T / R / E：伪造分录、重复结算、管理员越权改账、账本与审计不一致 | append-only 账本；幂等键；preview/commit 分离；结算事务化 | 补管理员操作边界、异常回滚演练、冲正分录策略文档 |
| **Audit Events** | T / R：审计事件遗漏、重放、伪造或无法对账 | append-only 审计事件；事件幂等键；规则执行写审计 | 补事件完整性校验、导出/归档策略、审计查询权限模型 |
| **Attestation / Physical Evidence** | S / T / I：GPS 欺骗、BLE 中继、弱存证伪造、证据引用泄露 | 已有 attestation 写入、时间窗口约束、后续规则预留；内部索引查询可回放 | 补 GPS/BLE abuse case、对象存储访问边界、V=0/V=1 降级防滥用策略 |
| **HDGP Adapter / Rule Engine** | T / D / E：规则包回滚、外部 Engine 异常、错误信任上游结果 | 当前以接口边界为主，未与具体上游实现硬耦合 | 补版本钉住策略、上游失败 fail-closed 行为、回放输入快照 |
| **LLM Queue / Human Review** | T / I / D：提示注入、灰区队列投毒、人工复核队列阻塞 | 当前尚未正式启用，风险已在范围文档标出 | 在 Phase D/E 补队列幂等键、prompt 摘要留痕、人工/自动切换策略 |

这张表意味着：仓库已经从“只有威胁摘要”推进到“有最小组件级威胁草案”，但还没有到可替代完整 threat model 的程度。

---

## 6. 数据流 / 信任边界图（草案）

> 说明：本节不是部署图，而是面向威胁模型的最小数据流草案，目的是明确“谁能调用谁、哪些数据跨边界、哪里需要 fail-closed”。

### 6.1 组件与数据流（当前 / 近期目标）

```text
[Client / Operator / Future Mobile App]
        |
        | HTTPS
        v
[LinkRSP API]
        |
        | shared-secret protected internal routes
        +------------------------------+
        |                              |
        v                              v
 [Postgres]                    [Object Storage]
  - tasks                       - evidence_ref blobs
  - attestations                - future raw evidence objects
  - ledger_entries
  - audit_events
  - semantic_audit_jobs (future)
        |
        | interface boundary
        v
[HDGP Adapter / External Rule Engine]
        |
        | future async / queued review
        v
[LLM Worker / Human Review Queue]
```

### 6.2 信任边界（最小集）

| 边界 | 边界两侧 | 当前判断 | 说明 |
|------|----------|----------|------|
| **TB-1 Client ↔ API** | 用户输入 / 服务端规则执行 | **低信任 → 受控域** | 所有任务、存证、查询参数都应视为外部输入；时间、limit、标识符必须在此边界校验。 |
| **TB-2 API ↔ Internal Routes** | 普通对外路径 / 内部查询与写路径 | **中信任 → 高敏感内部面** | 当前通过共享密钥做最小访问控制；泄露后会扩大横向读取与内部调用面。 |
| **TB-3 API ↔ Postgres** | 应用层 / 权威账本与审计存储 | **受控域 ↔ 核心状态域** | `ledger_entries`、`audit_events` 属于高完整性对象；此边界重点防止部分提交、重放和越权写入。 |
| **TB-4 API ↔ Object Storage** | 元数据服务 / 证据对象引用 | **受控域 ↔ 外部持久化对象域** | 当前主要是 `evidence_ref` 预留；未来需限制对象可见性、签名 URL、生存期与越权下载。 |
| **TB-5 API ↔ HDGP Adapter / External Engine** | LinkRSP 本地规则域 / 外部判定域 | **本域 ↔ 外部依赖域** | 上游结果不可被无条件信任；版本漂移、错误响应、超时都应按 fail-closed 或人工复核策略处理。 |
| **TB-6 Adapter ↔ LLM / Human Review** | 确定性规则域 / 灰区语义判定域 | **高风险边界** | prompt 注入、队列投毒、复核阻塞都集中在这里；且任何输出都不能直接生成积分。 |

### 6.3 关键数据对象与跨边界方向

| 数据对象 | 来源 | 去向 | 安全关注点 |
|---------|------|------|------------|
| **task metadata** | Client | API → Postgres | 参数篡改、时间窗口伪造、社区/UID 冒用 |
| **attestation summary** | Client / future mobile | API → Postgres | GPS 欺骗、BLE 中继、V 档位伪造、重放 |
| **ledger entries** | API settlement commit | Postgres | 只追加、幂等、事务一致性、管理员越权改账 |
| **audit events** | Rule execution path | Postgres | 审计遗漏、伪造、无法对账、查询权限过宽 |
| **evidence_ref / evidence object** | API / future upload flow | Object Storage | 未授权读取、对象枚举、过度暴露原始证据 |
| **rule input/output snapshot** | API / Adapter | External Engine / future queue | 版本回滚、输入漂移、输出不可重放 |
| **prompt summary / review job** | Adapter / future queue | LLM Worker / Human Review | prompt 注入、队列投毒、阻塞、泄露敏感文本 |

#### 6.3.1 账户休眠 / 归档与保留策略（威胁面引子）

长周期运行下，**休眠账户、身故或治理终止**后的数据最小化、冷归档与对象存储保留期若未定义，可能扩大泄露面或引发合规争议。设计原则与协议叙事见 [`../governance/membership-credit-lifecycle-supplement-v0.1.md`](../governance/membership-credit-lifecycle-supplement-v0.1.md)；工程侧需与对象签名 URL 生命周期、审计导出策略一并评审。

### 6.4 对外连接前的最小安全要求

- **内部接口隔离**：`/api/v1/internal/*` 在共享密钥之外，还需补调用审计、密钥轮换与最小调用主体边界。
- **对象存储边界显式化**：若启用原始证据上传，必须明确私有桶策略、签名下载与引用过期时间。
- **外部依赖 fail-closed**：HDGP Adapter、外部 Engine、未来 LLM Worker 失败时，不进入自动放行路径。
- **回放快照可追溯**：进入外部 Engine 或语义队列前，至少保留版本号、输入摘要、触发时间窗口。
- **人工复核可接管**：高风险灰区不得只依赖自动链路，必须预留人工复核或暂停路径。

---

## 7. 攻击面清单（最小 checklist 草案）

> 说明：本清单用于把“已经识别出的边界”转成后续实现、测试、联调和上线前可逐项核对的攻击面列表；它不是渗透测试报告，但应能指导 abuse case 与验证项落地。

| 攻击面 | 入口 / 对象 | 主要风险 | 当前控制 | 上线前至少补齐 |
|--------|-------------|----------|----------|----------------|
| **公开 API 写路径** | `POST /api/v1/tasks`、`POST /api/v1/tasks/{task_id}/attestations`、结算 preview/commit | 参数伪造、越权提交、重放、时间窗口污染 | 基础字段校验、UTC/RFC3339 约束、规则执行写审计、preview/commit 分离 | 补请求级身份边界、速率限制、异常调用审计 |
| **内部查询与内部写路径** | `/api/v1/internal/*` | 共享密钥泄露后横向读取、批量枚举、内部接口滥用 | 共享密钥保护、limit 参数校验、结构化错误返回 | 补调用主体分层、密钥轮换、访问日志与最小权限策略 |
| **账本写入面** | `ledger_entries`、结算 commit | 伪造分录、重复落账、部分提交、管理员越权改账 | append-only、幂等键、事务化提交、回放查询 | 补管理员操作边界、冲正策略、异常回滚演练 |
| **审计事件面** | `audit_events`、审计查询接口 | 审计遗漏、伪造、删除/篡改、过宽读取 | append-only、规则执行写审计、事件幂等键 | 补完整性校验、查询权限模型、导出归档边界 |
| **存证索引与物理证据面** | `attestations`、`attestation-index-query`、future `evidence_ref` | GPS 欺骗、BLE 中继、V 档位伪造、对象引用泄露 | 存证写入、时间窗口约束、索引查询可回放 | 补 GPS/BLE abuse cases、V=0/V=1 滥用防线、对象访问控制 |
| **对象存储面** | evidence object、签名下载、对象引用 | 未授权下载、对象枚举、证据长期暴露、误公开桶 | 当前以 `evidence_ref` 预留为主，未正式开放原始上传 | 补私有桶策略、签名 URL 生命周期、对象命名与删除保留策略 |
| **外部 Engine / HDGP 适配面** | Adapter、外部规则输入输出 | 规则包回滚、错误信任上游结果、假可用、输入/输出漂移 | 当前以接口边界隔离、未与单一实现硬耦合 | 补版本钉住、失败 fail-closed、输入输出快照留痕 |
| **未来 LLM / 人工复核队列面** | `semantic_audit_jobs`、prompt summary、review queue | prompt 注入、队列投毒、重复消费、人工阻塞 | 当前尚未正式启用，仅在文档中标出风险 | 补队列幂等键、prompt 摘要留痕、人工/自动切换与超时策略 |
| **配置与密钥面** | shared secret、DB DSN、外部服务凭据 | 凭据泄露、配置漂移、错误环境连接 | 当前以环境变量/服务配置为假定边界 | 补轮换策略、环境隔离、密钥使用审计 |
| **运维与供应链面** | CI、依赖、部署配置、第三方服务 | 依赖投毒、CI 密钥泄露、错误部署、假健康状态 | 当前已有仓库内版本与部署配置收敛 | 补依赖审计、CI 权限最小化、部署后关键路径检查 |

这张清单意味着：LinkRSP 当前已不只是“知道有哪些风险”，而是已经把主要入口整理成可验证、可继续细化的攻击面列表。

---

## 8. 缓解措施映射表（最小草案）

> 说明：本表把“威胁摘要 / 攻击面清单”继续往前推进一层，目的是明确哪些风险已有控制、哪些仍是剩余风险，以及下一步应该补什么，而不是把所有风险都停留在原则描述。

| 威胁 | 影响对象 | 当前控制 | 剩余风险 | 后续动作 |
|------|----------|----------|----------|----------|
| **伪造分录 / 重复结算** | `ledger_entries`、结算链路 | append-only、幂等键、preview/commit 分离、结算事务化 | 仍缺管理员越权边界、冲正流程与异常演练 | 补冲正分录策略、管理员权限约束、commit 失败回放测试 |
| **审计缺失 / 无法对账** | `audit_events`、规则执行链 | 规则执行写审计、append-only、事件幂等键 | 仍缺完整性校验、导出归档与查询权限分层 | 补事件完整性检查、审计查询权限模型、导出策略 |
| **共享密钥泄露 / 内部接口滥用** | `/api/v1/internal/*`、内部写路径 | 共享密钥保护、基础参数校验、结构化错误返回 | 仍可能被横向批量读取或伪造内部调用 | 补密钥轮换、调用审计、最小调用主体与分层密钥 |
| **GPS 欺骗 / BLE 中继 / V 档位伪造** | `attestations`、未来移动端存证 | 时间窗口约束、存证写入、索引可回放、规则预留 | 尚未有系统化设备/物理世界 abuse case 防线 | 补 GPS/BLE abuse cases、V=0/V=1 降级防滥用策略、移动端验证约束 |
| **对象证据泄露 / 引用越权读取** | `evidence_ref`、future object storage | 当前仅预留引用，尚未开放完整原始上传链路 | 一旦开放上传，可能暴露原始物理证据与对象枚举面 | 补私有桶策略、签名 URL、生存期、对象访问审计 |
| **规则包回滚 / 错误信任外部 Engine** | HDGP Adapter、external engine | 以接口边界隔离，未与单一实现硬耦合 | 上游版本漂移、超时、假成功仍可能污染本地判断 | 补版本钉住、输入输出快照、fail-closed / 人工复核分流 |
| **prompt 注入 / 队列投毒 / 人工复核阻塞** | future `semantic_audit_jobs`、LLM worker、review queue | 当前尚未启用，仅在威胁模型中显式标出 | Phase D/E 启动时会快速成为高风险入口 | 补队列幂等键、prompt 摘要留痕、人工接管与超时策略 |
| **依赖 / CI / 部署供应链问题** | CI、第三方服务、部署配置 | 当前部署路径与仓库配置已收敛 | 仍缺依赖审计、CI 密钥最小化和发布后核验 | 补依赖扫描、CI 权限收紧、部署后关键路径 smoke check |

这张表意味着：当前仓库已经能把“威胁 → 控制 → 剩余风险 → 后续动作”串成最小闭环，但还没有把这些动作沉淀成演练项与责任机制。

---

## 9. 红队 / 滥用案例回放清单（最小草案）

> 说明：本清单不是进攻性操作指南，而是面向防御验证的回放条目目录，用于在开发、联调、上线前复核“现有控制是否真的生效”。重点是复现风险、观察系统反应、确认 fail-closed 与审计留痕。

| 场景 | 目标入口 / 对象 | 预期验证点 | 当前状态 | 后续落地形式 |
|------|------------------|------------|----------|--------------|
| **账本重复提交 / 幂等重放** | settlement commit、`ledger_entries` | 同一 `idempotency_key` 重复提交时只返回同一分录；不得生成额外账本或多条审计副本 | **部分已覆盖**：已有结算集成测试覆盖重复 commit 返回同一 `ledger_entry_id` | 补异常路径回放：事务中断、审计写失败、重复请求乱序 |
| **账本部分提交 / 审计缺失** | settlement transaction、`audit_events` | 若审计事件写入失败，则账本提交整体失败；不得出现“已落账但无审计” | **部分已覆盖**：结算链已事务化 | 补故障注入测试，验证 `ledger_entries` 与 `audit_events` 原子一致 |
| **内部接口共享密钥泄露** | `/api/v1/internal/*` | 无密钥、错误密钥、过期/轮换后密钥都应被拒绝；内部访问应留有调用审计 | **基础控制已存在**：共享密钥保护 | 补认证失败回放、密钥轮换演练、访问日志检查项 |
| **内部查询批量枚举 / 窗口滥用** | `lrs-ledger-query`、`attestation-index-query` | 超大 `limit`、非法窗口、批量 UID 枚举请求应被限制或记录；错误输入不得扩大读取面 | **部分已覆盖**：RFC3339 与 limit 基础校验已存在 | 补速率限制、枚举检测、异常查询审计 |
| **GPS 欺骗 / 时间窗口伪造** | attestation 写路径、时间边界 | 存证时间与任务窗口冲突、位置摘要异常或跳变时，应进入 block/flag/复核路径，而非直接可信 | **规则预留为主**：文档已识别风险 | 补回放样例库与规则断言，覆盖 V=0/V=1 常见欺骗场景 |
| **BLE 中继 / 近场伪装** | future mobile attestation、V=2 流程 | 远程代打卡或中继场景不能被等同视为真实近场存证；至少要能降级或进入人工复核 | **尚未实现**：处于设计阶段 | 在 Phase D 前补设备侧 abuse case 与降级策略说明 |
| **对象证据越权读取 / 引用泄露** | `evidence_ref`、future object storage | 未授权主体不能通过对象名猜测或旧链接重放读取原始证据 | **尚未正式开放**：仅预留引用 | 补私有桶、签名 URL 生命周期、对象访问审计回放 |
| **规则包回滚 / 错误信任外部 Engine** | HDGP Adapter、external engine | 上游返回旧版本、异常版本或假成功时，本地应 fail-closed 或转人工复核，不得静默放行 | **尚未系统化验证**：目前仅有边界设计 | 补版本钉住检查、输入输出快照比对、上游失败演练 |
| **prompt 注入 / 队列投毒 / 重复消费** | future `semantic_audit_jobs`、LLM worker | 恶意文本不得影响规则执行边界；队列重复消费不得造成重复判定或状态漂移 | **尚未启用**：仅文档识别 | 在 Phase D/E 启动时补队列幂等、prompt 摘要留痕、超时与人工接管演练 |
| **管理员越权改账 / 绕过只追加约束** | `ledger_entries`、`audit_events`、运维面 | 管理操作不得直接修改既有账本与审计记录；只能追加冲正/补偿分录并留审计 | **原则已明确**：append-only | 补管理员操作边界、数据库权限审查、冲正流程演练 |

建议优先级：先把 **账本重放**、**审计缺失**、**共享密钥泄露**、**GPS/BLE 欺骗** 四类做成可重复执行的验证项，因为它们分别对应当前最核心的完整性、可追溯性、内部边界与物理存证风险。

---

## 10. 责任人与评审节奏（最小治理基线）

为避免威胁模型停留在一次性文档，当前先采用最小责任机制：

| 范围 | 当前责任角色 | 最低评审节奏 | 触发再审条件 |
|------|--------------|--------------|--------------|
| **内部接口与共享密钥边界** | 仓库维护者 / API 负责人 | **每两周一次** | 新增 `/api/v1/internal/*` 路由、密钥轮换、鉴权方式变化 |
| **账本 / 结算 / 审计事件** | 仓库维护者 / 后端负责人 | **每次结算链路变更前后各一次** | 事务边界、幂等键、落账规则、审计写入路径变化 |
| **存证索引 / 对象存储边界** | 仓库维护者 / 存证负责人 | **每月一次** | 启用 `evidence_ref` 原始对象上传、签名 URL、桶策略变化 |
| **HDGP Adapter / 外部 Engine 边界** | 仓库维护者 / 集成负责人 | **每次接口契约变更时** | 新增上游字段、版本策略调整、失败处理语义变化 |
| **未来语义队列 / 人工复核链路** | 仓库维护者 / 安全评审负责人 | **Phase D/E 启动前必须复审** | 启用 `semantic_audit_jobs`、prompt 摘要、人工接管流程 |

最小执行规则：

- 每次评审至少回看本文件第 5–9 节，确认组件、边界、攻击面、缓解项与回放条目未失真。
- 若实现变更影响 `docs/spec/openapi-v1.0-draft.md`、`docs/spec/time-and-window-conventions-v1.0.md` 或 `docs/engineering/implementation-plan-v1.0.md`，须在同一轮变更中同步回填交叉引用。
- 若发现新入口尚无对应威胁项，先补本文档再合并实现，避免“代码先行、边界缺席”。

---

## 11. 当前仍缺失的威胁模型交付物

相对于本文件第 1 节的目标，当前仓库仍缺：

- **回放条目的实现绑定**：当前已补出最小 abuse case 清单，但多数条目尚未绑定到自动化测试、故障注入脚本或上线前检查表。
- **发布前安全检查闭环**：当前已有 checklist 与责任节奏，但尚未形成固定的发布前复核模板。

换言之，当前状态是：**已有范围设计，也已有实现承接，并已补出最小 STRIDE、数据流 / 信任边界、攻击面清单、缓解映射、红队回放清单与责任评审基线；下一步重点是把高优先级回放条目绑定到可执行验证。**

---

## 12. 建议的下一步最小补齐顺序

1. 先以当前 **STRIDE 轻量表**、**数据流 / 信任边界图**、**攻击面清单**、**缓解措施映射表**、**红队 / 滥用案例回放清单** 为基线持续维护，后续实现变更同步回填组件、边界与控制项。
2. 将高优先级 abuse cases 绑定到具体检查形式，优先覆盖：账本重放、审计缺失、共享密钥泄露、GPS/BLE 欺骗。
3. 为发布前检查补最小安全复核模板，至少覆盖内部接口、账本写入、对象存储、未来语义队列。
4. 当 Phase D / E 启动时，再把人工复核队列、LLM 队列与 prompt 注入威胁并入正式 threat model。

---

*维护：当前以仓库维护者为默认 owner；进入试点或首版发布前，将责任角色细化到具体值班人与复核清单。*