Documentation & Security Enhancements

configs/security.yaml

@@ -0,0 +1,208 @@
+# Security Configuration for SAMO-DL Project
+# ===========================================
+
+# API Security Settings
+api:
+  # Rate limiting configuration
+  rate_limiting:
+    enabled: true
+    requests_per_minute: 60
+    burst_limit: 10
+    storage_backend: "redis"  # Use Redis for production, memory for development
+    redis_config:
+      host: "localhost"
+      port: 6379
+      db: 0
+      password: null  # Set via environment variable in production
+      ssl: false  # Enable in production
+
+  # CORS configuration
+  cors:
+    enabled: true
+    allowed_origins:
+      - "https://samo-project.com"
+      - "https://app.samo-project.com"
+      # WARNING: Remove the following localhost origin before deploying to production!
+      - "http://localhost:3000"  # Development only
+    allowed_methods:
+      - "GET"
+      - "POST"
+      - "OPTIONS"
+    allowed_headers:
+      - "Content-Type"
+      - "Authorization"
+      - "X-API-Key"
+    max_age: 3600
+
+  # Authentication settings
+  authentication:
+    enabled: true
+    api_key_required: true
+    jwt_enabled: false  # Future enhancement
+    session_timeout: 3600  # 1 hour
+
+  # Input validation
+  input_validation:
+    max_text_length: 1000
+    max_batch_size: 50
+    allowed_file_types: ["txt", "json"]
+    max_file_size_mb: 10
+
+# Security Headers
+security_headers:
+  enabled: true
+  headers:
+    X-Content-Type-Options: "nosniff"
+    X-Frame-Options: "DENY"
+    X-XSS-Protection: "1; mode=block"
+    Strict-Transport-Security: "max-age=31536000; includeSubDomains"
+    Content-Security-Policy: "default-src 'self'; script-src 'self'; style-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'"
+    Referrer-Policy: "strict-origin-when-cross-origin"
+    Permissions-Policy: "geolocation=(), microphone=(), camera=()"
+
+# Logging and Monitoring
+logging:
+  security_events:
+    enabled: true
+    level: "INFO"
+    format: "json"
+    include_pii: false
+
+  # Request logging
+  requests:
+    enabled: true
+    log_sensitive_data: false
+    mask_fields:
+      - "password"
+      - "api_key"
+      - "token"
+      - "secret"
+
+  # Error logging
+  errors:
+    enabled: true
+    log_to_file: true
+    log_to_console: false
+    include_stack_traces:
+      production: false   # Production security
+      development: true   # Enable stack traces for debugging
+      testing: true       # Enable stack traces for test runs
+
+# Environment Security
+environment:
+  # Required environment variables
+  required_vars:
+    - "DATABASE_URL"
+    - "SECRET_KEY"
+    - "API_KEY"
+    - "ENVIRONMENT"
+
+  # Sensitive variables (will be masked in logs)
+  sensitive_vars:
+    - "DATABASE_URL"
+    - "SECRET_KEY"
+    - "API_KEY"
+    - "OPENAI_API_KEY"
+    - "GOOGLE_CLOUD_CREDENTIALS"
+
+  # Environment-specific settings
+  production:
+    debug: false
+    log_level: "WARNING"
+    enable_health_checks: true
+
+  development:
+    debug: true
+    log_level: "DEBUG"
+    enable_health_checks: true
+
+  testing:
+    debug: false
+    log_level: "INFO"
+    enable_health_checks: false
+
+# Dependency Security
+dependencies:
+  # Security scanning
+  scanning:
+    enabled: true
+    tools:
+      - "safety"
+      - "bandit"
+      - "pip-audit"
+    auto_fix: false
+    fail_on_critical: true
+    fail_on_high: true  # Fail on high-severity vulnerabilities for security
+
+  # Update policy
+  updates:
+    auto_update: false
+    security_updates_only: true
+    test_after_update: true
+
+# Model Security
+model:
+  # Model loading security
+  loading:
+    validate_model_files: true
+    check_model_signatures: true
+    max_model_size_mb: 1000
+
+  # Inference security
+  inference:
+    max_input_length: 1000
+    max_batch_size: 50
+    timeout_seconds: 30
+    memory_limit_mb: 2048
+
+  # Model access control
+  access_control:
+    require_authentication: true
+    rate_limit_per_user: 100  # requests per hour
+    log_all_predictions: false
+
+# Database Security
+database:
+  # Connection security
+  connection:
+    use_ssl: true
+    verify_ssl: true
+    connection_timeout: 30
+    max_connections: 20
+
+  # Query security
+  queries:
+    max_query_time: 30  # seconds
+    log_slow_queries: true
+    prevent_sql_injection: true
+
+  # Data protection
+  data_protection:
+    encrypt_sensitive_data: true
+    mask_pii_in_logs: true
+    backup_encryption: true
+
+# Deployment Security
+deployment:
+  # Container security
+  container:
+    run_as_non_root: true
+    read_only_filesystem: true
+    drop_capabilities: true
+    security_context:
+      run_as_user: 1000
+      run_as_group: 1000
+      fs_group: 1000
+
+  # Network security
+  network:
+    use_https: true
+    enable_tls_1_3: true
+    disable_tls_1_0_1_1: true
+    certificate_validation: true
+
+  # Secrets management
+  secrets:
+    use_external_secrets: true
+    rotate_secrets: true
+    secret_rotation_days: 90 

deployment/cloud-run/requirements.txt

@@ -1,6 +1,6 @@
-flask==2.3.3
-torch==2.7.1
-transformers==4.52.1
-gunicorn==23.0.0
-numpy==1.24.3
-scikit-learn==1.5.0 
+flask>=3.1.1,<4.0.0
+torch>=2.7.1,<2.8.0
+transformers>=4.55.0,<5.0.0
+gunicorn>=23.0.0,<24.0.0
+numpy>=2.3.2,<3.0.0
+scikit-learn>=1.5.0,<2.0.0

deployment/requirements.txt

@@ -1,7 +1,7 @@
-transformers==4.52.1
-torch==2.7.1
-scikit-learn==1.5.0
-numpy==1.24.3
-pandas==2.0.3
-flask==2.3.3
-requests==2.32.4
+transformers>=4.55.0,<5.0.0
+torch>=2.7.1,<2.8.0
+scikit-learn>=1.5.0,<2.0.0
+numpy>=2.3.2,<3.0.0
+pandas>=2.0.0,<3.0.0
+flask>=3.1.1,<4.0.0
+requests>=2.32.4,<3.0.0

docs/API_DOCUMENTATION.md

@@ -38,7 +38,7 @@ Check the health status of the API and get basic metrics.
 ```json
 {
   "status": "healthy",
-  "model_loaded": true,
+  "model_status": "loaded",
   "model_version": "2.0",
   "emotions": ["anxious", "calm", "content", "excited", "frustrated", "grateful", "happy", "hopeful", "overwhelmed", "proud", "sad", "tired"],
   "uptime_seconds": 1234.5,

docs/USER_GUIDE.md

@@ -344,7 +344,7 @@ curl http://localhost:8000/health
 ```json
 {
   "status": "healthy",
-  "model_loaded": true,
+  "model_status": "loaded",
   "model_version": "2.0",
   "uptime_seconds": 1234.5,
   "metrics": {