javidi/secure-docker-bootstrap repository overview

⁠🛡️ Secure Docker Bootstrap Loader

A lightweight, secure, and immutable runtime bootstrap designed for modern Container-as-a-Service (CaaS) and cloud-native deployments.

Rather than embedding application logic, runtime binaries, or service configurations into Docker images, Secure Docker Bootstrap Loader dynamically provisions the execution environment by securely retrieving an encrypted payload from S3-compatible object storage or HTTPS, verifying its integrity, decrypting it locally, and executing it.

This architecture enables immutable infrastructure, allowing runtime behavior to evolve without rebuilding or republishing Docker images. The image itself remains static, while all deployment logic, provisioning scripts, and service initialization are managed externally through encrypted payloads.

⁠🎯 Design Goals

• 🧱 Immutable Docker image
• ⚡ Runtime bootstrap architecture
• 🔄 Externalized deployment logic
• 🔒 Secure encrypted payload execution
• ☁️ Native S3-compatible object storage integration
• 🪶 Minimal runtime footprint
• 🌐 Portable across CaaS providers
• 🛡️ Minimal attack surface
• 🛑 Zero hardcoded application logic

⁠🧠 Why This Architecture?

Traditional Docker images typically package application binaries, runtime dependencies, configuration files, and startup logic directly into the image.

Any application update generally requires rebuilding and republishing the image.

This project follows a different philosophy.

The Docker image remains completely static and acts only as a secure runtime bootstrap loader.

At runtime it:

1. 📥 Downloads an encrypted payload.
2. 🔍 Verifies its integrity.
3. 🔓 Decrypts it securely.
4. ▶️ Executes it.

Everything else—including application installation, runtime provisioning, configuration generation, package installation, and service startup—is delegated to the external payload.

This provides several advantages:

• ✅ No Docker image rebuilds when deployment logic changes.
• 🚀 Rapid deployment iterations.
• 🔒 Immutable infrastructure.
• 🧩 Separation between bootstrap and business logic.
• 📦 Easy modularization of deployment scripts.
• 🌍 Portable runtime provisioning across cloud providers.

⁠✨ Key Features

• Immutable Bootstrap Image – The Docker image never contains application logic, runtime binaries, or service-specific configuration.
• External Runtime Provisioning – All provisioning logic resides inside an encrypted external payload.
• Zero Hardcoded Secrets – No credentials, encryption keys, or deployment configuration are baked into the image.
• Native S3 API Support – Built-in s3cmd integration for Cloudflare R2 and any S3-compatible storage provider.
• Shared S3 Runtime Configuration – Automatically provisions /root/.s3cfg, allowing downstream scripts to reuse the same authenticated S3 session.
• HTTPS Fallback Support – Payloads can also be retrieved from a direct HTTPS URL when S3 is not used.
• Cryptographic Security – AES-256-CBC encryption with PBKDF2 key derivation using OpenSSL.
• Payload Integrity Verification – Optional SHA-256 checksum verification protects against corrupted or modified downloads.
• Windows CRLF Sanitization – Automatically removes Windows carriage returns after decryption to prevent shell execution issues.
• Proper PID 1 Handover – Uses exec for correct signal propagation and graceful container shutdown.
• Minimal Runtime Footprint – Built on debian:bookworm-slim with only essential runtime dependencies.
• Provider Independent – Designed for any Docker-compatible CaaS environment.

