opaque-logger 1.1.0

🛡️ Enterprise Data Masking Engine - Custom Callbacks, LGPD/GDPR Compliance, 77+ Validators, Zero False Positives

🇺🇸 English | 🇧🇷 Português | 🇪🇸 Español

---

The only data masking library that uses MATH, not AI

🎯 Why OPAQUE?

Unlike AI-based solutions that guess, OPAQUE validates using mathematical algorithms:

Feature	AI Solutions	OPAQUE
Validation	Neural networks (guessing)	Mathematical algorithms (proof)
False Positives	Common	Zero
Performance	Slow (GPU required)	Ultra-fast (pure math)
Debuggability	Black box	Deterministic hashing
Reversibility	No	Yes (Vault Mode)
Coverage	Limited	40+ validators across South America

✨ Key Features

🔐 Mathematical Validation Brazil: CPF, CNPJ, RG, CNH, RENAVAM, Pix, License Plates Argentina: CUIL/CUIT, DNI Chile: RUT (full validation) Colombia: Cédula, NIT Peru: DNI, RUC Uruguay: CI, RUT Venezuela: CI, RIF Ecuador: Cédula, RUC Bolivia: CI, NIT Paraguay: CI, RUC International: Credit Cards (Luhn), IBAN, Email, Phone, Passport	🏦 Vault Mode AES-256 encryption Reversible for debugging CLI decryption tool Master key protection PBKDF2 key derivation
🍯 Honeytokens Intrusion detection Bait data alerts Real-time monitoring Security integration Automated alerts	⚡ Circuit Breaker Flood protection Auto-recovery Resource optimization Server stability Configurable thresholds

🚀 Quick Start

Installation

pip install opaque-logger

Basic Usage

import logging
from opaque import OpaqueLogger, Validators

# Configure
OpaqueLogger.setup_defaults(
    rules=[
        Validators.BR.CPF,
        Validators.BR.CNPJ,
        Validators.FINANCE.CREDIT_CARD
    ],
    obfuscation_method="HASH"
)

# Integrate
logging.setLoggerClass(OpaqueLogger)
logger = logging.getLogger("app")

# Log securely
logger.info("User CPF: 529.982.247-25")
# Output: User CPF: [HASH-3A4C]

logger.info("Invalid CPF: 111.222.333-44")
# Output: Invalid CPF: 111.222.333-44 (preserved for debugging)

📊 Performance Benchmarks

Sanitization:     1,000+ messages/sec
CPF Validation:   65,000+ ops/sec
CNPJ Validation:  68,000+ ops/sec
Credit Card:      122,000+ ops/sec
Vault Encryption: 22,000+ ops/sec
Vault Decryption: 12,000+ ops/sec

🧪 Test Coverage

pytest -v

Results: ✅ 62/62 tests passing (100% success rate)

• ✅ All validators tested with valid and invalid data
• ✅ Vault encryption/decryption
• ✅ Honeytoken detection
• ✅ Circuit breaker activation
• ✅ Crash handler sanitization
• ✅ Middleware integration
• ✅ CLI tools

📚 Examples

🔹 Vault Mode (Reversible Encryption)

import os
from opaque import OpaqueLogger, Validators

# Set master key
os.environ["OPAQUE_MASTER_KEY"] = "your-master-key"

OpaqueLogger.setup_defaults(
    rules=[Validators.BR.CPF],
    obfuscation_method="VAULT",
    vault_key="your-master-key"
)

logger = logging.getLogger("secure")
logger.info("Processing CPF 529.982.247-25")
# Output: Processing CPF [VAULT:gAAAAABl...]

# Decrypt later
python -m opaque.cli reveal "[VAULT:gAAAAABl...]" --key=your-master-key
# Output: 🔓 REVEALED DATA: 529.982.247-25

🔹 Honeytokens (Intrusion Detection)

OpaqueLogger.setup_defaults(
    rules=[Validators.BR.CPF],
    honeytokens=["999.888.777-66"]  # Bait CPF
)

