@yanzhang123/readonly-db-mcp 0.9.7 → 0.9.9

package/ENTERPRISE_DEPLOYMENT.md

@@ -160,8 +160,14 @@ on unmatched started events and preserve them during incident review.
 
 Result masking is a final egress control, not an authorization boundary. Source
 columns matching `mask_columns` are redacted through aliases, expressions,
-subqueries and CTEs; unresolved outputs fall back to their result names. Bare
-patterns match only field names, and qualified patterns retain their scope.
+conversions, window functions, subqueries, derived tables, CTEs, set operations,
+JSON_TABLE, TABLE statements and stars. It is designed to fail closed: an output
+whose source cannot be determined is masked when it could come from a matching
+field, so complex queries may show extra redactions. Static analysis cannot see
+view definitions, stored-function bodies or real schemas, and cannot rule out
+SQL shapes it does not yet model. Bare
+patterns match only field names; qualified patterns retain their scope, resolve
+table aliases, and use the selected database for unqualified tables.
 COUNT statistics remain available without exposing their input values. Masking
 is disabled by default: omitted or empty `mask_columns` returns all field values
 without redaction. Configure the fields to mask per connection; there is no

package/README.md

@@ -72,14 +72,16 @@ npx -y @yanzhang123/readonly-db-mcp@0.9.1
 
 服务启动后，建议依次调用 `validate_connections` 和 `check_connection`，确认配置有效、网络可达、账号权限符合预期。`check_connection` 只返回不可逆账号指纹和权限分类，不会暴露用户名或原始授权语句。
 
-### 手动安装 Python 包
+### 从源码安装 Python 包
+
+本项目只通过上述 npm 包发布，不发布到 PyPI。PyPI 上名为 `mysql-mcp-server` / `mysql_mcp_server` 的包属于上游原项目，不包含本分支的只读、审计和脱敏实现，请勿用 `pip install mysql-mcp-server` 安装。源码部署时从本仓库安装：
 
 ```bash
-pip install mysql-mcp-server
+git clone https://github.com/12zhangyan/mysql_mcp_server.git
+cd mysql_mcp_server
+pip install ".[http]"   # 只用 STDIO 时可省略 [http]
 ```
 
-Python 包仍适用于源码部署，但本分支的主要分发方式是上述 npm 包。
-
 ## 配置
 
 ### 结果脱敏配置
@@ -98,7 +100,11 @@ mask_columns = [] # 默认全部放开；省略此项效果相同。
 
 旧单连接模式通过 `MYSQL_MASK_COLUMNS` 配置，以逗号分隔；未设置或设为空字符串均不脱敏。例如 `MYSQL_MASK_COLUMNS=password,access_token` 只按这两个规则处理。使用命名连接文件时，以各连接自己的 `mask_columns` 为准。
 
-显式配置会追踪别名、表达式和 CTE 的字段来源，并对 JSON 内匹配的键递归处理。不带点的模式只匹配字段名，例如 `password`；带点的模式按限定路径匹配，例如 `users.phone`。`COUNT` / `COUNT(DISTINCT ...)` 统计值可以正常读取，同一查询中匹配规则的原始值和拼接值仍会隐藏。
+显式配置会把每个结果列追溯到底层表的字段：别名、表达式、函数与类型转换、窗口函数、标量子查询与关联子查询、派生表、CTE（含列清单）、`UNION`、`LATERAL`、`JSON_TABLE`、`TABLE` 语句和 `*` 都会继续追踪，并对 JSON 内匹配的键递归处理。按路径从 JSON 文档读取的值也会检查路径中的键：`JSON_EXTRACT`、`->`、`->>`、`JSON_VALUE` 和 `JSON_TABLE` 列的路径只要经过匹配不带点规则的键（例如 `$.contact.phone` 匹配 `phone`），读出的值就会隐藏；路径含通配符、递归 `**` 或不是常量时按敏感处理。派生表或 CTE 中名称匹配规则的列也视为敏感来源；只有最外层的别名不算。不带点的模式只匹配字段名，例如 `password`；带点的模式按限定路径匹配，例如 `users.phone` 或 `app.users.phone`，表别名会解析回真实表名，未写库名的表按当前库匹配。`COUNT` / `COUNT(DISTINCT ...)` 统计值可以正常读取，同一查询中匹配规则的原始值和拼接值仍会隐藏；`WHERE`、`HAVING`、`EXISTS`、`IN` 子查询里的值不会出现在结果中，不会让其他列被遮蔽。
+
+脱敏按 fail-closed 设计：某个结果列的来源无法确定时（例如无法解析的列名、子查询中可能来自外层查询的列，或 MySQL 自动生成、与表达式文本对不上的列名），只要它可能来自匹配规则的字段，就按敏感处理；SQL 分析失败时同样按保守规则处理。因此少数复杂查询可能多遮几列。
+
+脱敏是结果出口的辅助控制，不是访问授权边界：它基于 SQL 静态分析，无法看到视图定义、存储函数内部或数据库中实际的表结构，也不能排除尚未覆盖的 SQL 写法。绝不能暴露的字段，应在数据库层用只包含安全字段的视图或列级权限隔离，再让本服务使用该账号。
 
 脱敏只替换返回值，不改变 MySQL 的 `WHERE` / `JOIN` 条件或删除结果行。`[REDACTED]` 表示值被隐藏，JSON/compact 的 `masked_columns` 可定位受影响列。已有的非空配置仍会生效；需要全部放开时，把它改成空列表（单连接模式清空环境变量），或删除该配置项。
 

