WINDOW PLACES
Checks before pull, build and run
A check is a handler Kiri calls before it pulls an image, starts a build or creates a container. You answer allow, warn or block, with a reason. Kiri’s engine asks, so your check sees every request that reaches it: docker, Compose, Kiri’s window, kiri and CI jobs alike. A check needs no screen of its own: what it decides shows wherever the pull or the run already shows. What people see will be in the Kiri docs under Checks when 1.0 ships.
The three hooks
| Hook | Kiri calls you | The event has |
|---|---|---|
before-pull |
Before it pulls an image, including the base images a build pulls | image as it was asked for, platform, client |
before-build |
Before a build starts, whether from docker build, docker buildx build, docker compose build, kiri build or the window |
build.name (the tag) and build.base (the images the Dockerfile names), platform, client |
before-run |
Before it creates a container | image, run.name, run.ports, the folders it mounts, whether it asks for privileged mode, client |
client is docker, compose, window, kiri or api. A check never gets environment values, the files in a build’s context, or the files in an image. Kiri’s own pulls, such as the images its builder needs, skip checks, so a check can’t stop Kiri from working. Starting a container that already exists isn’t checked again, and in 1.0 the images Kubernetes pulls for pods aren’t checked.
Declare and answer
Name the hooks under [adds] checks. A check has 2 seconds to answer; one that needs longer, such as one that reads its own saved scans or asks a server, can ask for up to 10 with timeout:
[adds]
checks = [{ on = "before-pull" }, { on = "before-run", timeout = "5s" }]
The install prompt shows one line for them: Check before pull and run and answer allow, warn or block. Then register a handler per hook and answer with allow, warn or block:
import { plugin } from "@kiri/sdk";
plugin.check("before-pull", async (pull) => {
if (pinned(pull.image)) return plugin.allow();
return plugin.block(`${pull.image} has no fixed version. Name one, such as nginx:1.27-alpine.`);
});
plugin.check("before-run", async (run, kiri) => {
const scan = await kiri.store.get(`scan:${run.image}`);
if (scan?.critical) return plugin.warn(`${run.image} has ${scan.critical} critical vulnerabilities.`);
return plugin.allow();
});plugin.Check("before-pull", func(ev plugin.CheckEvent, k *plugin.Kiri) plugin.Verdict {
if pinned(ev.Image) {
return plugin.Allow("")
}
return plugin.Block(ev.Image + " has no fixed version. Name one, such as nginx:1.27-alpine.")
})
plugin.Check("before-run", func(ev plugin.CheckEvent, k *plugin.Kiri) plugin.Verdict {
if n := criticalFindings(k, ev.Image); n > 0 { // your own code, reading k.Store
return plugin.Warn(fmt.Sprintf("%s has %d critical vulnerabilities.", ev.Image, n))
}
return plugin.Allow("")
})plugin::check("before-pull", |ev, _kiri| async move {
if pinned(&ev.image) {
return plugin::allow("");
}
plugin::block(format!("{} has no fixed version. Name one, such as nginx:1.27-alpine.", ev.image))
});
plugin::check("before-run", |ev, kiri| async move {
match critical_findings(&kiri, &ev.image).await { // your own code, reading kiri.store()
n if n > 0 => plugin::warn(format!("{} has {} critical vulnerabilities.", ev.image, n)),
_ => plugin::allow(""),
}
});from kiri import plugin
@plugin.check("before-pull")
def no_latest(ev, kiri):
if pinned(ev.image):
return plugin.allow()
return plugin.block(f"{ev.image} has no fixed version. Name one, such as nginx:1.27-alpine.")A check runs like the rest of your plugin, in Kiri’s Linux side with the pass the person agreed to, so it’s the same on a Mac, on Windows and on Linux. It runs on every pull, so it should be quick: Rust and Go plugins start fastest, and a check that needs data should read it from its own store, filled earlier by an event, rather than fetch it while someone waits.
How the answers add up
Kiri asks every check for a step at once and waits for all of them, never longer than each one’s time. One block stops the request. Warns let it go ahead, and each reason is shown. A check that doesn’t answer in time counts as a warn, “your plugin didn’t answer in n s”, and so does a handler that throws.
Two things change what your block means, and neither is up to you:
- Going ahead anyway. A block from a check someone installed themselves can be overridden once, with Pull anyway in the window or
--anywayonkiri pull,kiri buildandkiri run. Every override goes in the activity record. - Company rules. A company that requires your plugin can make its silence count as a block, and its blocks can’t be overridden. So a required check that’s slow stops people’s work: answer well inside your time. See Company plugins.
Write a reason people can act on
A warn or a block needs a reason: one sentence, up to 200 characters, that says what’s wrong and what to do instead. Kiri shows it with your plugin’s name everywhere the request shows: a row in the window, the Run panel, and docker’s own output.
$ docker pull nginx
Using default tag: latest
Error response from daemon: no-latest blocked this pull: nginx has no fixed version. Name one, such as nginx:1.27-alpine.
$ docker run -d -p 8080:80 nginx:1.27
WARNING: Trivy: nginx:1.27 has 2 critical vulnerabilities. Both have a fix.
9c2f4e1b7a3d0e6fA block reaches docker as an error from the engine, and a warn as a warning in Docker’s own words: a WARNING: line from docker run, and a status line during docker pull. plugin.allow(reason) takes a reason too; it goes only in the activity record.
Test a check
kiri plugin test runs your check against requests you describe, with the same pass it gets when installed. A case’s job names the hook and the image; expect names the verdict and words the reason must contain:
# tests/no-latest.toml
[[case]]
name = "a registry port isn't a tag"
job = { check = "before-pull", image = "localhost:5000/app" }
expect = { verdict = "block", reason = "no fixed version" }
[[case]]
name = "a pinned tag goes through"
job = { check = "before-pull", image = "nginx:1.27-alpine" }
expect = { verdict = "allow" }
$ kiri plugin test
no-latest 1.0.0 · 2 cases
✓ a registry port isn't a tag
✓ a pinned tag goes through
2 passed in 0.2 sTest and publish has the whole test format, and Your first plugin builds no-latest from an empty folder.
© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com