TestAble uses Fernet symmetric encryption to protect sensitive data including:

• Environment variable secrets
• GitHub access tokens
• API keys

⚠️ CRITICAL: You MUST set ENV_VAR_ENCRYPTION_KEY before starting the application. Without it, the application will fail to start.

Run this command to generate a new encryption key:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

This will output something like:

vtqWB5eoJvR8Xn0KqJ8xYw4YvN9Hn8FGLw1p8KqJxQM=

Development (.env file):

ENV_VAR_ENCRYPTION_KEY=vtqWB5eoJvR8Xn0KqJ8xYw4YvN9Hn8FGLw1p8KqJxQM=

Production (Docker/Kubernetes):

# docker-compose.yml
environment:
  - ENV_VAR_ENCRYPTION_KEY=vtqWB5eoJvR8Xn0KqJ8xYw4YvN9Hn8FGLw1p8KqJxQM=

# Kubernetes Secret
apiVersion: v1
kind: Secret
metadata:
  name: testable-secrets
type: Opaque
data:
  encryption-key: dnRxV0I1ZW9KdlI4WG4wS3FKOHhZdzRZdk45SG44RkdMdzFwOEtxSnhRTT0=

AWS/Cloud Providers: Use your cloud provider's secret management service:

• AWS: AWS Secrets Manager or Parameter Store
• GCP: Secret Manager
• Azure: Key Vault

1. Never commit the encryption key to version control

   • Add .env to .gitignore (already done)
   • Never hardcode keys in source code

2. Key rotation: If you need to rotate the key:

   • Generate a new key
   • Decrypt all existing secrets with the old key
   • Re-encrypt with the new key
   • Update the environment variable

3. Backup the key: Store the key in a secure location. If you lose it, all encrypted data becomes unrecoverable.

4. Key persistence: The same key must be used across all:

   • Application restarts
   • Multiple instances (if running in a cluster)
   • Development/staging/production environments (use different keys per environment)

The following sensitive data is automatically encrypted before storage:

1. Environment Variables marked as is_secret=true

   • API keys
   • Database passwords
   • OAuth secrets
   • Any variable containing: password, secret, key, token, api

2. GitHub Access Tokens

   • Personal access tokens
   • GitHub App installation tokens

3. Integration API Keys

   • Slack webhooks
   • Notion API tokens
   • Other third-party service credentials

Solution: Generate and set the encryption key as described above.

Possible causes:

• Encryption key was changed after secrets were encrypted
• Different key used in different environments
• Database was copied from another environment

Solution:

• Restore the original encryption key, OR
• Delete and re-enter all encrypted secrets

Check:

1. ENV_VAR_ENCRYPTION_KEY is set in environment
2. Key is valid (44 characters, base64-encoded)
3. Key is accessible to the application process

Before deploying to production:

• Generate a unique encryption key for production
• Store key in secure secret management service
• Configure key injection into application containers
• Verify key is not logged or exposed in error messages
• Test encryption/decryption functionality
• Document key backup and recovery procedures
• Set up monitoring for encryption failures
• Plan key rotation schedule (recommended: annually)

For security issues or concerns, please open a private security advisory on GitHub.