Secure Dockerfiles with cnspec

import IacScanOptions from './_iac-scan-options.mdx';

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.

Prerequisites

To scan Dockerfiles with cnspec, you must have:

cnspec installed on your workstation
Dockerfiles on your local system to scan

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 Console, 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.

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: docker.file.stage
  1: docker.file.stage
]

Retrieve base images

Get the base image for a specific stage:

cnspec> docker.file.stages[0].from
docker.file.stages[0].from: {
  image: "ubuntu"
  tag: "22.04"
}

Get all FROM instructions across stages:

cnspec> docker.file.stages { from }
docker.file.stages: [
  0: {
    from: {
      image: "node"
      tag: "18-alpine"
    }
  }
  1: {
    from: {
      image: "nginx"
      tag: "alpine"
    }
  }
]

Retrieve RUN instructions

cnspec> docker.file.stages[0].run
docker.file.stages[0].run: [
  0: "apt-get update"
  1: "apt-get install -y curl"
]

Retrieve USER configuration

cnspec> docker.file.stages[0].user
docker.file.stages[0].user: {
  user: "appuser"
}

Retrieve exposed ports

cnspec> docker.file.stages[0].expose
docker.file.stages[0].expose: [
  0: {
    port: 8080
    protocol: "tcp"
  }
]

Retrieve environment variables

cnspec> docker.file.stages[0].env
docker.file.stages[0].env: {
  NODE_ENV: "production"
  APP_PORT: "8080"
}

Retrieve COPY instructions

cnspec> docker.file.stages[0].copy { src dst chown chmod }
docker.file.stages[0].copy: [
  0: {
    src: ["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: ["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"
}

cnspec> docker.file.stages[0].cmd
docker.file.stages[0].cmd: {
  script: "npm start"
}

List all instructions

cnspec> docker.file.instructions
docker.file.instructions: {
  FROM: ["node:18-alpine"]
  RUN: ["apt-get update", "apt-get install -y curl"]
  COPY: ["package.json /app/"]
  ...
}

Example security checks

Ensure the Dockerfile does not use the root user

cnspec> docker.file.user.user != "root"
[ok] value: true

Ensure a HEALTHCHECK instruction is defined

cnspec> docker.file.healthcheck.test.length > 0
[ok] value: true

Verify no stage uses the `latest` tag

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

Verify COPY is used instead of ADD

cnspec> docker.file.stages.all(add == empty)
docker.file.stages.all: true

Verify no RUN instructions use sudo

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

Learn more

To scan Docker images, read Secure Docker Images with cnspec.
To scan running containers, read Secure Docker Containers with cnspec.
To learn more about how the MQL query language works, read Write Effective MQL.
Explore the Dockerfile resource reference.

Secure Dockerfiles with cnspec

On this page