2.6 KiB
mysql-readonly-tool Specification
Purpose
Define a fail-closed, parameterized, read-only MySQL evidence Tool that reuses ToolBoundary and exposes only bounded ACI results.
Requirements
Requirement: SQL validation SHALL fail closed on a conservative SELECT subset
The Tool SHALL parse exactly one SQL statement with JSqlParser and SHALL accept only a single SELECT with explicit projection columns, supported predicates/grouping/ordering, INNER JOIN or LEFT JOIN, parameter placeholders and allowlisted functions. It SHALL reject writes, CTEs, subqueries, set operations, wildcard projections except COUNT(*), metadata discovery, unsupported joins/functions, FOR UPDATE, multiple statements and unknown/ambiguous AST structures.
Requirement: Data-source and identifier authorization SHALL use exact independent allowlists
The Tool SHALL accept only a logical data_source ID and SHALL authorize every schema, table and column used in projection, join, predicate, grouping and ordering against the configured exact allowlist. It SHALL reject unknown data sources, schemas, tables, columns, aliases and ambiguous unqualified columns. Agent input SHALL NOT provide JDBC coordinates or authorization controls.
Requirement: Parameter binding and JDBC execution SHALL be read-only and bounded
The executor SHALL use a configured logical datasource, a read-only JDBC connection, PreparedStatement parameter binding, query timeout, max rows and Run cancellation/deadline checks. Placeholder count SHALL exactly match params. The executor SHALL not expose connection details or raw JDBC failures to the Agent.
Requirement: MySQL projection SHALL be bounded and evidence-aware
The projector SHALL expose only ordered columns, bounded JSON-safe rows, returned count and truncation. It SHALL enforce row, cell and total UTF-8 limits, redact sensitive column values, return NO_EVIDENCE for a successful empty result, and never expose raw JDBC metadata or credentials.
Requirement: MySQL Tool SHALL reuse canonical Harness ownership
The adapter SHALL pass the exact framework tool_call_id and RunContext through the existing ToolBoundary and canonical invocation store. It SHALL not create a second ID, use a parallel store, return raw SQL results, or modify legacy audit/public runtime paths.
Requirement: The query helper script SHALL be read-only and secret-free by default
The repository query helper SHALL require connection values from environment variables, reject non-SELECT and metadata discovery SQL before connection, and SHALL NOT commit writes or expose hardcoded external connection defaults.