Dockle - Container Image Linter for Security, Helping build the Best-Practice Docker Image, Easy to start
Dockle
helps you:
- Build Best Practice Docker images
- Build secure Docker images
- Checkpoints includes CIS Benchmarks
$ brew untap habakke/dockle # who use 0.1.16 or older version
$ brew install habakke/dockle
$ dockle [YOUR_IMAGE_NAME]
See Installation and Common Examples
- Features
- Comparison
- Installation
- Quick Start
- Checkpoint Summary
- Common Examples
- Continuous Integration
- Checkpoint Details
- CIS's Docker Image Checkpoints
- Dockle Checkpoints for Docker
- Dockle Checkpoints for Linux
- Credits
- Roadmap
- 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
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 |
You can use Homebrew on Mac OS X or Linux and WSL (Windows Subsystem for Linux).
$ brew install habakke/dockle
$ VERSION=$(
curl --silent "https://api.github.com/repos/habakke/dockle/releases/latest" | \
grep '"tag_name":' | \
sed -E 's/.*"v([^"]+)".*/\1/' \
) && rpm -ivh https://github.com/habakke/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Linux-64bit.rpm
$ VERSION=$(
curl --silent "https://api.github.com/repos/habakke/dockle/releases/latest" | \
grep '"tag_name":' | \
sed -E 's/.*"v([^"]+)".*/\1/' \
) && curl -L -o dockle.deb https://github.com/habakke/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Linux-64bit.deb
$ sudo dpkg -i dockle.deb && rm dockle.deb
dockle-bin can be installed from the Arch User Repository. Examples:
pikaur -Sy dockle-bin
or
yay -Sy dockle-bin
$ VERSION=$(
curl --silent "https://api.github.com/repos/habakke/dockle/releases/latest" | \
grep '"tag_name":' | \
sed -E 's/.*"v([^"]+)".*/\1/' \
) && curl -L -o dockle.zip https://github.com/habakke/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Windows-64bit.zip
$ unzip dockle.zip && rm dockle.zip
$ ./dockle.exe [IMAGE_NAME]
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
)
$ GO111MODULE=off go get github.com/habakke/dockle/cmd/dockle
$ cd $GOPATH/src/github.com/habakke/dockle && GO111MODULE=on go build -o $GOPATH/bin/dockle cmd/dockle/main.go
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/habakke/dockle/releases/latest" | \
grep '"tag_name":' | \
sed -E 's/.*"v([^"]+)".*/\1/' \
) && docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
habakke/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.
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
Also, you can use Docker to use dockle
command as follow.
$ export DOCKLE_LATEST=$(
curl --silent "https://api.github.com/repos/habakke/dockle/releases/latest" | \
grep '"tag_name":' | \
sed -E 's/.*"v([^"]+)".*/\1/' \
)
$ docker run --rm habakke/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 ...
- 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 |
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 |
Simply specify an image name (and a tag).
$ dockle habakke/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
PASS - DKL-DI-0001: Avoid sudo command
FATAL - DKL-DI-0002: Avoid sensitive directory mounting
* Avoid mounting sensitive dirs : /usr
PASS - DKL-DI-0003: Avoid apt-get/apk/dist-upgrade
PASS - DKL-DI-0004: Use apk add with --no-cache
FATAL - DKL-DI-0005: 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 - DKL-DI-0006: Avoid latest tag
FATAL - DKL-LI-0001: Avoid empty password
* No password user found! username : nopasswd
PASS - DKL-LI-0002: Be unique UID
PASS - DKL-LI-0002: Be unique GROUP
$ docker save alpine:latest -o alpine.tar
$ dockle --input alpine.tar
$ dockle -f json habakke/test-image:v1
$ dockle -f json -o results.json habakke/test-image:v1
Result
{
"summary": {
"fatal": 6,
"warn": 2,
"info": 2,
"pass": 7
},
"details": [
{
"code": "CIS-DI-0001",
"title": "Create a user for the container",
"level": "WARN",
"alerts": [
"Last user should not be root"
]
},
{
"code": "CIS-DI-0005",
"title": "Enable Content trust for Docker",
"level": "INFO",
"alerts": [
"export DOCKER_CONTENT_TRUST=1 before docker pull/build"
]
},
{
"code": "CIS-DI-0006",
"title": "Add HEALTHCHECK instruction to the container image",
"level": "WARN",
"alerts": [
"not found HEALTHCHECK statement"
]
},
{
"code": "CIS-DI-0008",
"title": "Remove setuid and setgid permissions in the images",
"level": "INFO",
"alerts": [
"Found setuid file: usr/lib/openssh/ssh-keysign urwxr-xr-x"
]
},
{
"code": "CIS-DI-0009",
"title": "Use COPY instead of ADD in Dockerfile",
"level": "FATAL",
"alerts": [
"Use COPY : /bin/sh -c #(nop) ADD file:81c0a803075715d1a6b4f75a29f8a01b21cc170cfc1bff6702317d1be2fe71a3 in /app/credentials.json "
]
},
{
"code": "CIS-DI-0010",
"title": "Do not store secrets in ENVIRONMENT variables",
"level": "FATAL",
"alerts": [
"Suspicious ENV key found : MYSQL_PASSWD"
]
},
{
"code": "CIS-DI-0010",
"title": "Do not store secret files",
"level": "FATAL",
"alerts": [
"Suspicious filename found : app/credentials.json "
]
},
{
"code": "DKL-DI-0002",
"title": "Avoid sensitive directory mounting",
"level": "FATAL",
"alerts": [
"Avoid mounting sensitive dirs : /usr"
]
},
{
"code": "DKL-DI-0005",
"title": "Clear apt-get caches",
"level": "FATAL",
"alerts": [
"Use 'rm -rf /var/lib/apt/lists' after 'apt-get install' : /bin/sh -c apt-get update \u0026\u0026 apt-get install -y git"
]
},
{
"code": "DKL-LI-0001",
"title": "Avoid empty password",
"level": "FATAL",
"alerts": [
"No password user found! username : nopasswd"
]
}
]
}
$ dockle -f sarif habakke/test-image:v1
$ dockle -f sarif -o results.json habakke/test-image:v1
By default, Dockle
exits with code 0
even if there are some problems.
Use the --exit-code, -c
option to exit with a non-zero exit code if WARN
or FATAL
alert were found.
$ dockle --exit-code 1 [IMAGE_NAME]
By default, --exit-code
run when there are WARN
or FATAL
level alerts.
Use the --exit-level, -l
option to change alert level. You can set info
, warn
or fatal
.
$ dockle --exit-code 1 --exit-level info [IMAGE_NAME]
$ dockle --exit-code 1 --exit-level fatal [IMAGE_NAME]
The --ignore, -i
option can ignore specified checkpoints.
$ dockle -i CIS-DI-0001 -i DKL-DI-0006 [IMAGE_NAME]
Or, use .dockleignore
file.
$ cat .dockleignore
# set root to default user because we want to run nginx
CIS-DI-0001
# Use latest tag because to check the image inside only
DKL-DI-0006
You can scan your built image with Dockle
in Travis CI/CircleCI.
In these examples, the test will fail with if any warnings were found.
Though, you can ignore the specified target checkpoints by using .dockleignore
file.
Or, if you just want the results to display and not let the test fail for this, specify --exit-code
to 0
in dockle
command.
.travis.yml
services:
- docker
env:
global:
- COMMIT=${TRAVIS_COMMIT::8}
before_install:
- docker build -t dockle-ci-test:${COMMIT} .
- export VERSION=$(curl --silent "https://api.github.com/repos/habakke/dockle/releases/latest" | grep '"tag_name":' | sed -E 's/.*"v([^"]+)".*/\1/')
- wget https://github.com/habakke/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Linux-64bit.tar.gz
- tar zxvf dockle_${VERSION}_Linux-64bit.tar.gz
script:
- ./dockle dockle-ci-test:${COMMIT}
- ./dockle --exit-code 1 dockle-ci-test:${COMMIT}
- Example: https://travis-ci.org/habakke/dockle-ci-test
- Repository: https://github.com/habakke/dockle-ci-test
.circleci/config.yml
jobs:
build:
docker:
- image: docker:18.09-git
steps:
- checkout
- setup_remote_docker
- run:
name: Build image
command: docker build -t dockle-ci-test:${CIRCLE_SHA1} .
- run:
name: Install dockle
command: |
apk add --update curl
VERSION=$(
curl --silent "https://api.github.com/repos/habakke/dockle/releases/latest" | \
grep '"tag_name":' | \
sed -E 's/.*"v([^"]+)".*/\1/'
)
wget https://github.com/habakke/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Linux-64bit.tar.gz
tar zxvf dockle_${VERSION}_Linux-64bit.tar.gz
mv dockle /usr/local/bin
- run:
name: Scan the local image with dockle
command: dockle --exit-code 1 dockle-ci-test:${CIRCLE_SHA1}
workflows:
version: 2
release:
jobs:
- build
- Example: https://circleci.com/gh/habakke/dockle-ci-test
- Repository: https://github.com/habakke/dockle-ci-test
.gitlab-ci.yml
image: docker:stable
stages:
- test
variables:
DOCKER_HOST: tcp://docker:2375/
DOCKER_DRIVER: overlay2
services:
- docker:dind
unit_test:
stage: test
before_script:
- apk -Uuv add bash git curl tar sed grep
script:
- docker build -t dockle-ci-test:${CI_COMMIT_SHORT_SHA} .
- |
VERSION=$(
curl --silent "https://api.github.com/repos/habakke/dockle/releases/latest" | \
grep '"tag_name":' | \
sed -E 's/.*"v([^"]+)".*/\1/' \
) && curl -L -o dockle.tar.gz https://github.com/habakke/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Linux-64bit.tar.gz && \
tar zxvf dockle.tar.gz
- ./dockle --exit-code 1 dockle-ci-test:${CI_COMMIT_SHORT_SHA}
- Example: https://gitlab.com/tomoyamachi/dockle-ci-test/-/jobs/238215077
- Repository: https://github.com/habakke/dockle-ci-test
Dockle
can download images from a private registry, without installing Docker
or any other 3rd party tools. It's designed so for ease of use in a CI process.
All you have to do is: install Dockle
and set ENVIRONMENT variables.
- NOTE: I don't recommend using ENV vars in your local machine.
To download the private repository from Docker Hub, you need to set DOCKLE_AUTH_URL
, DOCKLE_USERNAME
and DOCKLE_PASSWORD
ENV vars.
export DOCKLE_AUTH_URL=https://registry.hub.docker.com
export DOCKLE_USERNAME={DOCKERHUB_USERNAME}
export DOCKLE_PASSWORD={DOCKERHUB_PASSWORD}
- NOTE: You don't need to set ENV vars when downloading from the public repository.
Dockle
uses the AWS SDK. You don't need to install aws
CLI tool.
Use AWS CLI's ENVIRONMENT variables.
export AWS_ACCESS_KEY_ID={AWS ACCESS KEY}
export AWS_SECRET_ACCESS_KEY={SECRET KEY}
export AWS_DEFAULT_REGION={AWS REGION}
Dockle
uses the Google Cloud SDK. So, you don't need to install gcloud
command.
If you'd like to use the target project's repository, you can settle via GOOGLE_APPLICATION_CREDENTIAL
.
# must set DOCKLE_USERNAME empty char
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credential.json
BasicAuth server needs DOCKLE_USERNAME
and DOCKLE_PASSWORD
.
export DOCKLE_USERNAME={USERNAME}
export DOCKLE_PASSWORD={PASSWORD}
# if you'd like to use 80 port, use NonSSL
export DOCKLE_NON_SSL=true
Special Thanks to @knqyf263 (Teppei Fukuda) and Trivy
This project exists thanks to all the people who contribute. [Contribute].
Become a financial contributor and help us sustain our community. [Contribute]
Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]
- AGPLv3
@tomoyamachi (Tomoya Amachi)
- 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
- 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
- dangerous mount