compose-lint

URL: https://github.com/tmatens/compose-lint/blob/main/.github/SECURITY.md#supported-versions

Justification: .github/SECURITY.md §"Supported Versions" states: "Only the latest minor release receives security fixes." Pre-1.0 SemVer rules are documented in docs/RELEASING.md (PATCH = bug fixes only; MINOR = additive changes plus new rules at non-CRITICAL severity; MAJOR = breaking changes). The upgrade path is pip install --upgrade compose-lint (PyPI) or pulling the new tag from composelint/compose-lint (Docker Hub). Every release ships a CHANGELOG entry calling out anything that changes findings (rule additions, severity adjustments, parser fixes), so users can plan upgrades against a stable contract.

The project uses GitHub Issues as its public issue tracker for bug reports and feature requests. The tracker is linked from README.md, CONTRIBUTING.md, and the PyPI project page.

URL: https://github.com/tmatens/compose-lint/blob/main/.github/SECURITY.md

Justification: .github/SECURITY.md documents the process end-to-end. Reports are filed privately via GitHub Security Advisories at https://github.com/tmatens/compose-lint/security/advisories/new (public issues are explicitly disallowed for vulnerabilities). The maintainer commits to a 7-day acknowledgement SLA, then fix coordination and advisory publication with credit. Scope (in-scope: code execution / info disclosure via crafted Compose, supply-chain tampering, exploitable vulnerable dependencies; out-of-scope: rule false positives/negatives, vulnerable test fixtures) is defined explicitly. CONTRIBUTING.md §"Maintainers" reaffirms the 7-day security-ack SLA.

SECURITY.md documents the CVD process: private reporting via GitHub Security Advisories, acknowledgement within 7 days, coordinated fix and advisory publication with credit. See https://github.com/tmatens/compose-lint/blob/main/SECURITY.md [osps_vm_01_01]

URL: https://github.com/tmatens/compose-lint/blob/main/pyproject.toml

Justification: The primary language is Python 3.10+. pyproject.toml [tool.ruff.lint] selects the active rule families: PEP 8 (E, W), pyflakes (F), isort (I), pyupgrade (UP), bugbear (B), simplify (SIM), and flake8-type-checking (TCH). pyproject.toml [tool.mypy] sets strict = true. target-version = "py310". Formatting is ruff format (Black-compatible). CONTRIBUTING.md §"Code standards" enumerates the additional contributor-facing rules (Python 3.10+ stdlib only, type annotations on all public functions, plain Python types in rule code, latest stable for new dependencies).

URL: https://github.com/tmatens/compose-lint/blob/main/.github/workflows/ci.yml

Justification: Every standard above is enforced by CI on every push and pull request to main:

lint job: ruff check src/ tests/ and ruff format --check src/ tests/.
type-check job: mypy src/ (strict).
test matrix: pytest on Python 3.10, 3.11, 3.12, 3.13, 3.14.
coverage job: pytest --cov=compose_lint --cov-fail-under=80. Locally, the pre-push hook in .githooks/ blocks unsigned commits before they reach origin. Required-status-checks on main block merges if any CI gate fails.

Justification: compose-lint is pure Python; no native binaries are built. The Hatchling build backend produces a py3-none-any wheel. There are no compiler or linker invocations to honor CC/CFLAGS/etc.

Justification: There is no compiler/linker step. Python source ships verbatim inside the wheel, so debugging information (source line numbers, identifiers) is inherently preserved.

Justification: Hatchling traverses a single source tree (src/compose_lint/) to produce the wheel. There is no recursive Make, no sub-builds, and therefore no cross-dependency hazard.

URL: https://github.com/tmatens/compose-lint/blob/main/docs/RELEASING.md

Justification:

Hatchling produces deterministic wheels (declared input file lists, sorted output).
PyPI publishes happen via Trusted Publishing (OIDC) with Sigstore build attestations attached to every release — anyone can independently verify provenance.
Every CI install uses pip install --require-hashes -r requirements.lock (or requirements-dev.lock / requirements-build.lock); the lockfiles are regenerated reproducibly using the documented uv pip compile --generate-hashes invocations in AGENTS.md §"Regenerating lockfiles".
Every GitHub Actions uses: reference is SHA-pinned with the tag in a trailing comment (Renovate manages the bumps).
Docker base image is digest-pinned to the OCI manifest-list digest.

URL: https://github.com/tmatens/compose-lint#installation

Justification: README.md §"Installation" documents multiple install paths, all using widely-recognized conventions:

pip install compose-lint (uninstall: pip uninstall compose-lint).
docker run --rm -v "$(pwd):/src" composelint/compose-lint (the published image is multi-arch, distroless, nonroot).
pre-commit hook (.pre-commit-hooks.yaml exposes the compose-lint ID for repos: use).
GitHub Action (uses: tmatens/compose-lint@v0.7.0).

URL: https://github.com/tmatens/compose-lint/blob/main/pyproject.toml

Justification: pip honors PEP 517 / PEP 668 conventions for install location (system, virtual environment, --user, pipx). The [project.scripts] entry in pyproject.toml — compose-lint = "compose_lint.cli:main" — installs the launcher to the standard bin/ of whatever environment pip is operating against. There is no custom prefix logic, no out-of-tree install hooks, no override of the standard build/install backend.

CONTRIBUTING.md "Development setup" documents the full build procedure (Python ≥3.10, virtualenv, editable install with dev extras). pyproject.toml declares build-system requirements. See https://github.com/tmatens/compose-lint/blob/main/CONTRIBUTING.md#development-setup [osps_do_07_01]

Dependencies are ingested via pip with hash-pinned lockfiles (requirements.lock, requirements-dev.lock, requirements-build.lock) generated by uv pip compile. CI installs use pip install --require-hashes. GitHub Actions are SHA-pinned. See https://github.com/tmatens/compose-lint/blob/main/CLAUDE.md#dependency-pinning [osps_br_05_01]

URL: https://github.com/tmatens/compose-lint/tree/main/.github/workflows

Justification: Multiple layers of dependency monitoring run continuously:

Renovate (.github/renovate.json) opens dep-bump PRs weekly across runtime deps, dev tooling, GitHub Actions SHA pins, and Docker base image digests.
pip-audit runs in the security job of ci.yml on every push and PR (reports all severities; gating reserved for critical).
Bandit runs in the same job for Python source-level vulnerability patterns.
CodeQL (.github/workflows/codeql.yml) runs on every push/PR and weekly on schedule.
OpenSSF Scorecard (.github/workflows/scorecard.yml) runs weekly and publishes SARIF.
Docker Scout (.github/workflows/scout-scan.yml) scans the published image; .vex/ ships OpenVEX statements for downstream consumers.
ClusterFuzzLite (.clusterfuzzlite/, fuzz/fuzz_compose.py) fuzzes the parser on every PR.

Direct Python dependencies are declared in pyproject.toml (dependencies and the [project.optional-dependencies] table). Fully-resolved hash-pinned lockfiles (requirements.lock, requirements-dev.lock, requirements-build.lock) are committed for reproducible CI installs. See https://github.com/tmatens/compose-lint/blob/main/pyproject.toml [osps_qa_02_01]

URL: https://github.com/tmatens/compose-lint/blob/main/pyproject.toml

Justification:

pyproject.toml sets target-version = "py310"; ruff's UP (pyupgrade) rules auto-flag deprecated stdlib idioms (e.g., typing.List → list).
The CI test matrix runs Python 3.10 through 3.14, so any deprecation surfacing at the latest interpreter fails CI.
The parser uses yaml.SafeLoader (the safe, current API), never the deprecated yaml.load(..., Loader=...) shape.
mypy strict catches use of deprecated typing aliases that have moved.

CI runs the full pytest suite across Python 3.10–3.14 on every PR via .github/workflows/ci.yml; the aggregate ci-ok check is required by the main branch ruleset, blocking merge unless tests pass. [osps_qa_06_01]

URL: https://github.com/tmatens/compose-lint/blob/main/CONTRIBUTING.md

Justification: CONTRIBUTING.md §"PR expectations" mandates: "Update tests. New rules need positive and negative tests. Bug fixes need a regression test." Reviewer-enforced; the maintainer rejects bug-fix PRs that don't include the regression test in the same commit. The pull-request template surfaces this expectation at PR-creation time. Bug-fix commits in git log consistently land with their regression test in the same commit, comfortably exceeding the 50% threshold.

URL: https://github.com/tmatens/compose-lint/blob/main/.github/workflows/ci.yml

Justification: Statement coverage is measured in CI on every push and PR and gated at ≥80%:

pyproject.toml adds pytest-cov==7.1.0 to the [dev] extras and configures [tool.coverage.run] (source = compose_lint, statement coverage, parallel = true) plus [tool.coverage.report] (fail_under = 80, show_missing, sensible excludes for TYPE_CHECKING / NotImplementedError / # pragma: no cover).
The coverage job in .github/workflows/ci.yml runs pytest --cov=compose_lint --cov-report=term-missing --cov-fail-under=80 on Python 3.13. The threshold is duplicated at the workflow level so a config drift cannot silently lower it. The job is in the ci-ok rollup so branch protection enforces it.
A subprocess-coverage shim (coverage_subprocess.pth + COVERAGE_PROCESS_START) ensures coverage measures the python -m compose_lint subprocesses spawned by test_cli.py and test_integration.py. Measured statement coverage on Linux CI is approximately 93%.
CONTRIBUTING.md §"Local quality checks" documents the local coverage command for contributors.

URL: https://github.com/tmatens/compose-lint/blob/main/CONTRIBUTING.md

Justification: CONTRIBUTING.md §"Adding a new rule" lists the test obligation as step 5 of the new-rule checklist: "Add test file tests/test_CL{NNNN}.py with both positive (triggers) and negative (clean) cases. Negative cases must include at least one hardened-but-unusual configuration the rule must not flag." §"PR expectations" generalizes the rule: tests required for new functionality, regression tests required for bug fixes. The PR template links back to CONTRIBUTING.md so contributors see the policy at PR-creation time.

Documented in CONTRIBUTING.md §"Adding a new rule" (test file is step 5 of the checklist) and §"PR expectations" ("Update tests. New rules need positive and negative tests. Bug fixes need a regression test."). The PR template links back to CONTRIBUTING.md.

mypy runs with strict = true (the maximum setting: enables all optional strict flags). ruff selects broad rule families including B (bugbear correctness checks) and UP (pyupgrade modernization) in addition to the defaults. Formatting drift is also an error (ruff format --check).

Secure design principles applied throughout:

Least privilege: single runtime dep (PyYAML); CI workflows declare permissions: {} deny-all and per-job least-privilege scopes; published Docker image is distroless, runs as nonroot uid 65532, drops all capabilities by documented invocation.
Input validation: LineLoader(yaml.SafeLoader) — never yaml.load() — rejects malformed/unsafe YAML and Python-object tags. Engine validates that services: exists and is a mapping (ADR-013). Rules receive plain Python primitives; parser-specific types never leak into rule code.
Fail-secure: usage errors and parse failures exit 2 (distinct from "findings present" exit 1). Default --fail-on=HIGH errs on the side of breaking the build.
Defense in depth: mypy strict + ruff B (bugbear) + Bandit + CodeQL + ClusterFuzzLite fuzzing + pip-audit + Scorecard, layered.
Secure defaults: pre-commit hook fails closed; GitHub Action runs without arguments and lints repository defaults; Docker image entrypoint is the linter (no shell).
Supply-chain security: Trusted Publishing (no long-lived PyPI tokens), Sigstore attestations, hash-pinned lockfiles, SHA-pinned actions, signed git tags, OIDC for Docker Hub.
References: README §"Security posture", SECURITY.md §"Supply Chain", docs/adr/003-yaml-parsing.md, docs/adr/006-exit-codes.md, docs/adr/009-runtime-base-image.md.

N/A — compose-lint is a static Docker Compose linter. The software produced implements no cryptographic protocols, algorithms, password storage, or key/nonce generation. Sole runtime dependency is PyYAML.

compose-lint implements no cryptographic algorithms in its product code. PyYAML, the sole runtime dependency, performs no crypto. Mark N/A.

compose-lint implements no cryptographic algorithms in its product code. PyYAML, the sole runtime dependency, performs no crypto. Mark N/A.

compose-lint performs no network communication at runtime. The CLI reads files from disk and writes findings to stdout/stderr. Mark N/A.

No TLS use. Mark N/A.

No TLS use. Mark N/A.

No TLS use. Mark N/A.

PyPI releases include Sigstore build attestations generated via Trusted Publishing (OIDC) — each wheel and sdist is accompanied by a signed attestation. Git tags are SSH-signed. Verify via PyPI's attestation viewer or python -m sigstore verify. See https://github.com/tmatens/compose-lint/blob/main/SECURITY.md [osps_br_06_01]

Every release tag is git tag -s SSH-signed annotated. publish.yml verify-tag job now performs three checks (the previously-noted "follow-up" is closed):

Annotated tag (git cat-file -t returns tag, not commit).
Reachable from origin/main.
SSH signature verifies against .github/allowed_signers (added in PR #202; key namespace-scoped to git so it cannot be reused for arbitrary SSH signing if leaked). Pre-flight handles missing/empty allowed_signers with an explicit error pointing at the rotation procedure in GOVERNANCE.md.
End-to-end provenance chain is now: SSH-verified annotated tag → reachable-from-main → CI build → Sigstore attestation → PyPI / Docker Hub.

Parser: LineLoader(yaml.SafeLoader) rejects unsafe YAML constructs (Python-object tags, arbitrary class instantiation). Documented in ADR-003.
Engine: validates that services: exists and is a mapping; emits a usage error (exit 2) otherwise. ADR-013 covers the missing-services-key handling.
Rules: receive only plain Python primitives; rule code does not reach back to parser internals.
Allowlist nature: rules check for known-bad patterns, not arbitrary input shapes; the allowlist for what counts as "valid Compose" is delegated to authoritative Compose schema (the linter is intentionally lenient on schema compliance to focus on security findings — see feedback_scope_security_not_style memory).
Fuzzing: fuzz/fuzz_compose.py runs continuously via ClusterFuzzLite (.clusterfuzzlite/) on every PR, attacking the parser surface with adversarial input.

Memory-safe language: pure Python. Type system enforcement: mypy --strict in CI. Lint-level hardening: ruff B (bugbear correctness rules), UP (pyupgrade), SIM (simplify), TCH (type-checking) — all run on every PR. Runtime container hardening: published Docker image is distroless, multi-arch, nonroot (uid 65532); README documents the fully-hardened invocation (--read-only --cap-drop ALL --security-opt no-new-privileges:true --network none --user 65532:65532 --pids-limit 256). CI workflow hardening: every workflow declares permissions: {} deny-all at top; jobs request only the scopes they need; every uses: is SHA-pinned with a trailing tag comment. Supply-chain hardening: PyPI Trusted Publishing (no long-lived tokens), hash-pinned lockfiles, signed annotated tags, Sigstore attestations, cosign-signed Docker images.

Threat surface assessed and documented across the project: SECURITY.md defines scope and out-of-scope; the architecture is deliberately minimal (PyYAML only runtime dependency, read-only file processing, no network, no eval); adversarial inputs (malformed YAML, billion-laughs-style attacks, crafted anchor/merge chains) are exercised by ClusterFuzzLite continuous fuzzing. Supply-chain surface hardened via Trusted Publishing, Sigstore attestations, signed commits/tags, SHA-pinned actions, hash-pinned lockfiles. See https://github.com/tmatens/compose-lint/blob/main/SECURITY.md [osps_sa_03_01]

Bandit and CodeQL both implement vulnerability-pattern rules. Bandit scans for the Python-specific common-weakness patterns (B-series: shell injection, insecure deserialization, weak crypto calls, hardcoded secrets, etc.). CodeQL's default query suite covers OWASP/CWE categories (injection, path traversal, SSRF, XSS).

compose-lint is written in pure Python (a memory-safe language) with PyYAML as the sole runtime dependency. No C/C++/unsafe-Rust code is produced or shipped.