SQL 权限校验 huangzuting/dsh-plugin-sql-security-validate

dsh-plugin-sql-security-validate

AI SQL 权限校验拦截插件 — DeepSeek Harness 通用 AI 数据库权限管控插件。

拦截智能体（Agent）生成的越权 SQL：不静默改写、直接拒绝执行，并把结构化权限原因返回给模型，让模型自主剔除越权字段、更换统计口径，或用自然语言向用户解释权限不足。

- 插件 ID：dsh-plugin-sql-security-validate
- 适用框架：DeepSeek Harness（Cordis）
- 适配版本：DSH >= 0.1.x（本仓库验证于 0.2.0-rc.1）
- 开源协议：MIT

1. 它解决什么问题

| 问题 | 本插件的做法 |
| AI 自主生成越权 SQL，查询敏感表 / 敏感字段 | AST 解析全部资源，命中策略即拒绝执行 |
| 给 AI 的报错含糊，问答链路断裂 | 拒绝原因里带 SQL_PERMISSION_DENIED 与越权资源明细 |
| 静默改写导致 AI「以为数据完整」产生幻觉 | 永不改写 SQL，拒绝是显式的 |
| 个人轻量使用 vs 企业强安全，两套形态 | 全部加固项默认关闭，生产按需开启 |
| 多插件环境下拒绝决策被后置插件覆盖 | 可选单调守卫 ctx.tools.guard()，拒绝不可推翻 |

2. 边界（对外免责，清晰闭环）

1. 本插件仅防护 AI 智能体生成的越权 SQL。
2. 不存在「AI 底层绕过 MCP」的风险：Agent 没有网络与协议权限，无法直连 MCP 服务，所有 MCP 请求必须经过 DSH Runtime 调度流水线（Agent 输出工具调用 → 插件拦截层 → MCP 真实执行）。
3. 插件层唯一的覆盖风险来自多插件事件顺序，已由可选 Guard 严格模式彻底封堵。
4. 不防护「平台多工具名绕过」——需要平台侧收敛 MCP 工具入口。
5. 不做 MCP 服务层、IP 层、账号层鉴权——那属于服务安全范畴。

3. 安装

在 DSH Web GUI 的 插件市场 或 设置 → 插件 中安装本 bundle，或在会话里让 Agent 调用：

plugin_manager action=install_bundle target=<本目录绝对路径>

安装后 bundle 会在 profile 中插入一行 sql-security-validate，默认即启用。

4. 配置

配置项分两组呈现：

- 设置 → 插件 → AI SQL 权限校验拦截插件：可视化表单（由 Config schema 自动生成）。
- cordis.patch.yml：直接写 YAML，适合批量/版本化管理。

4.1 基础通用配置

| 配置项 | 类型 | 默认值 | 说明 |
| enable | boolean | true | 插件总开关 |
| auditEnable | boolean | true | 是否记录审计日志 |
| securityMode | enum | blacklist | blacklist / whitelist_emulate |

4.2 高级安全加固（默认全部关闭）

| 配置项 | 类型 | 默认值 | 说明 |
| enableStrictGuardMode | boolean | false | 单调守卫严格拦截（防插件覆盖） |
| enableAntiUnmount | boolean | false | 防卸载保护（生产加固） |
| enableBundleRequireLock | boolean | false | 强依赖校验 |
| requiredBundles | string[] | [] | 强依赖校验生效时必需的 bundle 包名 |

默认状态下：插件可随时卸载、无任何强制锁定、无启动强制依赖。

4.3 本地静态黑名单

| 配置项 | 默认值 |
| localBlacklist.tables（db.table） | ['db.admin', 'db.sensitive_log'] |
| localBlacklist.columns（db.table.column） | ['db.user.phone', 'db.user.idcard', 'db.user.bank_no'] |

4.3b 本地白名单（白名单模式无需中台）

| 配置项 | 默认值 | 说明 |
| localWhitelist.tables | [] | 允许访问的表；允许整表时只写表名 |
| localWhitelist.columns | [] | 允许访问的字段，用于按字段授权 |

白名单模式下，本地白名单与远程中台返回的授权取并集。

4.4 远程动态权限 OpenAPI

| 配置项 | 默认值 | 说明 |
| remotePolicy.enabled | false | 是否从权限中台拉取 |
| remotePolicy.policyApiUrl | '' | 权限中台接口地址 |
| remotePolicy.policyApiToken | '' | 接口鉴权 Token（role('secret')，不会被回显） |
| remotePolicy.apiTimeoutMs | 3000 | 超时时间（毫秒） |
| remotePolicy.cacheTtlMs | 30000 | 策略缓存时长（毫秒） |
| remotePolicy.tenantId | '' | tenantId 查询参数 |
| remotePolicy.userId | '' | userId 查询参数 |

