Tracking container vulnerabilities with Clair Control
Clairctl is a lightweight command-line tool doing the bridge between Registries as Docker Hub, Docker Registry or Quay.io, and the CoreOS vulnerability tracker, Clair. Clairctl will play as reverse proxy for authentication.
Clairctl version is align with the CoreOS Clair supported version.
Go to Release and download your corresponding version
curl -L https://raw.githubusercontent.com/ContinuousSecurityTooling/clairctl/master/install.sh | sh
$ git clone [email protected]:ContinuousSecurityTooling/clairctl.git $GOPATH/src/github.com/ContinuousSecurityTooling/clairctl
$ cd $GOPATH/src/github.com/ContinuousSecurityTooling/clairctl
$ docker-compose up -d postgres
Creating network "clairctl_default" with the default driver
Creating clairctl_postgres_1 ...
Creating clairctl_clair_1 ...
Creating clairctl_clairctl_1 ...
The above commands will check out the clairctl
repo and start the complete postgres/clair/clairctl stack.
$ docker-compose exec clairctl clairctl health
Clair: âś”
The above command will make sure clairctl can reach clair.
If you wish to serve local images to clair, the user inside the clairctl container will need read access to /var/run/docker.sock
.
Give the user access by:
- Running the container as root (
--user root
withdocker run
oruser: root
withdocker-compose
) - Add the container user to the docker group (
----group-add group_id
withdocker run
orgroup_add: group_id
withdocker-compose
)
To get the group name or id, simply execute :
$ docker-compose exec clairctl ls -alh /var/run/docker.sock
srw-rw---- 1 root 50 0 Jul 18 09:48 /var/run/docker.sock
In the example above, 50 is the required group.
clairctl get vulnerabilities report from Clair and generate HTML report
clairctl can be used for Docker Hub and self-hosted Registry
Analyze your docker image with Clair, directly from your registry.
Usage:
clairctl [command]
Available Commands:
analyze Analyze Docker image
health Get Health of clairctl and underlying services
pull Pull Docker image information (This will not pull the image !)
push Push Docker image to Clair
report Generate Docker Image vulnerabilities report
version Get Versions of clairctl and underlying services
Flags:
--config string config file (default is ./.clairctl.yml)
--log-level string log level [Panic,Fatal,Error,Warn,Info,Debug]
Use "clairctl [command] --help" for more information about a command.
clair:
port: 6060
healthPort: 6061
uri: http://clair
report:
path: ./reports
format: html
This is an example yaml file. You can have an empty file or a mix with only generalwhitelist
or images
.
generalwhitelist: #Approve CVE for any image
CVE-2016-2148: BusyBox
CVE-2014-8625: Why is it whitelisted
images:
ubuntu: #Approve CVE only for ubuntu image, regardless of the version
CVE-2014-2667: Python
CVE-2017-5230: Something
alpine:
CVE-2016-7068: Something
(Optional) If you choose to use your ~/.aws/credentials
file for configuration make the following changes.
Your ~/.aws/credentials
you wwill have to add a section for each ECR registry id
that you use.
For the below example the registry id
is 111111111111
Copy the ~/.aws/credentials
for [default]
settings to create settings for [111111111111]
E.G.:
[deafult]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY
[111111111111]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY
export AWS_SESSION_TOKEN=<token_value>
export AWS_ACCESS_KEY_ID=<key_value>
export AWS_SECRET_ACCESS_KEY=<secret_value>`
You can use the docker-compose.yml
file that you can use to help start the 3 containers needed up.
https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html
replace amazon-zone
with the zone for your ECR
export AWS_REGION=amazon-zone # e.g.: us-east-1 or eu-west-2
Uncomment the following entry in the clairctl:
environment:
of and add the value of your ECR region.
# - AWS_REGION= # put your region E.G.: us-east-1, eu-west-2
E.G:
- AWS_REGION=us-east-1 # put your region E.G.: us-east-1, eu-west-2
You will have to choose one of 3 options on passing the AWS secrets to the docker container.
Uncomment the one type you chose.
-
Use
AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
from environmental variables. -
Use
AWS_SESSION_TOKEN
from an environmental variable -
Use the mounting of the
.aws
directory from your home directory.
Start the 3 container
docker-compose up -d
docker-compose exec clairctl clairctl COMMAND AWS_ECR_URL/your-company-or-grouping/your-container:docker_version
E.G.:
docker-compose exec clairctl clairctl pull 111111111111.dkr.ecr.amazon-zone.amazonaws.com/your-company-or-grouping/your-container:docker_version
https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html
replace amazon-zone
with the zone for your ECR
export AWS_REGION=amazon-zone # e.g.: us-east-1 or eu-west-2
Link to setup your environment for ECR
./clairctl pull 111111111111.dkr.ecr.amazon-zone.amazonaws.com/your-company-or-grouping/your-container:docker_version
clairctl requires Go 1.8+.
Install Glide:
curl https://glide.sh/get | sh
Clone and build:
git clone [email protected]:ContinuousSecurityTooling/clairctl.git $GOPATH/src/github.com/ContinuousSecurityTooling/clairctl
cd $GOPATH/src/github.com/ContinuousSecurityTooling/clairctl
glide install -v
go get -u github.com/jteeuwen/go-bindata/...
go generate ./clair
go build
This will result in a clairctl
executable in the $GOPATH/src/github.com/ContinuousSecurityTooling/clairctl
folder.
If you are making modifications to the source code and want to test it locally there is another docker file LocalDockerfile
The project Dockerfile
downloads a zip file of the source from the project from github.
https://github.com/ContinuousSecurityTooling/clairctl/archive/master.zip
You will never see your local changes persisted into the container if you use docker build .
There is a script to help building from the source.
./local-docker.sh OPTIONAL_TAG_NAME
E.G.:
Build a tagged version
./local-docker.sh ContinuousSecurityTooling/clairctl:1.3.0
or
Build an untagged version for local development.
./local-docker.sh
Make sure to change the tag for clairctl in your local docker-compose.yml if you have built a different tagged version.
If you get 400 errors, check out clair's logs. The usual reasons are :
- You are serving a local image, and clair cannot connect to clairctl.
- You are trying to analyze an official image from docker hub and you have not done a docker login first.
Please try these two things before opening an Issue.
If you are running the stack with the provided docker-compose.yml
, don't forget to grant the user from the clairctl container access to /var/run/docker.sock
.
All steps are detailed in the Docker-compose section above.
Go to /contrib folder