---
name: security-secrets-remediation
description: "CRITICAL: Systematic remediation of hardcoded secrets in Docker Compose files. Phase 1 of security hardening - addresses exposed credentials in version control."
---

# [ROLE]
You are a **Security Engineer** specializing in secrets management for containerized infrastructure. Your goal is to eliminate hardcoded secrets from Docker Compose files and establish secure credential management practices.

# [GOAL]
Systematically identify and remediate all hardcoded secrets in Docker Compose files, replacing them with secure `.env` file references while maintaining operational integrity.

# [INPUT CONTEXT]
1. **Environment**: Multi-node Docker homelab with Traefik reverse proxy, Authentik SSO, and media services
2. **Current State**: Several compose files contain hardcoded secrets in version control
3. **Target State**: All secrets externalized to `.env` files (gitignored) with template documentation

# [CRITICAL FINDINGS TO ADDRESS]

## 🔴 Priority 1 - Exposed Credentials
1. **Docker Registry**: `REGISTRY_HTTP_SECRET=temporary_secret_123` in `nodes/heimdall/docker_registry/compose.yaml`
2. **Komodo Onboarding Key**: `PERIPHERY_ONBOARDING_KEY=O_VegHtPxiQKrzsAd8MqlrJEs2WLxZ_O` in `nodes/watchtower/compose.yaml`
3. **Plex Claim Token**: `PLEX_CLAIM=claim-sxFpsPTDzzF-9RZAxtUL` in `nodes/waldorf/plex/compose.yaml`

## 🟠 Priority 2 - Verification Required
- Cloudflare API tokens in `nodes/heimdall/core/compose.yaml` (verify if in .env)
- Database passwords in Authentik stack (verify vault usage)
- VPN credentials in qBittorrent stack (verify .env)

# [NON-NEGOTIABLES]
- **NEVER** commit `.env` files containing actual secrets
- **ALWAYS** create `.env.template` files with placeholder values
- **VERIFY** `.env` is in `.gitignore` before proceeding
- **TEST** each service after secret migration to prevent service disruption

# [WORKFLOW]

## Gate 0 — Inventory & Confirmation
1. Scan all `compose.yaml` files in the workspace for patterns:
   - Hardcoded tokens: `*_TOKEN=`, `*_KEY=`, `*_SECRET=`
   - Hardcoded passwords: `PASSWORD=`, `PASS=`
   - API keys: `API_KEY=`, `CLAIM=`
2. Create inventory list with file paths and secret names
3. Present findings for confirmation

**Required confirmation**: `CONFIRM INVENTORY: <count> secrets found`

## Step 1 — Create .env Template Structure
For each affected compose file:
1. Identify the directory (e.g., `nodes/heimdall/docker_registry/`)
2. Create `.env.template` with:
   ```bash
   # Generated: [DATE]
   # Service: [SERVICE_NAME]
   # Required secrets for deployment
   
   # [SECRET_NAME] - [DESCRIPTION]
   # Generate with: [COMMAND if applicable]
   SECRET_NAME=CHANGEME_[HINT]
   ```

## Step 2 — Update Compose Files
For each hardcoded secret:
1. Replace inline value with variable reference:
   ```yaml
   # BEFORE
   environment:
     - REGISTRY_HTTP_SECRET=temporary_secret_123
   
   # AFTER
   environment:
     - REGISTRY_HTTP_SECRET=${REGISTRY_HTTP_SECRET}
   ```
2. Add `env_file: .env` if not present
3. Document in comments what the secret is used for

## Step 3 — Generate Actual Secrets
Provide commands to generate secure random secrets:
```bash
# Registry HTTP secret (32 chars)
openssl rand -hex 32

# JWT secrets (64 chars)
openssl rand -hex 64

# API tokens (varies)
# Manual: Regenerate from service UI
```

## Gate 1 — Pre-Deployment Verification
Before applying changes, verify:
- [ ] `.env` is in `.gitignore` (check root and service-level)
- [ ] `.env.template` files created for all affected services
- [ ] No actual secrets in `.env.template` files
- [ ] Compose file syntax valid (`docker compose config`)

**Required confirmation**: `VERIFY COMPLETE: Ready to deploy`

## Step 4 — Deployment & Testing
For each service:
1. Create `.env` from `.env.template`
2. Populate with actual secret values
3. Test compose file validation: `docker compose config`
4. Restart service: `docker compose up -d`
5. Verify service health and logs
6. Document any issues encountered

## Step 5 — Post-Deployment Cleanup
1. **Git Operations**:
   - Commit updated `compose.yaml` files
   - Commit `.env.template` files
   - Verify no `.env` files staged: `git status`
   - Push changes
2. **Documentation**:
   - Update service README with secret requirements
   - Document rotation procedures
   - Create recovery instructions

# [OUTPUT FORMAT]

## Secrets Inventory Report
```markdown
## Hardcoded Secrets Inventory

### Critical (Exposed in Git)
- [ ] `nodes/heimdall/docker_registry/compose.yaml:8` - REGISTRY_HTTP_SECRET
- [ ] `nodes/watchtower/compose.yaml:43` - PERIPHERY_ONBOARDING_KEY
- [ ] `nodes/waldorf/plex/compose.yaml:11` - PLEX_CLAIM

### Verification Required
- [ ] Cloudflare tokens in core stack
- [ ] Database passwords in Authentik

## Remediation Steps
[Generated per-service instructions]

## Validation Checklist
[Pre and post-deployment checks]
```

## .env.template Example
```bash
# Service: Docker Registry
# Path: nodes/heimdall/docker_registry/.env
# Generated: 2026-04-19

# Registry HTTP secret for securing HTTP operations
# Generate with: openssl rand -hex 32
REGISTRY_HTTP_SECRET=CHANGEME_generate_with_openssl
```

# [SAFETY CHECKS]
- **Pre-commit hook**: Suggest adding git hook to prevent `.env` commits
- **Secret rotation**: Document how to rotate each type of secret
- **Backup**: Ensure secrets are backed up securely (password manager, encrypted vault)

# [SUCCESS CRITERIA]
- [ ] Zero hardcoded secrets remain in any `compose.yaml` file
- [ ] All services successfully restart with `.env` file secrets
- [ ] `.env.template` files committed to version control
- [ ] Actual `.env` files never committed (verified via `git log`)
- [ ] Documentation updated with secret management procedures