Metadata-Version: 2.4
Name: dbshield-defense
Version: 0.2.0
Summary: Enterprise Database Guardrail & Wire Proxy Python SDK for Autonomous AI Agents (LangChain, CrewAI, LlamaIndex)
Author-email: RitualDev Studio <developer@ritualdev.in>, RitualDev Security <security@ritualdev.in>
License: MIT
Project-URL: Homepage, https://ritualdev.in/dbshield
Project-URL: Documentation, https://ritualdev.in/docs
Project-URL: TrustCenter, https://ritualdev.in/trust
Project-URL: Repository, https://github.com/RitualDev-Lab/dbshield-python
Project-URL: Issues, https://github.com/RitualDev-Lab/dbshield-python/issues
Keywords: ai-agents,database-security,sql-guardrail,ast-validator,pii-masking,sandbox,two-phase-commit,langchain,crewai,llamaindex
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: crewai
Requires-Dist: crewai>=0.1.0; extra == "crewai"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10.0; extra == "llamaindex"
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy>=2.0.0; extra == "sqlalchemy"
Dynamic: license-file

<div align="center">

# DBShield Python SDK 🛡️

[![PyPI version](https://img.shields.io/badge/PyPI-dbshield--defense-3776AB?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/dbshield-defense/)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Interactive Playground](https://img.shields.io/badge/Playground-Live%20Demo-00F59B?style=for-the-badge)](https://ritualdev.in/playground)
[![Trust Center](https://img.shields.io/badge/Trust-SIG%20Lite%20%2F%20DPDP-00D4FF?style=for-the-badge)](https://ritualdev.in/trust)

> Enterprise-grade Database Guardrail & Wire Proxy Python SDK for Autonomous AI Agents built with LangChain, CrewAI, LlamaIndex, and SQLAlchemy.

[Documentation](https://ritualdev.in/docs) • [Web Portal](https://ritualdev.in) • [Trust Center](https://ritualdev.in/trust) • [Issues](https://github.com/RitualDev-Lab/dbshield-python/issues)

</div>

---

## ⚡ Key Features

- **AST Query Validator**: In-memory SQL AST query analyzer detecting tautologies (`WHERE 1=1`), destructive DDL (`DROP TABLE`, `TRUNCATE`), unindexed queries, and row read ceilings.
- **Dynamic PII Redactor**: Format-preserving pseudonymization and regex redaction for SSNs, Luhn-valid credit card numbers, email addresses, and JWT/API tokens.
- **Two-Phase Commit Distributed Sandbox**: Dry-run simulation with automatic rollback and single-use HMAC-SHA256 commit tokens.
- **Transparent Middleware**: DB-API 2.0 cursor wrappers (`DBShieldConnectionWrapper`) and SQLAlchemy hooks (`attach_dbshield`) with zero application refactoring.
- **AI Agent Framework Integrations**:
  - **LangChain**: `DBShieldSQLDatabase` and `DBShieldQueryTool`
  - **CrewAI**: `DBShieldDatabaseTool`
  - **LlamaIndex**: `DBShieldLlamaIndexTransform`
- **100% Air-Gapped & Zero Telemetry**: Operates strictly local-first within air-gapped private VPC networks.

---

## 📦 Installation

```bash
pip install dbshield-defense
```

*Note: In code, import as standard `import dbshield` or `from dbshield import DBShieldGuard`.*

---

## 🚀 Usage Guide

### 1. In-Memory AST SQL Guard

Validate queries generated by LLMs before execution:

```python
from dbshield import DBShieldGuard

guard = DBShieldGuard()

# 1. Block destructive operations
result = guard.validate_query("DROP TABLE users")
print(result.allowed)     # False
print(result.risk_level)  # "CRITICAL"
print(result.violations)  # [Violation(code='DESTRUCTIVE_DDL_PROHIBITED', ...)]

# 2. Block unconstrained mutations and tautologies
result = guard.validate_query("DELETE FROM orders WHERE 1=1")
print(result.allowed)     # False
```

---

### 2. Dynamic PII Redaction & Format Preservation

```python
from dbshield import PiiRedactor

redactor = PiiRedactor()

text = "User SSN is 000-12-3456 and email is john@acme.com"
sanitized = redactor.redact_text(text)
print(sanitized)
# -> "User SSN is [REDACTED:SSN:9705bb] and email is j***n@a****e.com"
```

---

### 3. Transparent SQLAlchemy Integration

```python
from sqlalchemy import create_engine
from dbshield import attach_dbshield

engine = create_engine("postgresql://user:pass@localhost:5432/proddb")

# Attach DBShield interceptor hook
attach_dbshield(engine)

# All queries executed via engine are now validated and PII-sanitized automatically!
```

---

### 4. LangChain Integration

```python
from dbshield.integrations.langchain import DBShieldSQLDatabase, DBShieldQueryTool
from langchain_community.utilities import SQLDatabase

raw_db = SQLDatabase.from_uri("sqlite:///analytics.db")
shield_db = DBShieldSQLDatabase(raw_db)

# Create an agent tool that refuses destructive DDL or tautology queries
tool = DBShieldQueryTool(db=shield_db)
```

---

### 5. CrewAI Database Tool

```python
from dbshield.integrations.crewai import DBShieldDatabaseTool
import sqlite3

conn = sqlite3.connect("company.db")
db_tool = DBShieldDatabaseTool(connection=conn)

# When an autonomous CrewAI agent generates a query:
output = db_tool._run("SELECT name, email FROM customers WHERE active = 1")
print(output)  # Rows returned with sensitive PII automatically masked!
```

---

### 6. LlamaIndex Transform

```python
from dbshield.integrations.llamaindex import DBShieldLlamaIndexTransform

transform = DBShieldLlamaIndexTransform()
safe_response = transform.postprocess_response("Query returned user SSN 000-12-3456")
```

---

## 🔒 Security & Compliance

- **Zero Cloud Exfiltration**: Runs 100% locally with `DBSHIELD_AIR_GAPPED=1`.
- **Pre-filled SIG Lite / CAIQ**: Download the Vendor Risk Assessment Packet at [ritualdev.in/trust](https://ritualdev.in/trust).
- **Statutory Alignment**: Designed for **India DPDP Act 2023**, **EU GDPR**, and **SOC 2 Type II**.

---

## 📄 License

MIT © [RitualDev Studio](https://ritualdev.in)
