{"id":13521305,"url":"https://github.com/open-policy-agent/opa-docker-authz","last_synced_at":"2025-04-05T15:07:47.714Z","repository":{"id":11260927,"uuid":"60713839","full_name":"open-policy-agent/opa-docker-authz","owner":"open-policy-agent","description":"A policy-enabled authorization plugin for Docker.","archived":false,"fork":false,"pushed_at":"2025-03-31T02:11:03.000Z","size":234597,"stargazers_count":87,"open_issues_count":13,"forks_count":26,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-01T17:55:08.655Z","etag":null,"topics":["authorization","docker","opa"],"latest_commit_sha":null,"homepage":"","language":"Go","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/open-policy-agent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2016-06-08T16:43:57.000Z","updated_at":"2025-03-18T08:55:18.000Z","dependencies_parsed_at":"2023-01-13T18:00:10.694Z","dependency_job_id":"f41d8539-66fd-4739-95d1-b198a44f07d7","html_url":"https://github.com/open-policy-agent/opa-docker-authz","commit_stats":{"total_commits":59,"total_committers":17,"mean_commits":"3.4705882352941178","dds":0.6271186440677966,"last_synced_commit":"09ffe71b932fcd6eef5868535ed46607362f41cf"},"previous_names":["open-policy-agent/docker-authz-plugin"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-policy-agent%2Fopa-docker-authz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-policy-agent%2Fopa-docker-authz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-policy-agent%2Fopa-docker-authz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-policy-agent%2Fopa-docker-authz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-policy-agent","download_url":"https://codeload.github.com/open-policy-agent/opa-docker-authz/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353745,"owners_count":20925329,"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":["authorization","docker","opa"],"created_at":"2024-08-01T06:00:32.490Z","updated_at":"2025-04-05T15:07:47.686Z","avatar_url":"https://github.com/open-policy-agent.png","language":"Go","funding_links":[],"categories":["Image scanning / Registry","Tools","Language and Platform Integrations","工具"],"sub_categories":["Compliance","Docker","合规检查"],"readme":"# opa-docker-authz\n\nThis project is used to show how OPA can help policy-enable an existing service.\n\nIn this example, we policy-enable the authorization functionality available in the Docker Engine, which is implemented using a plugin architecture. Plugins were introduced in the Docker Engine in 1.10, as a v1 implementation, and further extended in 1.13, as a v2 implementation. Plugins that adhere to the former are often termed [legacy plugins](https://docs.docker.com/engine/extend/legacy_plugins/), whilst the latter are termed [managed plugins](https://docs.docker.com/engine/extend/).\n\n`opa-docker-authz` is an [authorization plugin](https://docs.docker.com/engine/extend/plugins_authorization/) for the Docker Engine, and can be run as a legacy plugin, or as a managed plugin. The managed plugin is the recommended configuration.\n\n## Usage\n\nSee the [detailed example](http://www.openpolicyagent.org/docs/docker-authorization.html) to setup a running example of this plugin.\n\n### Build\n\nA makefile is provided for creating different artifacts, each of which requires Docker:\n\n- `make build` - builds the `opa-docker-authz` binary\n- `make image` - builds a Docker image for use as a legacy plugin\n- `make plugin` - builds a managed plugin\n\n### Install\n\nTo make use of the `opa-docker-authz` plugin, [TLS must be enabled](https://docs.docker.com/engine/security/https/), in order for the Docker daemon to authenticate the client user. The client's X.509 certificate subject common name, should be [configured](https://docs.docker.com/engine/extend/plugins_authorization/#default-user-authorization-mechanism) with the user who is the subject of the authorization request.\n\n**Managed Plugin**\n\nThe managed plugin is a special pre-built Docker image, and as such, has no prior knowledge of the user's intended policy. OPA policy is defined using the [Rego language](https://www.openpolicyagent.org/docs/language-reference.html), which for the purposes of the `opa-docker-authz` plugin, is either contained within a file (using the `-policy-file` argument) or fetched from bundles through an OPA [configuration](https://www.openpolicyagent.org/docs/latest/configuration/) file (using the `-config-file` argument). Since the latter option allows not just remote bundles, but any of the OPA management features such as decision logging, it is the recommended choice. The plugin needs to be made aware of either the location of the policy file, or the config file, during its installation.\n\nIn order to provide user-defined OPA policy or config, the plugin is configured with a bind mount; `/etc/docker` is mounted at `/opa` inside the plugin's container, which is its working directory. If you define your config in a file located at the path `/etc/docker/config/opa-conf.yaml`, for example, it will be available to the plugin at `/opa/config/opa-conf.yaml`.\n\nIf the plugin is installed without a reference to a Rego policy file, or a config file, all authorization requests sent to the plugin by the Docker daemon, fail open, and are authorized by the plugin.\n\nThe following steps detail how to install the managed plugin.\n\nDownload the `opa-docker-authz` plugin from the Docker Hub (depending on how your Docker environment is configured, you may need to execute the following commands using the `sudo` utility), and specify the location of the policy file, or config file, using the `opa-args` key, and an appropriate value:\n\n```\n$ docker plugin install --alias opa-docker-authz openpolicyagent/opa-docker-authz-v2:0.8 opa-args=\"-config-file /opa/config/opa-conf.yaml\"\nPlugin \"openpolicyagent/opa-docker-authz-v2:\u003cVERSION\u003e\" is requesting the following privileges:\n - mount: [/etc/docker]\nDo you grant the above permissions? [y/N] y\n...\nInstalled plugin openpolicyagent/opa-docker-authz-v2:\u003cVERSION\u003e\n```\n\nCheck the plugin is installed and enabled:\n\n```\n$ docker plugin ls\nID                  NAME                      ENABLED\ncab1329e2a5a        opa-docker-authz:latest   true\n```\n\nWith the plugin installed and enabled, the Docker daemon needs to be configured to make use of the plugin. There are a couple of ways of doing this, but perhaps the easiest is to add a configuration option to the daemon's configuration file (usually `/etc/docker/daemon.json`):\n\n```json\n{\n    \"authorization-plugins\": [\"openpolicyagent/opa-docker-authz-v2:0.8\"]\n}\n```\n\nTo update the Docker daemon's configuration, send a `HUP` signal to its process:\n\n```\n$ sudo kill -HUP $(pidof dockerd)\n```\n\nThe Docker daemon will now send authorization requests for all Docker client API calls, to the `opa-docker-authz` plugin, for evaluation.\n\n**Legacy Plugin**\n\nIf you prefer to use the legacy plugin, it needs to be started as a container, before applying the same configuration to the Docker daemon, as detailed above:\n\n```\n$ docker container run -d --restart=always --name opa-docker-authz \\\n    -v /run/docker/plugins:/run/docker/plugins \\\n    -v $HOME/opa/policies:/opa \\\n    openpolicyagent/opa-docker-authz:0.6 -policy-file /opa/authz.rego\n```\n\n### Logs\n\nIf using the plugin with the `-config-file` option, full decision logging capabilities - including configuring remote endpoints - is at your disposal.\n\nIf using a policy file, the activity describing the interaction between the Docker daemon and the authorization plugin, and the authorization decisions made by OPA, can be found in the daemon's logs. Their [location](https://docs.docker.com/config/daemon/#read-the-logs) is dependent on the host operating system configuration.\n\nLogs are generated in a json format similar to [decision logs](https://www.openpolicyagent.org/docs/latest/management/#decision-logs):\n\n```\n{\n  \"config_hash\": \"a2e84e38eafd14a816194357860b253becbc739e601cf4307078413a0a578a89\",\n  \"decision_id\": \"8d4c6d08-b56e-4625-b66c-3e6c00d7a6e7\",\n  \"input\": {\n    \"AuthMethod\": \"\",\n    \"BindMounts\": [],\n    \"Body\": null,\n    \"Headers\": {\n      \"Content-Length\": \"0\",\n      \"Content-Type\": \"text/plain\",\n      \"User-Agent\": \"Docker-Client/19.03.11 (linux)\"\n    },\n    \"Method\": \"POST\",\n    \"Path\": \"/v1.40/images/create?fromImage=registry.company.com%3A8885%2Fbash\\\\u0026tag=latest\",\n    \"PathArr\": [\n      \"\",\n      \"v1.40\",\n      \"images\",\n      \"create\"\n    ],\n    \"PathPlain\": \"/v1.40/images/create\",\n    \"Query\": {\n      \"fromImage\": [\n        \"registry.company.com:8885/bash\"\n      ],\n      \"tag\": [\n        \"latest\"\n      ]\n    },\n    \"User\": \"\"\n  },\n  \"labels\": {\n    \"app\": \"opa-docker-authz\",\n    \"id\": \"396f1138-ea63-4be0-9ce0-3184cb20b1dd\",\n    \"opa_version\": \"v0.18.0\",\n    \"plugin_version\": \"0.8\"\n  },\n  \"result\": true,\n  \"timestamp\": \"2020-06-16T16:44:54.328705305Z\"\n}\n```\n\n### Input Processing\n\nThe Rego `input` document is largely identical to the JSON data structure given to opa-docker-authz by Docker, with the following additions\nto enrich the document with additional information and assist policy authoring:\n - PathPlain - the Path portion of the RequestURI (exposed as 'Path'), i.e. without the query string \n - PathArr - PathPlain split into an array of path elements by '/'\n - BindMounts - an array of bind mount objects, as specified via either 'Binds' or 'Mounts' (see below)\n \n#### BindMounts\n\nThe BindMounts array is populated with information about the source, readonly status and resolved symlink path of each bind.  The each object in the array\nhas the schema\n\n```\n{\n  \"Source\": \"\u003csource path\u003e\",\n  \"ReadOnly\": true|false,\n  \"Resolved\": \"\u003cresolved source path\u003e\"\n}\n```\n\nwhere 'Resolved' is either the empty string (\"\") or the full host path that corresponds to `Source` after resolving any symbolic links. \nThis allows for effective policy checking of bind mount sources, including where the true source path is obfuscated with symlinks. This\nmitigates against a known trivial bypass of policy that check for binds, for example\n\n```\ncd /home/user\nln -sf / root\ndocker run --rm -it -v/home/user/root:/mnt image\n# /mnt is now / in the hostfs\ndocker run --rm -it -v/home/user/root/var:/mnt image\n# /mnt is now /var on the host\n```\n\nIn each of the above examples, the 'Resolved' path allows for the situation to be detected by policy (it will resolve to \"/\" and \"/var\", respectively).\n\n**Note**: in order for the bind mount resolution to work, the opa-docker-authz plugin must have read access to all parts of the filesystem for which\nthese checks are required by the policy.  The easiest way to achieve this is to run the plugin as a legacy plugin as `root`.  If using a managed plugin,\nthe `config.json` would need to rebuilt with a custom bind configuration that exposes the relevant parts of the hostfs to the plugin as read only binds. \n\n### Uninstall\n\nUninstalling the `opa-docker-authz` plugin is the reverse of installing. First, remove the configuration applied to the Docker daemon, not forgetting to send a `HUP` signal to the daemon's process.\n\nIf you're using the legacy plugin, use the `docker container rm -f opa-docker-authz` command to remove the plugin. Otherwise, use the `docker plugin rm -f opa-docker-authz` command to remove the managed plugin.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-policy-agent%2Fopa-docker-authz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-policy-agent%2Fopa-docker-authz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-policy-agent%2Fopa-docker-authz/lists"}