Repolode
Submit
Tecnativa

Tecnativa/docker-socket-proxy

A security-focused HAProxy proxy in front of the Docker socket that lets you allow or block specific Docker API sections via environment variables.

View on GitHub
Stars
2,850
Forks
211
Open issues
57
Last commit
2 months ago

What is it?

Docker Socket Proxy sits between a service and the Docker socket and filters which Docker API requests are accepted. Mounting the raw socket into a container effectively grants root access to the host, yet some services need it to react to events or manage containers. This proxy lets you expose only the parts of the API a service actually needs.

The proxy is built on the Alpine-based HAProxy image with a small configuration file. Each API section is controlled by an environment variable set to 1 to grant access or 0 to revoke it. Requests to revoked sections receive an HTTP 403 response. Events, ping and version are allowed by default, while security-critical sections such as AUTH and SECRETS, and write operations via POST, are revoked by default.

The image does not provide TLS and is meant to run on a private Docker network, not be exposed publicly. It supports a configurable socket path through SOCKET_PATH, for systems such as balenaOS, and a LOG_LEVEL setting. Multiple Docker API versions are supported, and images are published to Docker Hub and GitHub Container Registry.

Key features

  • 01Allows or denies Docker API sections through per-section environment variables.
  • 02Returns HTTP 403 for blocked requests.
  • 03Can restrict the proxy to read-only access by disabling POST.
  • 04Supports a custom socket path via SOCKET_PATH.
  • 05Built on Alpine and HAProxy with a small configuration file.
  • 06Covers multiple Docker API versions from 1.27 to 1.51.

Use cases

  • Giving a monitoring or reverse-proxy container read-only access to container events.
  • Limiting a CI or automation tool so it cannot run privileged operations on the host.
  • Exposing only the Docker API sections a Traefik-style service discovery tool needs.

Quick start

  1. 1

    Run the proxy container with access to the Docker socket

    docker container run -d --privileged --name dockerproxy -v /var/run/docker.sock:/var/run/docker.sock -p 127.0.0.1:2375:2375 tecnativa/docker-socket-proxy
  2. 2

    Point your local Docker client at the proxy

    export DOCKER_HOST=tcp://localhost:2375
  3. 3

    Check the connection with docker version

    docker version

Things to know

  • The container runs with --privileged, which the README says is required to connect to the Docker socket.
  • The image has no TLS support, so traffic is plain HTTP and must be kept on a restricted network.
  • Access to each Docker API section is off by default for security-critical areas and must be granted deliberately.

In collections

Security scanners, audits & threat intel tools

Topics

#docker#security#proxy#haproxy#container#devops#hacktoberfest

FAQ

What is docker-socket-proxy?
A security-focused HAProxy proxy in front of the Docker socket that lets you allow or block specific Docker API sections via environment variables. Docker Socket Proxy sits between a service and the Docker socket and filters which Docker API requests are accepted. Mounting the raw socket into a container effectively grants root access to the host, yet some services need it to react to events or manage containers. This proxy lets you expose only the parts of the API a service actually needs.
Is docker-socket-proxy free to use? What license does it have?
docker-socket-proxy is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is docker-socket-proxy still maintained?
Updated within 6 months. The last commit to docker-socket-proxy was on Aug 31, 2026.
What can I use docker-socket-proxy for?
Giving a monitoring or reverse-proxy container read-only access to container events. Limiting a CI or automation tool so it cannot run privileged operations on the host. Exposing only the Docker API sections a Traefik-style service discovery tool needs.
How do I install docker-socket-proxy?
Run the proxy container with access to the Docker socket: docker container run -d --privileged --name dockerproxy -v /var/run/docker.sock:/var/run/docker.sock -p 127.0.0.1:2375:2375 tecnativa/docker-socket-proxy Point your local Docker client at the proxy: export DOCKER_HOST=tcp://localhost:2375 Check the connection with docker version: docker version
Where can I get docker-socket-proxy?
The source code and installation instructions are on GitHub: https://github.com/Tecnativa/docker-socket-proxy

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects