authegg/secrets-management

Secrets Management

Enforce secure secrets handling across Docker, Kubernetes, and CI/CD environments. Prevent credential leaks at every stage of the container lifecycle.

When to Use

• Configuring environment variables in Dockerfiles or compose files
• Setting up Kubernetes Secrets or external secret operators
• Integrating with HashiCorp Vault, AWS Secrets Manager, or similar
• Reviewing code for hardcoded credentials
• Setting up CI/CD pipeline secrets
• When the user mentions "API key", "password", "token", "credentials", ".env", or "secrets"

Cardinal Rules

1. NEVER put secrets in Dockerfiles (ENV, ARG, or COPY)
2. NEVER commit secrets to version control
3. NEVER pass secrets via command-line arguments (visible in process lists)
4. NEVER log secrets — scrub them from output
5. ALWAYS rotate secrets regularly
6. ALWAYS use the principle of least privilege for secret access

Where Secrets Should NOT Be

Dockerfiles — NEVER do this

# ❌ ALL of these are wrong
ENV DATABASE_URL=postgres://user:password@host/db
ARG API_KEY=sk-abc123
COPY .env /app/.env
RUN echo "password" > /app/config

docker-compose — NEVER do this

# ❌ Wrong
services:
  app:
    environment:
      - DB_PASSWORD=mysecretpassword
      - API_KEY=sk-abc123

Kubernetes — NEVER do this

# ❌ Wrong — plaintext in manifest
env:
  - name: DB_PASSWORD
    value: "mysecretpassword"

Where Secrets SHOULD Be

Docker — BuildKit Secret Mounts

For build-time secrets (e.g., private npm tokens):

# ✅ Secret never persists in image layers
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) \
    npm ci

Build command:

docker build --secret id=npm_token,src=.npm_token .

Docker Compose — External Secrets

# ✅ Secrets from files, not inline
services:
  app:
    secrets:
      - db_password
    environment:
      - DB_PASSWORD_FILE=/run/secrets/db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt  # gitignored

Docker Swarm — Native Secrets

# Create secret
echo "mysecret" | docker secret create db_password -

# Reference in stack
services:
  app:
    secrets:
      - db_password
secrets:
  db_password:
    external: true

Kubernetes — Secrets + External Operators

Basic (acceptable for non-production):

apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
stringData:
  DB_PASSWORD: "value"  # Encrypt at rest in etcd

Mount as volume (preferred over env vars):

volumeMounts:
  - name: secrets
    mountPath: /etc/secrets
    readOnly: true
volumes:
  - name: secrets
    secret:
      secretName: app-secrets

Production — use an external operator:

• ExternalSecrets Operator: Syncs from AWS/GCP/Azure/Vault
• SealedSecrets: Encrypt secrets for safe git storage
• Vault Secrets Operator: Direct HashiCorp Vault integration

CI/CD — Pipeline Secrets

# GitHub Actions — use encrypted secrets
env:
  DB_PASSWORD: ${{ secrets.DB_PASSWORD }}

# NEVER echo or log secrets
- run: |
    # ✅ Mask the secret
    echo "::add-mask::$DB_PASSWORD"

Secret Detection in CI

Add to every pipeline:

# Trivy secret scan
trivy fs --scanners secret --exit-code 1 .

# git-secrets (AWS-focused)
git secrets --scan

# Gitleaks
gitleaks detect --source . --verbose

.gitignore Essentials

Every project must exclude:

.env
.env.*
*.secret
*.pem
*.key
*.p12
*.pfx
secrets/
credentials/

Secrets Rotation Checklist

• [ ] All secrets have an expiration policy
• [ ] Rotation can happen without downtime
• [ ] Old secrets are revoked after rotation
• [ ] Rotation is automated where possible
• [ ] Rotation events are logged and auditable

References

• references/secrets-checklist.md — Full review checklist