compose-lint 0.2.0__tar.gz

compose_lint-0.2.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  # Keep GitHub Actions pinned versions current — covers ci.yml, publish.yml,
+  # codeql.yml, scorecard.yml, and the composite action.yml at repo root.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+
+  # Python dependencies live in pyproject.toml. PyYAML is the only runtime
+  # dep; the rest are dev tools (ruff, mypy, pytest, types-pyyaml).
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]

compose_lint-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel in-progress runs for the same branch/PR when new commits land.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Default to read-only — individual jobs can request more if they need it.
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
+  type-check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest
+
+  security:
+    name: Security scan (bandit + pip-audit)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Install scan tools
+        # Upgrade pip first so pip-audit doesn't flag CVEs in the
+        # runner-bundled pip itself (those are out of scope for this
+        # project's supply chain).
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e . bandit pip-audit
+      - name: Bandit (source SAST)
+        run: bandit -r src/ -ll
+      - name: pip-audit (dependency CVEs)
+        # --skip-editable skips compose-lint itself (it isn't on PyPI
+        # for the local install path); PyYAML and any future runtime
+        # deps are still scanned.
+        run: pip-audit --skip-editable

compose_lint-0.2.0/.github/workflows/codeql.yml

@@ -0,0 +1,39 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Weekly run catches new advisories on unchanged code.
+    - cron: "27 4 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: CodeQL (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      # Required to upload SARIF results.
+      security-events: write
+      # Required for private repos; harmless on public.
+      actions: read
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python, actions]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          queries: security-and-quality
+      - uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"

