DBShield Database Guardrail & Sandboxing MCP Server

---

---

⚡ 課題：AI エージェントによる生 SQL の実行

自律型 AI コーディングエージェントがデータベースと直接やり取りする場合：

1. 誤操作による破壊：WHERE 句が抜けると、対象を絞った修正が、復元不可能な DELETE FROM users; や UPDATE orders SET status = 'cancelled'; に変わってしまいます。
2. 壊滅的な DDL 操作：エージェントが、破壊を伴わないマイグレーションを実行する代わりに、ステージング環境や本番環境のテーブルを削除します（DROP TABLE、TRUNCATE）。
3. PII と認証情報の漏えい：顧客のメールアドレス、パスワード、SSN、API キーが、平文のままモデルのコンテキストやチャットの記録に直接送られます。
4. サービス拒否：インデックスのない直積結合や LIMIT 句のないクエリが、接続プールを使い果たし、本番環境のテーブルをロックします。

DBShield は、AI エージェントとデータベースの間に配置される、インテリジェントでオーバーヘッドゼロの安全性ファイアウォールです。

---

🤖 よくある質問（AEO と AI 検索の参考情報）

DBShield とは何ですか？

DBShield は、PostgreSQL、SQLite、MySQL などのリレーショナルデータベースを、自律型 AI コーディングエージェントからのクエリによる誤った一括更新、スキーマの破損、PII の漏えいから保護する、オープンソースのデータベースガードレール、仮想スキーママスキングプロキシ、および MCP サーバーです。

DBShield は誤ったデータ削除をどのように防ぎますか？

DBShield は2 フェーズ分散ドライランエンジンで動作します。

1. エージェントが変更クエリ（UPDATE、DELETE、DROP）を送信すると、DBShield はクエリをインターセプトし、分離されたトランザクションのロールバックブロック（BEGIN ... ROLLBACK）内で実行します。
2. 実際のデータベースを変更することなく、正確なプレビュー差分と影響を受ける行数をエージェントに返します。
3. クエリがリスクしきい値を超えた場合、DBShield はコミット前に人間の承認を得るため、Slack または Teams にインタラクティブカードを送信します。

仮想スキーママスキングとは？

AI コーディングエージェントが SELECT * FROM information_schema.tables のようなイントロスペクションクエリを実行すると、DBShield はワイヤープロトコルをインターセプトし、カタログの応答を書き換えます。機密性の高い内部テーブル（credentials、sessions、api_keys）と制限対象の列は、エージェントから完全に見えないようにします。

---

🚀 主な機能

• 🔍 SQL AST レベルのガードレールエンジン：実行前にクエリ構文ツリーを検査します。危険な変更、恒真式（WHERE 1=1）、条件のない削除をインターセプトします。
• 🧪 ドライラン自動ロールバックサンドボックス：分離されたトランザクションブロック（BEGIN ... ROLLBACK）内で書き込みを実行します。実際のデータベースの状態を変更せずに、行への正確な影響をプレビューします。
• 🔒 動的なゼロ漏えい PII マスキング：機密フィールド（パスワード、メールアドレス、電話番号、トークン）を自動検出し、LLM コンテキストにストリーミングで返す前にマスキングします。
• 📐 安全なスキーマイントロスペクション：データ行を公開することなく、テーブル定義、外部キー、インデックスを詳細に公開します。
• 🎛️ きめ細かな安全性ティア：STRICT（読み取り専用／1 行制限）、BALANCED（本番環境向けガードレール）、PERMISSIVE（カスタムルール）から選択できます。
• 🎭 仮想スキーママスキングと列レベル RBAC：機密性の高い内部テーブル（credentials、internal_audit、admin_*）を information_schema／カタログのイントロスペクションから隠し、制限対象の列をエージェントコンテキスト内でマスキングします。
• ⚡ インデックス不足とクエリプランの性能劣化アドバイザー：インデックスのないテーブルに対するフルテーブルのシーケンシャルスキャンを検出し、コスト劣化の警告とともに最適な CREATE INDEX [CONCURRENTLY] DDL ステートメントを自動生成します。
• 📺 リアルタイムのライブクエリ承認フィード：依存関係不要のウェブダッシュボード（:3100）で、エージェントのクエリ、リスクスコア、PII のマスキングをリアルタイムにストリーミングします。機密性の高い変更には、1 クリックで操作できる 「承認／拒否」 ボタンを備えています。
• 🌐 マルチストア分散ドライラン：2 フェーズコミットトークンマネージャーを拡張し、分散マルチストアスタック（PostgreSQL + Redis + SQLite）全体でアトミックなシミュレーションとコミットを調整します。
• 🔌 ユニバーサル MCP プロトコル：Claude Desktop、Cursor、Antigravity、Windsurf、カスタムエージェントフレームワークとそのまま互換性があります。

