Supply Chain

Secure Dockerfiles with cnspec

Scan Dockerfiles for security misconfigurations with cnspec.

Catch insecure container image patterns at the source by scanning Dockerfiles before an image is ever built. cnspec evaluates Dockerfiles against the Mondoo Dockerfile Security and Mondoo Dockerfile Best Practices policies, flagging issues like running as root, missing health checks, mutable base image tags, and use of ADD instead of COPY.

This page is part of scanning your supply chain with cnspec. If you're new to cnspec, start with the Quickstart to install cnspec and run your first scan.

Prerequisites

To scan Dockerfiles with cnspec, you must have:

Scan a Dockerfile

Scan a single Dockerfile, substituting the path and name of the file for FILEPATH:

cnspec scan docker file FILEPATH

Find nested Dockerfiles within a directory, substituting the directory path for PATH:

cnspec scan docker file PATH

Scan with the Mondoo Dockerfile policies

Mondoo maintains out-of-the-box Dockerfile Security and Dockerfile Best Practices policies that flag running as root, missing health checks, mutable base image tags, use of ADD instead of COPY, and more.

Mondoo Platform users: Enable the policies in your space. In the Mondoo App, go to Findings > Policies, search for "Dockerfile", and add the policies. All future scans of your Dockerfiles automatically evaluate against them. To learn more, read Manage policies in Mondoo Platform.

Open source users: Pass a policy bundle URL directly to cnspec. Use the security policy:

cnspec scan docker file FILEPATH \
  --policy-bundle https://raw.githubusercontent.com/mondoohq/cnspec/refs/heads/main/content/mondoo-dockerfile-security.mql.yaml

Or the best-practices policy:

cnspec scan docker file FILEPATH \
  --policy-bundle https://raw.githubusercontent.com/mondoohq/cnspec/refs/heads/main/content/mondoo-dockerfile-best-practices.mql.yaml

Explore Dockerfiles

Run cnspec shell docker file FILEPATH to open the interactive shell and explore your Dockerfiles.

List stages in a multi-stage build

cnspec> docker.file.stages
docker.file.stages: [
  0: from.name="build"
  1: from.name=""
]

Retrieve base images

Get the base image for a specific stage:

cnspec> docker.file.stages[0].from
docker.file.stages[0].from: name="build" image="ubuntu" tag="22.04"
in Dockerfile:1-1
1:  FROM ubuntu:22.04 AS build

Get all FROM instructions across stages:

cnspec> docker.file.stages { from }
docker.file.stages: [
  0: {
    from: name="build" image="node" tag="18-alpine"
    in Dockerfile:1-1
    1:  FROM node:18-alpine AS build

  }
  1: {
    from: name="" image="nginx" tag="alpine"
    in Dockerfile:14-14
    14:  FROM nginx:alpine

  }
]

Retrieve RUN instructions

cnspec> docker.file.stages[0].run
docker.file.stages[0].run: [
  0: script="apt-get update"
     in Dockerfile:5-5
     5:  RUN apt-get update

  1: script="apt-get install -y curl"
     in Dockerfile:6-6
     6:  RUN apt-get install -y curl

]

Retrieve USER configuration

cnspec> docker.file.stages[0].user
docker.file.stages[0].user: user="appuser"
in Dockerfile:10-10
10:  USER appuser

Retrieve exposed ports

cnspec> docker.file.stages[0].expose
docker.file.stages[0].expose: [
  0: port=8080 protocol="tcp"
     in Dockerfile:9-9
     9:  EXPOSE 8080

]

Retrieve environment variables

cnspec> docker.file.stages[0].env
docker.file.stages[0].env: [
  0: name="NODE_ENV" value="production"
     in Dockerfile:3-3
     3:  ENV NODE_ENV=production

  1: name="APP_PORT" value="8080"
     in Dockerfile:4-4
     4:  ENV APP_PORT=8080

]

Retrieve COPY instructions

cnspec> docker.file.stages[0].copy { src dst chown chmod }
docker.file.stages[0].copy: [
  0: {
    src: [
      0: "package.json"
    ]
    dst: "/app/"
    chown: "appuser:appuser"
    chmod: ""
  }
]

