Metadata-Version: 2.4
Name: piiguardrails
Version: 2.0.8.post1
Summary: Enterprise PII Guardrail Studio
Project-URL: Homepage, https://github.com/piiguardrails/piiguardrails
Project-URL: Repository, https://github.com/piiguardrails/piiguardrails
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<div align="center">

# 🛡️ Enterprise PII Guardrails Studio

**High-Performance, Zero-Leak AI Privacy Gateway & Management Studio for Enterprise LLM Pipelines**

[![PyPI Version](https://img.shields.io/badge/PyPI%20Package-v2.0.8-blue?logo=pypi&logoColor=white)](https://pypi.org/project/piiguardrails/)
[![PyPI Downloads](https://img.shields.io/pepy/dt/piiguardrails?color=blue&label=PyPI%20Downloads&logo=pypi&logoColor=white)](https://pypi.org/project/piiguardrails/)
[![GitHub Downloads](https://img.shields.io/github/downloads/piiguardrails/piiguardrails/total?color=blue&label=GitHub%20Downloads&logo=github)](https://github.com/piiguardrails/piiguardrails)
[![Docker Pulls](https://img.shields.io/docker/pulls/piiguardrails/enterprise-pii-guardrail?color=blue&label=Docker%20Pulls&logo=docker&logoColor=white)](https://hub.docker.com/r/piiguardrails/enterprise-pii-guardrail)
[![GitHub Stars](https://img.shields.io/github/stars/piiguardrails/piiguardrails?style=flat&logo=github&color=gold)](https://github.com/piiguardrails/piiguardrails)

[![Python Version](https://img.shields.io/badge/python-%3E%3D%203.8-3776AB?logo=python&logoColor=white)](https://pypi.org/project/piiguardrails/)
[![Security](https://img.shields.io/badge/Security-AES--256%20SQLCipher%20%7C%20Ed25519-blueviolet)](https://github.com/piiguardrails/piiguardrails)
[![Performance](https://img.shields.io/badge/Latency-%3C25ms%20In--Memory-brightgreen)](https://github.com/piiguardrails/piiguardrails)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20x64-0078D4?logo=linux&logoColor=white)](https://pypi.org/project/piiguardrails/)
[![License](https://img.shields.io/badge/License-Commercial%20%2F%20Evaluation-orange)](https://github.com/piiguardrails/piiguardrails/blob/main/LICENSE)

<br/>

[**PyPI Package**](https://pypi.org/project/piiguardrails/) • [**GitHub Repository**](https://github.com/piiguardrails/piiguardrails) • [**API Reference**](https://github.com/piiguardrails/piiguardrails/blob/main/docs/API_REFERENCE.md) • [**Commercial License**](https://piiguardrails.com/license) • [**Licensing Guide**](https://github.com/piiguardrails/piiguardrails/blob/main/LICENSING_GUIDE.md) • [**Report Issue**](https://github.com/piiguardrails/piiguardrails/issues)

</div>

---

## 📸 The Enterprise Studio in Action

### Interactive PII Playground (Live Detection with Visual Highlight Pills)
Inspect, scrub, and redact sensitive entities with sub-25ms latency. Visual badge pills pinpoint exactly what the engine detected before it ever leaves your network.

![Interactive PII Playground](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/hero_playground.png)

<br/>

<details>
<summary><b>🔍 Expand to View Additional Studio Screenshots (8 Views)</b></summary>

<br/>

#### 1. Deterministic Safe Payload Output (`/mask`)
Transformed prompt ready for LLM consumption with reversible placeholder tokens (`<PERSON_1>`, `<SSN_1>`, `<CREDIT_CARD_1>`) and UIDAI statutory masked Aadhaar (`XXXX-XXXX-1234`).

![Safe Payload View](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/safe_payload_view.png)

#### 2. 30+ Entity Recognizers & Regulatory Profiles (HIPAA, GDPR, India DPDP, PCI-DSS)
Granular toggles for Financial, Healthcare, IT Security, Core PII, and statutory regional compliance—including the turnkey **India DPDP Act (2023)** profile with UIDAI Masked Aadhaar (`XXXX-XXXX-1234`), PAN Card, ABHA Health ID, UPI VPA, and IFSC Code.

![Guardrail Profiles](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/guardrail_profiles.png)

#### 3. External Logging & SIEM Integrations Hub (Splunk, Datadog, Webhooks)
Enterprise log stream forwarders with automated Splunk Event wrapping, Datadog Intake API integration, and real-time radiating status beacons.

![SIEM Integrations](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/siem_integrations.png)

#### 4. Enterprise Security Audit Logs & Telemetry
Immutable audit trails recording all masking events, policy intercepts, and administrative actions with full-text search, filtering, and CSV/JSON export.

![Audit Logs](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/audit_logs.png)

#### 5. Dynamic Custom Entity Pool (SQLite-Backed)
Define, search, and manage custom organization-specific regex patterns and entity definitions persisted directly in the local encrypted database.

![Custom Entity Pool](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/custom_entity_pool.png)

#### 6. Real-Time Threat Intelligence & IoC Shield
Interception firewall blocking malicious IP addresses, phishing domains, and credential leaks before evaluation.

![Threat Intelligence](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/threat_intelligence.png)

#### 7. Node-Locked Enterprise Licensing & Hardware ID Management
Cryptographically bound to your server hardware using Ed25519 signatures with zero external network phone-home requirement.

![License Management](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/license_management.png)

#### 8. Enterprise Authentication Portal
Encrypted session management, role-based access control, secret visibility eye-toggles, and customizable enterprise branding.

![Login Screen](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/login_screen.png)

</details>

---

## ⚡ Overview

**Enterprise PII Guardrails Studio** is an ultra-fast, defense-in-depth privacy gateway designed to intercept, detect, mask, and pseudonymize Personally Identifiable Information (PII) before it reaches third-party LLM APIs (OpenAI, Anthropic, Google Gemini, Azure OpenAI) or internal vector databases.

### Key Highlights:
- **Sub-25ms Live Masking**: In-memory LRU authorization cache and non-blocking asynchronous audit pipeline.
- **Turnkey Statutory Regulatory Profiles**: 1-click baseline protection for **HIPAA Security Rule Safeguards (45 CFR 164.312)**, **GDPR Article 32 Technical Measures**, **PCI-DSS v4.0 Req 3.4 Shield**, and **India DPDP Act (2023)** (with UIDAI Aadhaar, PAN, ABHA, UPI, and IFSC support).
- **Zero-Leak Guarantee at Rest**: Database, API keys, and audit logs are encrypted using **SQLCipher 256-bit AES-CBC** (with per-page HMAC-SHA512 integrity verification). Exported configurations and vault token dumps utilize Authenticated **AES-256-GCM**.
- **SHA-256 Cryptographic Verification**: Every downloaded runtime engine is verified on the fly against official SHA-256 hashes prior to execution.
- **Node-Locked Licensing (v4)**: Commercial licenses are cryptographically locked to the host's **Server Hardware ID** via Ed25519 asymmetric signatures—operating 100% offline with zero cloud dependency.
- **Bi-Directional Token Restoration**: Effortlessly restore LLM responses (`/unmask`) back to original values for authorized end users.

---

## 🔄 How It Works (Zero-Trust Pipeline)

```mermaid
sequenceDiagram
    autonumber
    actor User as Client / App
    participant GW as PII Guardrail Gateway
    participant Cache as In-Memory Auth Cache
    participant Engine as Multi-Tier PII Recognizer
    participant DB as SQLCipher AES-256
    participant LLM as External LLM (OpenAI / Anthropic)

    User->>GW: POST /mask (Prompt with sensitive PII)
    GW->>Cache: Verify X-API-Key (< 0.1ms)
    GW->>Engine: Scan regex rules + NLP entities
    Engine->>DB: Asynchronously store reversible tokens & mapping
    GW-->>User: Return Safe Payload (<PERSON_1>, <SSN_1>)
    
    User->>LLM: Send sanitized payload
    LLM-->>User: Return completion with tokens
    
    User->>GW: POST /unmask (LLM output + mapping vault)
    GW-->>User: Return restored response with real entity values
```

---

## 🚀 Quickstart

### Method 1: Using `pip` (Recommended)

```bash
# 1. Install from PyPI
pip install piiguardrails

# 2. Launch the studio
piiguardrails
```

On first launch, `piiguardrails` automatically streams the core binary, verifies its **SHA-256 cryptographic checksum**, provisions your encrypted database, and opens the studio dashboard on:
👉 **`http://localhost:8000`**

---

### Method 2: Using `uv` (Instant Sandbox — Zero Setup)

Run directly in a self-contained, isolated environment without polluting global Python:

```bash
uv run --with piiguardrails piiguardrails
```

---

### Method 3: Standalone Pre-Compiled Executable

For restricted air-gapped environments without Python installed, download the standalone binary directly from [GitHub Releases](https://github.com/piiguardrails/piiguardrails/releases):

- **Windows x64**: `EnterprisePIIGuardrail-v2.0.8-windows-x64.exe`
  - *SHA-256*: `43f26500fe8aed2ca78bef958639aea7317ec322ac1927fd4775fc9feea3ec37`
- **Linux x86_64**: `EnterprisePIIGuardrail-v2.0.8-linux-x86_64`
  - *SHA-256*: `8c2c62885ecaecce1bcb458ab86aa824eee1946cfe887100dbcd01b15ffdd77a`

Run directly:
```bash
# Linux
chmod +x EnterprisePIIGuardrail-v2.0.8-linux-x86_64
./EnterprisePIIGuardrail-v2.0.8-linux-x86_64

# Windows
.\EnterprisePIIGuardrail-v2.0.8-windows-x64.exe
```

---

### Method 4: Docker / Podman Deployment

```bash
docker run -d \
  -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  -e ACCEPT_LICENSE=true \
  -e SQLCIPHER_PASSPHRASE="your-secure-passphrase-min-32-chars!" \
  -e GUI_PASSWORD="<your-secure-password>" \
  --name pii-guardrail-studio \
  piiguardrails/enterprise-pii-guardrail:latest
```

---

### 🎁 Community Launch Promo: 6 Months Free Enterprise

To celebrate our v2.0 release, early adopters can unlock full **Enterprise Tier** features (unlimited API requests, unrestricted payload length, and custom regex policies) through **March 31, 2027**:

```text
ED3-AMBGXK7UVD777777-GRYXEUYUZ432JOHY-UWVDBHXRLAXU4U47-7MBK2DQGIUV4JQT6-UJNRXNTHI3JPBGIS-P66HGKVYNLMQXHHS-M3N4RF3XDN6LZILT-WQNCGJ4KEY6ONIIM
```

**To activate:**
1. Open the studio dashboard (`http://localhost:8000`).
2. Go to **Settings > License & Quota** in the sidebar.
3. Paste the key above and click **Activate License**.

---

## 🧩 Python Integration Example

Once the studio is running, integrate it directly into your LangChain, LlamaIndex, or raw API pipeline:

```python
import requests

API_KEY = "your-api-key-here"  # Generated in the Studio UI
headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# 1. Mask sensitive input before sending to LLM
payload = {
    "text": "Hello Alice Smith, your verification code was sent to alice.smith@acme.corp. Call us at 415-555-2671."
}

mask_response = requests.post("http://localhost:8000/mask", json=payload, headers=headers).json()
print("Masked text for LLM:", mask_response["masked_text"])
# Output: "Hello <PERSON_1>, your verification code was sent to <EMAIL_1>. Call us at <PHONE_1>."

# 2. Query your LLM with safe, masked prompt...
# simulated_llm_reply = "We contacted <PERSON_1> at <EMAIL_1> regarding the ticket."

# 3. Unmask the LLM response back to real entities for your user
unmask_payload = {
    "text": "We contacted <PERSON_1> at <EMAIL_1>.",
    "mapping": mask_response["mapping"]
}
unmask_response = requests.post("http://localhost:8000/unmask", json=unmask_payload, headers=headers).json()
print("Restored response:", unmask_response["unmasked_text"])
# Output: "We contacted Alice Smith at alice.smith@acme.corp."
```

---

## 🛡️ Enterprise Feature Matrix

| Capability | Trial Tier | Standard Tier | Enterprise Tier |
| :--- | :---: | :---: | :---: |
| **Masking Latency** | **< 25ms** | **< 25ms** | **< 25ms** |
| **Pre-built Entity Recognizers** | 30+ Included | 30+ Included | 30+ Included |
| **Custom Regex Engine** | 2 Patterns | 5 Patterns | **Unlimited** |
| **Max Payload Size** | 5,000 chars | 50,000 chars | **Unrestricted** |
| **API Request Quota** | 1,000 reqs/mo | 20,000 reqs/mo | **Unlimited** |
| **Storage Security** | SQLCipher AES-256-CBC | SQLCipher AES-256-CBC | **SQLCipher AES-256-CBC** |
| **Licensing Mode** | Version 3 Floating | Version 3 Floating | **Version 4 Node-Locked (HWID)** |
| **Threat Intelligence Shield** | ✅ Included | ✅ Included | ✅ Included |
| **Audit Logging & Retention** | ✅ Included | ✅ Included | ✅ Included |

> 🎁 **Community Launch Promo**: To celebrate our launch, early adopters can use the promotional product key above to activate the full **Enterprise Tier** (unlimited quota, unrestricted payload length, and unlimited custom regex patterns) free of charge through **March 31, 2027**.

---

## 📚 Complete Documentation Index

- 📖 **[API Reference Specification](https://github.com/piiguardrails/piiguardrails/blob/main/docs/API_REFERENCE.md)**: Full OpenAPI / REST documentation with request/response schemas for `/mask`, `/unmask`, `/health`, and Admin endpoints.
- 📊 **[Performance Benchmarks](https://github.com/piiguardrails/piiguardrails/blob/main/docs/BENCHMARKS.md)**: Latency breakdown (<25ms target, 3.8ms P50), concurrency tests, and test machine methodology.
- 🗂️ **[Entity Catalog](https://github.com/piiguardrails/piiguardrails/blob/main/docs/ENTITY_CATALOG.md)**: Exhaustive reference of 30+ built-in recognizers, context patterns, and mathematical checksum validations.
- 🛡️ **[Security Policy](https://github.com/piiguardrails/piiguardrails/blob/main/SECURITY.md)**: Vulnerability disclosure SLAs, security practices, and incident reporting.
- 🏰 **[Threat Model & Trust Boundaries](https://github.com/piiguardrails/piiguardrails/blob/main/docs/THREAT_MODEL.md)**: STRIDE analysis, network ingress/egress profile, and local attack surface.
- 🔑 **[Customer Licensing Guide](https://github.com/piiguardrails/piiguardrails/blob/main/LICENSING_GUIDE.md)**: Guide on tiers, obtaining your Server Hardware ID, and activating enterprise keys offline.
- 💾 **[Backup & Disaster Recovery Guide](https://github.com/piiguardrails/piiguardrails/blob/main/docs/BACKUP_AND_DISASTER_RECOVERY.md)**: Database persistence, `.env` encryption passphrase management, and server migration.

---

## 📋 System Requirements

- **Operating System**: Windows 10/11/Server (64-bit) or Linux (Ubuntu, Debian, RHEL, CentOS, Rocky, WSL2 x86_64)
- **Python**: `>= 3.8` (if running via `pip` / `uv`)
- **Memory**: Minimum 2 GB RAM (4 GB recommended for high throughput)
- **Network Port**: Default `8000` (configurable via `--port` or `.env`)

---

## 📄 License

This software is governed by the [Enterprise Evaluation and Commercial License Agreement](https://piiguardrails.com/license) ([Repository Copy](https://github.com/piiguardrails/piiguardrails/blob/main/LICENSE)). All rights reserved.

---

## ⚖️ Statutory & Compliance Disclaimer

Enterprise PII Guardrail provides technical safeguards to assist organizations in meeting regulatory obligations (such as India DPDP Act 2023, HIPAA Security Rule 45 CFR 164.312, PCI-DSS v4.0 Req 3.4, and GDPR Art. 32). Software alone does not constitute legal certification or regulatory compliance. Organizations remain responsible for their overall compliance postures and governance policies.
