docker-socket-proxy/README.md

# Docker Socket Proxy

[![](https://images.microbadger.com/badges/version/tecnativa/docker-socket-proxy:latest.svg)](https://microbadger.com/images/tecnativa/docker-socket-proxy:latest "Get your own version badge on microbadger.com")
[![](https://images.microbadger.com/badges/image/tecnativa/docker-socket-proxy:latest.svg)](https://microbadger.com/images/tecnativa/docker-socket-proxy:latest "Get your own image badge on microbadger.com")
[![](https://images.microbadger.com/badges/commit/tecnativa/docker-socket-proxy:latest.svg)](https://microbadger.com/images/tecnativa/docker-socket-proxy:latest "Get your own commit badge on microbadger.com")
[![](https://images.microbadger.com/badges/license/tecnativa/docker-socket-proxy.svg)](https://microbadger.com/images/tecnativa/docker-socket-proxy "Get your own license badge on microbadger.com")

## 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](#suppported-api-versions) for the API version you are using,
  and **know what you are doing**.

## Usage

1.  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

2.  Connect your local docker client to that socket:

        $ export DOCKER_HOST=tcp://localhost

3.  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

4.  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`
- `DISTRIBUTION`
- `EXEC`
- `IMAGES`
- `INFO`
- `NETWORKS`
- `NODES`
- `PLUGINS`
- `SERVICES`
- `SESSION`
- `SWARM`
- `SYSTEM`
- `TASKS`
- `VOLUMES`

## Supported API versions

- [1.27](https://docs.docker.com/engine/api/v1.27/)
- [1.28](https://docs.docker.com/engine/api/v1.28/)
- [1.29](https://docs.docker.com/engine/api/v1.29/)
- [1.30](https://docs.docker.com/engine/api/v1.30/)
- [1.37](https://docs.docker.com/engine/api/v1.37/)

## Feedback

Please send any feedback (issues, questions) to the [issue tracker][].

[Alpine]: https://alpinelinux.org/
[HAProxy]: http://www.haproxy.org/
[issue tracker]: https://github.com/Tecnativa/docker-socket-proxy/issues
:memo: Full README 2017-03-31 08:52:26 +00:00			`# Docker Socket Proxy`
:tada: Hello world 2017-03-29 09:32:48 +00:00
:memo: Full README 2017-03-31 08:52:26 +00:00			`[![](https://images.microbadger.com/badges/version/tecnativa/docker-socket-proxy:latest.svg)](https://microbadger.com/images/tecnativa/docker-socket-proxy:latest "Get your own version badge on microbadger.com")`
			`[![](https://images.microbadger.com/badges/image/tecnativa/docker-socket-proxy:latest.svg)](https://microbadger.com/images/tecnativa/docker-socket-proxy:latest "Get your own image badge on microbadger.com")`
			`[![](https://images.microbadger.com/badges/commit/tecnativa/docker-socket-proxy:latest.svg)](https://microbadger.com/images/tecnativa/docker-socket-proxy:latest "Get your own commit badge on microbadger.com")`
			`[![](https://images.microbadger.com/badges/license/tecnativa/docker-socket-proxy.svg)](https://microbadger.com/images/tecnativa/docker-socket-proxy "Get your own license badge on microbadger.com")`
:tada: Hello world 2017-03-29 09:32:48 +00:00
			`## What?`

spelling error, no change. 2019-06-15 00:58:36 +00:00			`This is a security-enhanced proxy for the Docker Socket.`
:tada: Hello world 2017-03-29 09:32:48 +00:00
			`## Why?`

			`Giving access to your Docker socket could mean giving root access to your host,`
:memo: Full README 2017-03-31 08:52:26 +00:00			`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.`
:tada: Hello world 2017-03-29 09:32:48 +00:00
			`## How?`

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

:memo: Full README 2017-03-31 08:52:26 +00:00			`It blocks access to the Docker socket API according to the environment`
:tada: Hello world 2017-03-29 09:32:48 +00:00			variables you set. It returns a `HTTP 403 Forbidden` status for those dangerous
			`requests that should never happen.`

:memo: Full README 2017-03-31 08:52:26 +00:00			`## 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](#suppported-api-versions) for the API version you are using,`
			`and know what you are doing.`

:tada: Hello world 2017-03-29 09:32:48 +00:00			`## Usage`

#7 - privileged explanation 2018-05-20 08:55:20 +00:00			1. 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):
:memo: Full README 2017-03-31 08:52:26 +00:00
			`$ 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. Connect your local docker client to that socket:`

			`$ export DOCKER_HOST=tcp://localhost`

			`3. 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`

			`4. 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`
Support Docker API 1.37 Add CONFIGS and DISTRIBUTION sections. 2019-01-08 08:56:51 +00:00			- `CONFIGS`
:memo: Full README 2017-03-31 08:52:26 +00:00			- `CONTAINERS`
Support Docker API 1.37 Add CONFIGS and DISTRIBUTION sections. 2019-01-08 08:56:51 +00:00			- `DISTRIBUTION`
:memo: Full README 2017-03-31 08:52:26 +00:00			- `EXEC`
			- `IMAGES`
			- `INFO`
			- `NETWORKS`
			- `NODES`
			- `PLUGINS`
			- `SERVICES`
Added missing experimental SESSION API 2019-01-21 12:54:21 +00:00			- `SESSION`
:memo: Full README 2017-03-31 08:52:26 +00:00			- `SWARM`
			- `SYSTEM`
			- `TASKS`
			- `VOLUMES`

			`## Supported API versions`

			`- [1.27](https://docs.docker.com/engine/api/v1.27/)`
:memo: Increase API version support 2017-07-31 10:32:26 +00:00			`- [1.28](https://docs.docker.com/engine/api/v1.28/)`
			`- [1.29](https://docs.docker.com/engine/api/v1.29/)`
			`- [1.30](https://docs.docker.com/engine/api/v1.30/)`
Support Docker API 1.37 Add CONFIGS and DISTRIBUTION sections. 2019-01-08 08:56:51 +00:00			`- [1.37](https://docs.docker.com/engine/api/v1.37/)`
:tada: Hello world 2017-03-29 09:32:48 +00:00
			`## Feedback`

			`Please send any feedback (issues, questions) to the [issue tracker][].`

			`[Alpine]: https://alpinelinux.org/`
			`[HAProxy]: http://www.haproxy.org/`
			`[issue tracker]: https://github.com/Tecnativa/docker-socket-proxy/issues`