compose-lint¶
A security-focused linter for Docker Compose files. It tells you exactly what's wrong with a Compose file and exactly how to fix it — every rule cites OWASP, CIS, or Docker documentation, and runtime claims are re-proven against live containers in CI.
pip install compose-lint
compose-lint check docker-compose.yml
Findings come with actionable fix guidance in the output; compose-lint
--explain CL-XXXX prints any rule's full documentation (the same page you are
reading here) in the terminal.
Rules¶
| Rule | Checks for | Auto-fix |
|---|---|---|
| CL-0001 | Container runtime socket mounted | — |
| CL-0002 | Privileged mode enabled | — |
| CL-0003 | Privilege escalation not blocked (no-new-privileges missing) |
✅ |
| CL-0004 | Image not pinned to a version | — |
| CL-0005 | Ports bound to all interfaces | ✅ |
| CL-0006 | No capability restrictions (cap_drop: [ALL] missing) |
— |
| CL-0007 | Root filesystem not read-only | ✅ |
| CL-0008 | Host network mode | — |
| CL-0009 | Seccomp/AppArmor profile disabled | ✅ |
| CL-0010 | Host PID/IPC namespace sharing | — |
| CL-0011 | Strong host-adjacent capability added | — |
| CL-0013 | Sensitive host path exposed | — |
| CL-0014 | Logging driver disabled | ✅ |
| CL-0016 | Dangerous host device exposed | — |
| CL-0017 | Shared mount propagation | — |
| CL-0018 | Explicit root user | — |
| CL-0019 | Image tag without digest | — |
| CL-0020 | Credential-shaped env key with literal value | — |
| CL-0021 | Credential embedded in a connection-string env value | — |
| CL-0022 | tmpfs mount re-enables exec/suid | ✅ |
| CL-0024 | Host-code-execution capability added | — |
| CL-0025 | Root-equivalent host path mounted writable | — |
| CL-0026 | No resource limits (memory/CPU) | — |
| CL-0027 | Bounded-grant capability added | — |
| CL-0028 | Host-reaching capability added | — |
| CL-0029 | Host-availability capability added | — |
| CL-0030 | Host-disclosure capability added | — |
Where to start¶
- Configuration —
.compose-lint.yml, suppressions with reasons, per-service overrides, severity threshold (--fail-on). - Severity levels — how CRITICAL/HIGH/MEDIUM/LOW are assigned, and why severities are deliberately not inflated.
- GitHub Action — inputs, SHA pin versus
v1, and why thepermissions:block is part of the recipe. - Hardening walkthrough — taking a real Compose file from default to hardened, finding by finding.
- CL-0006's capability guide — how to determine the capabilities an image actually needs, with a verbatim error-message → capability table proven in CI.
Source, issues, and releases: github.com/tmatens/compose-lint