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 ` | Scan repository SQL files/migrations for unsafe DDL or lock hazards. | +| `dbshield configure` | Auto-patch Claude Desktop, Cursor, or Antigravity MCP config. | +| `dbshield top` | Live terminal telemetry dashboard for intercepted queries. | diff --git a/docs/04-integrations-and-mcp.md b/docs/04-integrations-and-mcp.md new file mode 100644 index 0000000..45e0bc5 --- /dev/null +++ b/docs/04-integrations-and-mcp.md @@ -0,0 +1,11 @@ +# 04 — Integrations & MCP Server + +## MCP Tools Exposed by DBShield +- `db_query`: Guarded SQL execution with AST validation, cost gate, row cap, and automatic PII redaction. +- `db_dry_run`: Lock-free shadow transaction simulation returning exact affected-row counts and single-use commit tokens. +- `db_explain_query`: Query plan analyzer flagging unindexed sequential scans and proposing index DDL. +- `db_check_semantic_intent`: Verifies agent stated intent against targeted sensitive columns. +- `db_audit_log`: Queries the tamper-evident, PII-redacted HMAC audit ledger. + +## ChatOps Integration (Slack & Microsoft Teams) +Configure `DBSHIELD_CHATOPS_SECRET`, `SLACK_WEBHOOK_URL`, or `TEAMS_WEBHOOK_URL` to route `CRITICAL` mutations through `PreImageChecksumCoordinator` with 1-click HMAC-signed Approve/Reject cards. diff --git a/docs/05-enterprise-vpc-and-security.md b/docs/05-enterprise-vpc-and-security.md new file mode 100644 index 0000000..686ef04 --- /dev/null +++ b/docs/05-enterprise-vpc-and-security.md @@ -0,0 +1,11 @@ +# 05 — Enterprise VPC & Security Controls + +## Private VPC & Kubernetes Deployment +DBShield deploys alongside AgentShield and SkillPrism using the canonical Helm charts and Terraform modules in [`RitualDev-Lab/enterprise-governance-suite`](https://github.com/RitualDev-Lab/enterprise-governance-suite): +- Zero-egress `NetworkPolicy` isolating DBShield between agent pods and internal RDS/CloudSQL/Aurora endpoints. +- Virtual Schema RBAC hiding sensitive tables (`credentials`, `audit_*`) and columns per SSO role. +- Append-only HMAC-SHA256 audit ledger aligned with **PCI-DSS v4.0 Req 10** and **SOC 2 CC6.8**. +- Multi-SIEM streaming to Splunk HEC, Datadog Logs, and ArcSight CEF via `agent-defense-hub`. + +## Responsible Security Disclosure +Report vulnerabilities privately via [SECURITY.md](../SECURITY.md) or `security@ritualdev.in`.