README.adoc

dockmoor

Once you found a nice dock, it’s time to moor ⚓
dockmoor helps you to create reproducible builds with Docker.

Warning This is currently unmaintained. Tracking docker as a dependency was a mistake.

Renovate bot has a similar feature: https://docs.renovatebot.com/docker/#digest-pinning

Features

Implemented

• pin image references to currently used image via digest to make builds reproducible

  • works with (remote) docker daemon and docker registry (e.g. docker hub)

• list image references

• find Dockerfiles

• filter by various predicates, e.g. untagged, latest, RegEx-match

Upcoming

• amend missing tags

• find outdated image references

• other formats: docker-compose, GitLab CI, Circle CI, Travis CI, …​

Examples

Note: all digests are abbreviated for better readability

pin command

The pin command queries a Docker daemon (local or remote) or a docker registry (e.g. docker hub) for images matching the used image references and pins the image reference by appending the digest.

Note the Docker daemon is used by default, but only knows pulled images!

Pin well-known image references

dockmoor pin pin-examples/Dockerfile-nginx

Given the following multi-stage dockerfile:

# originally untagged
FROM nginx
# originally tagged 1.15
FROM nginx:1.15
# originally tagged 1
FROM nginx:1
# originally tagged 1.15-alpine-perl
FROM nginx:1.15-alpine-perl

RUN something

File after execution:

# originally untagged
FROM nginx@sha256:31b..91
# originally tagged 1.15
FROM nginx:1.15@sha256:31b..91
# originally tagged 1
FROM nginx:1@sha256:31b..91
# originally tagged 1.15-alpine-perl
FROM nginx:1.15-alpine-perl@sha256:9c6..ae

RUN something

stdout is empty
stderr is empty
exit code: 0

Pin all image references in a dockerfile using a docker registry

dockmoor pin --resolver=registry pin-examples/Dockerfile-testimagea

File before execution:

FROM menedev/testimagea:1
FROM menedev/testimagea:1.0
FROM menedev/testimagea:1.0.0
FROM menedev/testimagea:1.0.1
FROM menedev/testimagea:1.1.0
FROM menedev/testimagea:1.1.1
FROM menedev/testimagea:2
FROM menedev/testimagea:2.0
FROM menedev/testimagea:2.0.0
FROM menedev/testimagea:latest
FROM menedev/testimagea

RUN something

File after execution:

FROM menedev/testimagea:1@sha256:1e2..24
FROM menedev/testimagea:1.0@sha256:c27..4b
FROM menedev/testimagea:1.0.0@sha256:f38..df
FROM menedev/testimagea:1.0.1@sha256:c27..4b
FROM menedev/testimagea:1.1.0@sha256:bf1..96
FROM menedev/testimagea:1.1.1@sha256:1e2..24
FROM menedev/testimagea:2@sha256:3d4..a1
FROM menedev/testimagea:2.0@sha256:3d4..a1
FROM menedev/testimagea:2.0.0@sha256:3d4..a1
FROM menedev/testimagea:latest@sha256:3d4..a1
FROM menedev/testimagea@sha256:3d4..a1

RUN something

stdout is empty
stderr is empty
exit code: 0

Pin image references with latest or no tag in a dockerfile

dockmoor pin --latest pin-examples/Dockerfile-testimagea

File after execution:

FROM menedev/testimagea:1
FROM menedev/testimagea:1.0
FROM menedev/testimagea:1.0.0
FROM menedev/testimagea:1.0.1
FROM menedev/testimagea:1.1.0
FROM menedev/testimagea:1.1.1
FROM menedev/testimagea:2
FROM menedev/testimagea:2.0
FROM menedev/testimagea:2.0.0
FROM menedev/testimagea:latest@sha256:3d4..a1
FROM menedev/testimagea@sha256:3d4..a1

RUN something

stdout is empty
stderr is empty
exit code: 0

list command

All single file examples refer to a multi-stage build Dockerfile

List all image references where the tag ends in -test

Surrounding strings with / enables regular expression based matching.

dockmoor list --tag=/-test$/ Dockerfile

stdout:

image-name:1.12-test
image-name:1.11-test
docker.io/library/image-name:latest-test
example.com/image-name:1.12-test
example.com/image-name:latest-test@sha256:2c4..cf

stderr is empty
exit code: 0

List all image references with latest or no tag from a specific domain in file

You can use multiple predicates to filter the matching image references. In this example the domain predicate is used together wih the latest predicate. Predicates are connected to a conjunction: all predicates must match.

