Kiri Developers

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
Kiri
DockerContainersComposeImagesKiriSharePluginsSettingsPlugins Scans · 6

Images

NameSize Trivy
nginx:1.27192 MB2 critical
postgres:16438 MB1 high
shop-api:dev121 MBclean
redis:7.4117 MBnot scanned
Kiri 1.0.0Terminal1 shared 2 criticalVM running4 of 4 runningFeedback
Images with Trivy installed. The Trivy column shows each image's worst findings, and the Scans page under the Plugins heading counts the six images that have any. The note in the status bar adds up the critical ones.

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:

zsh
$ 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 needed

It 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.

Kiri

Images

nginx:1.27192 MB · 3 weeks ago2 critical
RunPullScan with ›
Remove
Grype Trivy
The menu of nginx:1.27, with Scan with › open. Grype comes with Kiri and is first; Trivy adds itself after it, with its mark.

What happens, in order:

  1. Kiri lists the packages in the image, the same CycloneDX list Save SBOM saves. The image’s files stay where they are.
  2. 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.
  3. The plugin runs trivy sbom on 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.
  4. 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.
  5. The container stops.
A scan with the Trivy pluginKiringinx:1.27files stay herepackage list (CycloneDX)Security tabScanned with Trivyscan-trivy, its own containertrivy sbommatches packagesits cache: the databasekept between scansmirror.gcr.ioTrivy’s databaselistfindingsfetch
What crosses each line during a scan. Kiri hands the plugin a package list, never the image. The plugin's only website is Trivy's database. Findings come back to Kiri, which draws them in its own Security tab.

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.

zsh
$ 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 --all

The 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 critical in red, 1 high in yellow, clean in 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.
Kiri
DockerContainersImagesKiriPluginsSettingsPlugins Scans · 6

Scans

ImageCriticalHighWith a fixScanned
nginx:1.272592 min ago⋯
postgres:160111 h ago⋯
node:22003today⋯
The Scans page. Kiri draws the table from rows the plugin sent; the ⋯ on each row runs the plugin's own actions. The IDs behind these numbers are examples.

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.

zsh
$ 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)
  7b1e04c9a2f8

The 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