DBShield MCP server

🛡️ DBShield

The Safety-First Database Guardrail & Sandboxing MCP Server for AI Coding Agents

Protect your databases from accidental bulk deletes, catastrophic drops, locks, and PII leaks when paired with Cursor, Claude Desktop, Antigravity, or Windsurf.

[!IMPORTANT]

💡 The Core Thesis: Bridging Intent vs. Effect

"Dry-run sandboxing is the piece that stands out. Guardrails and masking catch known bad patterns, but a sandbox shows what an agent's query would actually do before production. That gap between intent and effect is where most agent database incidents begin."

---

---

🎯 The "Intent vs. Effect" Problem in Autonomous AI Coding

When an AI coding agent acts on your database, static AST rules and regex patterns only catch known bad syntax (like DROP TABLE or WHERE 1=1). They cannot catch semantically plausible queries where the effect completely diverges from the user's intent:

┌──────────────────────────────────────┐     ┌────────────────────────────────────────────────────────────┐
│      AGENT'S STATED INTENT           │     │            AGENT'S EMITTED SQL                             │
│ "Update avatar for user #402"        │ ──► │ UPDATE users SET role = 'admin' WHERE id = 402;            │
│ Expected Effect: 1 row, non-sens col │     │ Simulated Effect: Privilege escalation to superadmin!      │
└──────────────────────────────────────┘     └────────────────────────────────────────────────────────────┘
                                                            ▲
                                                            │
                                  🚨 INTENT VS. EFFECT GAP DETECTED (BLOCKED)

┌──────────────────────────────────────┐     ┌────────────────────────────────────────────────────────────┐
│      AGENT'S STATED INTENT           │     │            AGENT'S EMITTED SQL                             │
│ "Archive test trial accounts"        │ ──► │ DELETE FROM accounts WHERE created_at < '2026-01-01';      │
│ Expected Blast Radius: ~5 rows       │     │ Simulated Effect: 14,820 customer production accounts lost │
└──────────────────────────────────────┘     └────────────────────────────────────────────────────────────┘
                                                            ▲
                                                            │
                                  🚨 BLAST RADIUS GAP DETECTED (BLOCKED & ROLLED BACK)

🔬 How DBShield Closes the Gap via Dry-Run Sandboxing

sequenceDiagram
    autonumber
    actor Developer as LLM Agent / Developer
    participant Proxy as DBShield Wire Proxy (:5432)
    participant Guard as AST Normalizer & Intent Guard
    participant Sandbox as Shadow Dry-Run Sandbox
    participant OS as SQLite VFS OS Shim
    participant Approvals as ChatOps (Slack / Teams)
    participant DB as Production Database

    Developer->>Proxy: SQL Mutation + Stated Intent Context
    Proxy->>Guard: Lexical Normalization & Semantic Intent Check
    
    alt In-line Comment Evasion / Unicode Smuggling
        Guard-->>Developer: ❌ [BLOCKED] Query normalization violation
    end

    Guard->>Sandbox: Execute in Isolated Transaction Envelope (BEGIN ... ROLLBACK)
    Sandbox->>OS: Page-Level Write Interception (Token Verified)
    OS-->>Sandbox: Intercepted OS Page Diffs & Computed Row Mutations
    Sandbox-->>Guard: Exact Blast Radius (Affected Rows, Column Mutations, DDL)
    
    Guard->>Guard: Gap Analysis: Compare Intent vs. Effect
    
    alt Gap Detected (Row Count Regressed OR Column Privilege Mismatch)
        Guard->>Approvals: Dispatch Two-Man Approval Card (Slack / Teams)
        Approvals-->>Developer: ⏸️ Mutation Paused Pending Human Sign-Off
    else Intent Aligned & Safe Blast Radius
        Guard->>DB: Monotonic Fencing Token Commit
        DB-->>Developer: ✅ Committed Successfully with HMAC-SHA256 Audit Trail
    end

flowchart TD
    A["Agent Intent: 'Update Profile'"] --> B["Emitted SQL: 'UPDATE users SET role=admin'"]
    B --> C["DBShield Wire Proxy (:5432 / :3306)"]
    C --> D{"AST Lexical Normalizer<br/>(Strip Evasion & Comment Injection)"}
    D -->|Passed| E["Shadow Sandbox Simulation<br/>(BEGIN ... ROLLBACK)"]
    D -->|Violation| Block1["❌ Terminate with Security Alert"]
    E --> F["OS Page-Level VFS Shim Interception"]
    F --> G["Calculate Exact Mutation Blast Radius<br/>(Rows Mutated, Columns Modified)"]
    G --> H{"Intent vs. Effect Gap Analyzer"}
    H -->|"GAP DETECTED!<br/>(Privilege escalation or row explosion)"| I["🚨 Route to Slack / Teams Two-Man Rule"]
    H -->|"INTENT ALIGNED<br/>(Blast radius matches intent)"| J["Sign with Monotonic Fencing Token"]
    J --> K["Commit to Production Database"]
    I -->|Human Approves| K
    I -->|Human Rejects| L["Atomic Rollback & HMAC Ledger Alert"]

---

⚡ 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