dockmoor list --domain=example.com --latest Dockerfile

stdout:

example.com/image-name:latest@sha256:2c4..cf
example.com/other-image
example.com/other-image:latest

stderr is empty
exit code: 0

List all image references in file

dockmoor list Dockerfile

stdout:

image-name
image-name:latest
image-name:1.12
image-name:1.12-test
image-name:1.11-test
image-name@sha256:2c4..cf
docker.io/library/image-name:1.12@sha256:2c4..cf
docker.io/library/image-name
docker.io/library/image-name:latest
docker.io/library/image-name:latest-test
example.com/image-name:1.12
example.com/image-name:1.12-test
example.com/image-name:1.12-testing
example.com/image-name:latest@sha256:2c4..cf
example.com/image-name:latest-test@sha256:2c4..cf
example.com/image-name@sha256:2c4..cf
example.com/other-image
example.com/other-image:latest

stderr is empty
exit code: 0

List all image references with latest or no tag in file

dockmoor list --latest Dockerfile

stdout:

image-name
image-name:latest
docker.io/library/image-name
docker.io/library/image-name:latest
example.com/image-name:latest@sha256:2c4..cf
example.com/other-image
example.com/other-image:latest

stderr is empty
exit code: 0

List all unpinned image references

dockmoor list --unpinned Dockerfile

stdout:

image-name
image-name:latest
image-name:1.12
image-name:1.12-test
image-name:1.11-test
docker.io/library/image-name
docker.io/library/image-name:latest
docker.io/library/image-name:latest-test
example.com/image-name:1.12
example.com/image-name:1.12-test
example.com/image-name:1.12-testing
example.com/other-image
example.com/other-image:latest

stderr is empty
exit code: 0

Use unix find to list all unpinned image references

find some-folder -type f -exec dockmoor list --unpinned {} \; | sort | uniq

stdout:

nginx
nginx:1.15.3
nginx:latest

stderr is empty
exit code: 0

Use unix find to list all image references with latest/no tags

find some-folder/ -type f -exec dockmoor list --latest {} \; | sort | uniq

stdout:

nginx
nginx:latest

stderr is empty
exit code: 0

Use unix find to list all image references

find some-folder/ -type f -exec dockmoor list {} \; | sort | uniq

stdout:

nginx
nginx:1.15.3
nginx:1.15.3-alpine@sha256:2c4..cf
nginx:latest
nginx@sha256:db5..44

stderr is empty
exit code: 0

contains command

Use unix find to list all files containing unpinned references

find some-folder -type f -exec dockmoor contains --unpinned {} \; -print

stdout:

some-folder/Dockerfile-nginx-latest
some-folder/Dockerfile-nginx-1.15.3
some-folder/Dockerfile-nginx-untagged
some-folder/subfolder/Dockerfile-nginx-latest

stderr is empty
exit code: 0

Use unix find to list all files containing latest/no tags

find some-folder -type f -exec dockmoor contains --latest {} \; -print

stdout:

some-folder/Dockerfile-nginx-latest
some-folder/Dockerfile-nginx-untagged
some-folder/subfolder/Dockerfile-nginx-latest

stderr is empty
exit code: Unresolved directive in cmdContains.adoc - include::../end-to-end/results/containsLatestInFolder.exitCode[]

Use unix find to list all supported files

find some-folder -type f -exec dockmoor contains {} \; -print

stdout:

some-folder/Dockerfile-nginx-latest
some-folder/Dockerfile-nginx-1.15.3
some-folder/Dockerfile-nginx-tagged-digest
some-folder/Dockerfile-nginx-untagged
some-folder/Dockerfile-nginx-digest
some-folder/subfolder/Dockerfile-nginx-latest

stderr is empty
exit code: 0

Test the format of a file

The contains command returns with exit code 0 when an image reference was found that matches. Using the --any predicate allows to match any file with a supported format that contains at least one image reference.

dockmoor contains Dockerfile

stdout is empty
stderr is empty
exit code: 0

dockmoor contains some-folder/NotADockerfile

stdout is empty
stderr is empty
exit code: 4

Supported Formats

• Dockerfile (as used by docker build)

Usage

dockmoor [OPTIONS] <contains | list | pin> [command-OPTIONS]

Application Options

-l, --log-level Sets the log-level (one of NONE, ERROR, WARN, INFO, DEBUG)

--version Show version and exit

Commands

• contains

• list

• pin

contains command

dockmoor [OPTIONS] contains [contains-OPTIONS] InputFile

Test if a file contains image references with matching predicates. Returns exit code 0 when the given input contains at least one image reference that satisfy the given conditions and is of valid format, non-null otherwise

Domain Predicates

Limit matched image references depending on their domain

--domain Matches all images matching one of the specified domains. Surround with '/' for regex i.e. /regex/.

Name Predicates

Limit matched image references depending on their name

--name Matches all images matching one of the specified names (e.g. "docker.io/library/nginx"). Surround with '/' for regex i.e. /regex/.

-f, --familiar-name Matches all images matching one of the specified familiar names (e.g. "nginx"). Surround with '/' for regex i.e. /regex/.

--path Matches all images matching one of the specified paths (e.g. "library/nginx"). Surround with '/' for regex i.e. /regex/.

Tag Predicates

Limit matched image references depending on their tag

--untagged Matches images with no tag

--latest Matches images with latest or no tag. References with digest are only matched when explicit latest tag is present.

--tag Matches all images matching one of the specified tag. Surround with '/' for regex i.e. /regex/.

Digest Predicates

Limit matched image references depending on their digest

--unpinned Matches unpinned image references, i.e. image references without digest.

--digest Matches all image references with one of the provided digests.

list command

dockmoor [OPTIONS] list [list-OPTIONS] InputFile

List image references with matching predicates. Returns exit code 0 when the given input contains at least one image reference that satisfy the given conditions and is of valid format, non-null otherwise

Domain Predicates

Limit matched image references depending on their domain

--domain Matches all images matching one of the specified domains. Surround with '/' for regex i.e. /regex/.

Name Predicates

Limit matched image references depending on their name

--name Matches all images matching one of the specified names (e.g. "docker.io/library/nginx"). Surround with '/' for regex i.e. /regex/.

-f, --familiar-name Matches all images matching one of the specified familiar names (e.g. "nginx"). Surround with '/' for regex i.e. /regex/.

--path Matches all images matching one of the specified paths (e.g. "library/nginx"). Surround with '/' for regex i.e. /regex/.

Tag Predicates

Limit matched image references depending on their tag

--untagged Matches images with no tag

--latest Matches images with latest or no tag. References with digest are only matched when explicit latest tag is present.

--tag Matches all images matching one of the specified tag. Surround with '/' for regex i.e. /regex/.

Digest Predicates

Limit matched image references depending on their digest

--unpinned Matches unpinned image references, i.e. image references without digest.

--digest Matches all image references with one of the provided digests.

pin command

dockmoor [OPTIONS] pin [pin-OPTIONS] InputFile

Change image references to a more reproducible format

Domain Predicates

Limit matched image references depending on their domain

--domain Matches all images matching one of the specified domains. Surround with '/' for regex i.e. /regex/.

Name Predicates

Limit matched image references depending on their name

--name Matches all images matching one of the specified names (e.g. "docker.io/library/nginx"). Surround with '/' for regex i.e. /regex/.

-f, --familiar-name Matches all images matching one of the specified familiar names (e.g. "nginx"). Surround with '/' for regex i.e. /regex/.

--path Matches all images matching one of the specified paths (e.g. "library/nginx"). Surround with '/' for regex i.e. /regex/.

Tag Predicates

Limit matched image references depending on their tag

--untagged Matches images with no tag

--latest Matches images with latest or no tag. References with digest are only matched when explicit latest tag is present.

--tag Matches all images matching one of the specified tag. Surround with '/' for regex i.e. /regex/.

Digest Predicates

Limit matched image references depending on their digest

--unpinned Matches unpinned image references, i.e. image references without digest.

--digest Matches all image references with one of the provided digests.

Reference format

Control the format of references, defaults are sensible, changes are not recommended

--force-domain Includes domain even in well-known references

--no-name Formats well-known references as digest only

--no-tag Don’t include the tag in the reference

--no-digest Don’t include the digest in the reference

Pin Options

Control how the image references are resolved

-r, --resolver Strategy to resolve image references (one of dockerd, registry)

--tag-mode Strategy to resolve image references (one of unchanged)

Output parameters

Output parameters

-o, --output Output file to write to. If empty, input file will be used.

Building locally and Contributing

Appreciated! See CONTRIBUTING for details.

Roadmap

Currently dockmoor is in a very eraly stage and under constant development.

To get an idea where the journey will go, take a look at the Roadmap