3.6 KiB
3.6 KiB
Proposal: single-react-mysql-readonly-tool
Problem
阶段 1 已冻结 query_mysql 的逻辑请求和有界结果契约,但当前仓库没有一个能把 SQL 安全地转换为可执行查询的实现。直接把 Agent 生成的 SQL 交给 JDBC 会允许写操作、元数据探测、通配符泄漏、allowlist 绕过和无界结果。
Proposed change
- 引入 JSqlParser 4.6,解析单条 SQL 并对保守的 SELECT 子集执行 fail-closed AST 校验。
- 增加逻辑数据源定义和静态
schema -> table -> column精确 allowlist;Agent 只能传逻辑数据源 ID。 - 增加参数绑定、占位符数量校验、函数 allowlist、显式列校验、JOIN/过滤/分组/排序字段校验和受控 LIMIT。
- 增加 JDBC 只读执行器:只使用配置映射的 DataSource,设置
readOnly、PreparedStatement、setMaxRows、查询超时,并在 Run 取消时中止执行。 - 增加 MySQL 结果 projector:限制行数、单元格和总 UTF-8 字节,脱敏敏感列,产生
MysqlToolResult和NO_EVIDENCE。 - 通过阶段 3A
ToolBoundary接入 canonical invocation store、Run budget、生命周期、evidence_status和框架tool_call_id。 - 把
scripts/query_mysql.py收敛为仅允许 SELECT/受控 SHOW 的只读查询脚本,移除默认外部连接参数和 commit 分支;凭据与连接信息全部从环境变量读取。
Scope
In scope
- SQL AST validator and validated query plan.
- Static logical data-source/allowlist model.
- JDBC read-only executor abstraction and implementation.
- MySQL result projector and ToolBoundary adapter.
- Security, truncation, timeout/cancellation, no-evidence and boundary tests.
- Query script safety cleanup required by the ISS-014 security prerequisite.
Out of scope
- Diagnosis Agent cutover or public Chat/AIOps/SSE changes.
- Querying the application's own persistence database through the Agent-facing Tool.
- Metadata discovery (
SHOW TABLES,SHOW COLUMNS,DESCRIBE,information_schema). - Tenant/row-level authorization, dynamic allowlists, arbitrary SQL functions, real production business datasource provisioning.
Frozen SQL subset
- One
SELECTstatement only. - Explicit projection columns;
COUNT(*)is the only star exception. INNER JOINandLEFT JOIN, normal predicates,GROUP BY,HAVING,ORDER BYand parameter placeholders.- No
WITH, subquery,UNION, window function,CROSS JOIN, write statement, metadata query, transaction control, dangerous function, or unknown AST node.
Constraints and risks
- Parser acceptance is not authorization: every table and column used by projection, predicates, joins, grouping and ordering must pass the independent allowlist.
- Unknown data source, schema, table, column, function, placeholder mismatch or parser failure fails closed before JDBC execution.
- JDBC row/cell/byte limits are enforced in addition to ToolBoundary limits; oversized results are projected with
truncated=trueor become a safe error when no valid bounded result can be produced. - The adapter is not wired into the existing public runtime in this stage; later Diagnosis Agent work will select it through the internal Harness application use case.
Acceptance direction
- Valid explicit-column SELECT and
COUNT(*)pass AST and allowlist validation. - Write statements, metadata, wildcard projection, nested/compound queries, unknown AST, allowlist bypass and placeholder mismatch are rejected without executor invocation.
- JDBC executor uses read-only prepared statements, max rows, timeout and cancellation.
- Agent receives only bounded
MysqlToolResult; raw JDBC rows remain Harness-only canonical data.