CocoIndex 目标连接器输入安全实战：标识符校验、参数化查询与值转义

CocoIndex 目标连接器输入安全实战标识符校验、参数化查询与值转义【免费下载链接】cocoindexIncremental engine for long horizon agents Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/co/cocoindex导读本文是 CocoIndex 仓库中 target-connector 技能 配套的输入安全指南聚焦目标连接器Target Connector在把用户提供的表名、列名、索引名等标识符与记录 ID、键值等数据值拼进外部系统查询语句时如何防止注入攻击并保证语义正确。读完本文你将掌握三类可复用的安全手段——API 入口处的标识符白名单校验、数据值的参数化绑定、无法参数化场景下的类型保留转义并能在 CocoIndex 各内置连接器SurrealDB、PostgreSQL、Neo4j、SQLite 等的源码中找到对应的权威实现与测试证据。1. 为什么目标连接器需要输入安全目标连接器的本质工作是把 CocoIndex 声明式目标状态TargetState同步到外部系统对比期望状态与历史追踪记录后把差异转成对数据库、文件系统或云存储的增删改操作参考 SKILL.md 中的 TargetHandler / TargetActionSink 说明。同步过程免不了把用户提供的名字表名、列名、索引名和数据值记录 ID、主键、内容写入查询语句于是出现两类风险注入风险名字或值中包含引号、分号、注释符等特殊字符时直接拼接会导致查询被改写甚至执行攻击者构造的语句。语义正确性风险即使没有安全威胁类型差异如整数123与字符串123被错误处理也会导致数据错位。CocoIndex 的解决思路高度统一名字走白名单校验值走参数化绑定参数化不了的内联场景走保留类型的转义。下文按这三个层次逐一展开并在每一节给出仓库内的实现与测试佐证。2. 标识符校验在 API 入口用白名单正则拒绝一切非法名字2.1 核心原则入口处校验而不是查询构造时转义用户提供的名字表、列、索引会被插值进查询中充当标识符。标识符在大多数数据库里既无法使用绑定参数如 PostgreSQL 的$1、Cypher 的$param只能绑定值不能绑定标识符单纯靠加引号转义又难以堵死所有边界例如名字本身包含双引号字符。因此正确做法是在 API 入口尽早校验——只要不匹配简单标识符的白名单就立即抛错让非法名字根本走不到查询构造这一步。input_safety.md 给出了标准实现import re _IDENTIFIER_RE re.compile(r^[a-zA-Z_][a-zA-Z0-9_]*$) def _validate_identifier(name: str, kind: str) - None: Raise ValueError if name is not a safe identifier. if not _IDENTIFIER_RE.match(name): raise ValueError( fInvalid {kind}: {name!r}. fMust match [a-zA-Z_][a-zA-Z0-9_]*. )规则^[a-zA-Z_][a-zA-Z0-9_]*$的含义非常明确首字符只能是字母a-zA-Z或下划线_排除以数字开头的名字后续字符只能包含字母、数字、下划线空字符串、包含空格、连字符、点号、反引号、分号等任何其他字符都会被拒绝。校验必须放在每一个接受名字的公开方法里覆盖表名、列名、索引名、主键、schema 名等所有入口def table_target(self, table_name: str, ...) - ...: _validate_identifier(table_name, table name) ... class TableSchema: def __init__(self, columns: dict[str, ColumnDef], ...) - None: for col_name in columns: _validate_identifier(col_name, column name) ...2.2 仓库实现证据SurrealDB 连接器本文档指定的权威实现位于 python/cocoindex/connectors/surrealdb/_target.py。它一字不差地落地了上述模式_IDENTIFIER_RE re.compile(r^[a-zA-Z_][a-zA-Z0-9_]*$) def _validate_identifier(name: str, kind: str) - None: Validate that *name* is a safe SurrealQL identifier. Raises :class:ValueError if the name contains characters that are not alphanumeric or underscore, or starts with a digit. if not _IDENTIFIER_RE.match(name): raise ValueError( fInvalid SurrealDB {kind}: {name!r}. Must match [a-zA-Z_][a-zA-Z0-9_]*. )随后在每一处公开 API 入口调用它同一文件内TableSchema.__init__对每个列名校验L356-L359table_target()校验表名L1291relation_target()校验关系表名以及 FROM/TO 两端的表名L1341-L1347declare_vector_index()校验向量索引字段名与索引名L1130-L1133。注意入口处校验的含金量即使_create_table/_apply_column_actions在构造DEFINE TABLE、DEFINE FIELD等 SurrealQL 时直接 f-string 拼接这些名字L959、L1003、L1015、L1038、L1051由于所有名字都已在入口通过白名单拼接是安全的——这正是提前校验代替事后转义的架构价值。2.3 全仓库的一致性实践这一模式并非 SurrealDB 独有而是整个python/cocoindex/connectors/目录的共同约定仅正则与错误信息略有差异连接器实现位置正则 / 特点PostgreSQLpython/cocoindex/connectors/postgres/_target.py^[A-Za-z_][A-Za-z0-9_]*$注释明确指出仅靠双引号转义无法防注入只要不是普通未加引号标识符就直接报错PostgreSQL Sourcepython/cocoindex/connectors/postgres/_source.py额外允许$字符^[a-zA-Z_][a-zA-Z0-9_$]*$用于处理带$的列名Neo4j / FalkorDBpython/cocoindex/connectors/neo4j/_cypher.pyFalkorDB 复用同一模块纯 Cypher 生成模块、无驱动依赖文档注释明确Cypher 标签、属性名、索引名无法用参数绑定必须在 API 入口校验、绝不在查询构造时转义SQLitepython/cocoindex/connectors/sqlite/_target.py同一正则模式Snowflake / BigQuerypython/cocoindex/connectors/snowflake/_target.py、python/cocoindex/connectors/bigquery/_target.py校验 dataset / schema / 列名Dorispython/cocoindex/connectors/doris/_target.py对数据库、表、列、索引名逐一校验ZVecpython/cocoindex/connectors/zvec/_target.py校验 collection / 字段名可见CocoIndex 所有目标连接器共享同一输入安全约定是有源码依据的结论。3. 数据值一律使用参数化查询绑定变量标识符只能靠白名单但数据值插入的内容、记录 ID 对应的值、过滤条件中的键值完全不同——它们应当永远通过参数化查询绑定变量传递绝不直接插值进查询字符串。3.1 三种主流写法对照input_safety.md 给出了三种不同数据库的参数化写法# Good — parameterized await conn.execute(INSERT INTO t (name) VALUES ($1), value) # PostgreSQL conn.execute(INSERT INTO t (name) VALUES (?), (value,)) # SQLite await conn.query(UPSERT t:id CONTENT $content, {content: val}) # SurrealDB # Bad — string interpolation await conn.execute(fINSERT INTO t (name) VALUES ({value}))参数化的收益驱动会在协议层把值与语句分离值中的引号、分号、反斜杠等字符只被当作数据不可能逃逸成 SQL/SurrealQL/Cypher 语法从根上消除注入面。3.2 仓库中的参数化实践SQLite 连接器_apply_actions中通过?占位符绑定值例如INSERT INTO t (name) VALUES (?)与(value,)的成对使用参见 python/cocoindex/connectors/sqlite/_target.py。PostgreSQL 连接器大量使用 asyncpg 的$1绑定。PostgreSQL 还额外处理了一类非注入但致命的边界——text/jsonb列不允许包含 NULU0000字符连接器通过_strip_nul/_sanitize_nul在绑定前递归清除字符串、dict 键与嵌套容器中的 NULpython/cocoindex/connectors/postgres/_target.py。对应测试 python/tests/connectors/test_postgres_target.py 专门验证text[]数组元素里的 NUL 也会被清除否则 asyncpg 会抛出ValueError: string cannot contain NUL (0x00) characters。Neo4j 连接器Cypher 生成模块 python/cocoindex/connectors/neo4j/_cypher.py 的模块级约定是所有值一律通过$-参数绑定例如build_node_upsert生成MERGE (n:Label{pk: $key_0, ...}) SET n $propsL90-L105键值与属性值全部走$key_N/$props参数绝无值内联。4. 值转义参数化行不通时的最后手段4.1 何时必须内联值有些查询语言的语法要求值出现在无法参数化的位置。文档以 SurrealDB 的table:id记录 ID 语法为例UPSERT person:alice CONTENT {...}中alice是记录 ID 的一部分不能绑定为$1只能内联。此时需要自己写转义函数。4.2 两条硬性要求保留类型区分整数123与字符串123在语义上可能完全不同——SurrealDB 中person:123数字 ID与person:123字符串 ID指向不同的记录。转义逻辑必须根据 Python 类型分别输出不能一律套引号。转义引号字符目标使用反引号引用字符串时值内部的反斜杠与反引号都必须转义防止提前闭合引用。文档给出的标准实现def _format_record_id(value: Any) - str: Format a record ID for inline use, preserving type. if isinstance(value, (int, float)): return str(value) # bare numeric: 123, 3.14 s str(value) s s.replace(\\, \\\\).replace(, \\) return f{s} # quoted string: alice4.3 仓库实现与单元测试这一函数在 python/cocoindex/connectors/surrealdb/_target.py 中逐字存在并被_SharedRecordApplier._apply_actions用于构造批量 UPSERT / DELETE / RELATE 语句L493-L531记录 ID 一律经由_format_record_id内联内容字段则用json.dumps(content, defaultstr)序列化后内联进CONTENT子句。对应的无数据库单元测试位于 python/tests/connectors/test_surrealdb_target.py逐条验证类型保留与转义正确性输入期望输出验证点alicealice普通字符串反引号包裹hastick| hastick 反引号被转义rback\slashback\\slash反斜杠被转义4242整数保持裸数字3.143.14浮点保持裸数字123123字符串123必须与整数123区分空字符串仍为合法引用顺带一提转义是按目标语法定制的LanceDB 的 DataFusion SQL 删除过滤器需要把单引号翻倍its→its而反斜杠原样透传——见 python/tests/connectors/test_lancedb_target.py 的_escape_sql_string测试。转义规则永远取决于目标方言写连接器时必须按目标语法单独实现与测试。5. 测试策略单元测试管转义集成测试管往返输入安全逻辑必须可验证。input_safety.md 给出了两层测试要求5.1 不需要数据库的单元测试对安全辅助函数校验、转义与 API 入口行为直接做断言合法标识符通过非法标识符抛出ValueError转义对特殊字符、空字符串、数值类型产生正确输出API 入口拒绝坏名字如TableSchema(columns{bad-name: ...})。这些测试在仓库中有两个典型体现SurrealDB 侧python/tests/connectors/test_surrealdb_target.py——TestValidateIdentifier用参数化测试验证users、_private、T1、a_b_c通过而my-table、123abc、空串、has space、back、semi;colon、a.b全部抛ValueErrormatchInvalid SurrealDBTestValidateIdentifierAtApiEntryPoints则直接验证TableSchema、table_target、relation_target 这三个公开入口会拒绝坏名字。Neo4j 侧python/tests/connectors/test_neo4j_target.py——同样的白名单参数化测试非法集合额外包含X-Y并验证MERGE (n:Document{filename: $key_0})这类生成结果里标识符以反引号包裹、值以参数绑定L115-L129。5.2 需要真实数据库的集成测试当目标数据库可用时应补充特殊字符值走完整 upsert/select 往返的集成测试写入包含引号、反斜杠、Unicode 的记录 ID 与内容再读回比对确认转义/参数化在实际查询链路中没有破坏数据。这类测试的框架可参考 python/tests/connectors/test_surrealdb_target.py 中requires_surrealdb守卫的集成用例以及 SKILL.md 的测试章节 给出的test_insert_and_update标准模式依赖缺失时用pytest.mark.skipif跳过保证纯环境也能跑完所有安全单元测试。6. 编写新目标连接器时的检查清单结合 input_safety.md 与仓库中十几个连接器的既有实践开发新目标连接器时可逐项自检入口全覆盖表名、列名、索引名、主键、schema/dataset 名等所有接受用户名字的公开方法是否都调用了_validate_identifier参考 surrealDB 的调用点分布值一律参数化数据值是否全部走绑定变量$1/?/$name/$props还是存在直接 f-string 内联值的地方内联必转义且保留类型无法参数化的内联位置如 SurrealDB 记录 ID、LanceDB 删除过滤器是否按目标方言转义引号字符并区分数值与字符串类型先校验后拼接拼接 DDL/DML 时使用的名字是否都已在更早的入口通过白名单而不是在拼接处做转义补救测试双轨并行无需数据库的单元测试是否覆盖校验/转义的全部边界特殊字符、空串、数值类型、入口拒收有数据库时是否补上特殊字符值的往返集成测试遵循这套约定后你的连接器将与 PostgreSQL、SQLite、SurrealDB、Neo4j 等内置连接器处于同一安全水位标识符注入在入口被白名单拦死值注入被参数化消解方言强制的内联位置有类型保留的精确转义兜底。7. 延伸阅读本文规范文档dev/agent-skills/target-connector/input_safety.md连接器实现总纲TargetHandler / TargetActionSink / 子目标失效策略 / 幂等动作dev/agent-skills/target-connector/SKILL.md权威实现一SurrealDB 连接器 python/cocoindex/connectors/surrealdb/_target.py含标识符校验、记录 ID 类型保留转义、批量 UPSERT/RELATE 语句构造权威实现二Neo4j 纯 Cypher 生成模块 python/cocoindex/connectors/neo4j/_cypher.py展示标识符入口校验 值参数绑定的模块级约定测试证据python/tests/connectors/test_surrealdb_target.py、python/tests/connectors/test_neo4j_target.py、python/tests/connectors/test_postgres_target.py【免费下载链接】cocoindexIncremental engine for long horizon agents Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/co/cocoindex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考