Dockerfile Linter — Best Practices & Security Checker

Popular Developer Tools tools

• JWT DecoderDecode, inspect, and validate JWT tokens with claim analysis.
• Cron ParserParse, validate, and build cron expressions with human-readable explanations.
• Regex TesterTest, debug, and explain regular expressions with real-time match highlighting.
• Regex ExplainerBreak down any regex into plain English, token by token.
• JSON to TypeScript & Schema GeneratorGenerate TypeScript interfaces, Zod schemas, and Valibot schemas from JSON.

How to Dockerfile Linter Online

1. 1

   Paste your Dockerfile content directly into the input editor, upload an existing Dockerfile from your filesystem, or choose one of the pre-configured production templates (Node.js multi-stage, Python FastAPI, Go scratch, or anti-pattern example) from the dropdown.

2. 2

   Customize your linting checks using the bottom options bar: toggle Security Audits (hardcoded credentials, root user, sudo), Best Practice Rules (Hadolint DL-series), Style Guidelines (keyword casing, clean formatting), and Layer Optimizations (cache ordering, layer chaining).

3. 3

   Review the instant linting diagnostics rendered in real time. Issues are organized by severity (Error, Warning, Info, Style, and Security) with precise line-number annotations, explanatory diagnostics, and clickable links to official Hadolint rule documentation.

4. 4

   Inspect your Container Health Score (0–100) and Stage Overview cards to review base images, stage aliases (AS <name>), declared user privileges, and working directories across single-stage and multi-stage builds.

5. 5

   Click the Format tab (⌘⇧F) to automatically clean up whitespace and standardize instruction keywords to uppercase, or click the Summary tab (⌘⇧S) for an architectural breakdown of exposed ports, volumes, entrypoints, and health checks.

6. 6

   Switch to the Optimize tab (⌘⇧O) to receive actionable recommendations for improving Docker build cache utilization, eliminating redundant package manager cache layers, and minimizing production image size.

7. 7

   Copy your validated, clean Dockerfile to your clipboard (⌘⇧C) or download it directly for use in your local development environment, Docker Compose configurations, or CI/CD automated deployment pipelines.

Dockerfile Linter Features

• ✓

  Comprehensive Hadolint Compatibility: Implements standard Hadolint DL-series rules (DL3000 through DL4006) directly in the browser with full AST-based parsing and zero external CLI dependencies.

• ✓

  Security Vulnerability Detection: Scans Dockerfiles for critical security anti-patterns including hardcoded secrets/API keys in ENV and ARG directives (SC1000/SC1001), insecure root user execution (DL3002), dangerous sudo usage (DL3004), and overly permissive file permissions (chmod 777).

• ✓

  Intelligent Build Cache & Layer Optimization: Analyzes instruction ordering to flag cache-busting patterns like `COPY . .` before dependency installations (OP1002) and unchained consecutive RUN statements that create bloated intermediate layers (OP1000).

• ✓

  Multi-Stage Build Architectural Analysis: Identifies orphaned or unused build stages (OP1001), ensures proper `COPY --from` references, and checks that non-root users and minimal runtime artifacts are properly configured in final production stages.

• ✓

  Package Manager Best Practices: Validates package management across major Linux distributions including Debian/Ubuntu (`apt-get install` version pinning, `-y` flag, `--no-install-recommends`, and `/var/lib/apt/lists/*` cleanup), Alpine Linux (`apk add --no-cache`), Python (`pip install` version pinning/requirements.txt), and Node.js (`npm ci` vs `npm install`).

• ✓

  Exec vs Shell Form Validation: Enforces POSIX-compliant JSON exec array syntax for CMD and ENTRYPOINT directives (DL3025) to guarantee proper Unix signal forwarding (SIGTERM, SIGINT) for graceful container shutdown.

• ✓

  Automated Container Health Scoring: Computes a weighted 0–100 Container Quality Score giving you an instant benchmark of your Dockerfile readiness for production environments.

• ✓

  Deterministic Base Image Verification: Detects unpinned `FROM` instructions and warns against mutable `:latest` tags (DL3006/DL3007) that cause non-reproducible container builds and unexpected deployment failures.

• ✓

  Real-Time Live Linting with Keyboard Navigation: Powered by debounced background AST analysis with native keyboard shortcuts: ⌘↵ (Run), ⌘⇧V (Lint), ⌘⇧F (Format), ⌘⇧S (Summary), and ⌘⇧O (Optimize).

• ✓

  100% Client-Side Privacy Guarantee: All Abstract Syntax Tree (AST) parsing and rule evaluation occurs entirely in your local browser runtime. Sensitive credentials, internal service names, and proprietary source layouts never leave your machine.

• ✓

  REST API Integration: Programmatically lint, format, and audit Dockerfiles via the `/api/tools/dockerfile-linter` REST endpoint for easy integration into pre-commit hooks, developer scripts, and CI/CD validation steps.

Frequently Asked Questions

What is a Dockerfile Linter and why is it important?

A Dockerfile linter is a static analysis tool that parses your Dockerfile into an Abstract Syntax Tree (AST) and evaluates it against industry best practices, security standards, and performance guidelines. Linting Dockerfiles before building images helps eliminate security vulnerabilities (such as leaked credentials and root execution), shrinks image file sizes, speeds up build times through efficient layer caching, and ensures reproducible deployments across development and production environments.

Is this Dockerfile linter compatible with Hadolint?

