campaign_connector/docs/security/security-setup.md

Security Setup Guide

This guide covers security configuration for SMS Campaign Manager, including API key generation, Docker security, and best practices.

Prerequisites

Before configuring security:

• Docker and Docker Compose installed
• Access to Android device (Termux)
• .env file created from .env.example

Quick Setup

Step 1: Generate API Keys

Run the key generation script:

cd /mnt/storagessd1tb/campaign_connector
python3 src/core/auth.py

This generates cryptographically secure keys for:

• ADMIN_API_KEY - Full system access
• USER_API_KEY - Regular operations
• TERMUX_API_KEY - Android device communication
• SECRET_KEY - Session encryption

Copy the generated keys immediately as they are only shown once.

Step 2: Configure Environment

Back up and edit your .env file:

cp .env .env.backup
nano .env

Add the security configuration:

# API Keys (generated above)
ADMIN_API_KEY=<your-admin-key>
USER_API_KEY=<your-user-key>
TERMUX_API_KEY=<your-termux-key>
SECRET_KEY=<your-secret-key>
TERMUX_API_SECRET=<same-as-termux-api-key>

# User Management
ADMIN_USERNAME=admin
ADMIN_PASSWORD=YourSecurePassword123!

Secure the file:

chmod 600 .env

Step 3: Configure Android Device

SSH into your Android device:

ssh -p 8022 android-dev@YOUR_ANDROID_IP

Option A - Use the automated setup script:

cd ~/projects/sms-campaign-manager
./android/setup-api-key.sh

Option B - Set manually:

echo 'export SMS_API_SECRET="<your-termux-api-key>"' >> ~/.bashrc
source ~/.bashrc

Step 4: Restart Services

On Ubuntu:

docker compose down
docker compose up -d --build

On Android (Termux):

pkill -f termux-sms-api-server.py
python ~/projects/sms-campaign-manager/android/termux-sms-api-server.py

Step 5: Verify Security

Test authentication:

# Should fail (no API key)
curl http://localhost:5000/api/campaign/list

# Should succeed (with API key)
curl -H "X-API-Key: YOUR_USER_API_KEY" http://localhost:5000/api/campaign/list

Verify Docker security:

docker inspect sms-campaign-manager | grep -E "Privileged|NetworkMode"
# Expected: "Privileged": false, "NetworkMode": "bridge" or "default"

Docker Security Configuration

The application runs with these security measures:

Container Isolation

The container runs without privileged mode:

services:
  sms-campaign:
    # Runs with standard permissions
    ports:
      - "5000:5000"
      - "5037:5037"

Network Isolation

Uses Docker bridge networking instead of host mode, providing proper network isolation while allowing necessary port access.

Secure Volumes

Only required directories are mounted:

volumes:
  - ./data:/app/data
  - ./uploads:/app/uploads
  - ./logs:/app/logs

API Key Roles

Admin API Key

Full system access:

• All user permissions
• Database reset operations
• System configuration changes

Use for administrative tasks and automation scripts requiring full access.

User API Key

Regular application access:

• Create and manage campaigns
• Send SMS messages
• Upload CSV files
• View analytics

Use for web dashboard access and team member API calls.

Termux API Key

Android device communication:

• Send SMS via Termux API
• Query SMS history
• Device status endpoints

Used internally for server-to-device communication.

Using API Keys

HTTP Headers

# X-API-Key header
curl -H "X-API-Key: YOUR_KEY" http://localhost:5000/api/endpoint

# Bearer token
curl -H "Authorization: Bearer YOUR_KEY" http://localhost:5000/api/endpoint

Web Dashboard

The web dashboard uses session-based authentication. Log in with username/password at /login. API keys are not needed for browser access after login.

Best Practices

Required

• Generate unique, random API keys
• Store keys only in .env file
• Set file permissions: chmod 600 .env
• Use HTTPS in production (Tailscale provides this)
• Never commit .env to version control

Recommended

• Rotate API keys every 90 days
• Use different keys per environment
• Monitor logs for failed authentication
• Keep Docker and dependencies updated
• Back up .env securely (encrypted)

Key Rotation

To rotate keys:

1. Generate new keys: python3 src/core/auth.py
2. Update .env on server and Android device
3. Restart all services
4. Update external scripts using old keys
5. Test all functionality
6. Securely delete old keys

Git Security

Remove secrets from version control:

# Remove .env from git tracking
git rm --cached .env
git commit -m "Remove .env from version control"

# Verify .env is in .gitignore
grep "^.env$" .gitignore

Troubleshooting

Authentication Required Error

Missing or invalid API key:

# Check if key is loaded in container
docker compose exec sms-campaign env | grep API_KEY

# Test with correct key
curl -H "X-API-Key: YOUR_KEY" http://localhost:5000/api/campaign/list

Invalid API Key Error

Key mismatch or formatting issue:

# Verify .env format (no spaces around =)
cat .env | grep API_KEY

# Restart to reload environment
docker compose restart

Android Server Won't Start

Missing SMS_API_SECRET:

# Check if set
echo $SMS_API_SECRET

# If empty, run setup
./android/setup-api-key.sh

Container Security Check

Verify Docker configuration:

# Should show "Privileged": false
docker inspect sms-campaign-manager | grep Privileged

# Should NOT show "NetworkMode": "host"
docker inspect sms-campaign-manager | grep NetworkMode

Environment Variables

Variable	Description	Required
ADMIN_API_KEY	Admin access key	Yes
USER_API_KEY	User access key	Yes
TERMUX_API_KEY	Android communication key	Yes
SECRET_KEY	Session encryption key	Yes
TERMUX_API_SECRET	Android server auth	Yes
ADMIN_USERNAME	Initial admin username	Yes
ADMIN_PASSWORD	Initial admin password	Yes

See Environment Variables Reference for the complete list.

Related Documentation

• API Security - Detailed API authentication guide
• Authentication Setup - User login configuration
• Quick Start - Getting started guide
• Deployment Guide - Production deployment