DBShield
README.md
<div align="center">
<img src="assets/logo.png" alt="DBShield Logo" width="130" />
# 🛡️ DBShield
**The Safety-First Database Guardrail & Sandboxing MCP Server for AI Coding Agents**
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@ritualdev-lab/dbshield)
[](https://securityscorecards.dev/viewer/?repo=github.com/RitualDev-Lab/DBShield)
[](https://ritualdev.in/trust)
[](https://ritualdev.in/dbshield)
[](./GUIDE.md)
[](./THREAT_MODEL.md)
[](https://open-vsx.org/extension/ritualdev-lab/ritual-agent-defense)
[](https://modelcontextprotocol.io/)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://github.com/RitualDev-Lab/DBShield/actions/workflows/ci.yml)
[](https://github.com/RitualDev-Lab/DBShield)
[](https://github.com/RitualDev-Lab/DBShield)
[](https://github.com/RitualDev-Lab/DBShield)
[](https://biomejs.dev)
*Protect your databases from accidental bulk deletes, catastrophic drops, locks, and PII leaks when paired with Cursor, Claude Desktop, Antigravity, or Windsurf.*
</div>
---
<p align="center">
<img src="docs/terminal-demo.svg" alt="DBShield Terminal Interactive Demo" width="100%" />
</p>
---
## ⚡ 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:
```bash
npx @ritualdev-lab/dbshield install-claude
```
Or manually add to `claude_desktop_config.json`:
```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`:
```bash
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:
```bash
npx @ritualdev-lab/dbshield proxy --port 5433 --upstream-host 127.0.0.1 --upstream-port 5432
```
In your application or `.env`:
```env
DATABASE_URL="postgres://user:password@127.0.0.1:5433/production_db"
```
### 4. Terminal CLI & Status
```bash
# 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`):
```bash
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`)
```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:
```bash
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:
```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 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:
```bash
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
```bash
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):
```bash
# 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
```
#### 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](./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](./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](./SKILL.md)
Standardized instructions and tool-calling directives for Antigravity, Cursor, Windsurf, and Claude Code.
* **GitHub Action CI/CD Migration Gate**: [action.yml](./action.yml)
Pre-merge migration validation and unindexed cascade lock detection (`uses: RitualDev-Lab/DBShield@v0.2.0`).
### Enterprise Contact & Incident Triage
* **Security & SOC 2 Packages**: `security@ritualdev.in`
* **Commercial & SLA Support**: `support@ritualdev.in`
* **Technical Architecture Review**: `developer@ritualdev.in`
* **Trust & Security Portal**: [https://ritualdev.in/trust](https://ritualdev.in/trust)
---
## 📄 License
MIT © [RitualDev Lab](https://github.com/RitualDev-Lab)
TDQS
A3.6/5.0
Scored across 12 tools
Disambiguation4/5
Most tools have clearly distinct purposes: status, schema introspection, query analysis, audit, migration validation, and distributed commit are well separated. The main ambiguity is between db_query and the db_dry_run/db_commit pair, since db_query says it safely executes SQL and may appear usable for mutations that should go through the dry-run/commit workflow.
Naming Consistency4/5
All names use a consistent db_ snake_case prefix and are generally readable. Most follow an action-oriented pattern, but db_status and db_audit_log are noun-style rather than verb_noun, which is a minor deviation.
Tool Count5/5
Twelve tools is well-scoped for a database security gateway covering status, schema, query safety, audit, migrations, and distributed transactions. Each tool appears to earn its place without excessive overlap.
Completeness5/5
The surface covers the expected lifecycle for guarded database operations: status, introspection, query execution, dry-run authorization, commit, explain plans, audit logs, migration safety, schema drift, semantic intent checks, and distributed two-phase commits. No obvious lifecycle gap stands out for the stated security-gateway purpose.
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues