A Docker image is a set of layers containing an operating system, libraries and your application, and any of them may include packages with known vulnerabilities. Trivy matches the contents of an image against a vulnerability database and shows which packages are affected and in which version the problem is fixed. Below: installation, running a scan, reading the report and adding the check to your build.
What Trivy checks
Trivy can analyze container images, project directories, configuration files and repositories. It detects operating system packages and application dependencies: npm, Composer, pip and others. It is important to know the boundary: the scanner finds only vulnerabilities that have already been published, and it will not show flaws in your own code or unknown holes.
| Mode | Command | What is checked |
|---|---|---|
| Image | trivy image | OS packages and dependencies inside the image |
| Filesystem | trivy fs | Project directory, lock files, secrets |
| Configuration | trivy config | Dockerfile, Compose, manifests |
Installation
You can install Trivy as a package from the project repository (instructions for your distribution are in the Trivy documentation) or run it straight from a container without installing anything on the server. In the second case the Docker socket is passed inside so that the scanner can see local images. On the first run it downloads the vulnerability database and keeps it in a cache, so the first run is slower than the following ones.
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock aquasec/trivy image nginx:latest
trivy --versionScanning an image and a filesystem
For an image it is enough to give its name. Without filters the report is long, so in practice you limit the severity level and hide vulnerabilities that have no fix yet: you cannot do anything about them anyway. The result can be saved as JSON for further processing.
trivy image myapp:1
trivy image --severity HIGH,CRITICAL myapp:1
trivy image --severity HIGH,CRITICAL --ignore-unfixed myapp:1
trivy image --format json -o result.json myapp:1For a project on disk use the fs mode: it reads dependency files and finds problematic library versions before the image is even built. The config mode checks Dockerfiles and manifests for insecure settings.
trivy fs .
trivy fs --scanners vuln,secret,misconfig .
trivy config .How to read the report
The report table lists the package, the CVE identifier, the installed version, the fixed version and the severity. The severity levels are UNKNOWN, LOW, MEDIUM, HIGH and CRITICAL. An empty fixed-version field means the package vendor has not released a fix yet. Not every finding is reachable in your configuration: a package may be present in the image but never run. Decide on urgency after assessing real exposure to the network.
- Start with CRITICAL and HIGH findings that have a fix available.
- If there is no fix, check whether the package is used and remove it from the image when possible.
- Create a .trivyignore file for deliberate exceptions and write the reason in a comment.
- Review exceptions regularly: the situation and the vulnerability database change.
Ignore list and build integration
The .trivyignore file contains one identifier per line, and lines starting with a hash sign are comments. The identifiers in the example are placeholders, so use real ones from your own report. For automatic checks rely on the exit code: the --exit-code 1 option makes Trivy fail when vulnerabilities of the chosen severity are found, and the CI build stops.
# .trivyignore
# CVE-YYYY-NNNNN not reachable from the network, review later
CVE-YYYY-NNNNNdocker build --pull --no-cache -t myapp:2 .
trivy image --exit-code 1 --severity CRITICAL myapp:2
echo $?A vulnerability in the base image and rebuilding
Most findings are not in your code but in the base image from the FROM line: in OS packages and system libraries. You cannot fix them inside a running container, because an image is immutable. There is one cure: obtain an updated base image and rebuild your own. The --pull option makes Docker download the fresh version of the base image, and --no-cache prevents old layers from being reused. A concrete rebuild example is covered in PHP in Docker: closing PHP2Shell by rebuilding the image.
It is convenient to store scanned images and re-check them in your own registry, as described in a private Docker Registry on your own server. If you are just getting familiar with the concepts, start with Docker image and container: what is the difference.
Frequently asked questions
How is Trivy different from docker scan?
Trivy is a standalone open-source scanner that does not depend on a specific Docker version, checks images, directories and configurations, and fits easily into CI. It also suits servers without a graphical client: all you need is a command line and access to the vulnerability database when updating it.
Why does a fresh image still contain vulnerabilities?
The vulnerability database is updated daily, while an image captures the state of packages at build time. A new database entry can appear the very next day even if you changed nothing. That is why images should be scanned regularly rather than once before deployment.
Do I have to fix every vulnerability that is found?
No, begin with critical ones and those that already have a fix. Some entries concern packages that are never run or are unreachable from the network. It is reasonable to add such cases to .trivyignore with an explanation and review them later instead of ignoring them forever.
How do I fix a vulnerability in the base image?
Update the base image and rebuild your own: docker build with the --pull option downloads the fresh version, and --no-cache disables stale layers. Then repeat the scan and restart the containers from the new image. Updating packages inside an already running container is not preserved and does not replace a rebuild.