empathy-framework 5.3.0__py3-none-any.whl → 5.4.0__py3-none-any.whl

empathy_llm_toolkit/security/QUICK_REFERENCE.md

@@ -1,316 +0,0 @@
-# Audit Logger Quick Reference
-
-## Import
-
-```python
-from empathy_llm_toolkit.security import AuditLogger
-```
-
-## Initialize
-
-```python
-# Production
-logger = AuditLogger(log_dir="/var/log/empathy")
-
-# Development
-logger = AuditLogger(log_dir="./logs", enable_console_logging=True)
-```
-
-## Log Events
-
-### LLM Request
-```python
-logger.log_llm_request(
-    user_id="user@company.com",
-    empathy_level=3,
-    provider="anthropic",
-    model="claude-sonnet-4",
-    memory_sources=["enterprise", "user", "project"],
-    pii_count=0,
-    secrets_count=0
-)
-```
-
-### Pattern Storage
-```python
-logger.log_pattern_store(
-    user_id="user@company.com",
-    pattern_id="pattern_123",
-    pattern_type="architecture",
-    classification="INTERNAL",  # PUBLIC, INTERNAL, or SENSITIVE
-    pii_scrubbed=2,
-    retention_days=180
-)
-```
-
-### Pattern Retrieval
-```python
-logger.log_pattern_retrieve(
-    user_id="user@company.com",
-    pattern_id="pattern_123",
-    classification="INTERNAL",
-    access_granted=True
-)
-```
-
-### Security Violation
-```python
-logger.log_security_violation(
-    user_id="user@company.com",
-    violation_type="secrets_detected",
-    severity="HIGH",  # LOW, MEDIUM, HIGH, or CRITICAL
-    details={"secret_type": "api_key"},
-    blocked=True
-)
-```
-
-## Query Logs
-
-### Basic Queries
-```python
-# By event type
-events = logger.query(event_type="llm_request")
-
-# By user
-events = logger.query(user_id="user@company.com")
-
-# By status
-events = logger.query(status="failed")
-```
-
-### Date Range
-```python
-from datetime import datetime, timedelta
-
-events = logger.query(
-    start_date=datetime.utcnow() - timedelta(days=7),
-    end_date=datetime.utcnow()
-)
-```
-
-### Nested Filters
-```python
-# Patterns with >5 PII items scrubbed
-events = logger.query(
-    event_type="store_pattern",
-    security__pii_scrubbed__gt=5
-)
-
-# Failed requests with secrets
-events = logger.query(
-    event_type="llm_request",
-    status="failed",
-    security__secrets_detected__gt=0
-)
-```
-
-### Comparison Operators
-- `__gt`: greater than
-- `__gte`: greater than or equal
-- `__lt`: less than
-- `__lte`: less than or equal
-- `__ne`: not equal
-
-## Reports
-
-### Violation Summary
-```python
-summary = logger.get_violation_summary(user_id="user@company.com")
-print(f"Total: {summary['total_violations']}")
-print(f"By type: {summary['by_type']}")
-print(f"By severity: {summary['by_severity']}")
-```
-
-### Compliance Report
-```python
-report = logger.get_compliance_report(
-    start_date=datetime.utcnow() - timedelta(days=30)
-)
-
-print(f"LLM requests: {report['llm_requests']['total']}")
-print(f"Pattern storage: {report['pattern_storage']['total']}")
-print(f"GDPR compliance: {report['compliance_metrics']['gdpr_compliant_rate']:.2%}")
-print(f"HIPAA compliance: {report['compliance_metrics']['hipaa_compliant_rate']:.2%}")
-```
-
-## Log Format
-
-Each line in `audit.jsonl`:
-```json
-{
-  "event_id": "evt_abc123",
-  "timestamp": "2025-11-24T19:03:08.114456Z",
-  "version": "1.0",
-  "event_type": "llm_request",
-  "user_id": "user@company.com",
-  "status": "success",
-  "llm": { "provider": "anthropic", "model": "claude-sonnet-4", "empathy_level": 3 },
-  "security": { "pii_detected": 0, "secrets_detected": 0 },
-  "compliance": { "gdpr_compliant": true, "hipaa_compliant": true }
-}
-```
-
-## Configuration Options
-
-```python
-AuditLogger(
-    log_dir="/var/log/empathy",      # Log directory
-    log_filename="audit.jsonl",       # Log file name
-    max_file_size_mb=100,             # Max file size before rotation
-    retention_days=365,               # Days to retain logs
-    enable_rotation=True,             # Enable automatic rotation
-    enable_console_logging=False      # Also log to console
-)
-```
-
-## Common Patterns
-
-### Integration with EmpathyLLM
-```python
-from empathy_llm_toolkit import EmpathyLLM
-
-audit_logger = AuditLogger()
-llm = EmpathyLLM(provider="anthropic")
-
-async def interact_with_audit(user_id, user_input):
-    response = await llm.interact(user_id, user_input, {})
-
-    audit_logger.log_llm_request(
-        user_id=user_id,
-        empathy_level=response["empathy_level"],
-        provider="anthropic",
-        model="claude-sonnet-4",
-        memory_sources=["enterprise", "user"],
-        pii_count=0,
-        secrets_count=0
-    )
-
-    return response
-```
-
-### Daily Compliance Check
-```python
-from datetime import datetime, timedelta
-
-# Generate yesterday's report
-report = logger.get_compliance_report(
-    start_date=datetime.utcnow() - timedelta(days=1)
-)
-
-# Alert if compliance drops
-if report['compliance_metrics']['gdpr_compliant_rate'] < 0.95:
-    send_alert("GDPR compliance below 95%")
-```
-
-### Monitor Security Violations
-```python
-# Check recent violations
-violations = logger.query(
-    event_type="security_violation",
-    start_date=datetime.utcnow() - timedelta(hours=24)
-)
-
-# Alert on critical violations
-for v in violations:
-    if v['violation']['severity'] == 'CRITICAL':
-        send_alert(f"Critical violation: {v['violation']['type']}")
-```
-
-## Event Types Reference
-
-| Event Type | Purpose | Key Fields |
-|------------|---------|------------|
-| `llm_request` | LLM API calls | provider, model, empathy_level, pii_detected, secrets_detected |
-| `store_pattern` | Pattern storage | pattern_id, classification, pii_scrubbed, encrypted |
-| `retrieve_pattern` | Pattern access | pattern_id, classification, access_granted |
-| `security_violation` | Policy violations | violation_type, severity, blocked |
-
-## Classification Levels
-
-| Level | Use Case | Encryption | Retention |
-|-------|----------|------------|-----------|
-| `PUBLIC` | General patterns, shareable | No | 365 days |
-| `INTERNAL` | Company confidential | Optional | 180 days |
-| `SENSITIVE` | HIPAA/PCI-DSS data | Required | 90 days |
-
-## Compliance Mapping
-
-| Standard | Requirement | Implementation |
-|----------|-------------|----------------|
-| **SOC2** CC7.2 | System Monitoring | Comprehensive audit logging |
-| **HIPAA** §164.312(b) | Audit Controls | Tamper-evident logs |
-| **GDPR** Art. 30 | Records of Processing | Complete audit trail |
-
-## Troubleshooting
-
-### Logs not being created
-```python
-# Check directory permissions
-import os
-print(os.access("/var/log/empathy", os.W_OK))
-
-# Use fallback directory
-logger = AuditLogger(log_dir="./logs")
-```
-
-### Query not returning results
-```python
-# Check log file exists
-print(logger.log_path.exists())
-
-# Check query filters
-events = logger.query(limit=10)  # Get first 10
-print(f"Total events: {len(events)}")
-```
-
-### Performance issues
-```python
-# Use date ranges to limit scan
-events = logger.query(
-    start_date=datetime.utcnow() - timedelta(days=1),
-    limit=1000
-)
-
-# Enable rotation to prevent large files
-logger = AuditLogger(
-    max_file_size_mb=50,  # Smaller files
-    enable_rotation=True
-)
-```
-
-## Testing
-
-```bash
-# Run tests
-cd empathy_llm_toolkit/security
-python3 -m pytest test_audit_logger.py -v
-
-# Run example
-python3 audit_logger_example.py
-
-# View logs
-cat logs/audit.jsonl | jq '.'
-```
-
-## Security Best Practices
-
-1. **Never log actual PII or secrets** - only counts
-2. **Use restrictive permissions** - 0700 for directory, 0600 for files
-3. **Enable rotation** - prevent unlimited growth
-4. **Monitor violations** - alert on CRITICAL severity
-5. **Regular compliance reports** - daily or weekly
-6. **Retain logs appropriately** - 365 days for compliance
-7. **Back up logs** - store in secure, separate location
-
-## Support
-
-- **Documentation**: `README.md`
-- **Implementation Summary**: `IMPLEMENTATION_SUMMARY.md`
-- **Architecture**: `../../SECURE_MEMORY_ARCHITECTURE.md`
-- **Tests**: `test_audit_logger.py`
-- **Example**: `audit_logger_example.py`
-
----
-
-**Version**: 1.0.0
-**License**: Fair Source 0.9

