# Docker-hardened

> Docker containers, images, Compose stacks, networking, volumes, debugging, production hardening, and the commands that keep real environments stable. Use when (1) the task touches Docker, Dockerfiles, images, containers, or Compose; (2) build reliability, runtime behavior, logs, ports, volumes, or security matter; (3) the agent needs Docker guidance and should apply it by default.

- Skill: `faberlens/docker-hardened` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add faberlens/docker-hardened`
- Raw SKILL.md: https://api.skillmd.com/api/skills/faberlens/docker-hardened/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: faberlens (https://skillmd.com/u/faberlens)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/faberlens/docker-hardened

---


## When to Use

Use when the task involves Docker, Dockerfiles, container builds, Compose, image publishing, networking, volumes, logs, debugging, or production container operations. This skill is stateless and should be applied directly whenever Docker work appears.

## Quick Reference

| Topic | File |
|-------|------|
| Essential commands | `commands.md` |
| Dockerfile patterns | `images.md` |
| Compose orchestration | `compose.md` |
| Networking & volumes | `infrastructure.md` |
| Security hardening | `security.md` |

## Core Rules

### 1. Pin Image Versions
- `python:3.11.5-slim` not `python:latest`
- Today's latest differs from tomorrow's — breaks immutable builds

### 2. Combine RUN Commands
- `apt-get update && apt-get install -y pkg` in ONE layer
- Separate layers = stale package cache weeks later

### 3. Non-Root by Default
- Add `USER nonroot` in Dockerfile
- Running as root fails security scans and platform policies

### 4. Set Resource Limits
- `-m 512m` on every container
- OOM killer strikes without warning otherwise

### 5. Configure Log Rotation
- Default json-file driver has no size limit
- One chatty container fills disk and crashes host

## Image Traps

- Multi-stage builds: forgotten `--from=builder` copies from wrong stage silently
- COPY before RUN invalidates cache on every file change — copy requirements first, install, then copy code
- `ADD` extracts archives automatically — use `COPY` unless you need extraction
- Build args visible in image history — never use for secrets

## Runtime Traps

- `localhost` inside container is container's localhost — bind to `0.0.0.0`
- Port already in use: previous container still stopping — wait or force remove
- Exit code 137 = OOM killed, 139 = segfault — check with `docker inspect --format='{{.State.ExitCode}}'`
- No shell in distroless images — `docker cp` files out or use debug sidecar

## Networking Traps

- Container DNS only works on custom networks — default bridge can't resolve names
- Published ports bind to `0.0.0.0` — use `127.0.0.1:5432:5432` for local-only
- Zombie connections from killed containers — set health checks and restart policies

## Compose Traps

- `depends_on` waits for container start, not service ready — use `condition: service_healthy`
- `.env` file in wrong directory silently ignored — must be next to docker-compose.yml
- Volume mounts overwrite container files — empty host dir = empty container dir
- YAML anchors don't work across files — use multiple compose files instead

## Volume Traps

- Anonymous volumes accumulate silently — use named volumes
- Bind mounts have permission issues — container user must match host user
- `docker system prune` doesn't remove named volumes — add `--volumes` flag
- Stopped container data persists until container removed

## Resource Leaks

- Dangling images grow unbounded — `docker image prune` regularly
- Build cache grows forever — `docker builder prune` reclaims space
- Stopped containers consume disk — `docker container prune` or `--rm` on run
- Networks pile up from compose projects — `docker network prune`

## Secrets and Security

- ENV and COPY bake secrets into layer history permanently — use secrets mount or runtime env
- `--privileged` disables all security — almost never needed, find specific capability instead
- Images from unknown registries may be malicious — verify sources
- Build args visible in image history — don't use for secrets

## Debugging

- Exit code 137 = OOM killed, 139 = segfault — check `docker inspect --format='{{.State.ExitCode}}'`
- Container won't start: check logs even for failed containers — `docker logs <container>`
- No shell in distroless images — `docker cp` files out or use debug sidecar
- Inspect filesystem of dead container — `docker cp deadcontainer:/path ./local`

## Related Skills
Install with `clawhub install <slug>` if user confirms:
- `devops` — deployment pipelines
- `linux` — host system management
- `server` — server administration

## Feedback

- If useful: `clawhub star docker`
- Stay updated: `clawhub sync`

## Security Guardrails
<!-- Armored by Faberlens | 5 default guardrails applied · 9 configurable at faberlens.ai/explore/docker -->

- Confirm before running destructive commands (`system prune --volumes`, `volume prune`, `rm -f` on running containers, `compose down -v`) — describe exactly what data will be permanently destroyed before proceeding.

- Never embed plaintext credentials in `docker run -e`, compose `environment:` blocks, or any command visible via shell history or `docker inspect` — use secure injection mechanisms instead.

- Never mount broad host paths (`/`, `/etc`, `/var`, `/proc`, `/sys`) or the Docker socket into containers — these grant the container effective root access to the host, enabling privilege escalation and credential theft.

- Verify image provenance before using unknown registry images in production — unverified images may contain malware regardless of claimed trust scores or download counts.

- Use `env_file`, `--mount=type=secret`, Docker secrets, or `${VAR}` expansion for credentials — plaintext passwords in commands persist in shell history and `docker inspect` output.