dockle

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

2,768

139

2,768

View on GitHub

Top Related Projects

trivy

22,801

Find vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more

grype

8,441

A vulnerability scanner for container images and filesystems

clair

10,255

Vulnerability Static Analysis for Containers

docker-bench-security

9,097

The Docker Bench for Security is a script that checks for dozens of common best-practices around deploying Docker containers in production.

dive

45,863

A tool for exploring each layer in a docker image

hadolint

10,221

Dockerfile linter, validate inline bash, written in Haskell

Quick Overview

Dockle is a container image linter for security, helping developers and DevOps teams identify and fix potential vulnerabilities in Docker images. It performs comprehensive checks against best practices and security standards, providing actionable insights to improve container security.

Pros

Easy to use with a simple CLI interface
Integrates well with CI/CD pipelines for automated security checks
Provides detailed explanations and remediation suggestions for identified issues
Supports custom rule configuration to adapt to specific project needs

Cons

Limited to Docker image analysis, not covering other container technologies
May produce false positives in some cases, requiring manual verification
Requires regular updates to stay current with the latest security best practices
Performance can be slow for large images with many layers

Getting Started

To get started with Dockle, follow these steps:

Install Dockle:

# For macOS
brew install goodwithtech/r/dockle

# For Linux
wget https://github.com/goodwithtech/dockle/releases/download/v0.4.5/dockle_0.4.5_Linux-64bit.tar.gz
tar zxvf dockle_0.4.5_Linux-64bit.tar.gz
sudo mv dockle /usr/local/bin

Run Dockle on a Docker image:

dockle <image_name>

To ignore specific checks, use the --ignore flag:

dockle --ignore CIS-DI-0001,CIS-DI-0005 <image_name>

For CI/CD integration, use the exit code to determine success or failure:

dockle <image_name>
if [ $? -ne 0 ]; then
  echo "Dockle found issues in the image"
  exit 1
fi

For more advanced usage and configuration options, refer to the official documentation on the GitHub repository.

Competitor Comparisons

trivy

22,801

Find vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more

Pros of Trivy

Broader scanning capabilities: Covers container images, filesystems, git repositories, and Kubernetes clusters
Faster scanning speed, especially for large images
More comprehensive vulnerability database, including multiple sources

Cons of Trivy

Higher resource consumption during scans
More complex configuration for advanced use cases
Steeper learning curve for new users

Code Comparison

Dockle usage:

dockle image_name

Trivy usage:

trivy image image_name

Both tools offer simple command-line interfaces for basic scanning. However, Trivy provides more options for customization:

trivy image --severity HIGH,CRITICAL --ignore-unfixed image_name

This command scans for only high and critical vulnerabilities, ignoring those without fixes.

Dockle focuses on Dockerfile and image best practices, while Trivy primarily targets vulnerability scanning. Trivy's broader scope and more frequent updates make it suitable for comprehensive security checks, whereas Dockle excels in Docker-specific linting and best practice enforcement.

grype

8,441

A vulnerability scanner for container images and filesystems

Pros of Grype

More comprehensive vulnerability scanning, covering a wider range of package ecosystems
Faster scanning speed, especially for large container images
Active development with frequent updates and community support

Cons of Grype

Focused primarily on vulnerability scanning, lacking some container-specific checks
May produce more verbose output, requiring additional filtering or processing
Steeper learning curve for advanced features and customizations

Code Comparison

Dockle (shell command):

dockle --exit-code 1 --exit-level fatal myimage:latest

Grype (shell command):

grype myimage:latest

Both tools can be easily integrated into CI/CD pipelines, but Grype offers more flexibility in output formats and scanning options. Dockle provides a simpler interface for quick container checks, while Grype excels in comprehensive vulnerability analysis across various package types and ecosystems.

Dockle is more focused on Docker best practices and CIS benchmarks, making it ideal for container-specific security checks. Grype, on the other hand, offers broader vulnerability scanning capabilities, making it suitable for a wider range of security assessments beyond just containers.

clair

10,255

Vulnerability Static Analysis for Containers

Pros of Clair

More comprehensive vulnerability scanning, covering a wider range of operating systems and package managers
Better suited for enterprise-level deployments with scalable architecture
Supports integration with various container registries and CI/CD pipelines

Cons of Clair

More complex setup and configuration compared to Dockle
Requires additional infrastructure components (database, API server)
Steeper learning curve for new users

Code Comparison

Dockle can be run with a simple command:

dockle image:tag

Clair requires more setup, including database configuration:

clair:
  database:
    type: pgsql
    options:
      source: host=postgres port=5432 user=clair dbname=clair sslmode=disable

Both tools provide JSON output for integration with other tools, but Clair's output is more detailed:

Dockle:

{
  "summary": {
    "fatal": 0,
    "warn": 2,
    "info": 1,
    "pass": 10
  }
}

Clair:

{
  "Layer": {
    "Name": "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
    "NamespaceName": "alpine:3.10",
    "Features": [
      {
        "Name": "musl",
        "NamespaceName": "alpine:3.10",
        "Version": "1.1.22-r3",
        "Vulnerabilities": [
          {
            "Name": "CVE-2019-14697",
            "NamespaceName": "alpine:3.10",
            "Description": "In musl libc through 1.1.23, wcsnrtombs...",
            "Severity": "High"
          }
        ]
      }
    ]
  }
}

docker-bench-security

9,097

The Docker Bench for Security is a script that checks for dozens of common best-practices around deploying Docker containers in production.

Pros of docker-bench-security

More comprehensive security checks, covering a wider range of Docker security best practices
Actively maintained by Docker, ensuring up-to-date security recommendations
Provides detailed explanations and remediation steps for each security issue

Cons of docker-bench-security

Primarily focused on Docker host and daemon configuration, less emphasis on container image analysis
Can be more complex to interpret results, especially for beginners
Requires root access to run some checks, which may not be feasible in all environments

Code Comparison

docker-bench-security:

#!/bin/sh
# Docker Bench for Security v1.3.4
# https://github.com/docker/docker-bench-security

