From d53db2da0659245da8f15d6a727b6e06f01f71c0 Mon Sep 17 00:00:00 2001
From: Albrecht Degering <albrecht@degering.name>
Date: Wed, 22 Jul 2026 04:48:10 +0200
Subject: [PATCH] fix(audit): bridge Docker from Flatpak sandboxes

---
 docs/SECURITY_AUDIT.md             |  8 +++++++
 tools/checks/security-audit/run.sh | 38 +++++++++++++++++++++++++-----
 2 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/docs/SECURITY_AUDIT.md b/docs/SECURITY_AUDIT.md
index 65e1a38..6071c0d 100644
--- a/docs/SECURITY_AUDIT.md
+++ b/docs/SECURITY_AUDIT.md
@@ -33,6 +33,14 @@ cd /mnt/DATA/git/govoplan
 tools/checks/security-audit/run.sh --mode full --scope govoplan
 ```
 
+When invoked from a Flatpak development environment without a sandbox-local
+Docker CLI, the wrapper automatically uses `flatpak-spawn --host docker`. The
+host account must still be allowed to open the Docker daemon socket. For a
+conventional rootful installation this commonly means membership in the
+`docker` group followed by a complete logout/login; that membership is
+root-equivalent, so rootless Docker is preferable where the deployment policy
+requires a smaller privilege boundary.
+
 Reports are written to `audit-reports/`, which is intentionally ignored by git.
 Each run records tool versions, report checksums, and start/end repository
 revision plus worktree fingerprints. A repository change during scanning makes
diff --git a/tools/checks/security-audit/run.sh b/tools/checks/security-audit/run.sh
index 85b7be8..40d9ebd 100644
--- a/tools/checks/security-audit/run.sh
+++ b/tools/checks/security-audit/run.sh
@@ -71,6 +71,32 @@ REBUILD="${REBUILD:-0}"
 UPDATE="${UPDATE:-0}"
 BUILD_ONLY="${BUILD_ONLY:-0}"
 
+declare -a DOCKER_CLI=()
+DOCKER_LOCATION=""
+if command -v docker >/dev/null 2>&1; then
+  DOCKER_CLI=(docker)
+  DOCKER_LOCATION="current environment"
+elif command -v flatpak-spawn >/dev/null 2>&1 \
+  && flatpak-spawn --host sh -lc 'command -v docker >/dev/null 2>&1'; then
+  DOCKER_CLI=(flatpak-spawn --host docker)
+  DOCKER_LOCATION="Flatpak host"
+else
+  echo "Docker is not available in this environment or through a Flatpak host bridge." >&2
+  echo "Install Docker, expose its CLI/socket, or run this script from the host." >&2
+  exit 1
+fi
+
+if ! DOCKER_VERSION_OUTPUT="$("${DOCKER_CLI[@]}" version --format '{{.Server.Version}}' 2>&1)"; then
+  echo "Docker was found on the $DOCKER_LOCATION, but its daemon is not accessible:" >&2
+  printf '  %s\n' "$DOCKER_VERSION_OUTPUT" >&2
+  if [[ "$DOCKER_LOCATION" == "Flatpak host" && "$DOCKER_VERSION_OUTPUT" == *"permission denied"* ]]; then
+    echo "Grant the host account access to the Docker socket, then fully log out and back in." >&2
+    echo "On a conventional rootful Docker installation: sudo usermod -aG docker \"$(id -un)\"" >&2
+    echo "Membership in the docker group is root-equivalent; use rootless Docker instead where that is preferred." >&2
+  fi
+  exit 1
+fi
+
 IMAGE_NAME="${IMAGE##*/}"
 if [[ "$IMAGE_NAME" == *:* ]]; then
   IMAGE_REPOSITORY="${IMAGE%:*}"
@@ -95,21 +121,21 @@ build_image() {
   if [[ "$UPDATE" == "1" ]]; then
     build_args=(--pull --no-cache "${build_args[@]}")
   fi
-  docker build "${build_args[@]}" "$ROOT"
+  "${DOCKER_CLI[@]}" build "${build_args[@]}" "$ROOT"
 }
 
-if [[ "$REBUILD" == "1" ]] || ! docker image inspect "$FINGERPRINT_IMAGE" >/dev/null 2>&1; then
+if [[ "$REBUILD" == "1" ]] || ! "${DOCKER_CLI[@]}" image inspect "$FINGERPRINT_IMAGE" >/dev/null 2>&1; then
   echo "Building security audit toolbox image: $FINGERPRINT_IMAGE"
   build_image
 else
   echo "Reusing security audit toolbox image: $FINGERPRINT_IMAGE"
-  if ! docker image inspect "$IMAGE_ALIAS" >/dev/null 2>&1; then
-    docker tag "$FINGERPRINT_IMAGE" "$IMAGE_ALIAS"
+  if ! "${DOCKER_CLI[@]}" image inspect "$IMAGE_ALIAS" >/dev/null 2>&1; then
+    "${DOCKER_CLI[@]}" tag "$FINGERPRINT_IMAGE" "$IMAGE_ALIAS"
   fi
 fi
 
 if [[ "$BUILD_ONLY" == "1" ]]; then
-  docker image inspect "$FINGERPRINT_IMAGE" --format 'Built audit toolbox image {{.RepoTags}} {{.Id}}'
+  "${DOCKER_CLI[@]}" image inspect "$FINGERPRINT_IMAGE" --format 'Built audit toolbox image {{.RepoTags}} {{.Id}}'
   exit 0
 fi
 
@@ -123,7 +149,7 @@ else
   EXTRA_ENV=()
 fi
 
-docker run --rm \
+"${DOCKER_CLI[@]}" run --rm \
   --user "$(id -u):$(id -g)" \
   -e HOME=/tmp/security-audit-home \
   -e SECURITY_AUDIT_SCOPE="$SCOPE" \