sqlguard-ninja 0.3.0__tar.gz → 0.5.0__tar.gz

{sqlguard_ninja-0.3.0 → sqlguard_ninja-0.5.0}/CHANGELOG.md

@@ -3,6 +3,36 @@
 All notable changes are documented here. The project follows
 [Semantic Versioning](https://semver.org/); before 1.0, minor versions may change the API.
 
+## [0.5.0] — 2026-10-24
+
+### Added
+* **MySQL 8** as a tested dialect within a documented scope: `sqlguard_ninja.integrations.mysql`
+  (`mysql_executor`: read-only transaction, `MAX_EXECUTION_TIME`, rollback; `bind_placeholders`:
+  AST-based binding of named placeholders, ADR-013), extra `[mysql]` (PyMySQL), and a MySQL 8.4
+  service-container CI job that executes every MySQL `allow` case as a SELECT-only account.
+* Corpus **1.2.0**: 26 MySQL cases (`cases/09_mysql.yaml`); results in
+  `docs/benchmarks/RESULTS_v1.2.md`.
+* `docs/guides/DATABASE_COMPATIBILITY.md`: compatibility matrix. SQL Server and Oracle are
+  parser-level experimental with smoke tests; they are not accepted by the MCP server.
+* The MCP server accepts `mysql` as a dialect.
+
+### Security
+* MySQL identifiers are compared exactly and never case-folded (fail closed). String values
+  containing a backslash or NUL are refused at binding time. `mysql_executor` refuses sessions
+  whose `sql_mode` changes lexing (`ANSI_QUOTES`, `NO_BACKSLASH_ESCAPES`, `PIPES_AS_CONCAT`,
+  `HIGH_NOT_PRECEDENCE`, `ANSI`); threat model T18.
+
+## [0.4.0] — 2026-10-24
+
+### Added
+* **MCP server** (`sqlninja mcp`, `sqlguard_ninja.mcp_server`, extra `[mcp]` on the official
+  MCP Python SDK 2.x). Tools: `validate_sql`, `explain_policy_decision`,
+  `inspect_query_cost`, `get_policy_capabilities`. The role and tenant are fixed server-side,
+  there is no execution and no database connection, internal detail is withheld, ungranted
+  tables and columns are not disclosed, input is size-capped, and calls are rate-limited.
+* An end-to-end test drives the real server over stdio with the SDK's `ClientSession`.
+* Docs: `docs/guides/MCP_INTEGRATION.md`; threat model T17.
+
 ## [0.3.0] — 2026-10-24
 
 ### Added

{sqlguard_ninja-0.3.0 → sqlguard_ninja-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlguard-ninja
-Version: 0.3.0
+Version: 0.5.0
 Summary: Security testing, policy enforcement, agent integration, privacy analysis and CI benchmarking for LLM-generated SQL.
 Project-URL: Homepage, https://github.com/Pratik653/SQLGuard_Ninjapy
 Project-URL: Documentation, https://github.com/Pratik653/SQLGuard_Ninjapy/tree/main/docs
@@ -29,7 +29,9 @@ Provides-Extra: all
 Requires-Dist: fastapi>=0.110; extra == 'all'
 Requires-Dist: langchain-core>=0.3; extra == 'all'
 Requires-Dist: langgraph>=0.2; extra == 'all'
+Requires-Dist: mcp<3,>=2.3; extra == 'all'
 Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
+Requires-Dist: pymysql>=1.1; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: fastapi>=0.110; extra == 'dev'
@@ -37,8 +39,10 @@ Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: hypothesis>=6.100; extra == 'dev'
 Requires-Dist: langchain-core>=0.3; extra == 'dev'
 Requires-Dist: langgraph>=0.2; extra == 'dev'
+Requires-Dist: mcp<3,>=2.3; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
+Requires-Dist: pymysql>=1.1; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
@@ -50,6 +54,10 @@ Requires-Dist: langchain-core>=0.3; extra == 'langchain'
 Provides-Extra: langgraph
 Requires-Dist: langchain-core>=0.3; extra == 'langgraph'
 Requires-Dist: langgraph>=0.2; extra == 'langgraph'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
 Description-Content-Type: text/markdown
@@ -177,8 +185,8 @@ result = guard.validate(
     role="hr_analyst",
     dialect="postgres",
 )
-result.allowed      # True
-result.findings     # () - structured Finding objects with rule_id, action, message, remediation
+result.allowed  # True
+result.findings  # () - structured Finding objects with rule_id, action, message, remediation
 
 guard.validate("SELECT full_name, salary FROM employees", role="hr_analyst").explain()
 # DENY:
@@ -191,16 +199,21 @@ guard.validate("SELECT full_name, salary FROM employees", role="hr_analyst").exp
 ```python
 from sqlguard_ninja.integrations import RequestContext, SQLCheckpoint
 from sqlguard_ninja.integrations.langgraph import (
-    CONTEXT_KEY, make_execute_node, make_guard_node, route_after_guard)
+    CONTEXT_KEY,
+    make_execute_node,
+    make_guard_node,
+    route_after_guard,
+)
 
 checkpoint = SQLCheckpoint(guard, mode="block", max_denied_attempts=3)
 graph.add_node("guard", make_guard_node(checkpoint))
-graph.add_node("execute", make_execute_node(checkpoint, executor))   # re-validates
-graph.add_conditional_edges("guard", route_after_guard(3),
-                            {"execute": "execute", "revise": "generate", "end": END})
+graph.add_node("execute", make_execute_node(checkpoint, executor))  # re-validates
+graph.add_conditional_edges(
+    "guard", route_after_guard(3), {"execute": "execute", "revise": "generate", "end": END}
+)
 
 ctx = RequestContext(principal=user.id, role=user.role, tenant_id=user.tenant_id)
-app.invoke(state, config={"configurable": {CONTEXT_KEY: ctx}})       # nodes cannot alter config
+app.invoke(state, config={"configurable": {CONTEXT_KEY: ctx}})  # nodes cannot alter config
 ```
 
 More in [AGENT_INTEGRATION.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/AGENT_INTEGRATION.md): the LangChain tool (its
@@ -263,6 +276,20 @@ Optional: `SQLCheckpoint(..., rewrite_tenant_filters=True)` adds missing tenant
 through the AST and executes only the re-validated rewrite. See
 [POLICY_AS_CODE.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_AS_CODE.md).
 
+## MCP server
+
+Let MCP-compatible agents check SQL against your policy before running it anywhere:
+
+```bash
+python -m pip install "sqlguard-ninja[mcp]"
+sqlninja mcp --policy builtin:retail_saas --role support_analyst --tenant 1
+```
+
+The four tools are `validate_sql`, `explain_policy_decision`, `inspect_query_cost` and
+`get_policy_capabilities`. The role and tenant are fixed server-side, the server never connects
+to a database, and it exposes no execution tool. Tested with the official MCP Python SDK
+client over stdio. See [MCP_INTEGRATION.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/MCP_INTEGRATION.md).
+
 ## Query cost analysis
 
 Every validation includes an explainable static score that uses the catalog's
@@ -280,8 +307,10 @@ rolled-back transaction:
 
 ```python
 from sqlguard_ninja.query_cost.postgres import PostgresPlanInspector
+
 report = PostgresPlanInspector(guard, lambda: psycopg.connect(READER_DSN)).inspect(
-    sql, role="support_analyst", context={"tenant_id": 1})
+    sql, role="support_analyst", context={"tenant_id": 1}
+)
 report.total_cost, report.plan_rows, report.static.score, report.findings
 ```
 
@@ -296,16 +325,16 @@ sqlninja benchmark run --dataset builtin:v1 --adapter external:sql-guardrail
 sqlninja benchmark compare --baseline benchmarks/baselines/native.json --candidate results/latest.json
 ```
 
-Results for corpus v1.1.0 (551 cases, 1,044 evaluations; SQLGuard Ninja 0.2.0; Windows 11,
+Results for corpus v1.2.0 (577 cases, 1,070 evaluations; SQLGuard Ninja 0.5.0; Windows 11,
 Python 3.11). Intervals are 95% Wilson intervals. Details, CSV and raw files:
-[RESULTS_v1.1.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/benchmarks/RESULTS_v1.1.md).
+[RESULTS_v1.2.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/benchmarks/RESULTS_v1.2.md).
 
 | Validator | Recall (95% CI) | Precision | F1 | FPR (95% CI) | Recall / FPR within declared capability | p95 ms |
 |---|---:|---:|---:|---:|---:|---:|
-| SQLGuard Ninja 0.2.0 | 100.0% (99.4–100.0) | 100.0% | 1.000 | 0.0% (0.0–0.9) | 100.0% / 0.0% | 3.33 |
-| sql-guardrail 0.5.2 | 98.7% (97.4–99.3) | 85.1% | 0.914 | 24.1% (20.3–28.3) | 98.3% / 19.7% | 2.63 |
-| agent-sql-guard 0.2.0 | 67.3% (63.4–70.9) | 85.2% | 0.752 | 16.3% (13.1–20.0) | 89.4% / 17.7% | 1.87 |
-| krish2105/sqlguard 0.1.0 | 65.3% (61.4–69.0) | 89.6% | 0.755 | 10.5% (8.0–13.8) | 83.5% / 5.2% | 1.95 |
+| SQLGuard Ninja 0.5.0 | 100.0% (99.4–100.0) | 100.0% | 1.000 | 0.0% (0.0–0.9) | 100.0% / 0.0% | 3.36 |
+| sql-guardrail 0.5.2 | 98.2% (96.9–99.0) | 84.7% | 0.909 | 24.8% (21.1–29.0) | 98.3% / 19.7% | 1.84 |
+| agent-sql-guard 0.2.0 | 66.8% (63.0–70.4) | 85.1% | 0.748 | 16.3% (13.2–20.0) | 89.4% / 17.7% | 1.44 |
+| krish2105/sqlguard 0.1.0 | 64.8% (61.0–68.5) | 89.4% | 0.752 | 10.7% (8.2–14.0) | 83.5% / 5.2% | 1.42 |
 
 **All of these are internal results.** The corpus was written by this project, alongside the
 engine. The native 100% shows consistency with the documented semantics, not independent
@@ -358,6 +387,7 @@ writes, more tested dialects, and SARIF output. Details in [ROADMAP.md](https://
 
 * [Policy reference](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_REFERENCE.md)
 * [Policy as code](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_AS_CODE.md)
+* [MCP integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/MCP_INTEGRATION.md)
 * [Agent integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/AGENT_INTEGRATION.md)
 * [Query cost](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/QUERY_COST.md)
 * [CI integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/CI_INTEGRATION.md)
@@ -371,8 +401,10 @@ writes, more tested dialects, and SARIF output. Details in [ROADMAP.md](https://
 ## Supported versions
 
 * Python 3.11, 3.12, 3.13 (CI matrix on Linux and Windows).
-* SQL dialects: **PostgreSQL** (tested against PostgreSQL 16) and **SQLite**. Other sqlglot
-  dialects parse but are experimental and untested.
+* SQL dialects: **PostgreSQL** (tested against PostgreSQL 16), **SQLite**, and **MySQL 8**
+  (tested against MySQL 8.4 in CI, within the documented scope: identifier case is not folded,
+  named placeholders only). SQL Server and Oracle are parser-level **experimental**; others are
+  untested. See the [compatibility matrix](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/DATABASE_COMPATIBILITY.md).
 
 ## Development
 

{sqlguard_ninja-0.3.0 → sqlguard_ninja-0.5.0}/README.md

@@ -121,8 +121,8 @@ result = guard.validate(
     role="hr_analyst",
     dialect="postgres",
 )
-result.allowed      # True
-result.findings     # () - structured Finding objects with rule_id, action, message, remediation
+result.allowed  # True
+result.findings  # () - structured Finding objects with rule_id, action, message, remediation
 
 guard.validate("SELECT full_name, salary FROM employees", role="hr_analyst").explain()
 # DENY:
@@ -135,16 +135,21 @@ guard.validate("SELECT full_name, salary FROM employees", role="hr_analyst").exp
 ```python
 from sqlguard_ninja.integrations import RequestContext, SQLCheckpoint
 from sqlguard_ninja.integrations.langgraph import (
-    CONTEXT_KEY, make_execute_node, make_guard_node, route_after_guard)
+    CONTEXT_KEY,
+    make_execute_node,
+    make_guard_node,
+    route_after_guard,
+)
 
 checkpoint = SQLCheckpoint(guard, mode="block", max_denied_attempts=3)
 graph.add_node("guard", make_guard_node(checkpoint))
-graph.add_node("execute", make_execute_node(checkpoint, executor))   # re-validates
-graph.add_conditional_edges("guard", route_after_guard(3),
-                            {"execute": "execute", "revise": "generate", "end": END})
+graph.add_node("execute", make_execute_node(checkpoint, executor))  # re-validates
+graph.add_conditional_edges(
+    "guard", route_after_guard(3), {"execute": "execute", "revise": "generate", "end": END}
+)
 
 ctx = RequestContext(principal=user.id, role=user.role, tenant_id=user.tenant_id)
-app.invoke(state, config={"configurable": {CONTEXT_KEY: ctx}})       # nodes cannot alter config
+app.invoke(state, config={"configurable": {CONTEXT_KEY: ctx}})  # nodes cannot alter config
 ```
 
 More in [AGENT_INTEGRATION.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/AGENT_INTEGRATION.md): the LangChain tool (its
@@ -207,6 +212,20 @@ Optional: `SQLCheckpoint(..., rewrite_tenant_filters=True)` adds missing tenant
 through the AST and executes only the re-validated rewrite. See
 [POLICY_AS_CODE.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_AS_CODE.md).
 
+## MCP server
+
+Let MCP-compatible agents check SQL against your policy before running it anywhere:
+
+```bash
+python -m pip install "sqlguard-ninja[mcp]"
+sqlninja mcp --policy builtin:retail_saas --role support_analyst --tenant 1
+```
+
+The four tools are `validate_sql`, `explain_policy_decision`, `inspect_query_cost` and
+`get_policy_capabilities`. The role and tenant are fixed server-side, the server never connects
+to a database, and it exposes no execution tool. Tested with the official MCP Python SDK
+client over stdio. See [MCP_INTEGRATION.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/MCP_INTEGRATION.md).
+
 ## Query cost analysis
 
 Every validation includes an explainable static score that uses the catalog's
@@ -224,8 +243,10 @@ rolled-back transaction:
 
 ```python
 from sqlguard_ninja.query_cost.postgres import PostgresPlanInspector
+
 report = PostgresPlanInspector(guard, lambda: psycopg.connect(READER_DSN)).inspect(
-    sql, role="support_analyst", context={"tenant_id": 1})
+    sql, role="support_analyst", context={"tenant_id": 1}
+)
 report.total_cost, report.plan_rows, report.static.score, report.findings
 ```
 
@@ -240,16 +261,16 @@ sqlninja benchmark run --dataset builtin:v1 --adapter external:sql-guardrail
 sqlninja benchmark compare --baseline benchmarks/baselines/native.json --candidate results/latest.json
 ```
 
-Results for corpus v1.1.0 (551 cases, 1,044 evaluations; SQLGuard Ninja 0.2.0; Windows 11,
+Results for corpus v1.2.0 (577 cases, 1,070 evaluations; SQLGuard Ninja 0.5.0; Windows 11,
 Python 3.11). Intervals are 95% Wilson intervals. Details, CSV and raw files:
-[RESULTS_v1.1.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/benchmarks/RESULTS_v1.1.md).
+[RESULTS_v1.2.md](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/benchmarks/RESULTS_v1.2.md).
 
 | Validator | Recall (95% CI) | Precision | F1 | FPR (95% CI) | Recall / FPR within declared capability | p95 ms |
 |---|---:|---:|---:|---:|---:|---:|
-| SQLGuard Ninja 0.2.0 | 100.0% (99.4–100.0) | 100.0% | 1.000 | 0.0% (0.0–0.9) | 100.0% / 0.0% | 3.33 |
-| sql-guardrail 0.5.2 | 98.7% (97.4–99.3) | 85.1% | 0.914 | 24.1% (20.3–28.3) | 98.3% / 19.7% | 2.63 |
-| agent-sql-guard 0.2.0 | 67.3% (63.4–70.9) | 85.2% | 0.752 | 16.3% (13.1–20.0) | 89.4% / 17.7% | 1.87 |
-| krish2105/sqlguard 0.1.0 | 65.3% (61.4–69.0) | 89.6% | 0.755 | 10.5% (8.0–13.8) | 83.5% / 5.2% | 1.95 |
+| SQLGuard Ninja 0.5.0 | 100.0% (99.4–100.0) | 100.0% | 1.000 | 0.0% (0.0–0.9) | 100.0% / 0.0% | 3.36 |
+| sql-guardrail 0.5.2 | 98.2% (96.9–99.0) | 84.7% | 0.909 | 24.8% (21.1–29.0) | 98.3% / 19.7% | 1.84 |
+| agent-sql-guard 0.2.0 | 66.8% (63.0–70.4) | 85.1% | 0.748 | 16.3% (13.2–20.0) | 89.4% / 17.7% | 1.44 |
+| krish2105/sqlguard 0.1.0 | 64.8% (61.0–68.5) | 89.4% | 0.752 | 10.7% (8.2–14.0) | 83.5% / 5.2% | 1.42 |
 
 **All of these are internal results.** The corpus was written by this project, alongside the
 engine. The native 100% shows consistency with the documented semantics, not independent
@@ -302,6 +323,7 @@ writes, more tested dialects, and SARIF output. Details in [ROADMAP.md](https://
 
 * [Policy reference](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_REFERENCE.md)
 * [Policy as code](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/POLICY_AS_CODE.md)
+* [MCP integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/MCP_INTEGRATION.md)
 * [Agent integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/AGENT_INTEGRATION.md)
 * [Query cost](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/QUERY_COST.md)
 * [CI integration](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/CI_INTEGRATION.md)
@@ -315,8 +337,10 @@ writes, more tested dialects, and SARIF output. Details in [ROADMAP.md](https://
 ## Supported versions
 
 * Python 3.11, 3.12, 3.13 (CI matrix on Linux and Windows).
-* SQL dialects: **PostgreSQL** (tested against PostgreSQL 16) and **SQLite**. Other sqlglot
-  dialects parse but are experimental and untested.
+* SQL dialects: **PostgreSQL** (tested against PostgreSQL 16), **SQLite**, and **MySQL 8**
+  (tested against MySQL 8.4 in CI, within the documented scope: identifier case is not folded,
+  named placeholders only). SQL Server and Oracle are parser-level **experimental**; others are
+  untested. See the [compatibility matrix](https://github.com/Pratik653/SQLGuard_Ninjapy/blob/main/docs/guides/DATABASE_COMPATIBILITY.md).
 
 ## Development