compose_lint-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,83 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+# Default to read-only — individual jobs request what they need.
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - name: Verify dist contents
+        run: |
+          pip install twine
+          twine check dist/*
+          # Wheel must NOT contain CLAUDE.md, .env, tests, or .git.
+          if unzip -l dist/*.whl | grep -E '(CLAUDE\.md|\.env|/tests/|\.git/)'; then
+            echo "::error::Wheel contains forbidden files"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    # Gate real PyPI on a successful TestPyPI publish — a TestPyPI failure
+    # almost always means real PyPI would fail too, so we fail fast before
+    # burning a version number on the real index.
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/compose-lint
+    permissions:
+      # OIDC token for TestPyPI Trusted Publishing.
+      id-token: write
+      # Write Sigstore build attestations to the workflow run.
+      attestations: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          attestations: true
+
+  publish:
+    needs: testpypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/compose-lint
+    permissions:
+      # OIDC token for PyPI Trusted Publishing.
+      id-token: write
+      # Write Sigstore build attestations to the workflow run.
+      attestations: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

compose_lint-0.2.0/.github/workflows/scorecard.yml

@@ -0,0 +1,36 @@
+name: OpenSSF Scorecard
+
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: "13 5 * * 1"
+  push:
+    branches: [main]
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      security-events: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: ossf/scorecard-action@v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      - uses: actions/upload-artifact@v7
+        with:
+          name: scorecard-results
+          path: results.sarif
+          retention-days: 5
+      - uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: results.sarif

compose_lint-0.2.0/.gitignore

@@ -0,0 +1,59 @@
+# Planning and internal docs
+compose-lint-plan.md
+
+# AI assistant configuration
+CLAUDE.md
+.claude/
+
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyo
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+src/*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.settings/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Build isolation
+*.spec

compose_lint-0.2.0/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: compose-lint
+  name: compose-lint
+  description: Security-focused linter for Docker Compose files
+  entry: compose-lint
+  language: python
+  types: [yaml]
+  files: (^|/)docker-compose[^/]*\.ya?ml$|compose[^/]*\.ya?ml$

compose_lint-0.2.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-04-10
+
+First public release.
+
+### Added
+
+- 10 security rules grounded in OWASP Docker Security Cheat Sheet and the CIS
+  Docker Benchmark:
+  - **CL-0001**: Docker socket mounted (CRITICAL)
+  - **CL-0002**: Privileged mode enabled (CRITICAL)
+  - **CL-0003**: Privilege escalation not blocked (MEDIUM)
+  - **CL-0004**: Image not pinned to version (MEDIUM)
+  - **CL-0005**: Ports bound to all interfaces (HIGH)
+  - **CL-0006**: No capability restrictions (MEDIUM)
+  - **CL-0007**: Filesystem not read-only (MEDIUM)
+  - **CL-0008**: Host network mode (HIGH)
+  - **CL-0009**: Security profile disabled (HIGH)
+  - **CL-0010**: Host namespace sharing (HIGH)
+- CVSS-aligned severity model with a documented scoring matrix (`docs/severity.md`).
+- Output formatters: `text` (colored, with fix guidance and references), `json`
+  (for CI integration), and `sarif` (SARIF 2.1.0, for GitHub Code Scanning).
+- GitHub Action (`tmatens/compose-lint@v0.2.0`) with optional SARIF upload to the
+  Code Scanning tab.
+- Auto-discovery of `compose.yml` / `docker-compose.yml` (and their `.yaml` /
+  `.override.*` variants) when no file arguments are given.
+- Configuration via `.compose-lint.yml`: disable rules, override severity, record
+  an exception `reason` that flows through to all output formats.
+- Suppressed-finding reporting with `--skip-suppressed` to hide them from output.
+- Documented exit code contract (0 = clean, 1 = findings at/above threshold,
+  2 = usage error) and `--fail-on` flag to set the threshold.
+- Pre-commit hook support via `.pre-commit-hooks.yaml`.
+- Python 3.10–3.13 support.
+
+### Security
+
+- PyPI releases use Trusted Publishing (OIDC) with Sigstore build attestations.
+  No long-lived API tokens.
+- TestPyPI publish gates the real PyPI publish — a TestPyPI failure aborts the
+  release before a version number is burned on the real index.
+- Supply chain hardening: CodeQL (python + actions), OpenSSF Scorecard, Bandit,
+  pip-audit, and Dependabot all run on every push and weekly.
+- GitHub Actions workflows are pinned, scoped to least-privilege permissions, and
+  use `persist-credentials: false` on checkout. The composite action passes user
+  inputs through `env:` rather than direct `${{ }}` interpolation to prevent
+  shell injection.
+
+[0.2.0]: https://github.com/tmatens/compose-lint/releases/tag/v0.2.0

compose_lint-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to compose-lint
+
+Thanks for your interest in contributing. This guide covers setup, code standards, and how to add new rules.
+
+## Development Setup
+
+```bash
+git clone https://github.com/tmatens/compose-lint.git
+cd compose-lint
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running Quality Checks
+
+All four must pass before submitting a PR:
+
+```bash
+ruff check src/ tests/          # Linting
+ruff format --check src/ tests/ # Formatting
+mypy src/                       # Type checking (strict mode)
+pytest                          # Tests
+```
+
+## Code Standards
+
+- **Python 3.10+** required
+- **Type annotations** on all public functions (`mypy --strict`)
+- **PyYAML** is the only runtime dependency. Do not add others without discussion.
+- **Rules receive plain Python types** (`dict`, `list`, `str`). Never leak parser-specific types into rule code.
+
+## Adding a New Rule
+
+1. Create `src/compose_lint/rules/CL{NNNN}_{snake_name}.py`
+2. Inherit from `BaseRule`, use the `@register_rule` decorator
+3. Set `id`, `name`, `severity`, `description`, `references`
+4. Implement `check(service_name, service_config, global_config, lines)` yielding `Finding` objects
+5. Add test file `tests/test_CL{NNNN}.py` with positive and negative cases
+6. Add fixture YAML files in `tests/compose_files/`
+7. Add rule documentation in `docs/rules/CL-{NNNN}.md`
+
+### Rule requirements
+
+- Every rule must reference OWASP Docker Security Cheat Sheet, CIS Docker Benchmark, or Docker official docs. No opinion-only rules.
+- Every finding must be actionable with specific fix guidance.
+- Severity must reflect real-world exploitability, not subjective importance.
+- Rule IDs are permanent and never reused.
+
+## Pull Requests
+
+- One feature or fix per PR
+- All quality checks must pass
+- Include tests for any new behavior
+- Commit messages should explain *why*, not just *what*
+
+## Questions?
+
+Open an issue if something is unclear.

compose_lint-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Todd Matens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.