4.5 拦截范围与审计（接线项）

| 配置项 | 默认值 | 说明 |
| targetToolPrefixes | ['mcp__'] | 只拦截这些前缀开头的工具；MCP 工具名恒为 mcp__<server>__<tool> |
| includeNonMcpSqlTools | false | 是否同时检查前缀之外的工具 |
| sqlParamKeys | ['sql','query','statement','text','command'] | 参数中哪些键按 SQL 解析 |
| allowSchemaDiscovery | true | 是否允许不带表名的结构发现语句（SHOW TABLES / SHOW DATABASES）。关掉则连表名都不给 |
| failOnParseError | false | 是否拒绝解析器无法识别的语句。打开更安全但会误伤 MySQL 历史语法 |
| strictDatabaseQualification | false | 白名单里的裸表名是否可匹配带库名的资源。默认宽容（user 也放行 mysql.user）；打开后裸表名仅匹配裸名 |
| audit.maxRecords | 5000 | 内存环形缓冲保留条数 |
| audit.redactSql | false | 是否把字符串字面量替换为 '' |
| audit.logPath | '' | 追加写 JSONL 的路径；空表示 $DSH_HOME/sql-security-validate/audit.jsonl |

4.6 结构发现语句怎么判定

DESCRIBE / SHOW 这类描述表结构的语句，与查询走同一套表级策略：

| 语句 | 已授权表 | 未授权表 | 不指名表 |
| DESCRIBE t / SHOW CREATE TABLE t | 放行 | 拒绝 | — |
| SELECT … FROM t | 放行 | 拒绝 | — |
| SHOW TABLES / SHOW DATABASES | — | — | 由 allowSchemaDiscovery 决定 |

这样 AI 依然能发现有哪些表、查看授权表的结构，据此写出合规查询；但碰不到未授权表的结构。若把结构发现也一律拒绝，AI 将无从了解库内有什么，问数能力随之失效。

5. 权限模式

黑名单模式（默认） — 无策略即放行；命中本地或远程黑名单即拒绝。适合绝大多数企业 AI 问数场景。

白名单模拟模式 — 无许可即禁止；仅放行「放行名单」里列出的资源。
放行名单有两个来源，可叠加：

1. 本地配置（localWhitelist，面板「放行名单」文本域）——无需任何外部服务；
2. 远程权限中台（remotePolicy.grantedTables / grantedColumns）——可选。

因此通用部署可以纯本地跑白名单，不依赖中台；需要集中管控时再接中台，两边条目取并集。适合政务、金融、央企、多租户强隔离场景。

6. 双拦截引擎

| 引擎 | 触发条件 | 特点 |
| pre-execute（默认） | 始终挂载 | 兼容性最强，可 await 远程策略 |
| guard（企业） | enableStrictGuardMode: true | 单调守卫，拒绝后任何后置插件都无法改回放行；同步判定，只用已缓存的远程策略 |

守卫是同步的，因此远程策略尚未取到时按 fail-closed 拒绝（宁可误拦，不可放过）。

7. 远程 OpenAPI 规范

请求：

GET {policyApiUrl}?tenantId=xxx&userId=xxx
Authorization: Bearer {policyApiToken}
Accept: application/json

标准返回体：

{
"code": 0,
"data": {
"forbiddenTables": [],
"forbiddenColumns": [],
"grantedTables": [],
"grantedColumns": []
}
}

grantedTables / grantedColumns 供白名单模拟模式使用。

降级策略：接口超时 / 非 2xx / code !== 0 / 结构非法 → 直接拒绝 SQL 执行（安全优先）。
空数组 → 仅使用本地策略。

8. 越权拒绝返回结构

插件不修改 SQL、不静默放行、不隐性删减字段。校验失败时模型看到：

{
"success": false,
"code": "SQL_PERMISSION_DENIED",
"message": "当前SQL包含无权限访问的资源，已禁止执行",
"detail": {
"forbiddenTables": ["db.admin"],
"forbiddenColumns": ["db.user.phone"],
"securityMode": "blacklist",
"interceptMode": "pre-execute",
"policySource": "local+remote"
}
}

模型收到后可自主执行：

1. 自动剔除越权字段重写 SQL；
2. 更换查询维度、更换统计方式；
3. 向用户用自然语言解释权限不足原因。

9. 执行链路

