2021-01-26 10:24:48 +00:00
|
|
|
[](https://github.com/Tecnativa/image-template/tree/v0.1.3)
|
2021-01-21 13:14:50 +00:00
|
|
|
[](https://github.com/orgs/Tecnativa/packages/container/package/docker-socket-proxy)
|
|
|
|
|
[](https://hub.docker.com/r/tecnativa/docker-socket-proxy)
|
|
|
|
|
|
2017-03-31 08:52:26 +00:00
|
|
|
# Docker Socket Proxy
|
2017-03-29 09:32:48 +00:00
|
|
|
|
|
|
|
|
## What?
|
|
|
|
|
|
2019-06-15 00:58:36 +00:00
|
|
|
This is a security-enhanced proxy for the Docker Socket.
|
2017-03-29 09:32:48 +00:00
|
|
|
|
|
|
|
|
## Why?
|
|
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
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.
|
2017-03-29 09:32:48 +00:00
|
|
|
|
|
|
|
|
## How?
|
|
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
We use the official [Alpine][]-based [HAProxy][] image with a small configuration file.
|
2017-03-29 09:32:48 +00:00
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
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.
|
2017-03-29 09:32:48 +00:00
|
|
|
|
2017-03-31 08:52:26 +00:00
|
|
|
## Security recommendations
|
|
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
- 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.
|
2021-08-13 16:53:46 +00:00
|
|
|
- [Read the docs](#supported-api-versions) for the API version you are using, and
|
2020-12-10 08:52:55 +00:00
|
|
|
**know what you are doing**.
|
2017-03-31 08:52:26 +00:00
|
|
|
|
2017-03-29 09:32:48 +00:00
|
|
|
## Usage
|
|
|
|
|
|
2020-12-10 08:52:55 +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):
|
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:
|
|
|
|
|
|
2021-04-26 14:23:47 +00:00
|
|
|
$ export DOCKER_HOST=tcp://localhost:2375
|
2017-03-31 08:52:26 +00:00
|
|
|
|
|
|
|
|
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>
|
|
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
The same will happen to any containers that use this proxy's `2375` port to access the
|
|
|
|
|
Docker socket API.
|
2017-03-31 08:52:26 +00:00
|
|
|
|
|
|
|
|
## Grant or revoke access to certain API sections
|
|
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
You grant and revoke access to certain features of the Docker API through environment
|
|
|
|
|
variables.
|
2017-03-31 08:52:26 +00:00
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
Normally the variables match the URL prefix (i.e. `AUTH` blocks access to `/auth/*`
|
|
|
|
|
parts of the API, etc.).
|
2017-03-31 08:52:26 +00:00
|
|
|
|
|
|
|
|
Possible values for these variables:
|
|
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
- `0` to **revoke** access.
|
|
|
|
|
- `1` to **grant** access.
|
2017-03-31 08:52:26 +00:00
|
|
|
|
|
|
|
|
### Access granted by default
|
|
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
These API sections are mostly harmless and almost required for any service that uses the
|
|
|
|
|
API, so they are granted by default.
|
2017-03-31 08:52:26 +00:00
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
- `EVENTS`
|
|
|
|
|
- `PING`
|
|
|
|
|
- `VERSION`
|
2017-03-31 08:52:26 +00:00
|
|
|
|
|
|
|
|
### Access revoked by default
|
|
|
|
|
|
|
|
|
|
#### Security-critical
|
|
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
These API sections are considered security-critical, and thus access is revoked by
|
|
|
|
|
default. Maximum caution when enabling these.
|
2017-03-31 08:52:26 +00:00
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
- `AUTH`
|
|
|
|
|
- `SECRETS`
|
|
|
|
|
- `POST`: When disabled, only `GET` and `HEAD` operations are allowed, meaning any
|
|
|
|
|
section of the API is read-only.
|
2017-03-31 08:52:26 +00:00
|
|
|
|
|
|
|
|
#### Not always needed
|
|
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
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`
|
2023-11-26 01:14:51 +00:00
|
|
|
- `ALLOW_START` (containers/`id`/`start`)
|
|
|
|
|
- `ALLOW_STOP` (containers/`id`/`stop`)
|
|
|
|
|
- `ALLOW_RESTARTS` (containers/`id`/`stop`|`restart`|`kill`)
|
2020-12-10 08:52:55 +00:00
|
|
|
- `DISTRIBUTION`
|
|
|
|
|
- `EXEC`
|
2021-10-09 11:13:52 +00:00
|
|
|
- `GRPC`
|
2020-12-10 08:52:55 +00:00
|
|
|
- `IMAGES`
|
|
|
|
|
- `INFO`
|
|
|
|
|
- `NETWORKS`
|
|
|
|
|
- `NODES`
|
|
|
|
|
- `PLUGINS`
|
|
|
|
|
- `SERVICES`
|
|
|
|
|
- `SESSION`
|
|
|
|
|
- `SWARM`
|
|
|
|
|
- `SYSTEM`
|
|
|
|
|
- `TASKS`
|
|
|
|
|
- `VOLUMES`
|
|
|
|
|
|
2021-11-23 17:54:54 +00:00
|
|
|
## Use a different Docker socket location
|
|
|
|
|
|
2021-11-24 15:46:42 +00:00
|
|
|
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.
|
2021-11-23 17:54:54 +00:00
|
|
|
|
2021-11-24 15:46:42 +00:00
|
|
|
For example, [balenaOS](https://www.balena.io/os/) 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`.
|
2021-11-23 17:54:54 +00:00
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
## Development
|
|
|
|
|
|
|
|
|
|
All the dependencies you need to develop this project (apart from Docker itself) are
|
|
|
|
|
managed with [poetry](https://python-poetry.org/).
|
|
|
|
|
|
|
|
|
|
To set up your development environment, run:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
poetry install
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Testing
|
|
|
|
|
|
|
|
|
|
To run the tests locally, add `--prebuild` to autobuild the image before testing:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
# 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
|
|
|
|
|
```
|
2017-03-31 08:52:26 +00:00
|
|
|
|
2019-08-22 13:29:29 +00:00
|
|
|
## Logging
|
|
|
|
|
|
|
|
|
|
You can set the logging level or severity level of the messages to be logged with the
|
2023-09-25 21:14:28 +00:00
|
|
|
environment variable `LOG_LEVEL`. Default value is info. Possible values are: debug,
|
2020-12-10 08:52:55 +00:00
|
|
|
info, notice, warning, err, crit, alert and emerg.
|
2019-08-22 13:29:29 +00:00
|
|
|
|
2017-03-31 08:52:26 +00:00
|
|
|
## Supported API versions
|
|
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
- [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/)
|
2017-03-29 09:32:48 +00:00
|
|
|
|
2020-12-14 08:42:03 +00:00
|
|
|
## Image tags
|
|
|
|
|
|
2021-07-05 06:56:12 +00:00
|
|
|
Right now, the only supported tags in our container images are the ones following this
|
|
|
|
|
rules:
|
|
|
|
|
|
|
|
|
|
1. Each individual git released version will result in an image being tagged with the
|
|
|
|
|
correspondent `:{{version}}`
|
|
|
|
|
1. `:latest` will refer to the latest _released_ version in git.
|
|
|
|
|
1. `:edge` will be the version that is in the repo's master branch
|
2020-12-14 08:42:03 +00:00
|
|
|
|
|
|
|
|
Any other tag you find in our [Docker Hub image][dh-img] is deprecated.
|
|
|
|
|
|
|
|
|
|
We recommend using [GitHub Container Registry][ghcr-img] instead.
|
|
|
|
|
|
2017-03-29 09:32:48 +00:00
|
|
|
## Feedback
|
|
|
|
|
|
2020-12-14 08:56:42 +00:00
|
|
|
Please send any issues to the [issue tracker][]. For other kind of feedback, you can use
|
|
|
|
|
[our forum][].
|
2017-03-29 09:32:48 +00:00
|
|
|
|
2020-12-10 08:52:55 +00:00
|
|
|
[alpine]: https://alpinelinux.org/
|
2020-12-14 08:42:03 +00:00
|
|
|
[dh-img]: https://hub.docker.com/r/tecnativa/docker-socket-proxy
|
2020-12-14 08:56:42 +00:00
|
|
|
[ghcr-img]:
|
|
|
|
|
https://github.com/orgs/Tecnativa/packages/container/package/docker-socket-proxy
|
2020-12-10 08:52:55 +00:00
|
|
|
[haproxy]: http://www.haproxy.org/
|
2017-03-29 09:32:48 +00:00
|
|
|
[issue tracker]: https://github.com/Tecnativa/docker-socket-proxy/issues
|
2020-12-14 08:42:03 +00:00
|
|
|
[our forum]: https://github.com/Tecnativa/docker-socket-proxy/discussions
|
