diff --git a/README.md b/README.md index 5e34349f2cf9..e6169a699659 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,14 @@ A Simple and Comprehensive Vulnerability Scanner for Containers, Compatible with # Accuracy Comparison - +The number of vulnerabilities detected on Alpine Linux (as of 2019/05/12) + + +See [Comparison with other scanners](#comparison-with-other-scanners) for details. # TOC + - [Abstract](#abstract) - [Features](#features) - [Installation](#installation) @@ -24,9 +28,8 @@ A Simple and Comprehensive Vulnerability Scanner for Containers, Compatible with - [Binary (Including Windows)](#binary-including-windows) - [From source](#from-source) - [Quick Start](#quick-start) +- [Application Dependencies](#application-dependencies) - [Examples](#examples) - - [Basic Usage](#basic-usage) - - [Scan an image](#scan-an-image) - [Scan an image file](#scan-an-image-file) - [Save the results as JSON](#save-the-results-as-json) - [Filter the vulnerabilities by severities](#filter-the-vulnerabilities-by-severities) @@ -34,7 +37,8 @@ A Simple and Comprehensive Vulnerability Scanner for Containers, Compatible with - [Ignore unfixed vulnerabilities](#ignore-unfixed-vulnerabilities) - [Specify exit code](#specify-exit-code) - [Ignore the specified vulnerabilities](#ignore-the-specified-vulnerabilities) - - [Clean all caches](#clean-all-caches) + - [Clear image caches](#clear-image-caches) + - [Reset](#reset) - [Continuous Integration (CI)](#continuous-integration-ci) - [Travis CI](#travis-ci) - [Circle CI](#circle-ci) @@ -49,31 +53,31 @@ A Simple and Comprehensive Vulnerability Scanner for Containers, Compatible with - [Others](#others) # Abstract -`Trivy` is a simple and comprehensive vulnerability scanner for containers. + +`Trivy` (`tri` pronounced like trigger, `vy` pronounced like bee) is a simple and comprehensive vulnerability scanner for containers. `Trivy` detects vulnerabilities of OS packages (Alpine, RHEL, CentOS, etc.) and application dependencies (Bundler, Composer, npm, etc.). `Trivy` is easy to use. Just install the binary and you're ready to scan. All you need to do for scanning is to specify a container image name. It is considered to be used in CI. Before pushing to a container registry, you can scan your local container image easily. See [here](#continuous-integration-ci) for details. - # Features + - Detect comprehensive vulnerabilities - - OS packages (Alpine, Red Hat Enterprise Linux, CentOS, Debian, Ubuntu) - - **Application dependencies** (Bundler, Composer, Pipenv, npm, Cargo) + - OS packages (Alpine, Red Hat Enterprise Linux, CentOS, Debian and Ubuntu) + - **Application dependencies** (Bundler, Composer, Pipenv, npm and Cargo) - Simple - Specify only an image name - Easy installation - **No need for prerequirements** such as installation of DB, libraries, etc. - `apt-get install`, `yum install` and `brew install` is possible (See [Installation](#installation)) - High accuracy - - **Especially Alpine** (See [Comparison with other scanners](#comparison-with-other-scanners)) + - **Especially Alpine Linux and RHEL/CentOS** (See [Comparison with other scanners](#comparison-with-other-scanners)) - Other OSes are also high - Continuous Integration - **Compatible with CI** such as Travis CI, CircleCI, Jenkins, etc. - See [CI Example](#continuous-integration-ci) - # Installation ## RHEL/CentOS @@ -94,7 +98,7 @@ $ sudo yum -y install trivy or ``` -$ rpm -ivh https://github.com/knqyf263/trivy/releases/download/v0.0.11/trivy_0.0.11_Linux-64bit.rpm +$ rpm -ivh https://github.com/knqyf263/trivy/releases/download/v0.0.12/trivy_0.0.12_Linux-64bit.rpm ``` ## Debian/Ubuntu @@ -115,18 +119,21 @@ or ``` $ sudo apt-get install rpm -$ wget https://github.com/knqyf263/trivy/releases/download/v0.0.11/trivy_0.0.11_Linux-64bit.deb -$ sudo dpkg -i trivy_0.0.11_Linux-64bit.deb +$ wget https://github.com/knqyf263/trivy/releases/download/v0.0.12/trivy_0.0.12_Linux-64bit.deb +$ sudo dpkg -i trivy_0.0.12_Linux-64bit.deb ``` ## Mac OS X / Homebrew + You can use homebrew on OS X. + ``` $ brew tap knqyf263/trivy $ brew install knqyf263/trivy/trivy ``` ## Binary (Including Windows) + Go to [the releases page](https://github.com/knqyf263/trivy/releases), find the version you want, and download the zip file. Unpack the zip file, and put the binary to somewhere you want (on UNIX-y systems, /usr/local/bin or the like). Make sure it has execution bits turned on. You need to install `rpm` command for scanning RHEL/CentOS. @@ -139,13 +146,28 @@ $ go get -u github.com/knqyf263/trivy # Quick Start -Simply specify an image name (and a tag). **The `latest` tag should be avoided as problems occur with cache.** +Simply specify an image name (and a tag). **The `latest` tag should be avoided as problems occur with cache.**. See [Clear image caches](#clear-image-caches) ``` $ trivy nginx:1.16.0-alpine ``` +# Application Dependencies + +`Trivy` automatically detects the following files in the container and scans vulnerabilities in the application dependencies. + +- Gemfile.lock +- Pipfile.lock +- composer.lock +- package-lock.json +- Cargo.lock + +The path of these files does not matter. + +Example: https://npm.pkg.github.com/knqyf263/trivy-ci-test/blob/master/Dockerfile + # Examples + ### Scan an image file ``` @@ -165,7 +187,8 @@ $ trivy -f json -o results.json composer:1.7.2 $ trivy --severity HIGH,CRITICAL python:3.7-alpine3.9 ``` -### Skip an update of vulnerability DB +### Skip an update of vulnerability DB + `Trivy` updates vulnerability database every time it is run. This is usually fast as it is a difference update. But if you want to skip even that, use the `--skip-update` option. ``` @@ -173,15 +196,16 @@ $ trivy --skip-update alpine:3.9 ``` ### Ignore unfixed vulnerabilities + By default, `Trivy` also detects unpatched/unfixed vulnerabilities. This means you can't fix these vulnerabilities even if you update all packages. If you would like to ignore them, use the `--ignore-unfixed` option. - ``` $ trivy --exit-code 1 httpd:2.4.39 ``` ### Specify exit code + By default, `Trivy` exits with code 0 even when vulnerabilities are detected. Use the `--exit-code` option if you want to exit with a non-zero exit code. @@ -197,6 +221,7 @@ $ trivy --exit-code 1 --severity CRITICAL httpd:2.4.39 ``` ### Ignore the specified vulnerabilities + Use `.trivyignore`. ``` @@ -207,44 +232,58 @@ CVE-2018-14618 # No impact in our settings CVE-2019-3855 -$ trivy composer:1.7.2 +$ trivy composer:1.7.2 ``` -### Clean all caches -The `--clean` option remove all caches. After this, it takes a long time as the vulnerability database needs to be rebuilt locally. +### Clear image caches + +The `--clear-cache` option removes image caches. This option is useful if the image which has the same tag is updated (such as when using `latest` tag). ``` -$ trivy --clean +$ trivy --clear-cache redis:5.0.4 ``` +### Reset + +The `--reset` option removes all caches and database. After this, it takes a long time as the vulnerability database needs to be rebuilt locally. + +``` +$ trivy --reset +``` + +# Continuous Integration (CI) -## Continuous Integration (CI) Scan your image built in Travis CI/CircleCI. The test will fail if a vulnerability is found. When you don't want to fail the test, specify `--exit-code 0` . **Note**: The first time take a while (faster by cache after the second time) -### Travis CI + +## Travis CI ``` $ cat .travis.yml services: - docker +env: + global: + - COMMIT=${TRAVIS_COMMIT::8} + before_install: - - docker build -t trivy-ci-test:latest . - - wget https://github.com/knqyf263/trivy/releases/download/v0.0.11/trivy_0.0.11_Linux-64bit.tar.gz - - tar zxvf trivy_0.0.11_Linux-64bit.tar.gz + - docker build -t trivy-ci-test:${COMMIT}. + - wget https://github.com/knqyf263/trivy/releases/download/v0.0.12/trivy_0.0.12_Linux-64bit.tar.gz + - tar zxvf trivy_0.0.12_Linux-64bit.tar.gz script: - - ./trivy --exit-code 0 --severity HIGH --quiet trivy-ci-test:latest - - ./trivy --exit-code 1 --severity CRITICAL --quiet trivy-ci-test:latest + - ./trivy -c --exit-code 0 --severity HIGH --quiet trivy-ci-test:latest + - ./trivy -c --exit-code 1 --severity CRITICAL --quiet trivy-ci-test:${COMMIT} cache: directories: - $HOME/.cache/trivy ``` -example: https://travis-ci.org/knqyf263/trivy-ci-test -repository: https://github.com/knqyf263/trivy-ci-test +Example: https://travis-ci.org/knqyf263/trivy-ci-test +Repository: https://github.com/knqyf263/trivy-ci-test -### Circle CI +## Circle CI ``` $ cat .circleci/config.yml @@ -259,16 +298,16 @@ jobs: key: vulnerability-db - run: name: Build image - command: docker build -t trivy-ci-test:latest . + command: docker build -t trivy-ci-test:${CIRCLE_SHA1} . - run: name: Install trivy command: | - wget https://github.com/knqyf263/trivy/releases/download/v0.0.11/trivy_0.0.11_Linux-64bit.tar.gz - tar zxvf trivy_0.0.11_Linux-64bit.tar.gz + wget https://github.com/knqyf263/trivy/releases/download/v0.0.12/trivy_0.0.12_Linux-64bit.tar.gz + tar zxvf trivy_0.0.12_Linux-64bit.tar.gz mv trivy /usr/local/bin - run: name: Scan the local image with trivy - command: trivy --exit-code 1 --quiet trivy-ci-test:latest + command: trivy --clear-cache --exit-code 1 --quiet trivy-ci-test:${CIRCLE_SHA1} - save_cache: key: vulnerability-db paths: @@ -280,8 +319,8 @@ workflows: - build ``` -example: https://circleci.com/gh/knqyf263/trivy-ci-test -repository: https://github.com/knqyf263/trivy-ci-test +Example: https://circleci.com/gh/knqyf263/trivy-ci-test +Repository: https://github.com/knqyf263/trivy-ci-test # Usage @@ -291,7 +330,7 @@ NAME: USAGE: trivy [options] image_name VERSION: - 0.0.11 + 0.0.12 OPTIONS: --format value, -f value format (table, json) (default: "table") --input value, -i value input file path instead of image name @@ -299,37 +338,62 @@ OPTIONS: --output value, -o value output file name --exit-code value Exit code when vulnerabilities were found (default: 0) --skip-update skip db update - --clean, -c clean all cache + --reset remove all caches and database + --clear-cache, -c clear image caches --quiet, -q suppress progress bar --ignore-unfixed display only fixed vulnerabilities - --refresh refresh DB (usually used after version update of trivy + --refresh refresh DB (usually used after version update of trivy) --debug, -d debug mode --help, -h show help --version, -v print the version ``` # Comparison with other scanners + ## Overview -The following table shows a result of scanning `composer:1.7.2` (selected randomly). -In this case, the union of vulnerabilities detected by all vulnerability scanners is used as a data set. -Of course, there may be vulnerabilities that all scanners could not detect. + +The following bar charts show the results of scanning `composer:1.7.2` and `crate:3.2.2` by container scanners. These images were selected randomly. + +Scanners: [Clair](https://github.com/coreos/clair), [Quay](https://quay.io/), [MicroScanner(Free)](https://github.com/aquasecurity/microscanner), [Docker Hub](https://hub.docker.com/), [Anchore Engine](https://anchore.com/engine/) See [spreadsheet](https://docs.google.com/spreadsheets/d/16uj9vGh2PHMcVwb_D4h0nYUSvzCAxcnUz9UgQaDCYs4/edit#gid=0) for details. -Date: 2019/05/12 +In this case, the union of vulnerabilities detected by all vulnerability scanners is used as a data set. + +**NOTE** + +- There may be vulnerabilities that all scanners could not detect. +- There may be a mistake because I have confirmed the correctness manually. + +### Alpine Linux + +The results of `composer:1.7.2` using Alpine Linux 3.7.1 (as of 2019/05/12). + + + +`Trivy` has high accuracy and high precision, while GCR did not detect any vulnerability. Althogh Docker Hub has many True Positive, it also has many False Positive. + +### RHEL/CentOS + +The results of `crate:3.2.2` using CentOS 7.6.1810. (as of 2019/05/14). + +The following chart includes only fixable vulnerabilities. + + + +Many vulnerability scanners only detect patched/fixable vulnerabilities on RHEL/CentOS, but Trivy also detects unpatched/unfixable vulnerabilities. -| Scanner | Clair | Quay | MircoScanner | Docker Hub | Anchore Engine | Trivy | -|-----------|-------|------|--------------|------------|---------------|-------| -| Accuracy | 75% | 75% | 66% | 22% | 74% | **85%** | -| Precision | 100% | 100% | 89% | 26% | 100% | **100%** | +The below is the graph including unfixable vulnerabilities. -Reference: [Clair](https://github.com/coreos/clair), [Quay](https://quay.io/), [MicroScanner(Free)](https://github.com/aquasecurity/microscanner), [Docker Hub](https://hub.docker.com/), [Anchore Engine](https://anchore.com/engine/) + + +### Other OS -`Trivy` has high accuracy and high precision, especially in the case of Alpine Linux. In the case of other OS, the result is similar to other container scanners. -## vs Clair, Quay -[Clair](https://github.com/coreos/clair) and [Quay](https://quay.io/) uses [alpine-secdb](https://github.com/alpinelinux/alpine-secdb/). +## vs Clair + +[Clair](https://github.com/coreos/clair) uses [alpine-secdb](https://github.com/alpinelinux/alpine-secdb/). However, the purpose of this database is to make it possible to know what packages has backported fixes. As README says, it is not a complete database of all security issues in Alpine. @@ -355,17 +419,23 @@ RUN apk add --no-cache sqlite-dev \ Finally, `Trivy` can also detect vulnerabilities in application dependent libraries such as Bundler, Composer, Pipenv, etc. ## vs Anchore Engine -Similar to Clair, there is a difference in detection accuracy on Alpine Linux. Also, Anchore Engine needs some steps to start scanning. + +Similar to Clair, there is a difference in detection accuracy on Alpine Linux. +Then, as noted above, `Anchore Engine` does not detect unfixable vulnerabilities on RHEL/CentOS, whereas `Trivy` does. + +Also, `Anchore Engine` needs some steps to start scanning. `Trivy` is much easier to use. -## vs Docker Hub, GCR -Docker Hub can scan only official images. GCR hardly detects vulnerability on Alpine Linux. Also, it is locked to a specific registry. +## vs Quay, Docker Hub, GCR -`Trivy` does not depend on the registry. In addition, it is easy to be integrated with CI/CD services. +As `Quay` seems to use `Clair` internally, it has the same accuracy with `Clair`. `Docker Hub` can scan only official images. `GCR` hardly detects vulnerability on Alpine Linux. Also, it is locked to a specific registry. +`Trivy` does not depend on the registry. In addition, it is easy to be integrated with CI/CD services. # Q&A + ## Homebrew + ### Error: Your macOS keychain GitHub credentials do not have sufficient scope! ``` @@ -379,6 +449,7 @@ echo 'export HOMEBREW_GITHUB_API_TOKEN=your_token_here' >> ~/.zshrc ``` Try: + ``` $ printf "protocol=https\nhost=github.com\n" | git credential-osxkeychain erase ``` @@ -400,7 +471,9 @@ $ brew install knqyf263/trivy/trivy ``` ## Others + ### Detected version update of trivy. Please try again with --refresh option + Try again with `--refresh` option ``` @@ -408,6 +481,7 @@ $ trivy --refresh alpine:3.9 ``` ### Unknown error + Try again with `--clean` option ``` @@ -425,13 +499,17 @@ $ trivy --clean - see [GitHub and Go: forking, pull requests, and go-getting](http://blog.campoy.cat/2014/03/github-and-go-forking-pull-requests-and.html) ----- +--- # Credits -Special thanks to [Tomoya Amachi](https://github.com/tomoyamachi) + +- Special thanks to [Tomoya Amachi](https://github.com/tomoyamachi) +- Special thanks to [Masahiro Fujimura](https://github.com/masahiro331) # License + MIT # Author + Teppei Fukuda (knqyf263) diff --git a/imgs/alpine.png b/imgs/alpine.png new file mode 100644 index 000000000000..71d23578c0ad Binary files /dev/null and b/imgs/alpine.png differ diff --git a/imgs/alpine_comparison.png b/imgs/alpine_comparison.png deleted file mode 100644 index 277f33819aca..000000000000 Binary files a/imgs/alpine_comparison.png and /dev/null differ diff --git a/imgs/centos_include_unfixable.png b/imgs/centos_include_unfixable.png new file mode 100644 index 000000000000..d9c2b65d9077 Binary files /dev/null and b/imgs/centos_include_unfixable.png differ diff --git a/imgs/centos_only_fixable.png b/imgs/centos_only_fixable.png new file mode 100644 index 000000000000..c5f8ec994b61 Binary files /dev/null and b/imgs/centos_only_fixable.png differ