tmatens/compose-lint

# compose-lint [](https://github.com/tmatens/compose-lint/actions/workflows/ci.yml) [](https://pypi.org/project/compose-lint/) [](https://hub.docker.com/r/composelint/compose-lint) [](https://pypi.org/project/compose-lint/) [](LICENSE) 一个专注于安全的 Docker Compose 文件 linter。在危险配置进入生产环境之前将其捕获。 compose-lint 定位于 [Hadolint](https://github.com/hadolint/hadolint) 在 Dockerfiles 领域所占据的细分市场：零配置、观点鲜明、快速，并基于 [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html) 和 [CIS](https://www.cisecurity.org/benchmark/docker) 标准。 ## 安装说明 **pip** ``` pip install compose-lint ``` **Docker** — [composelint/compose-lint](https://hub.docker.com/r/composelint/compose-lint) ``` docker run --rm -v "$(pwd):/src" composelint/compose-lint ``` ## 快速开始 不带参数运行以自动检测当前目录中的 `compose.yml`、`compose.yaml`、`docker-compose.yml` 或 `docker-compose.yaml`： ``` compose-lint ``` 或显式传递文件： ``` compose-lint docker-compose.yml docker-compose.prod.yml ``` Docker 等效方式： ``` docker run --rm -v "$(pwd):/src" composelint/compose-lint docker-compose.prod.yml ``` ## 示例输出 ``` docker-compose.yml:5 CRITICAL CL-0001 Docker socket mounted via '/var/run/docker.sock:/var/run/docker.sock'. This gives the container full control over the Docker daemon. service: traefik fix: Use a Docker socket proxy (e.g., tecnativa/docker-socket-proxy) to expose only the API endpoints your service needs. ref: https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-1 docker-compose.yml:3 HIGH CL-0005 Port '8080:80' is bound to all interfaces. Docker bypasses host firewalls (UFW/firewalld), potentially exposing this port to the public internet. service: web fix: Bind to localhost: 127.0.0.1:8080:80 ref: https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-5a docker-compose.yml: 1 critical, 1 high ``` ## 规则 | ID | 严重程度 | 描述 | OWASP | CIS | |----|----------|-------------|-------|-----| | [CL-0001](docs/rules/CL-0001.md) | CRITICAL | 挂载了 Docker socket | [Rule #1](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-1---do-not-expose-the-docker-daemon-socket-even-to-the-containers) | 5.31 | | [CL-0002](docs/rules/CL-0002.md) | CRITICAL | 已启用特权模式 | [Rule #3](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-3---do-not-run-containers-with-the---privileged-flag) | 5.4 | | [CL-0003](docs/rules/CL-0003.md) | MEDIUM | 未阻止权限提升 | [Rule #4](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-4---add-no-new-privileges-flag) | 5.25 | | [CL-0004](docs/rules/CL-0004.md) | MEDIUM | 镜像未固定到具体版本 | [Rule #13](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-13---enhance-supply-chain-security) | 5.27 | | [CL-0005](docs/rules/CL-0005.md) | HIGH | 端口绑定到所有接口 | [Rule #5a](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-5a---be-careful-when-mapping-container-ports-to-the-host-with-firewalls-like-ufw) | 5.13 | | [CL-0006](docs/rules/CL-0006.md) | MEDIUM | 没有能力限制 | [Rule #3](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-3---limit-capabilities-grant-only-specific-capabilities-needed-by-a-container) | 5.3 | | [CL-0007](docs/rules/CL-0007.md) | MEDIUM | 文件系统非只读 | [Rule #8](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-8---set-filesystem-and-volumes-to-read-only) | 5.12 | | [CL-0008](docs/rules/CL-0008.md) | HIGH | 主机网络模式 | [Rule #5](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-5---be-mindful-of-inter-container-connectivity) | 5.9 | | [CL-0009](docs/rules/CL-0009.md) | HIGH | 安全配置文件已禁用 | [Rule #6](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-6---use-linux-security-module-seccomp-apparmor-or-selinux) | 5.21 | | [CL-0010](docs/rules/CL-0010.md) | HIGH | 共享主机命名空间 | [Rule #3](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-3---limit-capabilities-grant-only-specific-capabilities-needed-by-a-container) | 5.8, 5.15, 5.16, 5.21 | | [CL-0011](docs/rules/CL-0011.md) | HIGH | 添加了危险能力 | [Rule #3](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-3---limit-capabilities-grant-only-specific-capabilities-needed-by-a-container) | 5.5 | | [CL-0012](docs/rules/CL-0012.md) | MEDIUM | PIDs cgroup 限制已禁用 | — | 5.29 | | [CL-0013](docs/rules/CL-0013.md) | HIGH | 挂载了敏感主机路径 | [Rule #8](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-8---set-filesystem-and-volumes-to-read-only) | 5.5 | | [CL-0014](docs/rules/CL-0014.md) | MEDIUM | 日志驱动已禁用 | — | 5.x | | [CL-0015](docs/rules/CL-0015.md) | LOW | 健康检查已禁用 | — | 4.6, 5.27 | | [CL-0016](docs/rules/CL-0016.md) | HIGH | 暴露了危险主机设备 | — | 5.18 | | [CL-0017](docs/rules/CL-0017.md) | MEDIUM | 共享挂载传播 | — | 5.20 | | [CL-0018](docs/rules/CL-0018.md) | MEDIUM | 显式 root 用户 | [Rule #7](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-7---do-not-run-containers-with-a-root-user) | 5.x | | [CL-0019](docs/rules/CL-0019.md) | MEDIUM | 镜像标签不带摘要 | [Rule #13](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-13---enhance-supply-chain-security) | 5.27 | ## 严重程度等级 发现结果根据可利用性和影响范围被评为 **LOW**（低）、**MEDIUM**（中）、**HIGH**（高）或 **CRITICAL**（严重）。有关完整评分矩阵，请参阅 [docs/severity.md](docs/severity.md)。 ## 配置 创建 `.compose-lint.yml` 以禁用规则或调整严重程度： ``` rules: CL-0001: enabled: false CL-0003: enabled: false reason: "SEC-1234 — Approved by J. Smith, expires 2026-07-01" CL-0005: severity: medium ``` 被禁用的规则仍然会运行——发现结果显示为 **SUPPRESSED**，且不影响退出代码。`reason` 字段会出现在所有输出格式中： - **Text**：显示在 `SUPPRESSED` 标签之后 - **JSON**：`suppression_reason` 字段 - **SARIF**：`suppressions[].justification`（被 GitHub Code Scanning 识别） 要从输出中隐藏被抑制的发现结果： ``` compose-lint --skip-suppressed docker-compose.yml ``` ## CLI 参考 ``` compose-lint [OPTIONS] [FILE ...] --format {text,json,sarif} Output format (default: text) --fail-on SEVERITY Minimum severity to trigger exit 1 (default: high) --skip-suppressed Hide suppressed findings from output --config PATH Path to config file (default: .compose-lint.yml) --version Show version and exit ``` ## 退出代码 | 代码 | 含义 | |------|---------| | 0 | 没有达到或超过 `--fail-on` 阈值的发现结果 | | 1 | 有一个或多个达到或超过 `--fail-on` 阈值的发现结果 | | 2 | 使用错误（无效参数、文件未找到、无效的 Compose 文件） | 默认阈值为 `high` —— 除非你主动选择，否则中等和低级别的发现结果不会导致 CI 失败： ``` compose-lint --fail-on low docker-compose.yml # fail on everything compose-lint --fail-on critical docker-compose.yml # only critical ``` ## CI 集成 ### GitHub Actions 最简单的方式 —— 运行 compose-lint 并将发现结果上传到 GitHub Code Scanning： ``` # .github/workflows/lint.yml name: Compose Lint on: [push, pull_request] jobs: compose-lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: tmatens/compose-lint@v0.3.3 with: sarif-file: results.sarif ``` 或直接从 PyPI 安装： ``` - uses: actions/setup-python@v6 with: python-version: "3.13" - run: pip install compose-lint - run: compose-lint docker-compose.yml ``` ### SARIF 输出 ``` compose-lint --format sarif docker-compose.yml > results.sarif ``` ## Pre-commit ``` # .pre-commit-config.yaml repos: - repo: https://github.com/tmatens/compose-lint rev: v0.3.3 hooks: - id: compose-lint ``` ## 对比 | 工具 | Compose 安全规则 | 范围 | 零配置 | |------|----------------------|-------|-------------| | **compose-lint** | 是 | Docker Compose | 是 | | **KICS** | 是 | 广泛的 IaC (Terraform, K8s, Compose, ...) | 否 | | **Hadolint** | 否 — 仅 Dockerfile | Dockerfile | 是 | | **dclint** | 是 — 仅 schema/structure | Docker Compose | 是 | | **Trivy** | 否 — Dockerfile + 镜像扫描 | Dockerfiles, 镜像, 代码仓库 | 是 | | **Checkov** | 否 — 不支持 Compose | 广泛的 IaC (Terraform, K8s, ...) | 否 | 如果你需要跨 Terraform、Kubernetes 等的广泛 IaC 覆盖，KICS 支持 Docker Compose，值得评估。如果你想要一个轻量级、专注的零配置工具，并且能为 Compose 文件提供可操作的修复指导，这就是它。 ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置以及如何添加规则。 ## 许可证 [MIT](LICENSE)

标签：CIS 基准, DevSecOps, Docker, Docker Compose, Python 工具, Web截图, 上游代理, 云安全监控, 安全扫描, 安全防御评估, 容器安全, 时序注入, 最佳实践, 服务器监控, 请求拦截, 逆向工具, 静态分析