Skip to content

Commit 73ae7c1

Browse files
feat: initial release of DBShield Python SDK (dbshield-defense)
0 parents  commit 73ae7c1

20 files changed

Lines changed: 1524 additions & 0 deletions

‎.github/workflows/publish-pypi.yml‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
name: Publish to PyPI
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
workflow_dispatch:
8+
9+
permissions: read-all
10+
11+
jobs:
12+
build:
13+
name: Build distribution 📦
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: read
17+
18+
steps:
19+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
20+
21+
- name: Set up Python
22+
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.0.0
23+
with:
24+
python-version: '3.12'
25+
26+
- name: Install pypa/build (hash-pinned)
27+
run: python3 -m pip install --require-hashes -r requirements-build.txt
28+
29+
- name: Build a binary wheel and a source tarball
30+
run: python3 -m build
31+
32+
- name: Generate CycloneDX SBOM
33+
uses: anchore/sbom-action@66cbf4bc1f1c0d2edc94016e65bc221b6bb0ad6c # v0.24.3
34+
with:
35+
path: ./
36+
format: 'cyclonedx-json'
37+
output-file: 'dist/dbshield-python-cyclonedx.sbom.json'
38+
artifact-name: 'dbshield-python-cyclonedx.sbom.json'
39+
upload-artifact: true
40+
upload-release-assets: false
41+
42+
- name: Generate SPDX SBOM
43+
uses: anchore/sbom-action@66cbf4bc1f1c0d2edc94016e65bc221b6bb0ad6c # v0.24.3
44+
with:
45+
path: ./
46+
format: 'spdx-json'
47+
output-file: 'dist/dbshield-python-spdx.sbom.json'
48+
artifact-name: 'dbshield-python-spdx.sbom.json'
49+
upload-artifact: true
50+
upload-release-assets: false
51+
52+
- name: Store the distribution packages
53+
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.0
54+
with:
55+
name: python-package-distributions
56+
path: dist/
57+
58+
publish-to-pypi:
59+
name: Publish Python 🐍 distribution 📦 to PyPI
60+
needs:
61+
- build
62+
runs-on: ubuntu-latest
63+
permissions:
64+
contents: read
65+
id-token: write
66+
environment:
67+
name: pypi
68+
url: https://pypi.org/p/dbshield-defense
69+
70+
steps:
71+
- name: Download all the dists
72+
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.0
73+
with:
74+
name: python-package-distributions
75+
path: dist/
76+
77+
- name: Publish distribution 📦 to PyPI
78+
uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.12.4
79+
with:
80+
password: ${{ secrets.PYPI_API_TOKEN }}
81+
82+
create-release:
83+
name: Create GitHub Release with SBOM Artifacts
84+
needs:
85+
- publish-to-pypi
86+
if: startsWith(github.ref, 'refs/tags/v')
87+
runs-on: ubuntu-latest
88+
permissions:
89+
contents: write
90+
steps:
91+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
92+
93+
- name: Download all the dists
94+
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.0
95+
with:
96+
name: python-package-distributions
97+
path: dist/
98+
99+
- name: Create GitHub Release
100+
uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2.6.2
101+
with:
102+
generate_release_notes: true
103+
files: |
104+
dist/*
105+
env:
106+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/python-tests.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: Python CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
permissions: read-all
10+
11+
jobs:
12+
test:
13+
runs-on: ubuntu-latest
14+
permissions:
15+
contents: read
16+
strategy:
17+
matrix:
18+
python-version: ["3.10", "3.11", "3.12", "3.13"]
19+
20+
steps:
21+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
22+
23+
- name: Set up Python ${{ matrix.python-version }}
24+
uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.0.0
25+
with:
26+
python-version: ${{ matrix.python-version }}
27+
28+
- name: Install dependencies
29+
run: |
30+
python -m pip install --upgrade pip
31+
pip install pytest
32+
33+
- name: Run Test Suite
34+
env:
35+
PYTHONPATH: src
36+
run: |
37+
python -m pytest tests/

‎.github/workflows/scorecard.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: OpenSSF Scorecard Security Analysis
2+
3+
on:
4+
branch_protection_rule:
5+
schedule:
6+
- cron: '30 1 * * 1'
7+
push:
8+
branches: [main]
9+
workflow_dispatch:
10+
11+
permissions: read-all
12+
13+
jobs:
14+
analysis:
15+
name: Scorecard Analysis
16+
runs-on: ubuntu-latest
17+
permissions:
18+
security-events: write
19+
id-token: write
20+
contents: read
21+
actions: read
22+
23+
steps:
24+
- name: Checkout Code
25+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
26+
with:
27+
persist-credentials: false
28+
29+
- name: Run OpenSSF Scorecard
30+
uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
31+
with:
32+
results_file: results.sarif
33+
results_format: sarif
34+
publish_results: true
35+
36+
- name: Upload SARIF to GitHub Code Scanning
37+
uses: github/codeql-action/upload-sarif@9418214df1f2c4b8128c770156c409013b07d6b9 # v3.28.11
38+
with:
39+
sarif_file: results.sarif

‎.gitignore‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
__pycache__/
2+
*.py[cod]
3+
*$py.class
4+
*.so
5+
.Python
6+
build/
7+
develop-eggs/
8+
dist/
9+
downloads/
10+
eggs/
11+
.eggs/
12+
lib/
13+
lib64/
14+
parts/
15+
sdist/
16+
var/
17+
wheels/
18+
share/python-wheels/
19+
*.egg-info/
20+
.installed.cfg
21+
*.egg
22+
.pytest_cache/
23+
.env
24+
.venv
25+
env/
26+
venv/
27+
ENV/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 RitualDev Studio (Divyanshu Jethi & Sakshi Sharma)
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
<div align="center">
2+
3+
# DBShield Python SDK 🛡️
4+
5+
[![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/)
6+
[![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/)
7+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
8+
[![Interactive Playground](https://img.shields.io/badge/Playground-Live%20Demo-00F59B?style=for-the-badge)](https://ritualdev.in/playground)
9+
[![Trust Center](https://img.shields.io/badge/Trust-SIG%20Lite%20%2F%20DPDP-00D4FF?style=for-the-badge)](https://ritualdev.in/trust)
10+
11+
> Enterprise-grade Database Guardrail & Wire Proxy Python SDK for Autonomous AI Agents built with LangChain, CrewAI, LlamaIndex, and SQLAlchemy.
12+
13+
[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)
14+
15+
</div>
16+
17+
---
18+
19+
## ⚡ Key Features
20+
21+
- **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.
22+
- **Dynamic PII Redactor**: Format-preserving pseudonymization and regex redaction for SSNs, Luhn-valid credit card numbers, email addresses, and JWT/API tokens.
23+
- **Two-Phase Commit Distributed Sandbox**: Dry-run simulation with automatic rollback and single-use HMAC-SHA256 commit tokens.
24+
- **Transparent Middleware**: DB-API 2.0 cursor wrappers (`DBShieldConnectionWrapper`) and SQLAlchemy hooks (`attach_dbshield`) with zero application refactoring.
25+
- **AI Agent Framework Integrations**:
26+
- **LangChain**: `DBShieldSQLDatabase` and `DBShieldQueryTool`
27+
- **CrewAI**: `DBShieldDatabaseTool`
28+
- **LlamaIndex**: `DBShieldLlamaIndexTransform`
29+
- **100% Air-Gapped & Zero Telemetry**: Operates strictly local-first within air-gapped private VPC networks.
30+
31+
---
32+
33+
## 📦 Installation
34+
35+
```bash
36+
pip install dbshield-defense
37+
```
38+
39+
*Note: In code, import as standard `import dbshield` or `from dbshield import DBShieldGuard`.*
40+
41+
---
42+
43+
## 🚀 Usage Guide
44+
45+
### 1. In-Memory AST SQL Guard
46+
47+
Validate queries generated by LLMs before execution:
48+
49+
```python
50+
from dbshield import DBShieldGuard
51+
52+
guard = DBShieldGuard()
53+
54+
# 1. Block destructive operations
55+
result = guard.validate_query("DROP TABLE users")
56+
print(result.allowed) # False
57+
print(result.risk_level) # "CRITICAL"
58+
print(result.violations) # [Violation(code='DESTRUCTIVE_DDL_PROHIBITED', ...)]
59+
60+
# 2. Block unconstrained mutations and tautologies
61+
result = guard.validate_query("DELETE FROM orders WHERE 1=1")
62+
print(result.allowed) # False
63+
```
64+
65+
---
66+
67+
### 2. Dynamic PII Redaction & Format Preservation
68+
69+
```python
70+
from dbshield import PiiRedactor
71+
72+
redactor = PiiRedactor()
73+
74+
text = "User SSN is 000-12-3456 and email is john@acme.com"
75+
sanitized = redactor.redact_text(text)
76+
print(sanitized)
77+
# -> "User SSN is [REDACTED:SSN:9705bb] and email is j***n@a****e.com"
78+
```
79+
80+
---
81+
82+
### 3. Transparent SQLAlchemy Integration
83+
84+
```python
85+
from sqlalchemy import create_engine
86+
from dbshield import attach_dbshield
87+
88+
engine = create_engine("postgresql://user:pass@localhost:5432/proddb")
89+
90+
# Attach DBShield interceptor hook
91+
attach_dbshield(engine)
92+
93+
# All queries executed via engine are now validated and PII-sanitized automatically!
94+
```
95+
96+
---
97+
98+
### 4. LangChain Integration
99+
100+
```python
101+
from dbshield.integrations.langchain import DBShieldSQLDatabase, DBShieldQueryTool
102+
from langchain_community.utilities import SQLDatabase
103+
104+
raw_db = SQLDatabase.from_uri("sqlite:///analytics.db")
105+
shield_db = DBShieldSQLDatabase(raw_db)
106+
107+
# Create an agent tool that refuses destructive DDL or tautology queries
108+
tool = DBShieldQueryTool(db=shield_db)
109+
```
110+
111+
---
112+
113+
### 5. CrewAI Database Tool
114+
115+
```python
116+
from dbshield.integrations.crewai import DBShieldDatabaseTool
117+
import sqlite3
118+
119+
conn = sqlite3.connect("company.db")
120+
db_tool = DBShieldDatabaseTool(connection=conn)
121+
122+
# When an autonomous CrewAI agent generates a query:
123+
output = db_tool._run("SELECT name, email FROM customers WHERE active = 1")
124+
print(output) # Rows returned with sensitive PII automatically masked!
125+
```
126+
127+
---
128+
129+
### 6. LlamaIndex Transform
130+
131+
```python
132+
from dbshield.integrations.llamaindex import DBShieldLlamaIndexTransform
133+
134+
transform = DBShieldLlamaIndexTransform()
135+
safe_response = transform.postprocess_response("Query returned user SSN 000-12-3456")
136+
```
137+
138+
---
139+
140+
## 🔒 Security & Compliance
141+
142+
- **Zero Cloud Exfiltration**: Runs 100% locally with `DBSHIELD_AIR_GAPPED=1`.
143+
- **Pre-filled SIG Lite / CAIQ**: Download the Vendor Risk Assessment Packet at [ritualdev.in/trust](https://ritualdev.in/trust).
144+
- **Statutory Alignment**: Designed for **India DPDP Act 2023**, **EU GDPR**, and **SOC 2 Type II**.
145+
146+
---
147+
148+
## 📄 License
149+
150+
MIT © [RitualDev Studio](https://ritualdev.in)

0 commit comments

Comments
 (0)