Gitlab Stack Secrets Manager

GitLab Stack Secrets Manager

This skill manages secrets for GitLab stack projects, ensuring secrets are stored securely, never exposed in configuration files, and properly integrated with Docker secrets.

When to Use This Skill

Activate this skill when the user requests:

• Create or manage Docker secrets
• Migrate environment variables to Docker secrets
• Validate secret configuration and permissions
• Audit secret usage and detect leaks
• Ensure secrets aren't in .env or docker-compose.yml
• Check if secrets are exposed in git
• Generate secure random secrets
• Rotate existing secrets
• Fix secret-related security issues

Core Security Principles

CRITICAL RULES - Never violated:

1. No Secrets in .env: Secrets MUST NEVER be in .env file 2. No Secrets in docker-compose.yml: No plaintext secrets in environment variables 3. ./secrets Directory: All secrets in ./secrets with 700 permissions 4. Secret Files: Individual files with 600 permissions 5. Git Protection: ./secrets/ in .gitignore, never committed 6. Proper Ownership: All files owned by Docker user (not root) 7. Docker Secrets Only*: Use Docker secrets mechanism exclusively

Secret Management Workflow

Phase 1: Understanding User Intent

Step 1: Determine the Operation

Ask yourself what the user wants to do:

• Create new secrets?
• Migrate existing environment variables to secrets?
• Validate current secret configuration?
• Audit secrets for leaks or issues?
• Update or rotate existing secrets?
• Remove secrets?

Step 2: Gather Context

1. Check current project state:

• Does ./secrets directory exist?
• Does docker-compose.yml exist?
• Does .env file exist?
• Is this part of stack-validator findings?

2. Review docker-compose.yml:

• Any secrets already defined?
• Any environment variables that look like secrets?
• Which services need secrets?

3. Scan for security issues:

• Secrets in .env?
• Secrets in docker-compose.yml environment variables?
• Secrets tracked in git?

Phase 2: Secret Creation

When: User wants to create new secrets

Step 1: Validate Prerequisites

1. Check if ./secrets directory exists:

   ls -ld ./secrets

2. If missing, create with proper permissions:

   mkdir -p ./secrets
   chmod 700 ./secrets

Step 2: Determine Secret Details

Ask the user (or infer from context):

• Secret name (e.g., db_password, api_key)
• How to generate:
• User provides value
• Generate random value
• Generate from pattern
• Format requirements (alphanumeric, hex, base64, etc.)
• Length requirements

Step 3: Create Secret File

1. Generate or accept secret value 2. Create file in ./secrets:

   echo -n "secret-value" > ./secrets/secret_name

3. Set proper permissions:

   chmod 600 ./secrets/secret_name

4. Verify ownership (should not be root)

Step 4: Update docker-compose.yml

1. Add to top-level secrets section:

   secrets:
     secret_name:
       file: ./secrets/secret_name

2. Add to appropriate service:

   services:
     myservice:
       secrets:
         - secret_name

Step 5: Verify .gitignore

Ensure ./secrets is excluded:

