#How to Use Hadolint to Lint Your Dockerfiles – CloudSavvy IT

Dockerfiles define the content of Docker images as a set of instructions in a text file. The Dockerfile syntax is generally straightforward but there are some gotchas to avoid. Adhering to best practices while writing complex Dockerfiles in a team setting can be tricky unless you’re automatically validating your file’s content.

Hadolint is a Dockerfile linter that can spot common issues for you. It uses an abstract syntax tree (AST) to parse your Dockerfile against predefined rulesets. Hadolint also incorporates ShellCheck so it can lint the shell scripts in your Dockerfile’s RUN instructions too.

Getting Started

Hadolint is distributed in multiple formats. You can quickly get started by downloading the latest pre-compiled binary for your operating system from the project’s GitHub releases page.

Hadolint’s also got its own own Docker image, hadolint/hadolint, if you’d rather not use the binary directly. As a final option, you can access Hadolint via the web for experimentation.

Linting a Dockerfile

Pass Hadolint the path to a Dockerfile to start a new scan:

hadolint Dockerfile

If you’re using the Dockerized version, it’s easiest to pipe the contents of your file into a Hadolint container:

docker run --rm -i hadolint/hadolint < Dockerfile

The scan results will be shown in your terminal. In this example, Hadolint is suggesting that the Dockerfile’s RUN apt-get install statement is unsafe as it doesn’t specify explicit package versions. The content of your image could change in-between builds, potentially creating confusing problems.

What Does Hadolint Look For?

Hadolint has dozens of built-in rules that check for common configuration and security issues. The linter aims to make your Dockerfiles compliant with the image building best practices suggested by Docker.

Included checks cover use of non-root final users, referencing a relative path in a WORKDIR statement, adding multiple HEALTHCHECK instructions, and not using explicitly pinned tags and versions. As Hadolint also inherits the ShellCheck ruleset, it’ll surface common Bash scripting problems which that tool identifies too.

Rules are identified as numbers prefixed with either HL or SC. HL rules are part of Hadolint whereas SC entries come from ShellCheck. Each check is given a severity from Error through to Info. If you get Errors in your scan results, those should be the first issues you resolve.

Customizing Configuration

Hadolint is configured via a .hadolint.yaml file. It will search multiple locations including your working, .config, and home directories. Only the first found file is used – there’s no merging between locations.

The config file lets you customize your scans by ignoring rules and changing their severities. While the default ruleset covers recommended best practices, you might find some checks don’t apply in your environment. Committing a .hadolint.yaml file alongside your Dockerfile lets you tailor Hadolint scans accordingly. Most config file fields are also supported as CLI flags and environment variables.

Rules are disabled by the ignored field. This should be a list of rule IDs:

ignored:
  - DL3010
  - DL3020

If you need to lower a rule’s severity without disabling it entirely, use the override key instead. This also lets you promote a low severity issue to a higher level. Use this if you want to place greater emphasis on a particular issue.

override:
  warning:
    - DL3020

This demotes rule DL3020 from its default “error” level to the less serious “warning.” This rule requires you use COPY instead of ADD when referencing files and folders in your build context.

You can adjust the global severity level too. Setting the failure-threshold field instructs Hadolint to exit with a failure status if any test reports an error at the given severity level:

failure-threshold: warning

This instruction means the Hadolint scan will fail if there’s either an error or a warning in its output.

You can disable exiting with a failure code using the no-fail: true config option or the --no-fail CLI flag. This will instruct Hadolint to exit with a 0 code irrespective of the actual test outcome. It can be useful if you want to include Hadolint as a non-blocking job in a CI pipeline.

Trusting Registries

Another use of the config file is to define trusted registries which you want to be able to reference in your Dockerfiles. When the trustedRegistries field is set, Hadolint will warn you when an image from another registry is used:

trustedRegistries:
  - docker.io
  - docker-registry.example.com

Label Schemas

Hadolint offers basic label linting too. This lets you enforce that labels added to your image by Dockerfile LABEL instructions comply with specified constraints. Here’s an example of how it works:

label-schema:
  notes: text
  app-version: semver
  built-at: rfc3339

This config snippet defines data types for four labels you can use in your Dockerfile. notes is declared as an arbitrary text field while app-version must be a semver-compatible version identifier. built-at is marked as an RFC-3339 datetime string. You can get the full list of supported types in the Hadolint docs.

Hadolint permits use of labels that aren’t listed in your schema. You can disable this and restrict LABEL instructions to only those present in the schema by setting strict-labels: true or using the --strict-labels flag.

Output Formats

Several output formats are supported via the format option or --format flag. The default is tty which emits colorized output to your terminal. Colors can be disabled with the --no-color flag.

The following alternative formatters are available:

• json – Provides the list of detected issues as a verbose JSON structure that’s ideal for use with your own scripts.
• checkstyle – A Checkstyle compatible report.
• codeclimate – A Code Climate compatible report.
• gitlab_codeclimate – Variation of the Code Climate report that works with GitLab’s integrated code quality features. This lets you view errors as a widget on merge request pages when running Hadolint with GitLab CI.

These output formats are ideal for using Hadolint programmatically or as part of a CI pipeline.

Summary

Hadolint automates the detection of Dockerfile issues. This helps your Docker images adhere to best practices and organizational standards. The default configuration is a good starting point but you can customize it to fit your needs by reclassifying and disabling rules.

You should consider integrating Hadolint with your CI tool to get instant reports as Dockerfile changes are committed. This accelerates code review by giving developers immediate visibility into problems. You can also use the tool locally while you work via community-supported editor extensions, providing an even shorter feedback loop.