Skip to content
Docker authentication plugin to enforce a image pull policy. Whitelist Docker images allowed to be pulled.
Go Shell Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Docker Image policy plugin

docker-image-policy is a Docker Access authorization plugin written Go to control which Images are allowed to be pulled by your Docker daemon. The plugin is using the AuthZPlugin API by Docker. Black and Whitelistings are expressed through regular expression. A default policy if no listing matched can be defined also.

Supported: Docker Engine >= 1.11


To build this plugin Go >= 1.7 and proper GOPATH setup is required.

$ make

Build Debian Package


Please consider using a Docker container for building the Debian package.

$ sudo sh

Example with Docker container:

$ git clone ~/docker-image-policy-plugin
$ docker run -it --rm -v ~/docker-image-policy-plugin:/go golang bash
$ sh
$ ls *.deb

Get started

Plugin configuration

Add a config file (default: /etc/docker/docker-image-policy.json), and configure the plugin like so:

  "whitelist": [
  "blacklist": [
  "defaultAllow": false

The whitelist and blacklist array expect strings in regex format. Image pull requests will be checked by applying the compiled regular expressions on the full image, < repository >:< tag >. Certain characters in a regular expression like "." have special meaning and need to be escaped. The JSON format requires you to double escape.

Image pull requests will be handled in the following order:

  1. Whitelist: Allow explicitly white listed images
  2. Blacklist: Reject explicitly black listed images
  3. defaultAllow: Default policy, if true allow, if false reject

If one of the steps matched, the plugin will return accordingly. If whitelist and blacklist did not match, the default policy defaultAllow will allow or reject the request.

Docker configuration

Edit your /etc/docker/daemon.json

  "authorization-plugins": ["docker-image-policy"]


Start docker-image-policy and restart Docker daemon.

$ docker-image-policy &
$ curl localhost:5006/health
$ service docker restart

Please consider using the systemd service file for running docker-image-policy

API Endpoints

Besides the plugin API for Docker a second API provided through (default) is available to monitor the plugin or check the current state.

  • /health -> Health check
  • /config -> Current config
  • /version -> Current version
$ curl localhost:5006/health


  • Simon Pirschel
You can’t perform that action at this time.