logger = logging.getLogger("security")
logger.info("Access with CPF 999.888.777-66")
# Stderr: 🚨 ALERTA VERMELHO: HONEYTOKEN DETECTED: 999.888.777-66
# Output: Access with CPF [HONEYTOKEN TRIGGERED]

🔹 Crash Handler (Traceback Sanitization)

from opaque import install_crash_handler, OpaqueLogger, Validators

# Setup
OpaqueLogger.setup_defaults(rules=[Validators.BR.CPF])
install_crash_handler()

# Now all crashes sanitize sensitive data
password = "secret123"
cpf = "529.982.247-25"
raise ValueError(f"Error: {cpf}")
# Traceback shows: ValueError: Error: [HASH-3A4C]
# Locals show: password = [REDACTED_SECRET_KEY]

🔹 Multi-Country Support

from opaque import OpaqueLogger, Validators

# Configure for multiple countries
OpaqueLogger.setup_defaults(
    rules=[
        Validators.BR.CPF,      # Brazil
        Validators.AR.DNI,      # Argentina
        Validators.CL.RUT,      # Chile
        Validators.CO.CEDULA,   # Colombia
        Validators.PE.DNI,      # Peru
        Validators.FINANCE.CREDIT_CARD,  # International
    ]
)

logger = logging.getLogger("latam")
logger.info("BR CPF: 529.982.247-25")  # Sanitized
logger.info("CL RUT: 12.345.678-5")    # Sanitized
logger.info("Card: 4532-1488-0343-6467")  # Sanitized

🔹 Compliance Scanning

# Scan your codebase for sensitive data
python -m opaque.cli scan ./src --output=report.html

# Output:
# 🔍 Scanning directory: ./src...
# ✅ Report generated: report.html
# 🛡️ Security Score: 98%
# 
# Found:
# - 15 CPF instances
# - 8 CNPJ instances
# - 3 Credit Card instances
# 
# Recommendations:
# - Use OpaqueLogger in production
# - Enable Vault mode for debugging
# - Add honeytokens for intrusion detection

🔹 FastAPI Middleware

from fastapi import FastAPI
from opaque.middleware import OpaqueFastAPIMiddleware
from opaque import OpaqueLogger, Validators

app = FastAPI()

OpaqueLogger.setup_defaults(
    rules=[Validators.BR.CPF, Validators.BR.CNPJ]
)

# Middleware will sanitize all request/response data
app.add_middleware(OpaqueFastAPIMiddleware, logger=OpaqueLogger("api"))

@app.post("/payment")
async def process_payment(cpf: str, amount: float):
    # CPF will be automatically sanitized in logs
    return {"status": "success"}

🔹 Django Integration

# settings.py
MIDDLEWARE = [
    'opaque.middleware.OpaqueDjangoMiddleware',
    # ... other middleware
]

# Configure in apps.py or __init__.py
from opaque import OpaqueLogger, Validators

OpaqueLogger.setup_defaults(
    rules=[Validators.BR.CPF, Validators.BR.CNPJ]
)

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                   OPAQUE Engine                     │
├─────────────────────────────────────────────────────┤
│  1. Context-Aware Regex Pattern Matching           │
│  2. Mathematical Validation (Mod 11, Luhn, etc.)   │
│  3. Honeytoken Detection                            │
│  4. Circuit Breaker Check                           │
│  5. Obfuscation (Hash/Vault/Mask)                  │
│  6. Structured Data Processing (JSON/Dict/List)    │
└─────────────────────────────────────────────────────┘

Processing Flow

Input Log Message
       ↓
[Honeytoken Check] → Alert if detected
       ↓
[Regex Pattern Matching] → Find potential sensitive data
       ↓
[Mathematical Validation] → Verify using algorithms
       ↓
[Circuit Breaker] → Prevent flood attacks
       ↓
[Obfuscation] → Hash/Vault/Mask
       ↓
Output Sanitized Message

🌍 Supported Validators

🇧🇷 Brazil

• ✅ CPF - Individual taxpayer ID (Mod 11 validation)
• ✅ CNPJ - Company taxpayer ID (Weighted Mod 11)
• ✅ RG - Identity card (format validation)
• ✅ CNH - Driver's license (format validation)
• ✅ RENAVAM - Vehicle registration (format validation)
• ✅ Pix - Instant payment keys (UUID, Email, Phone)
• ✅ Placa Mercosul - New license plates (ABC1D23)
• ✅ Placa Antiga - Old license plates (ABC-1234)

🇦🇷 Argentina

• ✅ CUIL/CUIT - Tax identification number
• ✅ DNI - National identity document

🇨🇱 Chile

• ✅ RUT - Tax identification number (full Mod 11 validation)

🇨🇴 Colombia

• ✅ Cédula - National identity card
• ✅ NIT - Tax identification number

🇵🇪 Peru

• ✅ DNI - National identity document
• ✅ RUC - Tax identification number

🇺🇾 Uruguay

• ✅ CI - Identity card
• ✅ RUT - Tax identification number

🇻🇪 Venezuela

• ✅ CI - Identity card
• ✅ RIF - Tax identification number

🇪🇨 Ecuador

• ✅ Cédula - Identity card (with province validation)
• ✅ RUC - Tax identification number

🇧🇴 Bolivia

• ✅ CI - Identity card
• ✅ NIT - Tax identification number

🇵🇾 Paraguay

• ✅ CI - Identity card
• ✅ RUC - Tax identification number

💳 Finance (International)

• ✅ Credit Cards - Visa, Mastercard, Amex, etc. (Luhn algorithm)
• ✅ IBAN - International Bank Account Number (Mod 97 validation)

🌐 International

• ✅ Email - Email addresses (RFC 5322 format)
• ✅ Phone - International phone numbers
• ✅ Passport - Passport numbers (alphanumeric format)

📖 Documentation

Document	Description
🇺🇸 English Guide	Complete documentation in English
🇧🇷 Guia em Português	Documentação completa em Português
🇪🇸 Guía en Español	Documentación completa en Español
📚 API Reference	Detailed API documentation
🔧 Installation Guide	Step-by-step installation
🏗️ Project Structure	Architecture overview
🤝 Contributing	Contribution guidelines
📝 Changelog	Version history

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/SamuelSilvass/OPAQUE.git
cd OPAQUE

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest -v

# Run benchmarks
python benchmarks/benchmark.py

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• PyPI Package: opaque-logger
• GitHub Repository: SamuelSilvass/OPAQUE
• Issues: GitHub Issues
• Changelog: CHANGELOG.md
• Documentation: Complete Docs

🏆 Why Choose OPAQUE?

✅ Zero False Positives

Every match is mathematically validated. No guessing, no AI hallucinations.

✅ Production-Ready

Used in enterprise environments processing millions of logs daily.

✅ Comprehensive Coverage

40+ validators covering all South American countries + international standards.

✅ Reversible Encryption

Debug production issues without exposing sensitive data.

✅ Security First

Honeytokens, circuit breakers, and crash handlers protect your data.

✅ Framework Agnostic

Works with FastAPI, Django, Flask, or any Python application.

✅ Performance Optimized

Process thousands of messages per second without slowing down your app. rules=[Validators.BR.CPF, Validators.BR.CNPJ] )

Middleware will sanitize all request/response data

app.add_middleware(OpaqueFastAPIMiddleware, logger=OpaqueLogger("api"))

@app.post("/payment") async def process_payment(cpf: str, amount: float): # CPF will be automatically sanitized in logs return {"status": "success"}

</details>

<details>
<summary><b>🔹 Django Integration</b></summary>

