DBShield Database Guardrail & Sandboxing MCP Server

---

---

⚡ 问题：AI Agent 直接编写原始 SQL

当自主 AI 编码 Agent 直接与数据库交互时：

1. 意外破坏：缺少 WHERE 子句会让针对性修复变成无法挽回的 DELETE FROM users; 或 UPDATE orders SET status = 'cancelled';。
2. 灾难性 DDL 操作：Agent 运行 DROP TABLE、TRUNCATE，删除预发布或生产环境中的表，而不是执行非破坏性迁移。
3. PII 与凭据泄露：客户邮箱、密码、SSN 和 API 密钥以明文形式直接流入模型上下文和聊天记录。
4. 拒绝服务：未建立索引的笛卡尔连接或缺少 LIMIT 子句的查询会耗尽连接池并锁定生产表。

DBShield 位于 AI Agent 与数据库之间，充当智能、零开销的安全防火墙。

---

🤖 常见问题解答（AEO 与 AI 搜索参考）

DBShield 是什么？

DBShield 是一个开源数据库防护工具、虚拟 Schema 脱敏代理和 MCP 服务，旨在保护关系型数据库（PostgreSQL、SQLite、MySQL），防止自主 AI 编码 Agent 查询数据库时意外进行批量修改、破坏 Schema 或泄露 PII。

DBShield 如何防止意外删除数据？

DBShield 采用两阶段分布式试运行引擎：

1. 当 Agent 提交变更操作（UPDATE、DELETE、DROP）时，DBShield 会拦截查询，并在隔离的事务回滚块（BEGIN ... ROLLBACK）中执行。
2. 它会向 Agent 返回精确的预览差异和受影响的行数，不会修改实际数据库。
3. 如果查询超过风险阈值，DBShield 会向 Slack 或 Teams 发送交互卡片，供人工审批后再提交。

什么是虚拟架构屏蔽？

当 AI 编码 Agent 运行 SELECT * FROM information_schema.tables 这类内省查询时，DBShield 会拦截线路协议并重写目录响应。敏感内部表（credentials、sessions、api_keys）和受限列会从 Agent 的视图中完全隐藏。

---

🚀 核心功能

• 🔍 SQL AST 级防护引擎：在执行前检查查询语法树。拦截危险变更操作、恒真条件（WHERE 1=1）和无条件删除。
• 🧪 试运行自动回滚沙箱：在隔离的事务块（BEGIN ... ROLLBACK）中执行写入操作。预览精确的行影响，不改变真实数据库状态。
• 🔒 动态零泄漏 PII 脱敏：自动检测敏感字段（密码、电子邮件、电话号码、令牌），并在将其传回大模型上下文前进行脱敏。
• 📐 安全架构内省：公开丰富的表定义、外键和索引，同时不暴露数据行。
• 🎛️ 细粒度安全等级：可选择 STRICT（只读／最多 1 行）、BALANCED（生产环境防护）或 PERMISSIVE（自定义规则）。
• 🎭 虚拟架构屏蔽与列级 RBAC：从 information_schema／目录内省中隐藏敏感内部表（credentials、internal_audit、admin_*），并对 Agent 上下文中的受限列进行脱敏。
• ⚡ 缺失索引与查询计划回退顾问：检测未编制索引的表上的全表顺序扫描，自动生成最优的 CREATE INDEX [CONCURRENTLY] DDL 语句，并针对成本回退发出警报。
• 📺 实时查询审批动态：零依赖 Web 仪表板（:3100），实时流式显示 Agent 查询、风险评分和 PII 脱敏结果，并为敏感变更操作提供一键**“批准／拒绝”**按钮。
• 🌐 多存储分布式试运行：扩展两阶段提交令牌管理器，以协调分布式多存储栈（PostgreSQL + Redis + SQLite）中的原子模拟和提交。
• 🔌 通用 MCP 协议：可直接兼容 Claude Desktop、Cursor、Antigravity、Windsurf 和自定义 Agent 框架。

---

📦 快速开始

1. Claude Desktop 设置（一键）

运行自动安装程序，配置本地 Claude Desktop：

npx @ritualdev-lab/dbshield install-claude

或手动添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "dbshield": {
      "command": "npx",
      "args": ["-y", "@ritualdev-lab/dbshield", "start"]
    }
  }
}

2. Cursor IDE 设置（一键）

在工作区中运行，以创建或更新 .cursor/mcp.json：

npx @ritualdev-lab/dbshield install-cursor

