Skip to content
forkcloserPublic

About

Dockerfile linter, written in Go

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

1 watching

Forks

godolint logo

godolint

Same shit, different language

godolint? hadolint?

This project is a friendly port of hadolint (a venerable and wildly used dockerfile linter written in haskell).

While there is nothing wrong with hadolint in itself, it does not fit well inside the go devtools ecosystem (*):

  • it is a foreign dependency, that has to be handled outside the familiar go toolchain
  • it comes as a binary, that you have to shell out to, and parse the output of
  • modifying it requires haskell knowledge

godolint is a pure go port of hadolint, filling an age-old gap in the container tooling landscape: the ability to lint dockerfiles in go.

It comes with an example binary that does mimic a small subset of the hadolint binary behavior, and can also be used (of course, and primarily) as a library in Go projects.

(*) see Why? section below for more details

Installation

As a CLI tool

go install github.com/forkcloser/godolint/cmd/godolint@latest

As a library

go get github.com/forkcloser/godolint

Quick Start

CLI Usage

# Lint a Dockerfile
godolint Dockerfile

# Output: a JSON array of violations on stdout, [] when there is none
# [{"file":"Dockerfile","line":1,"column":1,"level":"warning","code":"DL3007","message":"Using latest is prone to errors if the image will ever update. Pin the version explicitly to a release tag"}]

# Ignore specific rules
godolint --ignore DL3006 --ignore SC2050 Dockerfile

# Disable the shellcheck integration for RUN instructions
godolint --without-shellcheck Dockerfile

# Point the shellcheck integration at a configuration file — without this,
# shellcheck never finds a repository's .shellcheckrc, since the checked
# scripts run from a temp dir (requires shellcheck >= 0.10.0)
godolint --shellcheck-rcfile .shellcheckrc Dockerfile

# Logs go to stderr (stdout is the JSON only): --log-level or LOG_LEVEL,
# one of debug, info (default), warn, error
godolint --log-level debug Dockerfile

Configuration

godolint takes hadolint's settings, under hadolint's flags and from hadolint's own configuration file:

# Give a rule's violations another severity (--error, --warning, --info, --style)
godolint --error DL3006 --style DL3059 Dockerfile

# Exit 1 only for a violation of this severity or a graver one (default: info)
godolint --failure-threshold warning Dockerfile

# Never exit 1 for a violation
godolint --no-fail Dockerfile

# The registries images may come from (DL3026)
godolint --trusted-registry docker.io --trusted-registry '*.example.com' Dockerfile

# The labels every image must carry and how each is written (DL3049, DL3051 to
# DL3056, DL3058), and no other label (DL3050)
godolint --require-label maintainer:email --require-label version:semver --strict-labels Dockerfile

# A configuration file, and which one is used said on stderr
godolint --config .hadolint.yaml --verbose Dockerfile
# .hadolint.yaml
ignored:
  - DL3008
override:
  error:
    - DL3006
  style:
    - DL3059
trustedRegistries:
  - docker.io
  - "*.example.com"
label-schema:
  maintainer: email # text, url, spdx, hash, rfc3339, semver or email
  version: semver
strict-labels: true
disable-ignore-pragma: false
failure-threshold: warning # error, warning, info, style, ignore or none
no-fail: false

Without --config, the file used is the first that exists of .hadolint.yaml and .hadolint.yml in the working directory; hadolint.yaml and hadolint.yml in $XDG_CONFIG_HOME (or ~/.config); those two, config.yaml and config.yml in ~/.hadolint; .hadolint.yaml and .hadolint.yml in the home. On Windows the three directories are %APPDATA%, %APPDATA%\hadolint and Documents under the user's profile. The file and the command line add up as in hadolint: a list is the file's and the command line's together, a switch is on when either turns it on, the failure threshold is the command line's when it gives one, and a label both name keeps the file's type. A code given several severities gets the gravest.

A file is obeyed whole or not at all, where hadolint lints with its defaults when it cannot take one. A key hadolint does not have is an error naming it. So are a label type or a threshold that is not one, a label left with no type, and a format or formats other than json, the one format godolint writes. no-color is accepted: the JSON has no colour. hadolint's environment variables (HADOLINT_IGNORE, HADOLINT_FAILURE_THRESHOLD and the others, NO_COLOR) are not read.

Ignore pragmas

A Dockerfile silences rules with hadolint's pragmas, in a comment:

# hadolint global ignore=DL3008
FROM debian:bookworm
# hadolint ignore=DL3006,DL3007
FROM ubuntu
# hadolint stage ignore=DL3002
FROM alpine
USER root

ignore covers the next line, stage ignore, written above a FROM, the stage that FROM starts, global ignore the whole file. Spaces around the = and the commas, and a # comment after the list, are fine. A list with a name that is not a rule code (ignore=crazy,DL3002) is not a pragma at all, as in hadolint. --disable-ignore-pragma turns the three off. DL1001 reports every ignore pragma (and only that kind) at the ignore severity, which the CLI and the SDK never print.

