Dockerfile Linter & Analyzer
Analyze Dockerfiles for syntax errors, security risks, Docker best practices, image optimization opportunities, and build-caching improvements directly in your browser.
- '.env' is not excluded in .dockerignore. Secret environment files may enter the build context.
- '.git' is not excluded in .dockerignore, increasing build context upload time.
- 'node_modules' is not excluded in .dockerignore, potentially overriding clean container dependencies.
The base image uses the ':latest' tag, which can change unpredictably over time.
FROM node:22-alpine
The Dockerfile explicitly declares 'USER root'.
MAINTAINER is deprecated in modern Dockerfile specifications.
LABEL maintainer="John Doe <john@example.com>"
Sensitive key 'API_KEY' defined with a hardcoded value in ENV.
# Remove hardcoded secret default from ENV # Pass API_KEY via docker run -e API_KEY=... or Docker Secret Mount
Sensitive key 'DATABASE_PASSWORD' defined with a hardcoded value in ENV.
# Remove hardcoded secret default from ENV # Pass DATABASE_PASSWORD via docker run -e DATABASE_PASSWORD=... or Docker Secret Mount
ADD is downloading a remote URL directly.
The instruction copies files matching secret patterns (e.g. .env, id_rsa, credentials).
'apt-get update' is executed in its own layer without installing packages.
RUN apt-get update && apt-get install -y --no-install-recommends <packages> && rm -rf /var/lib/apt/lists/*
Package installation does not delete temporary package index lists.
Executing a remote script via 'curl | sh' without prior checksum or integrity verification.
Setting 777 permissions grants read, write, and execute access to all users.
CMD uses shell form instead of JSON-array exec form.
No HEALTHCHECK instruction was detected in the Dockerfile.
How to Use
1. What is a Dockerfile and How Does Container Building Work?
A Dockerfile is a plain-text configuration file containing an ordered sequence of commands and instructions used by the Docker engine to assemble an immutable container image.
Each instruction in a Dockerfile (such as FROM, COPY, RUN) creates a read-only filesystem layer. When a container runs, Docker stacks these layers and adds a thin writable layer on top. Understanding how layers are cached and ordered is critical for producing lightweight, secure, and fast container builds.
2. How to Lint & Optimize Dockerfiles Online
Follow these steps to analyze and audit a Dockerfile with ToolMono:
- Paste or Load: Enter your Dockerfile into the Monaco editor or select a sample preset from the Load Scenario menu.
- Add .dockerignore (Optional): Switch to the .dockerignore tab to cross-analyze build-context exclusion rules.
- Review Health Score: Check the 0–100 Dockerfile Score and high-level KPIs (Total Instructions, Errors, Security Issues, and Optimizations).
- Explore Findings: Filter findings by category (Security, Best Practice, Performance, Optimization, Reproducibility).
- Jump to Exact Lines: Click Line X on any finding to highlight the exact instruction in the Monaco editor.
- Apply Context-Aware Fixes: Review suggested remediation diffs and copy fixes directly.
- Export Reports: Download formatted Markdown reports, structured JSON data, or sanitized Dockerfiles with masked secrets.
3. Dockerfile Health Score (0–100) & Severity Model
The Dockerfile Health Score calculates an explainable quality index based on deterministic penalty rules:
- Critical Security Violations (Embedded secrets, chmod 777): -15 points
- High Errors (Unknown instructions, unverified curl | sh): -10 points
- Warnings & Best Practices (Root user, floating latest tags, bad apt caching): -5 points
- Optimizations (Missing apk --no-cache, missing pip --no-cache-dir): -2 points
4. Complete Dockerfile Instruction Reference
5. Dockerfile Security: Root User, Secrets & Permissions
Container security begins in the Dockerfile. By enforcing least privilege, avoiding hardcoded secrets, and restricting filesystem permissions, you significantly reduce the attack surface of containerized workloads.
6. Root User Risks & Implementing Non-Root Containers
By default, Docker executes container processes as root (UID 0). If an application vulnerability allows arbitrary code execution or a container breakout, the attacker gains root-level permissions.
Recommended Fix: Create a dedicated system user before the startup instruction:
# For Alpine Linux: RUN adduser -D -u 1000 appuser && chown -R appuser:appuser /app USER appuser # For Debian / Ubuntu: RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app USER appuser
7. Secrets Management: ENV vs. ARG vs. Build Secrets
Never bake API keys, database credentials, or private tokens into ENV or ARG instructions. Values defined in these instructions are permanently embedded into intermediate layers and readable via docker history or image inspection.
Instead, mount secrets during build time using BuildKit: RUN --mount=type=secret,id=mysecret ... or provide credentials dynamically at runtime via environment variables or Kubernetes secrets.
8. Base Image Selection, Floating Tags & Digest Pinning
Avoid floating tags like :latest. Pinned version tags (e.g. node:22-alpine) ensure consistent build results across developer workstations and CI/CD pipelines. For mission-critical environments, consider SHA256 digest pinning (e.g. alpine@sha256:77726ef6b...) for cryptographic immutability.
9. Multi-Stage Builds for Minimal Production Image Size
Multi-stage builds allow you to separate the build environment (compilers, build tools, dev dependencies) from the runtime environment.
# Stage 1: Build & Compile FROM node:22-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # Stage 2: Minimal Production Image FROM node:22-alpine AS production WORKDIR /app COPY package*.json ./ RUN npm ci --omit=dev COPY --from=builder /app/dist ./dist USER node CMD ["node", "dist/server.js"]
10. Docker Build-Layer Caching & Instruction Ordering
Docker executes instructions from top to bottom. If an instruction's cache is invalidated, all subsequent instructions must re-execute.
Place infrequently changed files (such as package.json or requirements.txt) and dependency installations before copying dynamic application source code (COPY . .).
11. Package Management Hygiene: apt, apk, npm, pip
Optimize package manager installations to minimize layer bloat:
- Debian/Ubuntu: Combine
apt-get update && apt-get install -y --no-install-recommends <pkgs> && rm -rf /var/lib/apt/lists/* - Alpine: Use
apk add --no-cache <pkgs>to avoid persisting local index files. - Python: Use
pip install --no-cache-dir -r requirements.txt. - Node.js: Use
npm ci --omit=devfor deterministic production installs.
12. COPY vs. ADD: Local Files, Archives & Remote Sources
Prefer COPY over ADD for straightforward local file copying. ADD has magic behaviors (automatic tarball extraction and remote URL downloads) that can produce unexpected side effects.
13. HEALTHCHECK & EXPOSE: Orchestration & Port Semantics
EXPOSE serves purely as documentation between image developers and operators; it does not publish ports on the host. Include a HEALTHCHECK instruction so orchestrators like Docker Swarm and Kubernetes can detect unresponsive containers.
14. .dockerignore Best Practices & Build-Context Security
A .dockerignore file prevents local files from entering the Docker build context. Always exclude sensitive files (.env, private keys) and local caches (node_modules, .git).
15. Step-by-Step Practical Dockerfile Hardening Example
Sample remediation for an insecure Node.js container:
# BEFORE: Multiple Anti-Patterns (Score: 45 / 100) FROM node:latest ENV API_KEY=secret_123 COPY . . RUN npm install USER root CMD npm start # AFTER: Hardened Multi-Stage Build (Score: 98 / 100) FROM node:22-alpine AS production WORKDIR /app ENV NODE_ENV=production COPY package*.json ./ RUN npm ci --omit=dev COPY . . USER node EXPOSE 3000 HEALTHCHECK --interval=30s CMD wget -qO- http://localhost:3000/health || exit 1 CMD ["node", "server.js"]
16. 100% In-Browser Privacy Guarantee (Zero Cloud Uploads)
All Dockerfile parsing, rule audits, and score calculations execute entirely inside your browser memory. Your Dockerfile and proprietary configurations are never transmitted to any external server or telemetry endpoint.
17. Authoritative References & Standards
Consult official containerization standards and security guidelines:
Docker Documentation: Dockerfile Reference
Official Docker standard specification for all Dockerfile instructions, syntax, and build parser directives.
Docker Documentation: Best practices for writing Dockerfiles
Authoritative Docker guidelines for layer caching, multi-stage builds, and minimal image sizing.
OWASP Docker Security Cheat Sheet
Industry security standards for non-root users, secret management, and container hardening.
CIS Docker Benchmark Standard
Center for Internet Security consensus benchmarks for container image configuration.
18. Frequently Asked Questions (20 FAQs)
Related Tools
Browse all toolsFree Compose Visualizer
Visualize Docker Compose files as interactive service dependency graphs and architecture diagrams. Inspect networks, volumes, ports, and dependencies directly in your browser.
.env Validator
Validate .env files, detect syntax errors, duplicate keys, empty values, potential secrets, compare environments, find missing variables, and review configuration drift.
HTTP Headers Analyzer
Analyze HTTP response headers online, audit security headers (CSP, HSTS, CORS), inspect cookies, detect information disclosure, and review caching policies.
HAR File Analyzer
Analyze HTTP Archive (HAR) files online to inspect network requests, response times, status codes, payload sizes, redirects, headers, and performance waterfalls directly in your browser.
CORS Tester
Test CORS configuration online, diagnose browser cross-origin errors, inspect CORS headers, test preflight OPTIONS requests, and get actionable server fix recommendations.
JSON Schema Validator
Validate JSON data against a JSON Schema online with detailed errors, JSON paths, draft detection, and browser-based processing.