docker-socket-proxy

Proxy over your Docker socket to restrict which requests it accepts

1,386

159

1,386

View on GitHub

Top Related Projects

rancher

23,337

Complete container management platform

portainer

30,364

Making Docker and Kubernetes management easy.

fluent-bit

5,723

Fast and Lightweight Logs and Metrics processor for Linux, BSD, OSX and Windows

traefik

50,858

The Cloud Native Application Proxy

Quick Overview

Docker Socket Proxy is a security-enhancing Docker image that acts as a proxy for the Docker socket. It allows you to expose the Docker socket to other containers or the host network while providing fine-grained access control, reducing the risk of unauthorized access and potential security breaches.

Pros

Improves security by limiting access to specific Docker API endpoints
Allows for easy configuration of allowed Docker commands through environment variables
Lightweight and easy to deploy as a Docker container
Supports TLS encryption for secure communication

Cons

Adds an extra layer of complexity to Docker setups
May introduce a slight performance overhead due to the proxy layer
Requires careful configuration to ensure proper access control
Limited documentation and community support compared to more mainstream solutions

Getting Started

To use Docker Socket Proxy, follow these steps:

Pull the Docker image:

docker pull tecnativa/docker-socket-proxy

Run the container with desired access control:

docker run -d --name docker-socket-proxy \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e CONTAINERS=1 \
  -e IMAGES=1 \
  -e NETWORKS=0 \
  -e VOLUMES=0 \
  -p 2375:2375 \
  tecnativa/docker-socket-proxy

Configure other containers or services to use the proxy instead of the direct Docker socket:
```
docker run -e DOCKER_HOST=tcp://docker-socket-proxy:2375 your-image
```

This setup exposes the Docker API on port 2375, allowing access to container and image-related endpoints while restricting access to networks and volumes.

Competitor Comparisons

rancher

23,337

Complete container management platform

Pros of Rancher

Comprehensive container management platform with a user-friendly web interface
Supports multi-cluster management and provides advanced orchestration features
Offers built-in monitoring, logging, and security features

Cons of Rancher

More complex setup and resource-intensive compared to lightweight alternatives
Steeper learning curve for users new to container orchestration
May introduce additional overhead for simple Docker deployments

Code Comparison

Docker Socket Proxy:

version: "2.1"
services:
  dockerproxy:
    image: tecnativa/docker-socket-proxy
    privileged: true
    environment:
      CONTAINERS: 1

Rancher:

version: '2'
services:
  rancher:
    image: rancher/rancher:latest
    privileged: true
    ports:
      - "80:80"
      - "443:443"

Summary

Docker Socket Proxy is a lightweight solution focused on providing secure access to the Docker socket, while Rancher is a full-featured container management platform. Docker Socket Proxy is simpler to set up and use for basic Docker socket access control, whereas Rancher offers a more comprehensive set of features for managing complex container environments across multiple clusters. The choice between the two depends on the specific needs of the project and the desired level of container orchestration and management capabilities.

portainer

30,364

Making Docker and Kubernetes management easy.

Pros of Portainer

Provides a comprehensive GUI for managing Docker environments
Offers advanced features like container management, volume control, and network configuration
Supports multiple Docker environments and orchestration platforms (e.g., Kubernetes)

Cons of Portainer

Heavier resource footprint due to its full-featured nature
Potentially introduces more security risks due to broader access to Docker functionality
Requires more setup and configuration for optimal security

Code Comparison

docker-socket-proxy:

docker run -d \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -p 2375:2375 \
    tecnativa/docker-socket-proxy

Portainer:

docker run -d \
    -p 8000:8000 -p 9000:9000 \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v portainer_data:/data \
    portainer/portainer-ce

Key Differences

docker-socket-proxy is a lightweight solution focused solely on providing secure access to the Docker socket, while Portainer is a full-featured management tool with a GUI. docker-socket-proxy is ideal for scenarios requiring minimal overhead and specific Docker socket access, whereas Portainer suits users needing comprehensive Docker management capabilities through a user-friendly interface.

fluent-bit

5,723

Fast and Lightweight Logs and Metrics processor for Linux, BSD, OSX and Windows

Pros of Fluent Bit

Highly efficient and lightweight log processor and forwarder
Supports multiple input sources and output destinations
Extensive plugin ecosystem for customization

Cons of Fluent Bit

More complex setup and configuration
Requires additional resources for log processing and forwarding

Code Comparison

Fluent Bit configuration example:

[INPUT]
    Name   docker
    Tag    docker.*

[OUTPUT]
    Name   stdout
    Match  *

Docker Socket Proxy configuration example:

version: '3'
services:
  dockerproxy:
    image: tecnativa/docker-socket-proxy
    environment:
      - CONTAINERS=1

Key Differences

Purpose: Fluent Bit is a log processor and forwarder, while Docker Socket Proxy is a security-focused Docker socket proxy
Functionality: Fluent Bit offers extensive log management capabilities, whereas Docker Socket Proxy provides controlled access to the Docker socket
Use case: Fluent Bit is ideal for log collection and processing in various environments, while Docker Socket Proxy is specifically designed for secure Docker API access

Conclusion

Choose Fluent Bit for comprehensive log management and processing needs across multiple platforms. Opt for Docker Socket Proxy when focusing on secure, controlled access to the Docker API in containerized environments.

traefik

50,858

The Cloud Native Application Proxy

Pros of Traefik

Full-featured reverse proxy and load balancer with automatic HTTPS
Dynamic configuration and service discovery for various backends
Extensive middleware support for customizing request/response handling

Cons of Traefik

More complex setup and configuration compared to simpler solutions
Higher resource usage due to its comprehensive feature set
Steeper learning curve for advanced configurations

Code Comparison

