vburnz/specimen-return-surface-analysis

# 返回面分析 **在返回路径上寻找攻击面。** 返回面分析是一种防御性安全审查启发法，用于在系统中分析较少的方向——即数据、元数据、错误、工件或工具输出从跨边界操作返回的路径——上寻找风险。 大多数系统会验证正向路径，因为它是显式的：请求输入、API 参数、出站主机名、工具参数、事件负载、依赖版本。 而返回路径往往是隐式的：响应体、头部、错误、生成的工件、工具结果、刷新令牌、缓存条目和处理程序输出。 本仓库提供了一个可重复的检查清单，用于识别正向路径与返回路径之间的信任差异、评估风险、区分发现与非发现，并选择修复模式。 ## 启发法 当一个系统对正向路径的验证比返回路径更严格时，验证较少的返回路径应被视为一个独立的攻击面。 返回路径的风险往往随着以下因素而增加： 1. 验证严格性的差异程度 2. 所跨越边界的敏感性 3. 接触返回数据的消费者数量及其权限 4. 返回的数据是否被渲染、解析、缓存、信任或执行 这是一种启发法，不是定理，也不能替代完整的威胁模型。它的价值在于将注意力引导到正向路径分析常常遗漏的一类错误上。 ## 用例 返回面分析在审查以下内容时非常有用： - Web 代理和 SSRF 缓解措施 - API 网关和错误处理 - LLM 代理和工具输出 - 事件系统和处理程序返回值 - 构建系统和生成的工件 - 身份验证和令牌委托流程 - 缓存、渲染器、解析器和其他信任边界交叉点 ## 直观示例 一个常见的错误是，因为当前请求路径是安全的，就将数据库输出视为可信。 想象这样一个 API 端点： ``` GET /users/:id ``` 请求到达后，服务会仔细验证 `id` 参数： - 必须是整数 - 必须属于经过身份验证的租户 - 通过参数化查询传递 - 在查询运行前进行授权检查 正向路径看起来很稳固。 ``` request parameter -> validation -> authorization -> parameterized query -> database ``` 但随后响应返回： ``` database row -> JSON response -> frontend render ``` 而这个返回路径可能几乎没有受到审查。 错误在于假设： ``` "It came from our database, so it is trusted." ``` 这个假设可能是错的。 数据库可能包含数月前由旧版本（存在漏洞）的应用程序写入的数据。也许之前的某个 bug 允许存储了不安全的 HTML、格式错误的 JSON 片段、危险的 URL、序列化对象、提示注入文本或意外的元数据。该 bug 后来被修复了，因此新写入的数据是干净的，但旧的被污染的行仍然存在。 当前版本验证新的请求参数。它并不一定验证返回的旧数据。 所以真正的流程是： ``` old attack request -> stale stored data -> later safe-looking API request -> unvalidated response -> vulnerable sink ``` 脆弱的时刻不是当前请求进入数据库。 脆弱的时刻是过时的、受攻击者影响的数据返回。 返回面分析会问： 在这种情况下，返回面包括： - 返回给 API 的数据库字段 - JSON 序列化边界 - 前端渲染接收点 - 从响应中填充的缓存 - 消耗数据的日志或分析管道 - 将返回字段视为可信的下游服务 修复不仅仅是“验证输入”。修复是在每个新的边界将返回的数据视为不可信： - 为将要使用的接收点编码输出 - 在重用前验证存储的记录 - 迁移或隔离遗留的被污染数据 - 对返回的对象强制执行模式 - 避免将数据库内容渲染为可执行或可解释的内容 - 增加对违反当前不变性的旧行的检测 正向路径可能已打补丁。 返回路径可能仍在承载着过去。 ## 操作流程 ### 0. 识别中介 寻找具有以下形式的操作： ``` input -> action(derived_from_input) -> process(result) -> output ``` `action` 跨越了一个边界：网络、进程、租户、权限级别、信任区域、模型上下文、文件系统、缓存、解析器、渲染器或构建阶段。 ### 1. 衡量信任差异 比较正向路径的处理方式与返回路径的处理方式。 | 维度 | 正向路径 | 返回路径 | 问题 | | :----------- | :------------------------------------------------------ | :--------------------------------------------------------------------- | :----------------------------------------------------------- | | 验证 | 输入是否经过模式检查、类型检查或允许列表检查？ | 返回的数据是否经过验证？ | 结果在使用前是否受到约束？ | | 清理 | 输入是否经过转义、编码或过滤？ | 输出是否经过转义、编码或过滤？ | 清理是否与接收点上下文匹配？ | | 访问控制 | 是否应用了身份验证、范围、速率限制或租户检查？ | 结果的暴露是否受到限制？ | 返回的数据是否能触及更广泛或更高信任度的受众？ | | 日志记录 | 输入是否被审计或度量？ | 返回路径是否被记录？ | 防御者能否看到返回端的滥用行为？ | | 解释/处理 | 输入是否被视为数据？ | 返回的内容是否被解析、渲染、缓存、信任或执行？ | 返回路径是否将数据升级为权限/权威？ | 当正向路径被仔细约束，而返回路径被假设为安全时，就存在高信任差异。 ### 2. 追踪高差异方向 对于每个返回值，问： | 检查项 | 问题 | | :------------- | :------------------------------------------------------------------------------------------------ | | 代理/转发 | 结果是否被转发给原始调用者或其他用户？ | | 元数据复制 | 头部、状态码、声明、标签或其他元数据是否被复制？ | | 信任假设 | 代码是否将结果视为来自可信来源？ | | 区域跨越 | 返回的数据是否从低信任区域跨越到高信任上下文？ | | 错误泄露 | 错误是否泄露了秘密、拓扑结构、堆栈跟踪、路径或内部状态？ | | 状态污染 | 结果是否会影响缓存、配置、数据库状态、模型上下文、环境或构建输出？ | | 解释/执行 | 结果是否被解析、渲染、编译、执行、反序列化或注入到另一个解释器中？ | ### 3. 评估风险 使用 [`docs/scoring.md`](docs/scoring.md) 中的评分标准进行分诊。 不要仅凭信任差异本身就认定为漏洞。一个可报告的发现通常需要一条可达的路径、一个有意义的信任边界以及具体的影响。 ## 跨领域示例 | 领域 | 设计路径 | 涌现的返回路径 | 信任差异 | | :------------- | :------------------------------------------------------ | :------------------------------------------------------ | :------------------------------------------------------------------------------ | | Web 安全 | 出站请求目标在允许列表中 | 响应体或头部被代理给客户端 | 目标选择受到约束，但返回的内容被信任 | | API 设计 | 请求模式经过验证 | 错误响应未结构化且泄露内部信息 | 请求格式有契约，但错误格式是临时性的 | | 数据库 | 查询参数被转义或参数化 | 结果集在没有上下文编码的情况下被渲染 | 查询受到保护，但存储的内容被信任 | | LLM 工具调用 | 工具输入根据模式进行验证 | 工具输出被注入到模型上下文中 | 工具调用受到约束，但返回的文本变成了类似指令的内容 | | 事件系统 | 事件负载在发布时经过验证 | 处理程序返回值未经验证即被传播 | 发布路径有门控，但处理程序输出被假设为良性 | | 构建系统 | 依赖版本和哈希被锁定 | 生成的工件未经完整性检查即被使用 | 输入被固定，但输出因为来自构建过程而被信任 | | 身份验证委托 | 出站令牌请求使用范围参数 | 令牌响应未经验证声明即被接受 | 请求受到约束，但返回的权限/权威被信任 | ## 检测信号 寻找如下所示的代码或设计模式： ``` input is allowlisted -> returned output is unfiltered input goes through middleware -> output bypasses middleware input is logged -> return path is not logged input has a concrete type/schema -> output is any/string/blob input errors are handled carefully -> output errors are passed through request metadata is stripped -> response metadata is copied tool arguments are validated -> tool result is injected verbatim ``` 一个简洁的审查规则： ``` If the system validates what goes out more than what comes back, review what comes back as attacker-influenced input. ``` ## 反模式 | 声明 | 失败模式 | 更好的框架 | | :--------------------------------------- | :--------------------------- | :--------------------------------------------------------------------------------------------------------- | | “我已经分析过这个了。” | 方向性盲点 | 你分析了正向路径。返回路径是另一条路径。 | | “响应来自内部源。” | 信任传递假设 | 请求去了系统允许或用户影响的地方。响应仍然需要验证。 | | “它只是透传。” | 透传谬误 | 透传意味着很少或没有返回路径强制执行。这可能就是问题所在。 | | “格式已经验证过了。” | 格式/内容混淆 | Content-Type 和模式检查不能保证在接收点处的语义安全。 | | “响应已经清理过了。” | 清理范围错误 | 清理必须与接收点匹配：HTML、头部、JSON、Shell、SQL、提示、缓存、解析器或模型上下文。 | ## 本仓库包含的内容 - [`docs/return-surface-analysis.md`](docs/return-surface-analysis.md)：完整方法 - [`docs/scoring.md`](docs/scoring.md)：实用分诊标准 - [`docs/false-positives.md`](docs/false-positives.md)：何时不应报告 - [`docs/remediation-patterns.md`](docs/remediation-patterns.md)：缓解模式 - [`docs/domain-checklists.md`](docs/domain-checklists.md)：领域特定审查提示 - [`docs/release-checklist.md`](docs/release-checklist.md)：发布清单 - [`docs/trace-return-path.md`](docs/trace-return-path.md)：针对旧工作标题的旧名称重定向 - [`examples/web-proxy.md`](examples/web-proxy.md)：代理和 SSRF 风格的返回路径 - [`examples/llm-tool-output.md`](examples/llm-tool-output.md)：LLM 工具输出作为不可信输入 - [`examples/api-error-leakage.md`](examples/api-error-leakage.md)：结构化输入，非结构化错误 - [`examples/build-artifact-integrity.md`](examples/build-artifact-integrity.md)：构建输出和工件信任 完整的归档内容请参见 [`MANIFEST.md`](MANIFEST.md)。 ## 负责任使用 本项目旨在用于防御性审查、授权测试、安全设计分析和漏洞分诊。 不要测试你不拥有或未获许可评估的系统。如果返回路径分析揭示了第三方系统中的漏洞，请遵循协调披露，并在受影响方有合理机会进行调查和修复之前，避免发布利用细节。 ## 状态 版本：`0.1.0`，包含用于清晰性的散文和合成示例的披露分析。 待发布：包含对前沿模型影响的复制和评估数据。 此启发法有意设计得小巧。它应该易于应用、易于证伪、易于改进。 ## 许可证 MIT。参见 [`LICENSE`](LICENSE)。 ## AI 辅助与披露 本项目是在 AI 辅助下开发的。 返回面分析技能及支持材料在 AI 系统的帮助下生成、编辑和审查。该方法已通过合成示例、审查场景和对抗性提示进行测试，以评估其是否能产生一致且有用的安全审查指导。 除非另有说明，否则由此方法产生的报告或示例可能是 AI 生成或 AI 辅助的。AI 生成的分析应视为审查辅助工具，而非权威性的安全判定。 所有发现应由合格的人工审查员独立验证后，方可用于漏洞报告、生产安全决策、公开披露或修复规划。

标签：API安全, API网关安全, JSON输出, SSRF防护, Web代理安全, 事件系统安全, 信任边界, 启发式方法, 安全审查, 工具输出安全, 应用程序安全, 攻击面分析, 构建系统安全, 缓存安全, 网络安全, 身份验证安全, 返回路径分析, 防御性安全, 隐私保护