zhongwei/gh-rknall-claude-skills-secrets-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:52:05 +08:00
commit 0f581cae40
6 changed files with 2142 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "secrets-manager",
"description": "Manages Docker secrets for GitLab stack projects, ensuring secrets are never in .env or docker-compose.yml. Handles migration from environment variables, validation, auditing, and secure secret generation",
"version": "1.0.0",
"author": {
"name": "rknall",
"email": "zhongweili@tubi.tv"
},
"skills": [
"./"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# secrets-manager
Manages Docker secrets for GitLab stack projects, ensuring secrets are never in .env or docker-compose.yml. Handles migration from environment variables, validation, auditing, and secure secret generation

636
SKILL.md Normal file
View File

@@ -0,0 +1,636 @@
---
name: "GitLab Stack Secrets Manager"
description: "Manages Docker secrets for GitLab stack projects, ensuring secrets are never in .env or docker-compose.yml, properly stored in ./secrets directory, and securely integrated with Docker secrets. Use when users need to create secrets, migrate from environment variables, validate secret configuration, audit secret usage, or ensure secrets are never committed to git."
---
# 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:
```bash
ls -ld ./secrets
```
2. If missing, create with proper permissions:
```bash
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:
```bash
echo -n "secret-value" > ./secrets/secret_name
```
3. Set proper permissions:
```bash
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:
```yaml
secrets:
secret_name:
file: ./secrets/secret_name
```
2. Add to appropriate service:
```yaml
services:
myservice:
secrets:
- secret_name
```
**Step 5: Verify .gitignore**
Ensure ./secrets is excluded:
```gitignore
/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:
```bash
[ -d ./secrets ] && echo "exists" || echo "missing"
```
2. Check permissions (should be 700):
```bash
stat -c "%a" ./secrets # Linux
stat -f "%OLp" ./secrets # macOS
```
3. Check ownership (not root):
```bash
ls -ld ./secrets
```
**Step 2: Secret Files Validation**
1. List all secret files:
```bash
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:
```bash
grep -q "secrets" .gitignore
```
2. Check if any secrets are staged:
```bash
git status --porcelain | grep secrets/
```
3. Check git history for secrets (if requested):
```bash
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:
```bash
grep -E "(PASSWORD|SECRET|KEY|TOKEN|API)" .env
```
2. Scan docker-compose.yml environment sections:
```yaml
# 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:
```bash
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:
```yaml
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:
```bash
# 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):
```bash
echo -n "$secret" > ./secrets/secret_name
```
2. Set permissions:
```bash
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):
```bash
grep -E "(PASSWORD|SECRET|KEY|TOKEN)" .env
```
2. **docker-compose.yml environment** (CRITICAL):
- Scan all environment sections
- Flag any secrets
3. **Configuration files**:
```bash
grep -r "password\|secret\|key" ./config/
```
4. **Git history**:
```bash
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:
```bash
find ./secrets -type f -not -perm 600
```
2. Check directory permissions:
```bash
[ "$(stat -c '%a' ./secrets)" = "700" ]
```
3. Check ownership:
```bash
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**
```bash
#!/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**
```bash
chmod +x docker-entrypoint.sh
```
**Step 5: Update docker-compose.yml**
```yaml
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:
```yaml
# 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.*

736
migration-guide.md Normal file
View File

@@ -0,0 +1,736 @@
# 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?](#why-migrate)
2. [Pre-Migration Checklist](#pre-migration-checklist)
3. [Migration Scenario 1: .env to Docker Secrets](#migration-scenario-1-env-to-docker-secrets)
4. [Migration Scenario 2: docker-compose.yml Environment to Docker Secrets](#migration-scenario-2-docker-composeyml-environment-to-docker-secrets)
5. [Migration Scenario 3: Combined Migration](#migration-scenario-3-combined-migration)
6. [Post-Migration Validation](#post-migration-validation)
7. [Troubleshooting](#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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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):
```bash
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**
```bash
# 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**
```bash
# 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:
```yaml
# Add to top-level secrets section
secrets:
db_password:
file: ./secrets/db_password
```
Update service to use secret:
```yaml
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**
```bash
# 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):
```bash
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**
```bash
# 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**
```bash
# 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**:
```yaml
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**
```bash
# Manually copy the value from docker-compose.yml
# API_KEY value: sk_live_abc123xyz789def456
```
**Step 2: Create Secret File**
```bash
# Create secret file
echo -n "sk_live_abc123xyz789def456" > ./secrets/api_key
chmod 600 ./secrets/api_key
```
**Step 3: Add Secret to docker-compose.yml**
```yaml
# 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
```javascript
// 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`:
```bash
#!/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:
```yaml
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
```
```bash
chmod +x docker-entrypoint.sh
```
**Step 5: Remove from docker-compose.yml environment**
Remove the old API_KEY line:
```yaml
services:
app:
environment:
API_URL: https://api.example.com
APP_ENV: production
# API_KEY removed - now using Docker secrets
```
**Step 6: Test**
```bash
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:
```bash
DB_PASSWORD=dbpass123
JWT_SECRET=jwt-secret-key-here
SMTP_PASSWORD=smtp-pass-123
```
docker-compose.yml:
```yaml
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**
```bash
# 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**
```yaml
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)
```bash
#!/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**
```bash
# 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**
```bash
# .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**
```bash
# 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:
```bash
# 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
```bash
# 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**:
```bash
# Check if secret is mounted
docker compose exec app ls -la /run/secrets/
# Check file permissions
ls -l ./secrets/db_password
```
**Fix**:
```bash
# 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
```bash
# Create entrypoint to load secrets into environment
# See Pattern 3 in secrets-patterns.md
```
**Solution B**: Modify application code
```javascript
// 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**:
```bash
# 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**:
```bash
# 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):
```bash
# 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**:
```bash
# 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
```bash
# 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.*

53
plugin.lock.json Normal file
View File

@@ -0,0 +1,53 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:rknall/claude-skills:secrets-manager",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "843e879caa1d8051906045c8287935aa2256b72a",
"treeHash": "06cc5fb06d81aa4d8baef613de9b3d57c0b7616ef1a74d6214cfd3d1e2a1ed39",
"generatedAt": "2025-11-28T10:27:59.285770Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "secrets-manager",
"description": "Manages Docker secrets for GitLab stack projects, ensuring secrets are never in .env or docker-compose.yml. Handles migration from environment variables, validation, auditing, and secure secret generation",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "migration-guide.md",
"sha256": "0cb0c47b682af944efd289b8e939f6d9957a110ff7cb90b273cda6861be80261"
},
{
"path": "README.md",
"sha256": "77b1b7f4d1935d017010953ec3bbb0bcb11203d719875f2f6f4ab16b25f41b41"
},
{
"path": "secrets-patterns.md",
"sha256": "da5bcfe17e0c6145ae5f2af7bba58db225d7ddb6380d590e4397fc736cb9c7cd"
},
{
"path": "SKILL.md",
"sha256": "0d77be726503d7a197fc0bd754324d89fde87a4137bbf1f3d9bcfa7fcb7146d3"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "15bc7680f66c3c255bcb8de508411cdef66b76eea5d290a9eb9b027316c2c6d7"
}
],
"dirSha256": "06cc5fb06d81aa4d8baef613de9b3d57c0b7616ef1a74d6214cfd3d1e2a1ed39"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

702
secrets-patterns.md Normal file
View File

@@ -0,0 +1,702 @@
# Secrets Management Patterns
This document outlines the secure patterns for managing secrets in GitLab stack projects.
## Table of Contents
1. [Core Security Principles](#core-security-principles)
2. [Directory and File Structure](#directory-and-file-structure)
3. [Docker Secrets Integration](#docker-secrets-integration)
4. [Secret Detection Patterns](#secret-detection-patterns)
5. [Migration Patterns](#migration-patterns)
6. [Common Secret Types](#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
```bash
# 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
```bash
# 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):
```yaml
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):
```yaml
secrets:
db_password:
external: true
name: prod_db_password
api_key:
external: true
name: prod_api_key_v2
```
### Service Secret Usage
**Basic usage**:
```yaml
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**:
```yaml
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**:
```yaml
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):
```regex
.*PASSWORD.*
.*SECRET.*
.*KEY.*
.*TOKEN.*
.*API.*
.*AUTH.*
.*CREDENTIAL.*
.*PRIVATE.*
.*CERT.*
```
**Value Patterns**:
```regex
# 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):
```bash
# ❌ 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):
```bash
# ✅ 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):
```yaml
# ❌ 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):
```yaml
# ✅ 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):
```bash
DB_PASSWORD=mysecretpass
API_KEY=sk_live_abc123xyz
JWT_SECRET=my-jwt-secret-key
```
**Migration steps**:
```bash
# 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):
```bash
# 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**:
```yaml
services:
app:
environment:
DB_HOST: postgres
DB_PASSWORD: supersecret123 # ❌ Secret in compose
API_KEY: sk_live_abc123 # ❌ Secret in compose
```
**Migration**:
```bash
# Extract values and create secret files
echo -n "supersecret123" > ./secrets/db_password
echo -n "sk_live_abc123" > ./secrets/api_key
chmod 600 ./secrets/*
```
**After**:
```yaml
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**:
```bash
#!/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**:
```yaml
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**:
```bash
chmod +x docker-entrypoint.sh
```
---
## Common Secret Types
### 1. Database Passwords
**Generate**:
```bash
openssl rand -base64 32 | tr -d '/+=' | head -c 32 > ./secrets/db_password
chmod 600 ./secrets/db_password
```
**Use with PostgreSQL**:
```yaml
services:
postgres:
image: postgres:16-alpine
secrets:
- db_password
environment:
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
```
### 2. API Keys
**Generate**:
```bash
openssl rand -hex 32 > ./secrets/api_key
chmod 600 ./secrets/api_key
```
**Format**: 64 hex characters
### 3. JWT Secrets
**Generate**:
```bash
openssl rand -base64 64 > ./secrets/jwt_secret
chmod 600 ./secrets/jwt_secret
```
**Format**: Base64-encoded, 64+ characters
### 4. Encryption Keys
**Generate AES-256 key**:
```bash
openssl rand -hex 32 > ./secrets/encryption_key
chmod 600 ./secrets/encryption_key
```
**Format**: 32 bytes hex (256-bit)
### 5. Session Secrets
**Generate**:
```bash
openssl rand -base64 32 > ./secrets/session_secret
chmod 600 ./secrets/session_secret
```
### 6. OAuth Client Secrets
**Usually provided by OAuth provider**, store securely:
```bash
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**:
```bash
# 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**:
```yaml
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**:
```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**:
```bash
# 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**:
```bash
# 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):
```bash
# 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
```bash
# 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):
```yaml
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.*