DBShield Database Guardrail & Sandboxing MCP Server

[DBShield Terminal Interactive Demo]

⚡ The Problem: AI Agents Writing Raw SQL

When autonomous AI coding agents interact directly with databases:

1. Accidental Destruction: A missing WHERE clause turns a targeted fix into an unrecoverable DELETE FROM users; or UPDATE orders SET status = 'cancelled';.
2. Catastrophic DDL: Agents dropping staging or production tables (DROP TABLE, TRUNCATE) instead of running non-destructive migrations.
3. PII & Credential Leaks: Customer emails, passwords, SSNs, and API keys are streamed in plaintext directly into model contexts and chat transcripts.
4. Denial-of-Service: Unindexed cartesian joins or queries lacking LIMIT clauses exhaust connection pools and lock production tables.

DBShield sits between your AI Agent and your Database as an intelligent, zero-overhead safety firewall.

🤖 Frequently Answered Questions (AEO & AI Search Reference)

What is DBShield?

DBShield is an open-source database guardrail, virtual schema masking proxy, and MCP server designed to protect relational databases (PostgreSQL, SQLite, MySQL) from accidental bulk mutations, schema corruption, and PII leaks when queried by autonomous AI coding agents.

How does DBShield prevent accidental data deletion?

DBShield operates with a Two-Phase Distributed Dry-Run Engine:

1. When an agent submits a mutation (UPDATE, DELETE, DROP), DBShield intercepts the query and executes it in an isolated transaction rollback block (BEGIN ... ROLLBACK).
2. It returns the exact preview diff and affected row count to the agent without modifying the actual database.
3. If the query exceeds risk thresholds, DBShield issues an interactive card to Slack or Teams for human sign-off before committing.

What is Virtual Schema Masking?

When AI coding agents run introspection queries like SELECT * FROM information_schema.tables, DBShield intercepts the wire protocol and rewrites catalog responses. Sensitive internal tables (credentials, sessions, api_keys) and restricted columns are hidden entirely from the agent's view.

🚀 Key Capabilities

• 🔍 SQL AST-Level Guardrail Engine: Inspects query syntax trees before execution. Intercepts dangerous mutations, tautologies (WHERE 1=1), and unconstrained deletes.
• 🧪 Dry-Run Auto-Rollback Sandboxing: Executes writes in an isolated transaction block (BEGIN ... ROLLBACK). Previews exact row impacts without altering the real database state.
• 🔒 Dynamic Zero-Leak PII Masking: Automatically detects sensitive fields (passwords, emails, phone numbers, tokens) and masks them before streaming back to LLM context.
• 📐 Safe Schema Introspection: Exposes rich table definitions, foreign keys, and indexes without exposing data rows.
• 🎛️ Granular Safety Tiers: Choose between STRICT (read-only / 1-row limits), BALANCED (production guardrails), or PERMISSIVE (custom rules).
• 🎭 Virtual Schema Masking & Column-Level RBAC: Hides sensitive internal tables (credentials, internal_audit, admin_*) from information_schema / catalog introspection and masks restricted columns from agent context.
• ⚡ Missing Index & Query Plan Regressive Advisor: Detects full-table sequential scans on unindexed tables and automatically synthesizes optimal CREATE INDEX [CONCURRENTLY] DDL statements with cost regression alerting.
• 📺 Real-time Live Query Approval Feed: Zero-dependency web dashboard (:3100) streaming live agent queries, risk scores, and PII redactions, featuring 1-click "Approve / Reject" buttons for sensitive mutations.
• 🌐 Multi-Store Distributed Dry-Run: Extends the two-phase commit token manager to coordinate atomic simulations and commits across distributed multi-store stacks (PostgreSQL + Redis + SQLite).
• 🔌 Universal MCP Protocol: Drop-in compatible with Claude Desktop, Cursor, Antigravity, Windsurf, and custom Agent frameworks.

📦 Quickstart

1. Claude Desktop Setup (1-Click)

Run the auto-installer to configure your local Claude Desktop:

npx @ritualdev-lab/dbshield install-claude

Or manually add to claude_desktop_config.json:

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

2. Cursor IDE Setup (1-Click)

Run inside your workspace to create or update .cursor/mcp.json:

npx @ritualdev-lab/dbshield install-cursor

3. PostgreSQL Wire-Protocol Proxy (Zero Client Config)

Run DBShield as a transparent TCP wire proxy on :5433 (or :5432). Any ORM (Prisma, Drizzle, SQLAlchemy), AI agent, or CLI connects directly:

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

In your application or .env:

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

4. Terminal CLI & Status

# Check status and inspect connected databasenpx @ritualdev-lab/dbshield status
# Initialize starter configuration filenpx @ritualdev-lab/dbshield init

5. Live Query Approval Feed & Web Dashboard

Start the real-time query approval web interface (:3100):

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

Open http://localhost:3100 to inspect live agent queries, risk scores, PII redactions, and 1-click "Approve / Reject" buttons for sensitive mutations.

