GitLab Stack Secrets Manager

What this skill does

# 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 cor