SDK Usage

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/forkcloser/godolint/sdk"
)

func main() {
    // Read Dockerfile
    content, _ := os.ReadFile("Dockerfile")

    // Create linter with default configuration (all rules)
    linter := sdk.New()

    // Lint the Dockerfile
    result, err := linter.Lint(context.Background(), content)
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error: %v\n", err)
        os.Exit(1)
    }

    // Report violations
    for _, v := range result.Violations {
        fmt.Printf("[%s] %s (line %d): %s\n",
            v.Severity, v.Code, v.Line, v.Message)
    }

    // Exit with error code if violations found
    if !result.Passed {
        os.Exit(1)
    }
}

Advanced SDK Usage

// Use a specific rule set
linter := sdk.New(sdk.WithRuleSet(sdk.RuleSetRecommended))

// Disable specific rules
linter := sdk.New(sdk.WithDisabledRules("DL3007", "DL3008"))

// Enable shellcheck integration
linter := sdk.New(sdk.WithShellcheck())

// Enable shellcheck integration with a specific configuration file
linter := sdk.New(sdk.WithShellcheck(sdk.WithShellcheckRCFile(".shellcheckrc")))

// Check for specific severity levels
if result.HasErrors() {
    fmt.Println("Critical issues found!")
}

counts := result.CountBySeverity()
fmt.Printf("Errors: %d, Warnings: %d\n",
    counts[sdk.SeverityError],
    counts[sdk.SeverityWarning])

Why?

What is wrong with depending on (hadolint) binaries?

TL;DR

