Same shit, different language
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
go install github.com/forkcloser/godolint/cmd/godolint@latestgo get github.com/forkcloser/godolint# 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 Dockerfilegodolint 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: falseWithout --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.
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 rootignore 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.
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)
}
}// 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])What is wrong with depending on (hadolint) binaries?
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 |
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.
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
// 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)
}// 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.
RuleSetAll- All implemented rules (default)RuleSetRecommended- Only Error and Warning severity rules
result.HasErrors() // Check for error-severity violations
result.HasWarnings() // Check for warning-severity violations
result.CountBySeverity() // Get violation counts by severity// 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.
*sdk.ParseError // Dockerfile parsing failed
*sdk.ConfigError // An option was given a value it does not takeThe 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 isinfounless--failure-thresholdor the configuration file names another, as in hadolint: a run whose violations are all of thestyleseverity 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-failsays
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)
}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
FROMstarts from the defaults, or from the stage it names (FROM baseafterFROM debian AS basekeeps base'sSHELL,ENVandARG) - Shell pragma -
# hadolint shell=powershellsets 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.
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.).
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,VOLUMEHEALTHCHECK,STOPSIGNAL,SHELLMAINTAINER,ONBUILD
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.
Rule stubs and tests are auto-generated from hadolint's source:
# Generate rule stubs and tests (runs both generators)
go generate ./internal/rulesThis 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
itof hadolint's rule specs, read whole (itsONBUILDvariants, 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
# Build CLI binary
just do build go
# Or directly
go build -o godolint ./cmd/godolint# Run all tests
just test
# Run specific rule tests
go test ./internal/rules -run DL3007# Run linters (tools are pinned by aqua: `aqua install --only-link` once)
just lint- Check if rule stub exists in
internal/rules/dlXXXX.go - If not, run
go generate ./internal/rulesto generate stub - Implement the
checkDLXXXXfunction - Add rule to
cmd/godolint/main.goregistration - 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
}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.
- The command writes JSON only: see Output Format.
- In the old
ENV key valueandLABEL key valueforms, the quotes of the value are removed, as a build removes them; hadolint keeps them there.
Contributions welcome; the open issues are the backlog: https://github.com/forkcloser/godolint/issues.
See LICENSE file.
