@ -11,36 +11,36 @@ This is a security-enhanced proxy for the Docker Socket.
## Why?
## Why?
Giving access to your Docker socket could mean giving root access to your host,
Giving access to your Docker socket could mean giving root access to your host, or even
or even to your whole swarm, but some services require hooking into that socket
to your whole swarm, but some services require hooking into that socket to react to
to react to events, etc. Using this proxy lets you block anything you consider
events, etc. Using this proxy lets you block anything you consider those services should
those services should not do.
not do.
## How?
## How?
We use the official [Alpine][]-based [HAProxy][] image with a small
We use the official [Alpine][]-based [HAProxy][] image with a small configuration file.
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
variables you set. It returns a `HTTP 403 Forbidden` status for those dangerous
set. It returns a `HTTP 403 Forbidden` status for those dangerous requests that should
requests that should never happen.
never happen.
## Security recommendations
## Security recommendations
- Never expose this container's port to a public network. Only to a Docker
- Never expose this container's port to a public network. Only to a Docker networks
networks where only reside the proxy itself and the service that uses it.
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
- Revoke access to any API section that you consider your service should not need.
need.
- This image does not include TLS support, just plain HTTP proxy to the host Docker
- This image does not include TLS support, just plain HTTP proxy to the host
Unix socket (which is not TLS protected even if you configured your host for TLS
Docker Unix socket (which is not TLS protected even if you configured your
protection). This is by design because you are supposed to restrict access to it
host for TLS protection). This is by design because you are supposed to
through Docker's built-in firewall.
restrict access to it through Docker's built-in firewall.
- [Read the docs](#suppported-api-versions) for the API version you are using, and
- [Read the docs](#suppported-api-versions) for the API version you are using,
**know what you are doing**.
and **know what you are doing**.
## Usage
## 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 \
$ docker container run \
-d --privileged \
-d --privileged \
@ -80,16 +80,16 @@ requests that should never happen.
Request forbidden by administrative rules.
Request forbidden by administrative rules.
</body></html>
</body></html>
The same will happen to any containers that use this proxy's `2375` port to
The same will happen to any containers that use this proxy's `2375` port to access the
access the Docker socket API.
Docker socket API.
## Grant or revoke access to certain API sections
## Grant or revoke access to certain API sections
You grant and revoke access to certain features of the Docker API through
You grant and revoke access to certain features of the Docker API through environment
environment variables.
variables.
Normally the variables match the URL prefix (i.e. `AUTH` blocks access to
Normally the variables match the URL prefix (i.e. `AUTH` blocks access to`/auth/*`
`/auth/*`parts of the API, etc.).
parts of the API, etc.).
Possible values for these variables:
Possible values for these variables:
@ -98,8 +98,8 @@ Possible values for these variables:
### Access granted by default
### Access granted by default
These API sections are mostly harmless and almost required for any service that
These API sections are mostly harmless and almost required for any service that uses the
uses the API, so they are granted by default.
API, so they are granted by default.
- `EVENTS`
- `EVENTS`
- `PING`
- `PING`
@ -109,19 +109,18 @@ uses the API, so they are granted by default.
#### Security-critical
#### Security-critical
These API sections are considered security-critical, and thus access is revoked
These API sections are considered security-critical, and thus access is revoked by
by default. Maximum caution when enabling these.
default. Maximum caution when enabling these.
- `AUTH`
- `AUTH`
- `SECRETS`
- `SECRETS`
- `POST`: When disabled, only `GET` and `HEAD` operations are allowed, meaning
- `POST`: When disabled, only `GET` and `HEAD` operations are allowed, meaning any
any section of the API is read-only.
section of the API is read-only.
#### Not always needed
#### Not always needed
You will possibly need to grant access to some of these API sections, which are
You will possibly need to grant access to some of these API sections, which are not so
not so extremely critical but can expose some information that your service
extremely critical but can expose some information that your service does not need.
does not need.
- `BUILD`
- `BUILD`
- `COMMIT`
- `COMMIT`
@ -144,8 +143,8 @@ does not need.
## Logging
## Logging
You can set the logging level or severity level of the messages to be logged with the
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,
environment variable `LOG_LEVEL`. Defaul value is info. Possible values are: debug,
info, notice, warning, err, crit, alert and emerg.
info, notice, warning, err, crit, alert and emerg.
## Supported API versions
## Supported API versions
@ -159,6 +158,6 @@ You can set the logging level or severity level of the messages to be logged wit
Please send any feedback (issues, questions) to the [issue tracker][].
Please send any feedback (issues, questions) to the [issue tracker][].
João Marques
4 years ago