droast
a dockerfile linter that actually has opinions. it catches bad practices and tells you about them in the least diplomatic way possible.
think of it as code review from a senior dev who's seen too many prod incidents and has stopped being polite about it.
the span-aware parser understands heredocs, parser and escape directives, shell and JSON forms, BuildKit flags such as RUN --mount, Windows paths, and PowerShell — and reports malformed Dockerfile syntax as DF071.
vs code extension
install from the marketplace and get inline squiggles as you type:
the binary is bundled — no separate install needed. findings appear in real time with roast messages on hover.
install
one-liner (macOS and Linux, detects Homebrew automatically):
|
Homebrew (macOS and Linux):
Cargo (crates.io, builds from source):
Wasmer (Wasmer Registry, sandboxed WASI command):
To scan files or a repository, explicitly mount the directory into the sandbox:
or grab a prebuilt binary from the releases page if you'd rather not wait for the rust compiler to do its thing.
usage
# the basics
# recursively discover and lint an entire repository
# boring mode (no roasts, just facts)
# only care about real problems
# disagree with a rule? valid, we respect it
# ci-friendly output
When given a directory—or no path at all—droast recursively discovers Dockerfile, Dockerfile.*, *.Dockerfile, Containerfile, and Containerfile.*. It also reads Compose YAML and Docker Bake HCL/JSON files to find non-standard Dockerfile paths and their declared build contexts. Repository ignore rules are respected, while hidden project directories such as .devcontainer remain discoverable.
For DF033, droast uses the effective ignore file Docker would use: <Dockerfile>.dockerignore beside the Dockerfile takes precedence over .dockerignore at the build-context root. Missing, empty, comment-only, and negation-only ignore files are reported; use --check-dockerignore=false to disable this context check.
configuration
droast works out of the box with zero configuration. for teams that want to commit project-level defaults, drop a droast.toml in the repo root:
# droast.toml — all fields optional
= "production" # minimal | security | performance | production | strict
= ["DF012", "DF022"]
= "warning"
= true
[]
= "error"
droast searches for droast.toml starting from the current directory, walking up to the nearest .git root. CLI flags always take precedence over the file — the file just sets the defaults so you don't repeat yourself.
To keep lint configuration elsewhere, pass its path explicitly:
Larger teams can add path-specific overrides, rule categories, inherited organization policy, registry and base-image allowlists, required OCI labels, and governed inline suppressions with mandatory reasons and expiration dates:
# droast ignore=DF001 reason="PLAT-142 migration" expires=2026-09-30
FROM alpine:latest
See the complete configuration guide and the copy-paste examples/droast-enterprise.toml. None of these controls are required; zero-config behavior stays unchanged.
github action
add droast to any repo in 5 lines:
- uses: immanuwell/dockerfile-roast@1.4.3
full example (.github/workflows/lint.yml):
name: Lint Dockerfiles
on:
jobs:
droast:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: immanuwell/dockerfile-roast@1.4.3
findings show up as inline annotations on the PR diff. no configuration required.
available inputs (all optional):
| input | default | description |
|---|---|---|
files |
Dockerfile |
file(s) or glob to lint |
min-severity |
config or info |
info, warning, or error |
preset |
— | minimal, security, performance, production, or strict |
category |
— | comma-separated rule categories to run |
skip-category |
— | comma-separated rule categories to skip |
skip |
— | comma-separated rule IDs to ignore |
no-roast |
false |
technical output only, no jokes |
no-fail |
false |
advisory mode — never blocks the build |
image-tag |
latest |
pin to a specific droast release, e.g. 1.4.3 |
example with options:
- uses: immanuwell/dockerfile-roast@1.4.3
with:
files: '**/Dockerfile'
preset: production
skip: DF012,DF022
no-fail: true # report findings but don't block the PR
docker
pull from ghcr and use immediately, no install needed:
# lint a Dockerfile in the current directory
# lint any file, anywhere
# pass flags as usual
or build locally from source:
the image is published automatically to ghcr.io/immanuwell/droast on every release tag.
wasmer
droast is also published as a WASI package in the Wasmer Registry. It uses the same CLI and rule engine as the native binary.
Lint through stdin without granting filesystem access:
Lint a mounted repository:
Wasmer denies host filesystem access unless a directory is mounted. If the repository uses droast.toml, pass --config /workspace/droast.toml after the -- separator.
shell completions
add this once, never mistype --min-severity again:
# bash — add to .bashrc
# zsh — add to .zshrc
# fish — add to config.fish
|
what it catches
Available Rules
ID SEVERITY CATEGORIES DESCRIPTION
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
DF001 WARN correctness,reproducibility Use specific base image tags instead of 'latest'
DF002 ERROR security Do not run as root
DF011 WARN performance Use multi-stage builds to reduce image size
DF013 ERROR security Avoid storing secrets in ENV variables
DF014 ERROR security Avoid hardcoding passwords or tokens in ARG/ENV
DF020 WARN security Set explicit non-root USER
DF003 WARN performance Combine RUN commands to reduce layers
DF004 WARN performance Clean apt/yum/apk cache in the same RUN layer
DF005 INFO correctness,reproducibility Pin package versions for reproducibility
DF006 WARN maintainability,performance Avoid ADD for local files; prefer COPY
DF007 WARN performance Do not copy the entire build context (COPY . .)
DF008 INFO maintainability,performance Use WORKDIR instead of inline cd commands
DF009 WARN correctness,maintainability Use absolute paths in WORKDIR
DF010 WARN security Avoid using sudo inside containers
DF012 INFO maintainability,reliability Set HEALTHCHECK for long-running services
DF017 WARN maintainability,reliability Use ENTRYPOINT with CMD for flexible images
DF018 WARN correctness,reliability Avoid using shell form for ENTRYPOINT
DF019 WARN correctness,maintainability Do not use deprecated MAINTAINER; use LABEL instead
DF022 INFO maintainability,reliability Specify EXPOSE for documented ports
DF023 WARN correctness,maintainability Avoid multiple FROM without aliases (unintended multistage)
DF024 WARN correctness,reproducibility Avoid using :latest in FROM even with aliases
DF025 WARN correctness,reliability Use JSON array syntax for CMD/ENTRYPOINT
DF026 WARN maintainability,performance Avoid recursive COPY from root
DF030 INFO performance Avoid using pip without --no-cache-dir
DF031 INFO performance Avoid npm install without ci/--production for prod images
DF032 INFO maintainability,reliability Set PYTHONDONTWRITEBYTECODE and PYTHONUNBUFFERED for Python images
DF033 INFO performance,security Use an effective .dockerignore for each build context
DF034 ERROR security Avoid chmod 777 — overly permissive
DF035 INFO maintainability,reliability Avoid using curl without --fail flags
DF036 WARN maintainability,reliability Avoid Dockerfile with no CMD or ENTRYPOINT
DF015 ERROR correctness,reliability Avoid using apt-get without -y flag
DF016 INFO performance Use --no-install-recommends with apt-get
DF021 ERROR security,supply-chain Avoid wget|sh pipe patterns (execute remote code)
DF027 ERROR correctness,reliability Do not use yum without -y flag
DF028 WARN performance Cache-bust apt-get update
DF029 WARN performance Avoid apk add without --no-cache
DF037 ERROR correctness,maintainability Dockerfile must begin with FROM, ARG, or a comment
DF038 WARN correctness,maintainability Multiple CMD instructions — only the last one takes effect
DF039 ERROR correctness,reliability Multiple ENTRYPOINT instructions — only the last one takes effect
DF040 ERROR correctness,reliability EXPOSE port must be in valid range 0-65535
DF041 ERROR correctness,reliability Multiple HEALTHCHECK instructions — only the last one applies
DF042 ERROR correctness,reproducibility FROM stage aliases must be unique
DF043 WARN correctness,maintainability zypper install without non-interactive flag
DF044 WARN correctness,maintainability Avoid zypper dist-upgrade in Dockerfiles
DF045 INFO performance Run zypper clean after zypper install
DF046 WARN performance Run dnf clean all after dnf install
DF047 WARN performance Run yum clean all after yum install
DF048 ERROR correctness,reliability COPY with multiple sources requires destination to end with /
DF049 WARN correctness,reliability COPY --from must reference a previously defined stage
DF050 ERROR correctness,reliability COPY --from cannot reference the current stage
DF051 WARN reproducibility,supply-chain Pin versions in pip install
DF052 WARN reproducibility,supply-chain Pin versions in apk add
DF053 WARN reproducibility,supply-chain Pin versions in gem install
DF054 WARN reproducibility,supply-chain Pin versions in go install with @version
DF055 INFO performance Run yarn cache clean after yarn install
DF056 INFO maintainability,performance Use wget --progress=dot:giga to avoid bloated build logs
DF057 WARN reliability,security Set -o pipefail before RUN commands that use pipes
DF058 WARN maintainability,performance Use either wget or curl consistently, not both
DF059 WARN correctness,maintainability Use apt-get or apt-cache instead of apt in scripts
DF060 INFO maintainability,reliability Avoid running pointless interactive commands inside containers
DF061 WARN correctness,maintainability Do not use --platform in FROM unless required
DF062 ERROR correctness,reproducibility ENV variable must not reference itself in the same statement
DF063 WARN correctness,maintainability COPY to relative destination requires WORKDIR to be set first
DF064 WARN performance useradd without -l flag may create excessively large images
DF065 WARN reproducibility,supply-chain FROM uses an unrecognised image registry
DF066 WARN reliability,security Bash-specific syntax used without a SHELL instruction
DF067 INFO maintainability,performance COPY of a local archive — ADD auto-extracts tarballs
DF068 ERROR correctness,reliability FROM, ONBUILD, and MAINTAINER are forbidden as ONBUILD triggers
DF069 WARN correctness,reproducibility Avoid apt-get upgrade / dist-upgrade — makes builds non-reproducible
DF070 WARN performance Avoid broad COPY before package install — invalidates Docker layer cache
DF071 ERROR correctness,reliability Dockerfile syntax must be valid
DF072 ERROR correctness,security Suppression directives must satisfy policy
DF073 ERROR reproducibility,supply-chain Base images must satisfy the approved image policy
DF074 ERROR correctness,security Image labels must satisfy the configured schema
Use --skip DF001,DF002 to suppress specific rules.
Use --min-severity warning to hide INFO findings.
the greatest hits:
| rule | crime |
|---|---|
| DF001 | FROM ubuntu:latest — pick an actual tag |
| DF002 | running explicitly as root |
| DF004 | apt cache left in the image (you made a trash can) |
| DF011 | shipping the entire build toolchain to prod |
| DF013 | secrets in ENV vars (in your layers. forever. congrats) |
| DF021 | curl | sh — no. |
| DF028 | split apt-get update + install in separate RUN layers |
| DF034 | chmod 777 somewhere in there |
| DF037 | instruction before FROM (invalid Dockerfile) |
| DF039 | multiple ENTRYPOINT instructions |
| DF046 | dnf install without cache cleanup |
| DF051 | pip install without version pins |
| DF057 | pipe in RUN without set -o pipefail |
| DF059 | apt used instead of apt-get in scripts |
| DF063 | COPY to relative path with no WORKDIR set |
rule categories: base images · security · package managers · layer hygiene · instruction quality · service quality · python/node specifics
exit codes
0 = clean (or --no-fail), 1 = errors found.
--no-fail is useful for advisory CI runs where you want the output but dont want to block the build yet.
license
MIT. do whatever.
comparison with other tools
The comparison used droast 1.4.2 and Hadolint 2.14.0 on Ubuntu 24.04 x86-64.
Both tools scanned the same lexically sorted set of 121 real-world Dockerfiles containing 28,279 lines. Each tool received three untimed warm-up scans followed by 30 measured scans. Runs were interleaved, and the execution order was reversed on every iteration to reduce ordering bias. One process invocation scanned the entire corpus, configuration was neutralized, and SARIF serialization was included in the elapsed time.
| metric | droast | Hadolint |
|---|---|---|
| median full-corpus scan | 191.043 ms | 1,177.579 ms |
| p95 full-corpus scan | 230.480 ms | 1,328.547 ms |
| files per second | 633.4 | 102.8 |
| lines per second | 148,024 | 24,015 |
| Linux x86-64 binary | 4,584,920 bytes | 54,727,336 bytes |
| findings | 2,070 | 444 |
| errors | 245 | 42 |
| warnings | 1,519 | 231 |
| notes | 306 | 171 |
The benchmark measures execution speed and binary size, not detection quality. Finding totals are not directly comparable because the tools have different rule sets, severities, shell-analysis coverage, and parser behavior.