108 lines
3.1 KiB
Markdown
108 lines
3.1 KiB
Markdown
|
# Secure Docker CI/CD with BuildKit Secrets
|
||
|
|
|
||
|
|
This document explains how our CI/CD pipeline securely handles SSH keys using Docker BuildKit secrets.
|
||
|
|
|
||
|
|
## 🔒 Security Benefits
|
||
|
|
|
||
|
|
### Before (Insecure)
|
||
|
|
```dockerfile
|
||
|
|
ARG SSH_PRIVATE_KEY
|
||
|
|
RUN echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
|
||
|
|
```
|
||
|
|
- ❌ SSH key stored in Docker image layers
|
||
|
|
- ❌ Visible in `docker history`
|
||
|
|
- ❌ Can be extracted from images
|
||
|
|
- ❌ Security vulnerability
|
||
|
|
|
||
|
|
### After (Secure)
|
||
|
|
```dockerfile
|
||
|
|
RUN --mount=type=secret,id=ssh_private_key \
|
||
|
|
cp /run/secrets/ssh_private_key ~/.ssh/id_rsa && \
|
||
|
|
# ... use key ... && \
|
||
|
|
rm -rf ~/.ssh
|
||
|
|
```
|
||
|
|
- ✅ SSH key never stored in image layers
|
||
|
|
- ✅ Not visible in `docker history`
|
||
|
|
- ✅ Cannot be extracted from final image
|
||
|
|
- ✅ Secure by design
|
||
|
|
|
||
|
|
## 🏗️ CI/CD Pipeline Implementation
|
||
|
|
|
||
|
|
### Gitea Actions Workflow
|
||
|
|
The `.gitea/workflows/cicd.yml` file now uses:
|
||
|
|
|
||
|
|
1. **Docker BuildKit Enabled**
|
||
|
|
```yaml
|
||
|
|
export DOCKER_BUILDKIT=1
|
||
|
|
```
|
||
|
|
|
||
|
|
2. **Secure Secret Mounting**
|
||
|
|
```yaml
|
||
|
|
# Create temporary SSH key file
|
||
|
|
echo "${SSH_PRIVATE_KEY}" > /tmp/ssh_key
|
||
|
|
chmod 600 /tmp/ssh_key
|
||
|
|
|
||
|
|
# Build with secret mount
|
||
|
|
docker build -f Dockerfile.cicd \
|
||
|
|
--secret id=ssh_private_key,src=/tmp/ssh_key \
|
||
|
|
-t cicd:latest .
|
||
|
|
|
||
|
|
# Clean up immediately
|
||
|
|
rm -f /tmp/ssh_key
|
||
|
|
```
|
||
|
|
|
||
|
|
### Local Development
|
||
|
|
Use the secure build script:
|
||
|
|
```bash
|
||
|
|
./scripts/build-cicd-secure.sh plex-playlist-cicd:latest
|
||
|
|
```
|
||
|
|
|
||
|
|
## 🔧 Required Setup
|
||
|
|
|
||
|
|
### 1. Gitea Secrets Configuration
|
||
|
|
Ensure these secrets are configured in your Gitea repository:
|
||
|
|
- `SSH_PRIVATE_KEY`: Your private SSH key for git operations
|
||
|
|
- `GITEA_TOKEN`: Token for pushing to container registry
|
||
|
|
|
||
|
|
### 2. Docker BuildKit Support
|
||
|
|
- **Gitea Actions**: Automatically enabled with `DOCKER_BUILDKIT=1`
|
||
|
|
- **Local builds**: Requires Docker 18.09+ with BuildKit enabled
|
||
|
|
- **CI runners**: Ensure BuildKit support in your runner environment
|
||
|
|
|
||
|
|
## 📋 Best Practices Applied
|
||
|
|
|
||
|
|
1. **Temporary Files**: SSH keys are written to temporary files and immediately removed
|
||
|
|
2. **File Permissions**: SSH keys get proper 600 permissions
|
||
|
|
3. **Multi-stage Security**: Keys are cleaned up within the same RUN command
|
||
|
|
4. **No ARG Secrets**: Never pass secrets via build arguments
|
||
|
|
5. **Dockerignore Protection**: `.dockerignore` prevents accidental secret inclusion
|
||
|
|
|
||
|
|
## 🧪 Testing Security
|
||
|
|
|
||
|
|
Verify no secrets in image:
|
||
|
|
```bash
|
||
|
|
# Build the image
|
||
|
|
./scripts/build-cicd-secure.sh test-image
|
||
|
|
|
||
|
|
# Check history (should show no secrets)
|
||
|
|
docker history test-image
|
||
|
|
|
||
|
|
# Try to find SSH keys (should find none)
|
||
|
|
docker run --rm test-image find / -name "*rsa*" -o -name "*ssh*" 2>/dev/null
|
||
|
|
```
|
||
|
|
|
||
|
|
## 🚀 Migration Checklist
|
||
|
|
|
||
|
|
- [x] Updated Dockerfile.cicd to use `--mount=type=secret`
|
||
|
|
- [x] Removed insecure `ARG SSH_PRIVATE_KEY`
|
||
|
|
- [x] Modified CI/CD workflow to use BuildKit secrets
|
||
|
|
- [x] Added `.dockerignore` patterns for SSH keys
|
||
|
|
- [x] Created secure build script
|
||
|
|
- [x] Documented security improvements
|
||
|
|
|
||
|
|
## 📚 References
|
||
|
|
|
||
|
|
- [Docker BuildKit Secrets](https://docs.docker.com/build/building/secrets/)
|
||
|
|
- [Docker Security Best Practices](https://docs.docker.com/develop/security-best-practices/)
|
||
|
|
- [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/)
|