/secrets/
/secrets/*
!secrets/.gitkeep

Phase 3: Secret Validation

When: User wants to validate secret configuration, or as part of other operations

Step 1: Directory Structure Validation

1. Check ./secrets exists:

   [ -d ./secrets ] && echo "exists" || echo "missing"

2. Check permissions (should be 700):

   stat -c "%a" ./secrets  # Linux
   stat -f "%OLp" ./secrets  # macOS

3. Check ownership (not root):

   ls -ld ./secrets

Step 2: Secret Files Validation

1. List all secret files:

   find ./secrets -type f ! -name .gitkeep

2. For each file, check:

• Permissions (should be 600)
• Ownership (not root)
• Not empty
• Readable

Step 3: docker-compose.yml Validation

1. Parse secrets section:

• List all defined secrets
• Verify files exist for each secret

2. Check service secret references:

• All referenced secrets are defined
• Services use secrets: key, not environment vars

3. CRITICAL: Scan for secrets in environment variables:

• Look for patterns: PASSWORD, SECRET, KEY, TOKEN, API
• Flag any that look like secrets
• These MUST be migrated

Step 4: .env File Validation

1. CRITICAL: Scan .env for secrets:

• Pattern matching: PASSWORD, SECRET, KEY, TOKEN, API
• Long random-looking strings
• Base64-encoded values
• Any value that should be a secret

2. If secrets found in .env:

• This is a CRITICAL security issue
• List all detected secrets
• Recommend immediate migration

Step 5: Git Safety Check

1. Verify .gitignore excludes ./secrets:

   grep -q "secrets" .gitignore

2. Check if any secrets are staged:

   git status --porcelain | grep secrets/

3. Check git history for secrets (if requested):

   git log --all --full-history -- ./secrets/

Step 6: Generate Validation Report

🔐 Secrets Validation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 Directory Structure
✅ ./secrets exists with 700 permissions
✅ Owned by user (1000:1000)
✅ ./secrets in .gitignore

📄 Secret Files (3)
✅ db_password - 600 permissions, 32 bytes
✅ api_key - 600 permissions, 64 bytes
⚠️  jwt_secret - 644 permissions (should be 600)

🐳 Docker Integration
✅ 3 secrets defined in docker-compose.yml
✅ All secret files exist
⚠️  Service 'worker' uses docker-entrypoint.sh

❌ CRITICAL SECURITY ISSUES
❌ .env contains secrets:
   * DB_PASSWORD=supersecret123
   * API_KEY=sk_live_abc123
   ** IMMEDIATE ACTION REQUIRED **

❌ docker-compose.yml environment variables contain secrets:
   * Service 'app' - JWT_SECRET in environment
   ** MUST MIGRATE TO DOCKER SECRETS **

✅ Git Safety
✅ No secrets in git staging
✅ .gitignore properly configured

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: FAILED (2 critical issues)

🔧 IMMEDIATE ACTIONS REQUIRED
1. Migrate secrets from .env to Docker secrets
2. Remove secrets from docker-compose.yml environment
3. Fix permissions on jwt_secret file

Phase 4: Secret Migration

When: Secrets found in .env or docker-compose.yml environment variables

CRITICAL: This is a security issue that must be fixed

Step 1: Identify Secrets to Migrate

1. Scan .env for secret patterns:

   grep -E "(PASSWORD|SECRET|KEY|TOKEN|API)" .env

2. Scan docker-compose.yml environment sections:

   # Look for patterns in environment variables

3. List all detected secrets with:

• Variable name
• Current location (.env or compose)
• Current value (for migration)
• Suggested secret name

Step 2: Confirm with User

Present findings and ask:

• Which variables should be migrated?
• Confirm secret names
• Confirm it's safe to remove from .env/compose

Step 3: Create Secret Files

For each secret to migrate:

1. Extract current value 2. Create secret file:

   echo -n "$value" > ./secrets/secret_name
   chmod 600 ./secrets/secret_name

3. Add to docker-compose.yml secrets section

Step 4: Update Service Configurations

For each service using the secret:

1. Add to service secrets list 2. Remove from environment variables 3. If container supports _FILE suffix:

   environment:
     DB_PASSWORD_FILE: /run/secrets/db_password

4. If container doesn't support native secrets:

• Create or update docker-entrypoint.sh
• Document this requirement

Step 5: Clean Up

1. Remove secrets from .env:

• Either delete the lines
• Or comment them out with migration note

2. Remove from docker-compose.yml environment 3. Verify .env.example doesn't have secret values

Step 6: Verification

1. Test that services start correctly 2. Verify services can access secrets 3. Confirm no secrets remain in .env or compose 4. Run validation to confirm

Phase 5: Secret Generation

When: Need to generate secure random secrets

Step 1: Determine Format Requirements

Common formats:

• Alphanumeric: Letters and numbers (default)
• Hex: Hexadecimal (0-9, a-f)
• Base64: Base64 encoding
• Numeric: Numbers only
• UUID: UUID v4 format

Step 2: Determine Length

Standard lengths:

• Database passwords: 32-64 characters
• API keys: 32-64 characters
• JWT secrets: 64 characters (or 32 bytes base64)
• Session secrets: 32 characters
• Encryption keys: 32 bytes (256-bit)

Step 3: Generate Secret

Use cryptographically secure methods:

# Alphanumeric (32 chars)
openssl rand -base64 32 | tr -d '/+=' | head -c 32

# Hex (64 chars)
openssl rand -hex 32

# Base64 (32 bytes)
openssl rand -base64 32

# UUID
uuidgen

# Custom (e.g., 16 alphanumeric)
LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 16

Step 4: Store Securely

1. Write to file (no trailing newline):

   echo -n "$secret" > ./secrets/secret_name

2. Set permissions:

   chmod 600 ./secrets/secret_name

Phase 6: Secret Auditing

When: User wants to audit secret usage, find leaks, or review security

Step 1: Secret Inventory

List all secrets with details:

• Name
• File path
• File size
• Permissions
• Owner
• Created date (if available)
• Last modified

Step 2: Usage Analysis

For each secret: 1. Check if defined in docker-compose.yml 2. List services using it 3. Check if file exists 4. Verify it's actually used

Step 3: Find Unused Secrets

1. Secrets defined but not used in any service 2. Secret files that aren't in docker-compose.yml 3. Suggest removal or documentation

Step 4: Leak Detection

Check common leak locations:

1. .env file (CRITICAL):

   grep -E "(PASSWORD|SECRET|KEY|TOKEN)" .env

2. docker-compose.yml environment (CRITICAL):

• Scan all environment sections
• Flag any secrets

3. Configuration files:

   grep -r "password\|secret\|key" ./config/

4. Git history:

   git log -p --all -S "secret-pattern"

5. Docker logs:

• Check recent logs for secret exposure

Step 5: Permission Audit

1. Check all files in ./secrets:

   find ./secrets -type f -not -perm 600

2. Check directory permissions:

   [ "$(stat -c '%a' ./secrets)" = "700" ]

3. Check ownership:

   find ./secrets -user root

Step 6: Generate Audit Report

Include:

• Total secrets count
• Usage statistics
• Security issues found
• Recommendations
• Risk assessment

Phase 7: docker-entrypoint.sh Generation

When: Container doesn't support native Docker secrets

Step 1: Determine Necessity

Check if container supports secrets:

• PostgreSQL, MySQL, MariaDB: Support _FILE suffix ✅
• Redis: Native secret support ✅
• MongoDB: Native secret support ✅
• Most modern containers: Check documentation

Only create entrypoint if:

• Container expects environment variables only
• No _FILE suffix support
• No native /run/secrets/ reading

Step 2: Identify Required Secrets

List secrets that need to be loaded:

• Secret name (in ./secrets/)
• Environment variable name
• Service name

Step 3: Generate Entrypoint Script

#!/bin/bash
set -e

# Function to load secrets from docker secrets into environment
load_secret() {
  local secret_name=$1
  local env_var=$2
  local secret_file="/run/secrets/${secret_name}"

  if [ -f "$secret_file" ]; then
    export "${env_var}=$(cat "$secret_file")"
    echo "Loaded secret: $secret_name -> $env_var"
  else
    echo "ERROR: Secret file $secret_file not found!" >&2
    exit 1
  fi
}

# Load all required secrets
load_secret "db_password" "DB_PASSWORD"
load_secret "api_key" "API_KEY"
load_secret "jwt_secret" "JWT_SECRET"

# Execute the main command
exec "$@"

Step 4: Set Permissions

chmod +x docker-entrypoint.sh

Step 5: Update docker-compose.yml

services:
  myservice:
    entrypoint: /docker-entrypoint.sh
    command: ["original-command"]
    volumes:
      - ./docker-entrypoint.sh:/docker-entrypoint.sh:ro
    secrets:
      - db_password
      - api_key

Step 6: Document

Add comment explaining why entrypoint is needed:

# docker-entrypoint.sh required because this container
# doesn't support Docker secrets natively

Communication Style

When managing secrets:

1. Be Security-Focused: Emphasize security at every step 2. Be Clear About Risks: Explain why secrets in .env/compose is dangerous 3. Be Urgent About Critical Issues: Don't downplay security problems 4. Be Helpful: Provide exact commands to fix issues 5. Be Thorough: Check all potential leak locations 6. Be Educational: Explain why Docker secrets are better 7. Never Display Secret Values: Show "[REDACTED]" instead

Critical Validation Points

These are must-pass security criteria:

1. ✅ NO secrets in .env file 2. ✅ NO secrets in docker-compose.yml environment variables 3. ✅ ./secrets directory exists with 700 permissions 4. ✅ All secret files have 600 permissions 5. ✅ ./secrets/* in .gitignore 6. ✅ No secrets tracked in git 7. ✅ No root-owned secret files 8. ✅ All referenced secrets exist 9. ✅ docker-entrypoint.sh only when truly necessary

Integration with Companion Skills

stack-validator

• Stack-validator calls this skill for secret validation
• Validates that secrets follow proper patterns
• Detects secrets in .env and compose files

stack-creator

• Creates ./secrets directory with proper setup
• Generates .gitkeep file
• Sets up .gitignore correctly
• Creates initial secret placeholders

config-generator

• Ensures configs don't contain secrets
• References secrets properly
• Uses environment variables for non-secrets only

Important Notes

• Read-Only for Secrets: NEVER display actual secret values to user
• Security First: Always prioritize security over convenience
• Migration Required: Secrets in .env/compose MUST be migrated
• No Shortcuts: Always follow security best practices
• Verify Everything: Check permissions, ownership, git status
• Companion-Aware: Work with other skills seamlessly

Example Workflow: Complete Secret Setup

User: "Set up secrets for my database"

1. Check current state
   - ./secrets missing → create it
   - docker-compose.yml has DB_PASSWORD in environment → CRITICAL ISSUE

2. Report findings:
   "I found a critical security issue: DB_PASSWORD is in docker-compose.yml
    environment variables. I'll migrate this to Docker secrets."

3. Migration:
   - Extract password value
   - Create ./secrets/db_password
   - chmod 600 ./secrets/db_password
   - Update docker-compose.yml secrets section
   - Update postgres service to use secrets
   - Remove from environment

4. Verification:
   - Run validation
   - Confirm no secrets in compose
   - Check .gitignore
   - Verify permissions

5. Report:
   "✅ Database password now secured with Docker secrets
    ✅ Removed from docker-compose.yml environment
    ✅ File permissions set correctly
    ✅ Added to .gitignore"

---

This skill ensures secrets are managed securely and never exposed in configuration files or version control.

Secrets Migration Guide

This guide provides step-by-step instructions for migrating secrets from insecure locations (.env, docker-compose.yml environment variables) to secure Docker secrets.

Table of Contents

1. Why Migrate? 2. Pre-Migration Checklist 3. Migration Scenario 1: .env to Docker Secrets 4. Migration Scenario 2: docker-compose.yml Environment to Docker Secrets 5. Migration Scenario 3: Combined Migration 6. Post-Migration Validation 7. Troubleshooting

---

Why Migrate?

Security Risks of Secrets in .env or docker-compose.yml

Critical security issues:

• 🔴 Git exposure: Files may be committed to version control
• 🔴 World-readable: Default permissions allow anyone on system to read
• 🔴 Plaintext storage: No encryption or protection
• 🔴 Audit trail: No tracking of who accessed secrets
• 🔴 Rotation difficulty: Hard to rotate without downtime
• 🔴 Backup exposure: Secrets copied in backups

Benefits of Docker Secrets

• ✅ Encrypted at rest and in transit (in Swarm mode)
• ✅ Never written to disk in container filesystem
• ✅ Mount-only access at /run/secrets/
• ✅ Proper permissions automatically
• ✅ Easy rotation without code changes
• ✅ Audit capabilities built-in
• ✅ Never in git by design

---

Pre-Migration Checklist

Before starting migration:

1. Backup Current Configuration

# Backup .env
cp .env .env.backup.$(date +%Y%m%d)

# Backup docker-compose.yml
cp docker-compose.yml docker-compose.yml.backup.$(date +%Y%m%d)

# Create migration log
echo "Migration started: $(date)" > .migration.log

2. Identify All Secrets

# Scan .env for potential secrets
grep -iE "(PASSWORD|SECRET|KEY|TOKEN|API|AUTH)" .env

# Scan docker-compose.yml for secrets in environment
grep -A 10 "environment:" docker-compose.yml | grep -iE "(PASSWORD|SECRET|KEY|TOKEN)"

3. Document Secret Usage

Create a migration plan:

Secret Name          | Current Location           | Service(s) Using
---------------------|----------------------------|------------------
DB_PASSWORD          | .env                       | postgres, app
API_KEY              | docker-compose.yml (app)   | app
JWT_SECRET           | .env                       | app
SMTP_PASSWORD        | docker-compose.yml (mail)  | mail

4. Ensure ./secrets Directory Exists

# Create if missing
mkdir -p ./secrets
chmod 700 ./secrets

# Add .gitkeep (only file that should be in git)
touch ./secrets/.gitkeep
git add ./secrets/.gitkeep

5. Verify .gitignore

# Add to .gitignore if not present
cat >> .gitignore << 'EOF'

# Secrets
/secrets/
/secrets/*
!secrets/.gitkeep
EOF

---

Migration Scenario 1: .env to Docker Secrets

Example: Database Password in .env

Before (.env):

DB_HOST=postgres
DB_PORT=5432
DB_NAME=myapp
DB_USER=appuser
DB_PASSWORD=supersecretpassword123  # ❌ Security risk!

Step-by-Step Migration

Step 1: Extract Secret Value

# Read current value from .env
DB_PASSWORD=$(grep "^DB_PASSWORD=" .env | cut -d'=' -f2-)
echo "Found DB_PASSWORD in .env"

Step 2: Create Secret File

# Create secret file (no trailing newline!)
echo -n "$DB_PASSWORD" > ./secrets/db_password

# Set proper permissions
chmod 600 ./secrets/db_password

# Verify
ls -l ./secrets/db_password
# Expected: -rw------- ... db_password

Step 3: Update docker-compose.yml

Add secret definition:

# Add to top-level secrets section
secrets:
  db_password:
    file: ./secrets/db_password

Update service to use secret:

services:
  postgres:
    image: postgres:16-alpine
    secrets:
      - db_password
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      # Use _FILE suffix for Docker secrets
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password

Step 4: Remove from .env

# Comment out old value with migration note
sed -i 's/^DB_PASSWORD=.*/# DB_PASSWORD migrated to Docker secrets (\.\/secrets\/db_password)/' .env

