From 5d61718c809af6444ca83c6dee9106a8e361473d Mon Sep 17 00:00:00 2001 From: Xinmin Zeng <135568692+fancyboi999@users.noreply.github.com> Date: Sun, 14 Jun 2026 11:03:50 +0800 Subject: [PATCH] fix(security): mount host Docker socket only in aio (DooD) sandbox mode (#3517) * fix(security): mount host Docker socket only in aio (DooD) sandbox mode The default Compose stack mounted /var/run/docker.sock read-write into the root gateway container in every sandbox mode, including the default `local` mode that never uses it -- an unnecessary host-escape surface (DooD = root-equivalent host control). deploy.sh already gated the socket *check* on sandbox_mode != local, but the Compose files mounted it unconditionally. Move the socket mount to an opt-in docker/docker-compose.dood.yaml overlay that deploy.sh / docker.sh append only when detect_sandbox_mode() returns `aio`. Default (local) and provisioner/Kubernetes modes no longer expose the host daemon. Tighten the socket existence check from != local to == aio. Document the DooD threat model in SECURITY.md. Reported by @greatmengqi. * refactor(docker): address review on socket-hardening PR - docker.sh: use absolute path for the dood overlay (match deploy.sh, drop cwd dependency) - deploy.sh: drop now-dead DEER_FLOW_DOCKER_SOCKET exports in down/build paths - docker-compose.yaml: fix stale header comment to point at the overlay Addresses codex + reviewer feedback on #3517. --------- Co-authored-by: Willem Jiang --- SECURITY.md | 39 +++++++++++++++++++++++++++++++++ docker/docker-compose-dev.yaml | 6 +++-- docker/docker-compose.dood.yaml | 25 +++++++++++++++++++++ docker/docker-compose.yaml | 8 ++++--- scripts/deploy.sh | 19 ++++++++-------- scripts/docker.sh | 14 ++++++++++++ 6 files changed, 96 insertions(+), 15 deletions(-) create mode 100644 docker/docker-compose.dood.yaml diff --git a/SECURITY.md b/SECURITY.md index d83e190e3..1dffa1d8a 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -11,6 +11,45 @@ Currently, we have two branches to maintain: Please go to https://github.com/bytedance/deer-flow/security to report the vulnerability you find. +## Sandbox Isolation and the Docker Socket (DooD) + +DeerFlow executes agent-generated shell/code through a configurable sandbox +(`sandbox.use` in `config.yaml`). The isolation guarantees differ by mode, and +one mode requires mounting the host Docker socket. Understand the trade-offs +before exposing an instance to untrusted input. + +| Mode | `config.yaml` | Host Docker socket | Isolation | +|------|---------------|--------------------|-----------| +| `local` (default) | `deerflow.sandbox.local:LocalSandboxProvider` | Not mounted | Commands run **inside the gateway container** on its filesystem. Not a strong boundary — `allow_host_bash` is `false` by default and should stay off for untrusted workloads. | +| `aio` (pure DooD) | `deerflow.community.aio_sandbox:AioSandboxProvider` (no `provisioner_url`) | **Mounted** (opt-in overlay) | Sandbox containers are started via the host Docker daemon. | +| `provisioner` (Kubernetes) | `AioSandboxProvider` + `provisioner_url` | Not mounted | Sandbox pods are created through the provisioner's K8s API over HTTP. Strongest isolation. | + +### The Docker socket is host root + +Mounting `/var/run/docker.sock` into a container grants that container +**root-equivalent control of the host**: anything able to reach the socket can +start a new container that bind-mounts the host filesystem and escape. This +matters for DeerFlow because the gateway executes model-generated commands, so a +prompt injection or any in-container code-execution primitive could pivot to the +host through the socket. + +To keep this off the default attack surface: + +- The host Docker socket is **not** mounted by the default Compose stack. It is + added only for `aio` mode through the opt-in `docker/docker-compose.dood.yaml` + overlay, which `scripts/deploy.sh` and `scripts/docker.sh` append + automatically when `detect_sandbox_mode()` returns `aio`. +- Prefer **provisioner/Kubernetes mode** for multi-tenant or internet-exposed + deployments — it isolates sandboxes without handing the gateway the host + daemon. +- If you must use `aio`/DooD, treat the host as part of the gateway's trust + boundary: run it on a dedicated host, and consider a scoped Docker API proxy + instead of the raw socket. + +> Note: the gateway bind-mounts `$HOME/.claude` and `$HOME/.codex` (read-only) +> for CLI auto-auth in **all** modes. These hold long-lived CLI credentials; +> scope or omit them when the gateway runs untrusted workloads. + ## CLI Credential Mounts (Claude Code / Codex) DeerFlow can reuse your Claude Code / Codex CLI subscription login as a model diff --git a/docker/docker-compose-dev.yaml b/docker/docker-compose-dev.yaml index f06bdf803..197d41110 100644 --- a/docker/docker-compose-dev.yaml +++ b/docker/docker-compose-dev.yaml @@ -146,8 +146,10 @@ services: # On macOS/Docker Desktop, uv may fail to create symlinks inside shared # host directories, which causes startup-time `uv sync` to crash. - gateway-uv-cache:/root/.cache/uv - # DooD: AioSandboxProvider runs inside the Gateway process. - - /var/run/docker.sock:/var/run/docker.sock + # DooD: the host Docker socket is NOT mounted by default. It is added only + # for aio (pure-DooD) sandbox mode via the opt-in docker-compose.dood.yaml + # overlay (appended by scripts/docker.sh). See SECURITY.md. + # CLI auth dirs (Claude Code / Codex) are NOT mounted by default: they # expose the entire ~/.claude and ~/.codex (history, projects, global # config, credentials) into the container. Mount them only when you use diff --git a/docker/docker-compose.dood.yaml b/docker/docker-compose.dood.yaml new file mode 100644 index 000000000..85bca9482 --- /dev/null +++ b/docker/docker-compose.dood.yaml @@ -0,0 +1,25 @@ +# DeerFlow — Docker-out-of-Docker (DooD) overlay (OPT-IN, NOT loaded by default) +# +# Mounts the host Docker socket into the gateway container so that +# AioSandboxProvider running in pure-Docker mode — config.yaml: +# sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider +# with NO provisioner_url — can start per-thread sandbox containers via the +# host Docker daemon. +# +# SECURITY: the host Docker socket grants the gateway container +# root-equivalent control of the host. Only load this overlay when you have +# explicitly chosen aio (DooD) sandbox mode and accept that trade-off. The +# default LocalSandboxProvider and the provisioner/Kubernetes mode do NOT need +# it and never load this file. See SECURITY.md for the full threat model. +# +# scripts/deploy.sh and scripts/docker.sh append this overlay automatically +# only when detect_sandbox_mode() returns "aio". Manual use: +# docker compose -f docker-compose.yaml -f docker-compose.dood.yaml up -d +# +# Compatible with both docker-compose.yaml (prod) and docker-compose-dev.yaml +# (dev): both define a `gateway` service, and Compose merges this volume entry +# onto it. DEER_FLOW_DOCKER_SOCKET defaults to /var/run/docker.sock. +services: + gateway: + volumes: + - ${DEER_FLOW_DOCKER_SOCKET:-/var/run/docker.sock}:/var/run/docker.sock diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml index 7370d0219..23191ec7a 100644 --- a/docker/docker-compose.yaml +++ b/docker/docker-compose.yaml @@ -13,7 +13,7 @@ # DEER_FLOW_CONFIG_PATH — path to config.yaml # DEER_FLOW_EXTENSIONS_CONFIG_PATH — path to extensions_config.json # DEER_FLOW_SKILLS_PATH — skills dir, default $DEER_FLOW_PROJECT_ROOT/skills -# DEER_FLOW_DOCKER_SOCKET — Docker socket path, default /var/run/docker.sock +# DEER_FLOW_DOCKER_SOCKET — Docker socket path for aio/DooD mode, default /var/run/docker.sock (used only by the opt-in docker-compose.dood.yaml overlay) # DEER_FLOW_REPO_ROOT — repo root (used for skills host path in DooD) # BETTER_AUTH_SECRET — required for frontend auth/session security # DEER_FLOW_INTERNAL_AUTH_TOKEN — shared internal Gateway auth token for multi-worker IM channels @@ -84,8 +84,10 @@ services: - ${DEER_FLOW_EXTENSIONS_CONFIG_PATH}:/app/backend/extensions_config.json:ro - ../skills:/app/skills:ro - ${DEER_FLOW_HOME}:/app/backend/.deer-flow - # DooD: AioSandboxProvider starts sandbox containers via host Docker daemon - - ${DEER_FLOW_DOCKER_SOCKET}:/var/run/docker.sock + # DooD: the host Docker socket is NOT mounted by default. It is added only + # for aio (pure-DooD) sandbox mode via the opt-in docker-compose.dood.yaml + # overlay (appended by scripts/deploy.sh). See SECURITY.md. + # CLI auth dirs (Claude Code / Codex) are NOT mounted by default: they # expose the entire ~/.claude and ~/.codex (history, projects, global # config, credentials) into the container. Mount them only when you use diff --git a/scripts/deploy.sh b/scripts/deploy.sh index bfef7e30e..a5b36aa5b 100755 --- a/scripts/deploy.sh +++ b/scripts/deploy.sh @@ -215,7 +215,6 @@ if [ "$CMD" = "down" ]; then export DEER_FLOW_HOME="${DEER_FLOW_HOME:-$REPO_ROOT/backend/.deer-flow}" export DEER_FLOW_CONFIG_PATH="${DEER_FLOW_CONFIG_PATH:-$DEER_FLOW_HOME/config.yaml}" export DEER_FLOW_EXTENSIONS_CONFIG_PATH="${DEER_FLOW_EXTENSIONS_CONFIG_PATH:-$DEER_FLOW_HOME/extensions_config.json}" - export DEER_FLOW_DOCKER_SOCKET="${DEER_FLOW_DOCKER_SOCKET:-/var/run/docker.sock}" export DEER_FLOW_REPO_ROOT="${DEER_FLOW_REPO_ROOT:-$REPO_ROOT}" export BETTER_AUTH_SECRET="${BETTER_AUTH_SECRET:-placeholder}" export DEER_FLOW_INTERNAL_AUTH_TOKEN="${DEER_FLOW_INTERNAL_AUTH_TOKEN:-placeholder}" @@ -232,11 +231,6 @@ if [ "$CMD" = "build" ]; then echo "==========================================" echo "" - # Docker socket is needed for compose to parse volume specs - if [ -z "$DEER_FLOW_DOCKER_SOCKET" ]; then - export DEER_FLOW_DOCKER_SOCKET="/var/run/docker.sock" - fi - "${COMPOSE_CMD[@]}" build echo "" @@ -270,20 +264,25 @@ if [ "$sandbox_mode" = "provisioner" ]; then services="$services provisioner" fi -# ── DEER_FLOW_DOCKER_SOCKET ─────────────────────────────────────────────────── +# ── DEER_FLOW_DOCKER_SOCKET (aio / pure-DooD mode only) ────────────────────── +# Only aio mode (AioSandboxProvider without provisioner_url) needs the host +# Docker socket. It is mounted via the opt-in docker-compose.dood.yaml overlay, +# appended here, so the default (local) and provisioner modes never expose the +# host daemon. Mounting the socket = root-equivalent host control; see SECURITY.md. if [ -z "$DEER_FLOW_DOCKER_SOCKET" ]; then export DEER_FLOW_DOCKER_SOCKET="/var/run/docker.sock" fi -if [ "$sandbox_mode" != "local" ]; then +if [ "$sandbox_mode" = "aio" ]; then if [ ! -S "$DEER_FLOW_DOCKER_SOCKET" ]; then echo -e "${RED}⚠ Docker socket not found at $DEER_FLOW_DOCKER_SOCKET${NC}" echo " AioSandboxProvider (DooD) will not work." exit 1 - else - echo -e "${GREEN}✓ Docker socket: $DEER_FLOW_DOCKER_SOCKET${NC}" fi + echo -e "${GREEN}✓ Docker socket: $DEER_FLOW_DOCKER_SOCKET${NC}" + echo -e "${YELLOW} Mounting host Docker socket into gateway (DooD = host root-equivalent). See SECURITY.md.${NC}" + COMPOSE_CMD+=(-f "$DOCKER_DIR/docker-compose.dood.yaml") fi echo "" diff --git a/scripts/docker.sh b/scripts/docker.sh index 9db74a4f5..8123d42f1 100755 --- a/scripts/docker.sh +++ b/scripts/docker.sh @@ -196,6 +196,20 @@ start() { services="frontend gateway provisioner nginx" fi + # Only aio mode (AioSandboxProvider without provisioner_url) needs the host + # Docker socket. Mount it via the opt-in docker-compose.dood.yaml overlay so + # the default (local) and provisioner modes never expose the host daemon. + # Mounting the socket = root-equivalent host control; see SECURITY.md. + if [ "$sandbox_mode" = "aio" ]; then + local docker_socket="${DEER_FLOW_DOCKER_SOCKET:-/var/run/docker.sock}" + if [ ! -S "$docker_socket" ]; then + echo -e "${YELLOW}⚠ Docker socket not found at $docker_socket — AioSandboxProvider (DooD) will not work.${NC}" + exit 1 + fi + echo -e "${YELLOW}Mounting host Docker socket into gateway (DooD = host root-equivalent). See SECURITY.md.${NC}" + COMPOSE_CMD="$COMPOSE_CMD -f $DOCKER_DIR/docker-compose.dood.yaml" + fi + echo -e "${BLUE}Runtime: Gateway embedded agent runtime${NC}" echo -e "${BLUE}Detected sandbox mode: $sandbox_mode${NC}" if [ "$sandbox_mode" = "provisioner" ]; then