Dry-run sandboxing, niyet-etki boşluğu analizi ve PII maskeleme yöntemlerini kullanarak ilişkisel veritabanlarını AI agent'lardan korur.
Ayrıca bilinen adı RitualDev-Lab/DBShield, dbshield, @ritualdev-lab/dbshield
- Yıldızlar
- 1
- Araçlar
- 12
- İndirmeler, 30 gün
- —
- En son sürüm
- 0.2.1
- Son commit
- 12 Kas 2026
- Lisans
- MIT
DBShield MCP nedir?
Dry-run sandboxing, niyet-etki boşluğu analizi ve PII maskeleme yöntemlerini kullanarak ilişkisel veritabanlarını AI agent'lardan korur. 12 araç sunar; örneğin db_status, db_describe_schema, db_query.
Özet, projenin README dosyasından oluşturuldu
DBShield MCP sunucusu hakkında
DBShield; otonom AI kodlama agent'ları ile PostgreSQL, MySQL ve SQLite gibi ilişkisel veritabanları arasında bir güvenlik duvarı görevi görür. Cursor, Claude Desktop, Antigravity veya Windsurf gibi araçları kullanan ve kazara veri kaybını veya hassas bilgi sızıntılarını önlemek isteyen geliştiriciler için tasarlanmıştır. Sunucu, sorguları durdurarak agent tarafından belirtilen hedeflerle uyumlu olduklarından emin olan akıllı bir wire proxy olarak çalışır.
Sistem, değişiklikleri bir BEGIN ve ROLLBACK deseni kullanarak izole bir işlem zarfı içinde yürüten bir dry-run sandboxing mekanizması kullanır. Bu, herhangi bir değişiklik canlı ortama ulaşmadan önce sunucunun etkilenen satır sayıları ve sütun değişiklikleri dahil olmak üzere tam etki alanını hesaplamasına olanak tanır. Ayrıca, yetkisiz doğrudan dosya sistemi erişimini engellemek için SQLite OS sayfa düzeyinde bir VFS shim özelliğine sahiptir.
Güvenlik; kaçınma taktiklerini önlemek için bir AST lexical normalizer ve şifreler veya e-postalar gibi hassas alanları gizleyen dinamik bir PII maskeleme motoru dahil olmak üzere çeşitli özelleşmiş bileşenler aracılığıyla sağlanır. Yüksek riskli işlemler için sunucu, bir commit tamamlanmadan önce insan müdahalesi gerektiren Slack veya Teams üzerinden bir onay mekanizmasını tetikleyebilir.
Neler yapabilirsiniz
- 1Kazara toplu silme işlemlerini önlemeBir AI agent kayıtları silmeye çalışırken yanlışlıkla hedeflenenin çok ötesinde bir üretim verisi setini hedefleyebilir.
- 2Agent niyetini SQL etkileriyle doğrulamaBir geliştirici, bir agent'ın SQL komutunun yürütülmeden önce belirtilen hedefle eşleştiğinden emin olmak için sandbox'ı kullanabilir.
- 3LLM bağlamlarından PII bilgilerini gizlemeMüşteri e-postalarını ve telefon numaralarını, AI modelinin sohbet geçmişine akıtılmaması için otomatik olarak maskeleyin.
Projenin README dosyasından alınmıştır. Her kullanım durumu, oradaki bir alıntı ile kontrol edilir.
DBShield MCP nasıl yüklenir
Biçimler 10 Kas 2026 tarihinde doğrulandıCursor'a ekleGoose'a ekleDBShield MCP'yi Claude Code içine yükleyin
$ claude mcp add dbshield -- npx -y @ritualdev-lab/dbshieldDBShield MCP'yi Cursor içine yükleyin
~/.cursor/mcp.json
{
"mcpServers": {
"dbshield": {
"command": "npx",
"args": [
"-y",
"@ritualdev-lab/dbshield"
]
}
}
}DBShield MCP'yi VS Code içine yükleyin
.vscode/mcp.json
{
"servers": {
"dbshield": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@ritualdev-lab/dbshield"
]
}
}
}DBShield MCP'yi VS Code CLI içine yükleyin
$ code --add-mcp '{"name":"dbshield","type":"stdio","command":"npx","args":["-y","@ritualdev-lab/dbshield"]}'DBShield MCP'yi Claude Desktop içine yükleyin
claude_desktop_config.json
{
"mcpServers": {
"dbshield": {
"command": "npx",
"args": [
"-y",
"@ritualdev-lab/dbshield"
]
}
}
}DBShield MCP'yi Codex içine yükleyin
$ codex mcp add dbshield -- npx -y @ritualdev-lab/dbshieldDBShield MCP'yi Codex config.toml içine yükleyin
~/.codex/config.toml
[mcp_servers.dbshield] command = "npx" args = ["-y", "@ritualdev-lab/dbshield"]
DBShield MCP'yi Gemini CLI içine yükleyin
$ gemini mcp add -s user dbshield npx -- -y @ritualdev-lab/dbshieldDBShield MCP'yi Gemini settings.json içine yükleyin
~/.gemini/settings.json
{
"mcpServers": {
"dbshield": {
"command": "npx",
"args": [
"-y",
"@ritualdev-lab/dbshield"
]
}
}
}DBShield MCP araçları 12
README dosyasından algılandıdb_statusdb_describe_schemadb_querydb_dry_rundb_commitdb_explain_querydb_audit_logdb_validate_migrationdb_check_schema_driftdb_check_semantic_intentdb_distributed_dry_rundb_distributed_commit
| db_status | — | |
| db_describe_schema | — | |
| db_query | — | |
| db_dry_run | — | |
| db_commit | — | |
| db_explain_query | — | |
| db_audit_log | — | |
| db_validate_migration | — | |
| db_check_schema_drift | — | |
| db_check_semantic_intent | — | |
| db_distributed_dry_run | — | |
| db_distributed_commit | — |
Yapılandırma
DATABASE_URLDBSHIELD_DB_URLConnection URL or file path for target database
DBSHIELD_DIALECTTarget database dialect (postgres, mysql, sqlite)
| Ad | Açıklama | Sunucu |
|---|---|---|
| DATABASE_URL | — | |
| DBSHIELD_DB_URL | Connection URL or file path for target database | |
| DBSHIELD_DIALECT | Target database dialect (postgres, mysql, sqlite) |
Otomatik kontroller
Çalıştırıldı 12 Kas 2026Tam rapor →Otomatik kontrollerimizden geçti. Bu bir güvenlik denetimi değildir: kodu okuyun ve sunucuya ihtiyaç duyduğu en dar erişimi verin. Kontroller nasıl çalışır
- Kaynak deposu bağlantılı ve erişilebilirGeçti
- Açık kaynak lisansı (OSI)Geçti
- Son bir yıl içinde commit veya sürüm mevcutGeçti
- Paket adı popüler bir pakete yakın değilGeçti
- Uzak uç nokta HTTPS kullanıyorKontrol edilmedi
- Yıkıcı araçlar etiketlenmişGeçti
- Modele yönelik gizli talimat yokGeçti
- Pakette veya bağımlılıklarında kritik uyarı yokGeçti
🛡️ 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:
- Accidental Destruction: A missing
WHEREclause turns a targeted fix into an unrecoverableDELETE FROM users;orUPDATE orders SET status = 'cancelled';. - Catastrophic DDL: Agents dropping staging or production tables (
DROP TABLE,TRUNCATE) instead of running non-destructive migrations. - PII & Credential Leaks: Customer emails, passwords, SSNs, and API keys are streamed in plaintext directly into model contexts and chat transcripts.
- Denial-of-Service: Unindexed cartesian joins or queries lacking
LIMITclauses 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:
- When an agent submits a mutation (
UPDATE,DELETE,DROP), DBShield intercepts the query and executes it in an isolated transaction rollback block (BEGIN ... ROLLBACK). - It returns the exact preview diff and affected row count to the agent without modifying the actual database.
- 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.sqliteor.dbfiles 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_*) frominformation_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
- 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).
- Commit authorization tokens are cryptographically signed (HMAC-SHA256) binding the exact normalized SQL query text, typed parameters (
- Hard Mutation Ceilings & Transactional Rollbacks (B2):
- Exceeding
maxRowsPerMutationis 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_commitrun inside an atomic transaction block: if actual row modifications exceed the authorized ceiling, DBShield immediately executesROLLBACK;and aborts.
- Exceeding
- 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].
- Protects against concurrent modifications between dry run and commit: if underlying database rows change such that actual affected rows differ from simulated rows (
- 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_logreturns strictly sanitized compliance records.
- Memory-Safe Streaming Read Row Capping (B4):
- SQLite row reads are streamed lazily using Node.js
stmt.iterate(). - Results are capped at
maxRowsPerReadwithout buffering the full dataset into Node.js heap memory, returning agent-friendly pagination metadata (totalReturned,isTruncated,maxAllowedRows,hasMore,warning).
- SQLite row reads are streamed lazily using Node.js
- 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.
- Replaced naive string prefix checks with SQLite prepared-statement column metadata (
🔒 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_runoutputs can be piped to an external human-in-the-loop review system (Slack, Teams, or ticketing webhook) before the token is submitted todb_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
DBShield MCP soruları
DBShield MCP'yi Claude Code'a nasıl eklerim?
Terminalinizde claude mcp add dbshield -- npx -y @ritualdev-lab/dbshield komutunu çalıştırın. Her projede kullanılabilir olması için --scope user ekleyin.
DBShield MCP'yi Cursor'a nasıl eklerim?
~/.cursor/mcp.json dosyasını açın ve yukarıdaki yükleme bölümünde gösterilen Cursor yapılandırmasını kullanarak sunucuyu mcpServers altına ekleyin.
DBShield MCP hangi araçları sunar?
12 araç sunar; bunlar arasında db_status, db_describe_schema, db_query, db_dry_run, db_commit yer alır.
DBShield nedir?
DBShield; AI agent'lar tarafından sorgulandığında ilişkisel veritabanlarını kazara veri değişikliğinden ve PII sızıntılarından korumak için tasarlanmış açık kaynaklı bir veritabanı güvenlik bariyeri, sanal şema maskeleme proxy'si ve MCP server'dır.
Virtual Schema Masking nedir?
İnceleme (introspection) sırasında hassas dahili tabloları ve kısıtlanmış sütunları agent'ın görüş alanından gizlemek için wire protocol sorgularını durduran bir özelliktir.