replicated/dockerfilelint repository overview

⁠Linter and validator for Dockerfile

Dockerfilelint is an npm module that analyzes a Dockerfile and looks for common traps, mistakes and helps enforce best practices:

⁠Testing

Start unit tests with npm test

⁠Running

⁠From the command line:

./bin/dockerfilelint <path/to/Dockerfile>

⁠Configuring

You can configure the linter by creating a .dockerfilelintrc with the following syntax:

rules:
  uppercase_commands: off

The keys for the rules can be any file in the /lib/reference.js file. At this time, it's only possible to disable rules. They are all enabled by default.

The following rules are supported:

required_params
uppercase_commands
from_first
invalid_line
sudo_usage
apt-get_missing_param
apt-get_recommends
apt-get-upgrade
apt-get-dist-upgrade
apt-get-update_require_install
apkadd-missing_nocache_or_updaterm
apkadd-missing-virtual
invalid_port
invalid_command
expose_host_port
label_invalid
missing_tag
latest_tag
extra_args
missing_args
add_src_invalid
add_dest_invalid
invalid_workdir
invalid_format
apt-get_missing_rm

⁠From a Docker container

(Replace the pwd/Dockerfile with the path to your local Dockerfile)

sudo docker run -v `pwd`/Dockerfile:/Dockerfile dockerfilelint /Dockerfile

⁠Online

If you don't want to install this locally you can try it out on https://fromlatest.io⁠.

⁠Checks performed

⁠FROM

• This should be the first command in the Dockerfile
• Base image should specify a tag
• Base image should not use latest tag
• Support FROM scratch without a tag
• Support the FROM <image>@<digest> syntax
• Allow config to specify "allowed" base layers

⁠MAINTAINER

• Should be followed by exactly 1 parameter (@ sign)

⁠RUN

• sudo is not included in the command
• apt-get [install | upgrade | remove] should include a -y flag
• apt-get install commands should include a --no-install-recommends flag
• apt-get install commands should be paired with a rm -rf /var/lib/apt/lists/* in the same layer
• Avoid running apt-get upgrade or apt-get dist-upgrade
• Never run apt-get update without apt-get install on the same line
• apk add commands should include a --no-cache flag or be paired with an --update flag with rm -rf /var/cache/apk/* in the same layer
• apk add support for --virtual flag
• handle best practices for yum operations and cleanup

⁠CMD

• Only a single CMD layer is allowed
• Better handling of escaped quotes
• Detect exec format with expected variable substitution

⁠LABEL

• Format should be key=value

⁠EXPOSE

• Only the container port should be listed
• All ports should be exposed in a single cache layer (line)
• The same port number should not be exposed multiple times
• Exposed ports should be numeric and in the accepted range

⁠ENV

• Format of ENV
• Best practice of only using a single ENV line to reduce cache layer count

⁠ADD

• Command should have at least 2 parameters
• Source command(s) cannot be absolute or relative paths that exist outside of the current build context
• Commands with wildcards or multiple sources require that destination is a directory, not a file
• If an ADD command could be a COPY, then COPY is preferred
• Using ADD to fetch remote files is discouraged because they cannot be removed from the layer

⁠COPY

• Implement checking (similar to ADD)
• Do not COPY multiple files on a single command to best use cache

⁠ENTRYPOINT

• Support

⁠VOLUME

• Format
• Any build steps after VOLUME is declare should not change VOLUME contents
• If JSON format, double quotes are required

⁠USER

• Should be followed by exactly 1 parameter

⁠WORKDIR

• Validate that it has exactly 1 parameter
• WORKDIR can only expand variables previously set in ENV commands

⁠ARG

• Support
• Prevent redefining the built in ARGs (proxy)

⁠ONBUILD

• Support

⁠STOPSIGNAL

• Validate input
• Only present one time

⁠Misc

• Only valid Dockerfile commands are present
• All commands should have at least 1 parameter
• Check that commands are written as upper case commands