docker-host-audit 0.2.0__tar.gz → 0.3.0__tar.gz

{docker_host_audit-0.2.0 → docker_host_audit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-host-audit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Read-only security audit for Docker hosts: flags root containers, exposed ports, secrets in env, privileged mode and mounted docker sockets.
 Author: Petr Hromádka
 Author-email: Petr Hromádka <109349500+petrhromadka@users.noreply.github.com>
@@ -67,7 +67,8 @@ reads live containers via `docker ps` / `docker inspect`.
 ## 🔍 What it checks
 
 Severity key: 🔴 critical · 🟠 high · 🟡 medium · 🔵 low. Each finding carries a title, a plain-language
-explanation, short **redacted** evidence, and a one-line remediation.
+explanation, short **redacted** evidence, and a one-line remediation. See
+[docs/checks.md](docs/checks.md) for every check with rationale and remediation.
 
 ### Privilege &amp; escape
 
@@ -100,6 +101,17 @@ explanation, short **redacted** evidence, and a one-line remediation.
 | 🔵 | `unpinned-image` | Image uses `:latest`, no tag, or no digest | Pulls aren't reproducible; upstream can silently change what runs. |
 | 🔵 | `unlimited-memory` | No memory limit set | A single container can exhaust host RAM and take the host down. |
 
+### Runtime hardening
+
+| | Check id | What | Why it matters |
+| :-: | --- | --- | --- |
+| 🟠 | `seccomp-unconfined` | `seccomp=unconfined` disables the default syscall filter | Widens the kernel attack surface available from inside the container. |
+| 🟡 | `apparmor-unconfined` | `apparmor=unconfined` disables the AppArmor profile | Drops mandatory access control confinement. |
+| 🔵 | `caps-not-dropped` | Capabilities are not dropped to `ALL` | The container keeps Docker's default cap set instead of least privilege. |
+| 🔵 | `no-healthcheck` | No container healthcheck is configured | Orchestration can't tell when the container is unhealthy. |
+
+See [docs/checks.md](docs/checks.md) for every check with full rationale and remediation.
+
 ---
 
 ## 📦 Install
@@ -297,6 +309,14 @@ register it in the `CHECKS` list of the relevant module under `src/ca/checks/`.
 
 ---
 
+## 📚 Documentation
+
+- [docs/checks.md](docs/checks.md) — reference for every check, with severity, trigger, rationale and remediation.
+- [docs/configuration.md](docs/configuration.md) — the optional config file and its settings.
+- [docs/github-action.md](docs/github-action.md) — the reusable GitHub Action for CI.
+
+---
+
 ## 📄 License
 
 [MIT](LICENSE) © 2026 Petr Hromádka

{docker_host_audit-0.2.0 → docker_host_audit-0.3.0}/README.md

@@ -45,7 +45,8 @@ reads live containers via `docker ps` / `docker inspect`.
 ## 🔍 What it checks
 
 Severity key: 🔴 critical · 🟠 high · 🟡 medium · 🔵 low. Each finding carries a title, a plain-language
-explanation, short **redacted** evidence, and a one-line remediation.
+explanation, short **redacted** evidence, and a one-line remediation. See
+[docs/checks.md](docs/checks.md) for every check with rationale and remediation.
 
 ### Privilege & escape
 
@@ -78,6 +79,17 @@ explanation, short **redacted** evidence, and a one-line remediation.
 | 🔵 | `unpinned-image` | Image uses `:latest`, no tag, or no digest | Pulls aren't reproducible; upstream can silently change what runs. |
 | 🔵 | `unlimited-memory` | No memory limit set | A single container can exhaust host RAM and take the host down. |
 
+### Runtime hardening
+
+| | Check id | What | Why it matters |
+| :-: | --- | --- | --- |
+| 🟠 | `seccomp-unconfined` | `seccomp=unconfined` disables the default syscall filter | Widens the kernel attack surface available from inside the container. |
+| 🟡 | `apparmor-unconfined` | `apparmor=unconfined` disables the AppArmor profile | Drops mandatory access control confinement. |
+| 🔵 | `caps-not-dropped` | Capabilities are not dropped to `ALL` | The container keeps Docker's default cap set instead of least privilege. |
+| 🔵 | `no-healthcheck` | No container healthcheck is configured | Orchestration can't tell when the container is unhealthy. |
+
+See [docs/checks.md](docs/checks.md) for every check with full rationale and remediation.
+
 ---
 
 ## 📦 Install
@@ -275,6 +287,14 @@ register it in the `CHECKS` list of the relevant module under `src/ca/checks/`.
 
 ---
 
+## 📚 Documentation
+
+- [docs/checks.md](docs/checks.md) — reference for every check, with severity, trigger, rationale and remediation.
+- [docs/configuration.md](docs/configuration.md) — the optional config file and its settings.
+- [docs/github-action.md](docs/github-action.md) — the reusable GitHub Action for CI.
+
+---
+
 ## 📄 License
 
 [MIT](LICENSE) © 2026 Petr Hromádka

{docker_host_audit-0.2.0 → docker_host_audit-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docker-host-audit"
-version = "0.2.0"
+version = "0.3.0"
 description = "Read-only security audit for Docker hosts: flags root containers, exposed ports, secrets in env, privileged mode and mounted docker sockets."
 readme = "README.md"
 license = "MIT"

{docker_host_audit-0.2.0 → docker_host_audit-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "docker-host-audit"
-version = "0.2.0"
+version = "0.3.0"
 description = "Read-only security audit for Docker hosts: flags root containers, exposed ports, secrets in env, privileged mode and mounted docker sockets."
 readme = "README.md"
 license = "MIT"

{docker_host_audit-0.2.0 → docker_host_audit-0.3.0}/src/ca/__init__.py

@@ -1,3 +1,3 @@
 """container-audit: read-only security audit for Docker hosts."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{docker_host_audit-0.2.0 → docker_host_audit-0.3.0}/src/ca/checks/__init__.py

@@ -7,6 +7,12 @@ from ca.models import CheckFn
 
 def get_checks() -> list[CheckFn]:
     """Every registered check, across all submodules."""
-    from ca.checks import exposure, hardening, images, privilege
+    from ca.checks import exposure, hardening, images, privilege, runtime
 
-    return [*privilege.CHECKS, *exposure.CHECKS, *hardening.CHECKS, *images.CHECKS]
+    return [
+        *privilege.CHECKS,
+        *exposure.CHECKS,
+        *hardening.CHECKS,
+        *images.CHECKS,
+        *runtime.CHECKS,
+    ]

docker_host_audit-0.3.0/src/ca/checks/runtime.py

@@ -0,0 +1,105 @@
+"""Runtime hardening checks: seccomp/apparmor profiles, capability dropping, healthchecks."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from ca.models import CheckFn, Container, Finding, Severity
+
+
+def _security_opt(c: Container) -> list[Any]:
+    host_config = c.raw.get("HostConfig")
+    if not isinstance(host_config, dict):
+        return []
+    opts = host_config.get("SecurityOpt")
+    return list(opts) if isinstance(opts, list) else []
+
+
+def _has_unconfined(c: Container, key: str) -> bool:
+    target = f"{key}:unconfined"
+    return any(str(opt).strip().lower().replace("=", ":") == target for opt in _security_opt(c))
+
+
+def _normalize_cap(cap: str) -> str:
+    return cap.strip().upper().removeprefix("CAP_")
+
+
+def _healthcheck_test(c: Container) -> list[Any] | None:
+    config = c.raw.get("Config")
+    if not isinstance(config, dict):
+        return None
+    healthcheck = config.get("Healthcheck")
+    if not isinstance(healthcheck, dict):
+        return None
+    test = healthcheck.get("Test")
+    return list(test) if isinstance(test, list) else []
+
+
+def seccomp_unconfined(containers: list[Container]) -> Iterable[Finding]:
+    for c in containers:
+        if _has_unconfined(c, "seccomp"):
+            yield Finding(
+                check_id="seccomp-unconfined",
+                title="Seccomp profile disabled (unconfined)",
+                severity=Severity.HIGH,
+                container=c.name,
+                detail="The default seccomp syscall filter is disabled, widening the kernel "
+                "attack surface.",
+                evidence="HostConfig.SecurityOpt contains seccomp=unconfined",
+                remediation="Remove `seccomp=unconfined`; use the default profile.",
+            )
+
+
+def apparmor_unconfined(containers: list[Container]) -> Iterable[Finding]:
+    for c in containers:
+        if _has_unconfined(c, "apparmor"):
+            yield Finding(
+                check_id="apparmor-unconfined",
+                title="AppArmor profile disabled (unconfined)",
+                severity=Severity.MEDIUM,
+                container=c.name,
+                detail="The container runs without an AppArmor profile, removing a layer of "
+                "mandatory access control.",
+                evidence="HostConfig.SecurityOpt contains apparmor=unconfined",
+                remediation="Use the default `docker-default` AppArmor profile.",
+            )
+
+
+def caps_not_dropped(containers: list[Container]) -> Iterable[Finding]:
+    for c in containers:
+        if "ALL" not in {_normalize_cap(cap) for cap in c.cap_drop}:
+            yield Finding(
+                check_id="caps-not-dropped",
+                title="Default capabilities are not dropped",
+                severity=Severity.LOW,
+                container=c.name,
+                detail="The container keeps Docker's default capability set instead of dropping "
+                "all and adding only what's needed.",
+                evidence="cap_drop does not contain ALL",
+                remediation="`cap_drop: [ALL]` then add back only required caps.",
+            )
+
+
+def no_healthcheck(containers: list[Container]) -> Iterable[Finding]:
+    for c in containers:
+        test = _healthcheck_test(c)
+        if not test or test == ["NONE"]:
+            yield Finding(
+                check_id="no-healthcheck",
+                title="Container has no healthcheck",
+                severity=Severity.LOW,
+                container=c.name,
+                detail="No container healthcheck, so orchestration can't detect an unhealthy "
+                "container.",
+                evidence="Config.Healthcheck is missing or disabled",
+                remediation="Add a HEALTHCHECK to the image or compose.",
+            )
+
+
+CHECKS: list[CheckFn] = [
+    seccomp_unconfined,
+    apparmor_unconfined,
+    caps_not_dropped,
+    no_healthcheck,
+]

{docker_host_audit-0.2.0 → docker_host_audit-0.3.0}/src/ca/cli.py

@@ -8,12 +8,16 @@ import socket
 import sys
 from datetime import UTC, datetime
 from pathlib import Path
+from typing import Any
 
 from ca import __version__
 from ca.checks import get_checks
+from ca.config import load_config
 from ca.models import Container, Finding, Report, Severity
 from ca.report import render
 
+_DEFAULTS = {"format": "text", "fail_on": "none", "min_severity": "info"}
+
 _FAIL_LEVELS = {
     "low": Severity.LOW,
     "medium": Severity.MEDIUM,
@@ -29,7 +33,13 @@ def _parser() -> argparse.ArgumentParser:
     )
     p.add_argument("--version", action="version", version=f"container-audit {__version__}")
     p.add_argument("--input", metavar="PATH", help="JSON array of `docker inspect` objects")
-    p.add_argument("--format", choices=["text", "json", "markdown", "sarif"], default="text")
+    p.add_argument(
+        "--config",
+        metavar="PATH",
+        help="path to a TOML config file; otherwise container-audit.toml / "
+        ".container-audit.toml in the current directory is used",
+    )
+    p.add_argument("--format", choices=["text", "json", "markdown", "sarif"], default=None)
     p.add_argument("--include-stopped", action="store_true", help="also audit stopped containers")
     p.add_argument(
         "--ignore",
@@ -40,13 +50,13 @@ def _parser() -> argparse.ArgumentParser:
     p.add_argument(
         "--fail-on",
         choices=["none", *_FAIL_LEVELS],
-        default="none",
+        default=None,
         help="exit 1 if any finding is at or above this severity",
     )
     p.add_argument(
         "--min-severity",
         choices=list(_MIN_LEVELS),
-        default="info",
+        default=None,
         help="hide findings below this severity from the report (--fail-on sees the same list)",
     )
     p.add_argument(
@@ -91,8 +101,26 @@ def _load(args: argparse.Namespace) -> list[Container] | None:
     return None
 
 
+def _apply_config(args: argparse.Namespace, config: dict[str, Any]) -> set[str]:
+    """Merge config into args (CLI flag > config > default) and return the ignore set."""
+    for key, default in _DEFAULTS.items():
+        if getattr(args, key) is None:
+            setattr(args, key, config.get(key, default))
+    for key in ("include_host", "include_stopped"):
+        if config.get(key):
+            setattr(args, key, True)
+    return set(args.ignore or []) | set(config.get("ignore", []))
+
+
 def main(argv: list[str] | None = None) -> int:
     args = _parser().parse_args(argv)
+    try:
+        config = load_config(args.config, Path.cwd())
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    ignored = _apply_config(args, config)
+
     containers = _load(args)
     if containers is None:
         return 2
@@ -102,7 +130,6 @@ def main(argv: list[str] | None = None) -> int:
         findings.extend(check(containers))
     floor = _MIN_LEVELS[args.min_severity]
     findings = [f for f in findings if f.severity >= floor]
-    ignored = set(args.ignore or [])
     findings = [f for f in findings if f.check_id not in ignored]
 
     report = Report(

docker_host_audit-0.3.0/src/ca/config.py

@@ -0,0 +1,64 @@
+"""Load optional TOML configuration. Stdlib-only, read-only.
+
+The config file sets defaults for a few CLI options. CLI flags always win
+over the file; the file wins over the built-in defaults. See `cli.py` for
+how the merge is applied.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+# key -> expected python type. `ignore` is a list of strings, handled separately.
+_STR_KEYS = ("min_severity", "fail_on", "format")
+_BOOL_KEYS = ("include_host", "include_stopped")
+_RECOGNISED = ("ignore", *_STR_KEYS, *_BOOL_KEYS)
+
+_DISCOVERY = ("container-audit.toml", ".container-audit.toml")
+
+
+def _validate(data: dict[str, Any]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in data.items():
+        if key not in _RECOGNISED:
+            raise ValueError(f"unknown config key: {key!r}")
+        if key == "ignore":
+            if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+                raise ValueError("config key 'ignore' must be a list of strings")
+        elif key in _STR_KEYS:
+            if not isinstance(value, str):
+                raise ValueError(f"config key {key!r} must be a string")
+        elif not isinstance(value, bool):  # _BOOL_KEYS
+            raise ValueError(f"config key {key!r} must be a boolean")
+        result[key] = value
+    return result
+
+
+def load_config(path: str | None, cwd: Path) -> dict[str, Any]:
+    """Return recognised config keys from `path`, or auto-discovered file, or {}.
+
+    Raises ValueError on a missing explicit path, malformed TOML, an unknown
+    key, or a wrong value type.
+    """
+    if path is not None:
+        config_path: Path | None = Path(path)
+    else:
+        config_path = next((cwd / name for name in _DISCOVERY if (cwd / name).is_file()), None)
+    if config_path is None:
+        return {}
+
+    try:
+        raw = config_path.read_bytes()
+    except FileNotFoundError:
+        raise ValueError(f"config file not found: {config_path}") from None
+    except OSError as exc:
+        raise ValueError(f"cannot read config file ({type(exc).__name__})") from None
+
+    try:
+        data = tomllib.loads(raw.decode("utf-8"))
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
+        raise ValueError(f"invalid config file: {exc}") from None
+
+    return _validate(data)