From fff6e49350a298d3d9ef61d89906a81ad96a8e59 Mon Sep 17 00:00:00 2001 From: Djeex Date: Sun, 23 Aug 2026 15:08:36 +0200 Subject: [PATCH] Run as non-root by default via PUID/PGID --- .env | 2 + Dockerfile | 2 +- README.MD | 8 ++ VERSION | 2 +- docker-compose.yaml | 2 + entrypoint.sh | 190 +++++++++++++++++++++++++++--------------- tests/entrypoint.bats | 50 ++++++++++- 7 files changed, 187 insertions(+), 69 deletions(-) diff --git a/.env b/.env index d9a812b..531504d 100644 --- a/.env +++ b/.env @@ -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 diff --git a/Dockerfile b/Dockerfile index 1983b77..524af92 100644 --- a/Dockerfile +++ b/Dockerfile @@ -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 / diff --git a/README.MD b/README.MD index 822c619..989a9e8 100644 --- a/README.MD +++ b/README.MD @@ -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 \ diff --git a/VERSION b/VERSION index 7dea76e..9084fa2 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.0.1 +1.1.0 diff --git a/docker-compose.yaml b/docker-compose.yaml index 78d82f5..95ad242 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -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} diff --git a/entrypoint.sh b/entrypoint.sh index b60c209..4c3923d 100644 --- a/entrypoint.sh +++ b/entrypoint.sh @@ -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 \ No newline at end of file +fail "Socat process has stopped" diff --git a/tests/entrypoint.bats b/tests/entrypoint.bats index 6ae2c7e..2146d76 100644 --- a/tests/entrypoint.bats +++ b/tests/entrypoint.bats @@ -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 -- 2.54.0