compose-auditor 0.2.0__tar.gz

compose_auditor-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fred Wojo
+
+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.

compose_auditor-0.2.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: compose-auditor
+Version: 0.2.0
+Summary: Docker Compose security and best-practice linter
+Author: Fred Wojo
+License: MIT
+Keywords: docker,compose,security,lint,devops
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: colorama>=0.4
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Dynamic: license-file
+
+# compose-auditor
+
+Docker Compose security and best-practice linter. Catches common misconfigs, security issues, and operational gaps before they reach production.
+
+## Install
+
+```bash
+# From source (recommended for local use)
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+
+# Or directly into a venv
+pip install compose-auditor
+```
+
+## Usage
+
+```bash
+# Basic lint — colored text output, exits 1 on CRITICAL
+compose-auditor lint docker-compose.yml
+
+# Lint a specific path
+compose-auditor lint ~/Media/docker-compose.yml
+
+# JSON output (for CI pipelines)
+compose-auditor lint docker-compose.yml --format json
+
+# Control exit behavior
+compose-auditor lint docker-compose.yml --fail-on warning   # exit 1 on WARNING+
+compose-auditor lint docker-compose.yml --fail-on never     # always exit 0
+
+# No color (for logs)
+compose-auditor lint docker-compose.yml --no-color
+
+# Homelab profile — suppresses noisy rules irrelevant to personal stacks
+compose-auditor lint docker-compose.yml --profile homelab
+
+# Ignore specific rules (repeatable)
+compose-auditor lint docker-compose.yml --ignore SEC002 --ignore VOL001
+
+# Use a config file explicitly
+compose-auditor lint docker-compose.yml --config .compose-auditor.yml
+```
+
+## Profiles
+
+Profiles adjust severity for context. The `homelab` profile is built-in and tuned for personal self-hosted stacks.
+
+| Rule   | Default  | homelab  |
+|--------|----------|----------|
+| VOL001 | INFO     | suppressed |
+| RES002 | INFO     | suppressed |
+| OPS003 | INFO     | suppressed |
+| NET002 | WARNING  | INFO     |
+| IMG001 | WARNING  | INFO     |
+| RES001 | WARNING  | INFO     |
+
+## Config File
+
+Auto-discovered from `.compose-auditor.yml` in the current directory, then the home directory. Override with `--config`.
+
+```yaml
+# .compose-auditor.yml
+profile: homelab
+
+ignore:
+  - OPS003      # global — suppressed for all services
+
+rules:
+  NET002: INFO  # downgrade globally
+
+services:
+  traefik:
+    ignore:
+      - NET001  # traefik legitimately uses host networking
+  db:
+    ignore:
+      - SEC002  # postgres image sets its own user
+```
+
+Supported keys:
+- `profile` — apply a named profile (`homelab`)
+- `ignore` — list of rule IDs to suppress globally
+- `rules` — map of rule ID → new severity (`CRITICAL`, `WARNING`, `INFO`)
+- `services.<name>.ignore` — per-service rule suppression
+
+## LSIO Auto-Detection
+
+SEC002 (running as root / no user directive) is automatically suppressed for LinuxServer.io images. These images manage their own user mapping via `PUID`/`PGID` environment variables.
+
+Matched prefixes:
+- `lscr.io/linuxserver/`
+- `linuxserver/`
+- `ghcr.io/linuxserver/`
+
+## Rules
+
+| Rule ID  | Severity | Description |
+|----------|----------|-------------|
+| SEC001   | CRITICAL | Privileged container |
+| SEC002   | CRITICAL/WARNING | Running as root or no user directive |
+| SEC003   | CRITICAL | Docker socket mounted |
+| SEC004   | WARNING  | Bind mount to sensitive host path (/etc, /proc, /sys, etc.) |
+| SEC005   | CRITICAL | Plain-text secrets in environment variables |
+| NET001   | CRITICAL | Host network mode |
+| NET002   | WARNING  | Port bound to 0.0.0.0 (all interfaces) |
+| NET003   | CRITICAL | Duplicate host port binding across services |
+| OPS001   | INFO     | No restart policy |
+| OPS002   | INFO/WARNING | No healthcheck or healthcheck disabled |
+| OPS003   | INFO     | No logging configuration |
+| RES001   | WARNING  | No memory limit |
+| RES002   | INFO     | No CPU limit |
+| IMG001   | WARNING  | Using :latest (or untagged) image |
+| VOL001   | INFO     | Volume mounted read-write (consider :ro) |
+| DEP001   | INFO     | Service referenced in env/links without depends_on |
+
+NET003 is protocol-aware — TCP and UDP bindings on the same port number are treated as distinct and do not trigger a false positive.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | No issues at or above --fail-on threshold |
+| 1    | One or more findings at or above threshold |
+| 2    | Parse error (invalid YAML or not a compose file) |
+
+## JSON Output Schema
+
+```json
+{
+  "file": "/path/to/docker-compose.yml",
+  "summary": {
+    "CRITICAL": 3,
+    "WARNING": 7,
+    "INFO": 12
+  },
+  "findings": [
+    {
+      "severity": "CRITICAL",
+      "rule_id": "SEC001",
+      "service": "web",
+      "message": "Container runs in privileged mode",
+      "detail": "..."
+    }
+  ]
+}
+```

compose_auditor-0.2.0/README.md

@@ -0,0 +1,148 @@
+# compose-auditor
+
+Docker Compose security and best-practice linter. Catches common misconfigs, security issues, and operational gaps before they reach production.
+
+## Install
+
+```bash
+# From source (recommended for local use)
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+
+# Or directly into a venv
+pip install compose-auditor
+```
+
+## Usage
+
+```bash
+# Basic lint — colored text output, exits 1 on CRITICAL
+compose-auditor lint docker-compose.yml
+
+# Lint a specific path
+compose-auditor lint ~/Media/docker-compose.yml
+
+# JSON output (for CI pipelines)
+compose-auditor lint docker-compose.yml --format json
+
+# Control exit behavior
+compose-auditor lint docker-compose.yml --fail-on warning   # exit 1 on WARNING+
+compose-auditor lint docker-compose.yml --fail-on never     # always exit 0
+
+# No color (for logs)
+compose-auditor lint docker-compose.yml --no-color
+
+# Homelab profile — suppresses noisy rules irrelevant to personal stacks
+compose-auditor lint docker-compose.yml --profile homelab
+
+# Ignore specific rules (repeatable)
+compose-auditor lint docker-compose.yml --ignore SEC002 --ignore VOL001
+
+# Use a config file explicitly
+compose-auditor lint docker-compose.yml --config .compose-auditor.yml
+```
+
+## Profiles
+
+Profiles adjust severity for context. The `homelab` profile is built-in and tuned for personal self-hosted stacks.
+
+| Rule   | Default  | homelab  |
+|--------|----------|----------|
+| VOL001 | INFO     | suppressed |
+| RES002 | INFO     | suppressed |
+| OPS003 | INFO     | suppressed |
+| NET002 | WARNING  | INFO     |
+| IMG001 | WARNING  | INFO     |
+| RES001 | WARNING  | INFO     |
+
+## Config File
+
+Auto-discovered from `.compose-auditor.yml` in the current directory, then the home directory. Override with `--config`.
+
+```yaml
+# .compose-auditor.yml
+profile: homelab
+
+ignore:
+  - OPS003      # global — suppressed for all services
+
+rules:
+  NET002: INFO  # downgrade globally
+
+services:
+  traefik:
+    ignore:
+      - NET001  # traefik legitimately uses host networking
+  db:
+    ignore:
+      - SEC002  # postgres image sets its own user
+```
+
+Supported keys:
+- `profile` — apply a named profile (`homelab`)
+- `ignore` — list of rule IDs to suppress globally
+- `rules` — map of rule ID → new severity (`CRITICAL`, `WARNING`, `INFO`)
+- `services.<name>.ignore` — per-service rule suppression
+
+## LSIO Auto-Detection
+
+SEC002 (running as root / no user directive) is automatically suppressed for LinuxServer.io images. These images manage their own user mapping via `PUID`/`PGID` environment variables.
+
+Matched prefixes:
+- `lscr.io/linuxserver/`
+- `linuxserver/`
+- `ghcr.io/linuxserver/`
+
+## Rules
+
+| Rule ID  | Severity | Description |
+|----------|----------|-------------|
+| SEC001   | CRITICAL | Privileged container |
+| SEC002   | CRITICAL/WARNING | Running as root or no user directive |
+| SEC003   | CRITICAL | Docker socket mounted |
+| SEC004   | WARNING  | Bind mount to sensitive host path (/etc, /proc, /sys, etc.) |
+| SEC005   | CRITICAL | Plain-text secrets in environment variables |
+| NET001   | CRITICAL | Host network mode |
+| NET002   | WARNING  | Port bound to 0.0.0.0 (all interfaces) |
+| NET003   | CRITICAL | Duplicate host port binding across services |
+| OPS001   | INFO     | No restart policy |
+| OPS002   | INFO/WARNING | No healthcheck or healthcheck disabled |
+| OPS003   | INFO     | No logging configuration |
+| RES001   | WARNING  | No memory limit |
+| RES002   | INFO     | No CPU limit |
+| IMG001   | WARNING  | Using :latest (or untagged) image |
+| VOL001   | INFO     | Volume mounted read-write (consider :ro) |
+| DEP001   | INFO     | Service referenced in env/links without depends_on |
+
+NET003 is protocol-aware — TCP and UDP bindings on the same port number are treated as distinct and do not trigger a false positive.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | No issues at or above --fail-on threshold |
+| 1    | One or more findings at or above threshold |
+| 2    | Parse error (invalid YAML or not a compose file) |
+
+## JSON Output Schema
+
+```json
+{
+  "file": "/path/to/docker-compose.yml",
+  "summary": {
+    "CRITICAL": 3,
+    "WARNING": 7,
+    "INFO": 12
+  },
+  "findings": [
+    {
+      "severity": "CRITICAL",
+      "rule_id": "SEC001",
+      "service": "web",
+      "message": "Container runs in privileged mode",
+      "detail": "..."
+    }
+  ]
+}
+```

compose_auditor-0.2.0/compose_auditor/__init__.py

@@ -0,0 +1,3 @@
+"""compose-auditor: Docker Compose security and best-practice linter."""
+
+__version__ = "0.2.0"

compose_auditor-0.2.0/compose_auditor/analyzer.py

@@ -0,0 +1,152 @@
+"""Main analysis engine — loads a compose file and runs all rules."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+from .config import AuditConfig
+from .rules import (
+    ALL_RULES,
+    Finding,
+    check_depends_on,
+    check_ports,
+    _parse_port_entry,
+    SEVERITY_CRITICAL,
+    SEVERITY_WARNING,
+    SEVERITY_INFO,
+)
+
+
+def _load_compose(path: Path) -> dict[str, Any]:
+    with path.open("r") as fh:
+        data = yaml.safe_load(fh)
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} does not contain a valid YAML mapping.")
+    return data
+
+
+def analyze(path: Path, config: Optional[AuditConfig] = None) -> list[Finding]:
+    if config is None:
+        config = AuditConfig()
+
+    data = _load_compose(path)
+    services: dict[str, Any] = data.get("services", {}) or {}
+
+    if not services:
+        return [
+            Finding(
+                severity=SEVERITY_WARNING,
+                rule_id="PARSE001",
+                service="(file)",
+                message="No services found in compose file",
+                detail="",
+            )
+        ]
+
+    findings: list[Finding] = []
+
+    # Collect all port bindings across services for duplicate detection
+    global_ports: dict[str, str] = {}
+
+    for service_name, svc_config in services.items():
+        if svc_config is None:
+            svc_config = {}
+
+        for rule_fn in ALL_RULES:
+            if rule_fn is check_ports:
+                svc_findings = _check_ports_global(
+                    service_name, svc_config, global_ports
+                )
+            else:
+                svc_findings = rule_fn(service_name, svc_config)
+
+            findings.extend(svc_findings)
+
+        findings.extend(check_depends_on(service_name, svc_config, services))
+
+    # Apply config: filter ignored rules and adjust severities
+    result = []
+    for f in findings:
+        if config.is_ignored(f.rule_id, f.service):
+            continue
+        f.severity = config.effective_severity(f.rule_id, f.severity)
+        result.append(f)
+
+    return result
+
+
+def _check_ports_global(
+    service_name: str,
+    config: dict[str, Any],
+    global_ports: dict[str, str],
+) -> list[Finding]:
+    findings: list[Finding] = []
+    ports = config.get("ports", []) or []
+
+    for port_entry in ports:
+        raw = str(port_entry).strip()
+        bind_ip, host_port, container_port, protocol = _parse_port_entry(raw)
+
+        # 0.0.0.0 binding warning
+        if bind_ip in ("0.0.0.0", ""):
+            findings.append(
+                Finding(
+                    severity=SEVERITY_WARNING,
+                    rule_id="NET002",
+                    service=service_name,
+                    message=f"Port {host_port} bound to all interfaces (0.0.0.0)",
+                    detail=f"Use '127.0.0.1:{host_port}:{container_port}' to restrict to localhost unless external access is intentional.",
+                )
+            )
+
+        # Cross-service duplicate port detection.
+        # Include protocol — TCP and UDP on the same port is valid.
+        key = f"{protocol}:{bind_ip}:{host_port}"
+        if key in global_ports:
+            findings.append(
+                Finding(
+                    severity=SEVERITY_CRITICAL,
+                    rule_id="NET003",
+                    service=service_name,
+                    message=f"Host port {host_port} already bound by '{global_ports[key]}'",
+                    detail="Each host port can only be used by one service. Assign a different host port.",
+                )
+            )
+        else:
+            global_ports[key] = service_name
+
+    return findings
+
+
+def format_findings_text(findings: list[Finding]) -> str:
+    lines = []
+    for f in findings:
+        lines.append(f"  [{f.rule_id}] {f.message}")
+        if f.detail:
+            lines.append(f"           {f.detail}")
+    return "\n".join(lines)
+
+
+def findings_to_dict(findings: list[Finding]) -> list[dict[str, str]]:
+    return [
+        {
+            "severity": f.severity,
+            "rule_id": f.rule_id,
+            "service": f.service,
+            "message": f.message,
+            "detail": f.detail,
+        }
+        for f in findings
+    ]
+
+
+def summarize(findings: list[Finding]) -> dict[str, int]:
+    return {
+        SEVERITY_CRITICAL: sum(1 for f in findings if f.severity == SEVERITY_CRITICAL),
+        SEVERITY_WARNING: sum(1 for f in findings if f.severity == SEVERITY_WARNING),
+        SEVERITY_INFO: sum(1 for f in findings if f.severity == SEVERITY_INFO),
+    }

compose_auditor-0.2.0/compose_auditor/cli.py

@@ -0,0 +1,194 @@
+"""CLI entry point for compose-auditor."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from .analyzer import analyze, findings_to_dict, summarize
+from .config import AuditConfig, PROFILES, load_config
+from .rules import SEVERITY_CRITICAL, SEVERITY_WARNING, SEVERITY_INFO, Finding
+from . import __version__
+
+try:
+    from colorama import Fore, Style, init as colorama_init
+    colorama_init(autoreset=True)
+    _HAS_COLOR = True
+except ImportError:
+    _HAS_COLOR = False
+
+
+def _color(text: str, severity: str, no_color: bool) -> str:
+    if no_color or not _HAS_COLOR:
+        return text
+    if severity == SEVERITY_CRITICAL:
+        return f"{Fore.RED}{Style.BRIGHT}{text}{Style.RESET_ALL}"
+    if severity == SEVERITY_WARNING:
+        return f"{Fore.YELLOW}{Style.BRIGHT}{text}{Style.RESET_ALL}"
+    return f"{Fore.CYAN}{text}{Style.RESET_ALL}"
+
+
+def _severity_icon(severity: str) -> str:
+    return {
+        SEVERITY_CRITICAL: "✖",
+        SEVERITY_WARNING: "⚠",
+        SEVERITY_INFO: "ℹ",
+    }.get(severity, "?")
+
+
+def _print_text(
+    findings: list[Finding],
+    path: Path,
+    no_color: bool,
+    profile: str = "production",
+) -> None:
+    click.echo(f"\nAuditing: {path}")
+    if profile != "production":
+        click.echo(f"Profile:  {profile}")
+    click.echo()
+
+    if not findings:
+        msg = "No issues found."
+        click.echo(_color(msg, SEVERITY_INFO, no_color))
+        return
+
+    grouped: dict[str, list[Finding]] = {}
+    for f in findings:
+        grouped.setdefault(f.service, []).append(f)
+
+    for service, svc_findings in grouped.items():
+        label = f"  service: {service}"
+        click.echo(_color(label, SEVERITY_WARNING, no_color) if not no_color else label)
+        for f in svc_findings:
+            icon = _severity_icon(f.severity)
+            prefix = f"    {icon} [{f.severity:<8}] [{f.rule_id}]"
+            line = f"{prefix} {f.message}"
+            click.echo(_color(line, f.severity, no_color))
+            if f.detail:
+                if _HAS_COLOR and not no_color:
+                    click.echo(f"               {Fore.WHITE}{f.detail}{Style.RESET_ALL}")
+                else:
+                    click.echo(f"               {f.detail}")
+        click.echo()
+
+    counts = summarize(findings)
+    total = sum(counts.values())
+
+    parts = []
+    if counts[SEVERITY_CRITICAL]:
+        parts.append(_color(f"{counts[SEVERITY_CRITICAL]} critical", SEVERITY_CRITICAL, no_color))
+    if counts[SEVERITY_WARNING]:
+        parts.append(_color(f"{counts[SEVERITY_WARNING]} warning(s)", SEVERITY_WARNING, no_color))
+    if counts[SEVERITY_INFO]:
+        parts.append(_color(f"{counts[SEVERITY_INFO]} info", SEVERITY_INFO, no_color))
+
+    click.echo(f"Summary: {total} issue(s) found — " + ", ".join(parts))
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="compose-auditor")
+def cli() -> None:
+    """Docker Compose security and best-practice linter."""
+
+
+@cli.command()
+@click.argument("compose_file", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    show_default=True,
+    help="Output format.",
+)
+@click.option(
+    "--no-color",
+    is_flag=True,
+    default=False,
+    help="Disable colored output.",
+)
+@click.option(
+    "--fail-on",
+    "fail_on",
+    type=click.Choice(["critical", "warning", "info", "never"]),
+    default="critical",
+    show_default=True,
+    help="Exit with code 1 when findings at this level or above are found.",
+)
+@click.option(
+    "--profile",
+    "profile",
+    type=click.Choice(sorted(PROFILES.keys())),
+    default=None,
+    help="Audit profile — adjusts severity for context (e.g., homelab suppresses noise).",
+)
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, path_type=Path),
+    default=None,
+    help="Path to .compose-auditor.yml config file.",
+)
+@click.option(
+    "--ignore",
+    "ignore_rules",
+    multiple=True,
+    help="Rule IDs to ignore (can be repeated, e.g., --ignore SEC002 --ignore VOL001).",
+)
+def lint(
+    compose_file: Path,
+    output_format: str,
+    no_color: bool,
+    fail_on: str,
+    profile: str | None,
+    config_path: Path | None,
+    ignore_rules: tuple[str, ...],
+) -> None:
+    """Lint a docker-compose file for security and best-practice issues."""
+    # Build config: file < profile flag < --ignore flags
+    audit_config = load_config(config_path)
+
+    if profile:
+        audit_config.profile = profile
+        if profile in PROFILES:
+            audit_config.severity_overrides.update(PROFILES[profile])
+
+    for rule_id in ignore_rules:
+        audit_config.global_ignore.add(rule_id)
+
+    try:
+        findings = analyze(compose_file, audit_config)
+    except Exception as exc:
+        click.echo(f"Error parsing {compose_file}: {exc}", err=True)
+        sys.exit(2)
+
+    counts = summarize(findings)
+
+    if output_format == "json":
+        output = {
+            "file": str(compose_file),
+            "profile": audit_config.profile,
+            "summary": counts,
+            "findings": findings_to_dict(findings),
+        }
+        click.echo(json.dumps(output, indent=2))
+    else:
+        _print_text(findings, compose_file, no_color, audit_config.profile)
+
+    # Exit codes
+    fail_map = {
+        "never": [],
+        "info": [SEVERITY_CRITICAL, SEVERITY_WARNING, SEVERITY_INFO],
+        "warning": [SEVERITY_CRITICAL, SEVERITY_WARNING],
+        "critical": [SEVERITY_CRITICAL],
+    }
+    trigger_severities = fail_map[fail_on]
+    if any(f.severity in trigger_severities for f in findings):
+        sys.exit(1)
+
+
+def main() -> None:
+    cli()