@ -11,36 +11,36 @@ 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.
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.
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.
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**.
- 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):
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 \
@ -80,85 +80,84 @@ requests that should never happen.
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.
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.
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.).
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.
- `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.
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`
- `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.
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.
- `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`
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`
## Logging
You can set the logging level or severity level of the messages to be logged with the
environment variable `LOG_LEVEL`. Defaul value is info. Possible values are: debug,
info, notice, warning, err, crit, alert and emerg.
environment variable `LOG_LEVEL`. Defaul value is info. Possible values are: debug,
info, notice, warning, err, crit, alert and emerg.
João Marques
4 years ago