⚙️ Configuration (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"]}

Safety Tiers

🛠️ MCP Tools Reference

🛡️ Matrix of Supported SQL & Enforced Guarantees

DBShield enforces rigorous runtime guarantees across the SQL lifecycle. Guarantees are verified transactionally, ensuring mutations never exceed approved scope even if database state drifts:

Enforced Guarantees Breakdown

1. Parameter-Bound Commit Invariance (B1):
   • Commit authorization tokens are cryptographically signed (HMAC-SHA256) binding the exact normalized SQL query text, typed parameters (params), database identity (storagePath), safety tier, and simulated affected row count.
   • Any query tampering, bound parameter alteration, or cross-database replay attempt is instantly rejected (PARAMS_MISMATCH, QUERY_TAMPERED).
2. Hard Mutation Ceilings & Transactional Rollbacks (B2):
   • Exceeding maxRowsPerMutation is a hard safety limit across all safety tiers (STRICT, BALANCED, PERMISSIVE), immediately refusing dry-run authorization (EXCESSIVE_BLAST_RADIUS).
   • Mutations executed directly or committed through db_commit run inside an atomic transaction block: if actual row modifications exceed the authorized ceiling, DBShield immediately executes ROLLBACK; and aborts.
3. Simulation Delta Drift Prevention (B2):
   • Protects against concurrent modifications between dry run and commit: if underlying database rows change such that actual affected rows differ from simulated rows (simulatedAffectedRows != actualChanges), DBShield rolls back the transaction with [SIMULATION_DELTA_DRIFT].
4. Audit Log & Error Message Sanitization (B3):
   • Raw SQL strings have sensitive literals (passwords, tokens, API keys, emails, phone numbers, SSNs, credit cards) masked before being written to disk or the in-memory circular buffer.
   • Database engine errors (e.g., SQLite constraint failures) are sanitized prior to returning to the agent or storing in audit records.
   • db_audit_log returns strictly sanitized compliance records.
5. Memory-Safe Streaming Read Row Capping (B4):
   • SQLite row reads are streamed lazily using Node.js stmt.iterate().
   • Results are capped at maxRowsPerRead without buffering the full dataset into Node.js heap memory, returning agent-friendly pagination metadata (totalReturned, isTruncated, maxAllowedRows, hasMore, warning).
6. Robust Statement Classification & CTE Support (B5):
   • Replaced naive string prefix checks with SQLite prepared-statement column metadata (stmt.columns() > 0) and recursive AST extraction.
   • Complex CTEs (WITH active AS (...) SELECT ...) and leading single-line (--) or multi-line (/* */) comments are correctly classified and executed without error.

🔒 Production Deployment & Least-Privilege Guide

For production and shared environments, DBShield should be paired with database-level least privilege:

1. SQLite Filesystem Hardening

• File Permissions: Restrict database file permissions so only the DBShield process UID has access:
  bash

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

• Read-Only Connections: For read-only agent workloads, mount SQLite with read-only flags or initialize with SQLite read-only mode:
  json

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

2. Relational Database Least Privilege (PostgreSQL / MySQL)

• Create a dedicated database role for DBShield with minimal necessary grants:
  sql

  -- Create isolated roleCREATE 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. Policy Enforcement vs Human Approval

• Deterministic Policy Enforcement: DBShield's dry-run authorization token guarantees that a query adheres to automated safety policies (blast radius thresholds, tautology checks, parameter binding).
• Human Approval Hand-Off: In sensitive production workflows, db_dry_run outputs can be piped to an external human-in-the-loop review system (Slack, Teams, or ticketing webhook) before the token is submitted to db_commit.

🐳 Docker & Kubernetes Helm Packaging

DBShield is packaged as an enterprise container with an unprivileged non-root user (UID 10001), native Prometheus metrics exporter, and a production 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 (Zero-Config Full Stack)

Launch PostgreSQL, DBShield Wire Proxy, and Prometheus in one command:

docker compose up -d

• PostgreSQL Proxy: 127.0.0.1:5433 (Targeting PostgreSQL on :5432)
• Prometheus Dashboard: http://localhost:9091
• Metrics Endpoint: http://localhost:9090/metrics
• Health Endpoint: http://localhost:9090/healthz

2. Standalone Docker Container

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. Kubernetes Deployment via Helm

Deploy high-availability DBShield replicas (with HorizontalPodAutoscaler and Prometheus ServiceMonitor):

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

Metrics Exponent in Prometheus (/metrics)

• dbshield_up: Proxy health status (1 = healthy)
• dbshield_connections_active: Real-time active client connections
• dbshield_queries_total{status, safety_tier, operation}: Total queries evaluated
• dbshield_queries_blocked_total{rule, severity}: Queries intercepted and prevented
• dbshield_query_duration_seconds: Histogram measuring query evaluation latency
• dbshield_cost_savings_dollars_total: Estimated cloud spend saved from blocked runaway queries

🏛️ Enterprise Compliance & SLA Guarantees

DBShield provides deterministic, zero-data-custody database protection backed by enterprise contractual assurances:

• Formal Enterprise Service Level Agreement: ENTERPRISE_SLA.md
  Guaranteed response times: < 1 hour for P1 critical outages (24/7/365 coverage), < 4 hours for P2 high severity, 99.95% availability SLA.
• SOC 2 Type II & ISO/IEC 27001:2022 Readiness Matrix: SOC2_ISO27001_COMPLIANCE.md
  Comprehensive AICPA Trust Services Criteria (CC1–CC9, A1, C1, PI1, P1–P8) and ISO 27001 Annex A mapping for enterprise procurement audits.
• Autonomous AI Coding Agent Skill Definition: SKILL.md
  Standardized instructions and tool-calling directives for Antigravity, Cursor, Windsurf, and Claude Code.
• GitHub Action CI/CD Migration Gate: action.yml
  Pre-merge migration validation and unindexed cascade lock detection (uses: RitualDev-Lab/[email protected]).

Enterprise Contact & Incident Triage

• Security & SOC 2 Packages: [email protected]
• Commercial & SLA Support: [email protected]
• Technical Architecture Review: [email protected]
• Trust & Security Portal: https://ritualdev.in/trust

📄 License

MIT © RitualDev Lab