talk2me/SECURITY.md

Security Configuration Guide

This document outlines security best practices for deploying Talk2Me.

Environment Variables

NEVER commit sensitive information like API keys, passwords, or secrets to version control.

Required Security Configuration

1. TTS_API_KEY

   • Required for TTS server authentication
   • Set via environment variable: export TTS_API_KEY="your-api-key"
   • Or use a .env file (see .env.example)

2. SECRET_KEY

   • Required for Flask session security
   • Generate a secure key: python -c "import secrets; print(secrets.token_hex(32))"
   • Set via: export SECRET_KEY="your-generated-key"

3. ADMIN_TOKEN

   • Required for admin endpoints
   • Generate a secure token: python -c "import secrets; print(secrets.token_urlsafe(32))"
   • Set via: export ADMIN_TOKEN="your-admin-token"

Using a .env File (Recommended)

1. Copy the example file:

   cp .env.example .env
   

2. Edit .env with your actual values:

   nano .env  # or your preferred editor
   

3. Load environment variables:

   # Using python-dotenv (add to requirements.txt)
   pip install python-dotenv
   
   # Or source manually
   source .env
   

Python-dotenv Integration

To automatically load .env files, add this to the top of app.py:

from dotenv import load_dotenv
load_dotenv()  # Load .env file if it exists

Production Deployment

For production deployments:

1. Use a secrets management service:

   • AWS Secrets Manager
   • HashiCorp Vault
   • Azure Key Vault
   • Google Secret Manager

2. Set environment variables securely:

   • Use your platform's environment configuration
   • Never expose secrets in logs or error messages
   • Rotate keys regularly

3. Additional security measures:

   • Use HTTPS only
   • Enable CORS restrictions
   • Implement rate limiting
   • Monitor for suspicious activity

Docker Deployment

When using Docker:

# Use build arguments for non-sensitive config
ARG TTS_SERVER_URL=http://localhost:5050/v1/audio/speech

# Use runtime environment for secrets
ENV TTS_API_KEY=""

Run with:

docker run -e TTS_API_KEY="your-key" -e SECRET_KEY="your-secret" talk2me

Kubernetes Deployment

Use Kubernetes secrets:

apiVersion: v1
kind: Secret
metadata:
  name: talk2me-secrets
type: Opaque
stringData:
  tts-api-key: "your-api-key"
  flask-secret-key: "your-secret-key"
  admin-token: "your-admin-token"

Rate Limiting

Talk2Me implements comprehensive rate limiting to prevent abuse:

1. Per-Endpoint Limits:

   • Transcription: 10/min, 100/hour
   • Translation: 20/min, 300/hour
   • TTS: 15/min, 200/hour

2. Global Limits:

   • 1,000 requests/minute total
   • 50 concurrent requests maximum

3. Automatic Protection:

   • IP blocking for excessive requests
   • Request size validation
   • Burst control

See RATE_LIMITING.md for configuration details.

Security Checklist

• All API keys removed from source code
• Environment variables configured
• .env file added to .gitignore
• Secrets rotated after any potential exposure
• HTTPS enabled in production
• CORS properly configured
• Rate limiting enabled and configured
• Admin endpoints protected with authentication
• Error messages don't expose sensitive info
• Logs sanitized of sensitive data
• Request size limits enforced
• IP blocking configured for abuse prevention

Reporting Security Issues

If you discover a security vulnerability, please report it to:

• Create a private security advisory on GitHub
• Or email: security@yourdomain.com

Do not create public issues for security vulnerabilities.