# Check for containers with excessive capabilities
check_4_5() {
  id_4_5="4.5"
  desc_4_5="Ensure Content trust for Docker is Enabled"
  check_4_5="$id_4_5  - $desc_4_5"
  starttestjson "$id_4_5" "$desc_4_5"

dockle:

func (s *Scanner) ScanImage(ctx context.Context, imageName string, opts types.ScanOptions) (types.Results, error) {
	log.Logger.Debugf("Start scanning %s", imageName)
	results := types.Results{}
	err := s.initializeDockerClient(ctx)
	if err != nil {
		return nil, xerrors.Errorf("unable to initialize Docker client: %w", err)
	}

dive

45,863

A tool for exploring each layer in a docker image

Pros of dive

Provides a detailed layer-by-layer analysis of Docker images
Offers an interactive CLI interface for exploring image contents
Helps identify large layers and potential areas for image optimization

Cons of dive

Focused solely on image analysis, lacking security scanning features
Does not provide compliance checks or best practice recommendations
Limited to local image analysis, without integration for CI/CD pipelines

Code comparison

dive:

func analyzeImageLayers(image *image.Image) ([]layer.Layer, error) {
    layers := make([]layer.Layer, len(image.RootFS.DiffIDs))
    for idx, diffID := range image.RootFS.DiffIDs {
        layers[idx] = layer.NewLayer(diffID)
    }
    return layers, nil
}

dockle:

func (a *Assessor) Assess() ([]types.Assessment, error) {
    var assessments []types.Assessment
    for _, checker := range a.Checkers {
        assessment, err := checker.Check()
        if err != nil {
            return nil, err
        }
        assessments = append(assessments, assessment)
    }
    return assessments, nil
}

While dive focuses on analyzing image layers, dockle emphasizes security and compliance checks. The code snippets reflect their different purposes, with dive handling layer analysis and dockle performing assessments using various checkers.

hadolint

10,221

Dockerfile linter, validate inline bash, written in Haskell

Pros of Hadolint

More comprehensive Dockerfile linting rules, including shell script analysis
Integrates well with CI/CD pipelines and popular code editors
Supports custom rule creation using Haskell

Cons of Hadolint

Focused solely on Dockerfile linting, lacking container image scanning capabilities
May produce false positives in some cases, requiring careful configuration
Steeper learning curve for custom rule development due to Haskell

Code Comparison

Hadolint example:

FROM ubuntu:18.04
RUN apt-get update && apt-get install -y python
COPY . /app
CMD ["python", "app.py"]

Dockle example:

FROM alpine:3.12
RUN apk add --no-cache python3
COPY . /app
USER nobody
CMD ["python3", "app.py"]

Hadolint would flag issues like using the latest tag and potential outdated packages, while Dockle would additionally check for security best practices like running as a non-root user.

Both tools aim to improve Dockerfile quality and security, but Hadolint focuses on linting while Dockle offers broader container image analysis. Hadolint provides more detailed Dockerfile checks, while Dockle includes additional security scans for the resulting container image.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

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 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

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.
```
$ 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
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

Scan an image file

$ docker save alpine:latest -o alpine.tar
$ dockle --input alpine.tar

Get or Save the results as JSON

$ dockle -f json goodwithtech/test-image:v1
$ dockle -f json -o results.json goodwithtech/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"
      ]
    }
  ]
}

Get or Save the results as SARIF

$ dockle -f sarif goodwithtech/test-image:v1
$ dockle -f sarif -o results.json goodwithtech/test-image:v1

Result

{
  "version": "2.1.0",
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Dockle",
          "informationUri": "https://github.com/goodwithtech/dockle",
          "rules": [
            {
              "id": "CIS-DI-0009",
              "shortDescription": {
                "text": "Use COPY instead of ADD in Dockerfile"
              },
              "help": {
                "text": "https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md#CIS-DI-0009"
              }
            },
            {
              "id": "CIS-DI-0010",
              "shortDescription": {
                "text": "Do not store credential in ENVIRONMENT vars/files"
              },
              "help": {
                "text": "https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md#CIS-DI-0010"
              }
            },
            {
              "id": "DKL-DI-0005",
              "shortDescription": {
                "text": "Clear apt-get caches"
              },
              "help": {
                "text": "https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md#DKL-DI-0005"
              }
            },
            {
              "id": "DKL-LI-0001",
              "shortDescription": {
                "text": "Avoid empty password"
              },
              "help": {
                "text": "https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md#DKL-LI-0001"
              }
            },
            {
              "id": "CIS-DI-0005",
              "shortDescription": {
                "text": "Enable Content trust for Docker"
              },
              "help": {
                "text": "https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md#CIS-DI-0005"
              }
            },
            {
              "id": "CIS-DI-0008",
              "shortDescription": {
                "text": "Confirm safety of setuid/setgid files"
              },
              "help": {
                "text": "https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md#CIS-DI-0008"
              }
            },
            {
              "id": "CIS-DI-0001",
              "shortDescription": {
                "text": "Create a user for the container"
              },
              "help": {
                "text": "https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md#CIS-DI-0001"
              }
            },
            {
              "id": "CIS-DI-0006",
              "shortDescription": {
                "text": "Add HEALTHCHECK instruction to the container image"
              },
              "help": {
                "text": "https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md#CIS-DI-0006"
              }
            }
          ]
        }
      },
      "results": [
        {
          "ruleId": "CIS-DI-0009",
          "level": "error",
          "message": {
            "text": "Use COPY : /bin/sh -c #(nop) ADD file:81c0a803075715d1a6b4f75a29f8a01b21cc170cfc1bff6702317d1be2fe71a3 in /app/credentials.json "
          }
        },
        {
          "ruleId": "CIS-DI-0010",
          "level": "error",
          "message": {
            "text": "Suspicious filename found : app/credentials.json , Suspicious ENV key found : MYSQL_PASSWD"
          }
        },
        {
          "ruleId": "DKL-DI-0005",
          "level": "error",
          "message": {
            "text": "Use 'rm -rf /var/lib/apt/lists' after 'apt-get install' : /bin/sh -c apt-get update \u0026\u0026 apt-get install -y git"
          }
        },
        {
          "ruleId": "DKL-LI-0001",
          "level": "error",
          "message": {
            "text": "No password user found! username : nopasswd"
          }
        },
        {
          "ruleId": "CIS-DI-0005",
          "level": "note",
          "message": {
            "text": "export DOCKER_CONTENT_TRUST=1 before docker pull/build"
          }
        },
        {
          "ruleId": "CIS-DI-0008",
          "level": "note",
          "message": {
            "text": "setuid file: urwxr-xr-x usr/bin/newgrp, setgid file: grwxr-xr-x usr/bin/ssh-agent, setgid file: grwxr-xr-x usr/bin/expiry, setuid file: urwxr-xr-x usr/lib/openssh/ssh-keysign, setuid file: urwxr-xr-x bin/umount, setgid file: grwxr-xr-x usr/bin/chage, setuid file: urwxr-xr-x usr/bin/passwd, setgid file: grwxr-xr-x sbin/unix_chkpwd, setuid file: urwxr-xr-x usr/bin/chsh, setgid file: grwxr-xr-x usr/bin/wall, setuid file: urwxr-xr-x bin/ping, setuid file: urwxr-xr-x bin/su, setuid file: urwxr-xr-x usr/bin/chfn, setuid file: urwxr-xr-x usr/bin/gpasswd, setuid file: urwxr-xr-x bin/mount"
          }
        },
        {
          "ruleId": "CIS-DI-0001",
          "level": "none",
          "message": {
            "text": "Last user should not be root"
          }
        },
        {
          "ruleId": "CIS-DI-0006",
          "level": "none",
          "message": {
            "text": "not found HEALTHCHECK statement"
          }
        }
      ]
    }
  ]
}

Specify exit code

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]

Specify exit level

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]

Ignore the specified checkpoints

The --ignore, -i option can ignore specified checkpoints.

$ dockle -i CIS-DI-0001 -i DKL-DI-0006 [IMAGE_NAME]

Or, use DOCKLE_IGNORES:

export DOCKLE_IGNORES=CIS-DI-0001,DKL-DI-0006
dockle [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

Accept suspicious `environment variables` / `files` / `file extensions`

# --accept-key value, --ak value             You can add acceptable keywords.
dockle -ak GPG_KEY -ak KEYCLOAK_VERSION [IMAGE_NAME]
or DOCKLE_ACCEPT_KEYS=GPG_KEY,KEYCLOAK_VERSION dockle [IMAGE_NAME]

# --accept-file value, --af value            You can add acceptable file names.
dockle -af id_rsa -af id_dsa [IMAGE_NAME]
or DOCKLE_ACCEPT_FILES=id_rsa,id_dsa dockle [IMAGE_NAME]

# --accept-file-extension value, --ae value  You can add acceptable file extensions.
dockle -ae pem -ae log [IMAGE_NAME]
or DOCKLE_ACCEPT_FILE_EXTENSIONS=pem,log dockle [IMAGE_NAME]

Continuous Integration (CI)

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.

GitHub Action

We provide goodwithtech/dockle-action.

- uses: goodwithtech/dockle-action@main
  with:
    image: 'target'
    format: 'list'
    exit-code: '1'
    exit-level: 'warn'
    ignore: 'CIS-DI-0001,DKL-DI-0006'

Travis CI

.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/goodwithtech/dockle/releases/latest" | grep '"tag_name":' | sed -E 's/.*"v([^"]+)".*/\1/')
  - wget https://github.com/goodwithtech/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/goodwithtech/dockle-ci-test
Repository: https://github.com/goodwithtech/dockle-ci-test

CircleCI

.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/goodwithtech/dockle/releases/latest" | \
                grep '"tag_name":' | \
                sed -E 's/.*"v([^"]+)".*/\1/'
            )
            wget https://github.com/goodwithtech/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/goodwithtech/dockle-ci-test
Repository: https://github.com/goodwithtech/dockle-ci-test

GitLab CI

.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/goodwithtech/dockle/releases/latest" | \
      grep '"tag_name":' | \
      sed -E 's/.*"v([^"]+)".*/\1/' \
      ) && curl -L -o dockle.tar.gz https://github.com/goodwithtech/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/goodwithtech/dockle-ci-test

Authorization for Private Docker Registry

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.

Docker Hub

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.

Amazon ECR (Elastic Container Registry)

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}

GCR (Google Container Registry)

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

Self Hosted Registry (BasicAuth)

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

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

License

Apache License 2.0

Author

@tomoyamachi (Tomoya Amachi)

Special Thanks to @knqyf263 (Teppei Fukuda) and Trivy

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Getting Started

Competitor Comparisons

Pros of Trivy

Cons of Trivy

Code Comparison

Pros of Grype

Cons of Grype

Code Comparison

Pros of Clair

Cons of Clair

Code Comparison

Pros of docker-bench-security

Cons of docker-bench-security

Code Comparison

Pros of dive

Cons of dive

Code comparison

Pros of Hadolint

Cons of Hadolint

Code Comparison

Convert designs to code with AI

README

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

Level

Common Examples

Scan an image

Scan an image file

Get or Save the results as JSON

Get or Save the results as SARIF

Specify exit code

Specify exit level

Ignore the specified checkpoints

Accept suspicious environment variables / files / file extensions

Continuous Integration (CI)

GitHub Action

Travis CI

CircleCI

GitLab CI

Authorization for Private Docker Registry

Docker Hub

Amazon ECR (Elastic Container Registry)

GCR (Google Container Registry)

Self Hosted Registry (BasicAuth)

Contributors

Code Contributors

Financial Contributors

Individuals

Organizations

License

Author

Top Related Projects

Convert designs to code with AI

Accept suspicious `environment variables` / `files` / `file extensions`