{"id":13451460,"url":"https://github.com/Tecnativa/docker-socket-proxy","last_synced_at":"2025-03-23T18:32:33.344Z","repository":{"id":38391194,"uuid":"86563927","full_name":"Tecnativa/docker-socket-proxy","owner":"Tecnativa","description":"Proxy over your Docker socket to restrict which requests it accepts","archived":false,"fork":false,"pushed_at":"2024-09-10T06:06:32.000Z","size":74,"stargazers_count":1669,"open_issues_count":42,"forks_count":169,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-03-22T08:07:22.948Z","etag":null,"topics":["docker","hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tecnativa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-29T09:33:46.000Z","updated_at":"2025-03-21T03:53:30.000Z","dependencies_parsed_at":"2023-01-30T03:01:10.906Z","dependency_job_id":"36b16504-3eaf-4e6e-bd43-ba61bbdb4f3f","html_url":"https://github.com/Tecnativa/docker-socket-proxy","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tecnativa%2Fdocker-socket-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tecnativa%2Fdocker-socket-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tecnativa%2Fdocker-socket-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tecnativa%2Fdocker-socket-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tecnativa","download_url":"https://codeload.github.com/Tecnativa/docker-socket-proxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245149681,"owners_count":20568947,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","hacktoberfest"],"created_at":"2024-07-31T07:00:54.188Z","updated_at":"2025-03-23T18:32:33.243Z","avatar_url":"https://github.com/Tecnativa.png","language":"Python","readme":"[![Last image-template](https://img.shields.io/badge/last%20template%20update-v0.1.3-informational)](https://github.com/Tecnativa/image-template/tree/v0.1.3)\n[![GitHub Container Registry](https://img.shields.io/badge/GitHub%20Container%20Registry-latest-%2324292e)](https://github.com/orgs/Tecnativa/packages/container/package/docker-socket-proxy)\n[![Docker Hub](https://img.shields.io/badge/Docker%20Hub-latest-%23099cec)](https://hub.docker.com/r/tecnativa/docker-socket-proxy)\n\n# Docker Socket Proxy\n\n## What?\n\nThis is a security-enhanced proxy for the Docker Socket.\n\n## Why?\n\nGiving access to your Docker socket could mean giving root access to your host, or even\nto your whole swarm, but some services require hooking into that socket to react to\nevents, etc. Using this proxy lets you block anything you consider those services should\nnot do.\n\n## How?\n\nWe use the official [Alpine][]-based [HAProxy][] image with a small configuration file.\n\nIt blocks access to the Docker socket API according to the environment variables you\nset. It returns a `HTTP 403 Forbidden` status for those dangerous requests that should\nnever happen.\n\n## Security recommendations\n\n-   Never expose this container's port to a public network. Only to a Docker networks\n    where only reside the proxy itself and the service that uses it.\n-   Revoke access to any API section that you consider your service should not need.\n-   This image does not include TLS support, just plain HTTP proxy to the host Docker\n    Unix socket (which is not TLS protected even if you configured your host for TLS\n    protection). This is by design because you are supposed to restrict access to it\n    through Docker's built-in firewall.\n-   [Read the docs](#supported-api-versions) for the API version you are using, and\n    **know what you are doing**.\n\n## Usage\n\n1.  Run the API proxy (`--privileged` flag is required here because it connects with the\n    docker socket, which is a privileged connection in some SELinux/AppArmor contexts\n    and would get locked otherwise):\n\n        $ docker container run \\\n            -d --privileged \\\n            --name dockerproxy \\\n            -v /var/run/docker.sock:/var/run/docker.sock \\\n            -p 127.0.0.1:2375:2375 \\\n            tecnativa/docker-socket-proxy\n\n2.  Connect your local docker client to that socket:\n\n        $ export DOCKER_HOST=tcp://localhost:2375\n\n3.  You can see the docker version:\n\n        $ docker version\n        Client:\n         Version:      17.03.1-ce\n         API version:  1.27\n         Go version:   go1.7.5\n         Git commit:   c6d412e\n         Built:        Mon Mar 27 17:14:43 2017\n         OS/Arch:      linux/amd64\n\n        Server:\n         Version:      17.03.1-ce\n         API version:  1.27 (minimum version 1.12)\n         Go version:   go1.7.5\n         Git commit:   c6d412e\n         Built:        Mon Mar 27 17:14:43 2017\n         OS/Arch:      linux/amd64\n         Experimental: false\n\n4.  You cannot see running containers:\n\n        $ docker container ls\n        Error response from daemon: \u003chtml\u003e\u003cbody\u003e\u003ch1\u003e403 Forbidden\u003c/h1\u003e\n        Request forbidden by administrative rules.\n        \u003c/body\u003e\u003c/html\u003e\n\nThe same will happen to any containers that use this proxy's `2375` port to access the\nDocker socket API.\n\n## Grant or revoke access to certain API sections\n\nYou grant and revoke access to certain features of the Docker API through environment\nvariables.\n\nNormally the variables match the URL prefix (i.e. `AUTH` blocks access to `/auth/*`\nparts of the API, etc.).\n\nPossible values for these variables:\n\n-   `0` to **revoke** access.\n-   `1` to **grant** access.\n\n### Access granted by default\n\nThese API sections are mostly harmless and almost required for any service that uses the\nAPI, so they are granted by default.\n\n-   `EVENTS`\n-   `PING`\n-   `VERSION`\n\n### Access revoked by default\n\n#### Security-critical\n\nThese API sections are considered security-critical, and thus access is revoked by\ndefault. Maximum caution when enabling these.\n\n-   `AUTH`\n-   `SECRETS`\n-   `POST`: When disabled, only `GET` and `HEAD` operations are allowed, meaning any\n    section of the API is read-only.\n\n#### Not always needed\n\nYou will possibly need to grant access to some of these API sections, which are not so\nextremely critical but can expose some information that your service does not need.\n\n-   `BUILD`\n-   `COMMIT`\n-   `CONFIGS`\n-   `CONTAINERS`\n-   `ALLOW_START` (containers/`id`/`start`)\n-   `ALLOW_STOP` (containers/`id`/`stop`)\n-   `ALLOW_RESTARTS` (containers/`id`/`stop`|`restart`|`kill`)\n-   `DISTRIBUTION`\n-   `EXEC`\n-   `GRPC`\n-   `IMAGES`\n-   `INFO`\n-   `NETWORKS`\n-   `NODES`\n-   `PLUGINS`\n-   `SERVICES`\n-   `SESSION`\n-   `SWARM`\n-   `SYSTEM`\n-   `TASKS`\n-   `VOLUMES`\n\n## Use a different Docker socket location\n\nIf your OS stores its Docker socket in a different location and you are unable to bind\nmount it in your container specification, you can specify this via the `SOCKET_PATH`\nenvironment variable.\n\nFor example, [balenaOS](https://www.balena.io/os/) exposes its socket at\n`/var/run/balena-engine.sock`. To accommodate this, merely set the `SOCKET_PATH`\nenvironment variable to `/var/run/balena-engine.sock`.\n\n## Development\n\nAll the dependencies you need to develop this project (apart from Docker itself) are\nmanaged with [poetry](https://python-poetry.org/).\n\nTo set up your development environment, run:\n\n```\npoetry install\n```\n\n### Testing\n\nTo run the tests locally, add `--prebuild` to autobuild the image before testing:\n\n```sh\npoetry run pytest --prebuild\n```\n\nBy default, the image that the tests use (and optionally prebuild) is named\n`docker-socket-proxy:local`. If you prefer, you can build it separately before testing,\nand remove the `--prebuild` flag, to run the tests with that image you built:\n\n```sh\ndocker image build -t docker-socket-proxy:local .\npoetry run pytest\n```\n\nIf you want to use a different image, export the `DOCKER_IMAGE_NAME` env variable with\nthe name you want:\n\n```sh\n# To build it automatically\nenv DOCKER_IMAGE_NAME=my_custom_image poetry run pytest --prebuild\n\n# To prebuild it separately\ndocker image build -t my_custom_image .\nenv DOCKER_IMAGE_NAME=my_custom_image poetry run pytest\n```\n\n## Logging\n\nYou can set the logging level or severity level of the messages to be logged with the\nenvironment variable `LOG_LEVEL`. Default value is info. Possible values are: debug,\ninfo, notice, warning, err, crit, alert and emerg.\n\n## Supported API versions\n\n-   [1.27](https://docs.docker.com/engine/api/v1.27/)\n-   [1.28](https://docs.docker.com/engine/api/v1.28/)\n-   [1.29](https://docs.docker.com/engine/api/v1.29/)\n-   [1.30](https://docs.docker.com/engine/api/v1.30/)\n-   [1.37](https://docs.docker.com/engine/api/v1.37/)\n\n## Image tags\n\nRight now, the only supported tags in our container images are the ones following this\nrules:\n\n1. Each individual git released version will result in an image being tagged with the\n   correspondent `:{{version}}`\n1. `:latest` will refer to the latest _released_ version in git.\n1. `:edge` will be the version that is in the repo's master branch\n\nAny other tag you find in our [Docker Hub image][dh-img] is deprecated.\n\nWe recommend using [GitHub Container Registry][ghcr-img] instead.\n\n## Feedback\n\nPlease send any issues to the [issue tracker][]. For other kind of feedback, you can use\n[our forum][].\n\n[alpine]: https://alpinelinux.org/\n[dh-img]: https://hub.docker.com/r/tecnativa/docker-socket-proxy\n[ghcr-img]:\n    https://github.com/orgs/Tecnativa/packages/container/package/docker-socket-proxy\n[haproxy]: http://www.haproxy.org/\n[issue tracker]: https://github.com/Tecnativa/docker-socket-proxy/issues\n[our forum]: https://github.com/Tecnativa/docker-socket-proxy/discussions\n","funding_links":[],"categories":["Python","Python (1887)","Dockerfile","容器管理与运维 (Container Operations)","docker"],"sub_categories":["网络与反向代理 (Networking / Reverse Proxy)"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTecnativa%2Fdocker-socket-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTecnativa%2Fdocker-socket-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTecnativa%2Fdocker-socket-proxy/lists"}