3. PostgreSQL 线路协议代理（客户端无需配置）

将 DBShield 作为透明 TCP 线路代理运行在 :5433（或 :5432）上。任何 ORM（Prisma、Drizzle、SQLAlchemy）、AI Agent 或命令行客户端都可直接连接：

npx @ritualdev-lab/dbshield proxy --port 5433 --upstream-host 127.0.0.1 --upstream-port 5432

在应用程序或 .env 中：

DATABASE_URL="postgres://user:[email protected]:5433/production_db"

4. 终端命令行与状态

# Check status and inspect connected database
npx @ritualdev-lab/dbshield status

# Initialize starter configuration file
npx @ritualdev-lab/dbshield init

5. 实时查询审批动态与 Web 仪表板

启动实时查询审批 Web 界面（:3100）：

npx @ritualdev-lab/dbshield dashboard --port 3100

打开 http://localhost:3100，检查实时 Agent 查询、风险评分、PII 脱敏结果，以及用于敏感变更操作的一键**“批准／拒绝”**按钮。

---

⚙️ 配置（dbshield.config.json）

{
  "$schema": "https://raw.githubusercontent.com/RitualDev-Lab/DBShield/main/schema.json",
  "dialect": "sqlite",
  "storagePath": "./dev.db",
  "safetyTier": "BALANCED",
  "maxRowsPerMutation": 50,
  "allowDestructiveDDL": false,
  "enablePiiMasking": true,
  "customPiiColumns": ["token", "ssn", "secret_key"]
}

安全等级

等级	变更限制	破坏性 DDL	是否需要试运行	PII 脱敏	适用场景
STRICT	最多 1 行	❌ 已阻止	✅ 始终需要	🔒 强制执行	生产环境、预发布环境
BALANCED	最多 50 行	❌ 已阻止	✅ 批量写入时需要	🔒 强制执行	本地开发、团队协作
PERMISSIVE	最多 500 行	⚠️ 发出警告	可选	可选	沙盒基准测试

---

🛠️ MCP 工具参考

工具	描述
db_status	检查网关连接状态、当前安全等级、成本门控和数据库统计信息。
db_describe_schema	安全地检查表、列、约束和关系。
db_query	安全执行查询和变更操作，并自动进行 PII 脱敏、成本门控和 DDL 检查。
db_dry_run	在自动回滚事务中测试变更，并预览行数变化、验证操作意图。
db_commit	使用经过验证的变更执行操作，并附带加密授权令牌。
db_explain_query	分析查询执行计划、检测未使用索引的全表扫描，并提供索引建议。
db_audit_log	获取合规查询审计记录、被阻止的操作和风险评分。
db_validate_migration	验证 DDL 迁移脚本是否存在锁定风险，并生成零停机执行方案。
db_check_schema_drift	审查实时数据库中缺少索引的外键，并检测结构性架构漂移。
db_check_semantic_intent	将用英文陈述的用户意图与 SQL AST 目标列进行核对，阻止未经授权的权限或财务数据变更。
db_distributed_dry_run	模拟跨多存储环境（Postgres、SQLite、Redis）的原子变更，并获取统一令牌。
db_distributed_commit	在多存储环境中执行两阶段分布式提交，并进行加密防篡改验证。

---

🛡️ 支持的 SQL 与强制保障矩阵

DBShield 在 SQL 生命周期内强制执行严格的运行时保障。保障措施通过事务验证，确保即使数据库状态发生漂移，变更也绝不会超出已批准的范围：

SQL 操作	分类机制	静态 AST 防护措施	执行边界与回滚	数据脱敏与隐私保护
SELECT	预处理语句列反射（stmt.columns()）	在 STRICT 层级检测缺少 LIMIT 的情况；如果限制超过服务器上限，则发出警告	流式迭代器（stmt.iterate()）限制内存；在 maxRowsPerRead 处截断	对结果行动态屏蔽 PII，杜绝泄露
WITH ... (CTE)	预处理语句列反射与递归 AST 分析	递归提取底层被变更的表，并验证读取安全性	流式迭代器（stmt.iterate()）设定硬性读取上限	对结果行动态屏蔽 PII，杜绝泄露
UPDATE (Targeted)	AST 求值与重言式检查器（evaluateWhereClause）	阻止无约束更新、WHERE 1=1、WHERE true 和包含重言式的 OR	原子事务；如果受影响的行数超过 maxMutationRows，则回滚	在日志和数据库错误中屏蔽字面值
DELETE (Targeted)	AST 求值与重言式检查器（evaluateWhereClause）	阻止无约束删除、WHERE 1=1 和包含重言式的 OR	原子事务；如果受影响的行数超过 maxMutationRows，则回滚	在日志和数据库错误中屏蔽字面值
INSERT	AST 求值与方言解析器	STRICT 层级要求进行预检干运行模拟	原子事务；如果插入的行数超过 maxMutationRows，则回滚	对 (cols) VALUES (vals) 中的敏感字面值进行脱敏
DROP TABLE / TRUNCATE	AST 语句操作码检查	严重阻止：除非明确覆盖，否则在接触数据库前拦截	阻止直接执行	审计日志记录被阻止的尝试，并标记高风险评分
ALTER TABLE DROP COLUMN	AST 表达式访问器（expr.action）	已阻止：在接触数据库前拦截，以防止架构数据丢失	阻止直接执行	审计日志记录被阻止的尝试
EXPLAIN / PRAGMA	预处理语句列反射	安全的只读检查	读取量限制为 maxRowsPerRead	清理输出