# Or remove entirely
sed -i '/^DB_PASSWORD=/d' .env

After (.env):

DB_HOST=postgres
DB_PORT=5432
DB_NAME=myapp
DB_USER=appuser
# DB_PASSWORD migrated to Docker secrets (./secrets/db_password)

Step 5: Update .env.example

# Update .env.example to document the secret
cat >> .env.example << 'EOF'

# DB_PASSWORD is managed via Docker secrets
# File: ./secrets/db_password
# See README.md for secret setup instructions
EOF

Step 6: Test

# Restart services
docker compose down
docker compose up -d postgres

# Check logs for errors
docker compose logs postgres

# Verify secret is accessible inside container
docker compose exec postgres sh -c 'cat /run/secrets/db_password'

---

Migration Scenario 2: docker-compose.yml Environment to Docker Secrets

Example: API Key in docker-compose.yml

Before:

services:
  app:
    image: myapp:latest
    environment:
      API_URL: https://api.example.com
      API_KEY: sk_live_abc123xyz789def456  # ❌ Security risk!
      APP_ENV: production

Step-by-Step Migration

Step 1: Extract Secret Value

# Manually copy the value from docker-compose.yml
# API_KEY value: sk_live_abc123xyz789def456

Step 2: Create Secret File

# Create secret file
echo -n "sk_live_abc123xyz789def456" > ./secrets/api_key
chmod 600 ./secrets/api_key

Step 3: Add Secret to docker-compose.yml

# Top-level secrets
secrets:
  api_key:
    file: ./secrets/api_key

services:
  app:
    image: myapp:latest
    secrets:
      - api_key
    environment:
      API_URL: https://api.example.com
      APP_ENV: production
      # If app supports reading from file
      API_KEY_FILE: /run/secrets/api_key

Step 4: Application Code Update (if needed)

If application doesn't support _FILE suffix:

