Security Best Practices

INFO

This documentation covers security features available in Cellar API v3.2.0+

Cellar is designed with security as a priority. This page covers security features, best practices, and deployment considerations.

File Upload Security

When using the v2 API for file uploads, Cellar implements several security measures to protect against common attack vectors.

File Size Limits

The APP_MAX_FILE_SIZE_MB configuration setting controls the maximum file size that can be uploaded. The default of 8 MB is designed to:

• Support common use cases (QR codes, screenshots, PDFs, credentials, configuration files)
• Remain compatible with AWS Lambda deployments (API Gateway has a 10 MB payload limit)
• Prevent denial-of-service attacks via large file uploads
• Balance memory usage during encryption (files are buffered in memory)

Files that fit within 8 MB:

• QR codes and barcodes (< 1 MB)
• Screenshots and compressed images (2-5 MB)
• PDFs with text and images (1-6 MB)
• Private keys, certificates, and credential files (< 1 MB)
• Source code archives and configuration files (1-5 MB)
• Short audio recordings (1-2 MB)

Increasing the limit:

For Docker or traditional server deployments, you can increase the limit by setting a higher value. Note that Lambda deployments are constrained by the API Gateway 10 MB limit.

APP_MAX_FILE_SIZE_MB=20  # Increase to 20 MB for Docker deployments

Automatic Security Protections

Cellar automatically applies the following security measures to file uploads and downloads:

Input Validation:

• Empty files (0 bytes) are rejected
• File size is validated before encryption
• Malformed multipart requests are rejected

Download Protection:

Files are served with security headers that prevent common web vulnerabilities:

• Content-Type: application/octet-stream - Forces browser to treat all files as downloads
• X-Content-Type-Options: nosniff - Prevents MIME type sniffing attacks
• Content-Security-Policy: default-src 'none' - Blocks any script execution
• X-Frame-Options: DENY - Prevents clickjacking attacks
• Cache-Control: no-store, no-cache, must-revalidate - Prevents caching of sensitive files

File Type Support:

All file types are supported without restrictions. This provides maximum flexibility for users to share any type of secret. Recipients are responsible for safely handling downloaded files. Cellar focuses on secure transmission and storage, not content filtering.

Deployment Best Practices

When deploying Cellar in production, consider these security recommendations:

1. Use HTTPS

Always deploy Cellar behind HTTPS in production. While Cellar encrypts secrets at rest using your chosen cryptography engine, HTTPS protects secrets in transit between clients and the API.

Configure your reverse proxy or load balancer to:

• Terminate TLS with valid certificates
• Force HTTPS redirects for HTTP requests
• Use strong cipher suites (TLS 1.2+)

2. Configure Appropriate File Size Limits

Set APP_MAX_FILE_SIZE_MB based on your:

• Use case: What types of files will users share?
• Deployment environment: Are you using Lambda (10 MB limit) or Docker (flexible)?
• Available memory: Files are buffered in memory during encryption
• Redis capacity: Encrypted files are stored in Redis

3. Monitor Storage Usage

Cellar stores all data in Redis. Monitor your Redis instance to prevent memory exhaustion:

• Track total memory usage
• Set up alerts for approaching memory limits
• Configure Redis maxmemory policy appropriately
• Consider Redis persistence settings based on your durability requirements

4. Implement Rate Limiting

While Cellar implements file size limits, consider adding rate limiting at your reverse proxy or API gateway:

• Limit requests per IP address
• Limit file uploads per time period
• Protect against brute force access attempts
• Prevent automated scanning of secret IDs

Popular tools for rate limiting:

• nginx limit_req module
• AWS API Gateway throttling
• Cloudflare rate limiting
• Traefik rate limiting middleware

5. Secure Your Cryptography Engine

For HashiCorp Vault:

• Use the principle of least privilege for AppRole permissions
• Rotate Vault tokens regularly
• Enable Vault audit logging
• Use TLS for Vault connections

For AWS KMS:

• Use IAM roles with minimal required permissions
• Enable CloudTrail logging for KMS operations
• Use KMS key policies to restrict access
• Consider using different keys per environment

6. Secure Your Datastore

For Redis:

• Enable password authentication (DATASTORE_REDIS_PASSWORD)
• Use TLS for Redis connections in production
• Restrict network access to Redis (firewall rules)
• Consider Redis ACLs for fine-grained access control
• Keep Redis updated with security patches

7. Educate Users

Inform your users about:

• File handling: Downloaded files should be scanned and verified
• Expiration: Set appropriate expiration times for sensitivity level
• Access limits: Use access limits to prevent unauthorized sharing
• Link sharing: Secret links should be shared through secure channels (not email)

Security Considerations

What Cellar Protects

Cellar provides:

• Encryption at rest through your chosen cryptography engine (Vault or AWS KMS)
• Automatic deletion based on expiration time or access limits
• Ephemeral storage with no permanent file system persistence
• Input validation to prevent malformed or malicious uploads
• Secure headers to prevent XSS and content sniffing attacks

What Cellar Does Not Protect

Users and administrators are responsible for:

• Encryption in transit: Use HTTPS to protect data between clients and the API
• Content scanning: Cellar does not scan files for viruses or malware
• Access control: Anyone with a secret link can access it (no authentication)
• Link distribution: Ensure secret links are shared through secure channels
• Safe file handling: Recipients must verify and safely handle downloaded files

Threat Model

Cellar is designed to protect against:

• Data breaches: Secrets are encrypted at rest and automatically deleted
• Unauthorized access after expiration: Secrets are immediately and permanently deleted
• Over-sharing: Access limits prevent unlimited distribution
• XSS attacks: Security headers prevent script execution
• DoS attacks: File size limits prevent resource exhaustion

Cellar does not protect against:

• Compromised secret links: Anyone with the link can access the secret
• Man-in-the-middle attacks: Use HTTPS to protect against this
• Malicious file content: Cellar does not inspect or filter file contents
• Infrastructure vulnerabilities: Keep your deployment environment secure and updated

Compliance and Auditing

Logging

Cellar logs all API operations including:

• Secret creation (with metadata but not content)
• Secret access attempts (successful and failed)
• Secret deletion (manual and automatic)
• Configuration changes

Configure LOGGING_LEVEL and LOGGING_FORMAT to meet your auditing requirements.

Data Retention

Cellar enforces data retention through:

• Expiration times: Secrets are automatically deleted after expiration
• Access limits: Secrets are deleted after reaching access limit
• No backups: Deleted secrets cannot be recovered

Compliance Considerations

When deploying Cellar for compliance requirements:

• Document your encryption key management procedures
• Maintain audit logs of all secret operations
• Implement appropriate access controls at the infrastructure level
• Consider data residency requirements when choosing cloud regions
• Review your organization’s data retention policies

Incident Response

If you suspect a security issue:

1. For secret compromise: Secrets automatically expire and can be manually deleted
2. For infrastructure compromise: Rotate all cryptography credentials immediately
3. For vulnerability reports: Report issues to the Cellar project on GitLab
4. For deployment issues: Review logs and configuration for misconfigurations

Additional Resources

• Configuration Reference - Complete configuration options
• Deployment Guide - Deployment instructions
• Cellar API Repository - Source code and issue tracking