borghei/Claude-Skills / engineering/docker-development
docker-development
FlaggedAnalyse Dockerfiles and Compose files for security, image size, cache and config problems, with CI-ready exit codes. Use when reviewing or optimising a Dockerfile, validating docker-compose, or adding a container lint step.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.1 KB |
| examples/Dockerfile.sample | other | 1.9 KB |
| examples/docker-compose.sample.yml | config | 3.0 KB |
| examples/docker-compose.sound.yml | config | 787 B |
| references/docker-best-practices.md | markdown | 2.8 KB |
| scripts/compose_validator.py | script | 17.1 KB |
| scripts/dockerfile_analyzer.py | script | 15.2 KB |
scripts/compose_validator.py
View on GitHub#!/usr/bin/env python3
"""
Docker Compose Validator - Validate docker-compose files for correctness and best practices.
Checks service dependencies, port conflicts, volume configurations,
network definitions, and common misconfigurations.
License: MIT
"""
import argparse
import json
import re
import sys
from dataclasses import dataclass, asdict
from pathlib import Path
from typing import List, Dict, Any, Optional, Set, Tuple
@dataclass
class Finding:
"""A validation finding."""
severity: str
category: str
service: str
message: str
recommendation: str
class ComposeParser:
"""Minimal YAML-like parser for docker-compose files (stdlib only)."""
def __init__(self, content: str):
self.content = content
self.lines = content.split("\n")
def parse(self) -> Dict[str, Any]:
"""Parse compose file into a structured dict."""
result: Dict[str, Any] = {}
current_top_key = None
current_service = None
current_sub_key = None
indent_stack: List[Tuple[int, str]] = []
for line in self.lines:
line = re.sub(r"\s+#.*$", "", line) # trailing comment
stripped = line.strip()
if not stripped or stripped.startswith("#"):
continue
indent = len(line) - len(line.lstrip())
# Top-level keys
if indent == 0 and ":" in stripped:
key = stripped.split(":")[0].strip()
current_top_key = key
result[key] = {}
current_service = None
current_sub_key = None
continue
if current_top_key == "services" and indent == 2 and ":" in stripped:
svc_name = stripped.split(":")[0].strip()
current_service = svc_name
result.setdefault("services", {})[svc_name] = {}
current_sub_key = None
continue
if current_service and current_top_key == "services":
svc = result["services"][current_service]
if indent == 4 and ":" in stripped:
key = stripped.split(":")[0].strip()
value = ":".join(stripped.split(":")[1:]).strip()
current_sub_key = key
if value:
svc[key] = value.strip("\"'")
else:
svc.setdefault(key, [])
elif indent >= 6 and not stripped.startswith("- ") and ":" in stripped \
and current_sub_key in ("environment", "labels"):
# map form ("KEY: value") stored like the list form ("KEY=value")
k, _, v = stripped.partition(":")
if not isinstance(svc.get(current_sub_key), list):
svc[current_sub_key] = []
svc[current_sub_key].append(f"{k.strip()}={v.strip().strip(chr(34) + chr(39))}")
elif indent >= 6 and stripped.startswith("- "):
item = stripped[2:].strip().strip("\"'")
if current_sub_key:
if not isinstance(svc.get(current_sub_key), list):
svc[current_sub_key] = []
svc[current_sub_key].append(item)
elif indent >= 6 and current_sub_key and isinstance(svc.get(current_sub_key), list):
# nested mapping (deploy.resources.limits, healthcheck.test ...): keep the
# lines so presence checks such as "resources" in deploy still work
svc[current_sub_key].append(stripped)
return result
class ComposeValidator:
"""Validates docker-compose configurations."""
def __init__(self, content: str, check_ports: bool = False):
self.content = content
self.check_ports_only = check_ports
self.findings: List[Finding] = []
parser = ComposeParser(content)
self.config = parser.parse()
self.services = self.config.get("services", {})
def validate(self) -> List[Finding]:
"""Run all validation checks."""
if self.check_ports_only:
self._check_port_conflicts()
return self.findings
self._check_structure()
self._check_port_conflicts()
self._check_dependencies()
self._check_volumes()
self._check_security()
self._check_best_practices()
return self.findings
def _check_structure(self):
"""Check basic compose file structure."""
if not self.services:
self.findings.append(Finding(
severity="critical",
category="structure",
service="(global)",
message="No services defined in compose file.",
recommendation="Add a 'services' section with at least one service.",
))
return
for name, svc in self.services.items():
if not isinstance(svc, dict):
continue
has_image = "image" in svc
has_build = "build" in svc
if not has_image and not has_build:
self.findings.append(Finding(
severity="critical",
category="structure",
service=name,
message=f"Service '{name}' has neither 'image' nor 'build' defined.",
recommendation="Add 'image: <name>:<tag>' or 'build: <context>' to the service.",
))
def _check_port_conflicts(self):
"""Detect duplicate host port bindings."""
port_map: Dict[str, List[str]] = {}
for name, svc in self.services.items():
if not isinstance(svc, dict):
continue
ports = svc.get("ports", [])
if not isinstance(ports, list):
continue
for port_spec in ports:
port_str = str(port_spec).strip().strip('"').strip("'")
# Parse host port from spec like "8080:80" or "127.0.0.1:8080:80"
parts = port_str.split(":")
if len(parts) >= 2:
host_port = parts[-2]
# Handle port ranges
host_key = f"0.0.0.0:{host_port}"
if len(parts) == 3:
host_key = f"{parts[0]}:{parts[1]}"
port_map.setdefault(host_key, []).append(name)
for port, services in port_map.items():
if len(services) > 1:
self.findings.append(Finding(
severity="critical",
category="ports",
service=", ".join(services),
message=f"Port conflict: host port {port} is used by services: {', '.join(services)}.",
recommendation="Assign unique host ports to each service.",
))
def _check_dependencies(self):
"""Validate service dependencies and detect circular deps."""
dep_graph: Dict[str, Set[str]] = {}
for name, svc in self.services.items():
if not isinstance(svc, dict):
continue
deps = svc.get("depends_on", [])
if isinstance(deps, list):
dep_graph[name] = set(deps)
elif isinstance(deps, str):
dep_graph[name] = {deps}
else:
dep_graph[name] = set()
# Check for references to undefined services
all_services = set(self.services.keys())
for name, deps in dep_graph.items():
for dep in deps:
if dep not in all_services:
self.findings.append(Finding(
severity="critical",
category="dependencies",
service=name,
message=f"Service '{name}' depends on undefined service '{dep}'.",
recommendation=f"Define service '{dep}' or remove the dependency.",
))
# Detect circular dependencies using DFS
visited: Set[str] = set()
path: List[str] = []
def dfs(node: str) -> bool:
if node in path:
cycle = path[path.index(node):] + [node]
self.findings.append(Finding(
severity="critical",
category="dependencies",
service=node,
message=f"Circular dependency detected: {' -> '.join(cycle)}.",
recommendation="Break the circular dependency chain.",
))
return True
if node in visited:
return False
visited.add(node)
path.append(node)
for dep in dep_graph.get(node, set()):
if dfs(dep):
return True
path.pop()
return False
for name in self.services:
visited.clear()
path.clear()
dfs(name)
def _check_volumes(self):
"""Check volume configurations."""
for name, svc in self.services.items():
if not isinstance(svc, dict):
continue
volumes = svc.get("volumes", [])
if not isinstance(volumes, list):
continue
for vol in volumes:
vol_str = str(vol)
# Check for mounting Docker socket
if "/var/run/docker.sock" in vol_str:
self.findings.append(Finding(
severity="warning",
category="security",
service=name,
message=f"Service '{name}' mounts Docker socket.",
recommendation="Docker socket access grants container root-equivalent privileges. Ensure this is necessary.",
))
# Check for mounting sensitive host paths
sensitive_paths = ["/etc/shadow", "/etc/passwd", "/root"]
for sp in sensitive_paths:
if vol_str.startswith(sp + ":") or f":{sp}" in vol_str:
self.findings.append(Finding(
severity="critical",
category="security",
service=name,
message=f"Service '{name}' mounts sensitive host path: {sp}.",
recommendation="Avoid mounting sensitive host paths into containers.",
))
def _check_security(self):
"""Check security-related configurations."""
for name, svc in self.services.items():
if not isinstance(svc, dict):
continue
# Check for privileged mode
if svc.get("privileged") in ("true", True):
self.findings.append(Finding(
severity="critical",
category="security",
service=name,
message=f"Service '{name}' runs in privileged mode.",
recommendation="Remove privileged mode. Use specific capabilities instead (cap_add).",
))
# Check for host network mode
if svc.get("network_mode") == "host":
self.findings.append(Finding(
severity="warning",
category="security",
service=name,
message=f"Service '{name}' uses host network mode.",
recommendation="Use bridge or custom networks for better isolation.",
))
def _check_best_practices(self):
"""Check general best practices."""
for name, svc in self.services.items():
if not isinstance(svc, dict):
continue
# Check restart policy
if "restart" not in svc:
self.findings.append(Finding(
severity="info",
category="best-practice",
service=name,
message=f"Service '{name}' has no restart policy.",
recommendation="Add 'restart: unless-stopped' for production services.",
))
# Check for resource limits
deploy = svc.get("deploy", "")
if not deploy or "resources" not in str(deploy):
self.findings.append(Finding(
severity="info",
category="best-practice",
service=name,
message=f"Service '{name}' has no resource limits defined.",
recommendation="Add deploy.resources.limits for CPU and memory.",
))
# Check image tags: no tag and ":latest" both float
image = svc.get("image", "")
if image and "@sha256:" not in image and (":" not in image.split("/")[-1] or image.endswith(":latest")):
self.findings.append(Finding(
severity="warning",
category="best-practice",
service=name,
message=f"Service '{name}' uses floating image '{image}'.",
recommendation="Pin image to a specific version tag (or digest).",
))
# Literal secrets in environment (values that are not ${VAR} references)
env = svc.get("environment", [])
for entry in env if isinstance(env, list) else []:
key, sep, value = str(entry).partition("=")
if sep and value and not value.startswith("$") and \
re.search(r"PASS|SECRET|TOKEN|API_KEY|PRIVATE_KEY", key, re.I):
self.findings.append(Finding(
severity="critical",
category="security",
service=name,
message=f"Service '{name}' sets {key} to a literal value in the compose file.",
recommendation="Use env_file (kept out of git), ${VAR} substitution or Compose secrets.",
))
def format_text(findings: List[Finding], services: Dict, ports_only: bool = False) -> str:
"""Format results as human-readable text."""
lines = []
lines.append("=" * 60)
lines.append("DOCKER COMPOSE VALIDATION REPORT")
lines.append("=" * 60)
lines.append(f"\nServices found: {len(services)}")
for name in services:
lines.append(f" - {name}")
critical = [f for f in findings if f.severity == "critical"]
warnings = [f for f in findings if f.severity == "warning"]
info = [f for f in findings if f.severity == "info"]
lines.append(f"\nFindings: {len(critical)} critical, {len(warnings)} warnings, {len(info)} info")
lines.append("-" * 60)
for severity, group in [("CRITICAL", critical), ("WARNING", warnings), ("INFO", info)]:
if not group:
continue
lines.append(f"\n[{severity}]")
for f in group:
lines.append(f" [{f.category}] {f.service}: {f.message}")
lines.append(f" Fix: {f.recommendation}")
lines.append("")
if not findings:
lines.append("\nNo host port conflicts found (only the port check ran; rerun without --check-ports for the full validation)."
if ports_only else "\nNo issues found by the structure, dependency, port, volume, security and best-practice checks.")
lines.append("=" * 60)
return "\n".join(lines)
def format_json(findings: List[Finding], services: Dict) -> str:
"""Format results as JSON."""
return json.dumps({
"services": list(services.keys()),
"findings": [asdict(f) for f in findings],
"summary": {
"total": len(findings),
"critical": sum(1 for f in findings if f.severity == "critical"),
"warnings": sum(1 for f in findings if f.severity == "warning"),
"info": sum(1 for f in findings if f.severity == "info"),
}
}, indent=2)
def main():
parser = argparse.ArgumentParser(
description="Validate docker-compose files for correctness and best practices."
)
parser.add_argument("--file", "-f", required=True, help="Path to docker-compose file")
parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format")
parser.add_argument("--check-ports", action="store_true", help="Run only the port-conflict check (skips every other check)")
args = parser.parse_args()
path = Path(args.file)
if not path.exists():
print(f"Error: File not found: {args.file}", file=sys.stderr)
sys.exit(2)
content = path.read_text()
validator = ComposeValidator(content, check_ports=args.check_ports)
findings = validator.validate()
if args.format == "json":
report = json.loads(format_json(findings, validator.services))
report["checks_run"] = (["ports"] if args.check_ports else
["structure", "dependencies", "ports", "volumes", "security", "best-practices"])
print(json.dumps(report, indent=2))
else:
print(format_text(findings, validator.services, ports_only=args.check_ports))
if any(f.severity == "critical" for f in findings):
sys.exit(1)
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |