docker

Use the docker InSpec audit resource to test configuration data for docker daemon. It is a very comprehensive resource. Please have a look at docker_container and docker_image, too.


Syntax

A docker resource block declares allows you to write test for many containers:

describe docker.containers do
  its('images') { should_not include 'u12:latest' }
end

or:

describe docker.containers.where { names == 'flamboyant_colden' } do
  it { should be_running }
end

where

  • .where() may specify a specific item and value, to which the matchers are compared
  • commands, ids, images, labels, local_volumes, mounts, names, networks, ports, sizes and 'status' are valid matchers for containers

The docker resource block also declares allows you to write test for many images:

describe docker.images do
  its('repositories') { should_not include 'inssecure_image' }
end

or if you want to query specific images:

describe docker.images.where { repository == 'ubuntu' && tag == '12.04' } do
  it { should_not exist }
end

where

  • .where() may specify a specific item and value, to which the matchers are compared
  • commands, ids, images, labels, local_volumes, mounts, names, networks, ports, sizes and 'status' are valid matchers for containers


Examples

The following examples show how to use this InSpec audit resource.

Return all running containers

docker.containers.running?.ids.each do |id|
  describe docker.object(id) do
    its('State.Health.Status') { should eq 'healthy' }
  end
end

Verify a Docker Server and Client version

describe docker.version do
  its('Server.Version') { should cmp >= '1.12'}
  its('Client.Version') { should cmp >= '1.12'}
end

Iterate over all containers to verify host coniguration

docker.containers.ids.each do |id|
  # call docker inspect for a specific container id
  describe docker.object(id) do
    its(%w(HostConfig Privileged)) { should cmp false }
    its(%w(HostConfig Privileged)) { should_not cmp true }
  end
end

Iterate over all images to verify the container was built without ADD instruction

docker.images.ids.each do |id|
  describe command("docker history #{id}| grep 'ADD'") do
    its('stdout') { should eq '' }
  end
end

Verify that health-checks are enabled for a container

describe docker.object('71b5df59442b') do
  its(%w(Config Healthcheck)) { should_not eq nil }
end

Run the DevSec docker baseline profile

There are two ways to run the docker-baseline profile to test Docker via the docker resource.

Clone the profile:

$ git clone https://github.com/dev-sec/cis-docker-benchmark.git

and then run:

$ inspec exec cis-docker-benchmark

Or execute the profile directly via URL:

$ inspec exec https://github.com/dev-sec/cis-docker-benchmark


Matchers

For a full list of available matchers, please visit our matchers page.

containers

containers returns information about containers as returned by docker ps -a. You can determine specific information about

describe docker.containers do
  its('ids') { should include 'sha:71b5df59...442b' }
  its('commands') { should_not include '/bin/sh' }
  its('images') { should_not include 'u12:latest' }
  its('ports') { should include '0.0.0.0:1234->1234/tcp' }
  its('labels') { should include 'License=GPLv2,Vendor=CentOS' }
end

images

images returns information about docker image as returned by docker images. You can determine specific information about

describe docker.images do
  its('ids') { should include 'sha:12b5df59...442b' }
  its('repositories') { should_not include 'my_image' }
  its('tags') { should_not include 'unwanted_tag' }
  its('sizes') { should_not include "1.41 GB" }
end

version

info returns the parsed result of docker version

describe docker.version do
  its('Server.Version') { should cmp >= '1.12'}
  its('Client.Version') { should cmp >= '1.12'}
end

info

info returns the parsed result of docker info

describe docker.info do
  its('Configuration.Path') { should eq 'value' }
end

object(‘id’)

object returns low-level information about docker objects. It is calling docker inspect under the hood.

describe docker.object(id) do
  its('Configuration.Path') { should eq 'value' }
end