1. AI 生成 SQL 工具调用
2. 本插件 AST 解析所有表、字段资源（含 JOIN / 子查询 / CTE / 函数）
3. 合并【本地静态策略 + 远程中台策略】
4. 按拦截模式判断：pre-execute 拦截，或 guard 单调守卫拦截
5. 越权则拒绝执行、返回明细
6. 审计日志落库
7. AI 根据拒绝原因自主修正回答

判定边界（两条容易误解的规则）

- SELECT 在表上有列级规则时会被拒绝。 星号没有列清单可比对，无法证明它排除了被禁止的字段，因此直接拒绝，拒绝原因里记为 <表名>.。COUNT() 不属于这种情况——它是聚合，不暴露任何列值。
- 前导注释会在判定前剥掉。 语句可以以 --、#、/ / 开头，注释不携带语义，不允许它影响判定结果。

10. 审计日志

每条记录包含：原始 SQL、校验结果（放行/拒绝）、越权资源明细、权限来源、拦截模式、租户/用户信息、会话 ID、时间戳、工具名与 callId。

两种读取方式：

- 设置页面板：设置 →「SQL 权限校验」。可直接操作，见下节。
- JSONL 文件：$DSH_HOME/sql-security-validate/audit.jsonl，一行一条 JSON，可直接 tail / grep / 交给日志采集。

设置页可以做什么

| 操作 | 说明 |
| 总开关 | 一键启用/停用拦截（停用后所有 SQL 直接放行） |
| 黑白名单切换 | blacklist ⇄ whitelist_emulate |
| 严格守卫开关 | 开/关 enableStrictGuardMode |
| 编辑黑名单 | 禁区表、禁区字段两个文本域 |
| 编辑白名单 | 放行表、放行字段两个文本域（不需要权限中台） |
| 审计明细 | 点任意一行展开：原始 SQL、命中的具体策略条目、检查到的表、权限来源、引擎、会话 |
| 清空审计 | 同时清空内存环与磁盘文件 |

策略为空时面板会给出解释：黑名单模式下说明「未禁止即放行」、当前不会拦截任何 SQL；白名单模式下说明「未列出一律禁止」、当前所有 SQL 都会被拒，并明确这不是故障。
两种状态都附带示例写法与保存方式，避免用户误判插件没生效。

审计记录除「越权资源」外还保留 matchedRules（命中哪条策略）与 inspectedTables（本次检查了哪些表）——被拒的表和拒绝它的规则是两件事。

内存环保持最新 audit.maxRecords 条供即时读取；启用后同时追加到文件，重启后自动回填历史。
审计写入是 fail-soft 的：磁盘问题只损失历史，永不阻塞工具调用。

11. 防卸载与依赖机制

- 所有安全锁定默认关闭；默认状态下插件可随时卸载、无强制锁定、无启动强制依赖。
- enableAntiUnmount 打开后，plugin_manager 对本插件的停用/移除操作会被守卫拒绝，并提示先关闭该开关。它不改写 profile、不删除文件，是完全可解释、可撤销的硬化。
- enableBundleRequireLock 打开后，requiredBundles 中列出的 bundle 若未在本轮 profile 中选中，插件激活即失败（fail loud）。
- 源码完全开放二次开发，可永久固化安全策略。

12. 开发与测试

npm test # 或 pnpm test

- tests/unit.mjs — SQL 资源解析、策略引擎、远程客户端的 49 项断言
- tests/engine.mjs — 在真实 apply() 接线上的 28 项端到端断言（含审计路由与策略命中）
- tests/report-vectors.mjs — 第三方安全报告的 15 组向量（DESCRIBE / SHOW / 结构发现语义）

模块布局：

| 文件 | 职责 |
| src/index.js | 插件入口：Config、双引擎挂载、防卸载、审计接线与只读路由 |
| src/client.js | 浏览器半边：设置页只读面板（当前策略 + 最近拦截记录） |
| src/sql-parse.js | 基于 AST 的 SQL 资源提取（vendored node-sql-parser） |
| vendor/node-sql-parser/ | 内联的 SQL 解析器（2.8 MB，见其 README） |
| src/policy.js | 权限决策引擎与远程 OpenAPI 客户端 |
| src/audit.js | 审计日志：内存环 + JSONL 追加写 |

13. 已知限制

- 客户端面板由 Host 启动时的模块图装配；新增或改动 src/client.js 后需要重启
dsh web 并刷新页面才会生效（Cordis 的 HMR 不重新导入已缓存的 ESM 模块）。
- 严格守卫模式下，远程策略中台成为硬依赖：中台不可用时所有 SQL 调用都会被拒绝。
- 插件只识别 targetToolPrefixes 内的工具；若某个 MCP 数据库工具名不匹配，需自行补充前缀或打开 includeNonMcpSqlTools。

14. 许可证

MIT