attune-ai 2.0.0__py3-none-any.whl

attune_llm/security/QUICK_REFERENCE.md

@@ -0,0 +1,316 @@
+# Audit Logger Quick Reference
+
+## Import
+
+```python
+from attune_llm.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 attune_llm 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 attune_llm/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

attune_llm/security/README.md

@@ -0,0 +1,262 @@
+# 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 attune_llm.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 attune_llm.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 attune_llm/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 `attune_llm/README.md`
+
+---
+
+**Author**: Empathy Framework Team
+**Version**: 1.8.0-beta
+**License**: Fair Source 0.9

attune_llm/security/__init__.py

@@ -0,0 +1,62 @@
+"""Security Module for Empathy Framework
+
+DEPRECATED: This module re-exports from attune.memory.security
+Use `from attune.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 attune.memory)
+License: Fair Source 0.9
+"""
+
+# Re-export from consolidated memory module for backwards compatibility
+from attune.memory.long_term import (
+                                         Classification,
+                                         ClassificationRules,
+                                         EncryptionManager,
+                                         PatternMetadata,
+                                         SecureMemDocsIntegration,
+                                         SecurityError,
+)
+from attune.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",
+]