Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions docs/01-quickstart.md
Original file line number Diff line number Diff line change
@@ -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)
16 changes: 16 additions & 0 deletions docs/02-architecture.md
Original file line number Diff line number Diff line change
@@ -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.
16 changes: 16 additions & 0 deletions docs/03-configuration-and-cli.md
Original file line number Diff line number Diff line change
@@ -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 <dir>` | 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. |
11 changes: 11 additions & 0 deletions docs/04-integrations-and-mcp.md
Original file line number Diff line number Diff line change
@@ -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.
11 changes: 11 additions & 0 deletions docs/05-enterprise-vpc-and-security.md
Original file line number Diff line number Diff line change
@@ -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`.
Loading