Lesson 4 of 7 in Security basics for DevOps

Scanning images and dependencies for known flaws

Core12 min

A vulnerability scanner lists the packages inside an image or project, compares their versions against a database of publicly known flaws, and reports matches. Each known flaw has a CVE identifier and a severity rating, and most fixes are an upgrade.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Least privilege for people, jobs and containers

The problem this solves

You never write most of what runs in production. Your image contains an operating system's packages, a language runtime and dozens of libraries, and any of them can have a flaw that was published after you built the image. The same image that was clean last month can have findings today without a single change on your side.

You need an automatic way to ask, on every build, which of these known flaws are in what I am about to ship. A scanner answers that. The harder skill is reading the answer without panic: most findings are not equally urgent, and some cannot be fixed yet.

How it works

A scanner compares your packages against a flaw database
A scanner compares your packages against a flaw databaseThe scanner lists the packages in your image, compares their versions with a database of known flaws, writes a report, and the pipeline gate passes or fails on it.1 listpackages2 compare versions3 findings4 decideYour imageOS packages and libsScannerfor example TrivyFlaw databaseCVEs and fixed versionsReportid, severity, fixPipeline gatepass or fail
  • Data
  • Control
  • Other

The scanner lists the packages in your image, compares their versions with a database of known flaws, writes a report, and the pipeline gate passes or fails on it.

  1. Your image to Scanner: 1 list packages
  2. Flaw database to Scanner: 2 compare versions
  3. Scanner to Report: 3 findings
  4. Report to Pipeline gate: 4 decide
What to do with one finding
What to do with one findingYou read the row, then either update the base image when a fixed version exists or record why you accept the risk and review it later.1 read2a yes2b noA findingid, severity, versionsFix available?see FIXED VERSIONUpdate and rebuildnewer base or libraryRecord exceptionreason and review date
  • Other
  • Control
  • Runs code
  • Security

You read the row, then either update the base image when a fixed version exists or record why you accept the risk and review it later.

  1. A finding to Fix available?: 1 read
  2. Fix available? to Update and rebuild: 2a yes
  3. Fix available? to Record exception: 2b no

A CVE (Common Vulnerabilities and Exposures) is a public identifier for one known flaw, written like CVE-<year>-<number>. Severity is a rating of how bad the flaw could be, usually low, medium, high or critical. It describes the flaw in general, not how exposed your particular service is.

The scanner needs a database of known flaws and downloads it on first use, so the first run needs internet and takes longer. Trivy reports one row per match with the package, the CVE id, severity, the installed version and a fixed version when one exists.

Read the fixed version column first. If a fix exists, the usual remedy is to rebuild on a newer base image or bump the library. If none exists, you can often do nothing yet, and a good process records that decision with a reason and a date to look again.

A finding can also be a false positive or simply not reachable, for example a flaw in a tool your image ships but never runs. Judge that with evidence, not hope, and do not mute a whole class of findings to make the pipeline green.

Try it yourself

Install Trivy from its official documentation first. These commands pull public images and scan them locally. No account is needed, and they change nothing on your machine except cached downloads.

  1. 1
    Scan a small image
    trivy image --scanners vuln alpine:3.22

    The first run downloads the flaw database. Near the top you get a summary line with counts per severity, followed by a table if anything was found. A clean result simply prints a summary with zeros.

  2. 2
    Show only what you can act on
    trivy image --scanners vuln --severity HIGH,CRITICAL --ignore-unfixed alpine:3.22

    --severity filters the rows and --ignore-unfixed hides flaws that have no fixed version yet. Run the same command against debian:bookworm to compare how much an image brings along.

  3. 3
    Turn findings into a failing exit code
    trivy image --scanners vuln --severity CRITICAL --exit-code 1 debian:bookworm
    echo "exit code: $?"

    By default Trivy exits 0 even when it reports flaws, so a pipeline step would pass. With --exit-code 1 it exits 1 when it finds something that matches your filters, which is what a CI gate needs.

  4. 4
    Scan a project's dependencies
    cd <your-project-folder>
    trivy fs --scanners vuln .

    Run it in a project that has a lockfile such as package-lock.json or requirements.txt. Trivy reads the lockfile to find library versions without building anything.

What breaks, and where to look

  • The scan fails before printing any result, with a message such as failed to download vulnerability DB.

    WHY IT HAPPENS
    Trivy could not fetch its flaw database. Common reasons are no internet access, a proxy or firewall, or a download rate limit on the registry hosting the database.
    CHECK FIRST
    Run the same command again with --debug to see the URL it tried, then test that URL from the same network. In a restricted network, use the database mirror options described in the Trivy documentation.
  • The CI job scans the image, prints HIGH findings, and still passes.

    WHY IT HAPPENS
    Trivy exits 0 by default whether or not it finds flaws. Nothing tells the pipeline to stop.
    CHECK FIRST
    Add --exit-code 1 with the severities you want to block, then run it locally and read echo $? to confirm it fails.
  • A finding stays on the report after you changed the Dockerfile and rebuilt.

    WHY IT HAPPENS
    The rebuild reused a cached base layer or an older tag, so the vulnerable package is still inside. A tag such as latest is also a moving label that may not point to a newer image on your machine.
    CHECK FIRST
    Rebuild with docker build --pull --no-cache and rescan. Then confirm the package version in the report changed to the fixed one.

When not to use this

  • A scanner only knows flaws that are already published. A clean report does not mean the image is secure, and it says nothing about your own code or bad configuration.
  • Do not gate every build on every low severity finding. Choose a threshold your team will actually keep fixing, and raise it over time.

Check yourself

What is a CVE?

A public identifier for one specific known flaw in software, used so tools and people can refer to the same issue.

An image was clean last month and has findings today with no change. Why?

New flaws were published after you built it, and the scanner's database now knows about them.

What is the usual fix when the FIXED VERSION column has a value?

Update the package, typically by rebuilding on a newer base image or bumping the dependency, then rescan.

Lesson 89 of 92 in the DevOps path

Search

Search cheat sheets and projects