Skip to main content

​
Synopsis

Read-only views over the broker’s image inventory. The controller reports each container’s image identity; the broker keys it by digest, not tag, so two nodes that resolved nginx:latest differently show as two images.
list and get show identity only; an image listed there is neither vetted nor flagged. vulns and sbom show what scanners reported for the image, from the supplychain component. signers shows who signed a digest and trust which ImageTrustPolicies would deny what. See vulns for vulnerabilities across the cluster.

​
images list

Calls GET /images and prints one page, ordered by digest.
RUNNING is the number of workload containers running the digest now. 0 means it is no longer running; the row stays until retention prunes it. When more pages exist, the command prints the --after value for the next page on stderr, so a piped table stays clean.

​
images get

Calls GET /images/{digest} and prints the image and every workload container that runs or ran it, running rows first.
A digest the broker has never seen exits non-zero with image ... is not in the inventory. -o json and -o yaml print the broker’s response unchanged, including fields this CLI version does not know about. Global flags (--kubeconfig, --context, --broker-namespace, --broker-service, --broker-token-file, --debug) are listed in the CLI overview.

​
images vulns

Calls GET /images/{digest}/vulnerabilities: the findings scanners reported for one image, deduplicated across sources, most severe first. Findings come from Trivy Operator reports and, when the opt-in supplychain matcher is enabled, from kguardian’s own Grype matcher, which matches SBOMs.
  • No vulnerability data means no source has reported on the image. That is unknown, not clean.
  • FIXED lists every fixed version the sources give, in source order. None is picked, because text order is not version order.
  • KEV unknown means no source said either way. Trivy never reports KEV, so this is not “not exploited”.
  • JOIN says how the report was matched to what runs: image_id and platform_manifest are exact, workload_tag is by tag only.
  • IN USE and TIER are explained in vulns. unknown is never “not used”, and a KEV finding in a workload with no observed ingress is P0.

​
CI gate: --fail-on

Every result prints a gate: line on stderr, so a pipeline can tell “findings” (1) from “couldn’t check” (2) from “no data” (3). Without --fail-on, errors exit 1 as for any other command. The gate runs its own query, so it sees every page, not only the one printed.

​
images sbom

Calls GET /images/{digest}/sbom. Every source’s SBOM is kept side by side and listed with its trust level, weakest first: The components shown come from one SBOM: --source if given, else Trivy Operator’s, else another scanner’s, and a registry SBOM only when it is the only one.
-o cyclonedx writes the broker’s CycloneDX 1.5 JSON export of that SBOM (GET /images/{digest}/sbom/cyclonedx) to stdout, with the source, join and trust in metadata.properties:
A listed component says nothing about whether it is loaded at runtime.

​
images signers

Calls GET /images/{digest}/attestation: who signed one image digest, as kguardian’s signature discovery found it (needs supplychain.signatureDiscovery.enabled).
Verified is not trusted. Anyone with a Fulcio identity or a key can sign, and anyone who can push to the repository can attach a signature. Whether the signer is one you accept is what an ImageTrustPolicy decides: see images trust.
An unverified signature shows its error and never a signer: an identity it claims is not a fact. Signatures and attestations that verified are listed first. The output below was captured from a local broker. The signature results are real sigstore-go verifications of kguardian’s signing test fixtures, so repositories name a local test registry; the workloads were seeded, and the payments and recs digests are synthetic.
A digest with no result has not been checked:

​
CI gate: images signers --fail-on

Exit code by verdict and level: A pass only says a valid signature exists. To gate on who signed, use images trust --fail-on would-deny with a policy.

​
images trust

Calls GET /image-trust: the evaluator’s ImageTrustPolicy and ClusterImageTrustPolicy results, served by the broker. For every policy and running container it selects: Trusted, WouldDeny or Unknown with the reason, WouldDeny first. Report-only: WouldDeny means an admission controller enforcing the policy would reject the image. kguardian never blocks anything. Unknown can also carry a discovery reason such as registry_auth, or no_signer_identity (the result says verified but names no signer).
The summary line goes to stderr. One workload, and a cut list:

​
CI gate: --fail-on would-deny

The gate reads the counts, which cover every result, so --limit does not hide a WouldDeny. --verdict cannot be combined with --fail-on.

​
images admission-policy

Calls GET /attestations/policy and writes an image signature admission policy generated from the signers kguardian verified on running images (needs supplychain.signatureDiscovery.enabled). Audit is Kyverno validationActions: [Audit] with digest mutation off, or policy-controller mode: warn (it has no audit-only mode). A repository is covered only when every running digest of it verified; the rest are listed in the header as not covered. See ImageTrustPolicy for what is generated. The policy is fetched whole before anything is written, and -f writes a temporary file in the same directory and renames it over the target, so a crash never leaves a partial file. If the broker’s answer is larger than the client reads (10 MiB), nothing is written and the command exits 2 (“could not check”) rather than leaving a cut-off policy.

​
Examples