MCP 服务器

mcp-sql-guard

Validates SQL queries via AST parsing, ensuring they are single read-only SELECTs on allowed tables with enforced LIMITs, and masks PII columns based on user roles. Provides a tamper-evident audit log and runs fully offline.

README

mcp-sql-guard

Give an agent read access to your warehouse without the write risk, injection, or data exposure. A Model Context Protocol server that parses every statement to an abstract syntax tree and clears it only if it is a single read-only, allow-listed SELECT. It enforces a LIMIT, masks PII columns unless the caller's role is entitled to them, and records every decision in a tamper-evident audit log. Runs fully offline on a bundled DuckDB warehouse.

Handing an agent a database connection is the fastest way to turn a helpful tool into a data breach: a generated DROP, a read_csv('/etc/passwd'), a UNION into system tables, or a plain SELECT email that leaks customer PII to whoever is asking. String matching does not stop these; the query has to be understood. This server validates on the AST and governs at the column level, built from my text-to-SQL and guardrails work.

What this demonstrates

Governance control	Where
Single read-only SELECT, verified on the AST	validator.py
Table allowlist, CTE-aware so CTE names are not mistaken for tables	validator.py
File and system functions blocked (`read_csv`, `copy`, `attach`, ...)	config.py
LIMIT injected when absent, capped when too large	validator.py
Column-level PII masking, alias and `SELECT *` aware	validator.py · masking.py
Role entitlement for PII (`read_pii`)	config.py
Tamper-evident audit log	audit.py
Governance gate in CI	evals.py

Architecture

flowchart LR
    SQL[agent SQL + role] --> V{{AST validator}}
    POL[(governance policy)] --> V
    V -->|not a read-only SELECT| X[refuse + audit]
    V -->|ok| L[enforce LIMIT]
    L --> E[execute on warehouse]
    E --> M[mask PII by role]
    M --> A[(hash-chained audit)]
    M --> SQL

Quickstart

make dev            # venv + install -e ".[dev]"

sqlguard schema     # the queryable schema, PII marked
sqlguard demo       # benign, masked, and blocked queries
sqlguard query "SELECT name, email FROM customers" --role analyst   # email masked
sqlguard eval       # the governance gate
sqlguard serve --role analyst                                       # live MCP server over stdio

No keys, no network. The warehouse is a bundled in-memory DuckDB. Point at a real database in production by swapping the connection in engine.py; the validation and masking logic is unchanged.

The gate that matters

sqlguard eval replays governed and adversarial queries (report):

metric	value	gate
unsafe_executed	0	= 0
pii_exposed	0	= 0
privileged_pii_visible	True	true
execution_accuracy	1.000	>= 0.90
false_block_rate	0.000	<= 0.10

The two zeros are the contract. unsafe_executed counts any write, multi-statement, file-access, or non-allow-listed query that ran; it must be zero. pii_exposed counts any raw email or phone number that reached a role without read_pii; it must be zero. privileged_pii_visible confirms masking is a role decision, not a blanket blackout: a privacy officer still sees the data. Recall and false-block confirm ordinary analytics still work. CI fails if any gate slips.

What it catches

sqlguard demo over sample traffic:

Writes and DDL. DROP, INSERT, UPDATE, and anything that is not a SELECT is refused before it reaches the database.
Multi-statement smuggling. SELECT ...; DROP TABLE ... is rejected as more than one statement.
File and system access. read_csv, copy, attach, and friends are blocked, so the query cannot escape the warehouse.
Metadata exfiltration. A UNION into system tables is refused because unions and non-allow-listed tables are not permitted.
PII exposure. An analyst selecting email, email AS contact, or SELECT * gets the column masked; a privacy officer with read_pii gets the value.

Design decisions

Validate on the AST, not the string. A query is understood, not pattern matched, so obfuscation and aliasing do not get past the checks.
Mask cannot be renamed away. PII masking is computed from the projection, including alias resolution and SELECT * expansion, so email AS x is still masked.
Least privilege by default. PII is masked unless a role is explicitly granted read_pii. The policy YAML is written to be read in review.
Fail closed. A parse error, an unknown table, or an execution error is a clean denial, never an uncaught path.

Layout

src/mcp_sql_guard/  config · schema · validator · masking · engine · audit · guard · server · evals · cli
data/  policy.example.yaml · eval_cases.jsonl
reports/  governance_report_example.md