package/SECURITY.md

@@ -161,13 +161,32 @@ The MCP server includes built-in protection against SQL injection for administra
 - Result masking is opt-in: `mask_columns` defaults to an empty list, and legacy
   `MYSQL_MASK_COLUMNS` defaults to empty. There is no built-in sensitive-field list;
   omitted or empty rules return all field values without redaction, including JSON
-  keys. When rules are configured, matching source columns (or output names when
-  unresolved) and JSON keys are replaced with `[REDACTED]`. Unqualified patterns
-  match only field names; qualified patterns retain table/database scope. Aliases,
-  expressions and CTEs retain tracing. COUNT statistics do not inherit masking
-  from their inputs, while matching raw values and combined expressions remain
-  masked. Configure rules against your schema; name-based masking cannot replace
-  database views or column-level permissions.
+  keys. When rules are configured, each result column is traced through aliases,
+  expressions and conversions, window functions, scalar and correlated
+  subqueries, derived tables, CTEs (including column lists), set operations,
+  LATERAL, JSON_TABLE, TABLE statements and stars to base-table columns, and
+  matching sources and JSON keys are replaced with `[REDACTED]`. Columns of derived
+  tables and CTEs whose names match are sensitive sources too; only final output
+  aliases are exempt. Unqualified patterns match only field names; qualified
+  patterns retain table/database scope, resolve table aliases, and apply the
+  selected database to tables named without one. COUNT statistics do not inherit
+  masking from their inputs, while matching raw values and combined expressions
+  remain masked. Values from WHERE, HAVING, EXISTS and IN subqueries never reach
+  the result and do not mask other columns.
+- Values read from a JSON document by path (`JSON_EXTRACT`, `->`, `->>`,
+  `JSON_VALUE`, JSON_TABLE column paths) are masked when any key on the path
+  matches an unqualified pattern, consistent with key masking inside returned JSON
+  text. Wildcard, recursive (`**`) and computed paths are treated as sensitive.
+- Masking is designed to fail closed: a result column whose source cannot be
+  determined (including unqualified names a subquery may resolve in the outer
+  query) is treated as sensitive if it could come from a matching field, and
+  analysis failures fall back to conservative rules. Some complex queries may
+  therefore show extra `[REDACTED]` columns.
+- Masking is a static-analysis egress control, not an authorization boundary. It
+  cannot see view definitions, stored-function bodies, or actual table schemas,
+  and cannot rule out SQL shapes it does not yet model.
+  Fields that must never be exposed belong behind database views or column-level
+  permissions for the account this server uses.
 
 These controls enforce the MCP read-only contract even when the supplied MySQL
 account has write privileges. A `SELECT`-only account is still recommended as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanzhang123/readonly-db-mcp",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "description": "Enterprise-auditable, strictly read-only MySQL MCP server with multi-environment profiles.",
   "license": "MIT",
   "type": "commonjs",