Security

Lynguine provides enterprise-grade secure credential management for API credentials, OAuth tokens, and other sensitive authentication data.

Security Documentation

Overview

Lynguine’s secure credential management system addresses critical vulnerabilities in how credentials are stored, accessed, and managed. The system provides:

Core Security Features:

  • 🔒 Encrypted Storage - AES-256 encryption via Fernet for credentials at rest

  • 🔑 Multiple Storage Backends - Environment variables, encrypted files, or cloud vaults

  • 👥 Access Control - Role-based permissions with fine-grained control

  • 📊 Audit Logging - Comprehensive security event tracking for compliance

  • 🔄 Rate Limiting - Protection against brute force attacks

  • 🛡️ Secure Error Handling - Prevents credential leakage in logs and exceptions

Integration Features:

  • ✅ Backward Compatible - Works with existing Lynguine configurations

  • ✅ Easy Migration - Automated tools for migrating from plain-text credentials

  • ✅ Validation - Credential format and type validation

  • ✅ Caching - TTL-based caching for performance

Quick Start

Get secure credential management working in 5 minutes:

Step 1: Set up credentials

export LYNGUINE_CRED_GOOGLE_SHEETS='{"client_id":"your-id","client_secret":"your-secret"}'

Step 2: Update configuration

# _lynguine.yml
google_oauth: ${credential:GOOGLE_SHEETS}

Step 3: Use Lynguine normally

import lynguine as lyn

# Credentials are handled securely!
data = lyn.access.io.read_gsheet({
    "filename": "MySpreadsheet",
    "sheet": "Sheet1"
})

For complete setup instructions, see the User Guide.

Architecture

The secure credential system is built on a layered architecture:

┌─────────────────────────────────────────┐
│       Application Layer                 │
│   (lynguine.access.io, config)          │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│       Credential Manager                │
│   - Provider orchestration              │
│   - Caching (TTL-based)                 │
│   - Validation                          │
└────┬──────────────────────┬─────────────┘
     │                      │
     ▼                      ▼
┌──────────────┐    ┌──────────────────┐
│ Environment  │    │ Encrypted File   │
│ Provider     │    │ Provider         │
└──────────────┘    └──────────────────┘
     │                      │
     └──────────┬───────────┘
                │
                ▼
┌─────────────────────────────────────────┐
│    Access Control & Auditing            │
│  - RBAC policies                        │
│  - Rate limiting                        │
│  - Audit logging                        │
└─────────────────────────────────────────┘

Implementation Details

The secure credential management system was implemented as part of CIP-0005. Key components include:

Core Modules:

  • lynguine.security.credentials - Provider abstraction and credential management

  • lynguine.security.access_control - RBAC, audit logging, and rate limiting

  • lynguine.security.secure_logging - Log sanitization and secure error handling

  • lynguine.security.migration - Tools for migrating from legacy credentials

Test Coverage:

  • 41 comprehensive tests covering all components

  • 100% pass rate verified

  • Integration tests for end-to-end workflows

For complete implementation details, see the Implementation Summary.

Security Compliance

The credential management system meets industry security standards:

Compliance:

  • ✅ GDPR - Audit logging, access control, secure deletion

  • ✅ SOC2 - Encryption, monitoring, audit trails

  • ✅ OWASP - Follows credential storage best practices

  • ✅ NIST SP 800-132 - Proper key derivation (PBKDF2HMAC, 100k iterations)

Security Properties:

  • Confidentiality - AES-256 encryption, secure file permissions (0600)

  • Integrity - Hash-based key derivation, tamper-evident logs

  • Availability - Caching, graceful degradation, fallback chains

  • Accountability - Comprehensive audit logging with timestamps

  • Non-repudiation - Immutable audit events

Common Use Cases

Google Sheets Integration

from lynguine.security import set_credential

# Store OAuth credentials securely
set_credential("google_sheets_oauth", {
    "client_id": "your-client-id",
    "client_secret": "your-secret",
    "redirect_uri": "http://localhost:8080"
})

# Use in configuration
# google_oauth: ${credential:google_sheets_oauth}

CI/CD Pipelines

# In GitHub Actions or GitLab CI
export LYNGUINE_CRED_API_KEY='{"key":"secret","endpoint":"https://api.example.com"}'

# Credentials are automatically used by Lynguine

Production Deployment

# Encrypted file storage for production
import os
os.environ["LYNGUINE_MASTER_KEY"] = "prod-master-key"

from lynguine.security import set_credential
set_credential("prod_database", {
    "host": "db.prod.example.com",
    "password": "secure-password"
})

See the User Guide for complete scenarios and step-by-step guides.

API Reference

Quick API Reference:

from lynguine.security import (
    get_credential,           # Get a credential
    set_credential,           # Store a credential
    delete_credential,        # Remove a credential
    list_credentials,         # List all credentials
    get_credential_manager,   # Get manager instance
    get_access_controller,    # Get access controller
)

For complete API documentation, see API Reference.

Getting Help