docker-socket-proxy:

version: '3'
services:
  proxy:
    image: tecnativa/docker-socket-proxy
    environment:
      CONTAINERS: 1

Traefik:

version: '3'
services:
  traefik:
    image: traefik:v2.5
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"

Summary

docker-socket-proxy is a lightweight solution focused on securing Docker socket access, while Traefik is a full-featured reverse proxy and load balancer. docker-socket-proxy is simpler to set up and use, with a primary focus on security. Traefik offers more advanced features and flexibility but requires more configuration and resources. Choose docker-socket-proxy for basic Docker socket security, or Traefik for a comprehensive reverse proxy solution with additional features like automatic HTTPS and dynamic service discovery.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Docker Socket Proxy

What?

This is a security-enhanced proxy for the Docker Socket.

Why?

Giving access to your Docker socket could mean giving root access to your host, or even to your whole swarm, but some services require hooking into that socket to react to events, etc. Using this proxy lets you block anything you consider those services should not do.

How?

We use the official Alpine-based HAProxy image with a small configuration file.

It blocks access to the Docker socket API according to the environment variables you set. It returns a HTTP 403 Forbidden status for those dangerous requests that should never happen.

Security recommendations

Never expose this container's port to a public network. Only to a Docker networks where only reside the proxy itself and the service that uses it.
Revoke access to any API section that you consider your service should not need.
This image does not include TLS support, just plain HTTP proxy to the host Docker Unix socket (which is not TLS protected even if you configured your host for TLS protection). This is by design because you are supposed to restrict access to it through Docker's built-in firewall.
Read the docs for the API version you are using, and know what you are doing.

Usage

Run the API proxy (--privileged flag is required here because it connects with the docker socket, which is a privileged connection in some SELinux/AppArmor contexts and would get locked otherwise):
```
$ 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
```
Connect your local docker client to that socket:
```
$ export DOCKER_HOST=tcp://localhost:2375
```

You can see the docker version:

$ docker version
Client:
 Version:      17.03.1-ce
 API version:  1.27
 Go version:   go1.7.5
 Git commit:   c6d412e
 Built:        Mon Mar 27 17:14:43 2017
 OS/Arch:      linux/amd64

Server:
 Version:      17.03.1-ce
 API version:  1.27 (minimum version 1.12)
 Go version:   go1.7.5
 Git commit:   c6d412e
 Built:        Mon Mar 27 17:14:43 2017
 OS/Arch:      linux/amd64
 Experimental: false

You cannot see running containers:

$ docker container ls
Error response from daemon: <html><body><h1>403 Forbidden</h1>
Request forbidden by administrative rules.
</body></html>

The same will happen to any containers that use this proxy's 2375 port to access the Docker socket API.

Grant or revoke access to certain API sections

You grant and revoke access to certain features of the Docker API through environment variables.

Normally the variables match the URL prefix (i.e. AUTH blocks access to /auth/* parts of the API, etc.).

Possible values for these variables:

0 to revoke access.
1 to grant access.

Access granted by default

These API sections are mostly harmless and almost required for any service that uses the API, so they are granted by default.

EVENTS
PING
VERSION

Access revoked by default

Security-critical

These API sections are considered security-critical, and thus access is revoked by default. Maximum caution when enabling these.

AUTH
SECRETS
POST: When disabled, only GET and HEAD operations are allowed, meaning any section of the API is read-only.

Not always needed

You will possibly need to grant access to some of these API sections, which are not so extremely critical but can expose some information that your service does not need.

BUILD
COMMIT
CONFIGS
CONTAINERS
ALLOW_START (containers/id/start)
ALLOW_STOP (containers/id/stop)
ALLOW_RESTARTS (containers/id/stop|restart|kill)
DISTRIBUTION
EXEC
GRPC
IMAGES
INFO
NETWORKS
NODES
PLUGINS
SERVICES
SESSION
SWARM
SYSTEM
TASKS
VOLUMES

Use a different Docker socket location

If your OS stores its Docker socket in a different location and you are unable to bind mount it in your container specification, you can specify this via the SOCKET_PATH environment variable.

For example, balenaOS exposes its socket at /var/run/balena-engine.sock. To accommodate this, merely set the SOCKET_PATH environment variable to /var/run/balena-engine.sock.

Development

All the dependencies you need to develop this project (apart from Docker itself) are managed with poetry.

To set up your development environment, run:

poetry install

Testing

To run the tests locally, add --prebuild to autobuild the image before testing:

poetry run pytest --prebuild

By default, the image that the tests use (and optionally prebuild) is named docker-socket-proxy:local. If you prefer, you can build it separately before testing, and remove the --prebuild flag, to run the tests with that image you built:

docker image build -t docker-socket-proxy:local .
poetry run pytest

If you want to use a different image, export the DOCKER_IMAGE_NAME env variable with the name you want:

# To build it automatically
env DOCKER_IMAGE_NAME=my_custom_image poetry run pytest --prebuild

# To prebuild it separately
docker image build -t my_custom_image .
env DOCKER_IMAGE_NAME=my_custom_image poetry run pytest

Logging

You can set the logging level or severity level of the messages to be logged with the environment variable LOG_LEVEL. Default value is info. Possible values are: debug, info, notice, warning, err, crit, alert and emerg.

Supported API versions

Image tags

Right now, the only supported tags in our container images are the ones following this rules:

Each individual git released version will result in an image being tagged with the correspondent :{{version}}
:latest will refer to the latest released version in git.
:edge will be the version that is in the repo's master branch

Any other tag you find in our Docker Hub image is deprecated.

We recommend using GitHub Container Registry instead.

Feedback

Please send any issues to the issue tracker. For other kind of feedback, you can use our forum.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot