TypeORM 安全策略全解：漏洞报告渠道、信任边界划分与参数绑定的源码级实现

本文围绕 TypeORM 仓库根目录的 SECURITY.md 展开，系统讲解 TypeORM 项目的漏洞报告渠道与所需信息清单、项目明确承诺的安全保证与明确不承诺的边界（标识符/SQL 表达式属于"代码位"而非"数据位"），并结合参数绑定、标识符转义与 sql 标签模板的真实源码实现，说明这些承诺在代码层面是如何落地的、以及 SQL 注入回归测试如何持续验证它们。读完后你可以准确判断某类问题是否属于 TypeORM 的安全漏洞范畴，并能以维护者期望的格式提交高质量的漏洞报告。

漏洞报告渠道：不走公开 Issue

SECURITY.md 开篇即给出最重要的一条规则：不要通过公开的 GitHub issues、discussions 或 pull requests 报告安全漏洞，因为公开披露会让攻击者在补丁发布前就掌握漏洞细节。官方指定的报告渠道有两条：

1. GitHub Security Advisories（首选）：通过 TypeORM 仓库的私有安全公告入口提交；
2. 邮件兜底：如果你无法使用 GitHub，可以发送邮件至 [e-mail]。

提交报告时应提供的信息清单

为帮助维护者快速分诊（triage），文档要求报告尽可能包含以下八项内容。这也是安全社区报告 ORM 类库漏洞时的通用最佳实践，值得逐条对照：

#	信息项	说明
1	问题类型	例如缓冲区溢出、SQL 注入、跨站脚本（XSS）等
2	相关源文件的完整路径	问题表现所涉及的源码文件
3	受影响源码的位置	tag / branch / commit 或直接 URL
4	复现所需的特殊配置	特定数据库、驱动或连接选项
5	逐步复现说明	从干净环境到触发漏洞的完整步骤
6	概念验证（PoC）或利用代码	如可提供
7	影响分析	攻击者可能如何利用该问题

文档特别强调第 7 项——"问题的影响，包括攻击者可能如何利用它"——因为 TypeORM 的严重度评估（见下文 CVSS 一节）高度依赖攻击向量的界定，缺少影响分析的报告难以准确定级。

安全模型：TypeORM 明确承诺的保证

SECURITY.md 的核心是"Security Model and Scope"一节。它首先给出一个总纲：TypeORM 既是 ORM，也是 SQL 构建工具（SQL-building toolkit），因此"理解哪些输入是可信的，是判断什么构成漏洞的关键"。文档明确警告：提交报告前应先读这一节，超出范围（out of scope）的报告将引用该策略被直接关闭。

保证一：值位置的数据是安全的（Values are safe）

文档承诺：任何出现在"值位置"（value position）的不可信数据——实体值、条件值、命名参数、分页值——都会被绑定为查询参数，或被正确转义为字面量。 也就是说，把用户输入放进"值"里，TypeORM 保证它不会被解释为 SQL。

这个承诺在源码中是真实落地的，可以从三条证据链印证：

1）参数绑定由每个驱动统一实现。 驱动接口 Driver.ts 声明了 createParameter(parameterName: string, index: number): string 抽象方法，各数据库驱动逐一实现：PostgreSQL 见 PostgresDriver.ts、MySQL 见 MysqlDriver.ts、Oracle 见 OracleDriver.ts、CockroachDB 见 CockroachDriver.ts 等。所有驱动把参数统一替换成占位符并收集到参数数组，交由驱动的原生绑定机制传输，从而从根本上杜绝值位置的注入。

2）SQL 标签模板同样强制参数化。 SqlTagUtils.ts 中的 buildSqlTag 函数处理 sql`` 标签模板：普通表达式统一走 driver.createParameter 生成占位符并 push 进 parameters 数组（见 SqlTagUtils.ts）；返回数组的函数表达式会展开为参数列表；唯一例外是函数直接返回字符串——该字符串按"开发者写的 SQL 片段"原样拼接，这正好对应下文的"标识符/表达式是代码"边界。

3）回归测试用恶意输入持续验证该保证。 test/functional/query-builder/sql-injection/sql-injection.test.ts 定义了一组经典攻击载荷，包括 '; DROP TABLE post; --、test' OR '1'='1、' UNION SELECT * FROM post --、'/**/OR/**/1=1-- 等，把它们作为命名参数值传入 andWhere 后，通过 verifyIntegrity（第 59-64 行）断言表中记录数仍为 2——即任何 DROP/DELETE/UNION 都不得生效。该测试在多驱动上运行（仅禁用 mongodb 与 spanner），是"值安全"承诺的自动化守门员。

保证二：来自数据库的内容一律按数据对待

文档的第二项承诺：从数据库返回的一切——值、结果集、数据库报告的元数据——在 TypeORM 处理它们的地方都被当作不可信数据处理，典型场景有两处：

• 实体水合（entity hydration）：查询结果映射回实体对象时，字段名来自数据库内容的部分必须被当作数据处理，防止数据库中的恶意键名污染原型链；
• 由数据库状态生成的代码与文件：包括 CLI 生成的迁移代码、实体文件等。文档特别指出，注入到"从数据库状态生成的代码/文件/命令"中属于安全漏洞。

这一条对应仓库中 CLI 生成类命令（如 src/commands/ 下的 Migration 生成、实体创建等）——它们从数据库 schema 读取表名、列名并写入生成的 TypeScript 文件，因此生成路径上的内容必须被视为不可信输入。

