dockle

Dockle - Simple Security Auditing and helping build the Best Docker Images

Dockle helps you:

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

To check your Docker image, only run:

$ brew install goodwithtech/dockle/dockle
$ dockle [YOUR_IMAGE_NAME]

TOC

• Features
• Comparison
• Installation
  • Linuxbrew
  • RHEL/CentOS
  • Debian/Ubuntu
  • Mac OS X / Homebrew
  • Windows
  • Binary
  • From source
  • Use Docker
• Checkpoint Summary
• Quick Start
  • Basic
  • Docker
• Examples
  • Scan an image
  • Scan an image file
  • Get or Save the results as JSON
  • Specify exit code
  • Ignore the specified checkpoints
  • Clear image caches
• Continuous Integration
  • Travis CI
  • CircleCI
  • 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 Examples
• CIS Benchmarks Support
  • High accuracy
• DevSecOps
  • Suitable for CI such as Travis CI, CircleCI, Jenkins, etc.
  • See CI Example

Comparison

Installation

Linuxbrew

You can use Homebrew on Linux and WSL (Windows Subsystem for Linux).

$ brew install goodwithtech/dockle/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

Mac OS X / Homebrew

You can use Homebrew on macOS.

$ brew install goodwithtech/dockle/dockle

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]

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)

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 goodwithtech/dockle:v${VERSION} [YOUR_IMAGE_NAME]

Quick Start

Here's a quick start. For more detailed usage and samples, such as using dockle on CIs, see EXAMPLES.md.

Basic

Simply specify an image name (and a tag).

$ dockle [YOUR_IMAGE_NAME]

FATAL   - Create a user for the container
        * Last user should not be root
WARN    - Enable Content trust for Docker
        * export DOCKER_CONTENT_TRUST=1 before docker pull/build
FATAL   - Add HEALTHCHECK instruction to the container image
        * not found HEALTHCHECK statement
FATAL   - 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
PASS    - Remove setuid and setgid permissions in the images
FATAL   - Use COPY instead of ADD in Dockerfile
        * Use COPY : /bin/sh -c #(nop) ADD file:81c0a803075715d1a6b4f75a29f8a01b21cc170cfc1bff6702317d1be2fe71a3 in /app/credentials.json
FATAL   - Do not store secrets in ENVIRONMENT variables
        * Suspicious ENV key found : MYSQL_PASSWD
FATAL   - Do not store secret files
        * Suspicious filename found : app/credentials.json
PASS    - Avoid sudo command
FATAL   - Avoid sensitive directory mounting
        * Avoid mounting sensitive dirs : /usr
PASS    - Avoid apt-get/apk/dist-upgrade
PASS    - Use apk add with --no-cache
FATAL   - Clear apt-get caches
        * Use 'apt-get clean && rm -rf /var/lib/apt/lists/*' : /bin/sh -c apt-get update && apt-get install -y git
PASS    - Avoid latest tag
FATAL   - Avoid empty password
        * No password user found! username : nopasswd
PASS    - Be unique UID
PASS    - Be unique GROUP

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]

For more suitable use, I suggest mounting a cache directory. Replace [YOUR_CACHE_DIR] below with the cache directory on your machine.

$ 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 -v [YOUR_CACHE_DIR]:/root/.cache/ goodwithtech/dockle:v${DOCKLE_LATEST} [YOUR_IMAGE_NAME]

• Example for macOS:

  $ docker run --rm -v $HOME/Library/Caches:/root/.cache/ 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.

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

Checkpoint Summary

• Details of each checkpoint see CHECKPOINT.md

Level

Dockle has 5 check levels.

Credits

Special Thanks to @knqyf263 (Teppei Fukuda) and Trivy

License

• AGPLv3

Author

@tomoyamachi (Tomoya Amachi)

Roadmap

• JSON output
• Check php.ini file
• Check nginx.conf file
• create CI badges
• Check /etc/hosts
  • duplicates
  • hostname
  • localhost
• Packages
  • Package managers
• File Permissions
  • Insecure permission
• Image Size
  • check large size container

if running docker daemon...

• Networking
  • docker port container if docker running
  • by file
    • /proc/1/net/tcp : openning port (if running)
• Volume mount
  • dangerous mount
    • /boot, /dev, /etc, /lib