Integration of Clair and Docker Registry (supports both Clair API v1 and v3)
Klar is a simple tool to analyze images stored in a private or public Docker registry for security vulnerabilities using Clair https://github.com/coreos/clair. Klar is designed to be used as an integration tool so it relies on enviroment variables. It's a single binary which requires no dependencies.
Klar serves as a client which coordinates the image checks between the Docker registry and Clair.
The simplest way is to download the latest release (for OSX and Linux) from https://github.com/optiopay/klar/releases/ and put the binary in a folder in your PATH (make sure it has execute permission).
Make sure you have Go language compiler installed and configured https://golang.org/doc/install
Then run
go get github.com/optiopay/klar
make sure your Go binary folder is in your PATH (e.g. export PATH=$PATH:/usr/local/go/bin)
Klar process returns 0 if the number of detected high severity vulnerabilities in an image is less than or equal to a threshold (see below), otherwise it returns 1.
Klar can be configured via the following environment variables:
-
CLAIR_ADDR- address of Clair server. The most complete form isprotocol://host:port-protocolandportdefault tohttpand6060respectfully and may be omitted. -
CLAIR_OUTPUT- severity level threshold, vulnerabilities with severity level higher than or equal to this threshold will be outputted. Supported levels areUnknown,Negligible,Low,Medium,High,Critical,Defcon1. Default isUnknown. -
CLAIR_THRESHOLD- how many outputted vulnerabilities Klar can tolerate before returning1. Default is0. -
CLAIR_TIMEOUT- timeout in minutes before Klar cancels the image scanning. Default is1 -
DOCKER_USER- Docker registry account name. -
DOCKER_PASSWORD- Docker registry account password. -
DOCKER_TOKEN- Docker registry account token. (Can be used in place ofDOCKER_USERandDOCKER_PASSWORD) -
DOCKER_INSECURE- Allow Klar to access registries with bad SSL certificates. Default isfalse. Clair will need to be booted with-insecure-tlsfor this to work. -
DOCKER_TIMEOUT- timeout in minutes when trying to fetch layers from a docker registry -
REGISTRY_INSECURE- Allow Klar to access insecure registries (HTTP only). Default isfalse. -
JSON_OUTPUT- Output JSON, not plain text. Default isfalse. -
WHITELIST_FILE- Path to the YAML file with the CVE whitelist. Look atwhitelist-example.yamlfor the file format.
Usage:
CLAIR_ADDR=localhost CLAIR_OUTPUT=High CLAIR_THRESHOLD=10 DOCKER_USER=docker DOCKER_PASSWORD=secret klar postgres:9.5.1
You can enable more verbose output but setting KLAR_TRACE to true.
- run
export KLAR_TRACE=trueto persist between runs.
Klar can be dockerized. Go to $GOPATH/src/github.com/optiopay/klar and build Klar in project root. If you are on Linux:
CGO_ENABLED=0 go build -a -installsuffix cgo .
If you are on Mac don't forget to build it for Linux:
GOOS=linux go build .
To build Docker image run in the project root (replace klar with fully qualified name if you like):
docker build -t klar .
Then pass env vars as separate --env arguments, or create an env file and pass it as --env-file argument. For example save env vars as my-klar.env:
CLAIR_ADDR=localhost
CLAIR_OUTPUT=High
CLAIR_THRESHOLD=10
DOCKER_USER=docker
DOCKER_PASSWORD=secret
Then run
docker run --env-file=my-klar.env klar postgres:9.5.1
There is no permanent username/password for Amazon ECR, the credentials must be retrived using aws ecr get-login and they are valid for 12 hours. Here is a sample script which may be used to provide Klar with ECR credentials:
DOCKER_LOGIN=`aws ecr get-login --no-include-email`
PASSWORD=`echo $DOCKER_LOGIN | cut -d' ' -f6`
REGISTRY=`echo $DOCKER_LOGIN | cut -d' ' -f9 | sed "s/https:\/\///"`
DOCKER_USER=AWS DOCKER_PASSWORD=${PASSWORD} ./klar ${REGISTRY}/my-image
For authentication against GCR (Google Cloud Registry), the easiest way is to use the application default credentials. Thes 8334 e only work when running Klar from GCP. The only requirement is the Google Cloud SDK.
DOCKER_USER=oauth2accesstoken
DOCKER_PASSWORD="$(gcloud auth application-default print-access-token)"
With Docker:
DOCKER_USER=oauth2accesstoken
DOCKER_PASSWORD="$(docker run --rm google/cloud-sdk:alpine gcloud auth application-default print-access-token)"