Merge pull request 'Run as non-root by default via PUID/PGID' (#4) from dev-v1.1 into main

Reviewed-on: #4
2026-08-23 15:18:11 +02:00
parent a8ce9a5d1a 0cc1b3cb37
commit f8fd388ade
7 changed files with 187 additions and 69 deletions
@@ -1,3 +1,5 @@
+PUID=1000 # User id the process runs as
+PGID=1000 # Group id the process runs as
 TARGET_HOST= # Target hostname/IP to proxy to
 TARGET_PORT= # Target port to proxy to
 UNIX_SOCKET_NAME= # Name of the socket file
@@ -1,6 +1,6 @@
 FROM alpine:3.24.1 AS base

-RUN apk add --no-cache socat netcat-openbsd \
+RUN apk add --no-cache socat netcat-openbsd su-exec \
    && rm -rf /var/cache/apk/* /tmp/*

 COPY entrypoint.sh VERSION /
@@ -46,6 +46,8 @@ Proxy Docker socket from a docker proxy to a container in host mode without dire

 | Variable | Default | Description | Example |
 |----------|---------|-------------|---------|
+| `PUID` | `911` | User ID the process runs as (drops root at startup) | `1000` |
+| `PGID` | `911` | Group ID the process runs as | `1000` |
 | `TARGET_HOST` | - | Target hostname/IP to proxy to | `socket-proxy-beszel` |
 | `TARGET_PORT` | - | Target port to proxy to | `2375` |
 | `UNIX_SOCKET_NAME` | - | Name of the socket file | `docker.sock` |
@@ -59,6 +61,8 @@ Proxy Docker socket from a docker proxy to a container in host mode without dire

 1. Create a `.env` file with your configuration:
 ```bash
+PUID=1000 #user id the process runs as
+PGID=1000 #group id the process runs as
 TARGET_HOST= #your target host
 TARGET_PORT= #your target host port
 UNIX_SOCKET_NAME= #your socket file name
@@ -73,6 +77,8 @@ services:
  socat-proxy:
    image: git.djeex.fr/djeex/socat-proxy:latest
    environment:
+      - PUID=${PUID}
+      - PGID=${PGID}
      - TARGET_HOST=${TARGET_HOST}
      - TARGET_PORT=${TARGET_PORT}
      - UNIX_SOCKET_NAME=${UNIX_SOCKET_NAME}
@@ -94,6 +100,8 @@ docker compose up -d
 ```bash
 docker run -d \
  --name socat-proxy \
+  -e PUID=1000 #user id the process runs as \
+  -e PGID=1000 #group id the process runs as \
  -e TARGET_HOST= #your target host \
  -e TARGET_PORT= #your target host port \
  -e UNIX_SOCKET_NAME= #your socket file name \
@@ -1 +1 @@
-1.0.1
+1.1.0
@@ -3,6 +3,8 @@ services:
  socat-proxy:
    build: .
    environment:
+      - PUID=${PUID}
+      - PGID=${PGID}
      - TARGET_HOST=${TARGET_HOST}
      - TARGET_PORT=${TARGET_PORT}
      - UNIX_SOCKET_NAME=${UNIX_SOCKET_NAME}
@@ -4,6 +4,52 @@ set -e
 CYAN="\033[1;36m"
 NC="\033[0m"

+log()  { echo "$(date '+%Y-%m-%d %H:%M:%S') $*"; }
+fail() { echo "$(date '+%Y-%m-%d %H:%M:%S') [!] $*" >&2; exit 1; }
+
+print_banner() {
+    version=$(cat VERSION 2>/dev/null || echo "unknown")
+    title="Socat Proxy - Version ${version}"
+    lines="Source: https://git.djeex.fr/Djeex/socat-proxy
+Mirror: https://github.com/Djeex/socat-proxy"
+
+    width=${#title}
+    old_ifs=$IFS
+    IFS='
+'
+    for l in $lines; do
+        [ ${#l} -gt "$width" ] && width=${#l}
+    done
+    IFS=$old_ifs
+    width=$((width + 2))
+
+    border=""
+    i=0
+    while [ "$i" -lt "$width" ]; do
+        border="${border}─"
+        i=$((i + 1))
+    done
+    printf "${CYAN}╭%s╮${NC}\n" "$border"
+
+    total_pad=$((width - ${#title}))
+    left=$((total_pad / 2))
+    right=$((total_pad - left))
+    printf "${CYAN}│${NC}%*s%s%*s${CYAN}│${NC}\n" "$left" "" "$title" "$right" ""
+
+    printf "${CYAN}├%s┤${NC}\n" "$border"
+
+    IFS='
+'
+    for l in $lines; do
+        printf "${CYAN}│${NC} %-*s${CYAN}│${NC}\n" "$((width - 1))" "$l"
+    done
+    IFS=$old_ifs
+
+    printf "${CYAN}╰%s╯${NC}\n" "$border"
+}
+
+print_banner
+
 DEBUG_LEVEL=${DEBUG_LEVEL:-1}
 UNIX_SOCKET_PATH=${UNIX_SOCKET_PATH%/}
 HOST_SOCKET_PATH=${HOST_SOCKET_PATH%/}
@@ -11,107 +57,116 @@ HOST_SOCKET_PATH=${HOST_SOCKET_PATH%/}
 FULL_HOST_SOCKET_PATH="$HOST_SOCKET_PATH/$UNIX_SOCKET_NAME"
 FULL_UNIX_SOCKET_PATH="$UNIX_SOCKET_PATH/$UNIX_SOCKET_NAME"

-VERSION=$(cat VERSION)
-
-echo -e "${CYAN}╭────────────────────────────────────────────────╮${NC}"
-echo -e "${CYAN}│${NC}            Socat-proxy - Version ${VERSION}${NC}         ${CYAN}│${NC}"
-echo -e "${CYAN}├────────────────────────────────────────────────┤${NC}"
-echo -e "${CYAN}│${NC} Source: https://git.djeex.fr/Djeex/socat-proxy ${CYAN}│${NC}"
-echo -e "${CYAN}│${NC} Mirror: https://github.com/Djeex/socat-proxy   ${CYAN}│${NC}"
-echo -e "${CYAN}╰────────────────────────────────────────────────╯${NC}"
-
-
 # Validate required environment variables
-if [ -z "$TARGET_HOST" ]; then
-    echo "[✗] TARGET_HOST environment variable is required"
-    exit 1
-fi
+[ -n "$TARGET_HOST" ] || fail "TARGET_HOST environment variable is required"
+[ -n "$TARGET_PORT" ] || fail "TARGET_PORT environment variable is required"
+[ -n "$UNIX_SOCKET_NAME" ] || fail "UNIX_SOCKET_NAME environment variable is required"
+[ -n "$UNIX_SOCKET_PATH" ] || fail "UNIX_SOCKET_PATH environment variable is required"
+[ -n "$HOST_SOCKET_PATH" ] || fail "HOST_SOCKET_PATH environment variable is required"

-if [ -z "$TARGET_PORT" ]; then
-    echo "[✗] TARGET_PORT environment variable is required"
-    exit 1
-fi
+PUID=${PUID:-911}
+PGID=${PGID:-911}

-if [ -z "$UNIX_SOCKET_NAME" ]; then
-    echo "[✗] UNIX_SOCKET_NAME environment variable is required"
-    exit 1
-fi
+case "$PGID" in
+    ''|*[!0-9]*) fail "PGID '$PGID' is not a valid numeric group id." ;;
+esac
+case "$PUID" in
+    ''|*[!0-9]*) fail "PUID '$PUID' is not a valid numeric user id." ;;
+esac

-if [ -z "$UNIX_SOCKET_PATH" ]; then
-    echo "[✗] UNIX_SOCKET_PATH environment variable is required"
-    exit 1
-fi
+log "[i] Requested PUID=$PUID, PGID=$PGID"

-if [ -z "$HOST_SOCKET_PATH" ]; then
-    echo "[✗] HOST_SOCKET_PATH environment variable is required"
-    exit 1
+log "[~] Checking group for GID $PGID..."
+GROUP_NAME=$(getent group "$PGID" | cut -d: -f1 || true)
+if [ -z "$GROUP_NAME" ]; then
+    log "[→] No existing group with GID $PGID, creating 'appgroup'."
+    addgroup -g "$PGID" appgroup || fail "Failed to create group with GID $PGID (addgroup exited $?)."
+    GROUP_NAME=appgroup
+else
+    log "[i] Reusing existing group '$GROUP_NAME' (GID $PGID)."
 fi
+log "[✓] Group ready: $GROUP_NAME"

-echo "[~] Starting socat proxy..."
-echo "[i] TCP target: $TARGET_HOST:$TARGET_PORT"
-echo "[i] HOST path: $HOST_SOCKET_PATH"
-echo "[i] Full host socket path: $FULL_HOST_SOCKET_PATH"
-echo "[i] Full socket path: $FULL_UNIX_SOCKET_PATH"
+log "[~] Checking user for UID $PUID..."
+USER_NAME=$(getent passwd "$PUID" | cut -d: -f1 || true)
+if [ -z "$USER_NAME" ]; then
+    log "[→] No existing user with UID $PUID, creating 'appuser'."
+    adduser -D -u "$PUID" -G "$GROUP_NAME" appuser || fail "Failed to create user with UID $PUID (adduser exited $?)."
+    USER_NAME=appuser
+else
+    log "[i] Reusing existing user '$USER_NAME' (UID $PUID)."
+fi
+log "[✓] User ready: $USER_NAME"
+
+log "[~] Starting socat proxy..."
+log "[i] TCP target: $TARGET_HOST:$TARGET_PORT"
+log "[i] HOST path: $HOST_SOCKET_PATH"
+log "[i] Full host socket path: $FULL_HOST_SOCKET_PATH"
+log "[i] Full socket path: $FULL_UNIX_SOCKET_PATH"

 # Check if socket file/folder exists and handle it
 if [ -e "$FULL_UNIX_SOCKET_PATH" ]; then
-    echo "[~] Socket file/folder $FULL_UNIX_SOCKET_PATH exists, removing it..."
+    log "[~] Socket file/folder $FULL_UNIX_SOCKET_PATH exists, removing it..."
    if rm -rf "$FULL_UNIX_SOCKET_PATH"; then
-        echo "[✓] Removed existing socket $FULL_UNIX_SOCKET_PATH"
+        log "[✓] Removed existing socket $FULL_UNIX_SOCKET_PATH"
    else
-        echo "[✗] Failed to remove existing socket $FULL_UNIX_SOCKET_PATH"
-        exit 1
+        fail "Failed to remove existing socket $FULL_UNIX_SOCKET_PATH"
    fi
 fi

-echo "[~] Creating socket directory structure..."
+log "[~] Creating socket directory structure..."
 # Create directory if needed
 if mkdir -p "$UNIX_SOCKET_PATH"; then
-    echo "[✓] Created directory $UNIX_SOCKET_PATH"
+    log "[✓] Created directory $UNIX_SOCKET_PATH"
 else
-    echo "[✗] Failed to create directory $UNIX_SOCKET_PATH"
-    exit 1
+    fail "Failed to create directory $UNIX_SOCKET_PATH"
 fi

-echo "[~] Creating socket with netcat..."
+# Grant the target user write access to the socket directory so the
+# su-exec'd socat process below can create the socket file in it.
+log "[~] Setting ownership of $UNIX_SOCKET_PATH to $USER_NAME:$GROUP_NAME..."
+chown "$USER_NAME:$GROUP_NAME" "$UNIX_SOCKET_PATH" || fail "chown on $UNIX_SOCKET_PATH failed — check that the host directory permissions allow it."
+log "[✓] Ownership set on $UNIX_SOCKET_PATH"
+
+log "[~] Preparing socket path..."
 # Create socket file by touching it, then remove it (this creates the path but leaves it clean for socat)
 touch "$FULL_UNIX_SOCKET_PATH"
 rm "$FULL_UNIX_SOCKET_PATH"
-echo "[✓] Socket path prepared at $FULL_UNIX_SOCKET_PATH"
+log "[✓] Socket path prepared at $FULL_UNIX_SOCKET_PATH"

 # Debug: Check if socket file exists and its permissions
 if [ -S "$FULL_UNIX_SOCKET_PATH" ]; then
-    echo "[✓] Socket file exists and is a socket"
+    log "[✓] Socket file exists and is a socket"
    ls -la "$FULL_UNIX_SOCKET_PATH"
 else
-    echo "[!] Socket file does not exist or is not a socket"
+    log "[!] Socket file does not exist or is not a socket"
    ls -la "$UNIX_SOCKET_PATH"
 fi

-echo "[~] Testing connection to target..."
+log "[~] Testing connection to target..."
 # Test if we can reach the target before starting socat
 if ! nc -z "$TARGET_HOST" "$TARGET_PORT" 2>/dev/null; then
-    echo "[!] Cannot connect to $TARGET_HOST:$TARGET_PORT - socat will retry automatically"
+    log "[!] Cannot connect to $TARGET_HOST:$TARGET_PORT - socat will retry automatically"
 else
-    echo "[✓] Connection to $TARGET_HOST:$TARGET_PORT is working"
+    log "[✓] Connection to $TARGET_HOST:$TARGET_PORT is working"
 fi

 # Signal handler for graceful shutdown
 cleanup() {
-    echo "[!] Received SIGTERM, shutting down gracefully..."
-    if [ ! -z "$SOCAT_PID" ]; then
-        echo "[~] Stopping socat process (PID: $SOCAT_PID)..."
+    log "[!] Received SIGTERM, shutting down gracefully..."
+    if [ -n "$SOCAT_PID" ]; then
+        log "[~] Stopping socat process (PID: $SOCAT_PID)..."
        kill "$SOCAT_PID" 2>/dev/null || true
        wait "$SOCAT_PID" 2>/dev/null || true
    fi
-    echo "[~] Cleanup completed, exiting..."
+    log "[~] Cleanup completed, exiting..."
    exit 0
 }

 # Set up signal trap
 trap cleanup SIGTERM SIGINT

-echo "[~] Starting socat proxy..."
+log "[~] Starting socat proxy..."
 # Start socat with configurable verbosity
 DEBUG_FLAGS=""
 if [ "$DEBUG_LEVEL" -eq 1 ]; then
@@ -122,25 +177,29 @@ elif [ "$DEBUG_LEVEL" -eq 3 ]; then
    DEBUG_FLAGS="-d -d -d"
 fi

-echo "[i] Using debug level: $DEBUG_LEVEL ($DEBUG_FLAGS)"
+log "[i] Using debug level: $DEBUG_LEVEL ($DEBUG_FLAGS)"

-if socat $DEBUG_FLAGS UNIX-LISTEN:$FULL_UNIX_SOCKET_PATH,fork,unlink-early TCP:$TARGET_HOST:$TARGET_PORT & then
+# mode=666 keeps the socket connectable from another container's UID
+# regardless of PUID/PGID here — see project notes on the socket
+# permission trade-off (this proxy's own threat model is the host/network
+# boundary, not multi-tenant isolation between containers on the same host).
+log "[→] Dropping privileges to $USER_NAME:$GROUP_NAME and starting socat"
+if su-exec "$USER_NAME:$GROUP_NAME" socat $DEBUG_FLAGS UNIX-LISTEN:$FULL_UNIX_SOCKET_PATH,fork,unlink-early,mode=666 TCP:$TARGET_HOST:$TARGET_PORT & then
    SOCAT_PID=$!
-    echo "[✓] Socat started with PID: $SOCAT_PID"
-    echo "[i] Socat command: socat -d -d UNIX-LISTEN:$FULL_UNIX_SOCKET_PATH,fork,unlink-early TCP:$TARGET_HOST:$TARGET_PORT"
-    echo "[~] Container is ready and running..."
+    log "[✓] Socat started with PID: $SOCAT_PID"
+    log "[i] Socat command: socat $DEBUG_FLAGS UNIX-LISTEN:$FULL_UNIX_SOCKET_PATH,fork,unlink-early,mode=666 TCP:$TARGET_HOST:$TARGET_PORT"
+    log "[~] Container is ready and running..."

    # Debug: Check socket after socat starts
    sleep 2
    if [ -S "$FULL_UNIX_SOCKET_PATH" ]; then
-        echo "[✓] Socat socket is active"
+        log "[✓] Socat socket is active"
        ls -la "$FULL_UNIX_SOCKET_PATH"
    else
-        echo "[!] Socat socket not found"
+        log "[!] Socat socket not found"
    fi
 else
-    echo "[✗] Failed to start socat proxy"
-    exit 1
+    fail "Failed to start socat proxy"
 fi

 # Keep the script alive and wait for socat process
@@ -148,5 +207,4 @@ while kill -0 "$SOCAT_PID" 2>/dev/null; do
    sleep 1
 done

-echo "[✗] Socat process has stopped"
-exit 1
+fail "Socat process has stopped"
@@ -15,6 +15,11 @@

 setup() {
    TEST_DIR="$(mktemp -d)"
+    # mktemp defaults to 700 (root-only traversal); a real bind-mounted host
+    # directory is typically world-traversable, so match that here — otherwise
+    # the non-root user entrypoint.sh drops to can't even reach its own
+    # (correctly chowned) socket subdirectory.
+    chmod 755 "$TEST_DIR"
    cp "$BATS_TEST_DIRNAME/../entrypoint.sh" "$TEST_DIR/"
    cp "$BATS_TEST_DIRNAME/../VERSION" "$TEST_DIR/"
    chmod +x "$TEST_DIR/entrypoint.sh"
@@ -36,7 +41,9 @@ teardown() {

 run_entrypoint_bg() {
    LOG="$TEST_DIR/out.log"
-    ( cd "$TEST_DIR" && exec ./entrypoint.sh >"$LOG" 2>&1 ) &
+    # Invoked via the absolute path (not a bare `./entrypoint.sh`) so its
+    # /proc cmdline actually contains $TEST_DIR for entrypoint_pid() to match.
+    ( cd "$TEST_DIR" && exec "$TEST_DIR/entrypoint.sh" >"$LOG" 2>&1 ) &
    disown 2>/dev/null || true
 }

@@ -106,6 +113,47 @@ wait_for_pid_gone() {
    [[ "$output" == *"HOST_SOCKET_PATH environment variable is required"* ]]
 }

+# ---- PUID/PGID privilege dropping ------------------------------------------
+
+@test "fails when PUID is not numeric" {
+    export PUID=abc
+    run "$TEST_DIR/entrypoint.sh"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"PUID 'abc' is not a valid numeric user id."* ]]
+}
+
+@test "fails when PGID is not numeric" {
+    export PGID=abc
+    run "$TEST_DIR/entrypoint.sh"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"PGID 'abc' is not a valid numeric group id."* ]]
+}
+
+@test "creates appuser/appgroup at the default 911 PUID/PGID and owns the socket dir" {
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+    grep -q "No existing group with GID 911, creating 'appgroup'" "$LOG"
+    grep -q "No existing user with UID 911, creating 'appuser'" "$LOG"
+    owner="$(stat -c '%U:%G' "$UNIX_SOCKET_PATH")"
+    [ "$owner" = "appuser:appgroup" ]
+}
+
+@test "reuses an existing user/group instead of creating one" {
+    export PUID=0
+    export PGID=0
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+    grep -q "Reusing existing group 'root' (GID 0)" "$LOG"
+    grep -q "Reusing existing user 'root' (UID 0)" "$LOG"
+}
+
+@test "creates the socket with mode 666 so other-UID consumers can connect" {
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+    mode="$(stat -c '%a' "$UNIX_SOCKET_PATH/$UNIX_SOCKET_NAME")"
+    [ "$mode" = "666" ]
+}
+
@test "prints the version banner from the VERSION file" {
    echo "9.9.9" > "$TEST_DIR/VERSION"
    run_entrypoint_bg
@@ -1 +1 @@
 .0.1
 .1.0