Option A: Modify application to read from file

// Node.js example
const fs = require('fs');

function getSecret(secretName) {
  try {
    return fs.readFileSync(`/run/secrets/${secretName}`, 'utf8').trim();
  } catch (err) {
    console.error(`Failed to read secret ${secretName}:`, err);
    process.exit(1);
  }
}

const apiKey = getSecret('api_key');

Option B: Use docker-entrypoint.sh

Create docker-entrypoint.sh:

#!/bin/bash
set -e

# Load API key from Docker secret
if [ -f /run/secrets/api_key ]; then
  export API_KEY=$(cat /run/secrets/api_key)
else
  echo "ERROR: api_key secret not found"
  exit 1
fi

# Execute original command
exec "$@"

Update docker-compose.yml:

services:
  app:
    image: myapp:latest
    entrypoint: /docker-entrypoint.sh
    command: ["npm", "start"]
    volumes:
      - ./docker-entrypoint.sh:/docker-entrypoint.sh:ro
    secrets:
      - api_key
    environment:
      API_URL: https://api.example.com
      APP_ENV: production

chmod +x docker-entrypoint.sh

Step 5: Remove from docker-compose.yml environment

Remove the old API_KEY line:

services:
  app:
    environment:
      API_URL: https://api.example.com
      APP_ENV: production
      # API_KEY removed - now using Docker secrets

Step 6: Test

docker compose up -d app
docker compose logs app

# Verify secret accessible
docker compose exec app sh -c 'cat /run/secrets/api_key'

---

Migration Scenario 3: Combined Migration

Example: Multiple Secrets in Both .env and docker-compose.yml

Before:

.env:

DB_PASSWORD=dbpass123
JWT_SECRET=jwt-secret-key-here
SMTP_PASSWORD=smtp-pass-123

docker-compose.yml:

services:
  app:
    environment:
      DB_PASSWORD: ${DB_PASSWORD}
      JWT_SECRET: ${JWT_SECRET}
      API_KEY: sk_live_hardcoded123

  mail:
    environment:
      SMTP_PASSWORD: ${SMTP_PASSWORD}

Comprehensive Migration

Step 1: Create All Secret Files

# Extract from .env
DB_PASSWORD=$(grep "^DB_PASSWORD=" .env | cut -d'=' -f2-)
JWT_SECRET=$(grep "^JWT_SECRET=" .env | cut -d'=' -f2-)
SMTP_PASSWORD=$(grep "^SMTP_PASSWORD=" .env | cut -d'=' -f2-)

# Create secret files
echo -n "$DB_PASSWORD" > ./secrets/db_password
echo -n "$JWT_SECRET" > ./secrets/jwt_secret
echo -n "$SMTP_PASSWORD" > ./secrets/smtp_password
echo -n "sk_live_hardcoded123" > ./secrets/api_key