⁠🏗️ Architecture

             Secure Docker Bootstrap Loader

      ┌───────────────────────────────────────────────────┐
      │              Immutable Docker Image           │
      └───────────────────────────────────────────────────┘
                              │
                              ▼
                 Validate Runtime Environment
                              │
                              ▼
        Generate Global S3 Configuration (/root/.s3cfg)
                              │
                              ▼
                   Fetch Encrypted Payload
              ┌────────────────┬──────────────────────┐
              │               │                    │
              ▼               ▼                    ▼
         Native S3 API   Cloudflare R2     HTTPS Fallback
                              │
                              ▼
                    script.enc (Encrypted)
                              │
                              ▼
                SHA-256 Integrity Verification
                              │
                              ▼
                AES-256-CBC Decryption (PBKDF2)
                              │
                              ▼
                CRLF Sanitization (Windows Safe)
                              │
                              ▼
                   /tmp/script.sh (Runtime)
                              │
                              ▼
                   Replace PID 1 via exec()
                              │
                              ▼
                External Runtime Provisioning
                ├── Install packages
                ├── Download additional assets
                ├── Configure services
                ├── Generate runtime configuration
                ├── Initialize applications
                └── Start custom services

⁠📦 Environment Variables

⁠🗄️ S3 API Configuration (Primary Method)

⁠⚙️ General Configuration

⁠🔄 Runtime Workflow

Container Starts
        │
        ▼
Validate Environment Variables
        │
        ▼
Configure S3 (Optional)
        │
        ▼
Download Encrypted Payload
        │
        ▼
Verify SHA-256 Integrity
        │
        ▼
Decrypt Payload
        │
        ▼
Normalize Line Endings
        │
        ▼
Execute Runtime Script
        │
        ▼
Provision Runtime Environment

⁠🛠️ Usage Example

⁠Using Native S3 API

docker run --rm \
  -e S3_ENDPOINT="your_account_id.r2.cloudflarestorage.com" \
  -e S3_BUCKET="your-bucket" \
  -e S3_BASE_KEY="bootstrap" \
  -e S3_ACCESS_KEY="your_access_key" \
  -e S3_SECRET_KEY="your_secret_key" \
  -e DECRYPT_KEY="your_strong_password" \
  -e SCRIPT_HASH="your_sha256_checksum" \
  yourusername/secure-docker-bootstrap:1.0.0

⁠Using HTTPS

docker run --rm \
  -e SCRIPT_URL="[https://example.com/script.enc](https://example.com/script.enc)" \
  -e DECRYPT_KEY="your_strong_password" \
  -e SCRIPT_HASH="your_sha256_checksum" \
  yourusername/secure-docker-bootstrap:1.0.0

⁠🔒 Encrypting Your Payload

Generate an encrypted deployment script using OpenSSL:

openssl enc \
    -aes-256-cbc \
    -pbkdf2 \
    -iter 10000 \
    -in script.sh \
    -out script.enc \
    -k "your_strong_password"

Generate the SHA-256 checksum:

Linux:

sha256sum script.enc

Windows PowerShell:

Get-FileHash script.enc -Algorithm SHA256

Use the generated checksum as the value of the SCRIPT_HASH environment variable.

⁠🛡️ Security Considerations

• 📌 Always use explicit image tags (for example 1.0.0) in production.
• 🔐 Store DECRYPT_KEY securely using your CaaS secret management system.
• 🔑 Store S3 credentials securely and never hardcode them into images.
• 🧊 The Docker image never contains deployment logic or application code.
• ⏱️ The decrypted payload exists only temporarily during runtime.
• 🔍 Optional SHA-256 verification protects against corrupted or modified payloads.
• 🌐 Runtime provisioning logic remains completely external to the immutable image.

⁠🎯 Typical Use Cases

• Immutable infrastructure deployments
• Container-as-a-Service (CaaS)
• Runtime provisioning
• Dynamic service initialization
• Secure application bootstrap
• Cloud-native deployment workflows
• Externalized deployment automation
• Encrypted deployment pipelines
• Portable bootstrap environments

⁠💡 Project Philosophy

The Docker image should know as little as possible.

Its only responsibility is to securely bootstrap the runtime environment.

All application logic, deployment scripts, package installation, service initialization, and runtime configuration belong outside the image in encrypted payloads.

This keeps the image immutable, minimizes maintenance overhead, improves portability, and allows deployment behavior to evolve without rebuilding or republishing Docker images.