Retrieve ADD instructions

cnspec> docker.file.stages[0].add { src dst }
docker.file.stages[0].add: [
  0: {
    src: [
      0: "https://example.com/config.tar.gz"
    ]
    dst: "/opt/"
  }
]

Retrieve build arguments

cnspec> docker.file.stages[0].arg { name default }
docker.file.stages[0].arg: [
  0: {
    name: "NODE_VERSION"
    default: "18"
  }
]

Retrieve image labels

cnspec> docker.file.stages[0].labels
docker.file.stages[0].labels: {
  maintainer: "team@example.com"
  version: "1.0"
}

Retrieve entrypoint and CMD

cnspec> docker.file.stages[0].entrypoint
docker.file.stages[0].entrypoint: script="node server.js"
in Dockerfile:11-11
11:  ENTRYPOINT node server.js
cnspec> docker.file.stages[0].cmd
docker.file.stages[0].cmd: script="npm start"
in Dockerfile:12-12
12:  CMD npm start

List all instructions

cnspec> docker.file.instructions
docker.file.instructions: [
  0: {
    original: "FROM node:18-alpine AS build"
  }
  1: {
    original: "RUN apt-get update"
  }
  2: {
    original: "COPY --chown=appuser:appuser package.json /app/"
  }
  ...
]

Example security checks

Ensure the Dockerfile does not use the root user

cnspec> docker.file.finalStage.runsAsRoot == false
[ok] value: false

[ok] means the check passed. The value after it is the value of runsAsRoot that cnspec compared, so value: false confirms that the final stage does not run as root.

Ensure a HEALTHCHECK instruction is defined

cnspec> docker.file.finalStage.hasHealthcheck
[ok] value: true

Verify no stage uses the latest tag

cnspec> docker.file.stages.all(from.tag != "latest")
[ok] value: true

Verify COPY is used instead of ADD

cnspec> docker.file.stages.all(add == empty)
[ok] value: true

Verify no RUN instructions use sudo

cnspec> docker.file.stages.all(run.none(script.contains("sudo")))
[ok] value: true

Scan options

OptionDescription
--asset-nameOverride the asset name
--annotationAdd an annotation to the asset (key=value)
--incognitoRun in incognito mode (do not report results to Mondoo Platform)
-o, --outputSet the output format (compact, csv, full, hdf, json, junit, ocsf-json, ocsf-parquet, report, sarif, summary, yaml)
-f, --policy-bundlePath to a policy file (local path, s3:// URI, or http(s):// URL)
--policySpecify policies to execute (requires --policy-bundle)
--risk-thresholdExit with status 1 if any risk meets or exceeds this value (0-100)

To gate a CI/CD pipeline, combine --risk-threshold with a report file, for example --risk-threshold 90 --output junit --output-target cnspec-junit.xml. 90 fails the job only on critical risks, 70 also fails on high risks, and 40 also fails on medium risks. To scan every infrastructure as code entry point in a repository in one step, use cnspec scan iac. For complete pipeline examples, read Integrate Mondoo with CI/CD Platforms.

Learn more

Docker Images

Scan Docker images for security misconfigurations and CVEs with cnspec.

Elastic Container Registry (ECR)

Scan Amazon Elastic Container Registry images for security vulnerabilities and misconfigurations with cnspec.

On this page

PrerequisitesScan a DockerfileScan with the Mondoo Dockerfile policiesExplore DockerfilesList stages in a multi-stage buildRetrieve base imagesRetrieve RUN instructionsRetrieve USER configurationRetrieve exposed portsRetrieve environment variablesRetrieve COPY instructionsRetrieve ADD instructionsRetrieve build argumentsRetrieve image labelsRetrieve entrypoint and CMDList all instructionsExample security checksEnsure the Dockerfile does not use the root userEnsure a HEALTHCHECK instruction is definedVerify no stage uses the latest tagVerify COPY is used instead of ADDVerify no RUN instructions use sudoLearn more