sql-safe-mcp 1.5.1__tar.gz → 2.0.0__tar.gz

{sql_safe_mcp-1.5.1 → sql_safe_mcp-2.0.0}/CHANGELOG.md

@@ -7,6 +7,77 @@ categories `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`.
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-11-07
+
+### Added
+
+- `sql-safe-mcp --verify-pii-rules [--strict]` connects to each `all_pii_safe` alias, reports how
+  many tables and columns every PII rule matches, and warns about rules that match nothing
+  (exit 2 with `--strict`) and about unprotected columns whose names look personal.
+- `logging.audit: true` writes one `sql_safe_mcp.audit` line per `execute_sql` call with the server,
+  database, tables and columns read, protected column count, row count, truncation, and elapsed
+  time (or the error `code`). It never contains SQL, bind values, rows, or tokens. Off by default;
+  the tool response is unchanged.
+- `--verify-pii-rules` also checks `pii.exposed_columns` and `pii.deny` entries (unmatched ones
+  warn and fail `--strict`) and, in `deny-by-default`, advises only on exposed columns.
+- `pii.mode: deny-by-default` protects every column not listed in `pii.exposed_columns`, and
+  `pii.deny` rejects any reference to a column with `QUERY_REJECTED` ("a denied column cannot be
+  referenced"). Existing configurations are unchanged. See `docs/configuration.md`.
+- `runtime.token_ttl_seconds` (off by default) rejects tokens older than the limit with
+  `INVALID_PII_TOKEN`. Enabling it also rejects tokens issued before it was set. The token format
+  stays `pii:v1:`.
+- `runtime.min_count_cell` (off by default) makes `execute_sql` return a `COUNT(*)` value from 1
+  to the threshold minus one as `null`, with the new column encoding `suppressed`. `0` is not
+  suppressed.
+- `pii_key_file` reads an alias key from a file instead of `pii_key_env`; a relative path is
+  resolved against the configuration file's directory. On POSIX the file must be owned by the
+  server user or root, with no access for others and no group write.
+
+### Security
+
+- With `logging.level: DEBUG`, the MCP SDK no longer writes a malformed protocol message to
+  stderr; its logger is held at `INFO` or above, because that message could carry SQL, tokens,
+  or rows.
+- `all_pii_safe` aliases now require verified TLS in `connection_url`: SQL Server needs
+  `Encrypt=yes` and rejects `TrustServerCertificate=yes` and `odbc_connect`; MySQL and MariaDB
+  need `ssl_ca` or `ssl_capath` and reject options that turn certificate checks off. A
+  configuration without them fails at startup with `CONFIG_ERROR`. `require_tls: false` on the
+  alias turns the check off and logs a warning at every start.
+- After loading the configuration, the server removes `pii_key_env` variables from its environment,
+  so child processes such as ODBC drivers no longer inherit PII keys.
+- `pii.rules` entries accept an optional `domain`. A token returned for a column of one domain is
+  rejected with `INVALID_PII_TOKEN` when compared with a column of another domain, so protected
+  values cannot be replayed across unrelated columns. Without `domain` the domain is the server
+  alias. Rules of different domains matching one column reject queries touching it with
+  `QUERY_REJECTED`.
+- PII tokens now pad their payload to a multiple of 32 bytes, so token length reveals only a
+  32-byte bucket of the plaintext length.
+- Tokens issued before padding and domains are rejected with `INVALID_PII_TOKEN`; agents must
+  request new tokens.
+- `execute_sql` now allows each SQL construct only in the positions the supported subset uses.
+  A bare column or literal used as a condition (`WHERE a`, `ON 1`, `WHERE a AND b = 1`) and any
+  other node in an unlisted position is rejected with `QUERY_REJECTED` before the database runs
+  the query.
+- `execute_sql` now checks a PII token against the type of the protected column it is compared
+  with. A string token compared with an integer or decimal column, or any token compared with a
+  column of an unrecognised type, is rejected with `QUERY_REJECTED` before the database runs the
+  query. Before, SQL Server could echo the decrypted value in a conversion error (for example
+  error 245).
+- Driver error messages in logs no longer carry values. Quoted literals (`'…'`, `N'…'`, `"…"`)
+  become `'***'` and digit runs of six or more become `***`, since SQL Server and MySQL echo the
+  offending value in conversion and duplicate-key errors. A failed `execute_sql` logs only the
+  driver error class and its SQLSTATE or numeric code, with no message text.
+
+## [1.5.2] - 2026-10-05
+
+### Security
+
+- `execute_sql` now rejects a projection whose alias names anything other than a direct column,
+  a literal, or `COUNT(*)`, such as `SELECT (Email) AS e FROM Users`. Before, the expression was
+  classified as a literal, so a protected column wrapped in parentheses was returned in clear,
+  and on MySQL/MariaDB a projected comparison such as `(Email > 'm') AS x` acted as an oracle on
+  the protected value. The lineage stage also fails closed on any untraceable projection.
+
 ## [1.5.1] - 2026-09-23
 
 ### Fixed

{sql_safe_mcp-1.5.1 → sql_safe_mcp-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sql-safe-mcp
-Version: 1.5.1
+Version: 2.0.0
 Summary: Minimal, read-only, PII-safe MCP server for SQL databases.
 License: MIT License
         
@@ -26,10 +26,10 @@ License: MIT License
 License-File: LICENSE
 Requires-Python: <3.15,>=3.12
 Requires-Dist: anyio<5,>=4.8
-Requires-Dist: cryptography<47,>=46.0.7
+Requires-Dist: cryptography<51,>=48.0.1
 Requires-Dist: mcp<3,>=2
 Requires-Dist: pydantic<3,>=2.10
-Requires-Dist: pymysql>=1.2.3
+Requires-Dist: pymysql<2,>=1.2.3
 Requires-Dist: pyodbc<6,>=5.2
 Requires-Dist: pyyaml<7,>=6
 Requires-Dist: sqlalchemy<3,>=2.0
@@ -133,7 +133,7 @@ or
 pip install sql-safe-mcp
 ```
 
-Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.5.1`.
+Pin a version when you want a fixed surface: `uvx sql-safe-mcp==2.0.0`.
 
 Requires Python 3.12–3.14, [uv](https://docs.astral.sh/uv/) (or `pip`), and
 [Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server)
@@ -265,9 +265,12 @@ only to stderr.
 ```
 
 can return a row such as `[42, "pii:v1:..."]`: the agent can follow the customer without reading
-the email address. A token is accepted only in `=` and `IN` predicates on the same protected column
-and server alias. Protection covers the columns you list, so list every column that holds personal
-data.
+the email address. A token is accepted only in `=` and `IN` predicates on the same server alias.
+If `FirstName` is protected, `SELECT FirstName FROM Users WHERE FirstName = 'Alice'` is rejected
+before it reaches the database. Filter protected columns only with authentic `pii:v1:...` tokens
+returned by `execute_sql` for the same alias; a matching prefix alone is not enough. Each token is
+authenticated and alias-bound, then validated and converted to a bound database value.
+Protection covers the columns you list, so list every column that holds personal data.
 
 ## Documentation
 
@@ -275,6 +278,8 @@ data.
   limits, and logging.
 - [Tool reference](docs/tools.md) - arguments, responses, errors, and the accepted SQL subset.
 - [Security model](docs/security-model.md) - trust boundaries, guarantees, limitations, and verification.
+- [Health data of minors](docs/health-data.md) - requirements, mechanisms, and an operator
+  checklist for medical deployments.
 - [Checks](docs/checks.md) - local, integration, and security verification commands.
 
 ## Security

{sql_safe_mcp-1.5.1 → sql_safe_mcp-2.0.0}/README.md

@@ -95,7 +95,7 @@ or
 pip install sql-safe-mcp
 ```
 
-Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.5.1`.
+Pin a version when you want a fixed surface: `uvx sql-safe-mcp==2.0.0`.
 
 Requires Python 3.12–3.14, [uv](https://docs.astral.sh/uv/) (or `pip`), and
 [Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server)
@@ -227,9 +227,12 @@ only to stderr.
 ```
 
 can return a row such as `[42, "pii:v1:..."]`: the agent can follow the customer without reading
-the email address. A token is accepted only in `=` and `IN` predicates on the same protected column
-and server alias. Protection covers the columns you list, so list every column that holds personal
-data.
+the email address. A token is accepted only in `=` and `IN` predicates on the same server alias.
+If `FirstName` is protected, `SELECT FirstName FROM Users WHERE FirstName = 'Alice'` is rejected
+before it reaches the database. Filter protected columns only with authentic `pii:v1:...` tokens
+returned by `execute_sql` for the same alias; a matching prefix alone is not enough. Each token is
+authenticated and alias-bound, then validated and converted to a bound database value.
+Protection covers the columns you list, so list every column that holds personal data.
 
 ## Documentation
 
@@ -237,6 +240,8 @@ data.
   limits, and logging.
 - [Tool reference](docs/tools.md) - arguments, responses, errors, and the accepted SQL subset.
 - [Security model](docs/security-model.md) - trust boundaries, guarantees, limitations, and verification.
+- [Health data of minors](docs/health-data.md) - requirements, mechanisms, and an operator
+  checklist for medical deployments.
 - [Checks](docs/checks.md) - local, integration, and security verification commands.
 
 ## Security

{sql_safe_mcp-1.5.1 → sql_safe_mcp-2.0.0}/pyproject.toml

@@ -1,16 +1,16 @@
 [project]
 name = "sql-safe-mcp"
-version = "1.5.1"
+version = "2.0.0"
 description = "Minimal, read-only, PII-safe MCP server for SQL databases."
 readme = "README.md"
 requires-python = ">=3.12,<3.15"
 license = { file = "LICENSE" }
 dependencies = [
     "anyio>=4.8,<5",
-    "cryptography>=46.0.7,<47",
+    "cryptography>=48.0.1,<51",
     "mcp>=2,<3",
     "pydantic>=2.10,<3",
-    "pymysql>=1.2.3",
+    "pymysql>=1.2.3,<2",
     "pyodbc>=5.2,<6",
     "pyyaml>=6,<7",
     "sqlalchemy>=2.0,<3",
@@ -63,7 +63,7 @@ markers = [
 [tool.mutmut]
 source_paths = ["src/sql_safe_mcp"]
 also_copy = ["server.json", "README.md", "tools", "scripts", "compose.sqlserver.yml", "compose.mysql.yml"]
-only_mutate = ["*security/*.py", "*config.py"]
+only_mutate = ["*security/*.py", "*config.py", "*diagnostics.py", "*service.py"]
 mutate_only_covered_lines = true
 pytest_add_cli_args = ["-q", "-m", "not integration and not deep", "-p", "no:cacheprovider"]
 pytest_add_cli_args_test_selection = ["tests/unit", "tests/security", "tests/contract"]

{sql_safe_mcp-1.5.1 → sql_safe_mcp-2.0.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/proprock/sql-safe-mcp",
     "source": "github"
   },
-  "version": "1.5.1",
+  "version": "2.0.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "sql-safe-mcp",
-      "version": "1.5.1",
+      "version": "2.0.0",
       "transport": {
         "type": "stdio"
       }

{sql_safe_mcp-1.5.1 → sql_safe_mcp-2.0.0}/sql-safe-mcp.example-multi.yaml

@@ -19,11 +19,14 @@ servers:
   billing:
     # `sqlserver` uses an mssql+pyodbc URL; the URL dialect must match this engine.
     engine: sqlserver
-    # all_pii_safe requires both `pii_key_env` and at least one effective local PII rule.
+    # all_pii_safe requires a key (`pii_key_env` or `pii_key_file`) and at least one effective PII rule.
     access_level: all_pii_safe
+    # all_pii_safe requires verified TLS: the URL must set Encrypt=yes and must not set
+    # TrustServerCertificate=yes. `require_tls: false` turns the check off for a dev server.
     connection_url: "${BILLING_SQL_URL}"
     # Environment-variable name for one base64-encoded 32-byte key. Names must match
-    # ^[A-Z_][A-Z0-9_]*$; each all_pii_safe alias needs a different key.
+    # ^[A-Z_][A-Z0-9_]*$; each all_pii_safe alias needs a different key. Instead of
+    # pii_key_env you may set `pii_key_file: secrets/billing.key` (relative to this file).
     pii_key_env: BILLING_PII_KEY
     pii:
       # Only local rules are used in this file; `include` is intentionally absent.
@@ -42,6 +45,7 @@ servers:
     # mysql and mariadb both use mysql+pymysql URLs. Select the engine matching the server.
     engine: mysql
     access_level: all_pii_safe
+    # Verified TLS for MySQL/MariaDB: the URL must set ssl_ca (or ssl_capath).
     connection_url: "${SHOP_MYSQL_URL}"
     pii_key_env: SHOP_PII_KEY
     pii:

{sql_safe_mcp-1.5.1 → sql_safe_mcp-2.0.0}/sql-safe-mcp.example-shared.yaml

@@ -38,6 +38,9 @@ pii_rules:
         schema: dbo # Optional for SQL Server; omit it to match every schema.
         table: "Users[0-9]?"
         columns: [Email, FirstName, LastName]
+        # Optional token domain (alias character set). Tokens of one domain are accepted only on
+        # columns of that domain; without it the domain is the server alias.
+        domain: users_identity
 
 servers:
   legacy-prod:
@@ -65,6 +68,21 @@ servers:
           table: Cards
           columns: [HolderName]
 
+  peds-deny-by-default:
+    engine: sqlserver
+    access_level: all_pii_safe
+    connection_url: "${PEDS_SQL_URL}"
+    pii_key_env: PEDS_PII_KEY
+    pii:
+      # `deny-by-default` protects every column that exposed_columns does not list.
+      mode: deny-by-default
+      exposed_columns: # `database` is optional here and defaults to "*".
+        - table: Visits
+          columns: [VisitId, DepartmentCode, VisitYear]
+      deny: # Unreachable even as a token; columns: ["*"] denies a whole table.
+        - table: "*"
+          columns: [Notes, Anamnesis, Attachment]
+
   reporting-metadata:
     engine: sqlserver
     access_level: metadata

{sql_safe_mcp-1.5.1 → sql_safe_mcp-2.0.0}/src/sql_safe_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Minimal, PII-safe MCP server for relational databases."""
 
-__version__ = "1.5.1"
+__version__ = "2.0.0"

{sql_safe_mcp-1.5.1 → sql_safe_mcp-2.0.0}/src/sql_safe_mcp/__main__.py

@@ -10,6 +10,7 @@ from pathlib import Path
 from sql_safe_mcp.config import load_config
 from sql_safe_mcp.errors import DomainError
 from sql_safe_mcp.mcp_server import create_server
+from sql_safe_mcp.pii_audit import collect_catalog, verify_pii_rules
 
 
 def _positive_int(value: str) -> int:
@@ -41,11 +42,24 @@ def _parser() -> argparse.ArgumentParser:
         metavar="N",
         help="Print N base64-encoded 32-byte PII keys (default: 1) and exit.",
     )
+    actions.add_argument(
+        "--verify-pii-rules",
+        action="store_true",
+        help="Connect to each all_pii_safe alias and report PII rules that match nothing.",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="With --verify-pii-rules, exit 2 when any rule matches nothing.",
+    )
     return parser
 
 
 def main() -> None:
-    args = _parser().parse_args()
+    parser = _parser()
+    args = parser.parse_args()
+    if args.strict and not args.verify_pii_rules:
+        parser.error("--strict requires --verify-pii-rules")
     if args.gen_pii_key is not None:
         for _ in range(args.gen_pii_key):
             print(base64.b64encode(secrets.token_bytes(32)).decode("ascii"))
@@ -58,6 +72,12 @@ def main() -> None:
     if args.check_config:
         print(f"Configuration valid: {len(config.servers)} server alias(es).")
         return
+    if args.verify_pii_rules:
+        report = verify_pii_rules(config, collect_catalog)
+        print("\n".join(report.lines), file=sys.stderr)
+        if report.errors or (args.strict and report.unmatched_rules):
+            raise SystemExit(2)
+        return
     create_server(config).run("stdio")