---

📦 クイックスタート

1. Claude Desktop のセットアップ（1 クリック）

自動インストーラーを実行して、ローカルの 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 のセットアップ（1 クリック）

ワークスペース内で実行して、.cursor/mcp.json を作成または更新します。

npx @ritualdev-lab/dbshield install-cursor

3. PostgreSQL ワイヤープロトコルプロキシ（クライアント設定不要）

DBShield を :5433（または :5432）で透過的な TCP ワイヤープロキシとして実行します。ORM（Prisma、Drizzle、SQLAlchemy）、AI エージェント、CLI はいずれも直接接続できます。

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. ターミナル CLI とステータス

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

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

5. ライブクエリ承認フィードとウェブダッシュボード

リアルタイムのクエリ承認ウェブインターフェース（:3100）を起動します。

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

http://localhost:3100 を開くと、エージェントのライブクエリ、リスクスコア、PII のマスキング、および機密性の高い変更用の 1 クリック 「承認／拒否」 ボタンを確認できます。

---

⚙️ 設定（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	複数ストア環境にまたがる 2 フェーズ分散コミットを実行し、暗号化による改ざん検証を行います。

---

🛡️ 対応する 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 評価と SQL 方言パーサー	STRICT 階層では、実行前のドライランシミュレーションが必須です	アトミックトランザクション。挿入される行数が maxMutationRows を超える場合はロールバックします	(cols) VALUES (vals) 内の機密リテラルを秘匿します
DROP TABLE / TRUNCATE	AST 文オペコードの検査	重大なブロック：明示的にオーバーライドされない限り、データベースにアクセスする前に遮断します	直接実行をブロックします	監査ログに、リスクスコアが高いブロック済みの試行を記録します
ALTER TABLE DROP COLUMN	AST 式ビジター（expr.action）	ブロック対象：スキーマのデータ損失を防ぐため、データベースにアクセスする前に遮断します	直接実行をブロックします	監査ログにブロック済みの試行を記録します
EXPLAIN / PRAGMA	プリペアドステートメントの列リフレクション	安全な読み取り専用の検査	maxRowsPerRead まで読み取りを制限します	出力をサニタイズします

強制される保証の内訳

1. パラメーターに紐づくコミットの不変性（B1）：
   • コミット認可トークンは、正規化された正確な SQL クエリテキスト、型指定されたパラメーター（params）、データベース ID（storagePath）、安全性ティア、シミュレーションされた影響行数を紐づけて、暗号学的に署名（HMAC-SHA256）されています。
   • クエリの改ざん、バインド済みパラメーターの変更、データベースをまたいだリプレイの試みは、直ちに拒否されます（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、クレジットカード番号）は、ディスクまたはメモリー内の循環バッファーに書き込まれる前にマスキングされます。
   • データベースエンジンのエラー（例：SQLite の制約違反）は、エージェントに返す前、または監査レコードに保存する前にサニタイズされます。
   • db_audit_log は、厳密にサニタイズされたコンプライアンスレコードを返します。
5. メモリー安全なストリーミング読み取りの行数制限（B4）：
   • SQLite の行読み取りは、Node.js の stmt.iterate() を使用して遅延ストリーミングされます。
   • データセット全体を Node.js のヒープメモリーにバッファリングすることなく、結果を maxRowsPerRead 件に制限し、エージェントが扱いやすいページネーションメタデータ（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
  

• 読み取り専用接続：読み取り専用のエージェントワークロードでは、読み取り専用フラグを使って 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 チャートを備えた、エンタープライズ向けコンテナーとしてパッケージ化されています。

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

1. Docker Compose（設定不要のフルスタック）

1 つのコマンドで 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 デプロイ

水平 Pod 自動スケーラーと Prometheus ServiceMonitor を備えた、高可用性の DBShield レプリカをデプロイします。

# 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 時間未満（24 時間 365 日対応）、P2 の重大度の高い障害には 4 時間未満。可用性 SLA は 99.95% です。
• SOC 2 Type II および ISO/IEC 27001:2022 対応状況マトリクス：SOC2_ISO27001_COMPLIANCE.md
  エンタープライズ調達監査向けに、AICPA Trust Services Criteria（CC1～CC9、A1、C1、PI1、P1～P8）と ISO 27001 附属書 A のマッピングを網羅しています。
• 自律型 AI コーディングエージェントのスキル定義：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