goodwithtech/dockle

Dockle - 容器镜像安全与最佳实践检查工具

Dockle 是一款专注于容器镜像安全和最佳实践的检查工具，帮助开发者构建安全、合规的 Docker 镜像。它支持 CIS 基准检查，能够检测镜像中的安全隐患和不符合最佳实践的配置，适用于集成到 CI/CD 流程中，实现 DevSecOps 自动化检查。

核心功能与特性

• 安全隐患检测：识别镜像中的敏感信息泄露、权限问题等安全风险
• 最佳实践指导：帮助优化 Dockerfile，遵循 Docker 官方最佳实践
• 简单易用：仅需指定镜像名称即可执行检查，无需复杂配置
• CIS 基准支持：符合 CIS Docker 镜像安全基准，检查准确性高
• DevSecOps 集成：支持 Travis CI、CircleCI、GitLab CI 等主流 CI 平台，实现自动化检查

工具对比

安装方法

Homebrew（macOS/Linux/WSL）

bash
# 若使用 0.1.16 或更早版本，先执行以下命令
brew untap goodwithtech/dockle
# 安装最新版本
brew install goodwithtech/r/dockle

RHEL/CentOS

bash
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

bash
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

可通过 AUR 安装 dockle-bin 包：

bash
pikaur -Sy dockle-bin
# 或
yay -Sy dockle-bin

Windows

bash
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 [镜像名称]

二进制文件

从 https://github.com/goodwithtech/dockle/releases/latest 下载对应操作系统/架构的二进制包，解压后将可执行文件放入 $PATH 目录（如 Unix 系统的 /usr/local/bin），并赋予执行权限：

bash
chmod +x dockle

源码编译

bash
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

使用 Docker 容器

bash
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} [镜像名称]

若需扫描本地主机上的镜像，需挂载 Docker 套接字：-v /var/run/docker.sock:/var/run/docker.sock

快速开始

基本使用

直接指定镜像名称（及标签）即可执行检查：

bash
dockle [镜像名称]

FATAL   - CIS-DI-0009: Dockerfile 中应使用 COPY 而非 ADD
        * 使用 COPY : /bin/sh -c #(nop) ADD file:81c0a803075715d1a6b4f75a29f8a01b21cc170cfc1bff6702317d1be2fe71a3 in /app/credentials.json
FATAL   - CIS-DI-0010: 不要在环境变量/文件中存储凭证
        * 发现可疑文件 : app/credentials.json
FATAL   - DKL-DI-0005: 清理 apt-get 缓存
        * 在 'apt-get install' 后使用 'rm -rf /var/lib/apt/lists' : /bin/sh -c apt-get update && apt-get install -y git
FATAL   - DKL-LI-0001: 避免空密码
        * 发现无密码用户! 用户名 : nopasswd
WARN    - CIS-DI-0001: 为容器创建用户
        * 最后一个用户不应为 root
INFO    - CIS-DI-0005: 启用 Docker 内容信任
        * 在 docker pull/build 前执行 'export DOCKER_CONTENT_TRUST=1'

Docker 容器方式

bash
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} [镜像名称]

检查点摘要

检查级别说明

常用示例

扫描镜像

bash
dockle goodwithtech/test-image:v1

扫描镜像文件

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

以 JSON 格式输出结果

bash
# 直接输出 JSON
dockle -f json goodwithtech/test-image:v1
# 保存 JSON 结果到文件
dockle -f json -o results.json goodwithtech/test-image:v1

json
{
  "summary": {
    "fatal": 6,
    "warn": 2,
    "info": 2,
    "pass": 7
  },
  "details": [
    {
      "code": "CIS-DI-0001",
      "title": "为容器创建用户",
      "level": "WARN",
      "alerts": [
        "最后一个用户不应为 root"
      ]
    },
    {
      "code": "CIS-DI-0005",
      "title": "启用 Docker 内容信任",
      "level": "INFO",
      "alerts": [
        "在 docker pull/build 前执行 'export DOCKER_CONTENT_TRUST=1'"
      ]
    }
  ]
}

指定退出码

默认情况下，即使发现问题，Dockle 也会以 0 退出。使用 --exit-code 选项可在发现 WARN 或 FATAL 级别问题时返回非零退出码：

bash
dockle --exit-code 1 [镜像名称]

指定退出级别

使用 --exit-level 选项可指定触发退出码的检查级别（info、warn 或 fatal）：

bash
# 当存在 INFO 及以上级别问题时退出码为 1
dockle --exit-code 1 --exit-level info [镜像名称]
# 仅当存在 FATAL 级别问题时退出码为 1
dockle --exit-code 1 --exit-level fatal [镜像名称]

忽略指定检查点

使用 --ignore 选项或 .dockleignore 文件可忽略指定检查点：

bash
# 命令行忽略
dockle -i CIS-DI-0001 -i DKL-DI-0006 [镜像名称]

# 或使用 .dockleignore 文件
cat .dockleignore
# 因需以 root 运行 nginx，忽略 CIS-DI-0001
CIS-DI-0001
# 因仅检查镜像内部，使用 latest 标签，忽略 DKL-DI-0006
DKL-DI-0006

持续集成（CI）

Travis CI

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

CircleCI

yaml
jobs:
  build:
    docker:
      - image: docker:18.09-git
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: 构建镜像
          command: docker build -t dockle-ci-test:${CIRCLE_SHA1} .
      - run:
          name: 安装 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: 扫描本地镜像
          command: dockle --exit-code 1 dockle-ci-test:${CIRCLE_SHA1}
workflows:
  version: 2
  release:
    jobs:
      - build

GitLab CI

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

私有 Docker 仓库认证

Dockle 支持从私有仓库拉取镜像，无需安装 Docker 或其他工具，只需设置环境变量：

Docker Hub 私有仓库

bash
export DOCKLE_AUTH_URL=https://registry.hub.docker.com
export DOCKLE_USERNAME={Docker Hub 用户名}
export DOCKLE_PASSWORD={Docker Hub 密码}

Amazon ECR

使用 AWS SDK 环境变量：

bash
export AWS_ACCESS_KEY_ID={AWS 访问密钥}
export AWS_SECRET_ACCESS_KEY={AWS 密钥}
export AWS_DEFAULT_REGION={AWS 区域}

Google GCR

bash
# 需将 DOCKLE_USERNAME 设置为空
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credential.json
export DOCKLE_USERNAME=

私有仓库（BasicAuth）

bash
export DOCKLE_USERNAME={用户名}
export DOCKLE_PASSWORD={密码}
# 若使用 80 端口，需启用非 SSL 模式
export DOCKLE_NON_SSL=true

检查点详情

完整检查点说明请参见 https://github.com/goodwithtech/dockle/blob/master/CHECKPOINT.md%EF%BC%8C%E5%8C%85%E6%8B%AC%EF%BC%9A

• CIS Docker 镜像检查点
• Dockle Docker 检查点
• Dockle Linux 检查点

许可证

AGPLv3

作者

https://github.com/tomoyamachi (Tomoya Amachi)

开发路线图

• JSON 输出格式
• 检查 php.ini 文件
• 检查 nginx.conf 文件
• 创建 CI 徽章
• 检查 /etc/hosts（