composelint/compose-lint repository overview

⁠compose-lint

Docker Compose security linter. Catches dangerous misconfigurations in compose.yml before they reach production — and auto-fixes the unambiguous ones, dry-run first. Grounded in the OWASP Docker Security Cheat Sheet⁠ and CIS Docker Benchmark⁠.

In a scan of 5,417 public Docker Compose files on GitHub, 91% of those that parse had at least one security finding — 32% had a finding rated HIGH or CRITICAL, and 10% had a CRITICAL. Read the full State of Docker Compose Security report →⁠

What it catches — 27 rules, each citing its OWASP/CIS grounding (full rules table⁠):

• Privilege flaws — privileged: true, missing cap_drop, no-new-privileges not set, root user, host namespace sharing
• Network exposure — wildcard port binds, network_mode: host
• Supply-chain — unpinned images, missing digest pins
• Filesystem and credential leaks — Docker socket mounts, sensitive host paths, plaintext credentials in environment:

⁠Usage

docker run --rm -v "$(pwd):/src" composelint/compose-lint            # lint the current directory
docker run --rm -v "$(pwd):/src" composelint/compose-lint fix        # preview auto-fixes (dry-run diff)
docker run --rm -v "$(pwd):/src" composelint/compose-lint --explain CL-0001

Auto-detects compose.yml / docker-compose.yml variants; pass filenames to lint specific files. fix --apply writes the mechanically unambiguous fixes in place (atomic, re-parsed and re-linted before writing); context-dependent findings are reported for manual review, never auto-edited. Unambiguous is not harmless — the guarantee is about the edit, not the outcome, so edits that change runtime behavior (e.g. read_only: true) are labelled ⚠ behavior-changing in the diff. Read those before --apply. Also on PyPI: pip install compose-lint (Python 3.11+).

⁠Exit codes

Output formats: human text (default), json, and sarif — SARIF uploads render findings and suggested fixes directly on GitHub pull requests. Suppressions live in a reviewable .compose-lint.yml with per-service reasons and stay visible in output, marked SUPPRESSED. See configuration⁠, the GitHub Action⁠, and CI integration recipes⁠ (GitHub Actions, GitLab, Forgejo/Gitea, pre-commit).

⁠This image

• Distroless Python⁠ on Debian, multi-arch (linux/amd64 + linux/arm64), nonroot UID 65532, no shell or package manager at runtime.
• Every release ships SLSA build provenance, Sigstore attestations, and an OpenVEX⁠ document; Docker Scout scans the published image daily. To verify an image's signature, see Verifying a release⁠.
• Tracked on OpenSSF Scorecard⁠ and OpenSSF Best Practices⁠.
• To run the container itself fully hardened, see Running with full hardening⁠.

⁠Links

Documentation⁠ · GitHub⁠ · PyPI⁠ · Rule docs⁠ · Changelog⁠ · Security policy⁠ · MIT license⁠