@devo-bmad-custom/agent-orchestration 1.0.1 → 1.0.3

package/src/.agents/skills/security-review/infrastructure/docker.md

@@ -1,432 +1,432 @@
-# Docker Security Reference
-
-## Overview
-
-Container security involves the Dockerfile, image composition, runtime configuration, and orchestration. Misconfigurations can lead to container escapes, privilege escalation, or exposure of sensitive data.
-
----
-
-## Dockerfile Security
-
-### Running as Root
-
-```dockerfile
-# VULNERABLE: Running as root (default)
-FROM node:18
-COPY . /app
-CMD ["node", "app.js"]  # Runs as root
-
-# SAFE: Non-root user
-FROM node:18
-RUN groupadd -r appgroup && useradd -r -g appgroup appuser
-WORKDIR /app
-COPY --chown=appuser:appgroup . .
-USER appuser
-CMD ["node", "app.js"]
-
-# SAFE: Using numeric UID (more portable)
-USER 1000:1000
-```
-
-### Base Image Issues
-
-```dockerfile
-# VULNERABLE: Using latest tag (unpredictable)
-FROM node:latest
-FROM ubuntu:latest
-
-# VULNERABLE: Using untrusted/unverified base image
-FROM randomuser/myimage
-
-# SAFE: Pinned versions with digest
-FROM node:18.19.0-alpine@sha256:abc123...
-FROM python:3.11.7-slim-bookworm
-
-# SAFE: Official images from verified publishers
-FROM docker.io/library/node:18.19.0-alpine
-```
-
-### Sensitive Data in Images
-
-```dockerfile
-# VULNERABLE: Secrets in build args visible in history
-ARG DB_PASSWORD
-RUN echo $DB_PASSWORD > /config
-
-# VULNERABLE: Copying secrets into image
-COPY .env /app/.env
-COPY secrets.json /app/
-COPY id_rsa /root/.ssh/
-
-# VULNERABLE: Secrets in environment variables
-ENV API_KEY=sk-12345
-ENV DB_PASSWORD=mysecret
-
-# SAFE: Mount secrets at runtime
-# docker run -v /secrets:/secrets:ro myimage
-# Or use Docker secrets in Swarm/K8s
-```
-
-### Build-Time Secrets
-
-```dockerfile
-# SAFE: Multi-stage build to exclude secrets
-FROM node:18 AS builder
-# Use build-time secret (Docker BuildKit)
-RUN --mount=type=secret,id=npm_token \
-    NPM_TOKEN=$(cat /run/secrets/npm_token) npm install
-
-FROM node:18-alpine
-COPY --from=builder /app/node_modules /app/node_modules
-# Secret not in final image
-
-# Build with: docker build --secret id=npm_token,src=.npmrc .
-```
-
-### Package Installation
-
-```dockerfile
-# VULNERABLE: Not cleaning up package manager cache
-RUN apt-get update && apt-get install -y curl wget
-# Leaves cache, increases image size and attack surface
-
-# VULNERABLE: Installing unnecessary packages
-RUN apt-get install -y vim nano curl wget git ssh
-
-# SAFE: Minimal installation with cleanup
-RUN apt-get update && \
-    apt-get install -y --no-install-recommends curl && \
-    rm -rf /var/lib/apt/lists/*
-
-# SAFE: Using minimal base images
-FROM alpine:3.19
-FROM gcr.io/distroless/nodejs18
-FROM scratch  # Empty base image
-```
-
-### COPY vs ADD
-
-```dockerfile
-# VULNERABLE: ADD can auto-extract and fetch URLs
-ADD https://example.com/file.tar.gz /app/  # Downloads from URL
-ADD archive.tar.gz /app/  # Auto-extracts
-
-# SAFE: COPY is more explicit
-COPY archive.tar.gz /app/
-RUN tar -xzf /app/archive.tar.gz && rm /app/archive.tar.gz
-```
-
-### Exposed Ports
-
-```dockerfile
-# CHECK: Are all exposed ports necessary?
-EXPOSE 22  # FLAG: SSH in container usually unnecessary
-EXPOSE 3306  # FLAG: Database port exposed
-EXPOSE 80 443 8080 9090 5000  # CHECK: Multiple ports
-
-# SAFE: Only expose what's needed
-EXPOSE 8080
-```
-
----
-
-## Image Scanning
-
-### Vulnerability Patterns
-
-```bash
-# Scan for vulnerabilities
-docker scan myimage
-trivy image myimage
-grype myimage
-
-# Check for secrets in image
-trufflehog docker --image myimage
-# Or manually inspect layers
-docker history --no-trunc myimage
-```
-
-### High-Risk Packages
-
-```dockerfile
-# FLAG: Packages that increase attack surface
-RUN apt-get install -y \
-    openssh-server \  # SSH access
-    sudo \            # Privilege escalation
-    netcat \          # Network tools
-    nmap \            # Network scanning
-    gcc make \        # Compilers (should be in build stage only)
-    python3-pip       # Package managers (install deps, then remove)
-```
-
----
-
-## Runtime Security
-
-### Privileged Mode
-
-```bash
-# VULNERABLE: Running privileged (full host access)
-docker run --privileged myimage
-
-# VULNERABLE: Dangerous capabilities
-docker run --cap-add=ALL myimage
-docker run --cap-add=SYS_ADMIN myimage
-docker run --cap-add=NET_ADMIN myimage
-
-# SAFE: Drop all capabilities, add only needed
-docker run --cap-drop=ALL --cap-add=NET_BIND_SERVICE myimage
-
-# SAFE: Read-only root filesystem
-docker run --read-only myimage
-
-# SAFE: No new privileges
-docker run --security-opt=no-new-privileges myimage
-```
-
-### Volume Mounts
-
-```bash
-# VULNERABLE: Mounting sensitive host paths
-docker run -v /:/host myimage           # Entire host filesystem
-docker run -v /etc:/etc myimage         # Host config files
-docker run -v /var/run/docker.sock:/var/run/docker.sock  # Docker socket
-
-# VULNERABLE: Writable mounts of sensitive paths
-docker run -v /etc/passwd:/etc/passwd myimage
-
-# SAFE: Specific paths, read-only where possible
-docker run -v /app/data:/data:ro myimage
-docker run -v myvolume:/app/data myimage  # Named volume
-```
-
-### Docker Socket Access
-
-```bash
-# CRITICAL: Docker socket mount = root on host
-docker run -v /var/run/docker.sock:/var/run/docker.sock myimage
-# Container can create privileged containers, access host
-
-# If required, use read-only and restrict with authz plugin
-# Or use Docker API proxy with limited permissions
-```
-
-### Network Security
-
-```bash
-# VULNERABLE: Host network mode
-docker run --network=host myimage  # No network isolation
-
-# SAFE: User-defined networks with isolation
-docker network create --internal internal-net  # No external access
-docker run --network=internal-net myimage
-
-# SAFE: Restrict inter-container communication
-docker network create --driver=bridge --opt com.docker.network.bridge.enable_icc=false isolated
-```
-
-### Resource Limits
-
-```bash
-# VULNERABLE: No resource limits (DoS risk)
-docker run myimage
-
-# SAFE: Set memory and CPU limits
-docker run --memory=512m --cpus=1 myimage
-
-# SAFE: Limit processes
-docker run --pids-limit=100 myimage
-```
-
----
-
-## Docker Compose Security
-
-### Secrets Management
-
-```yaml
-# VULNERABLE: Secrets in environment
-services:
-  app:
-    environment:
-      - DB_PASSWORD=mysecret
-      - API_KEY=sk-12345
-
-# SAFE: Use secrets
-services:
-  app:
-    secrets:
-      - db_password
-    environment:
-      - DB_PASSWORD_FILE=/run/secrets/db_password
-
-secrets:
-  db_password:
-    external: true  # Or file: ./secrets/db_password
-```
-
-### Privilege Restrictions
-
-```yaml
-# SAFE: Security options in compose
-services:
-  app:
-    image: myimage
-    user: "1000:1000"
-    read_only: true
-    security_opt:
-      - no-new-privileges:true
-    cap_drop:
-      - ALL
-    cap_add:
-      - NET_BIND_SERVICE
-    tmpfs:
-      - /tmp
-    deploy:
-      resources:
-        limits:
-          memory: 512M
-          cpus: '1'
-```
-
-### Network Isolation
-
-```yaml
-# SAFE: Internal networks for backend services
-services:
-  frontend:
-    networks:
-      - public
-      - internal
-
-  backend:
-    networks:
-      - internal  # Not accessible from outside
-
-  database:
-    networks:
-      - internal
-
-networks:
-  public:
-  internal:
-    internal: true  # No external access
-```
-
----
-
-## .dockerignore
-
-### Required Exclusions
-
-```dockerignore
-# SAFE: Exclude sensitive files
-.env
-.env.*
-*.pem
-*.key
-id_rsa*
-secrets/
-credentials/
-.git/
-.gitignore
-.dockerignore
-Dockerfile
-docker-compose*.yml
-*.log
-node_modules/
-__pycache__/
-.pytest_cache/
-coverage/
-.nyc_output/
-```
-
-### Missing .dockerignore
-
-```bash
-# FLAG: No .dockerignore may copy secrets into image
-# Check if .env, keys, or credentials are copied
-```
-
----
-
-## Registry Security
-
-### Image Pull Policy
-
-```yaml
-# VULNERABLE: Always pulling latest
-image: myregistry/myimage:latest
-
-# VULNERABLE: No digest verification
-image: myregistry/myimage:1.0
-
-# SAFE: Pinned with digest
-image: myregistry/myimage@sha256:abc123...
-```
-
-### Private Registry Auth
-
-```bash
-# VULNERABLE: Credentials in plain text
-docker login -u user -p password registry.example.com
-
-# SAFE: Use credential helpers
-# ~/.docker/config.json
-{
-  "credHelpers": {
-    "gcr.io": "gcloud",
-    "*.dkr.ecr.*.amazonaws.com": "ecr-login"
-  }
-}
-```
-
----
-
-## Grep Patterns for Dockerfiles
-
-```bash
-# Running as root
-grep -rn "^USER" Dockerfile || echo "No USER directive - runs as root"
-
-# Secrets in environment
-grep -rn "^ENV.*PASSWORD\|^ENV.*SECRET\|^ENV.*KEY\|^ENV.*TOKEN" Dockerfile
-
-# Secrets in build args
-grep -rn "^ARG.*PASSWORD\|^ARG.*SECRET\|^ARG.*KEY" Dockerfile
-
-# Latest tags
-grep -rn "FROM.*:latest\|FROM.*@" Dockerfile | grep -v "@sha256"
-
-# Privileged instructions
-grep -rn "^ADD\|EXPOSE 22\|apt-get install.*ssh" Dockerfile
-
-# Missing cleanup
-grep -rn "apt-get install" Dockerfile | grep -v "rm -rf"
-```
-
----
-
-## Testing Checklist
-
-- [ ] Container runs as non-root user
-- [ ] Base image is pinned with digest
-- [ ] No secrets in image layers (ENV, ARG, COPY)
-- [ ] Multi-stage build for secrets/build tools
-- [ ] Minimal base image (alpine, distroless)
-- [ ] Package manager cache cleaned
-- [ ] .dockerignore excludes sensitive files
-- [ ] No --privileged or dangerous capabilities
-- [ ] No Docker socket mount
-- [ ] Resource limits configured
-- [ ] Network isolation configured
-- [ ] Image scanned for vulnerabilities
-- [ ] Read-only root filesystem where possible
-
----
-
-## References
-
-- [Docker Security Best Practices](https://docs.docker.com/develop/security-best-practices/)
-- [CIS Docker Benchmark](https://www.cisecurity.org/benchmark/docker)
-- [OWASP Docker Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html)
+# Docker Security Reference
+
+## Overview
+
+Container security involves the Dockerfile, image composition, runtime configuration, and orchestration. Misconfigurations can lead to container escapes, privilege escalation, or exposure of sensitive data.
+
+---
+
+## Dockerfile Security
+
+### Running as Root
+
+```dockerfile
+# VULNERABLE: Running as root (default)
+FROM node:18
+COPY . /app
+CMD ["node", "app.js"]  # Runs as root
+
+# SAFE: Non-root user
+FROM node:18
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+WORKDIR /app
+COPY --chown=appuser:appgroup . .
+USER appuser
+CMD ["node", "app.js"]
+
+# SAFE: Using numeric UID (more portable)
+USER 1000:1000
+```
+
+### Base Image Issues
+
+```dockerfile
+# VULNERABLE: Using latest tag (unpredictable)
+FROM node:latest
+FROM ubuntu:latest
+
+# VULNERABLE: Using untrusted/unverified base image
+FROM randomuser/myimage
+
+# SAFE: Pinned versions with digest
+FROM node:18.19.0-alpine@sha256:abc123...
+FROM python:3.11.7-slim-bookworm
+
+# SAFE: Official images from verified publishers
+FROM docker.io/library/node:18.19.0-alpine
+```
+
+### Sensitive Data in Images
+
+```dockerfile
+# VULNERABLE: Secrets in build args visible in history
+ARG DB_PASSWORD
+RUN echo $DB_PASSWORD > /config
+
+# VULNERABLE: Copying secrets into image
+COPY .env /app/.env
+COPY secrets.json /app/
+COPY id_rsa /root/.ssh/
+
+# VULNERABLE: Secrets in environment variables
+ENV API_KEY=sk-12345
+ENV DB_PASSWORD=mysecret
+
+# SAFE: Mount secrets at runtime
+# docker run -v /secrets:/secrets:ro myimage
+# Or use Docker secrets in Swarm/K8s
+```
+
+### Build-Time Secrets
+
+```dockerfile
+# SAFE: Multi-stage build to exclude secrets
+FROM node:18 AS builder
+# Use build-time secret (Docker BuildKit)
+RUN --mount=type=secret,id=npm_token \
+    NPM_TOKEN=$(cat /run/secrets/npm_token) npm install
+
+FROM node:18-alpine
+COPY --from=builder /app/node_modules /app/node_modules
+# Secret not in final image
+
+# Build with: docker build --secret id=npm_token,src=.npmrc .
+```
+
+### Package Installation
+
+```dockerfile
+# VULNERABLE: Not cleaning up package manager cache
+RUN apt-get update && apt-get install -y curl wget
+# Leaves cache, increases image size and attack surface
+
+# VULNERABLE: Installing unnecessary packages
+RUN apt-get install -y vim nano curl wget git ssh
+
+# SAFE: Minimal installation with cleanup
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends curl && \
+    rm -rf /var/lib/apt/lists/*
+
+# SAFE: Using minimal base images
+FROM alpine:3.19
+FROM gcr.io/distroless/nodejs18
+FROM scratch  # Empty base image
+```
+
+### COPY vs ADD
+
+```dockerfile
+# VULNERABLE: ADD can auto-extract and fetch URLs
+ADD https://example.com/file.tar.gz /app/  # Downloads from URL
+ADD archive.tar.gz /app/  # Auto-extracts
+
+# SAFE: COPY is more explicit
+COPY archive.tar.gz /app/
+RUN tar -xzf /app/archive.tar.gz && rm /app/archive.tar.gz
+```
+
+### Exposed Ports
+
+```dockerfile
+# CHECK: Are all exposed ports necessary?
+EXPOSE 22  # FLAG: SSH in container usually unnecessary
+EXPOSE 3306  # FLAG: Database port exposed
+EXPOSE 80 443 8080 9090 5000  # CHECK: Multiple ports
+
+# SAFE: Only expose what's needed
+EXPOSE 8080
+```
+
+---
+
+## Image Scanning
+
+### Vulnerability Patterns
+
+```bash
+# Scan for vulnerabilities
+docker scan myimage
+trivy image myimage
+grype myimage
+
+# Check for secrets in image
+trufflehog docker --image myimage
+# Or manually inspect layers
+docker history --no-trunc myimage
+```
+
+### High-Risk Packages
+
+```dockerfile
+# FLAG: Packages that increase attack surface
+RUN apt-get install -y \
+    openssh-server \  # SSH access
+    sudo \            # Privilege escalation
+    netcat \          # Network tools
+    nmap \            # Network scanning
+    gcc make \        # Compilers (should be in build stage only)
+    python3-pip       # Package managers (install deps, then remove)
+```
+
+---
+
+## Runtime Security
+
+### Privileged Mode
+
+```bash
+# VULNERABLE: Running privileged (full host access)
+docker run --privileged myimage
+
+# VULNERABLE: Dangerous capabilities
+docker run --cap-add=ALL myimage
+docker run --cap-add=SYS_ADMIN myimage
+docker run --cap-add=NET_ADMIN myimage
+
+# SAFE: Drop all capabilities, add only needed
+docker run --cap-drop=ALL --cap-add=NET_BIND_SERVICE myimage
+
+# SAFE: Read-only root filesystem
+docker run --read-only myimage
+
+# SAFE: No new privileges
+docker run --security-opt=no-new-privileges myimage
+```
+
+### Volume Mounts
+
+```bash
+# VULNERABLE: Mounting sensitive host paths
+docker run -v /:/host myimage           # Entire host filesystem
+docker run -v /etc:/etc myimage         # Host config files
+docker run -v /var/run/docker.sock:/var/run/docker.sock  # Docker socket
+
+# VULNERABLE: Writable mounts of sensitive paths
+docker run -v /etc/passwd:/etc/passwd myimage
+
+# SAFE: Specific paths, read-only where possible
+docker run -v /app/data:/data:ro myimage
+docker run -v myvolume:/app/data myimage  # Named volume
+```
+
+### Docker Socket Access
+
+```bash
+# CRITICAL: Docker socket mount = root on host
+docker run -v /var/run/docker.sock:/var/run/docker.sock myimage
+# Container can create privileged containers, access host
+
+# If required, use read-only and restrict with authz plugin
+# Or use Docker API proxy with limited permissions
+```
+
+### Network Security
+
+```bash
+# VULNERABLE: Host network mode
+docker run --network=host myimage  # No network isolation
+
+# SAFE: User-defined networks with isolation
+docker network create --internal internal-net  # No external access
+docker run --network=internal-net myimage
+
+# SAFE: Restrict inter-container communication
+docker network create --driver=bridge --opt com.docker.network.bridge.enable_icc=false isolated
+```
+
+### Resource Limits
+
+```bash
+# VULNERABLE: No resource limits (DoS risk)
+docker run myimage
+
+# SAFE: Set memory and CPU limits
+docker run --memory=512m --cpus=1 myimage
+
+# SAFE: Limit processes
+docker run --pids-limit=100 myimage
+```
+
+---
+
+## Docker Compose Security
+
+### Secrets Management
+
+```yaml
+# VULNERABLE: Secrets in environment
+services:
+  app:
+    environment:
+      - DB_PASSWORD=mysecret
+      - API_KEY=sk-12345
+
+# SAFE: Use secrets
+services:
+  app:
+    secrets:
+      - db_password
+    environment:
+      - DB_PASSWORD_FILE=/run/secrets/db_password
+
+secrets:
+  db_password:
+    external: true  # Or file: ./secrets/db_password
+```
+
+### Privilege Restrictions
+
+```yaml
+# SAFE: Security options in compose
+services:
+  app:
+    image: myimage
+    user: "1000:1000"
+    read_only: true
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    cap_add:
+      - NET_BIND_SERVICE
+    tmpfs:
+      - /tmp
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: '1'
+```
+
+### Network Isolation
+
+```yaml
+# SAFE: Internal networks for backend services
+services:
+  frontend:
+    networks:
+      - public
+      - internal
+
+  backend:
+    networks:
+      - internal  # Not accessible from outside
+
+  database:
+    networks:
+      - internal
+
+networks:
+  public:
+  internal:
+    internal: true  # No external access
+```
+
+---
+
+## .dockerignore
+
+### Required Exclusions
+
+```dockerignore
+# SAFE: Exclude sensitive files
+.env
+.env.*
+*.pem
+*.key
+id_rsa*
+secrets/
+credentials/
+.git/
+.gitignore
+.dockerignore
+Dockerfile
+docker-compose*.yml
+*.log
+node_modules/
+__pycache__/
+.pytest_cache/
+coverage/
+.nyc_output/
+```
+
+### Missing .dockerignore
+
+```bash
+# FLAG: No .dockerignore may copy secrets into image
+# Check if .env, keys, or credentials are copied
+```
+
+---
+
+## Registry Security
+
+### Image Pull Policy
+
+```yaml
+# VULNERABLE: Always pulling latest
+image: myregistry/myimage:latest
+
+# VULNERABLE: No digest verification
+image: myregistry/myimage:1.0
+
+# SAFE: Pinned with digest
+image: myregistry/myimage@sha256:abc123...
+```
+
+### Private Registry Auth
+
+```bash
+# VULNERABLE: Credentials in plain text
+docker login -u user -p password registry.example.com
+
+# SAFE: Use credential helpers
+# ~/.docker/config.json
+{
+  "credHelpers": {
+    "gcr.io": "gcloud",
+    "*.dkr.ecr.*.amazonaws.com": "ecr-login"
+  }
+}
+```
+
+---
+
+## Grep Patterns for Dockerfiles
+
+```bash
+# Running as root
+grep -rn "^USER" Dockerfile || echo "No USER directive - runs as root"
+
+# Secrets in environment
+grep -rn "^ENV.*PASSWORD\|^ENV.*SECRET\|^ENV.*KEY\|^ENV.*TOKEN" Dockerfile
+
+# Secrets in build args
+grep -rn "^ARG.*PASSWORD\|^ARG.*SECRET\|^ARG.*KEY" Dockerfile
+
+# Latest tags
+grep -rn "FROM.*:latest\|FROM.*@" Dockerfile | grep -v "@sha256"
+
+# Privileged instructions
+grep -rn "^ADD\|EXPOSE 22\|apt-get install.*ssh" Dockerfile
+
+# Missing cleanup
+grep -rn "apt-get install" Dockerfile | grep -v "rm -rf"
+```
+
+---
+
+## Testing Checklist
+
+- [ ] Container runs as non-root user
+- [ ] Base image is pinned with digest
+- [ ] No secrets in image layers (ENV, ARG, COPY)
+- [ ] Multi-stage build for secrets/build tools
+- [ ] Minimal base image (alpine, distroless)
+- [ ] Package manager cache cleaned
+- [ ] .dockerignore excludes sensitive files
+- [ ] No --privileged or dangerous capabilities
+- [ ] No Docker socket mount
+- [ ] Resource limits configured
+- [ ] Network isolation configured
+- [ ] Image scanned for vulnerabilities
+- [ ] Read-only root filesystem where possible
+
+---
+
+## References
+
+- [Docker Security Best Practices](https://docs.docker.com/develop/security-best-practices/)
+- [CIS Docker Benchmark](https://www.cisecurity.org/benchmark/docker)
+- [OWASP Docker Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html)