强制保障措施详解

1. 参数绑定的提交不变性（B1）：
   • 提交授权令牌采用加密签名（HMAC-SHA256），绑定精确的规范化 SQL 查询文本、类型化参数（params）、数据库标识（storagePath）、安全级别和模拟受影响行数。
   • 任何查询篡改、绑定参数变更或跨数据库重放尝试都会立即被拒绝（PARAMS_MISMATCH、QUERY_TAMPERED）。
2. 严格的变更上限与事务回滚（B2）：
   • 超出 maxRowsPerMutation 是适用于所有安全级别（STRICT、BALANCED、PERMISSIVE）的严格安全限制，系统会立即拒绝试运行授权（EXCESSIVE_BLAST_RADIUS）。
   • 直接执行或通过 db_commit 提交的变更均在原子事务块中运行：如果实际行修改数超出授权上限，DBShield 会立即执行 ROLLBACK; 并中止操作。
3. 防止模拟结果差异漂移（B2）：
   • 防止试运行与提交之间发生并发修改：如果底层数据库行发生变化，导致实际受影响行数与模拟行数不同（simulatedAffectedRows != actualChanges），DBShield 会回滚事务并返回 [SIMULATION_DELTA_DRIFT]。
4. 审计日志与错误消息脱敏（B3）：
   • 写入磁盘或内存循环缓冲区之前，原始 SQL 字符串中的敏感字面量（密码、令牌、API 密钥、电子邮件、电话号码、SSN、信用卡号）会被屏蔽。
   • 返回给 Agent 或存储在审计记录中的数据库引擎错误（例如 SQLite 约束失败）都会经过脱敏处理。
   • db_audit_log 仅返回经过脱敏的合规记录。
5. 内存安全的流式读取行数限制（B4）：
   • SQLite 行采用 Node.js stmt.iterate() 进行惰性流式读取。
   • 结果数量限制为 maxRowsPerRead，不会将完整数据集缓冲到 Node.js 堆内存中，并返回便于 Agent 使用的分页元数据（totalReturned、isTruncated、maxAllowedRows、hasMore、warning）。
6. 稳健的语句分类与 CTE 支持（B5）：
   • 已将简单的字符串前缀检查替换为 SQLite 预处理语句列元数据（stmt.columns() > 0）和递归 AST 提取。
   • 复杂 CTE（WITH active AS (...) SELECT ...）以及以单行注释（--）或多行注释（/* */）开头的语句均可正确分类并执行，不会报错。

---

🔒 生产部署与最小权限指南

对于生产环境和共享环境，DBShield 应配合数据库级别的最小权限设置：

1. SQLite 文件系统加固

• 文件权限：限制数据库文件权限，仅允许 DBShield 进程 UID 访问：

  chmod 600 /var/data/production.db
  chown dbshield:dbshield /var/data/production.db
  

• 只读连接：对于只读 Agent 工作负载，可使用只读标志挂载 SQLite，或以 SQLite 只读模式初始化：

  {
    "storagePath": "file:/var/data/production.db?mode=ro",
    "safetyTier": "STRICT"
  }
  

2. 关系数据库最小权限（PostgreSQL / MySQL）

• 为 DBShield 创建专用数据库角色，并仅授予必要的最小权限：

  -- Create isolated role
  CREATE ROLE agent_user WITH LOGIN PASSWORD 'strong_random_password';
  
  -- Grant only targeted DML on application tables (NO DROP, TRUNCATE, or ALTER)
  GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO agent_user;
  REVOKE ALL ON SCHEMA public FROM PUBLIC;
  

