diff --git a/docs/01-quickstart.md b/docs/01-quickstart.md new file mode 100644 index 0000000..0e1a407 --- /dev/null +++ b/docs/01-quickstart.md @@ -0,0 +1,24 @@ +# 01 — DBShield Quickstart + +**DBShield (`@ritualdev-lab/dbshield`)** is a safety-first SQL guardrail, wire-protocol proxy, PII redactor, and lock-free dry-run sandbox for AI coding agents querying PostgreSQL, MySQL, SQLite, and Redis. + +## 1. Install & Run via MCP +```bash +npx -y @ritualdev-lab/dbshield --help +``` + +## 2. Configure Claude Desktop / Cursor / Antigravity +```bash +npx -y @ritualdev-lab/dbshield configure --client cursor +``` + +## 3. Launch the Wire-Protocol SQL Proxy +```bash +npx -y @ritualdev-lab/dbshield proxy --target postgres://readonly@localhost:5432/app --tier STRICT +``` + +## Next Steps +- [02 — Architecture](02-architecture.md) +- [03 — Configuration & CLI Reference](03-configuration-and-cli.md) +- [04 — Integrations & MCP Server](04-integrations-and-mcp.md) +- [05 — Enterprise VPC & Security](05-enterprise-vpc-and-security.md) diff --git a/docs/02-architecture.md b/docs/02-architecture.md new file mode 100644 index 0000000..025688e --- /dev/null +++ b/docs/02-architecture.md @@ -0,0 +1,16 @@ +# 02 — DBShield Architecture + +```mermaid +flowchart LR + Agent["AI Agent"] --> Proxy["DBShield MCP / Wire Proxy"] + Proxy --> Guard["AST SQL Guard + Cost Gate + Virtual Schema"] + Guard --> DryRun["Phase 1: Non-Blocking Pre-Image Checksum + Immediate ROLLBACK"] + DryRun --> ChatOps["Slack Block Kit / MS Teams HMAC Approval"] + ChatOps --> Commit["Phase 2: Fresh Connection Checksum Verification + Commit"] + Proxy --> PII["Wire PII Redactor & HMAC Audit Ledger"] +``` + +## Non-Blocking Two-Phase Pre-Image Checksum Coordinator +- **Phase 1 (Synchronous Inspection, `<5ms`)**: Computes a SHA-256 pre-image state checksum (`rowCount + latestTimestamp + schemaHash`), executes a detached dry-run with guaranteed immediate `ROLLBACK` (`0` held DB locks), and dispatches HMAC-signed Slack/MS Teams approval cards. +- **Phase 2 (Asynchronous Commit)**: Upon human approval, opens a fresh database connection, verifies the live pre-image checksum has not drifted (aborting with `PREIMAGE_DRIFT_DETECTED` on TOCTOU changes), and commits cleanly. +- **Zero Lock Contention**: Concurrent `SELECT` queries run unimpeded while destructive mutations wait in the human approval queue. diff --git a/docs/03-configuration-and-cli.md b/docs/03-configuration-and-cli.md new file mode 100644 index 0000000..336b6dd --- /dev/null +++ b/docs/03-configuration-and-cli.md @@ -0,0 +1,16 @@ +# 03 — DBShield Configuration & CLI Reference + +## Safety Tiers +- **`STRICT`**: Blocks unconstrained `DELETE`/`UPDATE`, destructive DDL (`DROP`/`TRUNCATE`), unindexed sequential scans, and requires explicit intent on sensitive columns. +- **`BALANCED`**: Allows safe reads and bounded mutations with dry-run simulation and PII masking enabled. +- **`PERMISSIVE`**: Audit logging and PII masking active with advisory warnings. + +## Core CLI Commands + +| Command | Description | +| :--- | :--- | +| `dbshield proxy` | Start transparent Postgres/MySQL wire-protocol guardrail proxy. | +| `dbshield mcp` | Start DBShield MCP stdio server for IDE agents. | +| `dbshield audit