diff --git a/README.md b/README.md index 8091107..c404b37 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,151 @@ -# Docker Socket Readonly Proxy +# Docker Socket Proxy -[![](https://images.microbadger.com/badges/version/tecnativa/docker-socket-readonly:latest.svg)](https://microbadger.com/images/tecnativa/docker-socket-readonly:latest "Get your own version badge on microbadger.com") -[![](https://images.microbadger.com/badges/image/tecnativa/docker-socket-readonly:latest.svg)](https://microbadger.com/images/tecnativa/docker-socket-readonly:latest "Get your own image badge on microbadger.com") -[![](https://images.microbadger.com/badges/commit/tecnativa/docker-socket-readonly:latest.svg)](https://microbadger.com/images/tecnativa/docker-socket-readonly:latest "Get your own commit badge on microbadger.com") -[![](https://images.microbadger.com/badges/license/tecnativa/docker-socket-readonly.svg)](https://microbadger.com/images/tecnativa/docker-socket-readonly "Get your own license badge on microbadger.com") +[![](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 readonly proxy for the Docker Socket. +This is a security-enhaced 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. +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 +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: + + $ 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:

403 Forbidden

+ Request forbidden by administrative rules. + + +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` +- `CONTAINERS` +- `EXEC` +- `IMAGES` +- `INFO` +- `NETWORKS` +- `NODES` +- `PLUGINS` +- `SERVICES` +- `SWARM` +- `SYSTEM` +- `TASKS` +- `VOLUMES` + +## Supported API versions + +- [1.27](https://docs.docker.com/engine/api/v1.27/) ## Feedback Please send any feedback (issues, questions) to the [issue tracker][]. [Alpine]: https://alpinelinux.org/ -[API]: https://docs.docker.com/engine/api/v1.27/ [HAProxy]: http://www.haproxy.org/ [issue tracker]: https://github.com/Tecnativa/docker-socket-proxy/issues -[Odoo]: https://www.odoo.com/ -[proxy mode]: https://www.odoo.com/documentation/10.0/reference/cmdline.html#cmdoption-odoo.py--proxy-mode -[worker mode]: https://www.odoo.com/documentation/10.0/setup/deploy.html#worker-number-calculation