composable-data-stack 0.13.0__py3-none-any.whl → 0.14.0__py3-none-any.whl

cli/confinement.py

@@ -0,0 +1,219 @@
+"""Declarative runtime confinement (seccomp, AppArmor, SELinux) for Compose services.
+
+A profile declares a default under `spec.security.runtime.confinement`; a
+module instance may override individual keys under `security.confinement`.
+The effective value is rendered into each service's `security_opt`.
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+from .diagnostics import Diagnostic
+
+INVALID_CONFINEMENT_CODE = "E127"
+CONFINEMENT_KEYS = ("seccomp", "apparmor", "selinux")
+
+_APPARMOR_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$")
+_DRIVE_RE = re.compile(r"^[A-Za-z]:")
+_SELINUX_LABEL_RE = re.compile(r"^(user|role|type|level):[A-Za-z0-9_.,:-]+$")
+
+
+def profile_confinement(profile_or_plan: dict[str, Any] | None) -> dict[str, Any]:
+    """Return the profile-wide confinement block from a profile or plan."""
+    if not isinstance(profile_or_plan, dict):
+        return {}
+    security = profile_or_plan.get("security")
+    if security is None:
+        security = (profile_or_plan.get("spec") or {}).get("security")
+    runtime = (security or {}).get("runtime") if isinstance(security, dict) else None
+    block = (runtime or {}).get("confinement") if isinstance(runtime, dict) else None
+    return block if isinstance(block, dict) else {}
+
+
+def plan_declares_confinement(plan: dict[str, Any] | None) -> bool:
+    """True when the profile or any module instance sets confinement."""
+    if profile_confinement(plan):
+        return True
+    return any(
+        isinstance((module.get("security") or {}).get("confinement"), dict)
+        and (module.get("security") or {}).get("confinement")
+        for module in (plan or {}).get("modules") or []
+        if isinstance(module, dict)
+    )
+
+
+def effective_confinement(
+    defaults: dict[str, Any] | None, override: dict[str, Any] | None
+) -> dict[str, Any]:
+    """Profile defaults with the module instance's keys layered on top."""
+    merged = {key: value for key, value in (defaults or {}).items() if key in CONFINEMENT_KEYS}
+    for key, value in (override or {}).items():
+        if key in CONFINEMENT_KEYS:
+            merged[key] = value
+    return merged
+
+
+def validate_confinement(
+    block: Any, path: str, base_dir: Path | None = None
+) -> list[Diagnostic]:
+    """Check one confinement block; `base_dir` anchors `file:` seccomp profiles."""
+    if block is None:
+        return []
+    if not isinstance(block, dict):
+        return [_error(f"{path} must be an object.", path)]
+    diagnostics: list[Diagnostic] = []
+    for key in block:
+        if key not in CONFINEMENT_KEYS:
+            diagnostics.append(_error(
+                f"Unknown confinement key '{key}'; supported keys: {', '.join(CONFINEMENT_KEYS)}.",
+                f"{path}.{key}",
+            ))
+
+    seccomp = block.get("seccomp")
+    if seccomp is not None:
+        diagnostics.extend(_validate_seccomp(seccomp, f"{path}.seccomp", base_dir))
+    apparmor = block.get("apparmor")
+    if apparmor is not None and not (
+        isinstance(apparmor, str)
+        and (apparmor in {"runtime/default", "unconfined"} or _APPARMOR_NAME_RE.match(apparmor))
+    ):
+        diagnostics.append(_error(
+            "apparmor must be 'runtime/default', 'unconfined' or the name of a profile "
+            "already loaded on the host (letters, digits, '.', '_', '-', '/').",
+            f"{path}.apparmor",
+        ))
+    selinux = block.get("selinux")
+    if selinux is not None:
+        diagnostics.extend(_validate_selinux(selinux, f"{path}.selinux"))
+    return diagnostics
+
+
+def _validate_seccomp(value: Any, path: str, base_dir: Path | None) -> list[Diagnostic]:
+    if value in {"default", "unconfined"}:
+        return []
+    if not isinstance(value, str) or not value.startswith("file:") or len(value) == 5:
+        return [_error(
+            "seccomp must be 'default', 'unconfined' or 'file:<path to a JSON profile "
+            "relative to the profile directory>'.",
+            path,
+        )]
+    relative = value[5:]
+    if base_dir is None:
+        return [_error(
+            "seccomp file profiles need a known profile directory to resolve against.", path
+        )]
+    # Reject rooted and drive-qualified paths explicitly: they are not
+    # "absolute" to pathlib on every platform (e.g. "/x" on Windows).
+    if (
+        Path(relative).is_absolute()
+        or relative.startswith(("/", "\\"))
+        or _DRIVE_RE.match(relative)
+        or ".." in Path(relative).parts
+    ):
+        return [_error(
+            "seccomp file profiles must be relative paths inside the profile directory.", path
+        )]
+    target = (base_dir / relative).resolve()
+    if not target.is_relative_to(base_dir.resolve()):
+        return [_error(
+            "seccomp file profile resolves outside the profile directory.", path
+        )]
+    if not target.is_file():
+        return [_error(f"seccomp profile '{relative}' does not exist.", path)]
+    return []
+
+
+def _validate_selinux(value: Any, path: str) -> list[Diagnostic]:
+    if value == "disable":
+        return []
+    if not isinstance(value, list) or not value or not all(isinstance(v, str) for v in value):
+        return [_error(
+            "selinux must be 'disable' or a non-empty list of labels such as "
+            "'type:container_t' or 'level:s0:c100,c200'.",
+            path,
+        )]
+    bad = [label for label in value if not _SELINUX_LABEL_RE.match(label)]
+    if bad:
+        return [_error(
+            f"Invalid SELinux label(s): {', '.join(bad)}; expected user:, role:, type: or level: values.",
+            path,
+        )]
+    kinds = [label.split(":", 1)[0] for label in value]
+    duplicates = sorted({k for k in kinds if kinds.count(k) > 1})
+    if duplicates:
+        return [_error(
+            f"Duplicate SELinux label kind(s): {', '.join(duplicates)}; "
+            "each of user:, role:, type: and level: may appear at most once.",
+            path,
+        )]
+    return []
+
+
+def confinement_security_opts(
+    confinement: dict[str, Any], compose_dir: Path, base_dir: Path | None
+) -> list[str]:
+    """Translate a validated confinement block into Compose `security_opt` entries.
+
+    Raises ValueError when a seccomp file cannot be expressed relative to
+    `compose_dir` (for example on a different Windows drive).
+    """
+    opts: list[str] = []
+    seccomp = confinement.get("seccomp")
+    if seccomp == "unconfined":
+        opts.append("seccomp=unconfined")
+    elif isinstance(seccomp, str) and seccomp.startswith("file:"):
+        target = (base_dir or compose_dir) / seccomp[5:]
+        opts.append(f"seccomp:{Path(os.path.relpath(target, compose_dir)).as_posix()}")
+    apparmor = confinement.get("apparmor")
+    if apparmor == "runtime/default":
+        opts.append("apparmor=docker-default")
+    elif isinstance(apparmor, str):
+        opts.append(f"apparmor={apparmor}")
+    selinux = confinement.get("selinux")
+    if selinux == "disable":
+        opts.append("label=disable")
+    elif isinstance(selinux, list):
+        opts.extend(f"label={label}" for label in selinux)
+    return opts
+
+
+def apply_confinement(
+    service: dict[str, Any],
+    confinement: dict[str, Any],
+    compose_dir: Path,
+    base_dir: Path | None,
+    path: str = "security.confinement",
+) -> list[Diagnostic]:
+    """Set the declared confinement on a service, replacing module-set values per key."""
+    if not confinement:
+        return []
+    try:
+        new_opts = confinement_security_opts(confinement, compose_dir, base_dir)
+    except ValueError:
+        return [_error(
+            "seccomp file profile cannot be referenced relative to the generated "
+            "docker-compose.yml (different drive); render into the profile's drive.",
+            f"{path}.seccomp",
+        )]
+    existing = [str(opt) for opt in service.get("security_opt") or []]
+    replaced = {
+        "seccomp": ("seccomp=", "seccomp:"),
+        "apparmor": ("apparmor=", "apparmor:"),
+        "selinux": ("label=", "label:"),
+    }
+    prefixes = tuple(p for key in confinement for p in replaced.get(key, ()))
+    kept = [opt for opt in existing if not opt.startswith(prefixes)] if prefixes else existing
+    # `default` seccomp means "engine default", so it only clears module-set values.
+    merged = kept + new_opts
+    if merged:
+        service["security_opt"] = merged
+    else:
+        service.pop("security_opt", None)
+    return []
+
+
+def _error(message: str, path: str) -> Diagnostic:
+    return Diagnostic(level="error", code=INVALID_CONFINEMENT_CODE, message=message, path=path)

