How to Lint Dockerfiles Using Hadolint (with examples)

Hadolint is a popular tool for analyzing Dockerfiles for best practices and potential issues. By running this tool on your Dockerfiles, you can ensure they are optimized, secure, and compliant with industry standards. It provides suggestions and highlights issues that could lead to inefficiencies or vulnerabilities in your Docker images. The tool can output the results in various formats and also allows you to customize its behavior by ignoring specific rules or utilizing trusted registries.

Lint a Dockerfile

Code:

hadolint path/to/Dockerfile

Motivation:
Running a basic linting command on a Dockerfile is the most common use case for Hadolint. This quick check helps identify potential security risks and inefficiencies that may exist within the Dockerfile, ensuring that guidelines are adhered to effectively and development standards are upheld. It’s especially important in a team setting where consistent practices need to be enforced.

Explanation:

• hadolint: This is the base command that initiates the linting process using Hadolint.
• path/to/Dockerfile: This specifies the file path to the Dockerfile that is to be linted. By pointing to the Dockerfile directly, Hadolint reads and analyzes its contents against predefined rules.

Example Output:

Dockerfile:3 DL3008 warning: Pin versions in apt-get install. Instead, use version=..
Dockerfile:5 DL3006 warning: Always tag the version of an image explicitly.

Lint a Dockerfile, Displaying Output in JSON Format

Code:

hadolint --format json path/to/Dockerfile

Motivation:
Using JSON as the output format is particularly useful for integrating the linting results into automated systems or CI/CD pipelines, which might require structured data for further processing. JSON format facilitates easy parsing and consumption by other software tools, enabling extended functionalities like error tracking and reporting.

Explanation:

• hadolint: The command-line utility to perform Dockerfile linting.
• --format json: This flag specifies that the linting results should be formatted in JSON. JSON is a lightweight data interchange format commonly used for data representation in web services.
• path/to/Dockerfile: The file path to the Dockerfile you want to analyze.

Example Output:

[
    {
        "line": 3,
        "code": "DL3008",
        "message": "Pin versions in apt-get install.",
        "file": "Dockerfile",
        "level": "warning"
    },
    {
        "line": 5,
        "code": "DL3006",
        "message": "Always tag the version of an image explicitly.",
        "file": "Dockerfile",
        "level": "warning"
    }
]

Lint a Dockerfile, Displaying Output in a Specific Format

Code:

hadolint --format tty|json|checkstyle|codeclimate|codacy path/to/Dockerfile

Motivation:
Hadolint provides various output formats to accommodate the diverse requirements of different environments and tools. Each format serves a specific purpose and can be more suitable depending on whether you need human-readable results or machine-parsable data for integration with other tools such as code review platforms or cloud environments.

Explanation:

• hadolint: The CLI tool used for linting Dockerfiles.
• --format tty|json|checkstyle|codeclimate|codacy: Specifies the desired output format. The options provided here (tty, json, checkstyle, codeclimate, codacy) give flexibility in choosing the most appropriate format depending on the destination or purpose of the linting results.
• path/to/Dockerfile: Indicates the location of the Dockerfile to be linted.

Example Output (for codeclimate format):

[
    {
        "description": "Pin versions in apt-get install.",
        "fingerprint": "abcdef123456",
        "severity": "minor",
        "categories": ["Bug Risk"],
        "location": {
            "path": "Dockerfile",
            "lines": {
                "begin": 3
            }
        }
    }
]

Lint a Dockerfile Ignoring Specific Rules

Code:

hadolint --ignore DL3006 --ignore DL3008 path/to/Dockerfile

Motivation:
Ignoring specific linting rules can be essential when particular warnings are irrelevant to your current project or context. This feature allows developers to concentrate on the most pertinent issues without being distracted by non-critical warnings that might not apply due to specific project constraints or intentional deviations from best practices.

Explanation:

• hadolint: Launches the linting of the Dockerfile.
• --ignore DL3006: Instructs Hadolint to skip rule DL3006, related to tagging image versions explicitly.
• --ignore DL3008: Instructs Hadolint to ignore rule DL3008, which deals with pinning versions in software installations.
• path/to/Dockerfile: Points to the Dockerfile where these rules should be ignored during the linting process.

Example Output:

No issues found

Note: The output indicates that the issues related to DL3006 and DL3008 have been ignored, and there are no other linting issues in the Dockerfile.

Lint Multiple Dockerfiles Using Specific Trusted Registries

Code:

hadolint --trusted-registry docker.io --trusted-registry example.com:5000 path/to/Dockerfile1 path/to/Dockerfile2 ...

Motivation:
Running Hadolint on multiple Dockerfiles simultaneously can save time and ensure uniformity across multiple builds. In secure environments, it’s crucial to use images from trusted registries to mitigate risks associated with unverified sources. By specifying trusted registries, Hadolint can alert you to potential security risks if images are sourced from untrusted registries.

Explanation:

• hadolint: Executes the linter on specified Dockerfiles.
• --trusted-registry docker.io: Adds docker.io to the list of trusted registries. Images pulled from this registry are considered safe.
• --trusted-registry example.com:5000: Extends the trust to another registry at example.com on port 5000.
• path/to/Dockerfile1 path/to/Dockerfile2 ...: Indicates multiple Dockerfiles that need to be checked, ensuring they adhere to security and best practice guidelines across different builds.

Example Output:

Dockerfile1:5 DL3018 warning: Avoid use of deprecated base images unless absolutely necessary.
Dockerfile2:8 DL4006 warning: Set SHELL options -o pipefail.

Conclusion

Hadolint is an essential tool for developers who work with Dockerfiles, offering a comprehensive way to enforce best practices and maintain security and efficiency within Docker-based projects. By accommodating various needs through customizable output formats and the ability to ignore specific rules, Hadolint integrates smoothly into diverse workflows, ranging from simple development environments to complex CI/CD pipelines. Its capability to cater to large-scale projects through linting multiple Dockerfiles simultaneously—with regard for trusted registries—highlights its flexibility and robustness.