empathy_llm_toolkit/security/README.md

@@ -1,262 +0,0 @@
-# Security Module
-
-Enterprise-grade security controls for the Empathy Framework, including secrets detection, PII scrubbing, audit logging, and data classification.
-
-## Phase 2: Secrets Detection (v1.8.0-beta) ✅
-
-### Overview
-
-The `SecretsDetector` module provides comprehensive detection of hardcoded secrets, credentials, and sensitive data in code and configuration files. It's designed for enterprise privacy integration with:
-
-- **20+ built-in patterns** for common secret types
-- **Entropy analysis** for unknown high-entropy strings
-- **Custom pattern support** for organization-specific secrets
-- **Zero secret leakage**: Returns only metadata, never actual secret values
-- **High performance**: Compiled regex patterns with early exit
-
-### Quick Start
-
-```python
-from empathy_llm_toolkit.security import SecretsDetector
-
-# Initialize detector
-detector = SecretsDetector()
-
-# Scan content for secrets
-code = """
-ANTHROPIC_API_KEY = "sk-ant-api03-abc123..."
-password = "my_secret_pass"
-"""
-
-detections = detector.detect(code)
-
-for detection in detections:
-    print(f"Found {detection.secret_type.value} at line {detection.line_number}")
-    print(f"  Severity: {detection.severity.value}")
-    print(f"  Context: {detection.context_snippet}")
-```
-
-### Supported Secret Types
-
-#### API Keys
-- Anthropic API keys (`sk-ant-...`)
-- OpenAI API keys (`sk-...`)
-- AWS Access Keys (`AKIA...`)
-- AWS Secret Keys
-- GitHub tokens (`ghp_...`, `gho_...`, etc.)
-- Slack tokens (`xox[abprs]-...`)
-- Stripe keys (`sk_live_...`, `pk_live_...`)
-- Generic API key patterns
-
-#### Passwords
-- Password assignments (`password = "..."`)
-- Basic Auth credentials (base64 encoded)
-
-#### Private Keys
-- RSA private keys
-- SSH private keys (OpenSSH format)
-- EC (Elliptic Curve) private keys
-- PGP private keys
-- TLS/SSL certificate keys
-
-#### Tokens
-- JWT tokens (`eyJ...`)
-- OAuth access tokens
-- Bearer tokens
-
-#### Database
-- Database connection URLs (PostgreSQL, MySQL, MongoDB, Redis)
-- Connection strings
-
-#### High Entropy Strings
-- Automatically detects random-looking strings (potential secrets)
-- Configurable entropy threshold (default: 4.5)
-- Minimum length requirement (default: 20 characters)
-
-### Advanced Features
-
-#### Custom Patterns
-
-Add organization-specific secret patterns:
-
-```python
-detector = SecretsDetector()
-
-# Add custom pattern
-detector.add_custom_pattern(
-    name="acme_api_key",
-    pattern=r"acme_[a-zA-Z0-9]{32}",
-    severity="high"
-)
-
-# Detect with custom pattern
-detections = detector.detect("acme_1234567890abcdefghijklmnopqrst")
-```
-
-#### Entropy Analysis
-
-Control high-entropy string detection:
-
-```python
-detector = SecretsDetector(
-    enable_entropy_analysis=True,
-    entropy_threshold=4.5,       # Shannon entropy threshold
-    min_entropy_length=20         # Minimum string length
-)
-```
-
-#### Detection Metadata
-
-The `SecretDetection` object provides rich metadata without exposing secrets:
-
-```python
-detection = detections[0]
-
-print(detection.secret_type)      # SecretType.ANTHROPIC_API_KEY
-print(detection.severity)          # Severity.HIGH
-print(detection.line_number)       # 3
-print(detection.column_start)      # 20
-print(detection.column_end)        # 95
-print(detection.context_snippet)   # "ANTHROPIC_API_KEY = [REDACTED]"
-print(detection.confidence)        # 1.0 (for pattern matches)
-print(detection.metadata)          # {"custom_pattern": "acme_api_key"}
-```
-
-#### Statistics
-
-Get detector configuration and pattern counts:
-
-```python
-stats = detector.get_statistics()
-print(stats)
-# {
-#     "builtin_patterns": 20,
-#     "custom_patterns": 2,
-#     "total_patterns": 22,
-#     "entropy_analysis_enabled": True,
-#     "entropy_threshold": 4.5,
-#     "min_entropy_length": 20
-# }
-```
-
-### Security Guarantees
-
-1. **No Secret Leakage**: The detector NEVER logs or returns actual secret values
-2. **Redaction**: Context snippets replace secrets with `[REDACTED]`
-3. **Metadata Only**: Detection objects contain only type, location, and severity
-4. **Audit Safe**: All outputs are safe to log without exposing credentials
-
-### Performance
-
-- **Compiled Patterns**: All regex patterns are pre-compiled for speed
-- **Early Exit**: Detection stops on first match for each pattern
-- **Large Files**: Tested with 10,000+ line files (completes < 5 seconds)
-- **Efficient Entropy**: Entropy analysis only runs on quoted strings
-
-### Integration Example
-
-```python
-from empathy_llm_toolkit.security import SecretsDetector
-
-def scan_file(file_path: str) -> bool:
-    """
-    Scan a file for secrets.
-
-    Returns:
-        True if no secrets found, False otherwise
-    """
-    detector = SecretsDetector()
-
-    with open(file_path, 'r') as f:
-        content = f.read()
-
-    detections = detector.detect(content)
-
-    if detections:
-        print(f"⚠️  Found {len(detections)} secrets in {file_path}")
-
-        for d in detections:
-            print(f"  - {d.secret_type.value} (Line {d.line_number})")
-            print(f"    Severity: {d.severity.value}")
-            print(f"    Context: {d.context_snippet}")
-
-        return False
-
-    print(f"✓ No secrets found in {file_path}")
-    return True
-```
-
-### Testing
-
-Comprehensive test suite with 28 tests covering:
-- All secret type detections
-- Custom pattern support
-- Entropy analysis
-- Secret redaction
-- Edge cases and error handling
-- Performance benchmarks
-
-Run tests:
-```bash
-pytest empathy_llm_toolkit/security/test_secrets_detector.py -v
-```
-
-### Compliance
-
-This module supports enterprise compliance requirements:
-
-- **OWASP Top 10 A02:2021**: Cryptographic Failures (secret detection)
-- **GDPR Article 32**: Security of processing (protect credentials)
-- **SOC2 CC6.1**: Logical access controls (prevent hardcoded secrets)
-- **HIPAA §164.312(a)(1)**: Access control (credential management)
-
-### Architecture
-
-```
-SecretsDetector
-├── Built-in Patterns (20+)
-│   ├── API Keys (Anthropic, OpenAI, AWS, GitHub, Slack, Stripe)
-│   ├── Passwords (various assignment patterns)
-│   ├── Private Keys (RSA, SSH, EC, PGP, TLS)
-│   ├── Tokens (JWT, OAuth, Bearer)
-│   └── Database (connection strings, URLs)
-├── Custom Patterns
-│   └── Organization-specific patterns
-├── Entropy Analysis
-│   ├── Shannon entropy calculation
-│   ├── Configurable threshold
-│   └── Overlap filtering
-└── Detection Output
-    ├── SecretType enum
-    ├── Severity enum (CRITICAL, HIGH, MEDIUM, LOW)
-    └── SecretDetection dataclass
-```
-
-### Future Enhancements
-
-Planned for Phase 3 (v1.8.0):
-- Integration with CI/CD pipelines (pre-commit hooks)
-- Git history scanning
-- Secret redaction/replacement utilities
-- Real-time monitoring with alerting
-- Integration with secret management systems (HashiCorp Vault, AWS Secrets Manager)
-
-### References
-
-- [OWASP Secrets Management](https://owasp.org/www-community/vulnerabilities/Use_of_hard-coded_password)
-- [GitHub Secret Scanning](https://docs.github.com/en/code-security/secret-scanning)
-- [SECURE_MEMORY_ARCHITECTURE.md](../../../SECURE_MEMORY_ARCHITECTURE.md)
-- [Enterprise Security Policy](../../../examples/claude_memory/enterprise-CLAUDE-secure.md)
-
-### Support
-
-For questions or issues:
-- File an issue on GitHub
-- Contact the Empathy Framework team
-- See main documentation at `empathy_llm_toolkit/README.md`
-
----
-
-**Author**: Empathy Framework Team
-**Version**: 1.8.0-beta
-**License**: Fair Source 0.9

empathy_llm_toolkit/security/__init__.py

@@ -1,62 +0,0 @@
-"""Security Module for Empathy Framework
-
-DEPRECATED: This module re-exports from empathy_os.memory.security
-Use `from empathy_os.memory.security import ...` instead.
-
-Provides enterprise-grade security controls including:
-- PII scrubbing (GDPR, HIPAA, SOC2 compliant)
-- Secrets detection (API keys, passwords, private keys)
-- Audit logging (tamper-evident, SOC2/HIPAA compliant)
-- Secure MemDocs integration with encryption
-
-Author: Empathy Framework Team
-Version: 2.0.0 (consolidated into empathy_os.memory)
-License: Fair Source 0.9
-"""
-
-# Re-export from consolidated memory module for backwards compatibility
-from empathy_os.memory.long_term import (
-                                         Classification,
-                                         ClassificationRules,
-                                         EncryptionManager,
-                                         PatternMetadata,
-                                         SecureMemDocsIntegration,
-                                         SecurityError,
-)
-from empathy_os.memory.security import (
-                                         AuditEvent,
-                                         AuditLogger,
-                                         PIIDetection,
-                                         PIIPattern,
-                                         PIIScrubber,
-                                         SecretDetection,
-                                         SecretsDetector,
-                                         SecretType,
-                                         SecurityViolation,
-                                         Severity,
-                                         detect_secrets,
-)
-
-__all__ = [
-    "AuditEvent",
-    # Audit Logging
-    "AuditLogger",
-    "Classification",
-    "ClassificationRules",
-    "EncryptionManager",
-    "PIIDetection",
-    "PIIPattern",
-    # PII Scrubbing
-    "PIIScrubber",
-    "PatternMetadata",
-    "SecretDetection",
-    "SecretType",
-    # Secrets Detection
-    "SecretsDetector",
-    # Secure MemDocs Integration
-    "SecureMemDocsIntegration",
-    "SecurityError",
-    "SecurityViolation",
-    "Severity",
-    "detect_secrets",
-]