Yes. This linter implements Hadolint-compatible rule IDs (such as DL3000, DL3002, DL3003, DL3004, DL3006, DL3007, DL3008, DL3009, DL3013, DL3014, DL3015, DL3016, DL3018, DL3019, DL3020, DL3025, DL3027, DL4000, DL4003, DL4004, and DL4006). Each rule provides direct links to the official Hadolint documentation so you can understand the exact reasoning and remediation for every warning.

Why should I avoid using the :latest tag in FROM instructions (DL3007)?

The `:latest` tag is mutable and points to whatever image version the repository maintainer most recently published. When building from `:latest`, your builds become non-deterministic: a build today may succeed while the same build tomorrow might break due to upstream dependency or OS changes. For predictable, reproducible container builds, always pin explicit version tags (such as `node:20.18-alpine` or `python:3.11-slim`) or immutable image SHA digests.

Why should containers not run as the root user (DL3002)?

By default, Docker containers run processes as the root user (UID 0). If an attacker manages to exploit a vulnerability in your application and escape the container runtime, they gain root privileges on the underlying host kernel. Creating and declaring a dedicated non-root user (e.g. `USER node` or `USER 10001:10001`) enforces the principle of least privilege and significantly limits the blast radius of container security incidents.

Why is `COPY . .` before `RUN npm install` or `pip install` bad for caching (OP1002)?

Docker evaluates cache validity sequentially from top to bottom. If you copy your entire project directory with `COPY . .` before running package manager installations, modifying any single file (such as a README or frontend component) invalidates Docker’s cache for that step and all subsequent steps. This forces package managers to re-download all dependencies from scratch. The recommended pattern is to copy only dependency manifests first (e.g. `COPY package*.json ./` or `COPY requirements.txt .`), run the install step, and only then copy the remaining source code.

What is the difference between `COPY` and `ADD` instructions in Dockerfiles (DL3020)?

`COPY` is the preferred instruction for copying local files and directories into a container because it is explicit and transparent. `ADD` includes implicit magic behaviors: it can automatically extract recognized compressed archives (.tar, .tar.gz, .zip) into the destination directory and download files directly from remote URLs. Using `ADD` for standard file copying creates ambiguity and risks unexpected build behaviors. Use `COPY` for all standard files, and reserve `ADD` strictly for local tarball auto-extraction.

Why should CMD and ENTRYPOINT use JSON exec array format instead of shell format (DL3025)?

When you define `CMD node server.js` (shell form), Docker wraps your command inside a shell subprocess (`/bin/sh -c "node server.js"`). Because the shell process receives PID 1 inside the container rather than your application, standard POSIX termination signals (like `SIGTERM` and `SIGINT`) sent by `docker stop` or Kubernetes during pod shutdown are not forwarded to your app. This causes unclean shutdowns and connection drops until Docker issues a forceful `SIGKILL`. Using exec form (`CMD ["node", "server.js"]`) runs your application as PID 1, allowing graceful shutdown handlers to execute cleanly.

How do multi-stage builds help optimize container size?

Multi-stage Docker builds allow you to use separate `FROM` stages for compiling and runtime packaging. You can install heavy build tools, compilers (like GCC, Go, Rust), development headers, and build dependencies in an initial `builder` stage, and then copy only the compiled binary or production bundle into a clean, minimal runtime image (like `alpine`, `distroless`, or `scratch`). This prevents build tools and source code from bloating the final production image and reducing the attack surface.

Why should I clean package manager caches in the same RUN layer (DL3009/DL3019)?

Each `RUN` instruction in a Dockerfile creates an immutable filesystem layer. If you execute `RUN apt-get update && apt-get install -y curl` in one step and run `RUN rm -rf /var/lib/apt/lists/*` in a separate later step, the cached package list files are still stored permanently in the earlier intermediate layer and remain part of the total image download size. Always chain package installation and cache cleanup in a single `RUN` instruction using `&&` (e.g. `RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*`).

What is the purpose of the HEALTHCHECK instruction in Dockerfiles (SC1003)?

The `HEALTHCHECK` directive instructs Docker and container orchestrators (like Kubernetes or Docker Swarm) on how to test that the containerized process is genuinely healthy and responsive, not merely running. If a web service deadlocks or enters a zombie state while the process PID is still alive, a configured health check (e.g. `HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:8080/health || exit 1`) detects the failure and allows orchestrators to automatically restart or re-route traffic away from the unhealthy container.

Is my Dockerfile or source code sent to any remote server?

No. This tool is built with a zero-trust, privacy-first design. All parsing, AST traversal, rule evaluation, and formatting logic runs entirely client-side inside your web browser. Your Dockerfiles, internal hostnames, port mappings, and build scripts never leave your machine.

Can I integrate this Dockerfile linter into our CI/CD workflow?

Yes. You can use the `/api/tools/dockerfile-linter` REST API endpoint via `curl`, Python, or GitHub Actions to lint Dockerfiles programmatically during CI checks. The endpoint returns structured JSON output containing rule IDs, severities, exact line numbers, and actionable fix suggestions.

Related Developer Tools

• Docker Compose to KubernetesConvert docker-compose.yml to Kubernetes Deployment, Service, ConfigMap, and PVC manifests.
• Kubernetes YAML ValidatorValidate, lint, and format Kubernetes manifests against structure rules, deprecated APIs, and security best practices.
• GitHub Actions ValidatorValidate, format and summarize GitHub Actions workflow YAML files against official schemas.
• Env File Parser & ConverterParse, validate, and convert .env files between formats.
• YAML ConverterConvert between JSON and YAML with validation, formatting, and multi-document support.