talk2me/SECURITY.md

Security Configuration Guide

This document outlines security best practices for deploying Talk2Me.

Secrets Management

Talk2Me includes a comprehensive secrets management system with encryption, rotation, and audit logging.

Quick Start

# Initialize secrets management
python manage_secrets.py init

# Set a secret
python manage_secrets.py set TTS_API_KEY

# List secrets
python manage_secrets.py list

# Rotate secrets
python manage_secrets.py rotate ADMIN_TOKEN

See SECRETS_MANAGEMENT.md for detailed documentation.

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.