在范围内的漏洞（In scope）清单

在上述两项保证出现缺陷时，即构成安全漏洞。文档给出了明确的在范围清单，可以逐条对照判断：

• 不可信运行时数据经文档化 API 的文档化用法到达生成查询时未转义——对非 SQL 驱动（如 MongoDB）则表现为"被解释为查询操作符而非值"；这包括 TypeORM 内部查询生成过程中拼接实体数据的情形；
• 驱动中参数绑定或字面量转义的缺陷；
• TypeORM 施加标识符转义之处的转义缺陷（注意限定词"where TypeORM applies it"——只在 TypeORM 承诺转义标识符的位置）；
• 数据库派生内容在 TypeORM 输出中逃逸其上下文：处理查询结果时的原型污染或代码执行，或注入到由数据库状态生成的代码/文件/命令中；
• 既有原型污染原语的放大：查询构建、结果处理或代码生成路径中的对象遍历（object iteration）不得拾取继承键，使得已被污染的运行环境无法通过 TypeORM 篡改生成的查询或输出的代码。文档同时注明：污染源头本身属于引入它的库/应用的漏洞，此类报告按降低后的严重度评估。

安全边界：TypeORM 明确不承诺什么

"不保证什么"与"保证什么"同样重要。文档用四个小节划定了信任边界，理解它们是避免无效报告的关键。

1. 标识符与 SQL 表达式是代码，不是数据

这是最核心的一条边界。文档指出：QueryBuilder 的职责就是构建 SQL，凡是文档写明接受标识符或 SQL 片段的参数——投影（projections）、条件字符串、排序与分组表达式、别名、计算表达式——都会按开发者原样输出，因为"表达任意 SQL 正是这些位置的用途"。它们无法在不破坏文档化功能的前提下转义，API 也从不承诺这些位置注入安全。

源码可以印证这一点：QueryBuilder.ts 中的 escape() 方法只做一件事——委托给驱动 this.dataSource.driver.escape(name)，用于表名、列名等 TypeORM 自身管理的标识符；而 where/orderBy/select 中开发者传入的表达式字符串则原样拼入查询。

由此得出文档的结论：把不可信输入传进这类位置，是应用层漏洞，等价于把用户输入拼进裸 SQL 字符串。要求应用层犯此错误的报告不在范围内。文档给出的工程准则很直接：所有不可信数据一律走参数绑定；永远不要从用户输入构建标识符或表达式。

2. Schema 定义是可信代码

实体定义、迁移对象及其选项都属于**开发者在编译期/设计期编写（design-time inputs）**的输入。由它们生成的 DDL 不针对敌对 schema 做加固——"攻击者若能控制你的 schema 定义，就已经控制了你的应用"。因此，以"不可信输入能到达 schema/迁移定义"为前提的报告不在范围内。文档补充了一条务实的例外：仍然欢迎"仅对标识符位置做转义"这类纵深防御性质的 PR，但按常规加固变更处理，而不是安全公告（advisory）。

3. 配置是可信代码

连接选项（connection options）、数据源配置（data source configuration）、CLI 参数与迁移文件都是开发者编写的输入，地位等同于应用源码本身。要求攻击者能控制这些前提的报告同样不在范围内。对应仓库中如 DataSourceOptions.ts、ormconfig.sample.json 所代表的配置面，均视为开发者掌控。

4. 运行时防护是尽力而为，不是安全边界

TypeORM 有时会加入一些校验，在应用错误到达数据库前就捕获它。文档明确这些防护只是叠加在上述信任模型之上的便利设施（conveniences）：它们不移动信任边界，也不可能完整。若某个防护被绕过、且绕过结果只是恢复了此前文档化行为，那是普通 bug——请提普通 issue，而不是按漏洞报告。

严重度评估：CVSS 应反映 TypeORM 的合同

文档对定级给出两条规则：

• CVSS 评分应反映 TypeORM 自身的合同，而不是一个"把不可信输入硬塞进代码位"的假想应用。若报告的攻击向量是"应用把攻击者可控输入传进了标识符/表达式/schema 槽位"，它描述的是应用漏洞，会按此评估；
• 提交前请检查现有 advisory 与近期版本发布记录——同一机制的重复报告将按重复合并关闭。

报告后会发生什么：响应承诺

SECURITY.md 末尾给出明确的服务预期：

• 72 小时内确认收到报告（aim to acknowledge reports within 72 hours）；
• 分诊后，维护者在私有 fork 中推进修复，避免补丁公开前泄露细节；
• 视情况协调带 CVE 编号的公开披露；
• 视复杂度，尽快发布补丁版本。

小结：一份面向用户的"安全自查"

把 SECURITY.md 的信任模型翻译成工程实践，可归纳为三条可操作准则：

1. 数据走参数位：用户输入只出现在命名参数/实体值/条件值等"值位置"，仓库内的 sql-injection 回归测试 已证明这条路径在多驱动下对经典注入载荷免疫；
2. 表达式位不接用户输入：select/where 条件字符串/orderBy 等标识符与表达式槽位只接受开发者常量，需要动态排序/过滤时应使用白名单映射而非字符串拼接；
3. 按范围提交报告：符合"值安全"或"数据库内容安全"两项保证被破坏的问题才构成 TypeORM 漏洞，且报告需携带上文八项信息清单，严重度陈述需与 TypeORM 的合同对齐。