• 🧪 Dry-Run Auto-Rollback Sandboxing & Intent vs. Effect Gap Engine: Executes writes in an isolated transaction envelope (BEGIN TRANSACTION READ ONLY; ... ROLLBACK;). Calculates the exact difference between the agent's stated intent and actual row/column impact before anything touches production.
• 📁 SQLite OS Page-Level VFS Shim (SqliteVfsShim): Intercepts OS disk page read/write operations (4096-byte pages), blocking agents from altering .sqlite or .db files via direct filesystem access outside the DBShield wire proxy (UNAUTHORIZED_DIRECT_FS_WRITE).
• 🔄 Multi-Replica Raft Consensus & Monotonic Fencing Tokens: Distributed state machine coordinator (RaftConsensusCoordinator) synchronizing transaction isolation leases and two-phase commit votes across clustered proxies to eliminate split-brain mutations.
• 🔏 Append-Only HMAC-SHA256 Audit Ledger (HmacAuditLedger): Meets PCI-DSS v4.0 Requirement 10 and SOC 2 CC6.8. Implements strictly contiguous monotonic sequence numbers, query payload hashing, and Merkle tree root calculation for tamper-evident compliance exports.
• 🔍 SQL AST Lexical Normalizer: Neutralizes zero-width unicode smuggling, comment-evasion tricks (e.g. SEL/**/ECT), multi-statement injection, and unconstrained deletes.
• 🔒 Dynamic Zero-Leak PII Masking: Automatically detects sensitive fields (passwords, emails, phone numbers, tokens) and masks them before streaming back to LLM context.
• 🎭 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:password@127.0.0.1:5433/production_db"

4. Terminal CLI & Status

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

# Initialize starter configuration file
npx @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

Tier	Mutation Limit	Destructive DDL	Dry-Run Required	PII Masking	Best For
STRICT	Max 1 row	❌ Blocked	✅ Always Required	🔒 Enforced	Production, Staging
BALANCED	Max 50 rows	❌ Blocked	✅ On Bulk Writes	🔒 Enforced	Local Dev, Team Collaboration
PERMISSIVE	Max 500 rows	⚠️ Warned	Optional	Optional	Sandbox Benchmarks

---

🛠️ MCP Tools Reference

Tool	Description
db_status	Inspect gateway connectivity, active safety tier, cost gate, and database statistics.
db_describe_schema	Safe introspection of tables, columns, constraints, and relations.
db_query	Safe read and mutation query execution with automatic PII redaction, cost gate, and DDL checks.
db_dry_run	Test mutation inside an auto-rollback transaction with row delta preview and intent verification.
db_commit	Execute verified mutation accompanied by cryptographic authorization token.
db_explain_query	Analyze query execution plans, detect unindexed full-table scans, and receive index hints.
db_audit_log	Retrieve compliance query audit trail, blocked operations, and risk scores.
db_validate_migration	Validate DDL migration scripts for lock hazards and generate zero-downtime execution recipes.
db_check_schema_drift	Audit live database foreign keys for missing indexes and detect structural schema drift.
db_check_semantic_intent	Check stated English user intent against SQL AST target columns to stop unauthorized privilege/financial mutations.
db_distributed_dry_run	Simulate atomic mutations across multi-store environments (Postgres, SQLite, Redis) and receive unified token.
db_distributed_commit	Execute two-phase distributed commit across multi-store environments with cryptographic tamper verification.

---

🛡️ 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:

SQL Operation	Classification Mechanism	Static AST Guardrail	Execution Boundary & Rollback	Data Masking & Privacy
SELECT	Prepared-statement column reflection (stmt.columns())	Detects missing LIMIT in STRICT tier; warns if limit exceeds server cap	Streaming iterator (stmt.iterate()) caps memory; truncates at maxRowsPerRead	Zero-leak dynamic PII masking on result rows
WITH ... (CTE)	Prepared-statement column reflection & recursive AST analysis	Recursively extracts underlying mutated tables & verifies read safety	Streaming iterator (stmt.iterate()) with hard read ceiling	Zero-leak dynamic PII masking on result rows
UPDATE (Targeted)	AST evaluation & tautology checker (evaluateWhereClause)	Blocks unconstrained updates, WHERE 1=1, WHERE true, tautological OR	Atomic transaction; rolls back if affected rows exceed maxMutationRows	Literal masking in logs & database errors
DELETE (Targeted)	AST evaluation & tautology checker (evaluateWhereClause)	Blocks unconstrained deletes, WHERE 1=1, tautological OR	Atomic transaction; rolls back if affected rows exceed maxMutationRows	Literal masking in logs & database errors
INSERT	AST evaluation & dialect parser	Pre-flight dry run simulation required under STRICT tier	Atomic transaction; rolls back if inserted rows exceed maxMutationRows	Redacts sensitive literals in (cols) VALUES (vals)
DROP TABLE / TRUNCATE	AST statement opcode inspection	CRITICAL BLOCK: Intercepted before database touch unless explicitly overridden	Direct execution blocked	Audit log records blocked attempt with high risk score
ALTER TABLE DROP COLUMN	AST expression visitor (expr.action)	BLOCKED: Intercepted before database touch to prevent schema data loss	Direct execution blocked	Audit log records blocked attempt
EXPLAIN / PRAGMA	Prepared-statement column reflection	Safe read-only inspection	Read capped at maxRowsPerRead	Sanitized output

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:

  chmod 600 /var/data/production.db
  chown 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:

  {
    "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:

  -- 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. 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 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