Nginx Docker Socket Permission Denied Fix

The Incident (What does the error mean?)

Raw error from Nginx error log:

2024/01/15 03:42:11 [crit] 29#29: *1 connect() to unix:/var/run/docker.sock failed
(13: Permission denied) while connecting to upstream, client: 172.18.0.1,
server: _, request: "GET /containers/json HTTP/1.1", upstream:
"http://unix:/var/run/docker.sock:/containers/json", host: "localhost"

What is immediately broken:

• Every upstream request Nginx proxies to the Docker API returns a 502.
• Any dashboard, reverse-proxy autodiscovery, or container introspection feature (Traefik-style label reads, Portainer agents, custom health UIs) is completely dead.
• If this is in a readiness probe path, your pod/container enters a crash loop.

Root cause in one line: /var/run/docker.sock is owned by root:docker with mode 660. The Nginx worker process is UID 101 (nginx user) and is not in the docker group, so the kernel denies the connect() syscall before a single byte is exchanged.

The Attack Vector / Blast Radius

This error is a symptom of a correct security boundary—but the wrong fix will create a critical vulnerability.

The naive fix developers reach for first:

chmod 777 /var/run/docker.sock   # DO NOT DO THIS

or

docker run --user root ...       # DO NOT DO THIS

Why that is catastrophic: The Docker socket is an unauthenticated root shell. Any process that can write to /var/run/docker.sock can:

1. POST /containers/create with Binds: ["/:/host"] and Privileged: true.
2. POST /containers/{id}/start
3. POST /containers/{id}/exec → execute arbitrary commands as root on the host.

This is a full container escape to host root in three API calls. CVSSv3 score for unrestricted Docker socket exposure: 9.8 (Critical). If your Nginx container is internet-facing and you chmod 777 the socket, you have handed the host to the first person who finds an Nginx RCE or SSRF.

Blast radius of the permission denied error itself:

• All Docker API proxy routes return 502.
• Autodiscovery pipelines stall.
• Monitoring agents lose container metadata.
• CI/CD pipelines that query container state will fail their health gates.

Prevention in CI/CD

1. Checkov — Block Raw Socket Mounts in IaC

Checkov rule CKV_DOCKER_1 flags privileged containers. Add a custom policy for socket mounts:

# .checkov/custom_policies/no_raw_docker_socket.yaml
metadata:
  name: "NoRawDockerSocketMount"
  id: "CKV2_DOCKER_CUSTOM_1"
  severity: CRITICAL
definition:
  and:
    - cond_type: attribute
      resource_types: [docker_container, docker_service]
      attribute: volumes
      operator: not_contains
      value: "/var/run/docker.sock:/var/run/docker.sock"

Run in CI:

checkov -d . --check CKV2_DOCKER_CUSTOM_1 --soft-fail-on MEDIUM

2. OPA/Conftest — Enforce Socket Proxy Pattern

# policy/docker_socket.rego
package docker

deny[msg] {
  input.services[name].volumes[_] == "/var/run/docker.sock:/var/run/docker.sock"
  input.services[name].image != "tecnativa/docker-socket-proxy"
  msg := sprintf("Service '%v' mounts raw Docker socket. Use tecnativa/docker-socket-proxy.", [name])
}

conftest test docker-compose.yml --policy policy/

3. GitHub Actions Gate

# .github/workflows/security.yml
- name: Lint Docker Compose for socket exposure
  run: |
    if grep -rn 'docker.sock' docker-compose*.yml | grep -v 'socket-proxy'; then
      echo "ERROR: Raw docker.sock mount detected outside socket-proxy service."
      exit 1
    fi

4. Dockerfile — Never Run as Root

 FROM nginx:alpine
+RUN addgroup -g 999 docker 2>/dev/null || true && \
+    adduser nginx docker
 USER nginx

Summary of controls: