Dockle - Container Image Linter for Security, Helping build the Best-Practice Docker Image, Easy to start

Dockle helps you:

1. Build Best Practice Docker images
2. Build secure Docker images
   • Checkpoints includes CIS Benchmarks

$ brew untap goodwithtech/dockle # who use 0.1.16 or older version
$ brew install goodwithtech/r/dockle
$ dockle [YOUR_IMAGE_NAME]

See Installation and Common Examples

Checkpoints Comparison

TOC

• Features
• Comparison
• Installation
• Homebrew (Mac OS X / Linux and WSL)
• RHEL/CentOS
• Debian/Ubuntu
• Arch Linux
• Windows
• Microsoft PowerShell 7
• Binary
• asdf
• From source
• Use Docker
• Quick Start
• Basic
• Docker
• Checkpoint Summary
• Common Examples
• Scan an image
• Scan an image file
• Get or Save the results as JSON
• Specify exit code
• Specify exit level
• Ignore the specified checkpoints
• Continuous Integration
• GitHub Action
• Travis CI
• CircleCI
• GitLab CI
• Authorization for Private Docker Registry
• Checkpoint Details
• CIS's Docker Image Checkpoints
• Dockle Checkpoints for Docker
• Dockle Checkpoints for Linux
• Credits
• Roadmap

Features

• Detect container's vulnerabilities
• Helping build best-practice Dockerfile
• Simple usage
• Specify only the image name
• See Quick Start and Common Examples
• CIS Benchmarks Support
• High accuracy
• DevSecOps
• Suitable for CI such as Travis CI, CircleCI, Jenkins, etc.
• See CI Example

Comparison

	Dockle	Hadolint	Docker Bench for Security	Clair
Target	Image	Dockerfile	Host

Docker Daemon

Image

Container Runtime | Image | | How to run | Binary | Binary | ShellScript | Binary | | Dependency | No | No | Some dependencies | No | | CI Suitable | ✓ | ✓ | x | x | | Purpose |Security Audit

Dockerfile Lint| Dockerfile Lint | Security Audit

Dockerfile Lint | Scan Vulnerabilities |

Installation

Homebrew (Mac OS X / Linux and WSL)

You can use Homebrew on Mac OS X or Linux and WSL (Windows Subsystem for Linux).

$ brew install goodwithtech/r/dockle

RHEL/CentOS

VERSION=$(
 curl --silent "https://api.github.com/repos/goodwithtech/dockle/releases/latest" | \
 grep '"tag_name":' | \
 sed -E 's/.*"v([^"]+)".*/\1/' \
) && rpm -ivh https://github.com/goodwithtech/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Linux-64bit.rpm

Debian/Ubuntu

VERSION=$(
 curl --silent "https://api.github.com/repos/goodwithtech/dockle/releases/latest" | \
 grep '"tag_name":' | \
 sed -E 's/.*"v([^"]+)".*/\1/' \
) && curl -L -o dockle.deb https://github.com/goodwithtech/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Linux-64bit.deb
$ sudo dpkg -i dockle.deb && rm dockle.deb

Arch Linux

dockle can be installed from the Arch User Repository using dockle or dockle-bin package.

git clone https://aur.archlinux.org/dockle-bin.git
cd dockle-bin
makepkg -sri

Windows

VERSION=$(
 curl --silent "https://api.github.com/repos/goodwithtech/dockle/releases/latest" | \
 grep '"tag_name":' | \
 sed -E 's/.*"v([^"]+)".*/\1/' \
) && curl -L -o dockle.zip https://github.com/goodwithtech/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Windows-64bit.zip
$ unzip dockle.zip && rm dockle.zip
$ ./dockle.exe [IMAGE_NAME]

Microsoft PowerShell 7

if (((Invoke-WebRequest "https://api.github.com/repos/goodwithtech/dockle/releases/latest").Content) -match '"tag_name":"v(?<ver>[^"]+)"') {
$VERSION=$Matches.ver &&
Invoke-WebRequest "https://github.com/goodwithtech/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Windows-64bit.zip" -OutFile dockle.zip &&
Expand-Archive dockle.zip && Remove-Item dockle.zip }

Binary

You can get the latest version binary from releases page.

Download the archive file for your operating system/architecture. Unpack the archive, and put the binary somewhere in your $PATH (on UNIX-y systems, /usr/local/bin or the like).

• NOTE: Make sure that it's execution bits turned on. (chmod +x dockle)

asdf

You can install dockle with the asdf version manager with this plugin, which automates the process of installing (and switching between) various versions of github release binaries. With asdf already installed, run these commands to install dockle:

# Add dockle plugin
asdf plugin add dockle

# Show all installable versions
asdf list-all dockle

# Install specific version
asdf install dockle latest

# Set a version globally (on your ~/.tool-versions file)
asdf global dockle latest

# Now dockle commands are available
dockle --version

From source

$ GO111MODULE=off go get github.com/goodwithtech/dockle/cmd/dockle
$ cd $GOPATH/src/github.com/goodwithtech/dockle && GO111MODULE=on go build -o $GOPATH/bin/dockle cmd/dockle/main.go

Use Docker

There's a Dockle image on Docker Hub also. You can try dockle before installing the command.

$ VERSION=$(
 curl --silent "https://api.github.com/repos/goodwithtech/dockle/releases/latest" | \
 grep '"tag_name":' | \
 sed -E 's/.*"v([^"]+)".*/\1/' \
) && docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  goodwithtech/dockle:v${VERSION} [YOUR_IMAGE_NAME]

You only need -v /var/run/docker.sock:/var/run/docker.sock when you'd like to scan the image on your host machine.

Quick Start

Basic

Simply specify an image name (and a tag).

$ dockle [YOUR_IMAGE_NAME]

Result

FATAL   - CIS-DI-0009: Use COPY instead of ADD in Dockerfile
        * Use COPY : /bin/sh -c #(nop) ADD file:81c0a803075715d1a6b4f75a29f8a01b21cc170cfc1bff6702317d1be2fe71a3 in /app/credentials.json
FATAL   - CIS-DI-0010: Do not store credential in ENVIRONMENT vars/files
        * Suspicious filename found : app/credentials.json
FATAL   - DKL-DI-0005: Clear apt-get caches
        * Use 'rm -rf /var/lib/apt/lists' after 'apt-get install' : /bin/sh -c apt-get update && apt-get install -y git
FATAL   - DKL-LI-0001: Avoid empty password
        * No password user found! username : nopasswd
WARN    - CIS-DI-0001: Create a user for the container
        * Last user should not be root
INFO    - CIS-DI-0005: Enable Content trust for Docker
        * export DOCKER_CONTENT_TRUST=1 before docker pull/build
INFO    - CIS-DI-0008: Confirm safety of setuid/setgid files
        * setuid file: app/suid.txt urw-r--r--
        * setgid file: app/gid.txt grw-r--r--
        * setuid file: usr/bin/gpasswd urwxr-xr-x
        * setgid file: usr/bin/wall grwxr-xr-x
        * setuid file: bin/su urwxr-xr-x
        * setuid file: bin/umount urwxr-xr-x
        * setuid file: bin/mount urwxr-xr-x
        * setgid file: usr/bin/ssh-agent grwxr-xr-x
        * setuid file: etc/shadow urw-r-----
        * setuid file: usr/bin/chsh urwxr-xr-x
        * setuid file: usr/bin/chfn urwxr-xr-x
        * setuid file: usr/lib/openssh/ssh-keysign urwxr-xr-x
        * setgid file: etc/passwd grw-r--r--
        * setgid file: sbin/unix_chkpwd grwxr-xr-x
        * setgid file: usr/bin/chage grwxr-xr-x
        * setuid file: usr/bin/passwd urwxr-xr-x
        * setgid file: usr/bin/expiry grwxr-xr-x
        * setuid file: usr/bin/newgrp urwxr-xr-x
IGNORE  - CIS-DI-0006: Add HEALTHCHECK instruction to the container image

Docker

Also, you can use Docker to use dockle command as follow.

$ export DOCKLE_LATEST=$(
 curl --silent "https://api.github.com/repos/goodwithtech/dockle/releases/latest" | \
 grep '"tag_name":' | \
 sed -E 's/.*"v([^"]+)".*/\1/' \
)
$ docker run --rm goodwithtech/dockle:v${DOCKLE_LATEST} [YOUR_IMAGE_NAME]

• If you'd like to scan the image on your host machine, you need to mount docker.sock.

  bash $ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock ...

Checkpoint Summary

• Details of each checkpoint see CHECKPOINT.md

CODE	DESCRIPTION	LEVEL※
	CIS's Docker Image Checkpoints
CIS-DI-0001	Create a user for the container	WARN
CIS-DI-0002	Use trusted base images for containers	FATAL
CIS-DI-0003	Do not install unnecessary packages in the container	FATAL
CIS-DI-0004	Scan and rebuild the images to include security patches	FATAL
CIS-DI-0005	Enable Content trust for Docker	INFO
CIS-DI-0006	Add HEALTHCHECK instruction to the container image	WARN
CIS-DI-0007	Do not use update instructions alone in the Dockerfile	FATAL
CIS-DI-0008	Confirm safety of setuid and setgid files	INFO
CIS-DI-0009	Use COPY instead of ADD in Dockerfile	FATAL
CIS-DI-0010	Do not store secrets in Dockerfiles	FATAL
CIS-DI-0011	Install verified packages only	INFO
	Dockle Checkpoints for Docker
DKL-DI-0001	Avoid sudo command	FATAL
DKL-DI-0002	Avoid sensitive directory mounting	FATAL
DKL-DI-0003	Avoid apt-get dist-upgrade	WARN
DKL-DI-0004	Use apk add with --no-cache	FATAL
DKL-DI-0005	Clear apt-get caches	FATAL
DKL-DI-0006	Avoid latest tag	WARN
	Dockle Checkpoints for Linux
DKL-LI-0001	Avoid empty password	FATAL
DKL-LI-0002	Be unique UID/GROUPs	FATAL
DKL-LI-0003	Only put necessary files	INFO

Level

Dockle has 5 check levels.

LEVEL	DESCRIPTION
FATAL	Be practical and prudent
WARN	Be practical and prudent, but limited uses (even if official images)
INFO	May negatively inhibit the utility or performance
SKIP	Not found target files
PASS	Not found any problems

Common Examples

Scan an image

Simply specify an image name (and a tag).

$ dockle goodwithtech/test-image:v1

Result

``` FATAL - CIS-DI-0001: Create a user for the container * Last user should not be root WARN - CIS-DI-0005: Enable Content trust for Docker * export DOCKER_CONTENT_TRUST=1 before docker pull/build FATAL - CIS-DI-0006: Add HEALTHCHECK instruction to the container image * not found HEALTHCHECK statement FATAL - CIS-DI-0007: Do not use update instructions alone in the Dockerfile * Use 'Always combine RUN 'apt-get update' with 'apt-get install' : /bin/sh -c apt-get update && apt-get install -y git FATAL - CIS-DI-0008: Remove setuid and setgid permissions in the images * Found setuid file: etc/passwd grw-r--r-- * Found setuid file: usr/lib/openssh/ssh-keysign urwxr-xr-x * Found setuid file: app/hoge.txt ugrw-r--r-- * Found setuid file: app/hoge.txt ugrw-r--r-- * Found setuid file: etc/shadow urw-r----- FATAL - CIS-DI-0009: Use COPY instead of ADD in Dockerfile * Use COPY : /bin/sh -c #(nop) ADD file:81c0a803075715d1a6b4f75a29f8a01b21cc170cfc1bff6702317d1be2fe71a3 in /app/credentials.json FATAL - CIS-DI-0010: Do not store secrets in ENVIRONMENT variables * Suspicious ENV key found : MYSQL_PASSWD FATAL - CIS-DI-0010: Do not store secret files * Suspicious filename found : app/credentials.json PA