copy-paste into a powerpoint for your CISO (don't forget to add ✅ and ❌)

Aspect External Binary Pure Go
Supply Chain Risk HIGH - Unverified provenance LOW - Checksummed source
Compromise Scenarios Account takeover, build pipeline, MITM Requires both GitHub + sum.golang.org
Cryptographic Verification Manual, often missing Automatic via go.sum
Reproducibility Poor - binary availability not guaranteed Excellent - source-based
Multi-arch Support Complex per-platform logic GOARCH=arm64 go build
Installation Complexity Bash scripts, sudo, platform detection go install
CI/CD Integration Manual download + caching Native Go tooling
Container Image Size +50-100MB (deps + binary) +5-10MB (static binary)
SBOM Generation Manual, incomplete go list -m all
Vulnerability Scanning Opaque binary, hard to scan govulncheck ./...
License Compliance Manual transitive analysis go-licenses report
TCB Size Large (GitHub, CDN, toolchain) Small (Go compiler, go.sum)
Offline Builds Impossible go mod vendor
Dependency Updates Manual version bumps go get -u + Dependabot

With more words

Supply chain concerns:

  • binary provenance is unverifiable
  • no cryptographic verification
  • version pinning is fragile
  • SBOM is incomplete or missing
  • license compliance is opaque / hardcoded
  • trusted computing base is WIDE
  • scanning binaries is difficult

Operational complexity:

  • multi-architecture is hell
  • installation script is hell with fries
  • CI/CD compounds hell further into full-blown hell
  • availability is not guaranteed
  • os-level dependencies if not compiled statically (which you have to figure out)

You COULD (should!) instead build from source (that is, if you like Gentoo). At least you would get proper git commit pinning, scannable / auditable source code, SBOM. But then, you have to maintain a build environment for it, in a language and with tools that does not match the rest of your stack, and that may also raise additional supply chain concerns, time and dedicated expertise.

So, yes, there is nothing wrong with hadolint-the-project-and-tool, per-se. But if what you do is more than noodling around, if you are not a haskell shop, or if you take your security seriously, depending on external binaries is definitely not something you should do.

This is why we wrote godolint, for people doing go.

Relationship with hadolint

godolint is a faithful port of hadolint to Go. Rule declarations and tests are generated from hadolint's Haskell source, at the commit of hadolint's master the hadolint entry in pins.yaml pins, by digest: just converge fetches that source and regenerates the files .converge names in internal/rules, and just lint fails when the committed rules and tests differ from it.

Current status:

  • All unit tests are automatically converted to Go tests
  • Rule metadata (code, severity, message) matches hadolint exactly
  • Every DL rule is implemented

Project philosophy:

  • hadolint is the upstream for rule definitions and baseline tests
  • We have no intention of fragmenting the community
  • New core rule requests should go through hadolint
  • We will regularly sync with hadolint's evolution

SDK API

Core Types

// Linter performs Dockerfile linting
type Linter struct { ... }

// Result contains linting results
type Result struct {
    Violations []Violation
    Passed     bool
}

// Violation represents a single rule violation
type Violation struct {
    Code     string   // Rule code (e.g., "DL3000")
    Severity Severity // error, warning, info, style
    Message  string   // Human-readable description
    Line     int      // Line number (1-indexed)
}

Configuration Options

// WithRuleSet - Use a predefined rule set
sdk.New(sdk.WithRuleSet(sdk.RuleSetRecommended))

// WithDisabledRules - Disable specific rules
sdk.New(sdk.WithDisabledRules("DL3007", "DL3008"))

// WithShellcheck - Enable shellcheck integration
sdk.New(sdk.WithShellcheck())

// WithShellcheckExclusions - The checks shellcheck leaves out, in place of
// SC2187, SC1090 and SC1091; with no code, none
sdk.New(sdk.WithShellcheck(sdk.WithShellcheckExclusions("SC2187")))

// WithSeverity - Give the violations of a code another severity
sdk.New(sdk.WithSeverity(sdk.SeverityError, "DL3006", "SC2086"))

// WithLabelSchema - The labels an image must carry, and how each is written
// (DL3049, DL3051 to DL3056, DL3058)
sdk.New(sdk.WithLabelSchema(map[string]sdk.LabelType{
    "maintainer":                       sdk.LabelEmail,
    "org.opencontainers.image.version": sdk.LabelSemVer,
}))

// WithStrictLabels - A label the schema does not name is a violation (DL3050)
sdk.New(sdk.WithStrictLabels())

// WithTrustedRegistries - The registries an image may come from (DL3026)
sdk.New(sdk.WithTrustedRegistries("docker.io", "*.example.com"))

// WithDisableIgnorePragma - Read no `# hadolint ignore=` pragma
sdk.New(sdk.WithDisableIgnorePragma())

These are hadolint's settings under hadolint's meanings: ignored, override, label-schema (the types text, url, spdx, hash, rfc3339, semver, email), strict-labels, trustedRegistries and disable-ignore-pragma. A code given to WithDisabledRules or WithSeverity may be one shellcheck reports (SC2086). A code given several severities gets the gravest, and a disabled code stays disabled whatever severity it is given. An option given a value it does not take (a label type or a severity that is none of the constants) makes Lint return a *sdk.ConfigError.

Rule Sets

  • RuleSetAll - All implemented rules (default)
  • RuleSetRecommended - Only Error and Warning severity rules

Result Methods

result.HasErrors()           // Check for error-severity violations
result.HasWarnings()         // Check for warning-severity violations
result.CountBySeverity()     // Get violation counts by severity

Rule Metadata

// Rules - every rule, ordered by code
for _, info := range sdk.Rules() {
    fmt.Println(info.Code, info.Severity, info.Message)
}

// Rule - one rule by its code
info, ok := sdk.Rule("DL3006")

A RuleInfo carries the rule's Code, the Severity every violation of it has unless WithSeverity gives the code another, and its Message in hadolint's words. A rule at SeverityIgnore (DL1001, DL3057) is off: its violations never reach a Result unless WithSeverity gives it a severity. A violation's message is its rule's, but for a rule about a label, which says <label> where the violation names the label (Label `<label>` is missing.); any other name in angle brackets (<package>, <version>) is the violation's text too.

Typed Errors

*sdk.ParseError    // Dockerfile parsing failed
*sdk.ConfigError   // An option was given a value it does not take

Output Format

The command writes hadolint's json format and no other: one array on stdout, on one line, with an object for each violation, and [] when there is none. Indented here:

[
  {
    "file": "Dockerfile",
    "line": 1,
    "column": 1,
    "level": "warning",
    "code": "DL3007",
    "message": "Using latest is prone to errors if the image will ever update. Pin the version explicitly to a release tag"
  },
  {
    "file": "Dockerfile",
    "line": 2,
    "column": 1,
    "level": "error",
    "code": "DL3000",
    "message": "Use absolute WORKDIR"
  }
]

file is the path as it was given, column is always 1, and level is error, warning, info or style. The violations of a file are ordered by line, and by code on one line; several files come one after the other, in the order they were given.

There is no --format and no --output: hadolint's other formats (tty, its default, checkstyle, codacy, codeclimate, gitlab_codeclimate, gnu, junit, sarif, sonarqube) and its output file are not offered, and a configuration file that asks for one of them is refused. A caller that wants another shape reads the JSON.

In the SDK, a Violation marshals as code, severity, message and line.

Exit codes:

  • 0: No violation at the failure threshold or graver. The threshold is info unless --failure-threshold or the configuration file names another, as in hadolint: a run whose violations are all of the style severity exits 0, with the violations on stdout. With --no-fail, no violation makes the exit status 1.
  • 1: A violation at the failure threshold or graver — or a usage or runtime error (a file that cannot be read or parsed, a configuration that cannot be obeyed), reported on stderr with nothing on stdout, whatever --no-fail says

Architecture

Parser

godolint uses moby/buildkit for parsing Dockerfiles, ensuring compatibility with Docker's official parser.

The parser interface is pluggable:

type Parser interface {
    Parse(dockerfile []byte) ([]syntax.InstructionPos, error)
}

Shell Script Validation

godolint includes full shellcheck integration for validating shell commands in RUN instructions:

  • Stateful tracking - Tracks ENV, ARG, and SHELL instructions across the Dockerfile
  • Multi-stage support - A FROM starts from the defaults, or from the stage it names (FROM base after FROM debian AS base keeps base's SHELL, ENV and ARG)
  • Shell pragma - # hadolint shell=powershell sets the shell for the stage, or for every stage when written before the first instruction
  • Smart skipping - Automatically skips non-POSIX shells (PowerShell, cmd) and the exec form (RUN ["cmd", "arg"]), which no shell runs
  • Complete context - Constructs scripts with proper shebang and environment exports

For external scripts validation, godolint does shell out to shellcheck.

This is an optional feature, that you have to require explicitly (as it does present the same challenges as hadolint).

We also believe this should stay disabled, and that external shell scripts linting should not be done at all by godolint (or hadolint). Similarly, neither hadolint nor godolint do lint external yaml, or typescript files, so, linting shell feels inconsistent, and can easily be done separately entirely.

ShellCheck violations, if enabled, will be reported with SC#### codes alongside DL#### rules.

Rule Engine

Rules implement a stateful interface allowing cross-instruction validation:

type Rule interface {
    Code() RuleCode              // "DL3007"
    Severity() Severity          // Error, Warning, Info, Style
    Message() string             // Human-readable description
    InitialState() State         // Initialize rule state
    Check(line int, state State, instruction Instruction) State
    Finalize(state State) State  // Process final state
}

Rules can maintain state across instructions for complex validations (multi-stage builds, shell context tracking, etc.).

Instruction Types

The AST covers all Dockerfile instructions:

  • FROM (image, tag, digest, platform, alias)
  • RUN, CMD, ENTRYPOINT (commands)
  • COPY, ADD (sources, destination, flags)
  • ENV, ARG, LABEL (key-value pairs)
  • WORKDIR, USER, EXPOSE, VOLUME
  • HEALTHCHECK, STOPSIGNAL, SHELL
  • MAINTAINER, ONBUILD

Rules & Tests

Rules and tests are (partly) generated from the hadolint codebase.

As such, godolint passes hadolint's internal test suite, (hopefully) guaranteeing a seamless transition.

Further, as we do not plan on fragmenting the ecosystem for no good reason, we use exactly the same rules, and plan on keeping up with hadolint's updated/new rules.

Code Generation

Rule stubs and tests are auto-generated from hadolint's source:

# Generate rule stubs and tests (runs both generators)
go generate ./internal/rules

This single command:

  • Extracts rule metadata (code, severity, message) from Haskell source
  • Generates Go function stubs for unimplemented rules
  • Converts Haskell test cases to Go tests for implemented rules: every it of hadolint's rule specs, read whole (its ONBUILD variants, its counts of failures, the Dockerfiles an assertion is mapped over). A block the generator cannot read stops it, and a case godolint does not pass yet is named in the generator with its issue, so no case is left out without a word
  • Reports implementation status

Development

Build

# Build CLI binary
just do build go

# Or directly
go build -o godolint ./cmd/godolint

Test

# Run all tests
just test

# Run specific rule tests
go test ./internal/rules -run DL3007

Lint

# Run linters (tools are pinned by aqua: `aqua install --only-link` once)
just lint

Adding New Rules

  1. Check if rule stub exists in internal/rules/dlXXXX.go
  2. If not, run go generate ./internal/rules to generate stub
  3. Implement the checkDLXXXX function
  4. Add rule to cmd/godolint/main.go registration
  5. Run tests: go test ./internal/rules -run DLXXXX

Example:

// internal/rules/dl3007.go
func checkDL3007(instruction syntax.Instruction) bool {
    from, ok := instruction.(*syntax.From)
    if !ok {
        return true // Not a FROM instruction, passes
    }

    // Fail if using :latest tag
    if from.Image.Tag != nil && *from.Image.Tag == "latest" {
        return false
    }

    return true
}

Releasing

A release is a signed, annotated tag vX.Y.Z on main; no binaries are published. Consumers pin the tag as a go_install package (through aqua) or with go install github.com/forkcloser/godolint/cmd/godolint@vX.Y.Z.

Limitations

  • The command writes JSON only: see Output Format.
  • In the old ENV key value and LABEL key value forms, the quotes of the value are removed, as a build removes them; hadolint keeps them there.

Contributing

Contributions welcome; the open issues are the backlog: https://github.com/forkcloser/godolint/issues.

License

See LICENSE file.

About

Dockerfile linter, written in Go

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages