LifeRPG_v2.0/docs/SECURITY.md

LifeRPG Security Guide

This document outlines the security measures implemented in LifeRPG, vulnerability reporting procedures, and best practices for secure deployment.

Table of Contents

1. Security Model
2. Authentication & Authorization
3. Data Protection
4. API Security
5. Dependency Security
6. Plugin Security
7. Vulnerability Reporting
8. Security Testing
9. Deployment Security
10. Compliance & Privacy

Security Model

LifeRPG implements a defense-in-depth security model with multiple layers of protection:

Security Principles

• Zero Trust: All requests are authenticated and authorized regardless of source
• Principle of Least Privilege: Components only have access to what they need
• Defense in Depth: Multiple security controls at different layers
• Secure by Default: Security features enabled by default
• Privacy by Design: Data minimization and protection built-in

Threat Model

Key threats addressed:

1. Unauthorized Access: Prevented through robust authentication and authorization
2. Data Exposure: Mitigated through encryption and access controls
3. Injection Attacks: Prevented through input validation and parameterized queries
4. Cross-Site Scripting (XSS): Mitigated through content security policy and output encoding
5. Cross-Site Request Forgery (CSRF): Prevented through anti-CSRF tokens
6. Denial of Service: Mitigated through rate limiting and resource controls
7. Supply Chain Attacks: Addressed through dependency scanning and SBOM
8. Plugin Vulnerabilities: Contained through sandboxing and permission controls

Authentication & Authorization

Authentication Methods

LifeRPG supports multiple secure authentication methods:

1. OAuth2/OIDC: Integration with identity providers using PKCE

   • Google, GitHub, Microsoft, etc.
   • Authorization code flow with PKCE for SPAs and mobile
   • Optional audience and issuer validation
   • RP-initiated logout support

2. Two-Factor Authentication (2FA)

   • TOTP (Time-based One-Time Password)
   • Recovery codes for backup access
   • Session management with primary/alt sessions

3. API Tokens

   • Fine-grained permissions
   • Expiring tokens with rotation
   • Token revocation support

Token Security

• JWT Security: Short-lived tokens with proper signing
• Secure Storage: Tokens stored securely (HTTPOnly, Secure cookies)
• Token Validation: Thorough validation of token claims
• Refresh Token Rotation: One-time use refresh tokens

Authorization

• Role-Based Access Control (RBAC): User roles with specific permissions
• Attribute-Based Access Control (ABAC): Fine-grained permissions based on attributes
• Resource Ownership: Users can only access their own data
• Permission Checks: Consistent permission validation throughout the application

Code example:

# API endpoint with permission check
@router.get("/habits/{habit_id}", response_model=HabitRead)
async def get_habit(
    habit_id: int,
    current_user: User = Depends(get_current_user),
    db: AsyncSession = Depends(get_db),
):
    habit = await habit_service.get_habit(db, habit_id)
    if not habit:
        raise HTTPException(status_code=404, detail="Habit not found")
    
    # Permission check
    if habit.user_id != current_user.id and not current_user.has_role("admin"):
        raise HTTPException(status_code=403, detail="Not authorized")
    
    return habit

Data Protection

Data at Rest

• Database Encryption: Sensitive fields encrypted in database
• Secure Storage: Secure storage options for sensitive user data
• Encryption Keys: Proper key management and rotation

Data in Transit

• TLS/HTTPS: All communications encrypted with TLS 1.2+
• HSTS: HTTP Strict Transport Security enabled
• Certificate Management: Proper certificate validation and pinning

Data Classification

Data is classified into sensitivity levels with appropriate controls:

1. Public Data: Non-sensitive, publicly accessible information
2. User Data: Personal data requiring authentication
3. Sensitive Data: Requiring additional protection (e.g., OAuth tokens)
4. System Data: Configuration and security settings

Data Minimization

• Purpose Limitation: Data collected only for specific purposes
• Storage Limitation: Data retained only as long as necessary
• Data Anonymization: Personal data anonymized where possible

API Security

Input Validation

• Schema Validation: All inputs validated against Pydantic schemas
• Type Checking: Strong typing throughout the application
• Sanitization: Input sanitization for special contexts (e.g., HTML)

# Input validation with Pydantic
class HabitCreate(BaseModel):
    title: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = Field(None, max_length=1000)
    frequency: str = Field(..., pattern="^(daily|weekly|monthly|custom)$")
    xp_reward: int = Field(..., ge=1, le=100)
    
    @validator('title')
    def title_must_not_contain_html(cls, v):
        if re.search(r'<[^>]*>', v):
            raise ValueError('Title must not contain HTML tags')
        return v

Request Limiting

• Rate Limiting: Per-user and per-IP rate limits
• Concurrent Request Limiting: Prevent resource exhaustion
• Request Size Limiting: Maximum body size enforced

# Rate limiting middleware
app.add_middleware(
    RateLimitMiddleware,
    rate=30,  # requests
    period=60,  # seconds
    storage=redis_storage,
    exclude_endpoints=["/health", "/metrics"],
)

Security Headers

• Content-Security-Policy (CSP): Restricts sources of executable scripts
• X-Content-Type-Options: Prevents MIME type sniffing
• X-Frame-Options: Prevents clickjacking
• Referrer-Policy: Controls referrer information
• Permissions-Policy: Restricts browser features

# Security headers middleware
app.add_middleware(
    SecurityHeadersMiddleware,
    csp="default-src 'self'; script-src 'self'; connect-src 'self';",
    hsts=True,
    frame_options="DENY",
    content_type_options=True,
    referrer_policy="same-origin",
    permissions_policy="camera=(), microphone=(), geolocation=()",
)

CSRF Protection

• Double Submit Cookie: CSRF token validation
• Same-Site Cookies: Cookies with SameSite=Lax/Strict
• Origin Checking: Validate Origin/Referer headers

Dependency Security

Software Bill of Materials (SBOM)

LifeRPG maintains a comprehensive SBOM that:

• Lists all direct and transitive dependencies
• Includes version information and licenses
• Is updated with each release
• Is available in both CycloneDX and SPDX formats

Dependency Scanning

• Automated Scanning: Dependencies scanned for vulnerabilities
• Regular Updates: Dependencies kept up-to-date
• Version Pinning: Explicit version pinning for all dependencies
• License Compliance: Dependency licenses tracked and reviewed

Tools used:

• GitHub Dependabot
• OWASP Dependency Check
• Snyk

Supply Chain Security

• Verified Sources: Dependencies from verified sources
• Integrity Verification: Package hashes verified
• Reproducible Builds: Deterministic build process
• Secure CI/CD: Pipeline security with proper secret management

Plugin Security

Sandbox Containment

Plugins run in a WebAssembly sandbox with:

• Memory Isolation: Protected memory space
• CPU Limits: Execution time and resource limits
• I/O Restrictions: Limited access to system resources
• Network Controls: Restricted network access

Permission System

Plugins operate under a strict permission model:

• Explicit Permissions: Must request specific permissions
• User Approval: Permissions displayed and approved by users
• Runtime Enforcement: Permissions enforced during execution
• Revocation: Permissions can be revoked at any time

Plugin Vetting

• Automated Analysis: Static and dynamic analysis of plugins
• Code Review: Optional review process for marketplace plugins
• Reputation System: User ratings and reviews
• Revocation Mechanism: Ability to disable malicious plugins

Vulnerability Reporting

Responsible Disclosure

We encourage responsible disclosure of security vulnerabilities:

1. Reporting Channel: Email security@liferpg.example.com or use our HackerOne page
2. Encryption: Use our PGP key for sensitive reports
3. Response Timeline: Initial response within 48 hours
4. Disclosure Policy: Coordinated disclosure after fixes
5. Recognition: Hall of Fame for security researchers

Bug Bounty Program

LifeRPG offers a bug bounty program with:

• Scope: Defined in-scope and out-of-scope targets
• Rewards: Based on severity and impact
• Rules of Engagement: Clear testing guidelines
• Safe Harbor: Protection for good-faith security research

Security Testing

Automated Testing

• SAST (Static Application Security Testing): Analyzes code for security issues
  • Tools: Bandit, ESLint security plugins, CodeQL
• DAST (Dynamic Application Security Testing): Tests running application
  • Tools: OWASP ZAP, Burp Suite
• Dependency Scanning: Checks dependencies for vulnerabilities
  • Tools: Dependabot, Snyk, OWASP Dependency Check
• Container Scanning: Analyzes container images
  • Tools: Trivy, Clair

Manual Testing

• Penetration Testing: Regular penetration tests
• Code Reviews: Security-focused code reviews
• Threat Modeling: Systematic analysis of threats
• Red Team Exercises: Simulated attacks to test defenses

CI/CD Integration

Security testing is integrated into CI/CD pipeline:

# Example GitHub Actions workflow
name: Security Checks

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run SAST scan
        uses: github/codeql-action/analyze@v2
        
      - name: Run dependency scan
        uses: snyk/actions/python@master
        
      - name: Run container scan
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: 'liferpg/api:latest'
          
      - name: Run DAST scan
        uses: zaproxy/action-full-scan@v0.3.0
        with:
          target: 'http://localhost:8080'

Deployment Security

Secure Configuration

• Environment Variables: Sensitive configuration in environment variables
• Secrets Management: Secrets stored in vault systems
• Configuration Validation: Validation of security settings
• Default Security: Secure defaults with explicit opt-out

Infrastructure Security

• Container Security: Minimal base images, non-root users
• Network Security: Network segmentation and firewalls
• Cloud Security: Follow cloud provider security best practices
• Access Controls: Least privilege for infrastructure access

Monitoring & Logging

• Security Monitoring: Detection of unusual patterns
• Centralized Logging: Security-relevant events logged
• Audit Trail: Actions tracked for accountability
• Alerting: Automatic alerts for security events

Incident Response

• Response Plan: Documented incident response procedure
• Roles & Responsibilities: Clear ownership during incidents
• Communication Plan: Internal and external communication
• Post-Incident Analysis: Learning from security incidents

Compliance & Privacy

Data Protection

• GDPR Compliance: European data protection regulations
• CCPA Compliance: California Consumer Privacy Act
• Data Subject Rights: Access, rectification, erasure
• Data Processing Records: Documentation of data processing

Privacy Features

• Privacy Policy: Clear and comprehensive policy
• Data Export: User data export functionality
• Data Deletion: Complete account deletion option
• Cookie Controls: Minimal and controllable cookie usage

Audit & Compliance

• Security Audits: Regular security assessments
• Compliance Checks: Verification of regulatory compliance
• Documentation: Comprehensive security documentation
• Training: Security awareness training for contributors

---

Security Checklist

Use this checklist to verify LifeRPG's security implementation:

Authentication & Authorization

• OAuth2/OIDC properly implemented with PKCE
• 2FA with TOTP available
• JWT tokens properly signed and validated
• Role-based access control implemented
• Resource ownership checks in place

Data Protection

• Sensitive data encrypted in database
• TLS 1.2+ enforced for all connections
• HTTPS-only cookies
• Clear data retention policies

API Security

• Input validation on all endpoints
• Rate limiting implemented
• Security headers configured
• CSRF protection in place
• Request size limits enforced

Dependency Security

• SBOM generated and maintained
• Dependency scanning in CI/CD
• Regular dependency updates
• License compliance verified

Plugin Security

• WASM sandbox implemented
• Plugin permissions system working
• Resource limits enforced
• Plugin vetting process documented

Deployment

• Secure configuration guide available
• Container security measures implemented
• Monitoring and logging in place
• Incident response plan documented

Compliance

• Privacy policy up-to-date
• Data subject rights implemented
• Compliance documentation available
• Security training materials created