
container-image
Container image inspection and analysis using skopeo and podman
- version
- 0.0.2
- GitHub stars
- 123
Install
/plugin install container-image@ai-helpersRun it inside Claude Code after adding the marketplace with /plugin marketplace add openshift-eng/ai-helpers.
Contents
Discovered from sourceSkills 1
cve-scan
Multi-source container-image CVE scanner with an AI triage layer. The bundled toolkit in
toolkit/ runs two complementary scanners and merges them; this skill drives
that toolkit and reasons over the merged report — the reasoning is the point, not the
mechanical scan.
Why two sources: no single scanner tells the whole truth about a Red Hat image. Red Hat's security data knows container-level and layered-product CVEs that NVD-driven scanners can't see, and applies backport-aware fix status and Red Hat severities. grype/trivy in turn report CVEs Red Hat has assessed as not-affected/won't-fix. Merging both is the only defensible picture.
Arguments
/container-image:cve-scan [<image>] [--output=triage|remediation|evidence] [--severity=<list>]
<image>(optional) — target image ref (e.g.registry.redhat.io/edo/foo:1.2). If omitted, infer it from the current session (see Phase 0).--output(defaulttriage) — comma-separated list of AI artifacts to produce:triage— prioritized findings + coverage-gap and disagreement analysis.remediation— concrete, grouped remediation steps tied to specific CVEs.evidence— auditable FedRAMP/ConMon narrative citing scanner versions + provenance.
--severity(default: all) — comma-separated severities to focus on (critical,important,moderate,low). Lower severities are still scanned, just not foregrounded in the triage.
Both scanners always run (Red Hat security data and the open-source scanners); there is no source toggle.
Implementation
Operational details (engine selection, build/run commands, auth, caching, exit codes, troubleshooting, JSON shape) live in references/scanning.md — read it before running anything.
The scanner container takes one argument: a skopeo source (docker://…,
docker-archive:…, …) and copies it with skopeo — it cannot see the host engine. Deciding
which skopeo source to pass is the skill's job (Phase 0 → Phase 1).
Phase 0 — Resolve the target reference
- If
<image>was given, use it. - Otherwise infer candidates from the current session, and rank them:
- locally built/tagged images (
podman images/docker images); - image refs in a
Dockerfile,Containerfile, or build command in the working dir; - image refs mentioned earlier in this conversation;
- the repo's component image (git remote → known image name).
- locally built/tagged images (
- Decide:
- exactly one strong candidate → use it, and state which and why;
- multiple candidates → ask the user to pick (use the
AskUserQuestiontool); - none → ask the user for the image ref.
Phase 1 — Pick the engine, detect where the image lives, then scan
Follow references/scanning.md:
- Engine: if only
dockeror onlypodmanis present, use it ($ENGINE); if both are present or it is unclear, ask the user; if neither is installed, stop and tell the user to install one first. Never install a container engine or any scanner on the host. - Build the scanner image with
$ENGINEfrom the bundled toolkit as the build context:${CLAUDE_PLUGIN_ROOT}/skills/cve-scan/toolkit(seetoolkit/). Tag it by the toolkit's content so a plugin upgrade never silently reuses a stale image: derive a short digest of the toolkit directory (e.g.find "$TOOLKIT" -type f | sort | xargs sha256sum | sha256sum | cut -c1-12) and buildcve-scanner:<digest>only when that tag is missing. (cve-scanner:latestis acceptable only if you rebuild whenever the toolkit changes.) - Detect where the reference lives (this is why detection is the skill's job — the
container can't), and build the skopeo source to pass:
- Host-local —
$ENGINE image exists <ref>(podman) /$ENGINE image inspect <ref>(docker) succeeds, i.e. a build that lives only in the host engine (typically an unqualified orlocalhost/…tag). Export it and pass it as an archive:$ENGINE save --format docker-archive -o <tmp>/img.tar <ref>(docker:docker save -o <tmp>/img.tar <ref>), then source =docker-archive:/input/img.tarwith the tar mounted-v <tmp>/img.tar:/input/img.tar:ro,z(the,zSELinux relabel is required). - Registry — a registry-qualified ref not (or not only) local: source =
docker://<ref>. For authenticated registries, mount credentials (next step). - If a registry-qualified ref is also cached in the host engine and the intent is
unclear, ask which to scan (the published image vs the local copy).
3a. Registry credentials (registry sources only). skopeo inside the container can't see
the host's login, so locate the host auth file, in order, and use the first that exists:
$REGISTRY_AUTH_FILE→${XDG_RUNTIME_DIR}/containers/auth.json(podman login) →$HOME/.docker/config.json(docker login) →${XDG_CONFIG_HOME:-$HOME/.config}/containers/auth.json. Copy it into the per-run temp dir (a privatemktemp -d, never relabel the user's live file) and mount the copy-v <tmp>/auth.json:/run/secrets/auth.json:ro,z -e REGISTRY_AUTH_FILE=/run/secrets/auth.json(the,zSELinux relabel is required, as with the local tar). Credential helpers: ifconfig.jsonusescredsStore/credHelpers(the secret is in a keychain, not the file), copying it yields nothing — tell the user topodman login <registry>(writes an inlineauth.json) and use that. If none exists and the scan returnsunauthorized, stop and tell the user to log in first — never prompt for, echo, or store credentials. Public images need none.
- Host-local —
- Run the entrypoint with the chosen skopeo source and
--format json -q, mounting a/cachevolume (plus the tar for a local source, and the auth copy for an authenticated registry). The entrypoint pins a registry tag to its digest once so both scanners scan the identical image. Both scanners run and merge automatically; for a local source the Pyxis catalog cross-check is skipped (no catalog record). Capture the merged JSON and the exit code.
If the build or scan cannot run in this environment, stop and give the user the exact command to run, then offer to triage the JSON they produce.
Phase 2 — AI triage over the merged JSON
Filter findings to --severity (default: all), then produce the requested --output:
triage(default): rank findings by real-world risk, combining Red Hat severity, fix availability (fixed / won't-fix / under-investigation), PROVENANCE/COVERAGE, and Go reachability (govulncheck). Explicitly call out:- Red-Hat-only findings (COVERAGE
script1-only) — only Red Hat's data reported them; NVD scanners did not. This is which source saw it, not where it lives: Script 1 also reports RPM and Go findings, so do not call these "container-level" from coverage alone. True container-level CVEs are the Pyxis-sourced ones — identify them by PROVENANCE (pyxis) / an image-level component, not byscript1-only. - scanner-only findings (COVERAGE
script2-only) — reported only by the open-source scanners, not in the Red Hat errata API. Their severity may come from NVD or a vendor source (e.g. GHSA, or Red Hat via trivy'sSeveritySource) — check the finding'sseverity_sourcerather than assuming NVD; note when Red Hat has assessed them not-affected/won't-fix. - DISAGREE rows — adjudicate using Red Hat as authoritative, showing the scanner's
rating (and its
severity_source) for reference.
- Red-Hat-only findings (COVERAGE
remediation: concrete, grouped next steps tied to specific CVEs — rebuild on a newer base, rebase the affected RPM/source package, backport, or waive-with-justification.evidence: an auditable narrative suitable for FedRAMP/ConMon, citing the pinned scanner versions and scan provenance from the report header.
--output may combine artifacts (e.g. --output=triage,remediation).
Return Value
The requested AI artifact(s), plus a gate decision derived from the scan exit code:
0 clean, 1 Critical/Important present (gate would fail), 2 scan error (nothing usable
ran), 3 incomplete coverage — any of: Red Hat security data degraded, the image rootfs
only partially unpacked, or the OSS scan was requested but could not run or all its scanners
failed. Always state the image scanned, which sources ran, and the gate decision.
Examples
/container-image:cve-scan registry.access.redhat.com/ubi9/ubi-micro:latest
/container-image:cve-scan quay.io/myorg/myapp:tag --output=triage,remediation
/container-image:cve-scan --severity=critical,important # infer image from session
/container-image:cve-scan registry.redhat.io/edo/foo:1.3 --output=evidence
Prerequisites
dockerorpodmanavailable in the session (the skill will not install one).- Network access to Red Hat's security-data APIs and to the target registry; set
REGISTRY_AUTH_FILEfor authenticated registries. - See references/scanning.md and toolkit/README.md.
Sponsors
Details
- Marketplace
- openshift-eng/ai-helpers
- Source
- plugins/container-image
- Category
- Community
More from openshift-eng/ai-helpers
All 56- docv0.0.2
- etcdv0.0.2
- gitv0.0.7
- githubv0.3.0
- golangv0.7.0
- gopls-lspv1.0.0
- gwapiv0.0.1
- hcpv0.0.3
- hello-worldv1.0.3
- jirav0.9.8
- lvmsv0.1.1
- marketplace-opsv0.1.2
- metricsv0.3.0
- must-gatherv0.0.3
- native-notificationsv0.0.2
- nid-teamv0.2.2
- nodev0.0.3
- node-bugv0.0.3
- node-cvev0.0.8
- node-onboardingv0.0.3
- node-rpmv0.0.3
- node-teamv1.0.1
- node-tuningv1.0.1
- olmv0.1.3