# Set permissions
chmod 600 ./secrets/*

# Verify
ls -la ./secrets/

Step 2: Update docker-compose.yml Completely

secrets:
  db_password:
    file: ./secrets/db_password
  jwt_secret:
    file: ./secrets/jwt_secret
  api_key:
    file: ./secrets/api_key
  smtp_password:
    file: ./secrets/smtp_password

services:
  app:
    image: myapp:latest
    secrets:
      - db_password
      - jwt_secret
      - api_key
    environment:
      # Only non-secret configuration
      DB_HOST: postgres
      APP_ENV: production

  mail:
    image: mailserver:latest
    secrets:
      - smtp_password
    environment:
      SMTP_HOST: smtp.example.com
      SMTP_PORT: 587

Step 3: Create docker-entrypoint.sh (if needed)

#!/bin/bash
set -e

# Load all secrets into environment
load_secret() {
  local secret_name=$1
  local env_var=$2

  if [ -f "/run/secrets/${secret_name}" ]; then
    export "${env_var}=$(cat "/run/secrets/${secret_name}")"
    echo "✓ Loaded ${env_var} from ${secret_name}"
  else
    echo "✗ Secret ${secret_name} not found!" >&2
    exit 1
  fi
}

# Load all required secrets
load_secret "db_password" "DB_PASSWORD"
load_secret "jwt_secret" "JWT_SECRET"
load_secret "api_key" "API_KEY"

exec "$@"

Step 4: Clean Up .env

# Remove all secrets from .env
sed -i '/^DB_PASSWORD=/d' .env
sed -i '/^JWT_SECRET=/d' .env
sed -i '/^SMTP_PASSWORD=/d' .env

# Add migration notes
cat >> .env << 'EOF'

# === SECRETS MIGRATED TO DOCKER SECRETS ===
# All sensitive credentials now in ./secrets/ directory
# - DB_PASSWORD: ./secrets/db_password
# - JWT_SECRET: ./secrets/jwt_secret
# - SMTP_PASSWORD: ./secrets/smtp_password
# - API_KEY: ./secrets/api_key
EOF

Step 5: Update .env.example

# .env.example should NOT have secret values
cat > .env.example << 'EOF'
# Application configuration
APP_ENV=development
DB_HOST=postgres
DB_PORT=5432

# === REQUIRED SECRETS ===
# Create these files in ./secrets/ directory:
# - db_password: Database password
# - jwt_secret: JWT signing secret
# - smtp_password: Email server password
# - api_key: External API key
#
# See README.md for instructions
EOF

Step 6: Comprehensive Testing

# Stop all services
docker compose down

# Start with new configuration
docker compose up -d

# Check all service logs
docker compose logs

# Verify secrets accessible in each container
docker compose exec app sh -c 'ls -la /run/secrets/'
docker compose exec mail sh -c 'ls -la /run/secrets/'

# Test application functionality
curl http://localhost:8080/health

---

Post-Migration Validation

Validation Checklist

Run these checks after migration:

# 1. No secrets in .env
! grep -iE "(password|secret|key|token)=[^ ]" .env

# 2. No secrets in docker-compose.yml environment
! grep -A 20 "environment:" docker-compose.yml | grep -iE "(password|secret|key|token).*:"

# 3. All secret files exist
for secret in db_password jwt_secret api_key smtp_password; do
  [ -f "./secrets/$secret" ] && echo "✓ $secret exists" || echo "✗ $secret MISSING"
done

# 4. Proper permissions
[ "$(stat -c '%a' ./secrets)" = "700" ] && echo "✓ Directory: 700" || echo "✗ Wrong permissions"
find ./secrets -type f ! -name .gitkeep -exec stat -c '%a %n' {} \; | while read perm file; do
  [ "$perm" = "600" ] && echo "✓ $file: 600" || echo "✗ $file: $perm (should be 600)"
done

# 5. Secrets not in git
! git ls-files | grep "secrets/" | grep -v .gitkeep

# 6. All services running
docker compose ps | grep Up

Use stack-validator

# Run comprehensive validation
claude "validate this stack"

# Should show:
# ✅ No secrets in .env
# ✅ No secrets in docker-compose.yml environment
# ✅ All secret files exist with proper permissions
# ✅ ./secrets in .gitignore

---

Troubleshooting

Issue 1: Service Can't Access Secret

Symptom: Container logs show "permission denied" or "file not found"

Diagnosis:

# Check if secret is mounted
docker compose exec app ls -la /run/secrets/

# Check file permissions
ls -l ./secrets/db_password

Fix:

# Ensure proper permissions
chmod 600 ./secrets/db_password

# Ensure secret is defined in compose
grep -A 2 "secrets:" docker-compose.yml

# Restart service
docker compose restart app

Issue 2: Application Still Expects Environment Variable

Symptom: Application error "Missing required environment variable"

Solution A: Use docker-entrypoint.sh

# Create entrypoint to load secrets into environment
# See Pattern 3 in secrets-patterns.md

Solution B: Modify application code

// Read from /run/secrets/ instead of environment
const password = fs.readFileSync('/run/secrets/db_password', 'utf8').trim();

Issue 3: Secrets Accidentally Committed to Git

Symptom: git status shows secrets/ files

Immediate action:

# DO NOT COMMIT!
git reset ./secrets/

# Ensure .gitignore is correct
echo "/secrets/*" >> .gitignore
echo "!secrets/.gitkeep" >> .gitignore

# Stage .gitignore
git add .gitignore

If already committed:

# Remove from git (keeps local file)
git rm --cached ./secrets/*
git add ./secrets/.gitkeep

# Commit the fix
git commit -m "Remove secrets from git (security fix)"

# IMPORTANT: Rotate all exposed secrets immediately!
# Anyone with access to git history can see them

Clean git history (if secrets were pushed):

# Use git-filter-repo (recommended)
git filter-repo --path secrets/ --invert-paths --force

# Force push (coordinate with team!)
git push --force

Issue 4: Wrong Permissions After Docker Created Files

Symptom: Secret files owned by root

Fix:

# Change ownership
sudo chown $(id -u):$(id -g) ./secrets/*

# Fix permissions
chmod 700 ./secrets
chmod 600 ./secrets/*

Issue 5: Secrets Work Locally but Not in Production

Issue: File-based secrets only work in docker compose, not Swarm

Solution: Use external secrets for Swarm/production

# Create secrets in Swarm
echo "db-password-value" | docker secret create prod_db_password -

# Update docker-compose.yml for production
secrets:
  db_password:
    external: true
    name: prod_db_password

---

Migration Verification Report

After migration, generate a report:

🔐 Secrets Migration Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Migration Completed: 2025-10-20 14:30:00

Secrets Migrated (4):
✅ db_password (.env → Docker secrets)
✅ jwt_secret (.env → Docker secrets)
✅ api_key (docker-compose.yml → Docker secrets)
✅ smtp_password (.env → Docker secrets)

File Structure:
✅ ./secrets directory: 700 permissions
✅ All secret files: 600 permissions
✅ .gitignore updated
✅ .gitkeep present

Configuration Cleanup:
✅ .env: 0 secrets remaining
✅ docker-compose.yml: 0 secrets in environment
✅ .env.example: updated with migration notes

Docker Integration:
✅ 4 secrets defined in docker-compose.yml
✅ All services updated
✅ docker-entrypoint.sh created for app service

Validation:
✅ stack-validator: PASS
✅ All services running
✅ No secrets in git

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Migration successful - stack secured!

Next Steps:
1. Test all application functionality
2. Monitor logs for secret access issues
3. Plan secret rotation schedule (90 days)
4. Document secret setup in README.md

---

Follow this guide to safely migrate secrets from insecure storage to Docker secrets.

GitLab Stack Secrets Manager

Secure Docker secrets management for GitLab stack projects - ensures secrets are never in .env or docker-compose.yml

Overview

The GitLab Stack Secrets Manager skill helps you manage Docker secrets securely, ensuring secrets are never exposed in configuration files or version control. It focuses on migrating secrets from insecure locations (.env, docker-compose.yml environment variables) to Docker secrets.

Core Principle: Secrets MUST NEVER be in .env or docker-compose.yml environment variables.

Features

• Secret Creation: Generate secure random secrets with proper permissions
• Migration: Move secrets from .env/docker-compose.yml to Docker secrets
• Validation: Detect secrets in wrong locations (CRITICAL security issue)
• Auditing: Find unused secrets, detect leaks, check permissions
• Git Protection: Ensure secrets never committed to version control
• docker-entrypoint.sh Generation: For containers without native secret support

When to Use

Use this skill when you need to:

• Create new Docker secrets
• Migrate environment variables to Docker secrets
• Fix "secrets in .env" or "secrets in docker-compose.yml" issues
• Validate secret configuration and permissions
• Audit secret usage and detect leaks
• Generate secure random passwords/keys
• Rotate existing secrets
• Ensure secrets aren't in git

Installation

# Install the skill marketplace
/plugin marketplace add rknall/Skills

# Install the secrets-manager skill
/plugin install secrets-manager

Quick Start

Critical Security Fix: Secrets in .env

If stack-validator found secrets in your .env file:

# Migrate all secrets from .env to Docker secrets
claude "migrate secrets from .env to Docker secrets"

This will: 1. Extract secret values from .env 2. Create ./secrets/secret_name files with proper permissions 3. Update docker-compose.yml to use Docker secrets 4. Remove secrets from .env 5. Verify the migration

Create a New Secret

# Generate a secure random database password
claude "create a new secret db_password"

# Generate an API key
claude "create secret api_key --generate"

Validate Secrets

# Check all secrets for issues
claude "validate secrets"

Critical Security Rules

These rules are NEVER violated:

1. ❌ NO secrets in .env - Environment file must not contain secrets 2. ❌ NO secrets in docker-compose.yml - No plaintext in environment variables 3. ✅ All secrets in ./secrets/ - With 700 directory permissions 4. ✅ Secret files: 600 permissions - Owner read/write only 5. ✅ *./secrets/ in .gitignore - Never commit secrets 6. ✅ Use Docker secrets only** - Native Docker secrets mechanism

How Secrets Should Be Stored

Correct Structure

./secrets/
├── .gitkeep              # Only file in git
├── db_password           # 600 permissions
├── api_key               # 600 permissions
└── jwt_secret            # 600 permissions

docker-compose.yml:
  secrets:
    db_password:
      file: ./secrets/db_password

  services:
    app:
      secrets:
        - db_password
      # Secret available at /run/secrets/db_password

Incorrect (Security Risk)

# ❌ .env file
DB_PASSWORD=supersecret123        # CRITICAL SECURITY RISK!

# ❌ docker-compose.yml
services:
  app:
    environment:
      DB_PASSWORD: supersecret123  # CRITICAL SECURITY RISK!

Common Use Cases

1. Migrate Secrets from .env

Before (.env):

DB_PASSWORD=mysecretpass
API_KEY=sk_live_abc123

Command:

claude "migrate DB_PASSWORD and API_KEY from .env to Docker secrets"

After:

• Secrets in ./secrets/db_password and ./secrets/api_key
• Updated docker-compose.yml to use Docker secrets
• Removed from .env

2. Fix Secrets in docker-compose.yml

Before (docker-compose.yml):

services:
  app:
    environment:
      API_KEY: sk_live_hardcoded

Command:

claude "migrate API_KEY from docker-compose.yml to Docker secrets"

After:

secrets:
  api_key:
    file: ./secrets/api_key

services:
  app:
    secrets:
      - api_key

3. Create New Random Secret

# Database password
claude "create db_password secret with 32 random characters"

# API key (hex format)
claude "generate api_key secret in hex format"

# JWT secret (base64)
claude "create jwt_secret as base64 encoded"

4. Validate All Secrets

claude "validate secrets configuration"

Example Report:

🔐 Secrets Validation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 Directory: ✅ 700 permissions
📄 Files: ✅ All 600 permissions

❌ CRITICAL SECURITY ISSUES
  ❌ .env contains secrets:
     * DB_PASSWORD
     * API_KEY
  ❌ docker-compose.yml has secrets in environment

🔧 IMMEDIATE ACTION REQUIRED
  Migrate secrets to Docker secrets now!

5. Audit Secrets

# Find unused secrets
claude "find unused secrets"

# Check for leaks
claude "check for secret leaks"

# List all secrets
claude "list all secrets with details"

What Gets Validated

Secret Detection Patterns

The skill detects these as secrets:

Variable Names:

• PASSWORD
• SECRET
• KEY
• TOKEN
• API
• AUTH
• CREDENTIAL

Value Patterns:

• Long random strings (40+ chars)
• Base64-encoded values
• Hex strings (64+ chars)
• JWT tokens
• API key formats (sk_live_, pk_live_)

Validation Checks

1. Directory Structure

• ./secrets exists with 700 permissions
• Owned by current user (not root)
• In .gitignore

2. Secret Files

• 600 permissions (owner read/write only)
• Not empty
• Not root-owned

3. .env File (CRITICAL)

• NO secrets detected
• Only configuration values

4. docker-compose.yml (CRITICAL)

• NO secrets in environment variables
• All secrets in top-level secrets section
• Services use secrets: key

5. Git Safety

• ./secrets/* in .gitignore
• No secrets in git history
• No secrets staged for commit

Migration Workflow

Automatic Migration

When secrets detected in .env or docker-compose.yml:

1. Detection: Scans for secret patterns 2. Extraction: Saves values to ./secrets/ files 3. Permissions: Sets 700/600 on directory/files 4. docker-compose.yml Update: Adds secrets section 5. Service Update: Updates services to use secrets 6. Cleanup: Removes secrets from .env/compose 7. Verification: Validates migration success

Manual Steps (if needed)

# 1. Create secret file
echo -n "secret-value" > ./secrets/db_password
chmod 600 ./secrets/db_password

# 2. Add to docker-compose.yml
# See examples in secrets-patterns.md

# 3. Remove from .env
sed -i '/DB_PASSWORD=/d' .env

# 4. Test
docker compose up -d
docker compose logs

Integration with Companion Skills

stack-validator

Automatically calls secrets-manager when:

• Secrets detected in .env
• Secrets found in docker-compose.yml environment
• Permission issues on ./secrets

stack-creator

Creates proper secret structure:

• ./secrets directory with 700 permissions
• .gitkeep file
• .gitignore configuration

config-generator

Ensures configs don't contain secrets, references secrets properly

docker-entrypoint.sh Pattern

For containers that don't support native Docker secrets:

When needed:

• Container expects environment variables only
• No _FILE suffix support

Example:

#!/bin/bash
set -e

# Load secrets into environment
export DB_PASSWORD=$(cat /run/secrets/db_password)
export API_KEY=$(cat /run/secrets/api_key)

exec "$@"

Containers with native support (don't need entrypoint):

• PostgreSQL: POSTGRES_PASSWORD_FILE
• MySQL/MariaDB: MYSQL_PASSWORD_FILE
• Most modern containers

Security Best Practices

File Permissions

# Directory
chmod 700 ./secrets/          # drwx------

# Files
chmod 600 ./secrets/*         # -rw-------

# Ownership
chown $(id -u):$(id -g) ./secrets/*

.gitignore

# Secrets - NEVER commit
/secrets/
/secrets/*
!secrets/.gitkeep

# Environment files
.env
.env.local

# Backups
*.old
*.backup

Secret Generation

# Strong random passwords (32 chars)
openssl rand -base64 32 | tr -d '/+=' | head -c 32

# Hex keys (64 chars)
openssl rand -hex 32

# UUID
uuidgen

Secret Rotation

# Backup old secret
cp ./secrets/api_key ./secrets/api_key.old

# Generate new
openssl rand -hex 32 > ./secrets/api_key

# Test
docker compose restart app

# Remove old after verification
rm ./secrets/api_key.old

Troubleshooting

Issue: Secrets detected in .env

Fix:

claude "migrate all secrets from .env to Docker secrets"

Issue: Permission denied accessing secret

Fix:

chmod 700 ./secrets
chmod 600 ./secrets/*

Issue: Secret file owned by root

Fix:

sudo chown $(id -u):$(id -g) ./secrets/*

Issue: Service can't read secret

Check: 1. Secret defined in docker-compose.yml? 2. Service lists secret in secrets: key? 3. File exists in ./secrets/? 4. Proper permissions?

# Verify
docker compose exec app ls -la /run/secrets/

Reference Documentation

• SKILL.md - Complete skill workflow and validation process
• secrets-patterns.md - Security patterns and best practices
• migration-guide.md - Step-by-step migration scenarios

Version History

v1.0.0 (2025-10-20)

• Initial release
• Secret creation and management
• Migration from .env and docker-compose.yml
• Comprehensive validation and auditing
• docker-entrypoint.sh generation
• Git protection and leak detection
• Integration with stack-validator

Contributing

Found an issue? This skill is part of the rknall-custom-skills marketplace.

License

Part of the rknall-custom-skills marketplace for Claude Code.

---

Secure your secrets - never expose them in configuration files or version control.

Secrets Management Patterns

This document outlines the secure patterns for managing secrets in GitLab stack projects.

Table of Contents

1. Core Security Principles 2. Directory and File Structure 3. Docker Secrets Integration 4. Secret Detection Patterns 5. Migration Patterns 6. Common Secret Types

---

Core Security Principles

The Golden Rules

NEVER:

• ❌ Put secrets in .env files
• ❌ Put secrets in docker-compose.yml environment variables
• ❌ Commit secrets to git
• ❌ Use world-readable permissions
• ❌ Store secrets as root-owned files
• ❌ Hardcode secrets in application code
• ❌ Log secret values
• ❌ Pass secrets via command-line arguments

ALWAYS:

• ✅ Use Docker secrets mechanism
• ✅ Store secret files in ./secrets directory
• ✅ Set 700 permissions on ./secrets directory
• ✅ Set 600 permissions on secret files
• ✅ Add ./secrets/* to .gitignore
• ✅ Use cryptographically secure random generation
• ✅ Rotate secrets regularly
• ✅ Audit secret usage

---

Directory and File Structure

Standard ./secrets Directory Layout

./secrets/
├── .gitkeep                    # Only file tracked by git
├── db_password                 # Database password
├── db_root_password            # Database root password
├── api_key                     # External API key
├── jwt_secret                  # JWT signing secret
├── oauth_client_secret         # OAuth secret
├── smtp_password               # Email password
├── encryption_key              # Application encryption key
└── ssl/
    ├── cert.pem                # SSL certificate
    └── key.pem                 # SSL private key

Permissions Reference

# Directory permissions
drwx------  ./secrets/                    # 700 (owner only)

# File permissions
-rw-------  db_password                   # 600 (owner read/write)
-rw-------  api_key                       # 600
-rw-------  jwt_secret                    # 600

# Ownership
user:user   all files and directories     # NOT root

Setting Up Proper Permissions

# Create secrets directory
mkdir -p ./secrets
chmod 700 ./secrets

# Create secret file
echo -n "secret-value" > ./secrets/db_password
chmod 600 ./secrets/db_password

# Verify permissions
ls -la ./secrets/
# Expected: drwx------  ... ./secrets/
# Expected: -rw-------  ... db_password

# Fix ownership if root-owned
sudo chown -R $(id -u):$(id -g) ./secrets/

---

Docker Secrets Integration

Top-Level Secrets Definition

File-based secrets (preferred for development/single-host):

secrets:
  db_password:
    file: ./secrets/db_password

  api_key:
    file: ./secrets/api_key

  jwt_secret:
    file: ./secrets/jwt_secret

  # SSL certificates
  ssl_cert:
    file: ./secrets/ssl/cert.pem

  ssl_key:
    file: ./secrets/ssl/key.pem

External secrets (for production/swarm):

secrets:
  db_password:
    external: true
    name: prod_db_password

  api_key:
    external: true
    name: prod_api_key_v2

Service Secret Usage

Basic usage:

services:
  app:
    image: myapp:latest
    secrets:
      - db_password
      - api_key
      - jwt_secret
    # Secrets mounted at /run/secrets/secret_name

Containers with native Docker secrets support:

services:
  postgres:
    image: postgres:16-alpine
    secrets:
      - db_password
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: appuser
      # Use _FILE suffix to point to secret
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password

Supported containers with _FILE suffix:

• PostgreSQL: POSTGRES_PASSWORD_FILE
• MySQL/MariaDB: MYSQL_ROOT_PASSWORD_FILE, MYSQL_PASSWORD_FILE
• MongoDB: Various _FILE variables
• Redis: Configuration file can read from secret path

Containers requiring docker-entrypoint.sh:

services:
  custom_app:
    image: myapp:latest
    entrypoint: /docker-entrypoint.sh
    command: ["npm", "start"]
    volumes:
      - ./docker-entrypoint.sh:/docker-entrypoint.sh:ro
    secrets:
      - api_key
      - jwt_secret
    # docker-entrypoint.sh loads secrets into environment

---

Secret Detection Patterns

Patterns That Indicate Secrets

Variable Name Patterns (case-insensitive):

.*PASSWORD.*
.*SECRET.*
.*KEY.*
.*TOKEN.*
.*API.*
.*AUTH.*
.*CREDENTIAL.*
.*PRIVATE.*
.*CERT.*

Value Patterns:

# Base64-encoded (long strings)
^[A-Za-z0-9+/]{40,}={0,2}$

# Hex strings (64+ chars)
^[a-f0-9]{64,}$

# JWT tokens
^eyJ[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$

# API keys (common formats)
^sk_live_[A-Za-z0-9]{24,}$
^pk_live_[A-Za-z0-9]{24,}$

# UUID format
^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Scanning .env for Secrets

Examples of secrets in .env (BAD):

# ❌ BAD - These are secrets and should NOT be in .env
DB_PASSWORD=supersecret123
API_KEY=sk_live_abc123xyz789
JWT_SECRET=my-super-secret-jwt-key
STRIPE_SECRET_KEY=sk_test_abc123
OAUTH_CLIENT_SECRET=oauth-secret-123
ENCRYPTION_KEY=aes256-key-here
ADMIN_PASSWORD=admin123
SMTP_PASSWORD=email-password
PRIVATE_KEY=-----BEGIN PRIVATE KEY-----

What SHOULD be in .env (GOOD):

# ✅ GOOD - Non-secret configuration
APP_NAME=myapp
APP_ENV=production
APP_DEBUG=false
APP_URL=https://example.com

# Database connection (NOT credentials)
DB_HOST=postgres
DB_PORT=5432
DB_NAME=myapp_production
DB_USER=appuser
# DB_PASSWORD is in ./secrets/db_password

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# Ports
WEB_PORT=80
API_PORT=8080

# Feature flags
ENABLE_CACHING=true
ENABLE_LOGGING=true

Scanning docker-compose.yml for Secrets

Bad patterns (secrets in environment):

# ❌ BAD - Secrets in environment variables
services:
  app:
    environment:
      DB_PASSWORD: supersecret123              # ❌ CRITICAL
      API_KEY: sk_live_abc123                  # ❌ CRITICAL
      JWT_SECRET: my-jwt-secret                # ❌ CRITICAL

  postgres:
    environment:
      POSTGRES_PASSWORD: dbpassword123         # ❌ CRITICAL

Good patterns (using Docker secrets):

# ✅ GOOD - Using Docker secrets
services:
  app:
    secrets:
      - db_password
      - api_key
      - jwt_secret
    environment:
      # Only non-secret config in environment
      DB_HOST: postgres
      DB_PORT: 5432
      DB_NAME: myapp

  postgres:
    secrets:
      - db_password
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password

secrets:
  db_password:
    file: ./secrets/db_password
  api_key:
    file: ./secrets/api_key
  jwt_secret:
    file: ./secrets/jwt_secret

---

Migration Patterns

Pattern 1: Migrate from .env to Docker Secrets

Before (.env file):

DB_PASSWORD=mysecretpass
API_KEY=sk_live_abc123xyz
JWT_SECRET=my-jwt-secret-key

Migration steps:

# 1. Create secret files
echo -n "mysecretpass" > ./secrets/db_password
echo -n "sk_live_abc123xyz" > ./secrets/api_key
echo -n "my-jwt-secret-key" > ./secrets/jwt_secret

# 2. Set permissions
chmod 600 ./secrets/*

# 3. Remove from .env
sed -i '/DB_PASSWORD=/d' .env
sed -i '/API_KEY=/d' .env
sed -i '/JWT_SECRET=/d' .env

After (.env file):

# Secrets moved to Docker secrets in ./secrets/
# DB_PASSWORD: ./secrets/db_password
# API_KEY: ./secrets/api_key
# JWT_SECRET: ./secrets/jwt_secret

Pattern 2: Migrate from docker-compose.yml environment to Secrets

Before:

services:
  app:
    environment:
      DB_HOST: postgres
      DB_PASSWORD: supersecret123    # ❌ Secret in compose
      API_KEY: sk_live_abc123        # ❌ Secret in compose

Migration:

# Extract values and create secret files
echo -n "supersecret123" > ./secrets/db_password
echo -n "sk_live_abc123" > ./secrets/api_key
chmod 600 ./secrets/*

After:

services:
  app:
    secrets:
      - db_password
      - api_key
    environment:
      DB_HOST: postgres
      # Secrets loaded from /run/secrets/

secrets:
  db_password:
    file: ./secrets/db_password
  api_key:
    file: ./secrets/api_key

Pattern 3: Create docker-entrypoint.sh for Legacy Containers

When container doesn't support _FILE variables:

docker-entrypoint.sh:

#!/bin/bash
set -e

# Function to load secret into environment variable
load_secret() {
  local secret_name=$1
  local env_var=$2
  local secret_file="/run/secrets/${secret_name}"

  if [ -f "$secret_file" ]; then
    export "${env_var}=$(cat "$secret_file")"
    echo "✓ Loaded secret: $secret_name -> $env_var"
  else
    echo "✗ ERROR: Secret file not found: $secret_file" >&2
    exit 1
  fi
}

# Load all required secrets
load_secret "db_password" "DB_PASSWORD"
load_secret "api_key" "API_KEY"
load_secret "jwt_secret" "JWT_SECRET"

# Execute the original command
exec "$@"

docker-compose.yml:

services:
  legacy_app:
    image: legacy-app:latest
    entrypoint: /docker-entrypoint.sh
    command: ["node", "server.js"]
    volumes:
      - ./docker-entrypoint.sh:/docker-entrypoint.sh:ro
    secrets:
      - db_password
      - api_key
      - jwt_secret

Set permissions:

chmod +x docker-entrypoint.sh

---

Common Secret Types

1. Database Passwords

Generate:

openssl rand -base64 32 | tr -d '/+=' | head -c 32 > ./secrets/db_password
chmod 600 ./secrets/db_password

Use with PostgreSQL:

services:
  postgres:
    image: postgres:16-alpine
    secrets:
      - db_password
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password

2. API Keys

Generate:

openssl rand -hex 32 > ./secrets/api_key
chmod 600 ./secrets/api_key

Format: 64 hex characters

3. JWT Secrets

Generate:

openssl rand -base64 64 > ./secrets/jwt_secret
chmod 600 ./secrets/jwt_secret

Format: Base64-encoded, 64+ characters

4. Encryption Keys

Generate AES-256 key:

openssl rand -hex 32 > ./secrets/encryption_key
chmod 600 ./secrets/encryption_key

Format: 32 bytes hex (256-bit)

5. Session Secrets

Generate:

openssl rand -base64 32 > ./secrets/session_secret
chmod 600 ./secrets/session_secret

6. OAuth Client Secrets

Usually provided by OAuth provider, store securely:

echo -n "provider-given-secret" > ./secrets/oauth_client_secret
chmod 600 ./secrets/oauth_client_secret

7. SSL/TLS Certificates and Keys

Store certificate and key separately:

# Certificate (can be less restrictive)
cp cert.pem ./secrets/ssl/cert.pem
chmod 644 ./secrets/ssl/cert.pem

# Private key (must be restrictive)
cp key.pem ./secrets/ssl/key.pem
chmod 600 ./secrets/ssl/key.pem

Use in compose:

secrets:
  ssl_cert:
    file: ./secrets/ssl/cert.pem
  ssl_key:
    file: ./secrets/ssl/key.pem

services:
  nginx:
    secrets:
      - ssl_cert
      - ssl_key
    # Mounted at /run/secrets/ssl_cert and /run/secrets/ssl_key

---

Git Protection Patterns

.gitignore Configuration

Comprehensive .gitignore:

# Secrets directory - NEVER commit
/secrets/
/secrets/*

# Allow only .gitkeep
!secrets/.gitkeep

# Backup files
*.old
*.backup
*.bak
*~

# Environment files (may contain secrets)
.env
.env.local
.env.*.local
.env.production

# Common secret file patterns
*password*.txt
*secret*.txt
*key*.txt
*token*.txt
*credential*.txt

# SSL/TLS
*.pem
*.key
*.crt
*.p12
*.pfx

# SSH keys
id_rsa
id_ed25519
*.ppk

Checking Git Status

Verify secrets aren't staged:

# Check for secrets in staging
git status | grep secrets/

# Should only show .gitkeep if anything
# If other files shown, they're staged (BAD!)

Check git history:

# Search for secrets in history
git log --all --full-history -- ./secrets/

# Search for specific patterns
git log -p --all -S "password"
git log -p --all -S "secret"

Remove secrets from git history (if committed):

# Using git-filter-repo (recommended)
git filter-repo --path secrets/ --invert-paths

# Or BFG Repo-Cleaner
bfg --delete-folders secrets

---

Secret Rotation Patterns

Safe Rotation Procedure

# 1. Backup current secret
cp ./secrets/api_key ./secrets/api_key.$(date +%Y%m%d).old

# 2. Generate new secret
openssl rand -hex 32 > ./secrets/api_key

# 3. Test with new secret
docker compose up -d
docker compose logs app  # Check for errors

# 4. If successful, remove old backup after grace period
# rm ./secrets/api_key.*.old

Rotation Tracking

Create .secrets/metadata.yml (not tracked):

db_password:
  created: 2025-01-15
  rotated: 2025-10-20
  rotation_interval_days: 90

api_key:
  created: 2025-01-15
  rotated: 2025-10-20
  rotation_interval_days: 90

---

Security Checklist

Pre-Deployment

• [ ] All secrets in ./secrets directory
• [ ] Directory permissions: 700
• [ ] File permissions: 600
• [ ] No root-owned files
• [ ] ./secrets/* in .gitignore
• [ ] No secrets in .env
• [ ] No secrets in docker-compose.yml environment
• [ ] All referenced secrets exist
• [ ] docker-entrypoint.sh only when necessary
• [ ] No secrets in git history

Post-Deployment

• [ ] Services can access secrets
• [ ] No secrets in container logs
• [ ] Secrets mounted at /run/secrets/
• [ ] No permission errors
• [ ] Rotation schedule established

---

These patterns ensure secrets are managed securely throughout the stack lifecycle.