3. 策略执行与人工审批

• 确定性策略执行：DBShield 的试运行授权令牌可确保查询符合自动化安全策略（影响范围阈值、恒真条件检查、参数绑定）。
• 人工审批交接：在敏感的生产工作流中，可将 db_dry_run 输出传递给外部人工参与审核系统（Slack、Teams 或工单 Webhook），待审核通过后再将令牌提交给 db_commit。

---

🐳 Docker 与 Kubernetes Helm 打包

DBShield 已打包为企业级容器，采用非特权非 root 用户（UID 10001），内置 Prometheus 指标导出器，并提供生产级 Kubernetes Helm chart：

PostgreSQL Clients / AI Agents ──► DBShield Wire Proxy (:5433) ──► Upstream PostgreSQL (:5432)
                                             │
                                             └──► Prometheus Scraper (:9090/metrics)
                                             └──► Kubernetes Probes (:9090/healthz, /ready)

1. Docker Compose（零配置全栈）

通过一条命令启动 PostgreSQL、DBShield Wire Proxy 和 Prometheus：

docker compose up -d

• PostgreSQL 代理：127.0.0.1:5433（目标为 :5432 上的 PostgreSQL）
• Prometheus 仪表板：http://localhost:9091
• 指标端点：http://localhost:9090/metrics
• 健康状态端点：http://localhost:9090/healthz

2. 独立 Docker 容器

docker run -d \
  --name dbshield-proxy \
  -p 5433:5433 \
  -p 9090:9090 \
  -e DBSHIELD_UPSTREAM_HOST=postgres.internal \
  -e DBSHIELD_UPSTREAM_PORT=5432 \
  -e DBSHIELD_SAFETY_TIER=BALANCED \
  ghcr.io/ritualdev-lab/dbshield:0.2.0

3. 通过 Helm 部署 Kubernetes

部署高可用 DBShield 副本（带有 HorizontalPodAutoscaler 和 Prometheus ServiceMonitor）：

# Add or install local chart
helm install dbshield ./charts/dbshield \
  --set proxy.upstreamHost="my-db.postgres.database.azure.com" \
  --set proxy.safetyTier="BALANCED" \
  --set replicaCount=2 \
  --set autoscaling.enabled=true

Prometheus 中的指标示例（/metrics）

• dbshield_up：代理健康状态（1 = 健康）
• dbshield_connections_active：实时活跃客户端连接数
• dbshield_queries_total{status, safety_tier, operation}：已评估的查询总数
• dbshield_queries_blocked_total{rule, severity}：已拦截并阻止的查询数
• dbshield_query_duration_seconds：用于衡量查询评估延迟的直方图
• dbshield_cost_savings_dollars_total：因阻止失控查询而估算节省的云支出

---

🏛️ 企业合规与 SLA 保证

DBShield 提供确定性、零数据托管的数据库保护，并由企业级合同保障：

• 正式企业服务等级协议：ENTERPRISE_SLA.md
  保证响应时间：P1 关键故障 < 1 小时（全年 7×24 小时覆盖），P2 高严重级别 < 4 小时；可用性 SLA 为 99.95%。
• SOC 2 Type II 和 ISO/IEC 27001:2022 准备情况矩阵：SOC2_ISO27001_COMPLIANCE.md
  为企业采购审计提供全面的 AICPA 信任服务标准（CC1–CC9、A1、C1、PI1、P1–P8）及 ISO 27001 附录 A 映射。
• 自主 AI 编码 Agent 技能定义：SKILL.md
  为 Antigravity、Cursor、Windsurf 和 Claude Code 提供标准化指令与工具调用准则。
• GitHub Action CI/CD 迁移门禁：action.yml
  合并前迁移验证及未索引级联锁检测（uses: RitualDev-Lab/[email protected]）。

企业联系与事件分流

• 安全与 SOC 2 资料包：[email protected]
• 商务与 SLA 支持：[email protected]
• 技术架构评审：[email protected]
• 信任与安全门户：https://ritualdev.in/trust

---

---

💖 通过 Dodo Payments 赞助与支持

DBShield 100% 开源，并采用 MIT 许可证。您的赞助将直接用于支持我们的多数据库回归测试基础设施（PostgreSQL、MySQL、SQLite、MongoDB）、自动化基准测试 CI 运行器，以及高可用 MCP 注册表遥测。

📄 许可证

MIT © RitualDev Lab