```python
# settings.py
MIDDLEWARE = [
    'opaque.middleware.OpaqueDjangoMiddleware',
    # ... other middleware
]

# Configure in apps.py or __init__.py
from opaque import OpaqueLogger, Validators

OpaqueLogger.setup_defaults(
    rules=[Validators.BR.CPF, Validators.BR.CNPJ]
)

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                   OPAQUE Engine                     │
├─────────────────────────────────────────────────────┤
│  1. Context-Aware Regex Pattern Matching           │
│  2. Mathematical Validation (Mod 11, Luhn, etc.)   │
│  3. Honeytoken Detection                            │
│  4. Circuit Breaker Check                           │
│  5. Obfuscation (Hash/Vault/Mask)                  │
│  6. Structured Data Processing (JSON/Dict/List)    │
└─────────────────────────────────────────────────────┘

Processing Flow

Input Log Message
       ↓
[Honeytoken Check] → Alert if detected
       ↓
[Regex Pattern Matching] → Find potential sensitive data
       ↓
[Mathematical Validation] → Verify using algorithms
       ↓
[Circuit Breaker] → Prevent flood attacks
       ↓
[Obfuscation] → Hash/Vault/Mask
       ↓
Output Sanitized Message

🌍 Supported Validators

🇧🇷 Brazil

• ✅ CPF - Individual taxpayer ID (Mod 11 validation)
• ✅ CNPJ - Company taxpayer ID (Weighted Mod 11)
• ✅ RG - Identity card (format validation)
• ✅ CNH - Driver's license (format validation)
• ✅ RENAVAM - Vehicle registration (format validation)
• ✅ Pix - Instant payment keys (UUID, Email, Phone)
• ✅ Placa Mercosul - New license plates (ABC1D23)
• ✅ Placa Antiga - Old license plates (ABC-1234)

🇦🇷 Argentina

• ✅ CUIL/CUIT - Tax identification number
• ✅ DNI - National identity document

🇨🇱 Chile

• ✅ RUT - Tax identification number (full Mod 11 validation)

🇨🇴 Colombia

• ✅ Cédula - National identity card
• ✅ NIT - Tax identification number

🇵🇪 Peru

• ✅ DNI - National identity document
• ✅ RUC - Tax identification number

🇺🇾 Uruguay

• ✅ CI - Identity card
• ✅ RUT - Tax identification number

🇻🇪 Venezuela

• ✅ CI - Identity card
• ✅ RIF - Tax identification number

🇪🇨 Ecuador

• ✅ Cédula - Identity card (with province validation)
• ✅ RUC - Tax identification number

🇧🇴 Bolivia

• ✅ CI - Identity card
• ✅ NIT - Tax identification number

🇵🇾 Paraguay

• ✅ CI - Identity card
• ✅ RUC - Tax identification number

💳 Finance (International)

• ✅ Credit Cards - Visa, Mastercard, Amex, etc. (Luhn algorithm)
• ✅ IBAN - International Bank Account Number (Mod 97 validation)

🌐 International

• ✅ Email - Email addresses (RFC 5322 format)
• ✅ Phone - International phone numbers
• ✅ Passport - Passport numbers (alphanumeric format)

📖 Documentation

Document	Description
🇺🇸 English Guide	Complete documentation in English
🇧🇷 Guia em Português	Documentação completa em Português
🇪🇸 Guía en Español	Documentación completa en Español
📚 API Reference	Detailed API documentation
🔧 Installation Guide	Step-by-step installation
🏗️ Project Structure	Architecture overview
🤝 Contributing	Contribution guidelines
📝 Changelog	Version history

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/SamuelSilvass/OPAQUE.git
cd OPAQUE

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest -v

# Run benchmarks
python benchmarks/benchmark.py

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• PyPI Package: opaque-logger
• GitHub Repository: SamuelSilvass/OPAQUE
• Issues: GitHub Issues
• Changelog: CHANGELOG.md
• Documentation: Complete Docs

🏆 Why Choose OPAQUE?

✅ Zero False Positives

Every match is mathematically validated. No guessing, no AI hallucinations.

✅ Production-Ready

Used in enterprise environments processing millions of logs daily.

✅ Comprehensive Coverage

40+ validators covering all South American countries + international standards.

✅ Reversible Encryption

Debug production issues without exposing sensitive data.

✅ Security First

Honeytokens, circuit breakers, and crash handlers protect your data.

✅ Framework Agnostic

Works with FastAPI, Django, Flask, or any Python application.

✅ Performance Optimized

Process thousands of messages per second without slowing down your app.

---

Built with precision by Samuel Silva

Protecting data with mathematics, not magic ✨

Made with ❤️ for the developer community

---

📧 Contact

For questions, suggestions, or support, please contact:

Email: [e-mail]

Or open an issue on GitHub Issues