cli/k8s_renderer.py

@@ -28,6 +28,7 @@ from typing import Any
 
 import yaml
 
+from .confinement import plan_declares_confinement
 from .diagnostics import Diagnostic
 from .renderer import (
     _build_context,
@@ -37,6 +38,7 @@ from .renderer import (
     _resolve_profile_dir,
     _resolve_project_root,
     _substitute_values,
+    apply_production_gates,
 )
 from .secret_leak import (
     check_generated_text,
@@ -110,6 +112,21 @@ def render_helm(
                 path=f"module:{module_id}.implementation.kubernetes",
             )
         )
+
+    if plan_declares_confinement(plan):
+        diagnostics.append(
+            Diagnostic(
+                level="warning",
+                code="W127",
+                message=(
+                    "Runtime confinement (seccomp/AppArmor/SELinux) is only rendered for "
+                    "the compose target; it has no effect on the Helm chart. "
+                    "Kubernetes security contexts are tracked under #65."
+                ),
+                path="spec.security.runtime.confinement",
+            )
+        )
+
     if unsupported:
         return {}, diagnostics
 
@@ -117,6 +134,28 @@ def render_helm(
     # ${k8s.service.*} can point forward to a workload declared later.
     service_names = _collect_service_names(renderable)
     diagnostics.extend(_check_binding_services(renderable, service_names))
+
+    # The built-in backup capability (config.backup.enabled, issue #665) is
+    # only implemented for the compose target: there is no Kubernetes
+    # sidecar workload yet. Fail closed instead of rendering a chart whose
+    # database is silently unprotected.
+    for module in renderable:
+        backup_config = (module.get("config") or {}).get("backup")
+        if isinstance(backup_config, dict) and backup_config.get("enabled") is True:
+            diagnostics.append(
+                Diagnostic(
+                    level="error",
+                    code="E142",
+                    message=(
+                        f'Module "{module["id"]}" enables config.backup.enabled, but the '
+                        'backup capability is not implemented for the "helm" render target '
+                        "(no Kubernetes sidecar workload exists yet). Render this profile "
+                        "with --target=compose, or disable backup for Kubernetes deploys."
+                    ),
+                    path=f"module:{module['id']}.config.backup.enabled",
+                )
+            )
+
     if any(diagnostic.level == "error" for diagnostic in diagnostics):
         return {}, diagnostics
 
@@ -141,8 +180,13 @@ def render_helm(
             "service": _service_context(module, service_names)
         }
         _release_scope_binding_hosts(context, service_names)
-        compose_services = deepcopy(
-            module["implementation"].get("compose", {}).get("services", {})
+        # The helm target is treated as production-only for now: Kubernetes
+        # deploys always render the production variants, regardless of the
+        # profile's metadata.environment. The learning (easy-install)
+        # variants exist for the compose target.
+        compose_services = apply_production_gates(
+            deepcopy(module["implementation"].get("compose", {}).get("services", {})),
+            True,
         )
         _merge_init_db_env(compose_services, module, secrets)
 
@@ -162,6 +206,7 @@ def render_helm(
             service_names=service_names,
             profile_dir=profile_dir,
             project_root=project_root,
+            is_production=True,
         )
         values["modules"][module_id] = {
             "config": _values_config(module.get("config", {})),
@@ -219,6 +264,7 @@ def _render_module(
     service_names: dict[str, str],
     profile_dir: Path | None,
     project_root: Path | None,
+    is_production: bool = False,
 ) -> tuple[
     dict[str, Any],
     list[tuple[str, dict[str, Any]]],
@@ -232,12 +278,16 @@ def _render_module(
     secret_keys: set[str] = set()
     module_values: dict[str, Any] = {}
 
-    volume_specs = _substitute_values(deepcopy(k8s.get("volumes", {})), context)
+    volume_specs = apply_production_gates(
+        _substitute_values(deepcopy(k8s.get("volumes", {})), context), is_production
+    )
+    configmap_specs = apply_production_gates(
+        _substitute_values(deepcopy(k8s.get("configMaps", {})), context), is_production
+    )
     for volume_spec in volume_specs.values():
         enabled_from = volume_spec.get("enabledFrom")
         if isinstance(enabled_from, str):
             volume_spec["enabledFrom"] = _resolve_expr(enabled_from, context)
-    configmap_specs = _substitute_values(deepcopy(k8s.get("configMaps", {})), context)
 
     # ConfigMaps are module-scoped: one manifest, mounted by whichever
     # containers name it.
@@ -305,6 +355,7 @@ def _render_module(
                 pod_volumes,
                 pvcs,
                 is_init=True,
+                is_production=is_production,
             )
             secret_keys |= keys
             init_containers.append(container)
@@ -328,6 +379,7 @@ def _render_module(
                 pod_volumes,
                 pvcs,
                 is_init=False,
+                is_production=is_production,
             )
             secret_keys |= keys
             containers.append(container)
@@ -432,6 +484,7 @@ def _translate_container(
     pod_volumes: dict[str, dict[str, Any]],
     pvcs: dict[str, dict[str, Any]],
     is_init: bool,
+    is_production: bool = False,
 ) -> tuple[dict[str, Any], dict, dict, set[str]]:
     spec = _substitute_values(deepcopy(spec), context)
     spec.pop("enabledFrom", None)
@@ -495,6 +548,7 @@ def _translate_container(
         pvcs,
         overrides.get("dropVolumeMounts", []) or [],
         context=context,
+        is_production=is_production,
     )
     if mounts:
         container["volumeMounts"] = mounts
@@ -730,6 +784,7 @@ def _translate_volumes(
     pvcs: dict[str, dict[str, Any]],
     drop_mounts: list[str],
     context: dict[str, Any] | None = None,
+    is_production: bool = False,
 ) -> list[dict[str, Any]]:
     mounts: list[dict[str, Any]] = []
     dropped = {str(d).rstrip("/") for d in drop_mounts}
@@ -745,6 +800,9 @@ def _translate_volumes(
         mounts.append({"name": name, "mountPath": path})
 
     for entry in spec.get("volumes", []) or []:
+        if isinstance(entry, dict) and isinstance(entry.get("production"), bool):
+            if entry["production"] != is_production:
+                continue
         source, target, read_only, kind = _parse_volume_entry(entry)
         if target is None or target.rstrip("/") in dropped:
             continue

cli/planner.py

@@ -14,7 +14,9 @@ from .loader import load_yaml_file, resolve_module_file
 from .resolver import (
     RequiredIfSyntaxError,
     evaluate_required_if,
+    is_certificate_ref,
     is_secret_ref,
+    parse_certificate_ref,
     parse_contract_ref,
     resolve_path,
     secret_name_from_ref,
@@ -170,6 +172,7 @@ def build_plan_from_profile(
     spec = profile.get("spec", {})
     secrets, secret_diags = load_profile_secrets(spec.get("secrets"), env_file)
     diagnostics.extend(secret_diags)
+    certificates = build_certificate_env_map(spec.get("certificates"))
 
     modules = spec.get("modules", [])
     if not isinstance(modules, list):
@@ -270,6 +273,8 @@ def build_plan_from_profile(
 
         # Validate secrets exist but leave "secrets.VAR" strings intact
         resolve_secret_refs(normalized_config, secrets, f"spec.modules[{i}].config", diagnostics)
+        # Same for certificate refs (issue #578): env names only, never material
+        resolve_certificate_refs(normalized_config, certificates, f"spec.modules[{i}].config", diagnostics)
 
         loaded = {
             "index": i,
@@ -310,6 +315,7 @@ def build_plan_from_profile(
                 "version": inst["version"],
                 "dependsOn": inst["dependsOn"],
                 "config": inst["config"],
+                "security": deepcopy(inst["instance"].get("security") or {}),
                 "consumes": resolve_consumed_contracts(inst, module_instances_by_id, resolved_contracts_by_module, diagnostics, secrets),
                 "provides": resolved_contracts_by_module[inst["id"]],
                 "implementation": inst["module"].get("spec", {}).get("implementation", {}),
@@ -324,7 +330,9 @@ def build_plan_from_profile(
         "environment": environment,
         "provenance": provenance,
         "runtime": spec.get("runtime", {}),
+        "security": deepcopy(spec.get("security") or {}),
         "secrets": secrets,
+        "certificates": certificates,
         "outputs": resolve_outputs(spec.get("outputs", {}), resolved_contracts_by_module, diagnostics),
         "modules": planned_modules,
     }
@@ -682,6 +690,67 @@ def resolve_consumed_contracts(
 
     return resolved
 
+def build_certificate_env_map(spec_certificates: Any) -> dict[str, dict[str, str]]:
+    """
+    Map each certificate alias to its two runtime environment variable NAMES
+    (issue #578): alias -> {"cert": certEnv, "key": keyEnv}.
+
+    Only names ever flow through CDS -- certificate/key material is supplied
+    by the external secret/cert provider at runtime and is never read,
+    planned, or rendered here.
+    """
+    if not isinstance(spec_certificates, dict):
+        return {}
+    values = spec_certificates.get("values")
+    if not isinstance(values, dict):
+        return {}
+    certificates: dict[str, dict[str, str]] = {}
+    for alias, definition in values.items():
+        if not isinstance(definition, dict):
+            continue
+        cert_env = definition.get("certEnv")
+        key_env = definition.get("keyEnv")
+        if isinstance(cert_env, str) and cert_env and isinstance(key_env, str) and key_env:
+            certificates[alias] = {"cert": cert_env, "key": key_env}
+    return certificates
+
+
+def resolve_certificate_refs(
+    obj: Any, certificates: dict[str, dict[str, str]], current_path: str, diagnostics: list[Diagnostic]
+) -> Any:
+    """
+    Validate that `certificates.<alias>.cert|.key` refs in planned config name
+    a declared alias, but leave the ref strings intact -- the renderer turns
+    them into ${VAR} runtime placeholders, exactly like secrets refs.
+    """
+    if isinstance(obj, dict):
+        return {
+            key: resolve_certificate_refs(value, certificates, f"{current_path}.{key}", diagnostics)
+            for key, value in obj.items()
+        }
+
+    if isinstance(obj, list):
+        return [
+            resolve_certificate_refs(value, certificates, f"{current_path}[{index}]", diagnostics)
+            for index, value in enumerate(obj)
+        ]
+
+    if isinstance(obj, str) and is_certificate_ref(obj):
+        parsed = parse_certificate_ref(obj)
+        alias = parsed[0] if parsed else None
+        if alias is None or alias not in certificates:
+            diagnostics.append(
+                Diagnostic(
+                    level="error",
+                    code="E129",
+                    message=f'Certificate ref "{obj}" could not be resolved.',
+                    path=current_path,
+                )
+            )
+
+    return obj  # always return unchanged
+
+
 def resolve_secret_refs(obj: Any, secrets: dict[str, str], current_path: str, diagnostics: list[Diagnostic]) -> Any:
     """
     Validate that all secrets.* references in obj exist in the secrets dict.

cli/preflight.py

@@ -47,7 +47,7 @@ def run_preflight(
     strict: bool = False,
 ) -> list[PreflightCheck]:
     checks: list[PreflightCheck] = []
-    checks.extend(_check_runtime(plan.get("runtime", {})))
+    checks.extend(_check_runtime(plan.get("runtime", {}), plan))
     checks.extend(_check_environment(compose_yaml, env_file))
     checks.extend(_check_ports(compose_yaml))
     checks.extend(_check_images(plan, compose_yaml, strict=strict))
@@ -58,7 +58,7 @@ def preflight_passed(checks: list[PreflightCheck]) -> bool:
     return not any(check.status == "FAIL" for check in checks)
 
 
-def _check_runtime(runtime: dict[str, Any]) -> list[PreflightCheck]:
+def _check_runtime(runtime: dict[str, Any], plan: dict[str, Any] | None = None) -> list[PreflightCheck]:
     runtime_type = runtime.get("type")
     if runtime_type != "docker-compose":
         return [
@@ -93,7 +93,7 @@ def _check_runtime(runtime: dict[str, Any]) -> list[PreflightCheck]:
     daemon_check, docker_info = _check_daemon()
     checks.append(daemon_check)
     if docker_info is not None:
-        checks.extend(_check_host_hardening(docker_info))
+        checks.extend(_check_host_hardening(docker_info, production=infer_profile_class(plan or {}) == "prod"))
     return checks
 
 
@@ -127,7 +127,7 @@ def _check_daemon() -> tuple[PreflightCheck, dict[str, Any] | None]:
     return PreflightCheck("PASS", "runtime.daemon", "Docker daemon is reachable."), info
 
 
-def _check_host_hardening(info: dict[str, Any]) -> list[PreflightCheck]:
+def _check_host_hardening(info: dict[str, Any], production: bool = True) -> list[PreflightCheck]:
     """
     Inspect host/daemon settings from `docker info` without privileged access.
 
@@ -144,10 +144,13 @@ def _check_host_hardening(info: dict[str, Any]) -> list[PreflightCheck]:
     rootless = "name=rootless" in options
     checks = [
         _host_check(
-            rootless,
+            rootless or not production,
             "host.rootless",
-            "Docker daemon runs in rootless mode.",
-            "Docker daemon runs as root. Prefer rootless mode (HOST-001).",
+            "Docker daemon runs in rootless mode."
+            if rootless
+            else "Docker daemon is not rootless (recommended for production hosts, HOST-001).",
+            "Docker daemon runs as root: a container breakout yields host root. "
+            "Use rootless Docker for production hosts (HOST-001, see docs/rootless-docker.md).",
         ),
         _host_check(
             rootless or "name=userns" in options,