EXAMPLES
Example: an image scanner
Kiri comes with one scanner, Grype, on every image’s Security tab. Some security teams already trust another one, and want the same findings on every laptop that they see in CI. The Trivy scanner, scan-trivy, is that second scanner. Kiri makes it and lists it in the marketplace. This page follows it from install to a blocked run, and shows the code and permissions behind each place.
What it adds
A scanner joins Kiri’s own Scan with › and Security tab, and can add a few places of its own to show what it found:
| Place | What Trivy puts there |
|---|---|
| F Scan with › | Trivy, after Grype, in an image’s menu and on its Security tab |
| Kiri’s Security tab | Each Trivy scan, marked Scanned with Trivy, in Kiri’s own table |
| H A column in Images | Trivy: 2 critical, 1 high or clean |
| D A page in the sidebar | Scans: every image with known vulnerabilities |
| A A status note | 2 critical in red while any of your images has one |
| K A check before run | A warn, or a block if you choose, when an image has a critical finding |
| G Settings | Under Plugins in Settings: warn or block, and whether to scan new pulls |
Images
Install it
Find Trivy scanner in the Plugins view’s Marketplace tab, or install it from a terminal. The prompt lists every place it shows and everything it may see and reach:
$ kiri plugin install scan-trivy
Trivy scanner 0.9.2 by Kiri ✓ · free · fits Kiri 1.0 and later
Finds known vulnerabilities in your images, with Trivy.
Signed by Kiri ✓ · sha256:4be1…c09a
Where it shows:
• Be a scanner: Trivy, in Scan with ›. See the packages in an image you scan
• Check before run and answer allow, warn or block
• Add a column to: Images
• Add a page to the sidebar: Scans
• Show a note in the status bar
What it may see and reach:
• See your images and the packages inside them (not their files)
• Hear when: an image is pulled
• Reach these websites: mirror.gcr.io
It runs trivy in a container of its own, only while it scans.
It can't see your files, the Docker socket or your other plugins.
Install? [y/N] y
✓ signature matches · installed in 1.6 s · no restart neededIt needs nothing set up. The one website it may reach, mirror.gcr.io, is where Trivy gets its database of known vulnerabilities. The first scan fetches it, which takes a minute on a typical connection; after that, the plugin keeps it between scans and fetches a new one when Trivy says it’s out of date.
Scan an image
Choose Scan with › Trivy in an image’s menu, or on its Security tab. In a terminal, kiri scan nginx:1.27 --with trivy. With Scan images when they’re pulled on, which it is unless you switch it off, every image you pull is scanned once it lands.
Images
What happens, in order:
- Kiri lists the packages in the image, the same CycloneDX list Save SBOM saves. The image’s files stay where they are.
- Kiri starts the plugin’s container and hands it the list. The container has no network but its own, and no website but
mirror.gcr.io. - The plugin runs
trivy sbomon the list, against the database it keeps, and turns Trivy’s report into findings: an ID, the package, its version, the severity, the version that fixes it and a title. - Kiri draws the findings on the image’s Security tab, marked Scanned with Trivy. The plugin keeps a short summary in its store, for its column, its page, its note and its check.
- The container stops.
The Security tab keeps the last 20 scans, whichever scanner made them, so you can put Grype’s scan of an image beside Trivy’s. They often differ a little: each matches the same packages against its own database. Scan again uses the scanner of the last scan.
$ kiri scan nginx:1.27 --with trivy
nginx:1.27 · scanned with Trivy · 143 packages
2 critical, 5 high, 5 medium · 9 have a fix
CRITICAL CVE-2026-0001 (example) openssl 3.3.1 → 3.3.3
CRITICAL CVE-2026-0002 (example) libxml2 2.12.6 → 2.12.9
… 10 more: kiri scan nginx:1.27 --with trivy --allThe column, the page and the note
The plugin’s three places all read the same summary from its store, so they agree:
- The Trivy column in Images shows each image’s worst news:
2 criticalin red,1 highin yellow,cleanin green, or nothing for an image not scanned yet. It sorts like Kiri’s own columns, worst first. - The Scans page lists every image with known vulnerabilities: critical, high, how many have a fix, and when it was scanned. The ⋯ on a row has Scan again and Open image, which opens the image’s Security tab.
- The note in the status bar adds up the critical findings across your images. A click opens its panel: one line per image, and Open Scans. With none, the note leaves the bar.
Scans
Warn or block a run
Trivy checks every container before it starts, from the window, docker run, Compose or a CI job. It looks up the image’s last scan, or scans it now if there’s none, and answers:
- No critical finding: allow, and nothing shows.
- A critical finding: a warn, unless you set When an image has a critical finding to Block in Trivy’s settings.
A warn lets the container start and shows the reason: on the step in the window, and as one of Docker’s own warnings in a terminal. A block stops it, with the reason, and Run anyway in the window or --anyway on kiri run goes ahead once. Every override goes in the activity record.
$ docker run -d nginx:1.27
WARNING: scan-trivy: nginx:1.27 has 2 critical vulnerabilities, both with a fix. See its Security tab in Kiri.
3f2a9c1b7d4e
$ docker run -d nginx:1.27
docker: Error response from daemon: scan-trivy blocked this run: nginx:1.27 has 2 critical vulnerabilities, both with a fix.
$ kiri run -d nginx:1.27 --anyway
! scan-trivy blocked this run; going ahead because you said --anyway (recorded)
7b1e04c9a2f8The check has 10 seconds to answer. A scan with the database in place takes a second or two; the very first one, while the database downloads, can take longer. A check that doesn’t answer in time counts as a warn. Your company can make it count as a block instead, for a plugin it requires.
Inside the plugin
Trivy is a program, so the plugin runs in a container: Trivy and a few lines of code that turn its report into findings. Here is its kiri-plugin.toml:
name = "scan-trivy"
version = "0.9.2"
publisher = "kiri"
description = "Finds known vulnerabilities in your images, with Trivy."
api = "1"
price = "free"
mark = { icon = "trivy.svg", colour = "#1904DA" }
[run]
image = "Dockerfile" # trivy and the plugin's code, pinned by hash at install
memory = "512MB"
cache = "1GB" # Trivy's database, kept between scans
[adds]
scan = [{ name = "trivy", label = "Trivy" }]
checks = [{ on = "before-run", timeout = "10s" }]
[window]
status = true
columns = [{ on = "images", label = "Trivy" }]
page = { label = "Scans" }
[needs]
images = "packages"
events = ["image.pulled"]
sites = ["mirror.gcr.io"]
[[settings]]
key = "on_critical"
label = "When an image has a critical finding"
type = "choice"
choices = ["Warn", "Block"]
default = "Warn"
[[settings]]
key = "scan_pulls"
label = "Scan images when they're pulled"
type = "switch"
default = true
A container plugin’s scratch folder is emptied each time it stops, which suits most plugins. A scanner’s database is hundreds of megabytes, so cache asks for a folder that’s kept between runs, shown on the plugin’s Overview tab and deleted only when you remove the plugin.
The scan and the check, nearly whole. scan.packages is the CycloneDX list from Kiri:
import { execFile } from "node:child_process";
import { writeFile } from "node:fs/promises";
import { promisify } from "node:util";
import { plugin } from "@kiri/sdk";
const run = promisify(execFile);
const CACHE = process.env.KIRI_CACHE; // the folder kept between runs
plugin.scan("trivy", async (scan, kiri) => {
await writeFile("/tmp/packages.json", JSON.stringify(scan.packages));
const { stdout } = await run("trivy", ["sbom", "--quiet", "--format", "json",
"--cache-dir", CACHE, "/tmp/packages.json"]);
const findings = (JSON.parse(stdout).Results ?? []).flatMap((r) => r.Vulnerabilities ?? []).map((v) => ({
id: v.VulnerabilityID, package: v.PkgName, version: v.InstalledVersion,
severity: v.Severity.toLowerCase(), fixed: v.FixedVersion ?? null, title: v.Title ?? "",
}));
await remember(kiri, scan.digest, findings); // the summary the column, page, note and check read
return findings;
});
plugin.check("before-run", async (ev, kiri) => {
const image = await kiri.images.get(ev.image); // the name as asked → its digest
const s = (await kiri.store.get(`scan:${image.digest}`)) ?? (await scanNow(kiri, image));
if (!s.critical) return plugin.allow();
const reason = `${ev.image} has ${s.critical} critical vulnerabilities, ${s.fixable} with a fix.`;
return (await kiri.settings.get("on_critical")) === "Block" ? plugin.block(reason) : plugin.warn(reason);
});
plugin.on("image.pulled", async (ev, kiri) => {
if (await kiri.settings.get("scan_pulls")) await scanNow(kiri, await kiri.images.get(ev.image));
});
scanNow asks Kiri for the image’s packages with kiri.images.packages and runs the same scan. remember writes the summary to the store, sets or clears the note with kiri.status.set, and calls kiri.refresh("column") and kiri.refresh("page") so the window redraws. The column’s code is on Tabs, pages and columns.
© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com