Security Best Practices

Security considerations and hardening guidelines for Telegram Bot API Docker

This guide covers security best practices for running the Telegram Bot API Docker container in production environments.

Container Security

Non-root User

The container runs as a non-root user for enhanced security:

RUN addgroup -S botapi && adduser -S -G botapi botapi
USER botapi

Key points:

• User: botapi
• Group: botapi
• All processes run without root privileges
• Data directories are owned by botapi:botapi

When mounting volumes, ensure the host directory is readable/writable by the container user (UID 1000).

Runtime Security

The Dockerfile implements several security measures:

1. Minimal runtime image: Alpine Linux base reduces attack surface
2. Only necessary dependencies: libstdc++ and libgcc for runtime
3. No build tools in final image: Multi-stage build separates build and runtime
4. Executable permissions: Entrypoint script uses --chmod=755 for explicit permissions

Credential Management

Required Credentials

Never commit your .env file or hardcode credentials in Docker commands. Use environment files or secrets management.

Two credentials are required to run the container:

Credential	Purpose	Where to get
TELEGRAM_API_ID	Telegram API application ID	https://my.telegram.org
TELEGRAM_API_HASH	Telegram API application hash	https://my.telegram.org

The entrypoint script validates these credentials at startup:

if [ -z "${TELEGRAM_API_ID:-}" ]; then
  echo "Error: TELEGRAM_API_ID is not set" >&2
  exit 1
fi

if [ -z "${TELEGRAM_API_HASH:-}" ]; then
  echo "Error: TELEGRAM_API_HASH is not set" >&2
  exit 1
fi

Secure Credential Storage

Use Docker secrets (Swarm/Compose):

services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    secrets:
      - telegram_api_id
      - telegram_api_hash
    environment:
      TELEGRAM_API_ID_FILE: /run/secrets/telegram_api_id
      TELEGRAM_API_HASH_FILE: /run/secrets/telegram_api_hash

secrets:
  telegram_api_id:
    file: ./secrets/api_id.txt
  telegram_api_hash:
    file: ./secrets/api_hash.txt

Use environment file with restricted permissions:

touch .env
chmod 600 .env
echo "TELEGRAM_API_ID=12345" >> .env
echo "TELEGRAM_API_HASH=abc123..." >> .env

Add to .gitignore:

.env
secrets/

Local Mode Security

TELEGRAM_LOCAL mode allows serving local files and should only be enabled in trusted environments with proper network isolation.

What is Local Mode?

When TELEGRAM_LOCAL=true is set, the server passes the --local flag to telegram-bot-api:

if [ "${TELEGRAM_LOCAL:-}" = "1" ] || 
   [ "$(printf '%s' "${TELEGRAM_LOCAL:-}" | tr '[:upper:]' '[:lower:]')" = "true" ]; then
  ARGS="$ARGS --local"
fi

Security Implications

Local mode enables:

• Serving files from the local filesystem
• Absolute file paths in getFile responses
• Bypassing normal file access restrictions

Security risks:

• Potential exposure of sensitive files if bot is compromised
• Directory traversal attacks if not properly isolated
• Larger attack surface for file-based exploits

When to Use Local Mode

✅ Safe scenarios:

• Development/testing environments
• Isolated private networks
• Single-tenant deployments with trusted bot code

❌ Avoid in:

• Public-facing production environments
• Multi-tenant deployments
• When serving untrusted bot applications

Hardening Local Mode

If you must use local mode:

1. Network isolation:

   docker network create --internal bot-network
   docker run --network bot-network ...
   

2. Read-only root filesystem:

   docker run --read-only -v /data -v /tmp ...
   

3. Limit volume mounts:

   # Only mount necessary directories
   docker run -v ./data:/data:ro ...
   

Volume Permissions

Secure Volume Configuration

The container expects writable access to:

• /data - Bot data and database
• /data/logs - Log files
• /tmp - Temporary files

Recommended permissions:

mkdir -p ./data/logs
chown -R 1000:1000 ./data  # botapi user UID/GID
chmod 750 ./data
chmod 640 ./data/logs/*

Sensitive Data Protection

Bot data directory may contain sensitive information including bot tokens, user data, and message history.

Best practices:

1. Encrypt volumes at rest:

   # Use encrypted filesystem or volume driver
   docker volume create --driver encrypted bot-data
   

2. Restrict host access:

   chmod 700 ./data
   # Only bot owner can access
   

3. Regular backups:

   # Backup to encrypted storage
   tar czf - ./data | gpg -e -r [e-mail] > backup.tar.gz.gpg
   

4. Exclude from version control:

   data/
   *.log
   

Network Security

Recommended Network Configuration

Create isolated network:

docker network create bot-network

Run with network isolation:

services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    networks:
      - bot-network
    # Only expose to localhost
    ports:
      - "127.0.0.1:8081:8081"
      - "127.0.0.1:8082:8082"

networks:
  bot-network:
    driver: bridge
    internal: false  # Needs outbound to Telegram servers

Firewall Rules

Allow only necessary traffic:

# Allow outbound to Telegram servers
iptables -A OUTPUT -p tcp -d 149.154.160.0/20 -j ACCEPT
iptables -A OUTPUT -p tcp -d 91.108.4.0/22 -j ACCEPT

# Allow inbound only from trusted IPs
iptables -A INPUT -p tcp --dport 8081 -s 10.0.0.0/8 -j ACCEPT
iptables -A INPUT -p tcp --dport 8081 -j DROP

Reverse Proxy

For production deployments, use a reverse proxy:

server {
    listen 443 ssl http2;
    server_name bot-api.example.com;

    ssl_certificate /etc/ssl/certs/cert.pem;
    ssl_certificate_key /etc/ssl/private/key.pem;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "DENY" always;

    location / {
        proxy_pass http://127.0.0.1:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Container Security Scanning

Scan for Vulnerabilities

Using Docker Scout:

docker scout cves ragnarok22/telegram-bot-api-docker

Using Trivy:

trivy image ragnarok22/telegram-bot-api-docker

Using Grype:

grype ragnarok22/telegram-bot-api-docker

Regular Updates

Keep your container image updated to receive security patches for Alpine Linux and upstream Telegram Bot API.

Pull latest image:

docker pull ragnarok22/telegram-bot-api-docker:latest
docker compose up -d  # Recreate with new image

Monitoring and Auditing

Enable Audit Logging

Increase log verbosity:

TELEGRAM_EXTRA_ARGS="--log-verbosity-level 3"

Monitor logs for suspicious activity:

tail -f ./data/logs/telegram-bot-api.log | grep -i "error\|warning\|unauthorized"

Container Resource Limits

Prevent resource exhaustion attacks:

services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          memory: 256M

Compliance and Hardening

CIS Docker Benchmark

Follow CIS Docker Benchmark guidelines:

• ✅ Run as non-root user
• ✅ Use trusted base images (Alpine)
• ✅ Scan images for vulnerabilities
• ✅ Limit container capabilities
• ✅ Use read-only root filesystem where possible

Security Checklist

• Credentials stored securely (not in version control)
• .env file has restricted permissions (600)
• Container runs as non-root
• Volumes have appropriate permissions
• Network access restricted to necessary ports
• Local mode disabled in production (unless required)
• Regular security scans performed
• Logs monitored for suspicious activity
• Backups encrypted and tested
• Container image kept up to date

Reporting Security Issues

If you discover a security vulnerability:

1. Do not open a public issue
2. Email the maintainer: [e-mail]
3. Include detailed reproduction steps
4. Allow reasonable time for a fix before disclosure

For vulnerabilities in the upstream Telegram Bot API server, report to: tdlib/telegram-bot-api