sql-data-guard 0.1.9__tar.gz → 0.2.0__tar.gz

{sql_data_guard-0.1.9/src/sql_data_guard.egg-info → sql_data_guard-0.2.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: sql-data-guard
-Version: 0.1.9
+Version: 0.2.0
 Summary: Safety Layer for LLM Database Interactions
-Author-email: Imperva - Threat Reseach Infra <ww.dis.imperva.threat-research-infra@thalesgroup.com>
+Author-email: Imperva - Threat Research Infra <ww.dis.imperva.threat-research-infra@thalesgroup.com>
 License: MIT License
         
         Copyright (c) 2025 Imperva
@@ -15,11 +15,16 @@ License: MIT License
 Project-URL: Homepage, https://github.com/ThalesGroup/sql-data-guard
 Project-URL: Issues, https://github.com/ThalesGroup/sql-data-guard/issues
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: sqlglot
+Requires-Dist: sqlglot<31,>=25.20.1
 Dynamic: license-file
 
 
@@ -32,7 +37,7 @@ Dynamic: license-file
 SQL is the go-to language for performing queries on databases, and for a good reason - it’s well known, easy to use and pretty simple. However, it seems that it’s as easy to use as it is to exploit, and SQL injection is still one of the most targeted vulnerabilities - especially nowadays with the proliferation of “natural language queries” harnessing Large Language Models (LLMs) power to generate and run SQL queries.
 
 
-To help solve this problem, we developed sql-data-guard, an open-source project designed to verify that SQL queries access only the data they are allowed to. It takes a query and a restriction configuration, and returns whether the query is allowed to run or not. Additionally, it can modify the query to ensure it complies with the restrictions. sql-data-guard has also a built-in module for detection of malicious payloads, allowing it to report on and remove malicious expressions before query execution.
+To help solve this problem, we developed sql-data-guard, an open-source project designed to verify that SQL queries access only the data they are allowed to. It takes a query and a restriction configuration, and returns whether the query is allowed to run or not. Additionally, it can modify the query to ensure it complies with the restrictions. sql-data-guard also detects "always-true" (static) expressions such as `OR 1 = 1`, a common injection payload, and removes them before query execution.
 
 
 sql-data-guard is particularly useful when constructing SQL queries with LLMs, as such queries can’t run as prepared statements. Prepared statements secure a query’s structure, but LLM-generated queries are dynamic and lack this fixed form, increasing SQL injection risk. sql-data-guard mitigates this by inspecting and validating the query's content.
@@ -45,14 +50,14 @@ Connecting LLMs to SQL databases without strict controls can risk accidental dat
 
 ## Why Use sql-data-guard?
 
-Consider using sql-guard if your application constructs SQL queries, and you need to ensure that only permitted data is accessed. This is particularly beneficial if:
+Consider using sql-data-guard if your application constructs SQL queries, and you need to ensure that only permitted data is accessed. This is particularly beneficial if:
 - Your application generates complex SQL queries.
 - Your application employs LLM (Large Language Models) to create SQL queries, making it difficult to fully control the queries.
 - Different application users and roles should have different permissions, and you need to correlate an application user or role with fine-grained data access permission.
 - In multi-tenant applications, you need to ensure that each tenant can access only their data, which requires row-level security and often cannot be done using the database permissions model.
 
-sql-guard does not replace the database permissions model. Instead, it adds an extra layer of security, which is crucial when implementing fine-grained, column-level, and row-level security is challenging or impossible. 
-Data restrictions are often complex and cannot be expressed by the database permissions model. For instance, you may need to restrict access to specific columns or rows based on intricate business logic, which many database implementations do not support. Instead of relying on the database to enforce these restrictions, sql-guard helps you overcome vendor-specific limitations by verifying and modifying queries before they are executed.
+sql-data-guard does not replace the database permissions model. Instead, it adds an extra layer of security, which is crucial when implementing fine-grained, column-level, and row-level security is challenging or impossible. 
+Data restrictions are often complex and cannot be expressed by the database permissions model. For instance, you may need to restrict access to specific columns or rows based on intricate business logic, which many database implementations do not support. Instead of relying on the database to enforce these restrictions, sql-data-guard helps you overcome vendor-specific limitations by verifying and modifying queries before they are executed.
 
 ## How It Works
 
@@ -73,7 +78,7 @@ from sql_data_guard import verify_sql
 config = {
     "tables": [
         {
-            "name": "orders",
+            "table_name": "orders",
             "columns": ["id", "product_name", "account_id"],
             "restrictions": [{"column": "account_id", "value": 123}]
         }
@@ -88,23 +93,32 @@ Output:
 ```json
 {
     "allowed": false,
-    "errors": ["Column name not allowed. Column removed from SELECT clause", 
-      "Always-True expression is not allowed", "Missing restriction for table: orders column: account_id value: 123"],
-    "fixed": "SELECT id, product_name, account_id FROM orders WHERE account_id = 123"
+    "errors": [
+        "Column name is not allowed. Column removed from SELECT clause",
+        "Missing restriction for table: orders column: account_id value: 123",
+        "Static expression is not allowed: 1 = 1"
+    ],
+    "fixed": "SELECT id FROM orders WHERE account_id = 123",
+    "risk": 0.53
 }
 ```
-For more details on restriction rules and validation, see the [manual.](docs/manual.md)
+`errors` is a sorted list. `risk` is between 0 (no risk) and 1 (high risk).
+For more details on restriction rules and validation, see the [manual.](https://raw.githubusercontent.com/ThalesGroup/sql-data-guard/main/docs/manual.md)
 
 
 Here is a table with more examples of SQL queries and their corresponding JSON outputs:
 
-| SQL Query                                               | JSON Output                                                                                                                                                                         |
-|---------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| SELECT id, product_name FROM orders WHERE account_id = 123 | { "allowed": true, "errors": [], "fixed": null }                                                                                                                                    |
-| SELECT id FROM orders WHERE account_id = 456            | { "allowed": false, "errors": ["Missing restriction for table: orders column: account_id value: 123"], "fixed": "SELECT id FROM orders WHERE account_id = 456 AND account_id = 123" } |
-| SELECT id, col FROM orders WHERE account_id = 123      | { "allowed": false, "errors": ["Column col is not allowed. Column removed from SELECT clause"], "fixed": "SELECT id FROM orders WHERE account_id = 123" } ```               |
-| SELECT id FROM orders WHERE account_id = 123 OR 1 = 1 | { "allowed": false, "errors": ["Always-True expression is not allowed"], "fixed": "SELECT id FROM orders WHERE account_id = 123" }                                                  |
-|SELECT * FROM orders WHERE account_id = 123| {"allowed": false, "errors": ["SELECT * is not allowed"], "fixed": "SELECT id, product_name, account_id FROM orders WHERE account_id = 123"}                                |
+| SQL Query | JSON Output |
+|-----------|-------------|
+| `SELECT id, product_name FROM orders WHERE account_id = 123` | `{ "allowed": true, "errors": [], "fixed": null, "risk": 0 }` |
+| `SELECT id FROM orders WHERE account_id = 456` | `{ "allowed": false, "errors": ["Missing restriction for table: orders column: account_id value: 123"], "fixed": "SELECT id FROM orders WHERE (account_id = 456) AND account_id = 123", "risk": 0.5 }` |
+| `SELECT id, col FROM orders WHERE account_id = 123` | `{ "allowed": false, "errors": ["Column col is not allowed. Column removed from SELECT clause"], "fixed": "SELECT id FROM orders WHERE account_id = 123", "risk": 0.3 }` |
+| `SELECT id FROM orders WHERE account_id = 123 OR 1 = 1` | `{ "allowed": false, "errors": ["Static expression is not allowed: 1 = 1"], "fixed": "SELECT id FROM orders WHERE account_id = 123", "risk": 0.8 }` |
+| `SELECT * FROM orders WHERE account_id = 123` | `{ "allowed": false, "errors": ["SELECT * is not allowed"], "fixed": "SELECT id, product_name, account_id FROM orders WHERE account_id = 123", "risk": 0.1 }` |
+| `SELECT id FROM orders WHERE account_id = 123 AND secret = 1` | `{ "allowed": false, "errors": ["Column secret is not allowed"], "fixed": null, "risk": 0.8 }` |
+| `SELECT id FROM orders WHERE account_id = 123; DROP TABLE orders` | `{ "allowed": false, "errors": ["Multiple statements are not allowed"], "fixed": null, "risk": 1.0 }` |
+
+When `fixed` is `null` the query cannot be repaired and must not be run.
 
 This table provides a variety of SQL queries and their corresponding JSON outputs, demonstrating how `sql-data-guard` handles different scenarios.
 
@@ -127,6 +141,25 @@ To run the sql-data-guard Docker container, use the following command:
 docker run -d --name sql-data-guard -p 5000:5000 ghcr.io/thalesgroup/sql-data-guard
 ```
 
+The image runs the service with [gunicorn](https://gunicorn.org/) (2 worker processes with 4 threads each), not the Flask development server, and installs `sql-data-guard` from PyPI. Release images are tagged with the version (for example `0.1.10`) and `latest`, and contain exactly that release. It runs as a non-root user and listens on port 5000.
+
+Settings (environment variables):
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `APP_API_TOKEN` | not set | When set, every request must send `Authorization: Bearer <token>`. **Set it unless the service is only reachable by trusted callers.** |
+| `APP_PORT` | `5000` | Port to listen on. |
+| `APP_HOST` | `127.0.0.1` (`0.0.0.0` in the image) | Address to bind. |
+| `APP_MAX_REQUEST_BYTES` | `1000000` | Maximum request size. |
+| `WEB_CONCURRENCY` | `2` | gunicorn worker processes (image only). |
+| `APP_THREADS` | `4` | Threads per worker (image only). |
+
+The caller sends the policy (`config`) with every request, so the service is not an enforcement point against callers who must not be able to choose their own policy.
+
+```bash
+docker run -d --name sql-data-guard -p 5000:5000 -e APP_API_TOKEN=change-me ghcr.io/thalesgroup/sql-data-guard
+```
+
 ### Calling the Docker Container Using REST API
 
 Once the `sql-data-guard` Docker container is running, you can interact with it using its REST API. Below is an example of how to verify an SQL query using `curl`:
@@ -134,6 +167,7 @@ Once the `sql-data-guard` Docker container is running, you can interact with it
 ```bash
 curl -X POST http://localhost:5000/verify-sql \
      -H "Content-Type: application/json" \
+     -H "Authorization: Bearer change-me" \
      -d '{
            "sql": "SELECT * FROM orders WHERE account_id = 123",
            "config": {
@@ -148,6 +182,10 @@ curl -X POST http://localhost:5000/verify-sql \
          }'
 ```
 
+## MCP Wrapper
+
+sql-data-guard can also protect an MCP server that talks to a database: the wrapper verifies the SQL of every tool call before the server sees it, and refuses tools that could run SQL without the guard. See [the MCP wrapper guide](https://raw.githubusercontent.com/ThalesGroup/sql-data-guard/main/docs/mcp-wrapper.md).
+
 ## Contributing
 We welcome contributions! Please see our [CONTRIBUTING.md](https://raw.githubusercontent.com/ThalesGroup/sql-data-guard/main/CONTRIBUTING.md) for more details.
 

{sql_data_guard-0.1.9 → sql_data_guard-0.2.0}/README.md

@@ -8,7 +8,7 @@
 SQL is the go-to language for performing queries on databases, and for a good reason - it’s well known, easy to use and pretty simple. However, it seems that it’s as easy to use as it is to exploit, and SQL injection is still one of the most targeted vulnerabilities - especially nowadays with the proliferation of “natural language queries” harnessing Large Language Models (LLMs) power to generate and run SQL queries.
 
 
-To help solve this problem, we developed sql-data-guard, an open-source project designed to verify that SQL queries access only the data they are allowed to. It takes a query and a restriction configuration, and returns whether the query is allowed to run or not. Additionally, it can modify the query to ensure it complies with the restrictions. sql-data-guard has also a built-in module for detection of malicious payloads, allowing it to report on and remove malicious expressions before query execution.
+To help solve this problem, we developed sql-data-guard, an open-source project designed to verify that SQL queries access only the data they are allowed to. It takes a query and a restriction configuration, and returns whether the query is allowed to run or not. Additionally, it can modify the query to ensure it complies with the restrictions. sql-data-guard also detects "always-true" (static) expressions such as `OR 1 = 1`, a common injection payload, and removes them before query execution.
 
 
 sql-data-guard is particularly useful when constructing SQL queries with LLMs, as such queries can’t run as prepared statements. Prepared statements secure a query’s structure, but LLM-generated queries are dynamic and lack this fixed form, increasing SQL injection risk. sql-data-guard mitigates this by inspecting and validating the query's content.
@@ -21,14 +21,14 @@ Connecting LLMs to SQL databases without strict controls can risk accidental dat
 
 ## Why Use sql-data-guard?
 
-Consider using sql-guard if your application constructs SQL queries, and you need to ensure that only permitted data is accessed. This is particularly beneficial if:
+Consider using sql-data-guard if your application constructs SQL queries, and you need to ensure that only permitted data is accessed. This is particularly beneficial if:
 - Your application generates complex SQL queries.
 - Your application employs LLM (Large Language Models) to create SQL queries, making it difficult to fully control the queries.
 - Different application users and roles should have different permissions, and you need to correlate an application user or role with fine-grained data access permission.
 - In multi-tenant applications, you need to ensure that each tenant can access only their data, which requires row-level security and often cannot be done using the database permissions model.
 
-sql-guard does not replace the database permissions model. Instead, it adds an extra layer of security, which is crucial when implementing fine-grained, column-level, and row-level security is challenging or impossible. 
-Data restrictions are often complex and cannot be expressed by the database permissions model. For instance, you may need to restrict access to specific columns or rows based on intricate business logic, which many database implementations do not support. Instead of relying on the database to enforce these restrictions, sql-guard helps you overcome vendor-specific limitations by verifying and modifying queries before they are executed.
+sql-data-guard does not replace the database permissions model. Instead, it adds an extra layer of security, which is crucial when implementing fine-grained, column-level, and row-level security is challenging or impossible. 
+Data restrictions are often complex and cannot be expressed by the database permissions model. For instance, you may need to restrict access to specific columns or rows based on intricate business logic, which many database implementations do not support. Instead of relying on the database to enforce these restrictions, sql-data-guard helps you overcome vendor-specific limitations by verifying and modifying queries before they are executed.
 
 ## How It Works
 
@@ -49,7 +49,7 @@ from sql_data_guard import verify_sql
 config = {
     "tables": [
         {
-            "name": "orders",
+            "table_name": "orders",
             "columns": ["id", "product_name", "account_id"],
             "restrictions": [{"column": "account_id", "value": 123}]
         }
@@ -64,23 +64,32 @@ Output:
 ```json
 {
     "allowed": false,
-    "errors": ["Column name not allowed. Column removed from SELECT clause", 
-      "Always-True expression is not allowed", "Missing restriction for table: orders column: account_id value: 123"],
-    "fixed": "SELECT id, product_name, account_id FROM orders WHERE account_id = 123"
+    "errors": [
+        "Column name is not allowed. Column removed from SELECT clause",
+        "Missing restriction for table: orders column: account_id value: 123",
+        "Static expression is not allowed: 1 = 1"
+    ],
+    "fixed": "SELECT id FROM orders WHERE account_id = 123",
+    "risk": 0.53
 }
 ```
-For more details on restriction rules and validation, see the [manual.](docs/manual.md)
+`errors` is a sorted list. `risk` is between 0 (no risk) and 1 (high risk).
+For more details on restriction rules and validation, see the [manual.](https://raw.githubusercontent.com/ThalesGroup/sql-data-guard/main/docs/manual.md)
 
 
 Here is a table with more examples of SQL queries and their corresponding JSON outputs:
 
-| SQL Query                                               | JSON Output                                                                                                                                                                         |
-|---------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| SELECT id, product_name FROM orders WHERE account_id = 123 | { "allowed": true, "errors": [], "fixed": null }                                                                                                                                    |
-| SELECT id FROM orders WHERE account_id = 456            | { "allowed": false, "errors": ["Missing restriction for table: orders column: account_id value: 123"], "fixed": "SELECT id FROM orders WHERE account_id = 456 AND account_id = 123" } |
-| SELECT id, col FROM orders WHERE account_id = 123      | { "allowed": false, "errors": ["Column col is not allowed. Column removed from SELECT clause"], "fixed": "SELECT id FROM orders WHERE account_id = 123" } ```               |
-| SELECT id FROM orders WHERE account_id = 123 OR 1 = 1 | { "allowed": false, "errors": ["Always-True expression is not allowed"], "fixed": "SELECT id FROM orders WHERE account_id = 123" }                                                  |
-|SELECT * FROM orders WHERE account_id = 123| {"allowed": false, "errors": ["SELECT * is not allowed"], "fixed": "SELECT id, product_name, account_id FROM orders WHERE account_id = 123"}                                |
+| SQL Query | JSON Output |
+|-----------|-------------|
+| `SELECT id, product_name FROM orders WHERE account_id = 123` | `{ "allowed": true, "errors": [], "fixed": null, "risk": 0 }` |
+| `SELECT id FROM orders WHERE account_id = 456` | `{ "allowed": false, "errors": ["Missing restriction for table: orders column: account_id value: 123"], "fixed": "SELECT id FROM orders WHERE (account_id = 456) AND account_id = 123", "risk": 0.5 }` |
+| `SELECT id, col FROM orders WHERE account_id = 123` | `{ "allowed": false, "errors": ["Column col is not allowed. Column removed from SELECT clause"], "fixed": "SELECT id FROM orders WHERE account_id = 123", "risk": 0.3 }` |
+| `SELECT id FROM orders WHERE account_id = 123 OR 1 = 1` | `{ "allowed": false, "errors": ["Static expression is not allowed: 1 = 1"], "fixed": "SELECT id FROM orders WHERE account_id = 123", "risk": 0.8 }` |
+| `SELECT * FROM orders WHERE account_id = 123` | `{ "allowed": false, "errors": ["SELECT * is not allowed"], "fixed": "SELECT id, product_name, account_id FROM orders WHERE account_id = 123", "risk": 0.1 }` |
+| `SELECT id FROM orders WHERE account_id = 123 AND secret = 1` | `{ "allowed": false, "errors": ["Column secret is not allowed"], "fixed": null, "risk": 0.8 }` |
+| `SELECT id FROM orders WHERE account_id = 123; DROP TABLE orders` | `{ "allowed": false, "errors": ["Multiple statements are not allowed"], "fixed": null, "risk": 1.0 }` |
+
+When `fixed` is `null` the query cannot be repaired and must not be run.
 
 This table provides a variety of SQL queries and their corresponding JSON outputs, demonstrating how `sql-data-guard` handles different scenarios.
 
@@ -103,6 +112,25 @@ To run the sql-data-guard Docker container, use the following command:
 docker run -d --name sql-data-guard -p 5000:5000 ghcr.io/thalesgroup/sql-data-guard
 ```
 
+The image runs the service with [gunicorn](https://gunicorn.org/) (2 worker processes with 4 threads each), not the Flask development server, and installs `sql-data-guard` from PyPI. Release images are tagged with the version (for example `0.1.10`) and `latest`, and contain exactly that release. It runs as a non-root user and listens on port 5000.
+
+Settings (environment variables):
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `APP_API_TOKEN` | not set | When set, every request must send `Authorization: Bearer <token>`. **Set it unless the service is only reachable by trusted callers.** |
+| `APP_PORT` | `5000` | Port to listen on. |
+| `APP_HOST` | `127.0.0.1` (`0.0.0.0` in the image) | Address to bind. |
+| `APP_MAX_REQUEST_BYTES` | `1000000` | Maximum request size. |
+| `WEB_CONCURRENCY` | `2` | gunicorn worker processes (image only). |
+| `APP_THREADS` | `4` | Threads per worker (image only). |
+
+The caller sends the policy (`config`) with every request, so the service is not an enforcement point against callers who must not be able to choose their own policy.
+
+```bash
+docker run -d --name sql-data-guard -p 5000:5000 -e APP_API_TOKEN=change-me ghcr.io/thalesgroup/sql-data-guard
+```
+
 ### Calling the Docker Container Using REST API
 
 Once the `sql-data-guard` Docker container is running, you can interact with it using its REST API. Below is an example of how to verify an SQL query using `curl`:
@@ -110,6 +138,7 @@ Once the `sql-data-guard` Docker container is running, you can interact with it
 ```bash
 curl -X POST http://localhost:5000/verify-sql \
      -H "Content-Type: application/json" \
+     -H "Authorization: Bearer change-me" \
      -d '{
            "sql": "SELECT * FROM orders WHERE account_id = 123",
            "config": {
@@ -124,6 +153,10 @@ curl -X POST http://localhost:5000/verify-sql \
          }'
 ```
 
+## MCP Wrapper
+
+sql-data-guard can also protect an MCP server that talks to a database: the wrapper verifies the SQL of every tool call before the server sees it, and refuses tools that could run SQL without the guard. See [the MCP wrapper guide](https://raw.githubusercontent.com/ThalesGroup/sql-data-guard/main/docs/mcp-wrapper.md).
+
 ## Contributing
 We welcome contributions! Please see our [CONTRIBUTING.md](https://raw.githubusercontent.com/ThalesGroup/sql-data-guard/main/CONTRIBUTING.md) for more details.
 

sql_data_guard-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+include-package-data = false
+package-dir = {"" = "src"}
+[tool.pip]
+extra-index-url = ["https://pypi.org/simple"]
+[project]
+name = "sql-data-guard"
+version = "0.2.0"
+dependencies = [
+    # lower bound: oldest version the test-suite passes on; upper bound: next untested major
+    "sqlglot>=25.20.1,<31"
+]
+authors = [
+  { name="Imperva - Threat Research Infra", email="ww.dis.imperva.threat-research-infra@thalesgroup.com" },
+]
+description = "Safety Layer for LLM Database Interactions"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+]
+license = {file = "LICENSE.md"}
+
+[project.urls]
+Homepage = "https://github.com/ThalesGroup/sql-data-guard"
+Issues = "https://github.com/ThalesGroup/sql-data-guard/issues"
+
+[tool.ruff.lint]
+select = ["F", "E9"]  # pyflakes + syntax errors
+
+[tool.mypy]
+files = ["src/sql_data_guard"]
+ignore_missing_imports = true
+
+[tool.coverage.run]
+source = ["sql_data_guard"]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true

sql_data_guard-0.2.0/src/sql_data_guard/__init__.py

@@ -0,0 +1,4 @@
+from .config_suggestion import merge_config, suggest_config
+from .sql_data_guard import verify_sql
+
+__all__ = ["verify_sql", "suggest_config", "merge_config"]

sql_data_guard-0.2.0/src/sql_data_guard/column_masking.py

@@ -0,0 +1,127 @@
+"""
+Column masking.
+
+Instead of removing a sensitive column from the SELECT list (which changes the shape of the
+result and can break the caller), a table can declare it as *masked*: the column is still
+returned under the same name, but its value is replaced, so the real value never leaves the
+database.
+
+    {
+        "table_name": "users",
+        "columns": ["id", "name", "ssn"],
+        "column_masks": [{"column": "ssn", "policy": "redact", "replacement": "****"}]
+    }
+
+A masked column can only be selected directly (`ssn`, `u.ssn`, `ssn AS x`, or through `SELECT *`).
+Any other use (WHERE, JOIN, GROUP BY, ORDER BY, inside a function or expression...) would let a
+caller learn the real value one comparison at a time, and cannot be masked, so it is rejected.
+"""
+
+from typing import Dict, List, Optional
+
+import sqlglot.expressions as expr
+
+from .verification_utils import names_equal, same_name, table_matches
+
+# policy name -> builds the replacement expression of a mask. More policies (for example a
+# partial mask) need functions whose names differ per database, and can be registered here.
+_DEFAULT_REPLACEMENT = "****"
+
+
+def _redact(mask: dict) -> expr.Expression:
+    return expr.Literal.string(mask.get("replacement", _DEFAULT_REPLACEMENT))
+
+
+MASK_POLICIES = {"redact": _redact}
+
+
+def validate_column_masks(config: dict) -> None:
+    """
+    Validates the `column_masks` of every table.
+
+    Raises:
+        ValueError: if a mask is malformed, uses an unknown policy, masks a column that is not in
+            the table's `columns`, masks a column twice, or masks a column used by a restriction.
+    """
+    for table in config.get("tables", []):
+        if "column_masks" not in table:
+            continue
+        name = table.get("table_name")
+        masks = table["column_masks"]
+        if not isinstance(masks, list):
+            raise ValueError(f"'column_masks' of table '{name}' must be a list.")
+        allowed = [str(c).lower() for c in table.get("columns", [])]
+        restricted = [str(r.get("column")).lower() for r in table.get("restrictions") or []]
+        seen = set()
+        for mask in masks:
+            if not isinstance(mask, dict) or not isinstance(mask.get("column"), str) or not mask["column"]:
+                raise ValueError(f"Each column mask of table '{name}' must be an object with a 'column'.")
+            column = mask["column"].lower()
+            if column not in allowed:
+                raise ValueError(
+                    f"Masked column '{mask['column']}' must also be in the 'columns' of table '{name}'."
+                )
+            if column in seen:
+                raise ValueError(f"Column '{mask['column']}' of table '{name}' is masked more than once.")
+            seen.add(column)
+            if column in restricted:
+                raise ValueError(
+                    f"Column '{mask['column']}' of table '{name}' cannot be both masked and restricted."
+                )
+            policy = mask.get("policy")
+            if policy not in MASK_POLICIES:
+                raise ValueError(
+                    f"Unsupported mask policy {policy!r} for column '{mask['column']}'. "
+                    f"Supported policies: {sorted(MASK_POLICIES)}."
+                )
+            replacement = mask.get("replacement", _DEFAULT_REPLACEMENT)
+            if not isinstance(replacement, str):
+                raise ValueError(f"'replacement' for column '{mask['column']}' must be a string.")
+
+
+def find_mask(col: expr.Column, scopes: List[List[expr.Table]], config: dict) -> Optional[dict]:
+    """
+    The mask that applies to a column reference, or None.
+
+    `scopes` are the tables of the query being verified and of its enclosing queries, innermost
+    first, so a correlated sub-query that refers to a table of the outer query is found too. A
+    qualified column is resolved to the innermost table with that name or alias; an unqualified
+    column to the innermost query that has a configured table with that column. If several tables
+    of that query could provide it, it is masked when any of them masks it (the safe choice).
+    """
+    for tables in scopes:
+        candidates = []
+        for table in tables:
+            if col.table and not same_name(col.table, table.alias_or_name):
+                continue
+            for config_table in config["tables"]:
+                if table_matches(table, config_table) and (
+                    col.table or any(names_equal(col, c) for c in config_table["columns"])
+                ):
+                    candidates.append(config_table)
+        if candidates:
+            return next(
+                (
+                    mask
+                    for config_table in candidates
+                    for mask in config_table.get("column_masks") or []
+                    if names_equal(col, mask["column"])
+                ),
+                None,
+            )
+    return None
+
+
+def mask_value(mask: dict) -> expr.Expression:
+    """The expression that replaces the value of a masked column."""
+    return MASK_POLICIES[mask["policy"]](mask)
+
+
+def masked_select_item(mask: dict, name: str) -> expr.Expression:
+    """`<mask value> AS <name>`: what a masked column is rewritten to in the SELECT list."""
+    return expr.alias_(mask_value(mask), expr.to_identifier(name))
+
+
+def table_masks(config_table: dict) -> Dict[str, dict]:
+    """Masks of a configured table, by lower case column name."""
+    return {m["column"].lower(): m for m in config_table.get("column_masks") or []}

sql_data_guard-0.2.0/src/sql_data_guard/config_suggestion.py

@@ -0,0 +1,169 @@
+"""
+Suggesting and applying allow-list changes to a configuration.
+
+``suggest_config`` answers "what would this query need to be allowed?" and ``merge_config``
+applies such an answer to a configuration. Both only deal with the table/column allow-list
+(``tables``); restrictions, masks, function lists and limits are never touched.
+"""
+
+import copy
+import logging
+from typing import List, Optional
+
+from .sql_data_guard import _verify_sql
+
+logger = logging.getLogger(__name__)
+
+# Every configured table needs at least one column, so a table that is being added is seeded
+# with this name to let the verification go on and find the columns the query really uses.
+_PLACEHOLDER_COLUMN = "__sql_data_guard_placeholder__"
+_MAX_ROUNDS = 25
+_DELTA_TABLE_KEYS = {"table_name", "database_name", "columns"}
+
+
+def _identity(table_name: str, database_name: Optional[str]) -> tuple:
+    return str(table_name).lower(), str(database_name or "").lower()
+
+
+def _find_entry(tables: List[dict], table_name: str, database_name: Optional[str]) -> Optional[dict]:
+    """The configured table a query reference refers to (same rule as table_matches)."""
+    for entry in tables:
+        if str(entry["table_name"]).lower() != str(table_name).lower():
+            continue
+        configured_db = entry.get("database_name")
+        if database_name and configured_db and str(database_name).lower() != str(configured_db).lower():
+            continue
+        return entry
+    return None
+
+
+def _has_column(entry: dict, column: str) -> bool:
+    return str(column).lower() in {str(c).lower() for c in entry["columns"]}
+
+
+def validate_delta(delta: dict) -> None:
+    """Raises ValueError unless ``delta`` has the shape produced by ``suggest_config``."""
+    if not isinstance(delta, dict) or set(delta) != {"tables"} or not isinstance(delta["tables"], list):
+        raise ValueError("A config delta must be an object with a single 'tables' list.")
+    for table in delta["tables"]:
+        if not isinstance(table, dict) or not set(table) <= _DELTA_TABLE_KEYS:
+            raise ValueError(f"A delta table may only have the keys {sorted(_DELTA_TABLE_KEYS)}.")
+        if not isinstance(table.get("table_name"), str) or not table["table_name"]:
+            raise ValueError("Each delta table must have a 'table_name'.")
+        db = table.get("database_name")
+        if db is not None and not isinstance(db, str):
+            raise ValueError("'database_name' must be a string.")
+        columns = table.get("columns")
+        if not isinstance(columns, list) or not columns or not all(isinstance(c, str) and c for c in columns):
+            raise ValueError("Each delta table must have a non-empty 'columns' list of names.")
+
+
+def merge_config(config: dict, delta: dict) -> dict:
+    """
+    Returns a copy of ``config`` with the tables and columns of ``delta`` added.
+
+    A delta table with the same name (and database) as a configured one adds its missing columns
+    to it; any other delta table is appended. Nothing else in the configuration changes, and the
+    arguments are not modified. Raises ValueError if ``delta`` is malformed.
+    """
+    validate_delta(delta)
+    merged = copy.deepcopy(config)
+    tables = merged.setdefault("tables", [])
+    for table in delta["tables"]:
+        existing = next(
+            (
+                t
+                for t in tables
+                if _identity(t["table_name"], t.get("database_name"))
+                == _identity(table["table_name"], table.get("database_name"))
+            ),
+            None,
+        )
+        if existing is None:
+            tables.append(copy.deepcopy(table))
+            continue
+        for column in table["columns"]:
+            if not _has_column(existing, column):
+                existing["columns"].append(column)
+    return merged
+
+
+def suggest_config(sql: str, config: dict, dialect: Optional[str] = None) -> Optional[dict]:
+    """
+    Suggests the smallest allow-list addition that lets ``sql`` run as written.
+
+    Returns ``{"tables": [{"table_name", "database_name"?, "columns": [...]}, ...]}``, to be
+    applied with ``merge_config``; ``{"tables": []}`` if the query needs nothing added. Returns
+    None when widening the allow-list cannot make the query acceptable:
+
+    - the query is rejected for another reason (DML/DDL, several statements, a blocked function,
+      a column that cannot be attributed to one table, ...);
+    - it needs a table without naming any column (``SELECT *`` or ``COUNT(*)`` on a table the
+      configuration does not know), because a configured table must list its columns.
+
+    The suggestion is always checked: ``verify_sql`` on ``merge_config(config, delta)`` accepts
+    the query (allowed, or fixable). It never raises.
+    """
+    try:
+        return _suggest(sql, config, dialect)
+    except Exception as e:  # noqa: BLE001 - never suggest anything on unexpected errors
+        logger.error(f"Unexpected error while suggesting a config ({type(e).__name__})")
+        return None
+
+
+def _suggest(sql: str, config: dict, dialect: Optional[str]) -> Optional[dict]:
+    if not isinstance(config, dict) or not isinstance(config.get("tables"), list):
+        return None
+    working = copy.deepcopy(config)
+    tables = working["tables"]
+    delta_tables: dict = {}  # identity -> delta table
+
+    def delta_for(entry: dict) -> dict:
+        key = _identity(entry["table_name"], entry.get("database_name"))
+        if key not in delta_tables:
+            table = {"table_name": entry["table_name"], "columns": []}
+            if entry.get("database_name"):
+                table["database_name"] = entry["database_name"]
+            delta_tables[key] = table
+        return delta_tables[key]
+
+    for _ in range(_MAX_ROUNDS):
+        violations: List[dict] = []
+        _verify_sql(sql, working, dialect, violations)
+        progress = False
+        for v in violations:
+            if v["table_name"] is None:
+                return None  # a column that belongs to no single table: nothing to suggest
+            entry = _find_entry(tables, v["table_name"], v["database_name"])
+            if v["type"] == "table":
+                if entry is None:
+                    entry = {
+                        "table_name": v["table_name"],
+                        **({"database_name": v["database_name"]} if v["database_name"] else {}),
+                        "columns": [_PLACEHOLDER_COLUMN],
+                    }
+                    tables.append(entry)
+                    delta_for(entry)  # listed even if no real column is found (rejected below)
+                    progress = True
+            else:
+                if entry is None:
+                    return None
+                if not _has_column(entry, v["column"]):
+                    entry["columns"].append(v["column"])
+                    delta_for(entry)["columns"].append(v["column"])
+                    progress = True
+        if not progress:
+            break
+    else:
+        return None  # did not settle
+
+    # a table can only be configured with columns: drop what was found for none
+    result = [t for t in delta_tables.values() if t["columns"]]
+    if len(result) != len(delta_tables):
+        return None
+    delta = {"tables": result}
+    merged = merge_config(config, delta)
+    verdict = _verify_sql(sql, merged, dialect)
+    if not verdict["allowed"] and verdict["fixed"] is None:
+        return None
+    return delta